@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005 Free Software Foundation, Inc.
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/help
@node Documentation, Files, Modes, Top
manual is not organized in that fashion; it is organized in terms of
topics of discussion.
+ For commands to access documentation strings, see @ref{Help, ,
+Help, emacs, The GNU Emacs Manual}.
+
@menu
* Documentation Basics:: Good style for doc strings.
Where to put them. How Emacs stores them.
to the keys for related commands and be accurate even when a user
rearranges the key bindings. (@xref{Keys in Documentation}.)
+@vindex emacs-lisp-docstring-fill-column
+ Emacs Lisp mode fills documentation strings to the width
+specified by @code{emacs-lisp-docstring-fill-column}.
+
In Emacs Lisp, a documentation string is accessible through the
function or variable that it describes:
documentation string from the appropriate file; this is transparent to
the user.
- For information on the uses of documentation strings, see @ref{Help, ,
-Help, emacs, The GNU Emacs Manual}.
-
@c Wordy to prevent overfull hbox. --rjc 15mar92
The @file{emacs/lib-src} directory contains two utilities that you can
use to print nice-looking hardcopy for the file
(symbol-plist 'command-line-processed)
@result{} (variable-documentation 188902)
@end group
+@group
+(documentation-property 'emacs 'group-documentation)
+ @result{} "Customization of the One True Editor."
+@end group
@end smallexample
@end defun
@defun documentation function &optional verbatim
This function returns the documentation string of @var{function}.
+@code{documentation} handles macros, named keyboard macros, and
+special forms, as well as 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
@code{documentation} returns @code{nil}.
@end defun
+@defun face-documentation face
+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
call it with a string containing key descriptions, separated by spaces;
it returns a string or vector containing the corresponding events.
(This may or may not be a single valid key sequence, depending on what
-events you use; @pxref{Keymap Terminology}.) If @var{need-vector} is
+events you use; @pxref{Key Sequences}.) If @var{need-vector} is
non-@code{nil}, the return value is always a vector.
@end defun
about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
we describe some program-level interfaces to the same information.
-@deffn Command apropos regexp &optional do-all
+@deffn Command apropos pattern &optional do-all
This function finds all ``meaningful'' symbols whose names contain a
-match for the regular expression @var{regexp}, and returns a list of
-them, with associated documentation (@pxref{Regular Expressions}). It
-also displays the symbols in a buffer named @samp{*Apropos*}, each
-with a one-line description taken from the beginning of its
-documentation string. A symbol is ``meaningful'' if it has a
+match for the apropos pattern @var{pattern}. An apropos pattern is
+either a word to match, a space-separated list of words of which at
+least two must match, or a regular expression (if any special regular
+expression characters occur). A symbol is ``meaningful'' if it has a
definition as a function, variable, or face, or has properties.
+The function returns a list of elements that look like this:
+
+@example
+(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
+ @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
+@end example
+
+Here, @var{score} is an integer measure of how important the symbol
+seems to be as a match, and the remaining elements are documentation
+strings for @var{symbol}'s various roles (or @code{nil}).
+
+It also displays the symbols in a buffer named @samp{*Apropos*}, each
+with a one-line description taken from the beginning of its
+documentation string.
+
@c Emacs 19 feature
If @var{do-all} is non-@code{nil}, or if the user option
@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also