@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/help
-@node Documentation, Files, Modes, Top
+@node Documentation
@chapter Documentation
@cindex documentation strings
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
@end menu
@node Documentation Basics
-@comment node-name, next, previous, up
@section Documentation Basics
@cindex documentation conventions
@cindex writing a documentation string
@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 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. (@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}.
-
- 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.
-
-@cindex @file{DOC-@var{version}} (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-@var{version}}, where @var{version} is the Emacs
-version number (@pxref{Version Info}).
-
-@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
-
-@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.
+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 documentation
+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
+ 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}.
+
+ 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 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.
-If the value recorded in the property list refers to a documentation
-string stored in a @file{DOC-@var{version}} 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 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.
-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}.
+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).
-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.
+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.
-The function @code{documentation} signals a @code{void-function} error
+Finally, unless @var{verbatim} is non-@code{nil}, this function calls
+@code{substitute-command-keys}. The result is the documentation
+string to return.
+
+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 @samp{*Help*} buffer.
+several symbols in a @file{*Help*} buffer.
@anchor{describe-symbols example}
@smallexample
@group
(princ
(format "%s\t%s\n%s\n\n" s
- (if (user-variable-p s)
+ (if (custom-variable-p s)
"Option " "Variable")
@end group
@group
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
for in the directory @code{doc-directory}. Usually @var{filename} is
-@code{"DOC-@var{version}"}.
+@code{"DOC"}.
@end defun
@defvar doc-directory
This variable holds the name of the directory which should contain the
-file @code{"DOC-@var{version}"} that contains documentation strings for
+file @code{"DOC"} that contains documentation strings for
built-in and preloaded functions and variables.
In most cases, this is the same as @code{data-directory}. They may be
@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
replaces them by what they stand for, returning the result as a string.
This permits display of documentation that refers accurately to the
user's own customized key bindings.
+
+@cindex advertised binding
+If a command has multiple bindings, this function normally uses the
+first one it finds. You can specify one particular key binding by
+assigning an @code{:advertised-binding} symbol property to the
+command, like this:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+The @code{:advertised-binding} property also affects the binding shown
+in menu items (@pxref{Menu Bar}). The property is ignored if it
+specifies a key binding that the command does not actually have.
@end defun
Here are examples of the special sequences:
Emacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
starting with @samp{C-}, a meta character turns into a string starting
-with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+with @samp{M-}, and space, tab, etc., appear as @samp{SPC},
@samp{TAB}, etc. A function key symbol appears inside angle brackets
@samp{<@dots{}>}. An event that is a list appears as the name of the
symbol in the @sc{car} of the list, inside angle brackets.
@end smallexample
@end defun
-@defun read-kbd-macro string &optional need-vector
+@deffn Command read-kbd-macro string &optional need-vector
This function is used mainly for operating on keyboard macros, but it
can also be used as a rough inverse for @code{key-description}. You
call it with a string containing key descriptions, separated by spaces;
(This may or may not be a single valid key sequence, depending on what
events you use; @pxref{Key Sequences}.) If @var{need-vector} is
non-@code{nil}, the return value is always a vector.
-@end defun
+@end deffn
@node Help Functions
@section Help Functions
documentation string, or @code{nil}, for @var{symbol} as a function,
variable, etc.
-It also displays the symbols in a buffer named @samp{*Apropos*}, each
+It also displays the symbols in a buffer named @file{*Apropos*}, each
with a one-line description taken from the beginning of its
documentation string.
@defopt help-event-list
The value of this variable is a list of event types that serve as
-alternative ``help characters.'' These events are handled just like the
+alternative ``help characters''. These events are handled just like the
event specified by @code{help-char}.
@end defopt
variable's default value is @code{describe-prefix-bindings}.
@end defvar
-@defun describe-prefix-bindings
+@deffn Command describe-prefix-bindings
This function calls @code{describe-bindings} to display a list of all
the subcommands of the prefix key of the most recent key sequence. The
prefix described consists of all but the last event of that key
sequence. (The last event is, presumably, the help character.)
-@end defun
+@end deffn
The following two functions are meant for modes that want to provide
help without relinquishing control, such as the ``electric'' modes.
@defun help-buffer
This function returns the name of the help buffer, which is normally
-@samp{*Help*}; if such a buffer does not exist, it is first created.
+@file{*Help*}; if such a buffer does not exist, it is first created.
@end defun
+@vindex help-window-select
@defmac with-help-window buffer-name body@dots{}
-This macro evaluates the @var{body} forms, inserting any output they
-produce into a buffer named @var{buffer-name} like
-@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}).
-(Usually, @var{buffer-name} should be the value returned by the
-function @code{help-buffer}.) It also puts the specified buffer into
-Help mode and displays a message telling the user how to quit and
-scroll the help window.
+This macro evaluates @var{body} like @code{with-output-to-temp-buffer}
+(@pxref{Temporary Displays}), inserting any output produced by its forms
+into a buffer named @var{buffer-name}. (Usually, @var{buffer-name}
+should be the value returned by the function @code{help-buffer}.) It
+also puts the specified buffer into Help mode and displays a message
+telling the user how to quit and scroll the help window. It selects the
+help window if the current value of the user option
+@code{help-window-select} has been set accordingly. It returns the last
+value in @var{body}.
@end defmac
@defun help-setup-xref item interactive-p
-This function updates the cross reference data in the @samp{*Help*}
+This function updates the cross reference data in the @file{*Help*}
buffer, which is used to regenerate the help information when the user
clicks on the @samp{Back} or @samp{Forward} buttons. Most commands
-that use the @samp{*Help*} buffer should invoke this function before
+that use the @file{*Help*} buffer should invoke this function before
clearing the buffer. The @var{item} argument should have the form
@code{(@var{function} . @var{args})}, where @var{function} is a function
to call, with argument list @var{args}, to regenerate the help buffer.
The @var{interactive-p} argument is non-@code{nil} if the calling
command was invoked interactively; in that case, the stack of items
-for the @samp{*Help*} buffer's @samp{Back} buttons is cleared.
+for the @file{*Help*} buffer's @samp{Back} buttons is cleared.
@end defun
@xref{describe-symbols example}, for an example of using
echo area at first, and display the longer @var{help-text} strings only
if the user types the help character again.
@end defopt
-
HCoop / bpt / emacs.git / blobdiff