[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107856: More small edits for doc/lispref/minibuf.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107856
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-04-18 23:04:05 -0700
message:
  More small edits for doc/lispref/minibuf.texi
  
  * doc/lispref/minibuf.texi (Object from Minibuffer):
  Remove overly pedantic paragraph.
  (Minibuffer History): Copyedits.  Add face-name-history.
  (Initial Input, Yes-or-No Queries, Multiple Queries)
  (Minibuffer Windows, Minibuffer Misc): Copyedits.
  (Yes-or-No Queries): Tweak example.
  (Minibuffer Commands): Add next-complete-history-element.
  (Minibuffer Misc): Mention minibuffer-message-timeout, and
  minibuffer-inactive-mode.
  
  * doc/lispref/minibuf.texi (Minibuffers):
  * doc/lispref/elisp.texi, doc/lispref/vol1.texi, doc/lispref/vol2.texi:
  Fix minibuffer subsection order.
  
  * lisp/subr.el: Comment.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/minibuf.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  lisp/subr.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-19 02:00:23 +0000
+++ b/doc/lispref/ChangeLog     2012-04-19 06:04:05 +0000
@@ -1,5 +1,17 @@
 2012-04-19  Glenn Morris  <address@hidden>
 
+       * minibuf.texi (Object from Minibuffer): Remove overly pedantic para.
+       (Minibuffer History): Copyedits.  Add face-name-history.
+       (Initial Input, Yes-or-No Queries, Multiple Queries)
+       (Minibuffer Windows, Minibuffer Misc): Copyedits.
+       (Yes-or-No Queries): Tweak example.
+       (Minibuffer Commands): Add next-complete-history-element.
+       (Minibuffer Misc): Mention minibuffer-message-timeout, and
+       minibuffer-inactive-mode.
+
+       * minibuf.texi (Minibuffers):
+       * elisp.texi, vol1.texi, vol2.texi: Fix minibuffer subsection order.
+
        * minibuf.texi: Standardize metasyntactic variables ("history", etc).
        Use Texinfo-recommended form of quote+punctuation.
        (Intro to Minibuffers): First minibuffer is #1, not #0.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-04-12 14:50:58 +0000
+++ b/doc/lispref/elisp.texi    2012-04-19 06:04:05 +0000
@@ -637,8 +637,8 @@
 * Multiple Queries::        Asking a series of similar questions.
 * Reading a Password::      Reading a password from the terminal.
 * Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Minibuffer Contents::     How such commands access the minibuffer text.
-* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2012-04-19 02:44:48 +0000
+++ b/doc/lispref/minibuf.texi  2012-04-19 06:04:05 +0000
@@ -30,8 +30,8 @@
 * Multiple Queries::          Asking a series of similar questions.
 * Reading a Password::        Reading a password from the terminal.
 * Minibuffer Commands::       Commands used as key bindings in minibuffers.
+* Minibuffer Windows::        Operating on the special minibuffer windows.
 * Minibuffer Contents::       How such commands access the minibuffer text.
-* Minibuffer Windows::        Operating on the special minibuffer windows.
 * Recursive Mini::            Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::           Various customization hooks and variables.
 @end menu
@@ -93,8 +93,6 @@
 minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
 local maps for completion.
 
address@hidden minibuffer-inactive-mode
address@hidden minibuffer-inactive-mode-map
 @cindex inactive minibuffer
   When a minibuffer is inactive, its major mode is
 @code{minibuffer-inactive-mode}, with keymap
@@ -408,23 +406,16 @@
 @end defun
 
 @defun edit-and-eval-command prompt form
-This function reads a Lisp expression in the minibuffer, and then
-evaluates it.  The difference between this command and
+This function reads a Lisp expression in the minibuffer, evaluates it,
+then returns the result.  The difference between this command and
 @code{eval-minibuffer} is that here the initial @var{form} is not
 optional and it is treated as a Lisp object to be converted to printed
 representation rather than as a string of text.  It is printed with
 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
 appear in the initial text.  @xref{Output Functions}.
 
-The first thing @code{edit-and-eval-command} does is to activate the
-minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
-representation of @var{form} in the minibuffer, and lets the user edit it.
-When the user exits the minibuffer, the edited text is read with
address@hidden and then evaluated.  The resulting value becomes the value
-of @code{edit-and-eval-command}.
-
 In the following example, we offer the user an expression with initial
-text which is a valid form already:
+text that is already a valid form:
 
 @smallexample
 @group
@@ -444,7 +435,6 @@
 @noindent
 Typing @key{RET} right away would exit the minibuffer and evaluate the
 expression, thus moving point forward one word.
address@hidden returns @code{nil} in this example.
 @end defun
 
 @node Minibuffer History
@@ -523,15 +513,15 @@
 read from the minibuffer don't add new elements to the history list.
 This lets Lisp programs explicitly manage input history by using
 @code{add-to-history}.  By default, @code{history-add-new-input} is
-set to a address@hidden value.
address@hidden
 @end defvar
 
 @defopt history-length
 The value of this variable specifies the maximum length for all
 history lists that don't specify their own maximum lengths.  If the
 value is @code{t}, that means there is no maximum (don't delete old
-elements).  The value of @code{history-length} property of the history
-list variable's symbol, if set, overrides this variable for that
+elements).  If a history list variable's symbol has a address@hidden
address@hidden property, it overrides this variable for that
 particular history list.
 @end defopt
 
