(Help Functions): Document new macro `with-help-window'.

2 files changed, 15 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 284809bdac1..0af60709be4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2007-11-13  Martin Rudalics  <rudalics@gmx.at>
+
+	* help.texi (Help Functions): Document new macro `with-help-window'.
+
 2007-11-10  Paul Pogonyshev  <pogonyshev@gmx.net>
 
 	* searching.texi (Replacing Match): Describe new
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 64b6a6ecfa2..c23d6808488 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -687,6 +687,17 @@ 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}.  @code{with-help-window}
+behaves like @code{with-output-to-temp-buffer} (@pxref{Temporary
+Displays}) but does more accurately restore the previous window
+configuration when quitting Help.  It also generates the message
+informing the user how to quit and scroll the help window by itself.
+Hence you will regret it if you use @code{print-help-return-message} in
+the body of this macro.
+@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