merge from trunk

this merges frmo trunk and fixes various build issues.
this needed a few ugly tweaks.
this hangs in "make check" now

18 files changed, 210 insertions, 83 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 259bf9a78a6..e4bc6eb5bcc 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,81 @@
+2013-07-06  Eli Zaretskii  <eliz@gnu.org>
+
+        * nonascii.texi (Text Representations): Document that
+        multibyte-string-p returns nil for non-string objects.
+
+2013-07-06  Glenn Morris  <rgm@gnu.org>
+
+        * elisp.texi (Top): Move WWW_GNU_ORG section outside @copying.
+
+2013-07-03  Glenn Morris  <rgm@gnu.org>
+
+        * debugging.texi (Debugging):
+        * files.texi (File Attributes, Changing Files): Fix cross-references.
+
+        * package.texi (Package Archives): Fix @url call.
+
+        * syntax.texi (Syntax Table Functions): Mention describe-syntax.
+
+2013-06-29  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Bidirectional Display): Document move-point-visually.
+
+2013-06-29  Xue Fuqiao  <xfq.free@gmail.com>
+
+        * buffers.texi (Buffer File Name): Fix typo.
+
+2013-06-26  Christopher Schmidt  <christopher@ch.ristopher.com>
+
+        * tips.texi (Coding Conventions): Improve wording.
+
+2013-06-24  Glenn Morris  <rgm@gnu.org>
+
+        * loading.texi (Autoload): Fix typo.
+
+        * variables.texi (Lexical Binding): Fix typo.
+
+        * functions.texi (Anonymous Functions): Put back ' removed 2012-10-23.
+
+2013-06-23  Lars Magne Ingebrigtsen  <larsi@gnus.org>
+
+        * display.texi (ImageMagick Images): Mention :max-width and
+        :max-height.
+
+2013-06-20  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * numbers.texi (Math Functions): Remove obsolete function log10.
+
+2013-06-19  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * modes.texi (Mode Line Data, Properties in Mode): Advertise `keymap'
+        rather than `local-map'.
+
+        * keymaps.texi (Active Keymaps): Fix documentation of
+        set-temporary-overlay-map and overriding-terminal-local-map.
+
+2013-06-19  Glenn Morris  <rgm@gnu.org>
+
+        * Makefile.in (dist): Edit more configure variables.
+        Try to check that we do not miss any in future.
+
+2013-06-17  Juanma Barranquero  <lekktu@gmail.com>
+
+        * text.texi (Undo, Changing Properties): Fix typos.
+
+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
+        "Font Selection") in the explanation of :font attribute (bug#14629).
+
+2013-06-13  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * loading.texi (Hooks for Loading): Don't document after-load-alist.
+        Document with-eval-after-load instead of eval-after-load.
+
 2013-06-11  Xue Fuqiao  <xfq.free@gmail.com>
 
         * files.texi (File Name Expansion): Make the example more
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 006c09d780c..c548b67d4ca 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -19,6 +19,9 @@
 
 SHELL = /bin/sh
 
+# NB If you add any more configure variables,
+# update the sed rules in the dist target below.
+
 # Standard configure variables.
 srcdir = @srcdir@
 
@@ -164,7 +167,12 @@ dist:
           -e 's/^\(buildinfodir *=\).*/\1 ./' \
           -e 's/^\(clean:.*\)/\1 infoclean/' \
           -e "s/@ver[s]ion@/${version}/" \
+          -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \
+          -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \
           ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile
+        @if grep '@[a-zA-Z_]*@' emacs-lispref-${version}/Makefile; then \
+          echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \
+        fi
         tar -cf emacs-lispref-${version}.tar emacs-lispref-${version}
         rm -rf emacs-lispref-${version}
 
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 7ed1876e4b1..01269851250 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -488,8 +488,9 @@ Normally, this function asks the user for confirmation if there
 already is a buffer visiting @var{filename}.  If @var{no-query} is
 non-@code{nil}, that prevents asking this question.  If there already
 is a buffer visiting @var{filename}, and the user confirms or
-@var{query} is non-@code{nil}, this function makes the new buffer name
-unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
+@var{no-query} is non-@code{nil}, this function makes the new
+buffer name unique by appending a number inside of @samp{<@dots{}>} to
+@var{filename}.
 
 If @var{along-with-file} is non-@code{nil}, that means to assume that
 the former visited file has been renamed to @var{filename}.  In this
@@ -1064,7 +1065,7 @@ Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
 @end deffn
 
 @defvar kill-buffer-query-functions
-After confirming unsaved changes, @code{kill-buffer} calls the functions
+Before confirming unsaved changes, @code{kill-buffer} calls the functions
 in the list @code{kill-buffer-query-functions}, in order of appearance,
 with no arguments.  The buffer being killed is the current buffer when
 they are called.  The idea of this feature is that these functions will
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 24629465525..335e3f802d2 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -32,7 +32,7 @@ program.
 
 @item
 You can use the ERT package to write regression tests for the program.
-@xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
+@xref{Top,the ERT manual,, ert, ERT: Emacs Lisp Regression Testing}.
 
 @item
 You can profile the program to get hints about how to make it more efficient.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4adcfdf8f4f..44fbc66a60e 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1655,26 +1655,26 @@ if it becomes empty (i.e., if its length becomes zero).  If you give
 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
 it immediately.
 
-@item local-map
-@cindex keymap of character (and overlays)
-@kindex local-map @r{(overlay property)}
-If this property is non-@code{nil}, it specifies a keymap for a portion
-of the text.  The property's value replaces the buffer's local map, when
-the character after point is within the overlay.  @xref{Active Keymaps}.
-
 @item keymap
+@cindex keymap of character (and overlays)
 @kindex keymap @r{(overlay property)}
-The @code{keymap} property is similar to @code{local-map} but overrides the
-buffer's local map (and the map specified by the @code{local-map}
-property) rather than replacing it.
+If this property is non-@code{nil}, it specifies a keymap for a portion of the
+text.  This keymap is used when the character after point is within the
+overlay, and takes precedence over most other keymaps.  @xref{Active Keymaps}.
+
+@item local-map
+@kindex local-map @r{(overlay property)}
+The @code{local-map} property is similar to @code{keymap} but replaces the
+buffer's local map rather than augmenting existing keymaps.  This also means it
+has lower precedence than minor mode keymaps.
 @end table
 
