[Emacs-diffs] trunk r115854: Lisp manaual improvements re docstrings

[Chong Yidong]

------------------------------------------------------------
revno: 115854
revision-id: address@hidden
parent: address@hidden
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2014-01-03 13:49:06 +0800
message:
  Lisp manaual improvements re docstrings
  
  * doc/lispref/compile.texi (Docs and Compilation): Copyedits.
  
  * doc/lispref/help.texi (Documentation, Accessing Documentation): Copyedits.
  (Documentation Basics): Rewrite, avoiding a repeat discussion of
  docstring conventions.
  
  * doc/lispref/tips.texi (Documentation Tips): Move discussion of
  emacs-lisp-docstring-fill-column here from Documentation Basics.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/compile.texi       
compile.texi-20091113204419-o5vbwnq5f7feedwu-6166
  doc/lispref/help.texi          help.texi-20091113204419-o5vbwnq5f7feedwu-6185
  doc/lispref/tips.texi          tips.texi-20091113204419-o5vbwnq5f7feedwu-6217

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-01-02 19:17:48 +0000
+++ b/doc/lispref/ChangeLog     2014-01-03 05:49:06 +0000
@@ -1,3 +1,14 @@
+2014-01-03  Chong Yidong  <address@hidden>
+
+       * help.texi (Documentation, Accessing Documentation): Copyedits.
+       (Documentation Basics): Rewrite, avoiding a repeat discussion of
+       docstring conventions.
+
+       * tips.texi (Documentation Tips): Move discussion of
+       emacs-lisp-docstring-fill-column here from Documentation Basics.
+
+       * compile.texi (Docs and Compilation): Copyedits.
+
 2014-01-02  Glenn Morris  <address@hidden>
 
        * numbers.texi (Numeric Conversions): Fix a typo.

=== modified file 'doc/lispref/compile.texi'
--- a/doc/lispref/compile.texi  2014-01-01 07:43:34 +0000
+++ b/doc/lispref/compile.texi  2014-01-03 05:49:06 +0000
@@ -240,60 +240,50 @@
 @section Documentation Strings and Compilation
 @cindex dynamic loading of documentation
 
