# HG changeset patch # User Glenn Morris # Date 1189051901 0 # Node ID 8d5608f0c2c9b5a5eeba409826e3e9fd272370c4 # Parent f29ed3b78ac8730156a560f260fd063ad761c3e9 Move to ../doc/lispref diff -r f29ed3b78ac8 -r 8d5608f0c2c9 lispref/help.texi --- a/lispref/help.texi Thu Sep 06 04:11:35 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,699 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/help -@node Documentation, Files, Modes, Top -@chapter Documentation -@cindex documentation strings - - GNU Emacs Lisp has convenient on-line help facilities, most of which -derive their information from the documentation strings associated with -functions and variables. This chapter describes how to write good -documentation strings for your Lisp programs, as well as how to write -programs to access documentation. - - 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}. For the conventions for writing -documentation strings, see @ref{Documentation Tips}. - -@menu -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* 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 -@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) 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 -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}. - - In Emacs Lisp, a documentation string is accessible through the -function or variable that it describes: - -@itemize @bullet -@item -@kindex function-documentation -The documentation for a function is usually stored in the function -definition itself (@pxref{Lambda Expressions}). The function -@code{documentation} knows how to extract it. You can also put -function documentation in the @code{function-documentation} property -of the function name. That is useful with definitions such as -keyboard macros that can't hold a documentation string. - -@item -@kindex variable-documentation -The documentation for a variable is stored in the variable's property -list under the property name @code{variable-documentation}. The -function @code{documentation-property} knows how to retrieve it. -@end itemize - -@cindex @file{DOC-@var{version}} (documentation) file -To save space, the documentation for preloaded functions and variables -(including primitive functions and autoloaded functions) is stored in -the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The -documentation strings for functions and variables loaded during the -Emacs session from byte-compiled files are stored in those files -(@pxref{Docs and Compilation}). - -The data structure inside Emacs has an integer offset into the file, or -a list containing a file name and an integer, in place of the -documentation string. The functions @code{documentation} and -@code{documentation-property} use that information to fetch the -documentation string from the appropriate file; this is transparent to -the user. - -@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 -@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and -@file{digest-doc}. - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string that is recorded in -@var{symbol}'s property list under property @var{property}. It -retrieves the text from a file if the value calls for that. 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 to obtain a string. - -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}. - -@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}. -@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 -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}, it calls -@code{substitute-command-keys} so as to return a value containing the -actual (current) key bindings. - -The function @code{documentation} 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 - -@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. - -@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 (user-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.} - (with-output-to-temp-buffer "*Help*" - (mapcar describe-func (sort sym-list 'string<)) - (print-help-return-message)))) -@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 -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, 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'. -@end group - -@group -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. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -The asterisk @samp{*} as the first character of a variable's doc string, -as shown above for the @code{goal-column} variable, means that it is a -user option; see the description of @code{defvar} in @ref{Defining -Variables}. - -@defun Snarf-documentation filename -@anchor{Definition of Snarf-documentation} -This function is used only during Emacs initialization, just before -the runnable Emacs is dumped. It finds the file offsets of the -documentation strings stored in the file @var{filename}, and records -them in the in-core function definitions and variable property lists in -place of the actual strings. @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-@var{version}"}. -@end defun - -@c Emacs 19 feature -@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 -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}. - -In older Emacs versions, @code{exec-directory} was used for this. -@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 - - 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 \= -quotes the following character and is discarded; thus, @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. - -@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. -@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\ -\\\\[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 " -@end group -@group -(key-description [delete] "\M-3") - @result{} "M-3 " -@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{} "" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "" -@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 - -@defun 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 defun - -@node Help Functions -@section Help Functions - - Emacs provides a variety of on-line 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{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 -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 (char-to-string help-char) 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defun print-help-return-message &optional function -This function builds a string that explains 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 calls @code{message} to display it in the echo area. - -This function expects to be called inside a -@code{with-output-to-temp-buffer} special form, and expects -@code{standard-output} to have the value bound by that special form. -For an example of its use, see the long example in @ref{Accessing -Documentation}. -@end defun - -@defvar 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 defvar - -@defvar 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 defvar - -@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} 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 - -@defun 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 - - 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}. - -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@c Emacs 19 feature -@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. In older -Emacs versions, @code{exec-directory} was used for this. -@end defvar - -@c Emacs 19 feature -@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 - -@ignore - arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815 -@end ignore