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'.

5 files changed, 55 insertions, 25 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index af09f4371f9..3ae7e0040cc 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2013-12-20  Chong Yidong  <cyd@gnu.org>
+
+        * text.texi (Changing Properties): Improve documentation for
+        add-face-text-property.
+        (Special Properties): Mention add-face-text-property.
+
 2013-12-18  Chong Yidong  <cyd@gnu.org>
 
         * customize.texi (Custom Themes): Document custom-known-themes
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index aa19338ddaf..b814d553296 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2825,29 +2825,37 @@ Do not rely on the return value of this function.
 @end defun
 
 @defun add-face-text-property start end face &optional appendp object
-@code{face} 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.
+@var{face} 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 non-@code{nil}, @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 non-@code{nil}, specifies a
+buffer or string to act on, rather than the current buffer.  If
+@var{object} 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
+@code{propertize}:
 
 @defun propertize string &rest properties
 This function returns a copy of @var{string} which has the text
@@ -3081,6 +3089,9 @@ Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
 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
diff --git a/etc/NEWS b/etc/NEWS
index 9177cec64a7..58cc6c61344 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -164,6 +164,7 @@ Available only on X, this option allows to control over-scrolling
 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.
 
diff --git a/src/ChangeLog b/src/ChangeLog
index 74ae25327ab..23857e33a6d 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2013-12-20  Chong Yidong  <cyd@gnu.org>
+
+        * textprop.c (Fadd_face_text_property): Doc fix.  Rename `appendp'
+        argument to `append'.
+
 2013-12-19  Eli Zaretskii  <eliz@gnu.org>
 
         * xdisp.c (extend_face_to_end_of_line): Use default face, not the
diff --git a/src/textprop.c b/src/textprop.c
index 5597a781a61..d5f86922ade 100644
--- a/src/textprop.c
+++ b/src/textprop.c
@@ -1338,20 +1338,27 @@ the designated part of OBJECT.  */)
 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;