(lispref.info)Documentation Basics


Next: Accessing Documentation Prev: Documentation Up: Documentation

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', print 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').

   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.  (Note: Accessing Documentation.)

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

   * The documentation for a function is stored in the function
     definition itself (Note: Lambda Expressions.).  The function
     `documentation' knows how to extract it.

   * The documentation for a variable is stored on the variable's
     property list under the property name `variable-documentation'.
     The function `documentation-property' knows how to extract it.

   However, to save space, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions) are
stored in the `emacs/etc/DOC-VERSION' file.  The
`emacs/etc/DOC-VERSION' file can be accessed by both the
`documentation' and the `documentation-property' functions, and the
process is transparent to the user.  In this case, the documentation
string is replaced with an integer offset into the
`emacs/etc/DOC-VERSION' file.  Keeping the documentation strings out of
the Emacs core image saves a significant amount of space.  *Note
Building Emacs::.

   For information on the uses of documentation strings, see *Note
Help: (emacs)Help.

   The `emacs/etc' 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'.


automatically generated by info2www