[Emacs-diffs] /srv/bzr/emacs/trunk r107333: Updates to Documentation chapter of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107333
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-02-19 13:54:33 +0800
message:
  Updates to Documentation chapter of Lisp manual.
  
  * doc/lispref/help.texi (Documentation, Documentation Basics, Help Functions):
  Minor clarifications.
  (Accessing Documentation): Clarify what documentation-property is
  for.  Add xref to Keys in Documentation.
  
  * doc/lispref/macros.texi (Defining Macros):
  * doc/lispref/modes.texi (Derived Modes): Say "documentation string" instead
  of docstring.
  
  * doc/lispref/tips.texi (Documentation Tips): Don't recommend using * in
  docstrings.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/help.texi
  doc/lispref/macros.texi
  doc/lispref/modes.texi
  doc/lispref/tips.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-19 03:39:04 +0000
+++ b/admin/FOR-RELEASE 2012-02-19 05:54:33 +0000
@@ -197,7 +197,7 @@
 frames.texi       
 functions.texi    cyd
 hash.texi         cyd
-help.texi         
+help.texi         cyd
 hooks.texi        
 index.texi
 internals.texi    
@@ -210,7 +210,7 @@
 maps.texi         
 markers.texi      
 minibuf.texi      
-modes.texi        
+modes.texi        cyd
 nonascii.texi     
 numbers.texi      cyd
 objects.texi      cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-18 13:38:33 +0000
+++ b/doc/lispref/ChangeLog     2012-02-19 05:54:33 +0000
@@ -1,3 +1,17 @@
+2012-02-19  Chong Yidong  <address@hidden>
+
+       * help.texi (Documentation, Documentation Basics, Help Functions):
+       Minor clarifications.
+       (Accessing Documentation): Clarify what documentation-property is
+       for.  Add xref to Keys in Documentation.
+
+       * tips.texi (Documentation Tips): Don't recommend using * in
+       docstrings.
+
+       * macros.texi (Defining Macros):
+       * modes.texi (Derived Modes): Say "documentation string" instead
+       of docstring.
+
 2012-02-18  Chong Yidong  <address@hidden>
 
        * modes.texi (Tabulated List Mode): New node.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-02-18 13:38:33 +0000
+++ b/doc/lispref/elisp.texi    2012-02-19 05:54:33 +0000
@@ -827,8 +827,7 @@
 
 Documentation
 
-* Documentation Basics::    Good style for doc strings.
-                              Where to put them.  How Emacs stores them.
+* Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
 * Describing Characters::   Making printable descriptions of

=== modified file 'doc/lispref/help.texi'
--- a/doc/lispref/help.texi     2012-02-02 07:06:37 +0000
+++ b/doc/lispref/help.texi     2012-02-19 05:54:33 +0000
@@ -8,11 +8,11 @@
 @chapter Documentation
 @cindex documentation strings
 
-  GNU Emacs Lisp has convenient on-line help facilities, most of which
-derive their information from the documentation strings associated with
-functions and variables.  This chapter describes how to write good
-documentation strings for your Lisp programs, as well as how to write
-programs to access documentation.
+  GNU Emacs has convenient built-in help facilities, most of which
+derive their information from documentation strings associated with
+functions and variables.  This chapter describes how to access
+documentation strings in Lisp programs.  @xref{Documentation Tips},
+for how to write good documentation strings.
 
   Note that the documentation strings for Emacs are not the same thing
 as the Emacs manual.  Manuals have their own source files, written in
@@ -23,12 +23,10 @@
 topics of discussion.
 
   For commands to display documentation strings, see @ref{Help, ,
-Help, emacs, The GNU Emacs Manual}.  For the conventions for writing
-documentation strings, see @ref{Documentation Tips}.
+Help, emacs, The GNU Emacs Manual}.
 
 @menu
-* Documentation Basics::      Good style for doc strings.
-                                Where to put them.  How Emacs stores them.
+* Documentation Basics::      Where doc strings are defined and stored.
 * Accessing Documentation::   How Lisp programs can access doc strings.
 * Keys in Documentation::     Substituting current key bindings.
 * Describing Characters::     Making printable descriptions of
@@ -52,14 +50,15 @@
 documentation string follows the initial value of the variable.
 
   When you write a documentation string, make the first line a
-complete sentence (or two complete sentences) since some commands,
-such as @code{apropos}, show only the first line of a multi-line
-documentation string.  Also, you should not indent the second line of
-a documentation string, if it has one, because that looks odd when you
+complete sentence (or two complete sentences) that briefly describes
+what the function or variable does.  Some commands, such as
address@hidden, show only the first line of a multi-line documentation
+string.  Also, you should not indent the second line of a
+documentation string, if it has one, because that looks odd when you
 use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
 (@code{describe-variable}) to view the documentation string.  There
-are many other conventions for doc strings; see @ref{Documentation
-Tips}.
+are many other conventions for documentation strings; see
address@hidden Tips}.
 
   Documentation strings can contain several special substrings, which
 stand for key bindings to be looked up in the current keymaps when the
@@ -71,55 +70,67 @@
   Emacs Lisp mode fills documentation strings to the width
 specified by @code{emacs-lisp-docstring-fill-column}.
 
-  In Emacs Lisp, a documentation string is accessible through the
-function or variable that it describes:
+  Exactly where a documentation string is stored depends on how its
+function or variable was defined or loaded into memory:
 
 @itemize @bullet
 @item
 @kindex function-documentation
-The documentation for a function is usually stored in the function
-definition itself (@pxref{Lambda Expressions} and @pxref{Function
-Documentation}).  The function @code{documentation} knows how to
-extract it.  You can also put function documentation in the
address@hidden property of the function name.  That is
-useful with definitions such as keyboard macros that can't hold a
-documentation string.
+When you define a function (@pxref{Lambda Expressions}, and
address@hidden Documentation}), the documentation string is stored in
+the function definition itself.  You can also put function
+documentation in the @code{function-documentation} property of a
+function name.  That is useful for function definitions which can't
+hold a documentation string, such as keyboard macros.
 
 @item
 @kindex variable-documentation
-The documentation for a variable is stored in the variable's property
-list under the property name @code{variable-documentation}.  The
-function @code{documentation-property} knows how to retrieve it.
+When you define a variable with a @code{defvar} or related form
+(@pxref{Defining Variables}), the documentation is stored in the
+variable's @code{variable-documentation} property.
+
address@hidden @address@hidden (documentation) file
address@hidden
+To save memory, the documentation for preloaded functions and
+variables (including primitive functions and autoloaded functions) is
+not kept in memory, but in the file
address@hidden/etc/address@hidden, where @var{version} is the Emacs
+version number (@pxref{Version Info}).
+
address@hidden
+When a function or variable is loaded from a byte-compiled file during
+the Emacs session, its documentation string is not loaded into memory.
+Instead, Emacs looks it up in the byte-compiled file as needed.
address@hidden and Compilation}.
 @end itemize
 
address@hidden @address@hidden (documentation) file
-To save space, the documentation for preloaded functions and variables
-(including primitive functions and autoloaded functions) is stored in
-the file @file{emacs/etc/address@hidden inside Emacs.  The
-documentation strings for functions and variables loaded during the
-Emacs session from byte-compiled files are stored in those files
-(@pxref{Docs and Compilation}).
-
-The data structure inside Emacs has an integer offset into the file, or
-a list containing a file name and an integer, in place of the
-documentation string.  The functions @code{documentation} and
address@hidden use that information to fetch the
-documentation string from the appropriate file; this is transparent to
-the user.
address@hidden
+Regardless of where the documentation string is stored, you can
+retrieve it using the @code{documentation} or
address@hidden function, described in the next section.
 
 @node Accessing Documentation
 @section Access to Documentation Strings
 
 @defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded in
address@hidden's property list under property @var{property}.  It
-retrieves the text from a file if the value calls for that.  If the
-property value isn't @code{nil}, isn't a string, and doesn't refer to
-text in a file, then it is evaluated to obtain a string.
+This function returns the documentation string recorded in
address@hidden's property list under property @var{property}.  It is
+most often used to look up the documentation strings of variables, for
+which @var{property} is @code{variable-documentation}.  However, it
+can also be used to look up other kinds of documentation, such as for
+customization groups (but for function documentation, use the
address@hidden command, below).
+
+If the value recorded in the property list refers to a documentation
+string stored in a @address@hidden file or a byte-compiled
+file, it looks up that string and returns it.  If the property value
+isn't @code{nil}, isn't a string, and doesn't refer to text in a file,
+then it is evaluated as a Lisp expression to obtain a string.
 
 The last thing this function does is pass the string through
address@hidden to substitute actual key bindings,
-unless @var{verbatim} is address@hidden
address@hidden to substitute actual key bindings
+(@pxref{Keys in Documentation}).  However, it skips this step if
address@hidden is address@hidden
 
 @smallexample
 @group
@@ -270,13 +281,13 @@
 @end group
 @end smallexample
 
address@hidden of Snarf-documentation}
 @defun Snarf-documentation filename
