123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752 |
- @c -*- mode: texinfo; coding: utf-8 -*-
- @c This is part of the GNU Emacs Lisp Reference Manual.
- @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
- @c Foundation, Inc.
- @c See the file elisp.texi for copying conditions.
- @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.
- 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
- the Texinfo language; documentation strings are specified in the
- definitions of the functions and variables they apply to. A collection
- of documentation strings is not sufficient as a manual because a good
- manual is not organized in that fashion; it is organized in terms of
- topics of discussion.
- For commands to display documentation strings, see @ref{Help, ,
- Help, emacs, The GNU Emacs Manual}.
- @menu
- * Documentation Basics:: Where doc strings are defined and stored.
- * Accessing Documentation:: How Lisp programs can access doc strings.
- * Keys in Documentation:: Substituting current key bindings.
- * Describing Characters:: Making printable descriptions of
- non-printing characters and key sequences.
- * Help Functions:: Subroutines used by Emacs help facilities.
- @end menu
- @node Documentation Basics
- @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. 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
- @cindex accessing documentation strings
- @defun documentation-property symbol property &optional verbatim
- This function returns the documentation string recorded in
- @var{symbol}'s property list under property @var{property}. It is
- most often used to look up the documentation strings of variables, for
- 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} 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 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.
- 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
- (documentation-property 'command-line-processed
- 'variable-documentation)
- @result{} "Non-nil once command line has been processed"
- @end group
- @group
- (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}. It
- 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
- 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.
- 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}.
- @end defun
- @defun face-documentation face
- This function returns the documentation string of @var{face} as a
- face.
- @end defun
- 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 @file{*Help*} buffer.
- @anchor{describe-symbols example}
- @smallexample
- @group
- (defun describe-symbols (pattern)
- "Describe the Emacs Lisp symbols matching PATTERN.
- All symbols that have PATTERN in their name are described
- in the *Help* buffer."
- (interactive "sDescribe symbols matching: ")
- (let ((describe-func
- (function
- (lambda (s)
- @end group
- @group
- ;; @r{Print description of symbol.}
- (if (fboundp s) ; @r{It is a function.}
- (princ
- (format "%s\t%s\n%s\n\n" s
- (if (commandp s)
- (let ((keys (where-is-internal s)))
- (if keys
- (concat
- "Keys: "
- (mapconcat 'key-description
- keys " "))
- "Keys: none"))
- "Function")
- @end group
- @group
- (or (documentation s)
- "not documented"))))
- (if (boundp s) ; @r{It is a variable.}
- @end group
- @group
- (princ
- (format "%s\t%s\n%s\n\n" s
- (if (custom-variable-p s)
- "Option " "Variable")
- @end group
- @group
- (or (documentation-property
- s 'variable-documentation)
- "not documented")))))))
- sym-list)
- @end group
- @group
- ;; @r{Build a list of symbols that match pattern.}
- (mapatoms (function
- (lambda (sym)
- (if (string-match pattern (symbol-name sym))
- (setq sym-list (cons sym sym-list))))))
- @end group
- @group
- ;; @r{Display the data.}
- (help-setup-xref (list 'describe-symbols pattern) (interactive-p))
- (with-help-window (help-buffer)
- (mapcar describe-func (sort sym-list 'string<)))))
- @end group
- @end smallexample
- The @code{describe-symbols} function works like @code{apropos},
- but provides more information.
- @smallexample
- @group
- (describe-symbols "goal")
- ---------- Buffer: *Help* ----------
- goal-column Option
- Semipermanent goal column for vertical motion, as set by @dots{}
- @end group
- @c Do not blithely break or fill these lines.
- @c That makes them incorrect.
- @group
- minibuffer-temporary-goal-position Variable
- not documented
- @end group
- @group
- set-goal-column Keys: C-x C-n
- Set the current horizontal position as a goal for C-n and C-p.
- @end group
- @c DO NOT put a blank line here! That is factually inaccurate!
- @group
- Those commands will move to this position in the line moved to
- rather than trying to keep the same horizontal position.
- With a non-nil argument ARG, clears out the goal column
- so that C-n and C-p resume vertical motion.
- The goal column is stored in the variable ‘goal-column’.
- (fn ARG)
- @end group
- @group
- temporary-goal-column Variable
- Current goal column for vertical motion.
- It is the column where point was at the start of the current run
- of vertical motion commands.
- When moving by visual lines via the function ‘line-move-visual’, it is a cons
- cell (COL . HSCROLL), where COL is the x-position, in pixels,
- divided by the default column width, and HSCROLL is the number of
- columns by which window is scrolled from left margin.
- When the ‘track-eol’ feature is doing its job, the value is
- ‘most-positive-fixnum’.
- ---------- Buffer: *Help* ----------
- @end group
- @end smallexample
- @anchor{Definition of Snarf-documentation}
- @defun Snarf-documentation filename
- This function is used when building Emacs, just before the runnable
- Emacs is dumped. It finds the positions of the documentation strings
- stored in the file @var{filename}, and records those positions into
- memory in the function definitions and variable property lists.
- @xref{Building Emacs}.
- 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"}.
- @end defun
- @defvar doc-directory
- This variable holds the name of the directory which should contain the
- 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
- different when you run Emacs from the directory where you built it,
- without actually installing it. @xref{Definition of data-directory}.
- @end defvar
- @node Keys in Documentation
- @section Substituting Key Bindings in Documentation
- @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
- sequences described below. Accessing documentation strings in the usual
- way substitutes current key binding information for these special
- sequences. This works by calling @code{substitute-command-keys}. You
- can also call that function yourself.
- Here is a list of the special sequences and what they mean:
- @table @code
- @item \[@var{command}]
- stands for a key sequence that will invoke @var{command}, or @samp{M-x
- @var{command}} if @var{command} has no key bindings.
- @item \@{@var{mapvar}@}
- stands for a summary of the keymap which is the value of the variable
- @var{mapvar}. The summary is made using @code{describe-bindings}.
- @item \<@var{mapvar}>
- stands for no text itself. It is used only for a side effect: it
- specifies @var{mapvar}'s value as the keymap for any following
- @samp{\[@var{command}]} sequences in this documentation string.
- @item ‘
- @itemx `
- (left single quotation mark and grave accent) both stand for a left quote.
- @item ’
- @itemx '
- (right single quotation mark and apostrophe) both stand for a right quote.
- @item \=
- quotes the following character and is discarded; thus, @samp{\=`} puts
- @samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output,
- and @samp{\=\=} puts @samp{\=} into the output.
- @end table
- @strong{Please note:} Each @samp{\} must be doubled when written in a
- string in Emacs Lisp.
- @defvar text-quoting-style
- @cindex curved quotes
- @cindex curly quotes
- The value of this variable is a symbol that specifies the style Emacs
- should use for single quotes in the wording of help and messages.
- If the variable's value is @code{curve}, the style is
- @t{‘like this’} with curved single quotes. If the value is
- @code{straight}, the style is @t{'like this'} with straight
- apostrophes. If the value is @code{grave}, the style is @t{`like
- this'} with grave accent and apostrophe, the standard style
- before Emacs version 25. The default value @code{nil}
- acts like @code{curve} if curved single quotes are displayable, and
- like @code{grave} otherwise.
- @end defvar
- @defun substitute-command-keys string
- This function scans @var{string} for the above special sequences and
- 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:
- @smallexample
- @group
- (substitute-command-keys
- "To abort recursive edit, type `\\[abort-recursive-edit]'.")
- @result{} "To abort recursive edit, type ‘C-]’."
- @end group
- @group
- (substitute-command-keys
- "The keys that are defined for the minibuffer here are:
- \\@{minibuffer-local-must-match-map@}")
- @result{} "The keys that are defined for the minibuffer here are:
- @end group
- ? minibuffer-completion-help
- SPC minibuffer-complete-word
- TAB minibuffer-complete
- C-j minibuffer-complete-and-exit
- RET minibuffer-complete-and-exit
- C-g abort-recursive-edit
- "
- @group
- (substitute-command-keys
- "To abort a recursive edit from the minibuffer, type \
- `\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
- @result{} "To abort a recursive edit from the minibuffer, type ‘C-g’."
- @end group
- @end smallexample
- There are other special conventions for the text in documentation
- strings---for instance, you can refer to functions, variables, and
- sections of this manual. @xref{Documentation Tips}, for details.
- @node Describing Characters
- @section Describing Characters for Help Messages
- @cindex describe characters and events
- These functions convert events, key sequences, or characters to
- textual descriptions. These descriptions are useful for including
- arbitrary text characters or key sequences in messages, because they
- convert non-printing and whitespace characters to sequences of printing
- characters. The description of a non-whitespace printing character is
- the character itself.
- @defun key-description sequence &optional prefix
- @cindex Emacs event standard notation
- This function returns a string containing the Emacs standard notation
- for the input events in @var{sequence}. If @var{prefix} is
- non-@code{nil}, it is a sequence of input events leading up to
- @var{sequence} and is included in the return value. Both arguments
- may be strings, vectors or lists. @xref{Input Events}, for more
- information about valid events.
- @smallexample
- @group
- (key-description [?\M-3 delete])
- @result{} "M-3 <delete>"
- @end group
- @group
- (key-description [delete] "\M-3")
- @result{} "M-3 <delete>"
- @end group
- @end smallexample
- See also the examples for @code{single-key-description}, below.
- @end defun
- @defun single-key-description event &optional no-angles
- @cindex event printing
- @cindex character printing
- @cindex control character printing
- @cindex meta character printing
- This function returns a string describing @var{event} in the standard
- 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},
- @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.
- If the optional argument @var{no-angles} is non-@code{nil}, the angle
- brackets around function keys and event symbols are omitted; this is
- for compatibility with old versions of Emacs which didn't use the
- brackets.
- @smallexample
- @group
- (single-key-description ?\C-x)
- @result{} "C-x"
- @end group
- @group
- (key-description "\C-x \M-y \n \t \r \f123")
- @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
- @end group
- @group
- (single-key-description 'delete)
- @result{} "<delete>"
- @end group
- @group
- (single-key-description 'C-mouse-1)
- @result{} "<C-mouse-1>"
- @end group
- @group
- (single-key-description 'C-mouse-1 t)
- @result{} "C-mouse-1"
- @end group
- @end smallexample
- @end defun
- @defun text-char-description character
- This function returns a string describing @var{character} in the
- standard Emacs notation for characters that appear in text---like
- @code{single-key-description}, except that control characters are
- represented with a leading caret (which is how control characters in
- Emacs buffers are usually displayed). Another difference is that
- @code{text-char-description} recognizes the 2**7 bit as the Meta
- character, whereas @code{single-key-description} uses the 2**27 bit
- for Meta.
- @smallexample
- @group
- (text-char-description ?\C-c)
- @result{} "^C"
- @end group
- @group
- (text-char-description ?\M-m)
- @result{} "\xed"
- @end group
- @group
- (text-char-description ?\C-\M-m)
- @result{} "\x8d"
- @end group
- @group
- (text-char-description (+ 128 ?m))
- @result{} "M-m"
- @end group
- @group
- (text-char-description (+ 128 ?\C-m))
- @result{} "M-^M"
- @end group
- @end smallexample
- @end defun
- @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;
- 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{Key Sequences}.) If @var{need-vector} is
- non-@code{nil}, the return value is always a vector.
- @end deffn
- @node Help Functions
- @section Help Functions
- @cindex help functions
- Emacs provides a variety of built-in help functions, all accessible to
- the user as subcommands of the prefix @kbd{C-h}. For more information
- 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 pattern &optional do-all
- This function finds all meaningful symbols whose names contain 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{function-doc} @var{variable-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. Each of the remaining elements is a
- documentation string, or @code{nil}, for @var{symbol} as a function,
- variable, etc.
- 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.
- 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
- shows key bindings for the functions that are found; it also shows
- @emph{all} interned symbols, not just meaningful ones (and it lists
- them in the return value as well).
- @end deffn
- @defvar help-map
- The value of this variable is a local keymap for characters following the
- Help key, @kbd{C-h}.
- @end defvar
- @deffn {Prefix Command} help-command
- This symbol is not a function; its function definition cell holds the
- keymap known as @code{help-map}. It is defined in @file{help.el} as
- follows:
- @smallexample
- @group
- (define-key global-map (string help-char) 'help-command)
- (fset 'help-command help-map)
- @end group
- @end smallexample
- @end deffn
- @defopt help-char
- The value of this variable is the help character---the character that
- Emacs recognizes as meaning Help. By default, its value is 8, which
- stands for @kbd{C-h}. When Emacs reads this character, if
- @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
- expression, and displays the result in a window if it is a string.
- Usually the value of @code{help-form} is @code{nil}. Then the
- help character has no special meaning at the level of command input, and
- it becomes part of a key sequence in the normal way. The standard key
- binding of @kbd{C-h} is a prefix key for several general-purpose help
- features.
- The help character is special after prefix keys, too. If it has no
- binding as a subcommand of the prefix key, it runs
- @code{describe-prefix-bindings}, which displays a list of all the
- subcommands of the prefix key.
- @end defopt
- @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
- event specified by @code{help-char}.
- @end defopt
- @defvar help-form
- If this variable is non-@code{nil}, its value is a form to evaluate
- whenever the character @code{help-char} is read. If evaluating the form
- produces a string, that string is displayed.
- A command that calls @code{read-event}, @code{read-char-choice}, or
- @code{read-char} probably should bind @code{help-form} to a
- non-@code{nil} expression while it does input. (The time when you
- should not do this is when @kbd{C-h} has some other meaning.)
- Evaluating this expression should result in a string that explains
- what the input is for and how to enter it properly.
- Entry to the minibuffer binds this variable to the value of
- @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
- @end defvar
- @defvar prefix-help-command
- This variable holds a function to print help for a prefix key. The
- function is called when the user types a prefix key followed by the help
- character, and the help character has no binding after that prefix. The
- variable's default value is @code{describe-prefix-bindings}.
- @end defvar
- @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 deffn
- The following two functions are meant for modes that want to provide
- help without relinquishing control, such as the electric modes.
- Their names begin with @samp{Helper} to distinguish them from the
- ordinary help functions.
- @deffn Command Helper-describe-bindings
- This command pops up a window displaying a help buffer containing a
- listing of all of the key bindings from both the local and global keymaps.
- It works by calling @code{describe-bindings}.
- @end deffn
- @deffn Command Helper-help
- This command provides help for the current mode. It prompts the user
- in the minibuffer with the message @samp{Help (Type ? for further
- options)}, and then provides assistance in finding out what the key
- bindings are, and what the mode is intended for. It returns @code{nil}.
- @vindex Helper-help-map
- This can be customized by changing the map @code{Helper-help-map}.
- @end deffn
- @defvar data-directory
- @anchor{Definition of data-directory}
- This variable holds the name of the directory in which Emacs finds
- certain documentation and text files that come with Emacs.
- @end defvar
- @defun help-buffer
- This function returns the name of the help buffer, which is normally
- @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 @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 @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 @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 @file{*Help*} buffer's @samp{Back} buttons is cleared.
- @end defun
- @xref{describe-symbols example}, for an example of using
- @code{help-buffer}, @code{with-help-window}, and
- @code{help-setup-xref}.
- @defmac make-help-screen fname help-line help-text help-map
- This macro defines a help command named @var{fname} that acts like a
- prefix key that shows a list of the subcommands it offers.
- When invoked, @var{fname} displays @var{help-text} in a window, then
- reads and executes a key sequence according to @var{help-map}. The
- string @var{help-text} should describe the bindings available in
- @var{help-map}.
- The command @var{fname} is defined to handle a few events itself, by
- scrolling the display of @var{help-text}. When @var{fname} reads one of
- those special events, it does the scrolling and then reads another
- event. When it reads an event that is not one of those few, and which
- has a binding in @var{help-map}, it executes that key's binding and
- then returns.
- The argument @var{help-line} should be a single-line summary of the
- alternatives in @var{help-map}. In the current version of Emacs, this
- argument is used only if you set the option @code{three-step-help} to
- @code{t}.
- This macro is used in the command @code{help-for-help} which is the
- binding of @kbd{C-h C-h}.
- @end defmac
- @defopt three-step-help
- If this variable is non-@code{nil}, commands defined with
- @code{make-help-screen} display their @var{help-line} strings in the
- echo area at first, and display the longer @var{help-text} strings only
- if the user types the help character again.
- @end defopt
|