Merge from emacs-24; up to 2012-12-06T01:39:03Z!monnier@iro.umontreal.ca

[bpt/emacs.git] / doc / lispref / help.texi

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 5dd8f3c..9fe069b 100644 (file)
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node Documentation
 @chapter Documentation
@@ -58,11 +58,17 @@ use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
 are many other conventions for documentation strings; see
 @ref{Documentation Tips}.
 
-  Documentation strings can contain several special substrings, which
-stand for key bindings to be looked up in the current keymaps when the
-documentation is displayed.  This allows documentation strings to refer
-to the keys for related commands and be accurate even when a user
-rearranges the key bindings.  (@xref{Keys in Documentation}.)
+  Documentation strings can contain several special text sequences,
+referring to key bindings which are looked up in the current keymaps
+when the user views the documentation.  This allows the help commands
+to display the correct keys even if a user rearranges the default key
+bindings.  @xref{Keys in Documentation}.
+
+  In the documentation string of an autoloaded command
+(@pxref{Autoload}), these special text sequences have an additional
+special effect: they cause @kbd{C-h f} (@code{describe-function}) on
+the command to trigger autoloading.  (This is needed for correctly
+setting up the hyperlinks in the @file{*Help*} buffer).
 
 @vindex emacs-lisp-docstring-fill-column
   Emacs Lisp mode fills documentation strings to the width
@@ -442,7 +448,7 @@ This function returns a string describing @var{event} in the standard
 Emacs notation for keyboard input.  A normal printing character
 appears as itself, but a control character turns into a string
 starting with @samp{C-}, a meta character turns into a string starting
-with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+with @samp{M-}, and space, tab, etc., appear as @samp{SPC},
 @samp{TAB}, etc.  A function key symbol appears inside angle brackets
 @samp{<@dots{}>}.  An event that is a list appears as the name of the
 symbol in the @sc{car} of the list, inside angle brackets.
@@ -722,4 +728,3 @@ If this variable is non-@code{nil}, commands defined with
 echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt
-