[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107854: Small edits for doc/lispref/minibuf.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107854
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-04-18 22:00:23 -0400
message:
  Small edits for doc/lispref/minibuf.texi
  
  * doc/lispref/minibuf.texi: Standardize metasyntactic variables
  ("history", etc).
  Use Texinfo-recommended form of quote+punctuation.
  (Intro to Minibuffers): First minibuffer is #1, not #0.
  Mention minibuffer-inactive-mode.
  (Text from Minibuffer): Copyedits.
  (Minibuffer History, Programmed Completion): Fix @var usage.
modified:
  doc/lispref/ChangeLog
  doc/lispref/minibuf.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-18 07:21:18 +0000
+++ b/doc/lispref/ChangeLog     2012-04-19 02:00:23 +0000
@@ -1,3 +1,12 @@
+2012-04-19  Glenn Morris  <address@hidden>
+
+       * minibuf.texi: Standardize metasyntactic variables ("history", etc).
+       Use Texinfo-recommended form of quote+punctuation.
+       (Intro to Minibuffers): First minibuffer is #1, not #0.
+       Mention minibuffer-inactive-mode.
+       (Text from Minibuffer): Copyedits.
+       (Minibuffer History, Programmed Completion): Fix @var usage.
+
 2012-04-18  Glenn Morris  <address@hidden>
 
        * processes.texi (Serial Ports, Byte Packing, Bindat Spec)

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2012-04-10 07:11:23 +0000
+++ b/doc/lispref/minibuf.texi  2012-04-19 02:00:23 +0000
@@ -60,8 +60,10 @@
 
   The minibuffer's window is normally a single line; it grows
 automatically if the contents require more space.  You can explicitly
address@hidden FIXME?  Works in 23.4, not 24.0.95.  (Bug#11276)
 resize it temporarily with the window sizing commands; it reverts to
 its normal size when the minibuffer is exited.  You can resize it
address@hidden FIXME?  Doesn't work in any version of Emacs?
 permanently by using the window sizing commands in the frame's other
 window, when the minibuffer is not active.  If the frame contains just
 a minibuffer, you can change the minibuffer's size by changing the
@@ -73,9 +75,9 @@
 code that uses the minibuffer, if you do not want that to change them.
 
   Under some circumstances, a command can use a minibuffer even if
-there is an active minibuffer; such minibuffers are called a
+there is an active minibuffer; such a minibuffer is called a
 @dfn{recursive minibuffer}.  The first minibuffer is named
address@hidden@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
address@hidden@samp{ *Minibuf-1*}}.  Recursive minibuffers are named by
 incrementing the number at the end of the name.  (The names begin with
 a space so that they won't show up in normal buffer lists.)  Of
 several recursive minibuffers, the innermost (or most recently
@@ -91,6 +93,14 @@
 minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
 local maps for completion.
 
address@hidden minibuffer-inactive-mode
address@hidden minibuffer-inactive-mode-map
address@hidden inactive minibuffer
+  When a minibuffer is inactive, it's major mode is
address@hidden, with keymap
address@hidden  This is only really useful if
+the minibuffer is in a separate frame.  @xref{Minibuffers and Frames}.
+
   When Emacs is running in batch mode, any request to read from the
 minibuffer actually reads a line from the standard input descriptor that
 was supplied when Emacs was started.
@@ -111,7 +121,7 @@
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
address@hidden read-from-minibuffer prompt-string &optional initial-contents 
keymap read hist default inherit-input-method
address@hidden read-from-minibuffer prompt &optional initial keymap read 
history default inherit-input-method
 This function is the most general way to get input from the
 minibuffer.  By default, it accepts arbitrary text and returns it as a
 string; however, if @var{read} is address@hidden, then it uses
@@ -119,8 +129,8 @@
 Functions}).
 
 The first thing this function does is to activate a minibuffer and
-display it with @var{prompt-string} as the prompt.  This value must be a
-string.  Then the user can edit text in the minibuffer.
+display it with @var{prompt} (which must be a string) as the
+prompt.  Then the user can edit text in the minibuffer.
 
 When the user types a command to exit the minibuffer,
 @code{read-from-minibuffer} constructs the return value from the text in
@@ -132,7 +142,7 @@
 The argument @var{default} specifies default values to make available
 through the history commands.  It should be a string, a list of
 strings, or @code{nil}.  The string or strings become the minibuffer's
-``future history,'' available to the user with @kbd{M-n}.
+``future history'', available to the user with @kbd{M-n}.
 
 If @var{read} is address@hidden, then @var{default} is also used
 as the input to @code{read}, if the user enters empty input.
@@ -149,12 +159,13 @@
 a keymap is the most important way to customize the minibuffer for
 various applications such as completion.
 
-The argument @var{hist} specifies which history list variable to use
+The argument @var{history} specifies a history list variable to use
 for saving the input and for history commands used in the minibuffer.
-It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
+It defaults to @code{minibuffer-history}.  You can optionally specify
+a starting position in the history list as well.  @xref{Minibuffer History}.
 
 If the variable @code{minibuffer-allow-text-properties} is
address@hidden, then the string which is returned includes whatever text
address@hidden, then the string that is returned includes whatever text
 properties were present in the minibuffer.  Otherwise all the text
 properties are stripped when the value is returned.
 
@@ -164,9 +175,9 @@
 Representations}) from whichever buffer was current before entering the
 minibuffer.
 
