[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs/doc/lispref help.texi
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] emacs/doc/lispref help.texi |
Date: |
Mon, 30 Mar 2009 21:57:28 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Chong Yidong <cyd> 09/03/30 21:57:28
Modified files:
doc/lispref : help.texi
Log message:
(Accessing Documentation): Update example to use
help-setup-xref and with-help-window.
(Help Functions): Remove print-help-return-message, which is
semi-obsolete due to with-help-window. Document help-buffer and
help-setup-xref.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/help.texi?cvsroot=emacs&r1=1.9&r2=1.10
Patches:
Index: help.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/help.texi,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- help.texi 29 Mar 2009 19:14:21 -0000 1.9
+++ help.texi 30 Mar 2009 21:57:28 -0000 1.10
@@ -232,9 +232,9 @@
@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
@@ -557,19 +557,6 @@
@end smallexample
@end deffn
address@hidden 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 address@hidden
-Otherwise it calls @code{message} to display it in the echo area.
-
-This function expects to be called inside a
address@hidden special form, and expects
address@hidden to have the value bound by that special form.
-For an example of its use, see the long example in @ref{Accessing
-Documentation}.
address@hidden 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
@@ -650,6 +637,38 @@
certain documentation and text files that come with Emacs.
@end defvar
address@hidden help-buffer
+This function returns the name of the help buffer, which is normally
address@hidden; if such a buffer does not exist, it is first created.
address@hidden deffn
+
address@hidden with-help-window buffer-name address@hidden
+This macro evaluates the @var{body} forms, inserting any output they
+produce into a buffer named @var{buffer-name} like
address@hidden (@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.
address@hidden defmac
+
address@hidden 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
address@hidden(@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 address@hidden 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.
address@hidden deffn
+
address@hidden example}, for an example of using
address@hidden, @code{with-help-window}, and
address@hidden
+
@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.
@@ -675,18 +694,6 @@
binding of @kbd{C-h C-h}.
@end defmac
address@hidden with-help-window buffer-name address@hidden
-This macro evaluates the @var{body} forms, inserting any output they
-produce into a buffer named @var{buffer-name} like
address@hidden (@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.
address@hidden defmac
-
@defopt three-step-help
If this variable is address@hidden, commands defined with
@code{make-help-screen} display their @var{help-line} strings in the