2 files changed, 26 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index af9aa2919e9..6c945dd244e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2013-06-17  Lars Magne Ingebrigtsen  <larsi@gnus.org>
+
+        * text.texi (Changing Properties): Document `add-face-text-property'.
+
 2013-06-17  Kenichi Handa  <handa@gnu.org>
 
         * display.texi (Face Attributes): Refer to "Low-Level font" (not
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6d5a39d887a..fdfc16f3f64 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2805,6 +2805,28 @@ from the specified range of text.  Here's an example:
 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:
+
+@example
+(add-face-text-property @var{start} @var{end} 'italic)
+(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00"))
+@end example
+
+The attribute is (by default) prepended to the list of face
+attributes, and the first attribute of the same type takes
+presedence.  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.
+
+@end defun
+
   The easiest way to make a string with text properties
 is with @code{propertize}: