⟦898b9d9bd⟧

TextFile

@setfilename ../info/help
@node Documentation, Files, Major and Minor Modes, Top
@chapter Documentation

@cindex documentation strings
  GNU Emacs Lisp has a simple to use facility for displaying the
documentation strings that are associated with functions and
variables.  In addition, Emacs has powerful on-line help.
  
  Documentation strings should be distinguished from manuals such as
this one, which can be examined inside Emacs using Info.  A manual is
defined by its own source file; documentation strings are specified in
the source of the functions and variables documented.

@menu
* Documentation Basics::        
* Documentation Strings::       
* Help Functions::      
@end menu

@node Documentation Basics, Documentation Strings, Documentation, Documentation
@comment  node-name,  next,  previous,  up
@section Documentation Basics
@cindex documentation conventions
@cindex writing a documentation string
@cindex documentation string, writing one
@cindex string, writing a documentation string

  A documentation string is written between double quotes, @code{"like this"}.

  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, you should make the first line
a complete sentence (or two compelte sentences) since some commands,
such as @code{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 @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
(@code{describe-variable}).  
@c !!! this chapter does not yet exist! (@xref{Writing}.)

@c !!! Should this be @kindex?
@cindex @code{variable-documentation} property
  In Emacs Lisp, the underlying principle is that adocumentation
string is kept with the function or variable which it describes:

@itemize @bullet
@item
The documentation for a function is stored in the function definition
itself (@pxref{Lambda Expressions}).  The function
@code{documentation} knows how to extract it.

@item
The documentation for a variable is stored on the variable's property
list under the property name @code{variable-documentation}.  The
function @code{documentation-property} knows how to extract it.
@end itemize

@cindex @file{emacs/etc/DOC-@var{version}}
@cindex @file{etc/DOC-@var{version}}
  However, to save space, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions)
stored in the @file{emacs/etc/DOC-@var{version}} file.  Both the
@code{documentation} and the @code{documentation-property} functions
know how to access the @file{emacs/etc/DOC-@var{version}} file, and the
process is transparent to the user.  In this case, the
@code{variable-documentation} property of the symbol is an integer
offset into the @file{emacs/etc/DOC-@var{version}} file.  Keeping the
documentation strings out of the Emacs core image saves a significant
amount of space.

  See @code{where-is-internal} and @code{describe-bindings} in
@ref{Global and Local Keymaps}.  Also, @pxref{Help, , Help, emacs, The
GNU Emacs User Manual}.

  The @file{emacs/etc} directory contains two utilities for printing
the @file{emacs/etc/DOC-@var{version}} file in hardcopy.  These are
@file{sorted-doc.c} and @file{digest-doc.c}.

  In addition,  documentation strings may contain several special
substrings.  These substrings allow the functions which retrieve them
to substitute the actual (current) key bindings into the strings,
using the @code{substitute-command-keys} function.
(@xref{Documentation Strings}.)

@node Documentation Strings, Help Functions, Documentation Basics, Documentation
@section Access to Documentation Strings

@defun documentation-property symbol property
  This function returns the documentation string that is @var{symbol}'s
@var{property}.  Use of this function differs from using @code{get},
since @code{documentation-property} is also able to access documentation
strings that are stored in the @file{emacs/etc/DOC-@var{version}} file.
In addition, @code{documentation-property} runs
@code{substitute-command-keys} on the resulting string, so Emacs will
display the actual (current) keybindings.

@example
(documentation-property 'command-line-processed
   'variable-documentation)
     @result{} "t once command line has been processed"
(symbol-plist 'command-line-processed)
     @result{} (variable-documentation 188902)
@end example
@end defun

@defun documentation function
  This function returns the documentation string of @var{function}.  If
the documentation string is stored in the
@file{emacs/etc/DOC-@var{version}} file, this function will access it
there.

  In addition, @code{documentation} runs @code{substitute-command-keys}
on the resulting string, so the value contains the actual (current)
keybindings.

  Emacs signals a @code{void-function} error unless @var{function} has
a function definition.  However, @var{function} does not need to have
a documentation string.  If there is no documentation string, the
function returns @code{nil}.

  Here is a function which uses @code{documentation} and
@code{documentation-property} to display the documentation strings for
several symbols in a @samp{*Help*} buffer.

@findex documentation-property @r{example}
@findex mapatoms @r{example}
@findex sort @r{example}
@findex commandp @r{example}
@findex function @r{example}
@example
(defun describe-symbols (pattern)
  "Describe the currently active 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)
            ;; @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) 
                             (concat "Command: "
                                     (or (mapconcat 
                                          'key-description 
                                          (where-is-internal s) 
                                          " ")))
                           "Function")
                         (or (documentation s) 
                             "not documented"))))
            
            (if (boundp s)              ; @r{It is a variable.}
                (princ
                 (format "%s\t%s\n%s\n\n" s
                         (if (user-variable-p s) 
                             "Option "
                           "Variable")
                         (or 
                          (documentation-property 
                           s 
                           'variable-documentation)
                          "not documented"))))))
         sym-list)
        
        ;; @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))
                       ))))      
        
        ;; @r{Display the data.}
        (with-output-to-temp-buffer "*Help*"
          (mapcar describe-func (sort sym-list 'string<))
          (print-help-return-message))))
