@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@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
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
-@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. @xref{Documentation Tips}.
+ When you write a documentation string, make the first line a
+complete sentence (or two complete sentences) since 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 doc strings; see @ref{Documentation
+Tips}.
Documentation strings can contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
property value isn't @code{nil}, isn't a string, and doesn't refer to
text in a file, then it is evaluated to obtain a string.
-Finally, @code{documentation-property} passes the string through
+The last thing this function does is pass the string through
@code{substitute-command-keys} to substitute actual key bindings,
unless @var{verbatim} is non-@code{nil}.
(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
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