@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.
+
+ 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}.
- Dynamic access to documentation strings does have drawbacks:
+@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.
-@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.
+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:
-@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
+@smallexample
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end smallexample
-@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.
+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{#$}
- 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
-
-@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.
-@end defopt
+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
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
@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
-@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}.
-
- 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
-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.
+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.
+
+@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}).
+
+@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
-@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
+ 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}.
-@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.
+ In the documentation string of an autoloaded command
+(@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
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
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).
+
+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.
-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.
+Finally, unless @var{verbatim} is non-@code{nil}, this function calls
+@code{substitute-command-keys}. The result is the documentation
+string to return.
-The function @code{documentation} signals a @code{void-function} error
+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}.
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.
@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
HCoop / bpt / emacs.git / commitdiff