-The @code{local-map} and @code{keymap} properties do not affect a
+The @code{keymap} and @code{local-map} properties do not affect a
 string displayed by the @code{before-string}, @code{after-string}, or
 @code{display} properties.  This is only relevant for mouse clicks and
 other mouse events that fall on the string, since point is never on
 the string.  To bind special mouse events for the string, assign it a
-@code{local-map} or @code{keymap} text property.  @xref{Special
+@code{keymap} or @code{local-map} text property.  @xref{Special
 Properties}.
 
 @node Finding Overlays
@@ -2126,7 +2126,8 @@ used automatically to handle certain shades of gray.
 
 @item :font
 The font used to display the face.  Its value should be a font object.
-@xref{Font Selection}, for information about font objects.
+@xref{Low-Level Font}, for information about font objects, font specs,
+and font entities.
 
 When specifying this attribute using @code{set-face-attribute}
 (@pxref{Attribute Functions}), you may also supply a font spec, a font
@@ -3260,7 +3261,9 @@ to @var{value}.
 properties are intermediate between a font object and a font spec:
 like a font object, and unlike a font spec, it refers to a single,
 specific font.  Unlike a font object, creating a font entity does not
-load the contents of that font into computer memory.
+load the contents of that font into computer memory.  Emacs may open
+multiple font objects of different sizes from a single font entity
+referring to a scalable font.
 
 @defun find-font font-spec &optional frame
 This function returns a font entity that best matches the font spec
@@ -4650,6 +4653,15 @@ image.  If only one of them is specified, the other one will be
 calculated so as to preserve the aspect ratio.  If both are specified,
 aspect ratio may not be preserved.
 
+@item :max-width, :max-height
+The @code{:max-width} and @code{:max-height} keywords are used for
+scaling if the size of the image of the image exceeds these values.
+If @code{:width} is set it will have precedence over @code{max-width},
+and if @code{:height} is set it will have precedence over
+@code{max-height}, but you can otherwise mix these keywords as you
+wish.  @code{:max-width} and @code{:max-height} will always preserve
+the aspect ratio.
+
 @item :rotation
 Specifies a rotation angle in degrees.
 
@@ -6419,6 +6431,26 @@ determined dynamically by Emacs.  For buffers whose value of
 buffers, this function always returns @code{left-to-right}.
 @end defun
 
+@cindex visual-order cursor motion
+  Sometimes there's a need to move point in strict visual order,
+either to the left or to the right of its current screen position.
+Emacs provides a primitive to do that.
+
+@defun move-point-visually direction
+This function moves point of the currently selected window to the
+buffer position that appears immediately to the right or to the left
+of point on the screen.  If @var{direction} is positive, point will
+move one screen position to the right, otherwise it will move one
+screen position to the left.  Note that, depending on the surrounding
+bidirectional context, this could potentially move point many buffer
+positions away.  If invoked at the end of a screen line, the function
+moves point to the rightmost or leftmost screen position of the next
+or previous screen line, as appropriate for the value of
+@var{direction}.
+
+The function returns the new buffer position as its value.
+@end defun
+
 @cindex layout on display, and bidirectional text
 @cindex jumbled display of bidirectional text
 @cindex concatenating bidirectional strings
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 343d9cc98e2..0d9432d5e01 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -97,16 +97,6 @@ This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@*
 This is the @cite{GNU Emacs Lisp Reference Manual}
 @end ifnottex
 corresponding to Emacs version @value{EMACSVER}.
-@ifset WWW_GNU_ORG
-@html
-<p>The homepage for GNU Emacs is at
-<a href="/software/emacs/">http://www.gnu.org/software/emacs/</a>.<br>
-For information on using Emacs, refer to
-the <a href="/software/emacs/manual/html_node/emacs/index.html">Emacs
-Manual</a>.<br>  To view this manual in other formats,
-click <a href="/software/emacs/manual/elisp.html">here</a>.
-@end html
-@end ifset
 
 Copyright @copyright{} 1990--1996, 1998--2013 Free Software Foundation, Inc.
 
@@ -167,6 +157,17 @@ Cover art by Etienne Suvasa.
 @node Top
 @top Emacs Lisp
 
+@ifset WWW_GNU_ORG
+@html
+<p>The homepage for GNU Emacs is at
+<a href="/software/emacs/">http://www.gnu.org/software/emacs/</a>.<br>
+For information on using Emacs, refer to the
+<a href="/software/emacs/manual/emacs.html">Emacs Manual</a>.<br>
+To view this manual in other formats, click
+<a href="/software/emacs/manual/elisp.html">here</a>.
+@end html
+@end ifset
+
 @insertcopying
 @end ifnottex
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 704ecfb6446..951d55ac90f 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1115,7 +1115,7 @@ permissions} of @var{filename}, as an integer.  It recursively follows
 symbolic links in @var{filename} at all levels.  If @var{filename}
 does not exist, the return value is @code{nil}.
 
-@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
 Manual}, for a description of mode bits.  If the low-order bit is 1,
 then the file is executable by all users, if the second-lowest-order
 bit is 1, then the file is writable by all users, etc.  The highest
@@ -1625,7 +1625,7 @@ octal numbers to enter @var{mode}.  For example,
 @noindent
 specifies that the file should be readable and writable for its owner,
 readable for group members, and readable for all other users.
-@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
 Manual}, for a description of mode bit specifications.
 
 Interactively, @var{mode} is read from the minibuffer using
@@ -1676,7 +1676,7 @@ the permissions on which the specification is based are taken from the
 mode bits of @var{base-file}.  If @var{base-file} is omitted or
 @code{nil}, the function uses @code{0} as the base mode bits.  The
 complete and relative specifications can be combined, as in
-@code{"u+r,g+rx,o+r,g-w"}.  @xref{File Permissions,,, coreutils, The
+@code{"u+r,g+rx,o+r,g-w"}.  @xref{File permissions,,, coreutils, The
 @sc{gnu} @code{Coreutils} Manual}, for a description of file mode
 specifications.
 @end defun
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 7768c147827..fcd345ef83b 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -974,10 +974,11 @@ Note that we do not quote the @code{lambda} form.
 compiled.  This would not happen if, say, you had constructed the
 anonymous function by quoting it as a list:
 
+@c Do not unquote this lambda!
 @example
 @group
 (defun double-property (symbol prop)
-  (change-property symbol prop (lambda (x) (* 2 x))))
+  (change-property symbol prop '(lambda (x) (* 2 x))))
 @end group
 @end example
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 822e952ef98..ef020364082 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -663,17 +663,16 @@ additional active keymaps through the variable
 
   The highest precedence normal keymap comes from the @code{keymap}
 text or overlay property.  If that is non-@code{nil}, it is the first
-keymap to be processed, in normal circumstances.  Next comes
-any keymap added by the function @code{set-temporary-overlay-map}.
-@xref{Controlling Active Maps}.
+keymap to be processed, in normal circumstances.
 
   However, there are also special ways for programs to substitute
 other keymaps for some of those.  The variable
 @code{overriding-local-map}, if non-@code{nil}, specifies a keymap
 that replaces all the usual active keymaps except the global keymap.
-Another way to do this is with @code{overriding-terminal-local-map};
-it operates on a per-terminal basis.  These variables are documented
-below.
+
+The very highest precedence keymap comes from
+@code{overriding-terminal-local-map}; it operates on a per-terminal basis and
+is normally used for modal/transient keybindings.
 
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 5c92307f7d5..dab8e8d1255 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -461,7 +461,7 @@ and calls @code{define-key}; not even if the variable name is the same
 symbol @var{function}.
 
 @cindex function cell in autoload
-if @var{function} already has non-void function definition that is not
+If @var{function} already has a non-void function definition that is not
 an autoload object, this function does nothing and returns @code{nil}.
 Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
 and stores it as the function definition for @var{function}.  The
@@ -990,19 +990,18 @@ file that was just loaded.
 @end defvar
 
 If you want code to be executed when a @emph{particular} library is
-loaded, use the function @code{eval-after-load}:
+loaded, use the macro @code{with-eval-after-load}:
 
-@defun eval-after-load library form
-This function arranges to evaluate @var{form} at the end of loading
+@defmac with-eval-after-load library body@dots{}
+This macro arranges to evaluate @var{body} at the end of loading
 the file @var{library}, each time @var{library} is loaded.  If
-@var{library} is already loaded, it evaluates @var{form} right away.
-Don't forget to quote @var{form}!
+@var{library} is already loaded, it evaluates @var{body} right away.
 
 You don't need to give a directory or extension in the file name
 @var{library}.  Normally, you just give a bare file name, like this:
 
 @example
-(eval-after-load "edebug" '(def-edebug-spec c-point t))
+(with-eval-after-load "edebug" (def-edebug-spec c-point t))
 @end example
 
 To restrict which files can trigger the evaluation, include a
@@ -1014,16 +1013,16 @@ example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
 @file{my_inst.el}:
 
 @example
-(eval-after-load "foo/bar/my_inst.elc" @dots{})
+(with-eval-after-load "foo/bar/my_inst.elc" @dots{})
 @end example
 
 @var{library} can also be a feature (i.e., a symbol), in which case
-@var{form} is evaluated at the end of any file where
+@var{body} is evaluated at the end of any file where
 @code{(provide @var{library})} is called.
 
-An error in @var{form} does not undo the load, but does prevent
-execution of the rest of @var{form}.
-@end defun
+An error in @var{body} does not undo the load, but does prevent
+execution of the rest of @var{body}.
+@end defmac
 
 Normally, well-designed Lisp programs should not use
 @code{eval-after-load}.  If you need to examine and set the variables
@@ -1031,18 +1030,3 @@ defined in another library (those meant for outside use), you can do
 it immediately---there is no need to wait until the library is loaded.
 If you need to call functions defined by that library, you should load
 the library, preferably with @code{require} (@pxref{Named Features}).
-
-@defvar after-load-alist
-This variable stores an alist built by @code{eval-after-load},
-containing the expressions to evaluate when certain libraries are
-loaded.  Each element looks like this:
-
-@example
-(@var{regexp-or-feature} @var{forms}@dots{})
-@end example
-
-The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms.  The forms are evaluated
-when the key matches the absolute true name or feature name of the
-library being loaded.
-@end defvar
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 7d42d2591d6..59729380ea7 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1800,7 +1800,7 @@ display of the text just as they would text in the buffer.  Any
 characters which have no @code{face} properties are displayed, by
 default, in the face @code{mode-line} or @code{mode-line-inactive}
 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).  The
-@code{help-echo} and @code{local-map} properties in @var{string} have
+@code{help-echo} and @code{keymap} properties in @var{string} have
 special meanings.  @xref{Properties in Mode}.
 
 @item @var{symbol}
@@ -2205,7 +2205,7 @@ The value of @code{global-mode-string}.
   Certain text properties are meaningful in the
 mode line.  The @code{face} property affects the appearance of text; the
 @code{help-echo} property associates help strings with the text, and
-@code{local-map} can make the text mouse-sensitive.
+@code{keymap} can make the text mouse-sensitive.
 
   There are four ways to specify text properties for text in the mode
 line:
@@ -2229,7 +2229,7 @@ structure, and make @var{form} evaluate to a string that has a text
 property.
 @end enumerate
 
-  You can use the @code{local-map} property to specify a keymap.  This
+  You can use the @code{keymap} property to specify a keymap.  This
 keymap only takes real effect for mouse clicks; binding character keys
 and function keys to it has no effect, since it is impossible to move
 point into the mode line.
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index e462c3b4ce4..b8b62325bb4 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -124,7 +124,8 @@ belong to the same character.
 
 @defun multibyte-string-p string
 Return @code{t} if @var{string} is a multibyte string, @code{nil}
-otherwise.
+otherwise.  This function also returns @code{nil} if @var{string} is
+some object other than a string.
 @end defun
 
 @defun string-bytes string
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index eeebac6bf72..2b6f31b670b 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -1156,11 +1156,6 @@ This function returns the logarithm of @var{arg}, with base
 returns a NaN.
 @end defun
 
-@defun log10 arg
-This function returns the logarithm of @var{arg}, with base 10:
-@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}.
-@end defun
-
 @defun expt x y
 This function returns @var{x} raised to power @var{y}.  If both
 arguments are integers and @var{y} is positive, the result is an
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index ad9f4fc1aea..f4d6b590c77 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -265,7 +265,7 @@ variable @code{load-file-name} (@pxref{Loading}).  Here is an example:
   Via the Package Menu, users may download packages from @dfn{package
 archives}.  Such archives are specified by the variable
 @code{package-archives}, whose default value contains a single entry:
-the archive hosted by the GNU project at @url{elpa.gnu.org}.  This
+the archive hosted by the GNU project at @url{http://elpa.gnu.org}.  This
 section describes how to set up and maintain a package archive.
 
 @cindex base location, package archive
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index dfa121103bc..6bbd7a3a7b7 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -506,6 +506,11 @@ This function returns the current syntax table, which is the table for
 the current buffer.
 @end defun
 
+@deffn Command describe-syntax &optional buffer
+This command displays the contents of the syntax table of
+@var{buffer} (by default, the current buffer) in a help buffer.
+@end deffn
+
 @defmac with-syntax-table table body@dots{}
 This macro executes @var{body} using @var{table} as the current syntax
 table.  It returns the value of the last form in @var{body}, after
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6d5a39d887a..c10458b39ae 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1226,7 +1226,7 @@ list, which is in the variable @code{buffer-undo-list}.
 
 @defvar buffer-undo-list
 This buffer-local variable's value is the undo list of the current
-buffer. A value of @code{t} disables the recording of undo information.
+buffer.  A value of @code{t} disables the recording of undo information.
 @end defvar
 
 Here are the kinds of elements an undo list can have:
@@ -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
+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.
+
+@end defun
+
   The easiest way to make a string with text properties
 is with @code{propertize}:
 
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index c40ae408f7f..2e3760e573e 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -54,12 +54,12 @@ You should choose a short word to distinguish your program from other
 Lisp programs.  The names of all global symbols in your program, that
 is the names of variables, constants, and functions, should begin with
 that chosen prefix.  Separate the prefix from the rest of the name
-with a hyphen, @samp{-}.  Use two hyphens if the symbol is not meant
-to be used by other packages.  This practice helps avoid name
-conflicts, since all global variables in Emacs Lisp share the same
-name space, and all functions share another name space@footnote{The
-benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}.
+with a hyphen, @samp{-}.  This practice helps avoid name conflicts,
+since all global variables in Emacs Lisp share the same name space,
+and all functions share another name space@footnote{The benefits of a
+Common Lisp-style package system are considered not to outweigh the
+costs.}.  Use two hyphens to separate prefix and name if the symbol is
+not meant to be used by other packages.
 
 Occasionally, for a command name intended for users to use, it is more
 convenient if some words come before the package's name prefix.  And
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 4bcf7985f0c..4a38fa9ccd5 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -988,7 +988,7 @@ Here is an example:
   (setq my-ticker (lambda ()
                     (setq x (1+ x)))))
     @result{} (closure ((x . 0) t) ()
-          (1+ x))
+          (setq x (1+ x)))
 
 (funcall my-ticker)
     @result{} 1