X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/bfab7c6ec74dc55d640ef36f8cb1790a1420f991..17284e30244d0dd635708cec51e19bafcd9a528b:/doc/lispref/help.texi diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index f68248f5e1..d3e289578c 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -1,7 +1,8 @@ @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, 2008 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/help @node Documentation, Files, Modes, Top @@ -106,12 +107,6 @@ documentation string. The functions @code{documentation} and 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 @@ -232,9 +227,9 @@ in the `*Help*' buffer." @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 @@ -247,7 +242,7 @@ but provides more information. ---------- 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. @@ -275,11 +270,6 @@ When the `track-eol' feature is doing its job, the value is 9999. @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 @@ -294,7 +284,6 @@ 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 @@ -303,8 +292,6 @@ 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 @@ -540,7 +527,6 @@ 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 @@ -566,20 +552,7 @@ follows: @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 @@ -596,13 +569,13 @@ 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 +@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 @@ -653,15 +626,44 @@ 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. +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. @@ -687,18 +689,6 @@ This macro is used in the command @code{help-for-help} which is the binding of @kbd{C-h C-h}. @end defmac -@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}). It -also puts that buffer in Help mode, displays a message telling the -user how to quit and scroll the help window, and does various other -things that make a help window work better. - -Don't use @code{print-help-return-message} in the body of this macro; -it would cause bad results. -@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 @@ -706,6 +696,3 @@ 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