-Use of @var{initial-contents} is mostly deprecated; we recommend using
+Use of @var{initial} is mostly deprecated; we recommend using
 a address@hidden value only in conjunction with specifying a cons cell
-for @var{hist}.  @xref{Initial Input}.
+for @var{history}.  @xref{Initial Input}.
 @end defun
 
 @defun read-string prompt &optional initial history default 
inherit-input-method
@@ -179,11 +190,11 @@
 @code{read-from-minibuffer}, except that, if address@hidden, it also
 specifies a default value to return if the user enters null input.  As
 in @code{read-from-minibuffer} it should be a string, a list of
-strings, or @code{nil} which is equivalent to an empty string.  When
+strings, or @code{nil}, which is equivalent to an empty string.  When
 @var{default} is a string, that string is the default value.  When it
 is a list of strings, the first string is the default value.  (All
 these strings are available to the user in the ``future minibuffer
-history.'')
+history''.)
 
 This function works by calling the
 @code{read-from-minibuffer} function:
@@ -202,16 +213,16 @@
 @end smallexample
 @end defun
 
address@hidden read-regexp prompt &optional default-value
address@hidden read-regexp prompt &optional default
 This function reads a regular expression as a string from the
 minibuffer and returns it.  The argument @var{prompt} is used as in
 @code{read-from-minibuffer}.  The keymap used is
 @code{minibuffer-local-map}, and @code{regexp-history} is used as the
 history list (@pxref{Minibuffer History, regexp-history}).
 
-The optional argument @var{default-value} specifies a default value to
+The optional argument @var{default} specifies a default value to
 return if the user enters null input; it should be a string, or
address@hidden which is equivalent to an empty string.
address@hidden, which is equivalent to an empty string.
 
 In addition, @code{read-regexp} collects a few useful candidates for
 input and passes them to @code{read-from-minibuffer}, to make them
@@ -235,9 +246,9 @@
 @end defun
 
 @defvar minibuffer-allow-text-properties