@@ -575,6 +565,14 @@
 A history list for arguments that are Lisp expressions to evaluate.
 @end defvar
 
address@hidden face-name-history
+A history list for arguments that are faces.
address@hidden defvar
+
address@hidden Less common: coding-system-history, input-method-history,
address@hidden command-history, grep-history, grep-find-history,
address@hidden read-envvar-name-history, setenv-history, yes-or-no-p-history.
+
 @node Initial Input
 @section Initial Input
 
@@ -608,11 +606,10 @@
 of 0 means the beginning of the string, 1 means after the first
 character, etc.  In @code{read-minibuffer}, and the other
 non-completion minibuffer input functions that support this argument,
-1 means the beginning of the string 2 means after the first character,
+1 means the beginning of the string, 2 means after the first character,
 etc.
 
-Use of a cons cell as the value for @var{initial} arguments is
-deprecated in user code.
+Use of a cons cell as the value for @var{initial} arguments is deprecated.
 
 @node Completion
 @section Completion
@@ -1900,7 +1897,7 @@
 using the mouse---more precisely, if @code{last-nonmenu-event}
 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
 uses a dialog box or pop-up menu to ask the question.  Otherwise, it
-uses keyboard input.  You can force use of the mouse or use of keyboard
+uses keyboard input.  You can force use either of the mouse or of keyboard
 input by binding @code{last-nonmenu-event} to a suitable value around
 the call.
 
@@ -1935,12 +1932,16 @@
 In the following example, the user first types @kbd{q}, which is
 invalid.  At the next prompt the user types @kbd{y}.
 
address@hidden Need an interactive example, because otherwise the return value
address@hidden obscures the display of the valid answer.
 @smallexample
 @group
-(y-or-n-p "Do you need a lift? ")
+(defun ask ()
+  (interactive)
+  (y-or-n-p "Do you need a lift? "))
 
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears in the echo area:}
+;; @r{After evaluation of the preceding definition, @kbd{M-x ask}}
+;;   @r{causes the following prompt to appear in the echo area:}
 @end group
 
 @group
@@ -2043,7 +2044,7 @@
 The value of @var{list} specifies the objects to ask questions about.
 It should be either a list of objects or a generator function.  If it is
 a function, it should expect no arguments, and should return either the
-next object to ask about, or @code{nil} meaning stop asking questions.
+next object to ask about, or @code{nil}, meaning to stop asking questions.
 
 The argument @var{prompter} specifies how to ask each question.  If
 @var{prompter} is a string, the question text is computed like this:
@@ -2059,8 +2060,8 @@
 If not a string, @var{prompter} should be a function of one argument
 (the next object to ask about) and should return the question text.  If
 the value is a string, that is the question to ask the user.  The
