34.1 Documentation Basics

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) since some commands, such as 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 you have one, because that looks odd when you use C-h f (describe-function) or C-h v (describe-variable). See Documentation Tips.

Documentation strings may 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. (See Accessing Documentation.)

Within the Lisp world, a documentation string is accessible through the function or variable that it describes:

• The documentation for a function is stored in the function definition itself (see Lambda Expressions). The function documentation knows how to extract it.
• The documentation for a variable is stored in the variable’s property list under the property name variable-documentation. The function documentation-property knows how to extract it.

To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in the internal doc file DOC. The documentation for functions and variables loaded during the SXEmacs session from byte-compiled files is stored in those very same byte-compiled files (see Docs and Compilation).

SXEmacs does not keep documentation strings in memory unless necessary. Instead, SXEmacs maintains, for preloaded symbols, an integer offset into the internal doc file, and for symbols loaded from byte-compiled files, a list containing the filename of the byte-compiled file and an integer offset, in place of the documentation string. The functions documentation and documentation-property use that information to read the documentation from the appropriate file; this is transparent to the user.

For information on the uses of documentation strings, see Help in The SXEmacs Reference Manual.

The emacs/lib-src directory contains two utilities that you can use to print nice-looking hardcopy for the file emacs/etc/DOC-version. These are sorted-doc.c and digest-doc.c.