-If this variable is @code{nil}, then @code{read-from-minibuffer} strips
-all text properties from the minibuffer input before returning it.
-This variable also affects @code{read-string}.  However,
+If this variable is @code{nil}, then @code{read-from-minibuffer}
+and @code{read-string} strip all text properties from the minibuffer
+input before returning it.  However,
 @code{read-no-blanks-input} (see below), as well as
 @code{read-minibuffer} and related functions (@pxref{Object from
 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
@@ -275,6 +286,12 @@
 
 @item @kbd{M-r}
 @code{previous-matching-history-element}
+
address@hidden
address@hidden Does not seem worth/appropriate mentioning.
address@hidden @address@hidden
address@hidden
address@hidden ignore
 @end table
 @end defvar
 
@@ -305,6 +322,8 @@
 @end smallexample
 @end defun
 
address@hidden Slightly unfortunate name, suggesting it might be related to the
address@hidden Nextstep port...
 @defvar minibuffer-local-ns-map
 This built-in variable is the keymap used as the minibuffer local keymap
 in the function @code{read-no-blanks-input}.  By default, it makes the
@@ -441,7 +460,7 @@
 kinds of inputs.  It's the Lisp programmer's job to specify the right
 history list for each use of the minibuffer.
 
-  You specify a minibuffer history list with the optional @var{hist}
+  You specify a minibuffer history list with the optional @var{history}
 argument to @code{read-from-minibuffer} or @code{completing-read}.
 Here are the possible values for it:
 
@@ -457,7 +476,7 @@
 symbol @var{variable}.  @code{previous-history-element} will display
 the most recent element of the history list in the minibuffer.  If you
 specify a positive @var{startpos}, the minibuffer history functions
-behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
 history element currently shown in the minibuffer.
 
 For consistency, you should also specify that element of the history
@@ -465,7 +484,7 @@
 to the minibuffer input function (@pxref{Initial Input}).
 @end table
 
-  If you don't specify @var{hist}, then the default history list
+  If you don't specify @var{history}, then the default history list
 @code{minibuffer-history} is used.  For other standard history lists,
 see below.  You can also create your own history list variable; just
 initialize it to @code{nil} before the first use.
@@ -560,7 +579,7 @@
 @section Initial Input
 
 Several of the functions for minibuffer input have an argument called
address@hidden or @var{initial-contents}.  This is a mostly-deprecated
address@hidden  This is a mostly-deprecated
 feature for specifying that the minibuffer should start out with
 certain text, instead of empty as usual.
 
@@ -577,7 +596,7 @@
 
 There is just one situation where you should specify a string for an
 @var{initial} argument.  This is when you specify a cons cell for the
address@hidden or @var{history} argument.  @xref{Minibuffer History}.
address@hidden argument.  @xref{Minibuffer History}.
 
 @var{initial} can also be a cons cell of the form @code{(@var{string}
 . @var{position})}.  This means to insert @var{string} in the
@@ -663,7 +682,7 @@
 permissible completions are the elements of the alist that are either
 strings, or conses whose @sc{car} is a string or symbol.
 Symbols are converted to strings using @code{symbol-name}.  Other
-elements of the alist are ignored. (Remember that in Emacs Lisp, the
+elements of the alist are ignored.  (Remember that in Emacs Lisp, the
 elements of alists do not @emph{have} to be conses.)  In particular, a
 list of strings is allowed, even though we usually do not
 think of such lists as alists.
@@ -880,7 +899,7 @@
   This section describes the basic interface for reading from the
 minibuffer with completion.
 
address@hidden completing-read prompt collection &optional predicate 
require-match initial hist default inherit-input-method
address@hidden completing-read prompt collection &optional predicate 
require-match initial history default inherit-input-method
 This function reads a string in the minibuffer, assisting the user by
 providing completion.  It activates the minibuffer with prompt
 @var{prompt}, which must be a string.
@@ -935,13 +954,13 @@
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 address@hidden  @xref{Completion Commands}.
 
-The argument @var{hist} specifies which history list variable to use for
+The argument @var{history} specifies which history list variable to use for
 saving the input and for minibuffer history commands.  It defaults to
 @code{minibuffer-history}.  @xref{Minibuffer History}.
 
 The argument @var{initial} is mostly deprecated; we recommend using a
 address@hidden value only in conjunction with specifying a cons cell
-for @var{hist}.  @xref{Initial Input}.  For default input, use
+for @var{history}.  @xref{Initial Input}.  For default input, use
 @var{default} instead.
 
 If the argument @var{inherit-input-method} is address@hidden, then the
@@ -1545,17 +1564,17 @@
 @end example
 @end defopt
 
address@hidden read-shell-command prompt &optional initial-contents hist &rest 
args
address@hidden read-shell-command prompt &optional initial history &rest args
 This function reads a shell command from the minibuffer, prompting
 with @var{prompt} and providing intelligent completion.  It completes
 the first word of the command using candidates that are appropriate
 for command names, and the rest of the command words as file names.
 
 This function uses @code{minibuffer-local-shell-command-map} as the
-keymap for minibuffer input.  The @var{hist} argument specifies the
+keymap for minibuffer input.  The @var{history} argument specifies the
 history list to use; if is omitted or @code{nil}, it defaults to
 @code{shell-command-history} (@pxref{Minibuffer History,
-shell-command-history}).  The optional argument @var{initial-contents}
+shell-command-history}).  The optional argument @var{initial}
 specifies the initial content of the minibuffer (@pxref{Initial
 Input}).  The rest of @var{args}, if present, are used as the
 @var{default} and @var{inherit-input-method} arguments in
@@ -1727,9 +1746,10 @@
 
 @item (boundaries . @var{suffix})
 This specifies a @code{completion-boundaries} operation.  The function
-should return @code{(boundaries START . END)}, where START is the
-position of the beginning boundary in the specified string, and END is
-the position of the end boundary in SUFFIX.
+should return @code{(boundaries @var{start} . @var{end})}, where
address@hidden is the position of the beginning boundary in the specified
+string, and @var{end} is the position of the end boundary in
address@hidden
 
 @item metadata
 This specifies a request for information about the state of the
@@ -1891,7 +1911,7 @@
 This function asks the user a question, expecting input in the echo
 area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
 user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
-and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit,'' like
+and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit'', like
 @kbd{C-g}, because the question might look like a minibuffer and for
 that reason the user might try to use @kbd{C-]} to get out.  The answer
 is a single character, with no @key{RET} needed to terminate it.  Upper
@@ -1952,10 +1972,10 @@
 appears on the screen at a time.
 @end defun
 
address@hidden y-or-n-p-with-timeout prompt seconds default-value
address@hidden y-or-n-p-with-timeout prompt seconds default
 Like @code{y-or-n-p}, except that if the user fails to answer within
 @var{seconds} seconds, this function stops waiting and returns
address@hidden  It works by setting up a timer; see @ref{Timers}.
address@hidden  It works by setting up a timer; see @ref{Timers}.
 The argument @var{seconds} may be an integer or a floating point number.
 @end defun
 
@@ -2081,7 +2101,7 @@
 
 When the user responds with @var{char}, @code{map-y-or-n-p} calls
 @var{function}.  If it returns address@hidden, the object is considered
-``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
+``acted upon'', and @code{map-y-or-n-p} advances to the next object in
 @var{list}.  If it returns @code{nil}, the prompt is repeated for the
 same object.