-  Functions and variables loaded from a byte-compiled file access their
-documentation strings dynamically from the file whenever needed.  This
-saves space within Emacs, and makes loading faster because the
-documentation strings themselves need not be processed while loading the
-file.  Actual access to the documentation strings becomes slower as a
-result, but this normally is not enough to bother users.
-
-  Dynamic access to documentation strings does have drawbacks:
-
address@hidden @bullet
address@hidden
-If you delete or move the compiled file after loading it, Emacs can no
-longer access the documentation strings for the functions and variables
-in the file.
-
address@hidden
-If you alter the compiled file (such as by compiling a new version),
-then further access to documentation strings in this file will
-probably give nonsense results.
address@hidden itemize
-
address@hidden
-These problems normally occur only if you build Emacs yourself and use
-it from the directory where you built it, and you happen to edit
-and/or recompile the Lisp source files.  They can be easily cured by
-reloading each file after recompiling it.
-
address@hidden @samp{#@@@var{count}}
address@hidden @samp{#$}
-  The dynamic documentation string feature writes compiled files that
-use a special Lisp reader construct, @samp{#@@@var{count}}.  This
-construct skips the next @var{count} characters.  It also uses the
address@hidden construct, which stands for ``the name of this file, as a
-string''.  It is usually best not to use these constructs in Lisp source
-files, since they are not designed to be clear to humans reading the
-file.
-
-  You can disable the dynamic documentation string feature at compile
-time by setting @code{byte-compile-dynamic-docstrings} to @code{nil};
-this is useful mainly if you expect to change the file, and you want
-Emacs processes that have already loaded it to keep working when the
-file changes.  You can do this globally, or for one source file by
-specifying a file-local binding for the variable.  One way to do that
-is by adding this string to the file's first line:
-
address@hidden
--*-byte-compile-dynamic-docstrings: nil;-*-
address@hidden example
+  When Emacs loads functions and variables from a byte-compiled file,
+it normally does not load their documentation strings into memory.
+Each documentation string is ``dynamically'' loaded from the
+byte-compiled file only when needed.  This saves memory, and speeds up
+loading by skipping the processing of the documentation strings.
+
+  This feature has a drawback: if you delete, move, or alter the
+compiled file (such as by compiling a new version), Emacs may no
+longer be able to access the documentation string of previously-loaded
+functions or variables.  Such a problem normally only occurs if you
+build Emacs yourself, and happen to edit and/or recompile the Lisp
+source files.  To solve it, just reload each file after recompilation.
+
+  Dynamic loading of documentation strings from byte-compiled files is
+determined, at compile time, for each byte-compiled file.  It can be
+disabled via the option @code{byte-compile-dynamic-docstrings}.
 
 @defopt byte-compile-dynamic-docstrings
 If this is address@hidden, the byte compiler generates compiled files
 that are set up for dynamic loading of documentation strings.
+
+To disable the dynamic loading feature for a specific file, set this
+option to @code{nil} in its header line (@pxref{File Variables, ,
+Local Variables in Files, emacs, The GNU Emacs Manual}), like this:
+
address@hidden
+-*-byte-compile-dynamic-docstrings: nil;-*-
address@hidden smallexample
+
+This is useful mainly if you expect to change the file, and you want
+Emacs sessions that have already loaded it to keep working when the
+file changes.
 @end defopt
 
address@hidden @samp{#@@@var{count}}
address@hidden @samp{#$}
+Internally, the dynamic loading of documentation strings is
+accomplished by writing compiled files with a special Lisp reader
+construct, @samp{#@@@var{count}}.  This construct skips the next
address@hidden characters.  It also uses the @samp{#$} construct, which
+stands for ``the name of this file, as a string''.  Do not use these
+constructs in Lisp source files; they are not designed to be clear to
+humans reading the file.
+
 @node Dynamic Loading
 @section Dynamic Loading of Individual Functions
 

=== modified file 'doc/lispref/help.texi'
--- a/doc/lispref/help.texi     2014-01-01 07:43:34 +0000
+++ b/doc/lispref/help.texi     2014-01-03 05:49:06 +0000
@@ -10,8 +10,13 @@
   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.
+documentation strings in Lisp programs.
+
+  The contents of a documentation string should follow certain
+conventions.  In particular, its first line should be a complete
+sentence (or two complete sentences) that briefly describes what the
+function or variable does.  @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
@@ -40,77 +45,48 @@
 @cindex string, writing a doc string
 
   A documentation string is written using the Lisp syntax for strings,
-with double-quote characters surrounding the text of the string.  This
-is because it really is a Lisp string object.  The string serves as
-documentation when it is written in the proper place in the definition
-of a function or variable.  In a function definition, the documentation
-string follows the argument list.  In a variable definition, the
-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) 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 documentation strings; see
address@hidden Tips}.
-
-  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
+with double-quote characters surrounding the text.  It is, in fact, an
+actual Lisp string.  When the string appears in the proper place in a
+function or variable definition, it serves as the function's or
+variable's documentation.
+
address@hidden @code{function-documentation} property
+  In a function definition (a @code{lambda} or @code{defun} form), the
+documentation string is specified after the argument list, and is
+normally stored directly in the function object.  @xref{Function
+Documentation}.  You can also put function documentation in the
address@hidden property of a function name
+(@pxref{Accessing Documentation}).
+
address@hidden @code{variable-documentation} property
+  In a variable definition (a @code{defvar} form), the documention
+string is specified after the initial value.  @xref{Defining
+Variables}.  The string is stored in the variable's
address@hidden property.
+
address@hidden @file{DOC} (documentation) file
+  Sometimes, Emacs does not keep documentation strings in memory.
+There are two such circumstances.  Firstly, to save memory, the
+documentation for preloaded functions and variables (including
+primitives) is kept in a file named @file{DOC}, in the directory
+specified by @code{doc-directory} (@pxref{Accessing Documentation}).
+Secondly, when a function or variable is loaded from a byte-compiled
+file, Emacs avoids loading its documentation string (@pxref{Docs and
+Compilation}).  In both cases, Emacs looks up the documentation string
+from the file only when needed, such as when the user calls @kbd{C-h
+f} (@code{describe-function}) for a function.
+
+  Documentation strings can contain special @dfn{key substitution
+sequences}, referring to key bindings which are looked up only 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).
-
address@hidden emacs-lisp-docstring-fill-column
-  Emacs Lisp mode fills documentation strings to the width
-specified by @code{emacs-lisp-docstring-fill-column}.
-
-  Exactly where a documentation string is stored depends on how its
-function or variable was defined or loaded into memory:
-
address@hidden @bullet
address@hidden
address@hidden function-documentation
-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.
-
address@hidden
address@hidden variable-documentation
-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 @file{DOC} (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/DOC}).
-
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}.
address@hidden itemize
-
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.
+(@pxref{Autoload}), these key-substitution sequences have an
+additional special effect: they cause @kbd{C-h f} on the command to
+trigger autoloading.  (This is needed for correctly setting up the
+hyperlinks in the @file{*Help*} buffer.)
 
 @node Accessing Documentation
 @section Access to Documentation Strings
@@ -122,18 +98,20 @@
 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 @file{DOC} 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
-(@pxref{Keys in Documentation}).  However, it skips this step if
address@hidden is address@hidden
address@hidden function, below).
+
+If the property value refers to a documentation string stored in the
address@hidden file or a byte-compiled file, this function 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.
+
+Finally, this function passes the string through
address@hidden to substitute key bindings (@pxref{Keys
+in Documentation}).  It skips this step if @var{verbatim} is
address@hidden
 
 @smallexample
 @group
@@ -160,16 +138,18 @@
 If @var{function} is a symbol, this function first looks for the
 @code{function-documentation} property of that symbol; if that has a
 address@hidden value, the documentation comes from that value (if the
-value is not a string, it is evaluated).  If @var{function} is not a
-symbol, or if it has no @code{function-documentation} property, then
address@hidden extracts the documentation string from the actual
-function definition, reading it from a file if called for.
-
-Finally, unless @var{verbatim} is address@hidden, it calls
address@hidden so as to return a value containing the
-actual (current) key bindings.
-
-The function @code{documentation} signals a @code{void-function} error
+value is not a string, it is evaluated).
+
+If @var{function} is not a symbol, or if it has no
address@hidden property, then @code{documentation}
+extracts the documentation string from the actual function definition,
+reading it from a file if called for.
+
+Finally, unless @var{verbatim} is address@hidden, this function calls
address@hidden  The result is the documentation
+string to return.
+
+The @code{documentation} function signals a @code{void-function} error
 if @var{function} has no function definition.  However, it is OK if
 the function definition has no documentation string.  In that case,
 @code{documentation} returns @code{nil}.
