Revision: miles@gnu.org--gnu-2004/emacs--unicode--0--patch-15

Merge from emacs--cvs-trunk--0

Patches applied:

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-218
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-220
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-221
   Restore deleted tagline in etc/TUTORIAL.ru

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-222
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-228
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-229
   Remove TeX output files from the archive

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-230
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-247
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-248
   src/lisp.h (CYCLE_CHECK): Macro moved from xfaces.c

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-249
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-256
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-258
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-263
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-264
   Update from CVS: lispref/display.texi: emacs -> Emacs.

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-265
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-274
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-275
   Update from CVS: man/makefile.w32-in: Revert last change

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-276
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-295
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-296
   Allow restarting an existing debugger session that's exited

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-297
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-299
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-300
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-327
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-328
   Update from CVS: src/.gdbinit (xsymbol): Fix last change.

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-329
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-344
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-345
   Tweak source regexps so that building in place won't cause problems

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-346
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-351
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-352
   Update from CVS: lisp/flymake.el: New file.

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-353
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-361
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-362
   Support " [...]" style defaults in minibuffer-electric-default-mode

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-363
   (read-number): Use canonical format for default in prompt.

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-364
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-367
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-368
   Improve display-supports-face-attributes-p on non-ttys

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-369
   Rewrite face-differs-from-default-p

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-370
   Move `display-supports-face-attributes-p' entirely into C code

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-371
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-372
   Simplify face-differs-from-default-p; don't consider :stipple.

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-373
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-374
   (tty_supports_face_attributes_p): Ensure attributes differ from default

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-375
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-376
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-377
   (Fdisplay_supports_face_attributes_p): Work around bootstrapping problem

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-378
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-380
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-381
   Face merging cleanups

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-382
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-384
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-385
   src/xfaces.c (push_named_merge_point): Return 0 if a cycle is detected

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-386
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-395
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-396
   Tweak arch tagging to make build/install-in-place less annoying

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-397
   Work around vc-arch problems when building eshell

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-398
   Tweak permissions

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-399
   Tweak directory permissions

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-400
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-401
   More build-in-place tweaking of arch tagging

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-402
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-403
   Yet more build-in-place tweaking of arch tagging

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-404
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-409
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-410
   Make sure image types are initialized for lookup too

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-411
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-416
   Update from CVS

1 files changed, 52 insertions, 38 deletions

diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 0c56f9d4622..a2695eab6b9 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -23,6 +23,7 @@ for reading an argument.
 * Object from Minibuffer::    How to read a Lisp object or expression.
 * Minibuffer History::	      Recording previous minibuffer inputs
 				so the user can reuse them.
+* Initial Input::             Specifying initial contents for the minibuffer.
 * Completion::                How to invoke and customize completion.
 * Yes-or-No Queries::         Asking a question with a simple answer.
 * Multiple Queries::	      Asking a series of similar questions.
@@ -168,25 +169,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text
 Representations}) from whichever buffer was current before entering the
 minibuffer.
 
-If @var{initial-contents} is a string, @code{read-from-minibuffer}
-inserts it into the minibuffer, leaving point at the end, before the
-user starts to edit the text.  The minibuffer appears with this text as
-its initial contents.
-
-Alternatively, @var{initial-contents} can be a cons cell of the form
-@code{(@var{string} . @var{position})}.  This means to insert
-@var{string} in the minibuffer but put point at @emph{one-indexed}
-@var{position} in the minibuffer, rather than at the end.  Any integer
-value less or equal to one puts point at the beginning of the string.
-
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for more or less the
-same job.  It does not make sense to use both features in a single call
-to @code{read-from-minibuffer}.  In general, we recommend using
-@var{default}, since this permits the user to insert the default value
-when it is wanted, but does not burden the user with deleting it from
-the minibuffer on other occasions.  For an exception to this rule,
-see @ref{Minibuffer History}.
+Use of @var{initial-contents} is mostly deprecated; we recommend using
+a non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.
 @end defun
 
 @defun read-string prompt &optional initial history default inherit-input-method
@@ -440,9 +425,11 @@ 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
-history element currently shown in the minibuffer.  For consistency,
-you should also specify that element of the history as the initial
-minibuffer contents.
+history element currently shown in the minibuffer.
+
+For consistency, you should also specify that element of the history
+as the initial minibuffer contents, using the @var{initial} argument
+to the minibuffer input function (@pxref{Initial Input}).
 @end table
 
   If you don't specify @var{hist}, then the default history list
@@ -506,6 +493,45 @@ A history list for arguments that are shell commands.
 A history list for arguments that are Lisp expressions to evaluate.
 @end defvar
 
+@node Initial Input
+@section Initial Input
+
+Several of the functions for minibuffer input have an argument called
+@var{initial} or @var{initial-contents}.  This is a mostly-deprecated
+feature for specifiying that the minibuffer should start out with
+certain text, instead of empty as usual.
+
+If @var{initial} is a string, the minibuffer starts out containing the
+text of the string, with point at the end, when the user starts to
+edit the text.  If the user simply types @key{RET} to exit the
+minibuffer, it will use the initial input string to determine the
+value to return.
+
+@strong{We discourage use of a non-@code{nil} value for
+@var{initial}}, because initial input is an intrusive interface.
+History lists and default values provide a much more convenient method
+to offer useful default inputs to the user.
+
+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
+@var{hist} or @var{history} 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
+minibuffer but put point at @var{position} within the string's text.
+
+As a historical accident, @var{position} was implemented
+inconsistently in different functions.  In @code{completing-read},
+@var{position}'s value is interpreted as origin-zero; that is, a value
+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,
+etc.
+
+Use of a cons cell as the value for @var{initial} arguments is
+deprecated in user code.
+ 
 @node Completion
 @section Completion
 @cindex completion
@@ -797,22 +823,10 @@ The argument @var{hist} 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}.
 
-If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
-into the minibuffer as part of the input, with point at the end.  Then
-it allows the user to edit the input, providing several commands to
-attempt completion.  @var{initial} can also be a cons cell of the form
-@code{(@var{string} .  @var{position})}.  In that case, point is put at
-@emph{zero-indexed} position @var{position} in @var{string}.  Note
-that this is different from @code{read-from-minibuffer} and related
-functions, which use a one-indexed position.  In most cases, we
-recommend using @var{default}, and not @var{initial}.
-
-@strong{We discourage use of a non-@code{nil} value for
-@var{initial}}, because it is an intrusive interface.  The history
-list feature (which did not exist when we introduced @var{initial})
-offers a far more convenient and general way for the user to get the
-default and edit it, and it is always available.  For an exception to
-this rule, see @ref{Minibuffer History}.
+The argument @var{initial} is mostly deprecated; we recommend using a
+non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.  For default input, use
+@var{default} instead.
 
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
 minibuffer inherits the current input method (@pxref{Input