-function can also return @code{t} meaning do act on this object (and
-don't ask the user), or @code{nil} meaning ignore this object (and don't
+function can also return @code{t}, meaning do act on this object (and
+don't ask the user), or @code{nil}, meaning ignore this object (and don't
 ask the user).
 
 The argument @var{actor} says how to act on the answers that the user
@@ -2113,12 +2114,14 @@
 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
 or pop-up menu to ask the question.  In this case, it does not use
-keyboard input or the echo area.  You can force use of the mouse or use
+keyboard input or the echo area.  You can force use either of the mouse or
 of keyboard input by binding @code{last-nonmenu-event} to a suitable
 value around the call.
 
 The return value of @code{map-y-or-n-p} is the number of objects acted on.
 @end defun
address@hidden FIXME  An example of this would be more useful than all the
address@hidden preceding examples of simple things.
 
 @node Reading a Password
 @section Reading a Password
@@ -2181,6 +2184,19 @@
 regular expression).
 @end deffn
 
address@hidden Command previous-complete-history-element n
+This command replaces the minibuffer contents with the value of the
address@hidden previous (older) history element that completes the current
+contents of the minibuffer before the point.
address@hidden deffn
+
address@hidden Command next-complete-history-element n
+This command replaces the minibuffer contents with the value of the
address@hidden next (newer) history element that completes the current
+contents of the minibuffer before the point.
address@hidden deffn
+
+
 @node Minibuffer Windows
 @section Minibuffer Windows
 @cindex minibuffer windows
@@ -2190,7 +2206,7 @@
 
 @defun active-minibuffer-window
 This function returns the currently active minibuffer window, or
address@hidden if none is currently active.
address@hidden if there is none.
 @end defun
 
 @defun minibuffer-window &optional frame
@@ -2223,8 +2239,8 @@
 frame.
 
 @defun minibuffer-window-active-p window
-This function returns address@hidden if @var{window}, assumed to be
-a minibuffer window, is currently active.
+This function returns address@hidden if @var{window} is the currently
+active minibuffer window.
 @end defun
 
 @node Minibuffer Contents
@@ -2339,7 +2355,7 @@
 @end defvar
 
 @defun minibuffer-selected-window
-This function returns the window which was selected when the
+This function returns the window that was selected when the
 minibuffer was entered.  If selected window is not a minibuffer
 window, it returns @code{nil}.
 @end defun
@@ -2350,10 +2366,19 @@
 frame.  If an integer, it specifies a number of lines.
 @end defopt
 
address@hidden minibuffer-message-timeout
 @defun minibuffer-message string &rest args
 This function displays @var{string} temporarily at the end of the
-minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.  If @var{args} is address@hidden, the
-actual message is obtained by passing @var{string} and @var{args}
-through @code{format}.  @xref{Formatting Strings}.
+minibuffer text, for a few seconds, or until the next input event
+arrives, whichever comes first.  The variable
address@hidden specifies the number of seconds to
+wait in the absence of input.  It defaults to 2.  If @var{args} is
address@hidden, the actual message is obtained by passing @var{string}
+and @var{args} through @code{format}.  @xref{Formatting Strings}.
 @end defun
+
address@hidden Command minibuffer-inactive-mode
+This is the major mode used in inactive minibuffers.  It uses
+keymap @code{minibuffer-inactive-mode-map}.  This can be useful
+if the minibuffer is in a separate frame.  @xref{Minibuffers and Frames}.
address@hidden deffn

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-04-12 14:50:58 +0000
+++ b/doc/lispref/vol1.texi     2012-04-19 06:04:05 +0000
@@ -658,8 +658,8 @@
 * Multiple Queries::        Asking a series of similar questions.
 * Reading a Password::      Reading a password from the terminal.
 * Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Minibuffer Contents::     How such commands access the minibuffer text.
-* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-04-12 14:50:58 +0000
+++ b/doc/lispref/vol2.texi     2012-04-19 06:04:05 +0000
@@ -657,8 +657,8 @@
 * Multiple Queries::        Asking a series of similar questions.
 * Reading a Password::      Reading a password from the terminal.
 * Minibuffer Commands::     Commands used as key bindings in minibuffers.
+* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Minibuffer Contents::     How such commands access the minibuffer text.
-* Minibuffer Windows::      Operating on the special minibuffer windows.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2012-04-17 16:24:44 +0000
+++ b/lisp/subr.el      2012-04-19 06:04:05 +0000
@@ -2335,6 +2335,8 @@
         (discard-input))))
     (let ((ret (eq answer 'act)))
       (unless noninteractive
+        ;; FIXME this prints one too many spaces, since prompt
+        ;; already ends in a space.  Eg "... (y or n)  y".
         (message "%s %s" prompt (if ret "y" "n")))
       ret)))