@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 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../info/help
+@setfilename ../../info/help
@node Documentation, Files, Modes, Top
@chapter Documentation
@cindex documentation strings
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
@group
;; @r{Display the data.}
- (with-output-to-temp-buffer "*Help*"
- (mapcar describe-func (sort sym-list 'string<))
- (print-help-return-message))))
+ (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
---------- Buffer: *Help* ----------
goal-column Option
-*Semipermanent goal column for vertical motion, as set by @dots{}
+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.
@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
@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
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
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
@smallexample
@group
-(define-key global-map (char-to-string help-char) 'help-command)
+(define-key global-map (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
+@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
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
+@end defopt
-@defvar help-event-list
+@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 defvar
+@end defopt
@defvar help-form
If this variable is non-@code{nil}, its value is a form to evaluate
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.
+certain documentation and text files that come with Emacs.
@end defvar
-@c Emacs 19 feature
+@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.
+@end defun
+
+@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.
+@end defmac
+
+@defun help-setup-xref item interactive-p
+This function updates the cross reference data in the @samp{*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
+clearing the buffer. The @var{item} argument should have the form
+@code{(@var{funtion} . @var{args})}, where @var{funtion} 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.
+@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.
if the user types the help character again.
@end defopt
-@ignore
- arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
-@end ignore
HCoop / bpt / emacs.git / blobdiff