@end example

  The @code{describe-symbols} function works like @code{apropos},
but provides more information.

@example
(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option 
*Semipermanent goal column for vertical motion, 
as set by C-x C-n, or nil.

set-goal-column Command: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
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, clears out the goal column
so that C-n and C-p resume vertical motion.

temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was at the start of current run 
of vertical motion commands.
---------- Buffer: *Help* ----------
@end example
@end defun

@defun Snarf-documentation filename
  This function is used only during Emacs initialization.  It is
executed before the system dumps a runnable Emacs.
@code{Snarf-documentation} finds the file-offsets of the documentation
strings stored in the file @var{filename}, and records them in the
in-core function definitions in place of the documentation strings.

  @var{filename} is found in the @file{emacs/etc} directory (usually
@var{filename} is @code{"DOC-@var{version}"}).  When the dumped Emacs is
later executed, the file is found in the @code{exec-directory}.
@end defun

@defun substitute-command-keys string
  This function returns @var{string} with modifications made to
specially formatted substrings such that the actual (current)
keybindings are listed.  This permists the documentation to provide
information that is updated to contain information about the current
key bindings.  (The key bindings may change between the time Emacs is
built and the time that the documentation is asked for.)

  The following table lists the forms of the special substrings that are
recognized by @code{substitute-command-keys} and the forms with which
the special substrings are replaced.

@table @code
@item \[@var{command}]
replaced by either
a keystroke sequence that will invoke @var{command} or
@code{M-x @var{command}} if @var{command} is not bound to a key sequence.

@item \@{@var{mapvar}@} 
replaced by a summary (made by
@code{describe-bindings}) of the value of @var{mapvar}, taken as a keymap.

@item \<@var{mapvar}> 
make @code{substitute-command-keys} use the value of @var{mapvar} as the
keymap for future @samp{\[@var{command}]} substrings.  This special
string does not produce any replacement text itself; it only affects the
replacements done later.
@end table

@quotation
@b{Note:}  Each @samp{\} must be doubled when written in a string in
Emacs Lisp.
@end quotation

  Here are examples of each special substring:

@example
(substitute-command-keys 
   "To abort recursive edit, type: \\[abort-recursive-edit]")

@result{} "To abort recursive edit, type:  C-]"

(substitute-command-keys 
   "The keys which are defined for the minibuffer here are:
  \\@{minibuffer-local-must-match-map@}")

@result{} "The keys which are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
LFD             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

(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 example
@end defun

@defun key-description string
@cindex Emacs character standard notation
  This function returns a string for printing the Emacs standard notation
of the characters in @var{string}.  See the examples for
@code{single-key-description}.
@end defun

@defun single-key-description character
@cindex character printing
@cindex control character printing
@cindex meta character printing
  This function returns a string for printing @var{character} in the
standard Emacs notation.  Normal printing characters don't change,
control characters turn into a string starting with @samp{C-}, meta
characters turn into a string starting with @samp{M-}, and space,
linefeed, etc. are transformed to @key{SPC}, @key{LFD}, etc.

@example
(single-key-description ?\C-x)
@result{} "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
@result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
@end example
@end defun

@defun text-char-description character
  This function returns a string for printing @var{character}.  This
is like @code{single-key-description}, except that that control
characters are represented with a leading caret (uparrow).

@example
(text-char-description ?\C-c)
     @result{} "^C"
(text-char-description ?\M-m)
     @result{} "M-m"
(text-char-description ?\C-\M-m)
     @result{} "M-^M"
@end example
@end defun

@node Help Functions,  , Documentation Strings, Documentation
@section Help Functions

  Emacs provides a variety of on-line help functions.  You can get to
all of them by typing @kbd{C-h} and then a key.  Here we describe some
program-level interfaces.  For more information about the interactive
help commands, @pxref{Help, , Help, emacs, The GNU Emacs Manual}.

  In addition, @kbd{M-.} (@code{find-tag}) is often helpful, as it
brings you to the source of a function or variable.

  Emacs loads the default help commands from the
@file{emacs/lisp/help.el} library.  In addition, Emacs has a
@file{emacs/lisp/helper.el} library of utilities.  This latter library
is for modes that want to provide help without relinquishing control,
such as the `electric' modes.  (To distinguish them from the regular
help functions, all the functions in the @file{emacs/lisp/helper.el}
library have names beginning with @samp{Helper}.)

@c !!!  the description of apropos is too user-oriented and perhaps
@c should be shortened and re-oriented towards calling from a program.

@deffn Command apropos regexp &optional predicate noprint
  This function finds all symbols whose names contain a match for the
regular expression @var{regexp}, and returns a list of them.  Normally
it will also pop up a window with the @samp{*Help*} buffer in it,
displaying the symbols and a one line description.  (Since only the
first lines of documentation strings are displayed, try to make the first lines
of your documentation strings whole sentences.)  If @var{noprint} is
non-@code{nil}, it does not display them, but just returns the list.

  If @var{predicate} is non-@code{nil}, then that predicate is called
on each symbol that has matched @var{regexp} and only symbols for
which that predicate returns a non-@code{nil} value are listed (and
displayed).

  When you call @code{apropos} interactively, Emacs prompts for
@var{regexp} in the minibuffer.

  In the first of the following examples, Emacs finds all the matches
to @kbd{exec}.  They are returned but not displayed.  In the second
example, Emacs finds and returns only those symbols that are also
commands; in addition, they are then displayed in the @samp{*Help*}
buffer.

@example
(apropos "exec" nil t)
     @result{} (Buffer-menu-execute command-execute exec-directory
    exec-path execute-extended-command execute-kbd-macro
    executing-kbd-macro executing-macro)

(apropos "exec" 'commandp)
     @result{} (Buffer-menu-execute execute-extended-command)

---------- Buffer: *Help* ----------
Buffer-menu-execute
  Function: Save and/or delete buffers marked with
  M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
execute-extended-command      ESC x
  Function: Read function name, then read its arguments and call it.
---------- Buffer: *Help* ----------
@end example

  Typing @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
but the command only displays information about symbols that are
commands.  In the body of the @code{command-apropos} function, the
call to @code{apropos} looks like this:

@example
(apropos string 'commandp)
@end example
@end deffn

@defopt completion-auto-help
  If this variable is non-@code{nil}, Emacs automatically displays a list
of possible completions, whenever the user asks for completion but nothing
can be completed because the next character is not unique.
@end defopt

@defun help-command
  This function is a keymap equivalent to @code{help-map}.
It is defined in @file{emacs/lisp/help.el} like this:

@example
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
@end example
@end defun

@defvar help-map
  The value of this variable is a local keymap for characters following the
Help key.
@end defvar

@defun print-help-return-message &optional function
  This function builds a message explaining how to restore the previous
state of the windows after a help command.  After building the message, it
applies @var{function} to it if @var{function} is non-@code{nil}.
Otherwise it applies @code{message} to it, thus printing it in the echo
area.

This function expects to be called inside of a
@code{with-output-to-temp-buffer} special form, and expects the value of
@code{standard-output} to be the temporary buffer used by that special
form, which is what it will be if you do not change it.

See the example in the section describing the @code{documentation}
function (@pxref{Documentation Strings}).

  The constructed message will be one of the forms shown below.

@example
(print-help-return-message)

---------- Echo Area ----------
Type C-x 1 to remove help window.
---------- Echo Area ----------

---------- Echo Area ----------
Type C-x 4 b RET to restore old contents of help window.
---------- Echo Area ----------
@end example

  Also, see the description of @code{where-is-internal}; 
this function returns list of key sequences (of any length) that are
bound to @var{command} in the local keymap and the global keymap.
@xref{Global and Local Keymaps}.
@end defun

  The following two functions are found in the library @file{helper}.
You must load that library with @code{(require 'helper)} in order to use
them.

@deffn Command Helper-describe-bindings
  This command pops up a window displaying the 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 a message: @code{Help (Type ? for further options)},
and then provides assistance for finding out what the key bindings are,
and what the mode is intended for.  It returns @code{nil}.

  This can be customized by changing the map @code{Helper-help-map}.
@end deffn

@defvar help-char
  The value of this variable is the character that Emacs recognizes as
meaning Help.  When Emacs reads this character (which is usually 8,
the value of @kbd{C-h}), Emacs evaluates @code{(eval help-form)}, and
displays the result if it is a string.  If @code{help-form}'s value is
@code{nil}, this character is read normally.
@end defvar

@defvar help-form
  The value of this variable is a form to execute when the character
@code{help-char} is read.  If the form returns a string, that string is
displayed.  If @code{help-form} is @code{nil}, then the help character
is not recognized.
@end defvar
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦898b9d9bd⟧ TextFile

Derivation

TextFile
