[Emacs-diffs] trunk r115628: Add/fix docs for add-face-text-property

[Chong Yidong]

------------------------------------------------------------
revno: 115628
revision-id: address@hidden
parent: address@hidden
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2013-12-20 15:12:04 +0800
message:
  Add/fix docs for add-face-text-property
  
  * doc/lispref/text.texi (Changing Properties): Improve documentation for
  add-face-text-property.
  (Special Properties): Mention add-face-text-property.
  
  * src/textprop.c (Fadd_face_text_property): Doc fix.  Rename `appendp'
  argument to `append'.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/text.texi          text.texi-20091113204419-o5vbwnq5f7feedwu-6215
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/textprop.c                 textprop.c-20091113204419-o5vbwnq5f7feedwu-512

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2013-12-18 14:54:24 +0000
+++ b/doc/lispref/ChangeLog     2013-12-20 07:12:04 +0000
@@ -1,3 +1,9 @@
+2013-12-20  Chong Yidong  <address@hidden>
+
+       * text.texi (Changing Properties): Improve documentation for
+       add-face-text-property.
+       (Special Properties): Mention add-face-text-property.
+
 2013-12-18  Chong Yidong  <address@hidden>
 
        * customize.texi (Custom Themes): Document custom-known-themes

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2013-09-13 08:26:03 +0000
+++ b/doc/lispref/text.texi     2013-12-20 07:12:04 +0000
@@ -2825,29 +2825,37 @@
 @end defun
 
 @defun add-face-text-property start end face &optional appendp object
address@hidden text attributes can be combined.  If you want to make a
-section both italic and green, you can either define a new face that
-have those attributes, or you can add both these attributes separately
-to text:
+This function acts on the text between @var{start} and @var{end},
+adding the face @var{face} to the @code{face} text property.
address@hidden should be a valid value for the @code{face} property
+(@pxref{Special Properties}), such as a face name or an anonymous face
+(@pxref{Faces}).
+
+If any text in the region already has a non-nil @code{face} property,
+those face(s) are retained.  This function sets the @code{face}
+property to a list of faces, with @var{face} as the first element (by
+default) and the pre-existing faces as the remaining elements.  If the
+optional argument @var{append} is address@hidden, @var{face} is
+appended to the end of the list instead.  Note that in a face list,
+the first occurring value for each attribute takes precedence.
+
+For example, the following code would assign a italicized green face
+to the text between @var{start} and @var{end}:
 
 @example
 (add-face-text-property @var{start} @var{end} 'italic)
-(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00"))
+(add-face-text-property @var{start} @var{end} '(:foreground "red"))
+(add-face-text-property @var{start} @var{end} '(:foreground "green"))
 @end example
 
-The attribute is (by default) prepended to the list of face
-attributes, and the first attribute of the same type takes
-precedence.  So if you have two @code{:foreground} specifications, the
-first one will take effect.
-
-If you pass in @var{appendp}, the attribute will be appended instead
-of prepended, which means that it will have no effect if there is
-already an attribute of the same type.
-
+The optional argument @var{object}, if address@hidden, specifies a
+buffer or string to act on, rather than the current buffer.  If
address@hidden is a string, then @var{start} and @var{end} are
+zero-based indices into the string.
 @end defun
 
-  The easiest way to make a string with text properties
-is with @code{propertize}:
+  The easiest way to make a string with text properties is with
address@hidden:
 
 @defun propertize string &rest properties
 This function returns a copy of @var{string} which has the text
@@ -3081,6 +3089,9 @@
 dynamically updating the @code{face} property of characters based on
 the context.
 
+The @code{add-face-text-property} function provides a convenient way
+to set this text property.  @xref{Changing Properties}.
+
 @item font-lock-face
 @kindex font-lock-face @r{(text property)}
 This property specifies a value for the @code{face} property that Font

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2013-12-20 05:20:33 +0000
+++ b/etc/NEWS  2013-12-20 07:12:04 +0000
@@ -164,6 +164,7 @@
 using the scroll bar (i.e. dragging the thumb down even when the end
 of the buffer is visible).
 
++++
 ** New function `add-face-text-property' has been added, which can be
 used to conveniently prepend/append new face attributes to text.
 

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2013-12-19 19:06:53 +0000
+++ b/src/ChangeLog     2013-12-20 07:12:04 +0000
@@ -1,3 +1,8 @@
+2013-12-20  Chong Yidong  <address@hidden>
+
+       * textprop.c (Fadd_face_text_property): Doc fix.  Rename `appendp'
+       argument to `append'.
+
 2013-12-19  Eli Zaretskii  <address@hidden>
 
        * xdisp.c (extend_face_to_end_of_line): Use default face, not the

=== modified file 'src/textprop.c'
--- a/src/textprop.c    2013-11-25 17:30:09 +0000
+++ b/src/textprop.c    2013-12-20 07:12:04 +0000
@@ -1338,20 +1338,27 @@
 DEFUN ("add-face-text-property", Fadd_face_text_property,
        Sadd_face_text_property, 3, 5, 0,
        doc: /* Add the face property to the text from START to END.
-The third argument FACE specifies the face to add.
-If any text in the region already has any face properties, this new
-face property will be added to the front of the face property list.
-If the optional fourth argument APPENDP is non-nil, append to the end
-of the face property list instead.
-If the optional fifth argument OBJECT is a buffer (or nil, which means
-the current buffer), START and END are buffer positions (integers or
+FACE specifies the face to add.  It should be a valid value of the
+`face' property (typically a face name or a plist of face attributes
+and values).
+
+If any text in the region already has a non-nil `face' property, those
+face(s) are retained.  This is done by setting the `face' property to
+a list of faces, with FACE as the first element (by default) and the
+pre-existing faces as the remaining elements.
+
+If optional fourth argument APPEND is non-nil, append FACE to the end
+of the face list instead.
+
+If optional fifth argument OBJECT is a buffer (or nil, which means the
+current buffer), START and END are buffer positions (integers or
 markers).  If OBJECT is a string, START and END are 0-based indices
 into it.  */)
   (Lisp_Object start, Lisp_Object end, Lisp_Object face,
-   Lisp_Object appendp, Lisp_Object object)
+   Lisp_Object append, Lisp_Object object)
 {
   add_text_properties_1 (start, end, list2 (Qface, face), object,
-                        (NILP (appendp)
+                        (NILP (append)
                          ? TEXT_PROPERTY_PREPEND
                          : TEXT_PROPERTY_APPEND));
   return Qnil;