@@ -180,7 +160,6 @@
 face.
 @end defun
 
address@hidden Wordy to prevent overfull hboxes.  --rjc 15mar92
 Here is an example of using the two functions, @code{documentation} and
 @code{documentation-property}, to display the documentation strings for
 several symbols in a @file{*Help*} buffer.
@@ -313,6 +292,7 @@
 @cindex documentation, keys in
 @cindex keys in documentation strings
 @cindex substituting keys in documentation
address@hidden key substitution sequence
 
   When documentation strings refer to key sequences, they should use the
 current, actual key bindings.  They can do so using certain special text

=== modified file 'doc/lispref/tips.texi'
--- a/doc/lispref/tips.texi     2014-01-01 08:31:29 +0000
+++ b/doc/lispref/tips.texi     2014-01-03 05:49:06 +0000
@@ -573,10 +573,13 @@
 60 characters.  The first line should not be wider than 67 characters
 or it will look bad in the output of @code{apropos}.
 
-You can fill the text if that looks good.  However, rather than blindly
-filling the entire documentation string, you can often make it much more
-readable by choosing certain line breaks with care.  Use blank lines
-between sections if the documentation string is long.
address@hidden emacs-lisp-docstring-fill-column
+You can fill the text if that looks good.  Emacs Lisp mode fills
+documentation strings to the width specified by
address@hidden  However, you can sometimes
+make a documentation string much more readable by adjusting its line
+breaks with care.  Use blank lines between sections if the
+documentation string is long.
 
 @item
 The first line of the documentation string should consist of one or two