address@hidden of Snarf-documentation}
-This function is used only during Emacs initialization, just before
-the runnable Emacs is dumped.  It finds the file offsets of the
-documentation strings stored in the file @var{filename}, and records
-them in the in-core function definitions and variable property lists in
-place of the actual strings.  @xref{Building Emacs}.
+This function is used when building Emacs, just before the runnable
+Emacs is dumped.  It finds the positions of the documentation strings
+stored in the file @var{filename}, and records those positions into
+memory in the function definitions and variable property lists.
address@hidden Emacs}.
 
 Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
 When the dumped Emacs is later executed, the same file will be looked
@@ -515,13 +526,14 @@
 The function returns a list of elements that look like this:
 
 @example
-(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
+(@var{symbol} @var{score} @var{functionn-doc} @var{variable-doc}
  @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
 @end example
 
 Here, @var{score} is an integer measure of how important the symbol
-seems to be as a match, and the remaining elements are documentation
-strings for @var{symbol}'s various roles (or @code{nil}).
+seems to be as a match.  Each of the remaining elements is a
+documentation string, or @code{nil}, for @var{symbol} as a function,
+variable, etc.
 
 It also displays the symbols in a buffer named @samp{*Apropos*}, each
 with a one-line description taken from the beginning of its

=== modified file 'doc/lispref/macros.texi'
--- a/doc/lispref/macros.texi   2012-02-15 05:15:43 +0000
+++ b/doc/lispref/macros.texi   2012-02-19 05:54:33 +0000
@@ -258,7 +258,8 @@
 for more details.
 
 @item (doc-string @var{number})
-Specify which element of the macro is the doc string, if any.
+Specify which element of the macro is the documentation string, if
+any.
 @end table
 
 A @code{declare} form only has its special effect in the body of a

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-02-18 13:38:33 +0000
+++ b/doc/lispref/modes.texi    2012-02-19 05:54:33 +0000
@@ -800,10 +800,10 @@
 mode no parent.  Then @code{define-derived-mode} behaves as described
 above, but, of course, omits all actions connected with @var{parent}.
 
-The argument @var{docstring} specifies the documentation string for
-the new mode.  @code{define-derived-mode} adds some general
-information about the mode's hook, followed by the mode's keymap, at
-the end of this docstring.  If you omit @var{docstring},
+The argument @var{docstring} specifies the documentation string for the
+new mode.  @code{define-derived-mode} adds some general information
+about the mode's hook, followed by the mode's keymap, at the end of this
+documentation string.  If you omit @var{docstring},
 @code{define-derived-mode} generates a documentation string.
 
 The @var{keyword-args} are pairs of keywords and values.  The values

=== modified file 'doc/lispref/tips.texi'
--- a/doc/lispref/tips.texi     2012-01-19 07:21:25 +0000
+++ b/doc/lispref/tips.texi     2012-02-19 05:54:33 +0000
@@ -826,9 +826,7 @@
 
 @item
 When you define a variable that users ought to set interactively, you
-normally should use @code{defcustom}.  However, if for some reason you
-use @code{defvar} instead, start the doc string with a @samp{*}.
address@hidden Variables}.
+should use @code{defcustom}.  @xref{Defining Variables}.
 
 @item
 The documentation string for a variable that is a yes-or-no flag should

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-02-18 13:38:33 +0000
+++ b/doc/lispref/vol1.texi     2012-02-19 05:54:33 +0000
@@ -848,8 +848,7 @@
 
 Documentation
 
-* Documentation Basics::    Good style for doc strings.
-                              Where to put them.  How Emacs stores them.
+* Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
 * Describing Characters::   Making printable descriptions of

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-02-18 13:38:33 +0000
+++ b/doc/lispref/vol2.texi     2012-02-19 05:54:33 +0000
@@ -847,8 +847,7 @@
 
 Documentation
 
-* Documentation Basics::    Good style for doc strings.
-                              Where to put them.  How Emacs stores them.
+* Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
 * Describing Characters::   Making printable descriptions of