From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 21 Oct 2017 07:43:30 +0000 (+0300)
Subject: Document 'minibuffer-with-setup-hook'
X-Git-Tag: emacs-26.0.91~505
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4587d8e0ef3302e9a2d99e2981897537eb320168;p=emacs.git

Document 'minibuffer-with-setup-hook'

* doc/lispref/minibuf.texi (Minibuffer Misc): Document
minibuffer-with-setup-hook.  (Bug#28877)
---

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index afd44b7dfe4..1ece8996008 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2407,6 +2407,19 @@ This is a normal hook that is run whenever the minibuffer is entered.
 @xref{Hooks}.
 @end defvar
 
+@defmac minibuffer-with-setup-hook function &rest body
+This macro executes @var{body} after arranging for the specified
+@var{function} to be called via @code{minibuffer-setup-hook}.  By
+default, @var{function} is called before the other functions in the
+@code{minibuffer-setup-hook} list, but if @var{function} is of the
+form @w{@code{(:append @var{func})}}, @var{func} will be called
+@emph{after} the other hook functions.
+
+The @var{body} forms should not use the minibuffer more than once.  If
+the minibuffer is re-entered recursively, @var{function} will only be
+called once, for the outermost use of the minibuffer.
+@end defmac
+
 @defvar minibuffer-exit-hook
 This is a normal hook that is run whenever the minibuffer is exited.
 @xref{Hooks}.