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.
This commit is contained in:
Chong Yidong
parent
0d53f628be
commit
d6d7851124
4 changed files with 121 additions and 137 deletions
|
|
@ -1,3 +1,14 @@
|
|||
2014-01-03 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* 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 <rgm@gnu.org>
|
||||
|
||||
* numbers.texi (Numeric Conversions): Fix a typo.
|
||||
|
|
|
|||
|
|
@ -240,60 +240,50 @@ $ emacs -batch -f batch-byte-compile *.el
|
|||
@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.
|
||||
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.
|
||||
|
||||
Dynamic access to documentation strings does have drawbacks:
|
||||
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.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
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.
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
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.
|
||||
|
||||
@cindex @samp{#@@@var{count}}
|
||||
@cindex @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
|
||||
@samp{#$} 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:
|
||||
|
||||
@example
|
||||
-*-byte-compile-dynamic-docstrings: nil;-*-
|
||||
@end example
|
||||
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 non-@code{nil}, 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:
|
||||
|
||||
@smallexample
|
||||
-*-byte-compile-dynamic-docstrings: nil;-*-
|
||||
@end 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
|
||||
|
||||
@cindex @samp{#@@@var{count}}
|
||||
@cindex @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
|
||||
@var{count} 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 @@ Help, emacs, The GNU Emacs Manual}.
|
|||
@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.
|
||||
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.
|
||||
|
||||
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
|
||||
@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
|
||||
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
|
||||
@ref{Documentation Tips}.
|
||||
@cindex @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
|
||||
@code{function-documentation} property of a function name
|
||||
(@pxref{Accessing 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
|
||||
@cindex @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
|
||||
@code{variable-documentation} property.
|
||||
|
||||
@cindex @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).
|
||||
|
||||
@vindex 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:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@kindex function-documentation
|
||||
When you define a function (@pxref{Lambda Expressions}, and
|
||||
@pxref{Function 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
|
||||
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.
|
||||
|
||||
@cindex @file{DOC} (documentation) file
|
||||
@item
|
||||
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
|
||||
@file{emacs/etc/DOC}).
|
||||
|
||||
@item
|
||||
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.
|
||||
@xref{Docs and Compilation}.
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
Regardless of where the documentation string is stored, you can
|
||||
retrieve it using the @code{documentation} or
|
||||
@code{documentation-property} 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 @@ 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
|
||||
@code{documentation} command, below).
|
||||
@code{documentation} function, 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.
|
||||
If the property value refers to a documentation string stored in the
|
||||
@file{DOC} file or a byte-compiled file, this function looks up that
|
||||
string and returns it.
|
||||
|
||||
The last thing this function does is pass the string through
|
||||
@code{substitute-command-keys} to substitute actual key bindings
|
||||
(@pxref{Keys in Documentation}). However, it skips this step if
|
||||
@var{verbatim} is non-@code{nil}.
|
||||
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
|
||||
@code{substitute-command-keys} to substitute key bindings (@pxref{Keys
|
||||
in Documentation}). It skips this step if @var{verbatim} is
|
||||
non-@code{nil}.
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
|
|
@ -160,16 +138,18 @@ ordinary functions.
|
|||
If @var{function} is a symbol, this function first looks for the
|
||||
@code{function-documentation} property of that symbol; if that has a
|
||||
non-@code{nil} 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
|
||||
@code{documentation} extracts the documentation string from the actual
|
||||
function definition, reading it from a file if called for.
|
||||
value is not a string, it is evaluated).
|
||||
|
||||
Finally, unless @var{verbatim} is non-@code{nil}, it calls
|
||||
@code{substitute-command-keys} so as to return a value containing the
|
||||
actual (current) key bindings.
|
||||
If @var{function} is not a symbol, or if it has no
|
||||
@code{function-documentation} property, then @code{documentation}
|
||||
extracts the documentation string from the actual function definition,
|
||||
reading it from a file if called for.
|
||||
|
||||
The function @code{documentation} signals a @code{void-function} error
|
||||
Finally, unless @var{verbatim} is non-@code{nil}, this function calls
|
||||
@code{substitute-command-keys}. 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 @@ This function returns the documentation string of @var{face} as a
|
|||
face.
|
||||
@end defun
|
||||
|
||||
@c 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 @@ without actually installing it. @xref{Definition of data-directory}.
|
|||
@cindex documentation, keys in
|
||||
@cindex keys in documentation strings
|
||||
@cindex substituting keys in documentation
|
||||
@cindex 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
|
||||
|
|
|
|||
|
|
@ -573,10 +573,13 @@ Format the documentation string so that it fits in an Emacs window on an
|
|||
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.
|
||||
@vindex 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
|
||||
@code{emacs-lisp-docstring-fill-column}. 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue