Merge from emacs-24 branch

11 files changed, 658 insertions, 448 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b5a25cb1c51..284a1230a83 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,75 @@
+2012-04-20  Chong Yidong  <cyd@gnu.org>
+
+        * processes.texi (Asynchronous Processes): Mention nil argument to
+        start-process.
+
+2012-04-20  Glenn Morris  <rgm@gnu.org>
+
+        * minibuf.texi (Basic Completion): No need to describe obarrays here.
+        Don't mention obsolete `nospace' argument of all-completions.
+        (Minibuffer Completion, Completion Commands, Reading File Names)
+        (Completion Variables): Copyedits.
+        (Completion Commands): Mention parent keymaps.
+        Remove obsolete minibuffer-local-filename-must-match-map.
+        (High-Level Completion): Remove read-variable's almost
+        word-for-word duplication of read-command.
+        * elisp.texi, vol1.texi, vol2.texi, minibuf.texi (Completion):
+        Update "High-Level Completion" description.
+
+2012-04-19  Glenn Morris  <rgm@gnu.org>
+
+        * 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.
+        Mention minibuffer-inactive-mode.
+        (Text from Minibuffer): Copyedits.
+        (Minibuffer History, Programmed Completion): Fix @var usage.
+        (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.
+
+2012-04-18  Glenn Morris  <rgm@gnu.org>
+
+        * processes.texi (Serial Ports, Byte Packing, Bindat Spec)
+        (Bindat Functions): Copyedits.
+
+2012-04-18  Christopher Schmidt  <christopher@ch.ristopher.com>
+
+        * files.texi (Saving Buffers): Document `visit and `visit-save'
+        values of require-final-newline.
+
+2012-04-18  Glenn Morris  <rgm@gnu.org>
+
+        * processes.texi (Output from Processes, Filter Functions):
+        Mention waiting-for-user-input-p.
+        (Sentinels, Query Before Exit, System Processes, Transaction Queues):
+        (Network Servers, Datagrams, Network Processes, Network Options)
+        (Network Feature Testing, Serial Ports): Copyedits.
+        (Network): Add encrypted network overview paragraph.
+        Cross-reference the Emacs-GnuTLS manual.  Use @acronym.
+
+2012-04-17  Chong Yidong  <cyd@gnu.org>
+
+        * help.texi (Keys in Documentation): Mention :advertised-binding.
+
+        * keymaps.texi (Menu Bar): Move most of the :advertised-binding
+        description to help.texi.
+
+2012-04-16  Glenn Morris  <rgm@gnu.org>
+
+        * processes.texi (Process Information, Input to Processes)
+        (Signals to Processes, Output from Processes, Process Buffers)
+        (Filter Functions, Decoding Output): Copyedits.
+        (Accepting Output): Discourage use of `millisec' argument.
+
 2012-04-15  Glenn Morris  <rgm@gnu.org>
 
         * processes.texi (Processes, Subprocess Creation, Shell Arguments):
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 76397556b01..4319d5eddda 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -637,8 +637,8 @@ Minibuffers
 * 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 Contents::     How such commands access the minibuffer text.
 * Minibuffer Windows::      Operating on the special minibuffer windows.
+* Minibuffer Contents::     How such commands access the minibuffer text.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 
@@ -648,7 +648,7 @@ Completion
 * Minibuffer Completion::   Invoking the minibuffer with completion.
 * Completion Commands::     Minibuffer commands that do completion.
 * High-Level Completion::   Convenient special cases of completion
-                              (reading buffer name, file name, etc.).
+                              (reading buffer names, variable names, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
 * Completion Variables::    Variables controlling completion behavior.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ca4504ca967..3597d9f80c4 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -489,11 +489,13 @@ in particular buffers.
 @defopt require-final-newline
 This variable determines whether files may be written out that do
 @emph{not} end with a newline.  If the value of the variable is
-@code{t}, then @code{save-buffer} silently adds a newline at the end of
-the file whenever the buffer being saved does not already end in one.
-If the value of the variable is non-@code{nil}, but not @code{t}, then
-@code{save-buffer} asks the user whether to add a newline each time the
-case arises.
+@code{t}, then @code{save-buffer} silently adds a newline at the end
+of the buffer whenever it does not already end in one.  If the value
+is @code{visit}, Emacs adds a missing newline just after it visits the
+file.  If the value is @code{visit-save}, Emacs adds a missing newline
+both on visiting and on saving.  For any other non-@code{nil} value,
+@code{save-buffer} asks the user whether to add a newline each time
+the case arises.
 
 If the value of the variable is @code{nil}, then @code{save-buffer}
 doesn't add newlines at all.  @code{nil} is the default value, but a few
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 769b4292d30..5dfb2b05ff8 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -347,6 +347,21 @@ This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
 This permits display of documentation that refers accurately to the
 user's own customized key bindings.
+
+@cindex advertised binding
+If a command has multiple bindings, this function normally uses the
+first one it finds.  You can specify one particular key binding by
+assigning an @code{:advertised-binding} symbol property to the
+command, like this:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+The @code{:advertised-binding} property also affects the binding shown
+in menu items (@pxref{Menu Bar}).  The property is ignored if it
+specifies a key binding that the command does not actually have.
 @end defun
 
   Here are examples of the special sequences:
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index f8befb8fd90..b12752fdeea 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2548,17 +2548,8 @@ the same command (if such a key binding exists).  This serves as a
 convenient hint for users who do not know the key binding.  If a
 command has multiple bindings, Emacs normally displays the first one
 it finds.  You can specify one particular key binding by assigning an
-@code{:advertised-binding} symbol property to the command.  For
-instance, the following tells Emacs to show @kbd{C-/} for the
-@code{undo} menu item:
-
-@smallexample
-(put 'undo :advertised-binding [?\C-/])
-@end smallexample
-
-@noindent
-If the @code{:advertised-binding} property specifies a key binding
-that the command does not actually have, it is ignored.
+@code{:advertised-binding} symbol property to the command.  @xref{Keys
+in Documentation}.
 
 @node Tool Bar
 @subsection Tool bars
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 1be21f5d974..c840eb6ded0 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -29,8 +29,8 @@ argument.
 * 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 Contents::       How such commands access the minibuffer text.
 * Minibuffer Windows::        Operating on the special minibuffer windows.
+* Minibuffer Contents::       How such commands access the minibuffer text.
 * Recursive Mini::            Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::           Various customization hooks and variables.
 @end menu
@@ -59,8 +59,10 @@ boundary between the prompt and the actual text.
 
   The minibuffer's window is normally a single line; it grows
 automatically if the contents require more space.  You can explicitly
+@c 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
+@c 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
@@ -72,9 +74,9 @@ of variables such as @code{this-command} and @code{last-command}
 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
-@w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
+@w{@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
@@ -90,6 +92,12 @@ to be done.  @xref{Text from Minibuffer}, for the non-completion
 minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
 local maps for completion.
 
+@cindex inactive minibuffer
+  When a minibuffer is inactive, its major mode is
+@code{minibuffer-inactive-mode}, with keymap
+@code{minibuffer-inactive-mode-map}.  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.
@@ -110,7 +118,7 @@ middle of a Lisp function.  Instead, do all minibuffer input as part of
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
+@defun 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 non-@code{nil}, then it uses
@@ -118,8 +126,8 @@ string; however, if @var{read} is non-@code{nil}, then it uses
 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
@@ -131,7 +139,7 @@ reads the text and returns the resulting Lisp object, unevaluated.
 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 non-@code{nil}, then @var{default} is also used
 as the input to @code{read}, if the user enters empty input.
@@ -148,12 +156,13 @@ value of @code{minibuffer-local-map} is used as the keymap.  Specifying
 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
-non-@code{nil}, then the string which is returned includes whatever text
+non-@code{nil}, 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.
 
@@ -163,9 +172,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text
 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 non-@code{nil} 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
@@ -178,11 +187,11 @@ The optional argument @var{default} is used as in
 @code{read-from-minibuffer}, except that, if non-@code{nil}, 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:
@@ -201,16 +210,16 @@ This function works by calling the
 @end smallexample
 @end defun
 
-@defun read-regexp prompt &optional default-value
+@defun 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
-@code{nil} which is equivalent to an empty string.
+@code{nil}, 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
@@ -234,9 +243,9 @@ function, after computing the list of defaults as described above.
 @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
@@ -274,6 +283,12 @@ default, it makes the following bindings:
 
 @item @kbd{M-r}
 @code{previous-matching-history-element}
+
+@ignore
+@c Does not seem worth/appropriate mentioning.
+@item @kbd{C-@key{TAB}}
+@code{file-cache-minibuffer-complete}
+@end ignore
 @end table
 @end defvar
 
@@ -304,6 +319,8 @@ This function discards text properties, regardless of the value of
 @end smallexample
 @end defun
 
+@c Slightly unfortunate name, suggesting it might be related to the
+@c 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
@@ -388,23 +405,16 @@ This function simply evaluates the result of a call to
 @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
-@code{read} 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
@@ -424,7 +434,6 @@ Please edit: (forward-word 1)@point{}
 @noindent
 Typing @key{RET} right away would exit the minibuffer and evaluate the
 expression, thus moving point forward one word.
-@code{edit-and-eval-command} returns @code{nil} in this example.
 @end defun
 
 @node Minibuffer History
@@ -440,7 +449,7 @@ is a list of strings (previous inputs), most recent first.
 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:
 
@@ -456,7 +465,7 @@ Specifying 0 for @var{startpos} is equivalent to just specifying the
 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
@@ -464,7 +473,7 @@ 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
+  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.
@@ -503,15 +512,15 @@ If the value of this variable is @code{nil}, standard functions that
 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 non-@code{nil} value.
+non-@code{nil}.
 @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 non-@code{nil}
+@code{history-length} property, it overrides this variable for that
 particular history list.
 @end defopt
 
@@ -555,11 +564,19 @@ A history list for arguments that are shell commands.
 A history list for arguments that are Lisp expressions to evaluate.
 @end defvar
 
+@defvar face-name-history
+A history list for arguments that are faces.
+@end defvar
+
+@c Less common: coding-system-history, input-method-history,
+@c command-history, grep-history, grep-find-history,
+@c read-envvar-name-history, setenv-history, yes-or-no-p-history.
+
 @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
+@var{initial}.  This is a mostly-deprecated
 feature for specifying that the minibuffer should start out with
 certain text, instead of empty as usual.
 
@@ -576,7 +593,7 @@ 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{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
@@ -588,11 +605,10 @@ inconsistently in different functions.  In @code{completing-read},
 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
@@ -603,6 +619,7 @@ starting from an abbreviation for it.  Completion works by comparing the
 user's input against a list of valid names and determining how much of
 the name is determined uniquely by what the user has typed.  For
 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+@c "This is the sort of English up with which I will not put."
 type the first few letters of the name of the buffer to which you wish
 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
 extends the name as far as it can.
@@ -627,7 +644,7 @@ for reading certain kinds of names with completion.
 * Minibuffer Completion::  Invoking the minibuffer with completion.
 * Completion Commands::    Minibuffer commands that do completion.
 * High-Level Completion::  Convenient special cases of completion
-                             (reading buffer name, file name, etc.).
+                             (reading buffer names, variable names, etc.).
 * Reading File Names::     Using completion to read file names and
                              shell commands.
 * Completion Variables::   Variables controlling completion behavior.
@@ -662,20 +679,14 @@ If @var{collection} is an alist (@pxref{Association Lists}), the
 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.
 
 @cindex obarray in completion
 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
-of all symbols in the obarray form the set of permissible completions.  The
-global variable @code{obarray} holds an obarray containing the names of
-all interned Lisp symbols.
-
-Note that the only valid way to make a new obarray is to create it
-empty and then add symbols to it one by one using @code{intern}.
-Also, you cannot intern a given symbol in more than one obarray.
+of all symbols in the obarray form the set of permissible completions.
 
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
@@ -756,16 +767,20 @@ too short).  Both of those begin with the string @samp{foobar}.
 @end smallexample
 @end defun
 
-@defun all-completions string collection &optional predicate nospace
+@c Removed obsolete argument nospace.
+@defun all-completions string collection &optional predicate
 This function returns a list of all possible completions of
-@var{string}.  The arguments to this function (aside from
-@var{nospace}) are the same as those of @code{try-completion}.  Also,
-this function uses @code{completion-regexp-list} in the same way that
+@var{string}.  The arguments to this function
+@c (aside from @var{nospace})
+are the same as those of @code{try-completion}, and it 
+uses @code{completion-regexp-list} in the same way that
 @code{try-completion} does.
 
+@ignore
 The optional argument @var{nospace} is obsolete.  If it is
 non-@code{nil}, completions that start with a space are ignored unless
 @var{string} starts with a space.
+@end ignore
 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
@@ -835,7 +850,7 @@ pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
 @end defun
 
 If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a non-@code{nil}
+variable as ``risky'' by giving it a non-@code{nil}
 @code{risky-local-variable} property.  @xref{File Local Variables}.
 
 @defvar completion-ignore-case
@@ -864,7 +879,7 @@ proper value is done the first time you do completion using @var{var}.
 It is done by calling @var{fun} with no arguments.  The
 value @var{fun} returns becomes the permanent value of @var{var}.
 
-Here is a usage example:
+Here is an example:
 
 @smallexample
 (defvar foo (lazy-completion-table foo make-my-alist))
@@ -879,7 +894,7 @@ Here is a usage example:
   This section describes the basic interface for reading from the
 minibuffer with completion.
 
-@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
+@defun 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.
@@ -934,13 +949,13 @@ The function @code{completing-read} uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 non-@code{nil}.  @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
 non-@code{nil} 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 non-@code{nil}, then the
@@ -949,7 +964,7 @@ Methods}) and the setting of @code{enable-multibyte-characters}
 (@pxref{Text Representations}) from whichever buffer was current before
 entering the minibuffer.
 
-If the built-in variable @code{completion-ignore-case} is
+If the variable @code{completion-ignore-case} is
 non-@code{nil}, completion ignores case when comparing the input
 against the possible matches.  @xref{Basic Completion}.  In this mode
 of operation, @var{predicate} must also ignore case, or you will get
@@ -1082,8 +1097,8 @@ uses this to highlight text in the completion list for better visual
 feedback.  This is not needed in the minibuffer; for minibuffer
 completion, you can pass @code{nil}.
 
-This function is called by @code{minibuffer-completion-help}.  The
-most common way to use it is together with
+This function is called by @code{minibuffer-completion-help}.  A
+common way to use it is together with
 @code{with-output-to-temp-buffer}, like this:
 
 @example
@@ -1117,7 +1132,7 @@ keymap makes the following bindings:
 @end table
 
 @noindent
-with other characters bound as in @code{minibuffer-local-map}
+and uses @code{minibuffer-local-map} as its parent keymap
 (@pxref{Definition of minibuffer-local-map}).
 @end defvar
 
@@ -1129,15 +1144,6 @@ minibuffer unconditionally.  By default, this keymap makes the following
 bindings:
 
 @table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
 @item @kbd{C-j}
 @code{minibuffer-complete-and-exit}
 
@@ -1146,25 +1152,21 @@ bindings:
 @end table
 
 @noindent
-with other characters bound as in @code{minibuffer-local-map}.
+and uses @code{minibuffer-local-completion-map} as its parent keymap.
 @end defvar
 
 @defvar minibuffer-local-filename-completion-map
-This is like @code{minibuffer-local-completion-map}
-except that it does not bind @key{SPC}.  This keymap is used by the
-function @code{read-file-name}.
+This is a sparse keymap that simply unbinds @key{SPC}; because
+filenames can contain spaces.  The function @code{read-file-name}
+combines this keymap with either @code{minibuffer-local-completion-map}
+or @code{minibuffer-local-must-match-map}.
 @end defvar
 
-@defvar minibuffer-local-filename-must-match-map
-This is like @code{minibuffer-local-must-match-map}
-except that it does not bind @key{SPC}.  This keymap is used by the
-function @code{read-file-name}.
-@end defvar
 
 @node High-Level Completion
 @subsection High-Level Completion Functions
 
-  This section describes the higher-level convenient functions for
+  This section describes the higher-level convenience functions for
 reading certain sorts of names with completion.
 
   In most cases, you should not call these functions in the middle of a
@@ -1238,7 +1240,7 @@ for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
 The argument @var{default} specifies what to return if the user enters
 null input.  It can be a symbol, a string or a list of strings.  If it
 is a string, @code{read-command} interns it before returning it.
-If it is a list, @code{read-command} returns the first element of this list.
+If it is a list, @code{read-command} interns the first element of this list.
 If @var{default} is @code{nil}, that means no default has been
 specified; then if the user enters null input, the return value is
 @code{(intern "")}, that is, a symbol whose name is an empty string.
@@ -1280,51 +1282,11 @@ complete in the set of extant Lisp symbols, and it uses the
 
 @defun read-variable prompt &optional default
 @anchor{Definition of read-variable}
-This function reads the name of a user variable and returns it as a
-symbol.
-
-The argument @var{default} specifies the default value to return if
-the user enters null input.  It can be a symbol, a string, or a list
-of strings.  If it is a string, @code{read-variable} interns it to
-make the default value.  If it is a list, @code{read-variable} interns
-the first element.  If @var{default} is @code{nil}, that means no
-default has been specified; then if the user enters null input, the
-return value is @code{(intern "")}.
-
-@example
-@group
-(read-variable "Variable name? ")
-
-;; @r{After evaluation of the preceding expression,}
-;;   @r{the following prompt appears,}
-;;   @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Variable name? @point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
-returns @code{fill-prefix}.
-
-In general, @code{read-variable} is similar to @code{read-command},
-but uses the predicate @code{custom-variable-p} instead of
-@code{commandp}:
-
-@cindex @code{custom-variable-p} example
-@example
-@group
-(read-variable @var{prompt})
-@equiv{}
-(intern
- (completing-read @var{prompt} obarray
-                  'custom-variable-p t nil))
-@end group
-@end example
+This function reads the name of a customizable variable and returns it
+as a symbol.  Its arguments have the same form as those of
+@code{read-command}.  It behaves just like @code{read-command}, except
+that it uses the predicate @code{custom-variable-p} instead of
+@code{commandp}.
 @end defun
 
 @deffn Command read-color &optional prompt convert allow-empty display
@@ -1342,7 +1304,7 @@ minibuffer.  However, when called interactively or if the optional
 argument @var{convert} is non-@code{nil}, it converts any input color
 name into the corresponding RGB value string and instead returns that.
 This function requires a valid color specification to be input.
-Empty color names are allowed when @code{allow-empty} is
+Empty color names are allowed when @var{allow-empty} is
 non-@code{nil} and the user enters null input.
 
 Interactively, or when @var{display} is non-@code{nil}, the return
@@ -1360,7 +1322,7 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
 
   The high-level completion functions @code{read-file-name},
 @code{read-directory-name}, and @code{read-shell-command} are designed
-to read file names, directory names, and shell commands respectively.
+to read file names, directory names, and shell commands, respectively.
 They provide special features, including automatic insertion of the
 default directory.
 
@@ -1369,15 +1331,29 @@ This function reads a file name, prompting with @var{prompt} and
 providing completion.
 
 As an exception, this function reads a file name using a graphical
-file dialog instead of the minibuffer, if (i) it is invoked via a
-mouse command, and (ii) the selected frame is on a graphical display
-supporting such dialogs, and (iii) the variable @code{use-dialog-box}
-is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
-Emacs Manual}), and (iv) the @var{directory} argument, described
-below, does not specify a remote file (@pxref{Remote Files,, Remote
-Files, emacs, The GNU Emacs Manual}).  The exact behavior when using a
-graphical file dialog is platform-dependent.  Here, we simply document
-the behavior when using the minibuffer.
+file dialog instead of the minibuffer, if all of the following are
+true:
+
+@enumerate
+@item
+It is invoked via a mouse command.
+
+@item
+The selected frame is on a graphical display supporting such dialogs.
+
+@item
+The variable @code{use-dialog-box} is non-@code{nil}.
+@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
+
+@item
+The @var{directory} argument, described below, does not specify a
+remote file.  @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
+@end enumerate
+
+@noindent
+The exact behavior when using a graphical file dialog is
+platform-dependent.  Here, we simply document the behavior when using
+the minibuffer.
 
 @code{read-file-name} does not automatically expand the returned file
 name.  You must call @code{expand-file-name} yourself if an absolute
@@ -1388,7 +1364,7 @@ The optional argument @var{require-match} has the same meaning as in
 
 The argument @var{directory} specifies the directory to use for
 completing relative file names.  It should be an absolute directory
-name.  If @code{insert-default-directory} is non-@code{nil},
+name.  If the variable @code{insert-default-directory} is non-@code{nil},
 @var{directory} is also inserted in the minibuffer as initial input.
 It defaults to the current buffer's value of @code{default-directory}.
 
@@ -1396,9 +1372,9 @@ If you specify @var{initial}, that is an initial file name to insert
 in the buffer (after @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for
 @var{initial} is @code{nil}---don't insert any file name.  To see what
-@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
-note:} we recommend using @var{default} rather than @var{initial} in
-most cases.
+@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
+a file.  @strong{Please note:} we recommend using @var{default} rather
+than @var{initial} in most cases.
 
 If @var{default} is non-@code{nil}, then the function returns
 @var{default} if the user exits the minibuffer with the same non-empty
@@ -1501,7 +1477,7 @@ use the code letters @samp{f} or @samp{F} in their interactive form.
 @xref{Interactive Codes,, Code Characters for interactive}.)  Its
 value controls whether @code{read-file-name} starts by placing the
 name of the default directory in the minibuffer, plus the initial file
-name if any.  If the value of this variable is @code{nil}, then
+name, if any.  If the value of this variable is @code{nil}, then
 @code{read-file-name} does not place any initial input in the
 minibuffer (unless you specify initial input with the @var{initial}
 argument).  In that case, the default directory is still used for
@@ -1544,17 +1520,17 @@ The file is @point{}
 @end example
 @end defopt
 
-@defun read-shell-command prompt &optional initial-contents hist &rest args
+@defun 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
@@ -1563,20 +1539,22 @@ Input}).  The rest of @var{args}, if present, are used as the
 
 @defvar minibuffer-local-shell-command-map
 This keymap is used by @code{read-shell-command} for completing
-command and file names that are part of a shell command.
+command and file names that are part of a shell command.  It uses
+@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
+to @code{completion-at-point}.
 @end defvar
 
 @node Completion Variables
 @subsection Completion Variables
 
-  Here are some variables which can be used to alter the default
+  Here are some variables that can be used to alter the default
 completion behavior.
 
 @cindex completion styles
 @defopt completion-styles
 The value of this variable is a list of completion style (symbols) to
 use for performing completion.  A @dfn{completion style} is a set of
-rules for generating completions.  Each symbol in occurring this list
+rules for generating completions.  Each symbol occurring this list
 must have a corresponding entry in @code{completion-styles-alist}.
 @end defopt
 
@@ -1623,13 +1601,14 @@ description of the available completion styles.
 @defopt completion-category-overrides
 This variable specifies special completion styles and other completion
 behaviors to use when completing certain types of text.  Its value
-should be a list of the form @code{(@var{category} . @var{alist})}.
-@var{category} is a symbol describing what is being completed;
-currently, the @code{buffer} and @code{file} categories are defined,
-but others can be defined via specialized completion functions
-(@pxref{Programmed Completion}).  @var{alist} is an association list
-describing how completion should behave for the corresponding
-category.  The following alist keys are supported:
+should be an alist with elements of the form @code{(@var{category}
+. @var{alist})}.  @var{category} is a symbol describing what is being
+completed; currently, the @code{buffer}, @code{file}, and
+@code{unicode-name} categories are defined, but others can be defined
+via specialized completion functions (@pxref{Programmed Completion}).
+@var{alist} is an association list describing how completion should
+behave for the corresponding category.  The following alist keys are
+supported:
 
 @table @code
 @item styles
@@ -1662,7 +1641,7 @@ the completion.
 The value should be a function to run after performing completion.
 The function should accept two arguments, @var{string} and
 @var{status}, where @var{string} is the text to which the field was
-completed and @var{status} indicates what kind of operation happened:
+completed, and @var{status} indicates what kind of operation happened:
 @code{finished} if text is now complete, @code{sole} if the text
 cannot be further completed but completion is not finished, or
 @code{exact} if the text is a valid completion but may be further
@@ -1726,9 +1705,10 @@ some completion alternative; @code{nil} otherwise.
 
 @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
+@var{start} is the position of the beginning boundary in the specified
+string, and @var{end} is the position of the end boundary in
+@var{suffix}.
 
 @item metadata
 This specifies a request for information about the state of the
@@ -1773,7 +1753,7 @@ the same as for @code{display-sort-function}.
 
 @defun completion-table-dynamic function
 This function is a convenient way to write a function that can act as
-programmed completion function.  The argument @var{function} should be
+a programmed completion function.  The argument @var{function} should be
 a function that takes one argument, a string, and returns an alist of
 possible completions of it.  You can think of
 @code{completion-table-dynamic} as a transducer between that interface
@@ -1827,7 +1807,7 @@ satisfy.
 
 @item :exclusive
 If the value is @code{no}, then if the completion table fails to match
-the text at point, then @code{completion-at-point} moves on to the
+the text at point, @code{completion-at-point} moves on to the
 next function in @code{completion-at-point-functions} instead of
 reporting a completion failure.
 @end table
@@ -1841,7 +1821,7 @@ old code to using @code{completion-at-point}.
 The first function in @code{completion-at-point-functions} to return a
 non-@code{nil} value is used by @code{completion-at-point}.  The
 remaining functions are not called.  The exception to this is when
-there is a @code{:exclusive} specification, as described above.
+there is an @code{:exclusive} specification, as described above.
 @end defvar
 
   The following function provides a convenient way to perform
@@ -1879,7 +1859,7 @@ answer.
 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.
 
@@ -1890,7 +1870,7 @@ the call.
 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
@@ -1914,12 +1894,16 @@ hardwired.  The keymap @code{query-replace-map} specifies them.
 In the following example, the user first types @kbd{q}, which is
 invalid.  At the next prompt the user types @kbd{y}.
 
+@c Need an interactive example, because otherwise the return value
+@c 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
@@ -1951,10 +1935,10 @@ We show successive lines of echo area messages, but only one actually
 appears on the screen at a time.
 @end defun
 
-@defun y-or-n-p-with-timeout prompt seconds default-value
+@defun 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
-@var{default-value}.  It works by setting up a timer; see @ref{Timers}.
+@var{default}.  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
 
@@ -2022,7 +2006,7 @@ single-character answer in the echo area for each one.
 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:
@@ -2038,8 +2022,8 @@ where @var{object} is the next object to ask about (as obtained from
 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
@@ -2080,7 +2064,7 @@ answer); @var{function} is a function of one argument (an object from
 
 When the user responds with @var{char}, @code{map-y-or-n-p} calls
 @var{function}.  If it returns non-@code{nil}, 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.
 
@@ -2092,12 +2076,14 @@ If @code{map-y-or-n-p} is called in a command that was invoked 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.  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
+@c FIXME  An example of this would be more useful than all the
+@c preceding examples of simple things.
 
 @node Reading a Password
 @section Reading a Password
@@ -2160,6 +2146,19 @@ This command replaces the minibuffer contents with the value of the
 regular expression).
 @end deffn
 
+@deffn Command previous-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+@deffn Command next-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+
 @node Minibuffer Windows
 @section Minibuffer Windows
 @cindex minibuffer windows
@@ -2169,7 +2168,7 @@ and test whether they are active.
 
 @defun active-minibuffer-window
 This function returns the currently active minibuffer window, or
-@code{nil} if none is currently active.
+@code{nil} if there is none.
 @end defun
 
 @defun minibuffer-window &optional frame
@@ -2202,8 +2201,8 @@ there can be more than one minibuffer window if there is more than one
 frame.
 
 @defun minibuffer-window-active-p window
-This function returns non-@code{nil} if @var{window}, assumed to be
-a minibuffer window, is currently active.
+This function returns non-@code{nil} if @var{window} is the currently
+active minibuffer window.
 @end defun
 
 @node Minibuffer Contents
@@ -2318,7 +2317,7 @@ minibuffer, it scrolls this window.
 @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
@@ -2329,10 +2328,19 @@ windows.  If a float, it specifies a fraction of the height of the
 frame.  If an integer, it specifies a number of lines.
 @end defopt
 
+@vindex 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 non-@code{nil}, 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
+@code{minibuffer-message-timeout} specifies the number of seconds to
+wait in the absence of input.  It defaults to 2.  If @var{args} is
+non-@code{nil}, the actual message is obtained by passing @var{string}
+and @var{args} through @code{format}.  @xref{Formatting Strings}.
 @end defun
+
+@deffn 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}.
+@end deffn
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 5a08fc9711e..71736584865 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -561,8 +561,13 @@ already exists, then @var{name} is modified (by appending @samp{<1>},
 etc.) to be unique.  The buffer @var{buffer-or-name} is the buffer to
 associate with the process.
 
+If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
+and associates its input and output with @var{buffer-or-name}, without
+creating a subprocess.  In that case, the remaining arguments
+@var{args} are ignored.
+
 The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
+line arguments for the subprocess.
 
 In the example below, the first process is started and runs (rather,
 sleeps) for 100 seconds (the output buffer @samp{foo} is created
@@ -728,17 +733,17 @@ happen sooner or later).
 @section Process Information
 
   Several functions return information about processes.
-@code{list-processes} is provided for interactive use.
 
-@deffn Command list-processes &optional query-only
+@deffn Command list-processes &optional query-only buffer
 This command displays a listing of all living processes.  In addition,
 it finally deletes any process whose status was @samp{Exited} or
 @samp{Signaled}.  It returns @code{nil}.
 
-The processes are shown in a buffer named @file{*Process List*}, whose
-major mode is named Process Menu mode.
+The processes are shown in a buffer named @file{*Process List*}
+(unless you specify otherwise using the optional argument @var{buffer}),
+whose major mode is Process Menu mode.
 
-If @var{query-only} is non-@code{nil} then it lists only processes
+If @var{query-only} is non-@code{nil}, it only lists processes
 whose query flag is non-@code{nil}.  @xref{Query Before Exit}.
 @end deffn
 
@@ -754,8 +759,8 @@ This function returns a list of all processes that have not been deleted.
 @end defun
 
 @defun get-process name
-This function returns the process named @var{name}, or @code{nil} if
-there is none.  An error is signaled if @var{name} is not a string.
+This function returns the process named @var{name} (a string), or
+@code{nil} if there is none.
 
 @smallexample
 @group
@@ -774,7 +779,7 @@ were given to the program.
 @smallexample
 @group
 (process-command (get-process "shell"))
-     @result{} ("/bin/csh" "-i")
+     @result{} ("bash" "-i")
 @end group
 @end smallexample
 @end defun
@@ -782,11 +787,10 @@ were given to the program.
 @defun process-contact process &optional key
 
 This function returns information about how a network or serial
-process was set up.  For a network process, when @var{key} is
-@code{nil}, it returns @code{(@var{hostname} @var{service})} which
-specifies what you connected to.  For a serial process, when @var{key}
-is @code{nil}, it returns @code{(@var{port} @var{speed})}.  For an
-ordinary child process, this function always returns @code{t}.
+process was set up.  When @var{key} is @code{nil}, it returns
+@code{(@var{hostname} @var{service})} for a network process, and
+@code{(@var{port} @var{speed})} for a serial process.
+For an ordinary child process, this function always returns @code{t}.
 
 If @var{key} is @code{t}, the value is the complete status information
 for the connection, server, or serial port; that is, the list of
@@ -794,7 +798,8 @@ keywords and values specified in @code{make-network-process} or
 @code{make-serial-process}, except that some of the values represent
 the current status instead of what you specified.
 
-For a network process:
+For a network process, the values include (see
+@code{make-network-process} for a complete list):
 
 @table @code
 @item :buffer
@@ -831,7 +836,7 @@ process is started and remains constant as long as the process exists.
 @end defun
 
 @defun process-name process
-This function returns the name of @var{process}.
+This function returns the name of @var{process}, as a string.
 @end defun
 
 @defun process-status process-name
@@ -871,12 +876,6 @@ if @var{process-name} is not the name of an existing process.
 (process-status (get-buffer "*shell*"))
      @result{} run
 @end group
-@group
-x
-     @result{} #<process xx<1>>
-(process-status x)
-     @result{} exit
-@end group
 @end smallexample
 
 For a network connection, @code{process-status} returns one of the symbols
@@ -914,13 +913,9 @@ the remote host is provided as process property @code{remote-tty}.
 
 @defun process-coding-system process
 @anchor{Coding systems for a subprocess}
-This function returns a cons cell describing the coding systems in use
-for decoding output from @var{process} and for encoding input to
-@var{process} (@pxref{Coding Systems}).  The value has this form:
-
-@example
-(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
-@end example
+This function returns a cons cell @code{(@var{decode} . @var{encode})},
+describing the coding systems in use for decoding output from, and
+encoding input to, @var{process} (@pxref{Coding Systems}).
 @end defun
 
 @defun set-process-coding-system process &optional decoding-system encoding-system
@@ -960,6 +955,7 @@ Emacs, which is done with the functions in this section.  You must
 specify the process to send input to, and the input data to send.  The
 data appears on the ``standard input'' of the subprocess.
 
+@c FIXME which?
   Some operating systems have limited space for buffered input in a
 @acronym{PTY}.  On these systems, Emacs sends an @acronym{EOF}
 periodically amidst the other characters, to force them through.  For
@@ -986,26 +982,14 @@ the current buffer's process.
 
 @defun process-send-string process string
 This function sends @var{process} the contents of @var{string} as
-standard input.  If it is @code{nil}, the current buffer's process is used.
-
-  The function returns @code{nil}.
+standard input.  It returns @code{nil}.  For example, to make a
+Shell buffer list files:
 
 @smallexample
 @group
 (process-send-string "shell<1>" "ls\n")
      @result{} nil
 @end group
-
-
-@group
----------- Buffer: *shell* ----------
-...
-introduction.texi               syntax-tables.texi~
-introduction.texi~              text.texi
-introduction.txt                text.texi~
-...
----------- Buffer: *shell* ----------
-@end group
 @end smallexample
 @end defun
 
@@ -1021,7 +1005,6 @@ is unimportant which number is larger.)
 @defun process-send-eof &optional process
 This function makes @var{process} see an end-of-file in its
 input.  The @acronym{EOF} comes after any text already sent to it.
-
 The function returns @var{process}.
 
 @smallexample
@@ -1052,7 +1035,7 @@ system.  For example, the signal @code{SIGINT} means that the user has
 typed @kbd{C-c}, or that some analogous thing has happened.
 
   Each signal has a standard effect on the subprocess.  Most signals
-kill the subprocess, but some stop or resume execution instead.  Most
+kill the subprocess, but some stop (or resume) execution instead.  Most
 signals can optionally be handled by programs; if the program handles
 the signal, then we can say nothing in general about its effects.
 
@@ -1061,7 +1044,7 @@ section.  Emacs also sends signals automatically at certain times:
 killing a buffer sends a @code{SIGHUP} signal to all its associated
 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
 processes.  (@code{SIGHUP} is a signal that usually indicates that the
-user hung up the phone.)
+user ``hung up the phone'', i.e., disconnected.)
 
   Each of the signal-sending functions takes two optional arguments:
 @var{process} and @var{current-group}.
@@ -1105,6 +1088,8 @@ and cannot be handled by the subprocess.
 @defun quit-process &optional process current-group
 This function sends the signal @code{SIGQUIT} to the process
 @var{process}.  This signal is the one sent by the ``quit
+@c FIXME?  Never heard of C-b being used for this.  In readline, eg
+@c bash, that is backward-word.
 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
 Emacs.
 @end defun
@@ -1129,11 +1114,12 @@ stopped previously.
 
 @defun signal-process process signal
 This function sends a signal to process @var{process}.  The argument
-@var{signal} specifies which signal to send; it should be an integer.
+@var{signal} specifies which signal to send; it should be an integer,
+or a symbol whose name is a signal.
 
-The @var{process} argument can be a system process @acronym{ID}; that
-allows you to send signals to processes that are not children of
-Emacs.  @xref{System Processes}.
+The @var{process} argument can be a system process @acronym{ID} (an
+integer); that allows you to send signals to processes that are not
+children of Emacs.  @xref{System Processes}.
 @end defun
 
 @node Output from Processes
@@ -1143,10 +1129,10 @@ Emacs.  @xref{System Processes}.
 
   There are two ways to receive the output that a subprocess writes to
 its standard output stream.  The output can be inserted in a buffer,
-which is called the associated buffer of the process, or a function
-called the @dfn{filter function} can be called to act on the output.  If
-the process has no buffer and no filter function, its output is
-discarded.
+which is called the associated buffer of the process (@pxref{Process
+Buffers}), or a function called the @dfn{filter function} can be
+called to act on the output.  If the process has no buffer and no
+filter function, its output is discarded.
 
   When a subprocess terminates, Emacs reads any pending output,
 then stops reading output from that subprocess.  Therefore, if the
@@ -1154,19 +1140,20 @@ subprocess has children that are still live and still producing
 output, Emacs won't receive that output.
 
   Output from a subprocess can arrive only while Emacs is waiting: when
-reading terminal input, in @code{sit-for} and @code{sleep-for}
-(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
-Output}).  This minimizes the problem of timing errors that usually
-plague parallel programming.  For example, you can safely create a
-process and only then specify its buffer or filter function; no output
-can arrive before you finish, if the code in between does not call any
-primitive that waits.
+reading terminal input (see the function @code{waiting-for-user-input-p}),
+in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in
+@code{accept-process-output} (@pxref{Accepting Output}).  This
+minimizes the problem of timing errors that usually plague parallel
+programming.  For example, you can safely create a process and only
+then specify its buffer or filter function; no output can arrive
+before you finish, if the code in between does not call any primitive
+that waits.
 
 @defvar process-adaptive-read-buffering
 On some systems, when Emacs reads the output from a subprocess, the
 output data is read in very small blocks, potentially resulting in
 very poor performance.  This behavior can be remedied to some extent
-by setting the variable @var{process-adaptive-read-buffering} to a
+by setting the variable @code{process-adaptive-read-buffering} to a
 non-@code{nil} value (the default), as it will automatically delay reading
 from such processes, thus allowing them to produce more output before
 Emacs tries to read it.
@@ -1235,9 +1222,9 @@ to insert, and updates it to point after the inserted text.  That is why
 successive batches of output are inserted consecutively.
 
 Filter functions normally should use this marker in the same fashion
-as is done by direct insertion of output in the buffer.  A good
-example of a filter function that uses @code{process-mark} is found at
-the end of the following section.
+as is done by direct insertion of output in the buffer.  For an
+example of a filter function that uses @code{process-mark},
+@pxref{Process Filter Example}.
 
 When the user is expected to enter input in the process buffer for
 transmission to the process, the process marker separates the new input
@@ -1285,14 +1272,16 @@ there is no filter.
 
   The filter function can only be called when Emacs is waiting for
 something, because process output arrives only at such times.  Emacs
-waits when reading terminal input, in @code{sit-for} and
-@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
-(@pxref{Accepting Output}).
+waits when reading terminal input (see the function
+@code{waiting-for-user-input-p}), in @code{sit-for} and
+@code{sleep-for} (@pxref{Waiting}), and in
+@code{accept-process-output} (@pxref{Accepting Output}).
 
   A filter function must accept two arguments: the associated process
 and a string, which is output just received from it.  The function is
 then free to do whatever it chooses with the output.
 
+@c Note this text is duplicated in the sentinels section.
   Quitting is normally inhibited within a filter function---otherwise,
 the effect of typing @kbd{C-g} at command level or to quit a user
 command would be unpredictable.  If you want to permit quitting inside
@@ -1303,19 +1292,20 @@ cases, the right way to do this is with the macro
   If an error happens during execution of a filter function, it is
 caught automatically, so that it doesn't stop the execution of whatever
 program was running when the filter function was started.  However, if
-@code{debug-on-error} is non-@code{nil}, the error-catching is turned
-off.  This makes it possible to use the Lisp debugger to debug the
+@code{debug-on-error} is non-@code{nil}, errors are not caught.
+This makes it possible to use the Lisp debugger to debug the
 filter function.  @xref{Debugger}.
 
-  Many filter functions sometimes or always insert the text in the
+  Many filter functions sometimes (or always) insert the output in the
 process's buffer, mimicking the actions of Emacs when there is no
-filter.  Such filter functions need to use @code{set-buffer} in order to
-be sure to insert in that buffer.  To avoid setting the current buffer
-semipermanently, these filter functions must save and restore the
-current buffer.  They should also check whether the buffer is still
-alive, update the process marker, and in some cases update the value
-of point.  Here is how to do these things:
-
+filter.  Such filter functions need to make sure that they save the
+current buffer, select the correct buffer (if different) before
+inserting output, and then restore the original buffer.
+They should also check whether the buffer is still alive, update the
+process marker, and in some cases update the value of point.  Here is
+how to do these things:
+
+@anchor{Process Filter Example}
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
@@ -1325,7 +1315,7 @@ of point.  Here is how to do these things:
 @end group
 @group
         (save-excursion
-          ;;  @r{Insert the text, advancing the process marker.}
+          ;; @r{Insert the text, advancing the process marker.}
           (goto-char (process-mark proc))
           (insert string)
           (set-marker (process-mark proc) (point)))
@@ -1333,14 +1323,8 @@ of point.  Here is how to do these things:
 @end group
 @end smallexample
 
-@noindent
-The reason to use @code{with-current-buffer}, rather than using
-@code{save-excursion} to save and restore the current buffer, is so as
-to preserve the change in point made by the second call to
-@code{goto-char}.
-
   To make the filter force the process buffer to be visible whenever new
-text arrives, insert the following line just before the
+text arrives, you could insert a line like the following just before the
 @code{with-current-buffer} construct:
 
 @smallexample
@@ -1351,12 +1335,16 @@ text arrives, insert the following line just before the
 previously, eliminate the variable @code{moving} and call
 @code{goto-char} unconditionally.
 
+@ignore
   In earlier Emacs versions, every filter function that did regular
 expression searching or matching had to explicitly save and restore the
 match data.  Now Emacs does this automatically for filter functions;
-they never need to do it explicitly.  @xref{Match Data}.
+they never need to do it explicitly.
+@end ignore
+  Note that Emacs automatically saves and restores the match data
+while executing filter functions.  @xref{Match Data}.
 
-  The output to the function may come in chunks of any size.  A program
+  The output to the filter may come in chunks of any size.  A program
 that produces the same output twice in a row may send it as one batch of
 200 characters one time, and five batches of 40 characters the next.  If
 the filter looks for certain text strings in the subprocess output, make
@@ -1374,7 +1362,7 @@ This function returns the filter function of @var{process}, or @code{nil}
 if it has none.
 @end defun
 
-  Here is an example of use of a filter function:
+  Here is an example of the use of a filter function:
 
 @smallexample
 @group
@@ -1394,7 +1382,7 @@ if it has none.
 (process-send-string "shell" "ls ~/other\n")
      @result{} nil
 kept
-     @result{} ("lewis@@slug[8] % "
+     @result{} ("lewis@@slug:$ "
 @end group
 @group
 "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
@@ -1450,8 +1438,8 @@ bytes, Emacs by default uses @code{no-conversion} for it; see
 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
 control this behavior.
 
-  @strong{Warning:} Coding systems such as @code{undecided} which
-determine the coding system from the data do not work entirely
+  @strong{Warning:} Coding systems such as @code{undecided}, which
+determine the coding system from the data, do not work entirely
 reliably with asynchronous subprocess output.  This is because Emacs
 has to process asynchronous subprocess output in batches, as it
 arrives.  Emacs must try to detect the proper coding system from one
@@ -1469,7 +1457,7 @@ output as a multibyte string or as a unibyte string according to the
 process's filter coding system.  Emacs
 decodes the output according to the process output coding system,
 which usually produces a multibyte string, except for coding systems
-such as @code{binary} and @code{raw-text}
+such as @code{binary} and @code{raw-text}.
 
 @node Accepting Output
 @subsection Accepting Output from Processes
@@ -1487,7 +1475,6 @@ output is inserted in the associated buffers or given to their filter
 functions.  If @var{process} is non-@code{nil} then this function does
 not return until some output has been received from @var{process}.
 
-@c Emacs 19 feature
 The arguments @var{seconds} and @var{millisec} let you specify timeout
 periods.  The former specifies a period measured in seconds and the
 latter specifies one measured in milliseconds.  The two time periods
@@ -1495,10 +1482,10 @@ thus specified are added together, and @code{accept-process-output}
 returns after that much time, whether or not there has been any
 subprocess output.
 
-The argument @var{millisec} is semi-obsolete nowadays because
-@var{seconds} can be a floating point number to specify waiting a
-fractional number of seconds.  If @var{seconds} is 0, the function
-accepts whatever output is pending but does not wait.
+The argument @var{millisec} is obsolete (and should not be used),
+because @var{seconds} can be a floating point number to specify
+waiting a fractional number of seconds.  If @var{seconds} is 0, the
+function accepts whatever output is pending but does not wait.
 
 @c Emacs 22.1 feature
 If @var{process} is a process, and the argument @var{just-this-one} is
@@ -1529,6 +1516,7 @@ describing the type of event.
 
   The string describing the event looks like one of the following:
 
+@c FIXME?  Also "killed\n" - see example below?
 @itemize @bullet
 @item
 @code{"finished\n"}.
@@ -1545,7 +1533,7 @@ describing the type of event.
 
   A sentinel runs only while Emacs is waiting (e.g., for terminal
 input, or for time to elapse, or for process output).  This avoids the
-timing errors that could result from running them at random places in
+timing errors that could result from running sentinels at random places in
 the middle of other Lisp programs.  A program can wait, so that
 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
@@ -1569,6 +1557,7 @@ should check whether the buffer is still alive.  If it tries to insert
 into a dead buffer, it will get an error.  If the buffer is dead,
 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
 
+@c Note this text is duplicated in the filter functions section.
   Quitting is normally inhibited within a sentinel---otherwise, the
 effect of typing @kbd{C-g} at command level or to quit a user command
 would be unpredictable.  If you want to permit quitting inside a
@@ -1579,8 +1568,8 @@ right way to do this is with the macro @code{with-local-quit}.
   If an error happens during execution of a sentinel, it is caught
 automatically, so that it doesn't stop the execution of whatever
 programs was running when the sentinel was started.  However, if
-@code{debug-on-error} is non-@code{nil}, the error-catching is turned
-off.  This makes it possible to use the Lisp debugger to debug the
+@code{debug-on-error} is non-@code{nil},  errors are not caught.
+This makes it possible to use the Lisp debugger to debug the
 sentinel.  @xref{Debugger}.
 
   While a sentinel is running, the process sentinel is temporarily
@@ -1588,10 +1577,14 @@ set to @code{nil} so that the sentinel won't run recursively.
 For this reason it is not possible for a sentinel to specify
 a new sentinel.
 
+@ignore
   In earlier Emacs versions, every sentinel that did regular expression
 searching or matching had to explicitly save and restore the match data.
 Now Emacs does this automatically for sentinels; they never need to do
-it explicitly.  @xref{Match Data}.
+it explicitly.
+@end ignore
+ Note that Emacs automatically saves and restores the match data
+while executing sentinels.  @xref{Match Data}.
 
 @defun set-process-sentinel process sentinel
 This function associates @var{sentinel} with @var{process}.  If
@@ -1599,7 +1592,7 @@ This function associates @var{sentinel} with @var{process}.  If
 The default behavior when there is no sentinel is to insert a message in
 the process's buffer when the process status changes.
 
-Changes in process sentinel take effect immediately---if the sentinel
+Changes in process sentinels take effect immediately---if the sentinel
 is slated to be run but has not been called yet, and you specify a new
 sentinel, the eventual call to the sentinel will use the new one.
 
@@ -1627,7 +1620,7 @@ has none.
 @defun waiting-for-user-input-p
 While a sentinel or filter function is running, this function returns
 non-@code{nil} if Emacs was waiting for keyboard input from the user at
-the time the sentinel or filter function was called, @code{nil} if it
+the time the sentinel or filter function was called, or @code{nil} if it
 was not.
 @end defun
 
@@ -1637,7 +1630,7 @@ was not.
   When Emacs exits, it terminates all its subprocesses by sending them
 the @code{SIGHUP} signal.  Because subprocesses may be doing
 valuable work, Emacs normally asks the user to confirm that it is ok
-to terminate them.  Each process has a query flag which, if
+to terminate them.  Each process has a query flag, which, if
 non-@code{nil}, says that Emacs should ask for confirmation before
 exiting and thus killing that process.  The default for the query flag
 is @code{t}, meaning @emph{do} query.
@@ -1656,7 +1649,7 @@ shell process to avoid querying:
 @smallexample
 @group
 (set-process-query-on-exit-flag (get-process "shell") nil)
-     @result{} t
+     @result{} nil
 @end group
 @end smallexample
 @end defun
@@ -1668,7 +1661,7 @@ shell process to avoid querying:
   In addition to accessing and manipulating processes that are
 subprocesses of the current Emacs session, Emacs Lisp programs can
 also access other processes running on the same machine.  We call
-these @dfn{system processes}, to distinguish between them and Emacs
+these @dfn{system processes}, to distinguish them from Emacs
 subprocesses.
 
   Emacs provides several primitives for accessing system processes.
@@ -1688,7 +1681,7 @@ This function returns an alist of attributes for the process specified
 by its process ID @var{pid}.  Each association in the alist is of the
 form @code{(@var{key} . @var{value})}, where @var{key} designates the
 attribute and @var{value} is the value of that attribute.  The various
-attribute @var{key}'s that this function can return are listed below.
+attribute @var{key}s that this function can return are listed below.
 Not all platforms support all of these attributes; if an attribute is
 not supported, its association will not appear in the returned alist.
 Values that are numbers can be either integer or floating-point,
@@ -1849,6 +1842,8 @@ as @code{shell-command}.
 @section Transaction Queues
 @cindex transaction queue
 
+@c That's not very informative.  What is a transaction, and when might
+@c I want to use one?
 You can use a @dfn{transaction queue} to communicate with a subprocess
 using transactions.  First use @code{tq-create} to create a transaction
 queue communicating with a specified process.  Then you can call
@@ -1878,8 +1873,11 @@ text at the end of the entire answer, but nothing before; that's how
 If the argument @var{delay-question} is non-@code{nil}, delay sending
 this question until the process has finished replying to any previous
 questions.  This produces more reliable results with some processes.
+@ignore
 
+@c Let's not mention it then.
 The return value of @code{tq-enqueue} itself is not meaningful.
+@end ignore
 @end defun
 
 @defun tq-close queue
@@ -1897,10 +1895,11 @@ Transaction queues are implemented by means of a filter function.
 @cindex UDP
 
   Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
-connections to other processes on the same machine or other machines.
+connections (@pxref{Datagrams}) to other processes on the same machine
+or other machines.
 A network connection is handled by Lisp much like a subprocess, and is
 represented by a process object.  However, the process you are
-communicating with is not a child of the Emacs process, so it has no
+communicating with is not a child of the Emacs process, has no
 process @acronym{ID}, and you can't kill it or send it signals.  All you
 can do is send and receive data.  @code{delete-process} closes the
 connection, but does not kill the program at the other end; that
@@ -1928,7 +1927,7 @@ network connection or server, @code{serial} for a serial port
 connection, or @code{real} for a real subprocess.
 
   The @code{process-status} function returns @code{open},
-@code{closed}, @code{connect}, and @code{failed} for network
+@code{closed}, @code{connect}, or @code{failed} for network
 connections.  For a network server, the status is always
 @code{listen}.  None of those values is possible for a real
 subprocess.  @xref{Process Information}.
@@ -1938,35 +1937,48 @@ subprocess.  @xref{Process Information}.
 process, being stopped means not accepting new connections.  (Up to 5
 connection requests will be queued for when you resume the server; you
 can increase this limit, unless it is imposed by the operating
-system.)  For a network stream connection, being stopped means not
-processing input (any arriving input waits until you resume the
-connection).  For a datagram connection, some number of packets may be
-queued but input may be lost.  You can use the function
+system---see the @code{:server} keyword of @code{make-network-process},
+@ref{Network Processes}.)  For a network stream connection, being
+stopped means not processing input (any arriving input waits until you
+resume the connection).  For a datagram connection, some number of
+packets may be queued but input may be lost.  You can use the function
 @code{process-command} to determine whether a network connection or
 server is stopped; a non-@code{nil} value means yes.
 
 @cindex network connection, encrypted
 @cindex encrypted network connections
-@cindex TLS network connections
-@cindex STARTTLS network connections
-@defun open-network-stream name buffer-or-name host service &rest parameters
+@cindex @acronym{TLS} network connections
+@cindex @acronym{STARTTLS} network connections
+Emacs can create encrypted network connections, using either built-in
+or external support.  The built-in support uses the GnuTLS
+(``Transport Layer Security'') library; see
+@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}.
+If your Emacs was compiled with GnuTLS support, the function
+@code{gnutls-available-p} is defined and returns non-@code{nil}.  For
+more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
+The external support uses the @file{starttls.el} library, which
+requires a helper utility such as @command{gnutls-cli} to be installed
+on the system.  The @code{open-network-stream} function can
+transparently handle the details of creating encrypted connections for
+you, using whatever support is available.
+
+@defun open-network-stream name buffer host service &rest parameters
 This function opens a TCP connection, with optional encryption, and
 returns a process object that represents the connection.
 
 The @var{name} argument specifies the name for the process object.  It
 is modified as necessary to make it unique.
 
-The @var{buffer-or-name} argument is the buffer to associate with the
+The @var{buffer} argument is the buffer to associate with the
 connection.  Output from the connection is inserted in the buffer,
 unless you specify a filter function to handle the output.  If
-@var{buffer-or-name} is @code{nil}, it means that the connection is not
+@var{buffer} is @code{nil}, it means that the connection is not
 associated with any buffer.
 
 The arguments @var{host} and @var{service} specify where to connect to;
 @var{host} is the host name (a string), and @var{service} is the name of
 a defined network service (a string) or a port number (an integer).
 
-@c FIXME?  Is this too lengthy for the printed manual?
 The remaining arguments @var{parameters} are keyword/argument pairs
 that are mainly relevant to encrypted connections:
 
@@ -1983,14 +1995,15 @@ The type of connection.  Options are:
 An ordinary, unencrypted connection.
 @item tls
 @itemx ssl
-A TLS (``Transport Layer Security'') connection.
+A @acronym{TLS} (``Transport Layer Security'') connection.
 @item nil
 @itemx network
 Start with a plain connection, and if parameters @samp{:success}
 and @samp{:capability-command} are supplied, try to upgrade to an encrypted
-connection via STARTTLS.  If that fails, retain the unencrypted connection.
+connection via @acronym{STARTTLS}.  If that fails, retain the
+unencrypted connection.
 @item starttls
-As for @code{nil}, but if STARTTLS fails drop the connection.
+As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection.
 @item shell
 A shell connection.
 @end table
@@ -2009,22 +2022,22 @@ command @var{capability-command}.  The latter defaults to the former.
 
 @item :starttls-function @var{function}
 Function of one argument (the response to @var{capability-command}),
-which returns either @code{nil}, or the command to activate STARTTLS
+which returns either @code{nil}, or the command to activate @acronym{STARTTLS}
 if supported.
 
 @item :success @var{regexp}
-Regular expression matching a successful STARTTLS negotiation.
+Regular expression matching a successful @acronym{STARTTLS} negotiation.
 
 @item :use-starttls-if-possible @var{boolean}
-If non-@code{nil}, do opportunistic STARTTLS upgrades even if Emacs
-doesn't have built-in TLS support.
+If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
+doesn't have built-in @acronym{TLS} support.
 
 @item :client-certificate @var{list-or-t}
 Either a list of the form @code{(@var{key-file} @var{cert-file})},
 naming the certificate key file and certificate file itself, or
 @code{t}, meaning to query @code{auth-source} for this information
-(@pxref{Top,,auth-source, auth, Emacs auth-source Library}).
-Only used for TLS or STARTTLS.
+(@pxref{Top,,Overview, auth, The Auth-Source Manual}).
+Only used for @acronym{TLS} or @acronym{STARTTLS}.
 
 @item :return-list @var{cons-or-nil}
 The return value of this function.  If omitted or @code{nil}, return a
@@ -2048,18 +2061,20 @@ The connection type: @samp{plain} or @samp{tls}.
 @section Network Servers
 @cindex network servers
 
-  You create a server by calling @code{make-network-process} with
-@code{:server t}.  The server will listen for connection requests from
-clients.  When it accepts a client connection request, that creates a
-new network connection, itself a process object, with the following
-parameters:
+  You create a server by calling @code{make-network-process}
+(@pxref{Network Processes}) with @code{:server t}.  The server will
+listen for connection requests from clients.  When it accepts a client
+connection request, that creates a new network connection, itself a
+process object, with the following parameters:
 
 @itemize @bullet
 @item
 The connection's process name is constructed by concatenating the
 server process's @var{name} with a client identification string.  The
+@c FIXME?  What about IPv6?  Say briefly what the difference is?
 client identification string for an IPv4 connection looks like
-@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
+@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an
+address and port number.  Otherwise, it is a
 unique number in brackets, as in @samp{<@var{nnn}>}.  The number
 is unique for each connection in the Emacs session.
 
@@ -2080,7 +2095,7 @@ uses its filter and sentinel; their sole purpose is to initialize
 connections made to the server.
 
 @item
-The connection's process contact info is set according to the client's
+The connection's process contact information is set according to the client's
 addressing information (typically an IP address and a port number).
 This information is associated with the @code{process-contact}
 keywords @code{:host}, @code{:service}, @code{:remote}.
@@ -2097,7 +2112,7 @@ The client process's plist is initialized from the server's plist.
 @section Datagrams
 @cindex datagrams
 
-  A datagram connection communicates with individual packets rather
+  A @dfn{datagram} connection communicates with individual packets rather
 than streams of data.  Each call to @code{process-send} sends one
 datagram packet (@pxref{Input to Processes}), and each datagram
 received results in one call to the filter function.
@@ -2150,7 +2165,8 @@ process object that represents it.  The arguments @var{args} are a
 list of keyword/argument pairs.  Omitting a keyword is always
 equivalent to specifying it with value @code{nil}, except for
 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}.  Here
-are the meaningful keywords:
+are the meaningful keywords (those corresponding to network options
+are listed in the following section):
 
 @table @asis
 @item :name @var{name}
@@ -2166,7 +2182,7 @@ connection.  Both connections and servers can be of these types.
 @item :server @var{server-flag}
 If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
 create a connection.  For a stream type server, @var{server-flag} may
-be an integer which then specifies the length of the queue of pending
+be an integer, which then specifies the length of the queue of pending
 connections to the server.  The default queue length is 5.
 
 @item :host @var{host}
@@ -2177,7 +2193,7 @@ specify a valid address for the local host, and only clients
 connecting to that address will be accepted.
 
 @item :service @var{service}
-@var{service} specifies a port number to connect to, or, for a server,
+@var{service} specifies a port number to connect to; or, for a server,
 the port number to listen on.  It should be a service name that
 translates to a port number, or an integer specifying the port number
 directly.  For a server, it can also be @code{t}, which means to let
@@ -2188,18 +2204,18 @@ the system select an unused port number.
 communication.  @code{nil} means determine the proper address family
 automatically for the given @var{host} and @var{service}.
 @code{local} specifies a Unix socket, in which case @var{host} is
-ignored.  @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
+ignored.  @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
 respectively.
 
 @item :local @var{local-address}
 For a server process, @var{local-address} is the address to listen on.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
+It overrides @var{family}, @var{host} and @var{service}, so you
+might as well not specify them.
 
 @item :remote @var{remote-address}
 For a connection, @var{remote-address} is the address to connect to.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
+It overrides @var{family}, @var{host} and @var{service}, so you
+might as well not specify them.
 
 For a datagram server, @var{remote-address} specifies the initial
 setting of the remote datagram address.
@@ -2223,7 +2239,7 @@ integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
 port number @var{p}.
 
 @item
-A local address is represented as a string which specifies the address
+A local address is represented as a string, which specifies the address
 in the local address space.
 
 @item
@@ -2245,8 +2261,8 @@ second argument matching @code{"open"} (if successful) or
 has succeeded or failed.
 
 @item :stop @var{stopped}
-Start the network connection or server in the `stopped' state if
-@var{stopped} is non-@code{nil}.
+If @var{stopped} is non-@code{nil}, start the network connection or
+server in the ``stopped'' state.
 
 @item :buffer @var{buffer}
 Use @var{buffer} as the process buffer.
@@ -2267,6 +2283,11 @@ Initialize the process query flag to @var{query-flag}.
 @item :filter @var{filter}
 Initialize the process filter to @var{filter}.
 
+@item :filter-multibyte @var{multibyte}
+If @var{multibyte} is non-@code{nil}, strings given to the process
+filter are multibyte, otherwise they are unibyte.  The default is the
+default value of @code{enable-multibyte-characters}.
+
 @item :sentinel @var{sentinel}
 Initialize the process sentinel to @var{sentinel}.
 
@@ -2274,7 +2295,7 @@ Initialize the process sentinel to @var{sentinel}.
 Initialize the log function of a server process to @var{log}.  The log
 function is called each time the server accepts a network connection
 from a client.  The arguments passed to the log function are
-@var{server}, @var{connection}, and @var{message}, where @var{server}
+@var{server}, @var{connection}, and @var{message}; where @var{server}
 is the server process, @var{connection} is the new process for the
 connection, and @var{message} is a string describing what has
 happened.
@@ -2311,7 +2332,7 @@ Using this option may require special privileges on some systems.
 @item :broadcast @var{broadcast-flag}
 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
 process will receive datagram packet sent to a broadcast address, and
-be able to send packets to a broadcast address.  Ignored for a stream
+be able to send packets to a broadcast address.  This is ignored for a stream
 connection.
 
 @item :dontroute @var{dontroute-flag}
@@ -2327,10 +2348,11 @@ If @var{linger-arg} is non-@code{nil}, wait for successful
 transmission of all queued packets on the connection before it is
 deleted (see @code{delete-process}).  If @var{linger-arg} is an
 integer, it specifies the maximum time in seconds to wait for queued
-packets to be sent before closing the connection.  Default is
-@code{nil} which means to discard unsent queued packets when the
+packets to be sent before closing the connection.  The default is
+@code{nil}, which means to discard unsent queued packets when the
 process is deleted.
 
+@c FIXME  Where out-of-band data is ...?
 @item :oobinline @var{oobinline-flag}
 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
 receive out-of-band data in the normal data stream.  Otherwise, ignore
@@ -2339,7 +2361,7 @@ out-of-band data.
 @item :priority @var{priority}
 Set the priority for packets sent on this connection to the integer
 @var{priority}.  The interpretation of this number is protocol
-specific, such as setting the TOS (type of service) field on IP
+specific; such as setting the TOS (type of service) field on IP
 packets sent on this connection.  It may also have system dependent
 effects, such as selecting a specific output queue on the network
 interface.
@@ -2347,20 +2369,20 @@ interface.
 @item :reuseaddr @var{reuseaddr-flag}
 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
 server process, allow this server to reuse a specific port number (see
-@code{:service}) unless another process on this host is already
+@code{:service}), unless another process on this host is already
 listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
 may be a period of time after the last use of that port (by any
-process on the host), where it is not possible to make a new server on
+process on the host) where it is not possible to make a new server on
 that port.
 @end table
 
 @defun set-network-process-option process option value &optional no-error
 This function sets or modifies a network option for network process
-@var{process}.  See @code{make-network-process} for details of options
-@var{option} and their corresponding values @var{value}.  If
-@var{no-error} is non-@code{nil}, this function returns @code{nil}
-instead of signaling an error if @var{option} is not a supported
-option.  If the function successfully completes, it returns @code{t}.
+@var{process}.  The accepted options and values are as for
+@code{make-network-process}.  If @var{no-error} is non-@code{nil},
+this function returns @code{nil} instead of signaling an error if
+@var{option} is not a supported option.  If the function successfully
+completes, it returns @code{t}.
 
 The current setting of an option is available via the
 @code{process-contact} function.
@@ -2377,11 +2399,9 @@ The current setting of an option is available via the
 @end example
 
 @noindent
-The result of the first form is @code{t} if it works to specify
+The result of this form is @code{t} if it works to specify
 @var{keyword} with value @var{value} in @code{make-network-process}.
-The result of the second form is @code{t} if @var{keyword} is
-supported by @code{make-network-process}.  Here are some of the
-@var{keyword}---@var{value} pairs you can test in
+Here are some of the @var{keyword}---@var{value} pairs you can test in
 this way.
 
 @table @code
@@ -2405,20 +2425,10 @@ Non-@code{nil} if the system can select the port for a server.
 @end example
 
 @noindent
-Here are some of the options you can test in this way.
-
-@table @code
-@item :bindtodevice
-@itemx :broadcast
-@itemx :dontroute
-@itemx :keepalive
-@itemx :linger
-@itemx :oobinline
-@itemx :priority
-@itemx :reuseaddr
-That particular network option is supported by
-@code{make-network-process} and @code{set-network-process-option}.
-@end table
+The accepted @var{keyword} values are @code{:bindtodevice}, etc.
+For the complete list, @pxref{Network Options}.  This form returns
+non-@code{nil} if that particular network option is supported by
+@code{make-network-process} (or @code{set-network-process-option}).
 
 @node Misc Network
 @section Misc Network Facilities
@@ -2490,11 +2500,11 @@ lets you change the speed, bytesize, and other parameters.  In a
 terminal window created by @code{serial-term}, you can click on the
 mode line for configuration.
 
-  A serial connection is represented by a process object which can be
-used similar to a subprocess or network process.  You can send and
-receive data and configure the serial port.  A serial process object
-has no process ID, you can't send signals to it, and the status codes
-are different from other types of processes.
+  A serial connection is represented by a process object, which can be
+used in a similar way to a subprocess or network process.  You can send and
+receive data, and configure the serial port.  A serial process object
+has no process ID, however, and you can't send signals to it, and the
+status codes are different from other types of processes.
 @code{delete-process} on the process object or @code{kill-buffer} on
 the process buffer close the connection, but this does not affect the
 device connected to the serial port.
@@ -2502,15 +2512,17 @@ device connected to the serial port.
   The function @code{process-type} returns the symbol @code{serial}
 for a process object representing a serial port connection.
 
-  Serial ports are available on GNU/Linux, Unix, and Windows systems.
+  Serial ports are available on GNU/Linux, Unix, and MS Windows systems.
 
 @deffn Command serial-term port speed
 Start a terminal-emulator for a serial port in a new buffer.
-@var{port} is the name of the serial port to which to connect.  For
-example, this could be @file{/dev/ttyS0} on Unix.  On Windows, this
+@var{port} is the name of the serial port to connect to.  For
+example, this could be @file{/dev/ttyS0} on Unix.  On MS Windows, this
 could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in
 Lisp strings).
 
+@c FIXME is 9600 still the most common value, or is it 115200 now?
+@c (Same value, 9600, appears below as well.)
 @var{speed} is the speed of the serial port in bits per second.  9600
 is a common value.  The buffer is in Term mode; see @ref{Term Mode,,,
 emacs, The GNU Emacs Manual}, for the commands to use in that buffer.
@@ -2519,25 +2531,27 @@ You can change the speed and the configuration in the mode line menu.
 
 @defun make-serial-process &rest args
 This function creates a process and a buffer.  Arguments are specified
-as keyword/argument pairs.  Here's the list of the meaningful keywords:
+as keyword/argument pairs.  Here's the list of the meaningful
+keywords, with the first two (@var{port} and @var{speed}) being mandatory:
 
 @table @code
-@item :port @var{port}@r{ (mandatory)}
+@item :port @var{port}
 This is the name of the serial port.  On Unix and GNU systems, this is
 a file name such as @file{/dev/ttyS0}.  On Windows, this could be
 @file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9}
 (double the backslashes in Lisp strings).
 
-@item :speed @var{speed}@r{ (mandatory)}
+@item :speed @var{speed}
 The speed of the serial port in bits per second.  This function calls
-@code{serial-process-configure} to handle the speed.
+@code{serial-process-configure} to handle the speed; see the
+following documentation of that function for more details.
 
 @item :name @var{name}
 The name of the process.  If @var{name} is not given, @var{port} will
 serve as the process name as well.
 
 @item :buffer @var{buffer}
-The buffer to associate with the process.  The value could be either a
+The buffer to associate with the process.  The value can be either a
 buffer or a string that names a buffer.  Process output goes at the
 end of that buffer, unless you specify an output stream or filter
 function to handle the output.  If @var{buffer} is not given, the
@@ -2547,16 +2561,16 @@ keyword.
 @item :coding @var{coding}
 If @var{coding} is a symbol, it specifies the coding system used for
 both reading and writing for this process.  If @var{coding} is a cons
-@code{(decoding . encoding)}, @var{decoding} is used for reading, and
-@var{encoding} is used for writing.  If not specified, the default is
-to determine the coding systems from data itself.
+@code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for
+reading, and @var{encoding} is used for writing.  If not specified,
+the default is to determine the coding systems from the data itself.
 
 @item :noquery @var{query-flag}
 Initialize the process query flag to @var{query-flag}.  @xref{Query
 Before Exit}.  The flags defaults to @code{nil} if unspecified.
 
 @item :stop @var{bool}
-Start process in the @code{stopped} state if @var{bool} is
+Start process in the ``stopped'' state if @var{bool} is
 non-@code{nil}.  In the stopped state, a serial process does not
 accept incoming data, but you can send outgoing data.  The stopped
 state is cleared by @code{continue-process} and set by
@@ -2571,8 +2585,7 @@ Install @var{sentinel} as the process sentinel.
 @item :plist @var{plist}
 Install @var{plist} as the initial plist of the process.
 
-@item :speed
-@itemx :bytesize
+@item :bytesize
 @itemx :parity
 @itemx :stopbits
 @itemx :flowcontrol
@@ -2600,7 +2613,7 @@ Here is an example:
 This functions configures a serial port connection.  Arguments are
 specified as keyword/argument pairs.  Attributes that are not given
 are re-initialized from the process's current configuration (available
-via the function @code{process-contact}) or set to reasonable default
+via the function @code{process-contact}), or set to reasonable default
 values.  The following arguments are defined:
 
 @table @code
@@ -2618,8 +2631,8 @@ rate}.  The value can be any number, but most serial ports work only
 at a few defined values between 1200 and 115200, with 9600 being the
 most common value.  If @var{speed} is @code{nil}, the function ignores
 all other arguments and does not configure the port.  This may be
-useful for special serial ports such as Bluetooth-to-serial converters
-which can only be configured through AT commands sent through the
+useful for special serial ports such as Bluetooth-to-serial converters,
+which can only be configured through @samp{AT} commands sent through the
 connection.  The value of @code{nil} for @var{speed} is valid only for
 connections that were already opened by a previous call to
 @code{make-serial-process} or @code{serial-term}.
@@ -2646,9 +2659,9 @@ flow control).  If @var{flowcontrol} is not given, it defaults to no
 flow control.
 @end table
 
-@code{serial-process-configure} is called by
-@code{make-serial-process} for the initial configuration of the serial
-port.
+Internally, @code{make-serial-process} calls
+@code{serial-process-configure} for the initial configuration of the
+serial port.
 @end defun
 
 @node Byte Packing
@@ -2658,8 +2671,12 @@ port.
   This section describes how to pack and unpack arrays of bytes,
 usually for binary network protocols.  These functions convert byte arrays
 to alists, and vice versa.  The byte array can be represented as a
+@c FIXME?  No multibyte?
 unibyte string or as a vector of integers, while the alist associates
 symbols either with fixed-size objects or with recursive sub-alists.
+To use the functions referred to in this section, load the
+@code{bindat} library.
+@c It doesn't have any autoloads.
 
 @cindex serializing
 @cindex deserializing
@@ -2680,7 +2697,7 @@ direction is also known as @dfn{serializing} or @dfn{packing}.
 
   To control unpacking and packing, you write a @dfn{data layout
 specification}, a special nested list describing named and typed
-@dfn{fields}.  This specification controls length of each field to be
+@dfn{fields}.  This specification controls the length of each field to be
 processed, and how to pack or unpack it.  We normally keep bindat specs
 in variables whose names end in @samp{-bindat-spec}; that kind of name
 is automatically recognized as ``risky''.
@@ -2729,12 +2746,12 @@ String of length @var{len}.
 Zero-terminated string, in a fixed-size field with length @var{len}.
 
 @item vec @var{len} [@var{type}]
-Vector of @var{len} elements of type @var{type}, or bytes if not
-@var{type} is specified.
+Vector of @var{len} elements of type @var{type}, defaulting to bytes.
 The @var{type} is any of the simple types above, or another vector
-specified as a list @code{(vec @var{len} [@var{type}])}.
+specified as a list of the form @code{(vec @var{len} [@var{type}])}.
 
 @item ip
+@c FIXME?  IPv6?
 Four-byte vector representing an Internet address.  For example:
 @code{[127 0 0 1]} for localhost.
 
@@ -2762,12 +2779,11 @@ below, or by an expression @code{(eval @var{form})} where @var{form}
 should evaluate to an integer, specifying the field length.
 
 A field specification generally has the form @code{([@var{name}]
-@var{handler})}.  The square braces indicate that @var{name} is
-optional.  (Don't use names that are symbols meaningful as type
-specifications (above) or handler specifications (below), since that
-would be ambiguous.)  @var{name} can be a symbol or the expression
-@code{(eval @var{form})}, in which case @var{form} should evaluate to
-a symbol.
+@var{handler})}, where @var{name} is optional.  Don't use names that
+are symbols meaningful as type specifications (above) or handler
+specifications (below), since that would be ambiguous.  @var{name} can
+be a symbol or an expression @code{(eval @var{form})}, in which case
+@var{form} should evaluate to a symbol.
 
 @var{handler} describes how to unpack or pack the field and can be one
 of the following:
@@ -2814,10 +2830,11 @@ of @var{form}.  A non-@code{nil} result indicates a match.
 
 @item repeat @var{count} @var{field-specs}@dots{}
 Process the @var{field-specs} recursively, in order, then repeat
-starting from the first one, processing all the specs @var{count}
+starting from the first one, processing all the specifications @var{count}
 times overall.  The @var{count} is given using the same formats as a
 field length---if an @code{eval} form is used, it is evaluated just once.
-For correct operation, each spec in @var{field-specs} must include a name.
+For correct operation, each specification in @var{field-specs} must
+include a name.
 @end table
 
 For the @code{(eval @var{form})} forms used in a bindat specification,
@@ -2856,9 +2873,10 @@ specification, @code{bindat-raw} to a byte array, and @var{struct} to an
 alist representing unpacked field data.
 
 @defun bindat-unpack spec bindat-raw &optional bindat-idx
+@c FIXME?  Again, no multibyte?
 This function unpacks data from the unibyte string or byte
 array @code{bindat-raw}
-according to @var{spec}.  Normally this starts unpacking at the
+according to @var{spec}.  Normally, this starts unpacking at the
 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
 specifies a zero-based starting position to use instead.
 
@@ -2894,7 +2912,7 @@ according to @var{spec}.
 
 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
 This function returns a byte array packed according to @var{spec} from
-the data in the alist @var{struct}.  Normally it creates and fills a
+the data in the alist @var{struct}.  It normally creates and fills a
 new byte array starting at the beginning.  However, if @var{bindat-raw}
 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
 pack into.  If @var{bindat-idx} is non-@code{nil}, it specifies the starting
@@ -2907,6 +2925,7 @@ meets or exceeds the total length to avoid an out-of-range error.
 @defun bindat-ip-to-string ip
 Convert the Internet address vector @var{ip} to a string in the usual
 dotted notation.
+@c FIXME?  Does it do IPv6?
 
 @example
 (bindat-ip-to-string [127 0 0 1])
@@ -2916,10 +2935,16 @@ dotted notation.
 
 @node Bindat Examples
 @subsection Examples of Byte Unpacking and Packing
+@c FIXME?  This seems a very long example for something that is not used
+@c very often.  As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs.
+@c Maybe one or both of these examples should just be moved to the
+@c commentary of bindat.el.
 
   Here is a complete example of byte unpacking and packing:
 
 @lisp
+(require 'bindat)
+
 (defvar fcookie-index-spec
   '((:version  u32)
     (:count    u32)
@@ -2928,16 +2953,14 @@ dotted notation.
     (:flags    u32)
     (:delim    u8)
     (:ignored  fill 3)
-    (:offset   repeat (:count)
-               (:foo u32)))
+    (:offset   repeat (:count) (:foo u32)))
   "Description of a fortune cookie index file's contents.")
 
 (defun fcookie (cookies &optional index)
   "Display a random fortune cookie from file COOKIES.
 Optional second arg INDEX specifies the associated index
-filename, which is by default constructed by appending
-\".dat\" to COOKIES.  Display cookie text in possibly
-new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
+filename, by default \"COOKIES.dat\".  Display cookie text
+in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME
 is COOKIES without the directory part."
   (interactive "fCookies file: ")
   (let* ((info (with-temp-buffer
@@ -2960,10 +2983,9 @@ is COOKIES without the directory part."
 
 (defun fcookie-create-index (cookies &optional index delim)
   "Scan file COOKIES, and write out its index file.
-Optional second arg INDEX specifies the index filename,
-which is by default constructed by appending \".dat\" to
-COOKIES.  Optional third arg DELIM specifies the unibyte
-character which, when found on a line of its own in
+Optional arg INDEX specifies the index filename, which by
+default is \"COOKIES.dat\".  Optional arg DELIM specifies the
+unibyte character that, when found on a line of its own in
 COOKIES, indicates the border between entries."
   (interactive "fCookies file: ")
   (setq delim (or delim ?%))
@@ -3000,8 +3022,8 @@ COOKIES, indicates the border between entries."
         (write-file (or index (concat cookies ".dat")))))))
 @end lisp
 
-Following is an example of defining and unpacking a complex structure.
-Consider the following C structures:
+The following is an example of defining and unpacking a complex
+structure.  Consider the following C structures:
 
 @example
 struct header @{
@@ -3014,14 +3036,14 @@ struct header @{
 struct data @{
     unsigned char    type;
     unsigned char    opcode;
-    unsigned short   length;  /* In network byte order */
+    unsigned short   length;  /* in network byte order  */
     unsigned char    id[8];   /* null-terminated string  */
     unsigned char    data[/* (length + 3) & ~3 */];
 @};
 
 struct packet @{
     struct header    header;
-    unsigned long    counters[2];  /* In little endian order */
+    unsigned long    counters[2];  /* in little endian order  */
     unsigned char    items;
     unsigned char    filler[3];
     struct data      item[/* items */];
@@ -3029,7 +3051,7 @@ struct packet @{
 @};
 @end example
 
-The corresponding data layout specification:
+The corresponding data layout specification is:
 
 @lisp
 (setq header-spec
@@ -3041,21 +3063,21 @@ The corresponding data layout specification:
 (setq data-spec
       '((type      u8)
         (opcode    u8)
-        (length    u16)  ;; network byte order
+        (length    u16)  ; network byte order
         (id        strz 8)
         (data      vec (length))
         (align     4)))
 
 (setq packet-spec
       '((header    struct header-spec)
-        (counters  vec 2 u32r)   ;; little endian order
+        (counters  vec 2 u32r)   ; little endian order
         (items     u8)
         (fill      3)
         (item      repeat (items)
                    (struct data-spec))))
 @end lisp
 
-A binary data representation:
+A binary data representation is:
 
 @lisp
 (setq binary-data
@@ -3065,7 +3087,7 @@ A binary data representation:
         1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
 @end lisp
 
-The corresponding decoded structure:
+The corresponding decoded structure is:
 
 @lisp
 (setq decoded (bindat-unpack packet-spec binary-data))
@@ -3089,7 +3111,7 @@ The corresponding decoded structure:
         (type . 1))))
 @end lisp
 
-Fetching data from this structure:
+An example of fetching data from this structure:
 
 @lisp
 (bindat-get-field decoded 'item 1 'id)
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 45a0dee3b1c..25ea8577467 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -658,8 +658,8 @@ Minibuffers
 * 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 Contents::     How such commands access the minibuffer text.
 * Minibuffer Windows::      Operating on the special minibuffer windows.
+* Minibuffer Contents::     How such commands access the minibuffer text.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 
@@ -670,7 +670,7 @@ Completion
 * Minibuffer Completion::   Invoking the minibuffer with completion.
 * Completion Commands::     Minibuffer commands that do completion.
 * High-Level Completion::   Convenient special cases of completion
-                              (reading buffer name, file name, etc.).
+                              (reading buffer names, variable names, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
 * Completion Variables::    Variables controlling completion behavior.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 01a3e3c129e..2fd2a8d8224 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -657,8 +657,8 @@ Minibuffers
 * 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 Contents::     How such commands access the minibuffer text.
 * Minibuffer Windows::      Operating on the special minibuffer windows.
+* Minibuffer Contents::     How such commands access the minibuffer text.
 * Recursive Mini::          Whether recursive entry to minibuffer is allowed.
 * Minibuffer Misc::         Various customization hooks and variables.
 
@@ -669,7 +669,7 @@ Completion
 * Minibuffer Completion::   Invoking the minibuffer with completion.
 * Completion Commands::     Minibuffer commands that do completion.
 * High-Level Completion::   Convenient special cases of completion
-                              (reading buffer name, file name, etc.).
+                              (reading buffer names, variable names, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
 * Completion Variables::    Variables controlling completion behavior.
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 46fea77107b..20c453544bc 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,23 @@
+2012-04-20  Glenn Morris  <rgm@gnu.org>
+
+        * faq.texi (New in Emacs 24): New section.
+        (Packages that do not come with Emacs): Mention M-x list-packages.
+
+2012-04-20  Glenn Morris  <rgm@gnu.org>
+
+        * Makefile.in: Replace non-portable use of $< in emacs-gnutls rules.
+
+2012-04-20  Eli Zaretskii  <eliz@gnu.org>
+
+        * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add emacs-gnutls.
+        ($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets.
+
+2012-04-20  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * emacs-gnutls.texi: Add documentation for the GnuTLS integration.
+        * Makefile.in: Add emacs-gnutls.texi to build.
+
+2012-04-20  Alan Mackenzie  <acm@muc.de>
 2012-04-14  Alan Mackenzie  <acm@muc.de>
 
         * cc-mode.texi (c-offsets-alist): Correct a typo.
diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi
index 5b7bb7ec9ce..0f20c41c8eb 100644
--- a/doc/misc/faq.texi
+++ b/doc/misc/faq.texi
@@ -942,6 +942,7 @@ status of its latest version.
 @menu
 * Origin of the term Emacs::
 * Latest version of Emacs::
+* New in Emacs 24::
 * New in Emacs 23::
 * New in Emacs 22::
 * New in Emacs 21::
@@ -1009,12 +1010,84 @@ Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}).  As of Emacs 22,
 you can give this command a prefix argument to read about which features
 were new in older versions.
 
+@node New in Emacs 24
+@section What is different about Emacs 24?
+@cindex Differences between Emacs 23 and Emacs 24
+@cindex Emacs 24, new features in
+
+@itemize
+@cindex packages, installing more
+@item
+Emacs now includes a package manager.  Type @kbd{M-x list-packages} to
+get started.  You can use this to download and automatically install
+many more Lisp packages.
+
+@cindex lexical binding
+@item
+Emacs Lisp now supports lexical binding on a per-file basis.  In
+@emph{lexical binding}, variable references must be located textually
+within the binding construct.  This contrasts with @emph{dynamic
+binding}, where programs can refer to variables defined outside their
+local textual scope.  A Lisp file can use a local variable setting of
+@code{lexical-binding: t} to indicate that the contents should be
+interpreted using lexical binding.  See the Emacs Lisp Reference
+Manual for more details.
+
+@cindex bidirectional display
+@cindex right-to-left languages
+@item
+Some human languages, such as English, are written from left to right.
+Others, such as Arabic, are written from right to left.  Emacs now has
+support for any mixture of these forms---this is ``bidirectional text''.
+
+@item
+Handling of text selections has been improved, and now integrates
+better with external clipboards.
+
+@cindex themes
+@item
+A new command @kbd{customize-themes} allows you to easily change the
+appearance of your Emacs.
+
+@item
+Emacs can be compiled with the Gtk+ 3 toolkit.
+
+@item
+Support for several new external libraries can be included at compile
+time:
+
+@itemize
+
+@item
+``Security-Enhanced Linux'' (SELinux) is a Linux kernel feature that
+provides more sophisticated file access controls than ordinary
+``Unix-style'' file permissions.
+
+@item
+The ImageMagick display library.  This allows you to display many more
+image format in Emacs, as well as carry out transformations such as
+rotations.
+
+@item
+The GnuTLS library for secure network communications.  Emacs uses this
+transparently for email if your mail server supports it.
+
+@item
+The libxml2 library for parsing XML structures.
+@end itemize
+
+@item
+Much more flexibility in the handling of windows and buffer display.
+
+@end itemize
+
+As always, consult the @file{NEWS} file for more information.
+
+
 @node New in Emacs 23
 @section What is different about Emacs 23?
 @cindex Differences between Emacs 22 and Emacs 23
 @cindex Emacs 23, new features in
-@cindex Recently introduced features
-@cindex Default features
 
 @itemize
 
@@ -1065,8 +1138,7 @@ Other changes include: support for serial port access; D-Bus bindings; a
 new Visual Line mode for line-motion; improved completion; a new mode
 (@samp{DocView}) for viewing of PDF, PostScript, and DVI documents; nXML
 mode (for editing XML documents) is included; VC has been updated for
-newer version control systems; etc.  As always, consult the @file{NEWS}
-file for more information.
+newer version control systems; etc.
 
 
 @node New in Emacs 22
@@ -3225,6 +3297,14 @@ see @ref{Packages that do not come with Emacs}.
 @cindex Emacs Lisp List
 @cindex Emacs Lisp Archive
 
+Your first port of call should be the @kbd{M-x list-packages} command.
+This connects to the @uref{http:///elpa.gnu.org, GNU ELPA} (``Emacs
+Lisp Package Archive'') server and fetches the list of additional
+packages that it offers.  These are GNU packages that are available
+for use with Emacs, but are distributed separately.  Select a package
+to get more details about the features that it offers, and then if you
+wish, Emacs can download and automatically install it for you.
+
 @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp
 List (ELL)}, maintained by @email{S.J.Eglen@@damtp.cam.ac.uk, Stephen Eglen},
 aims to provide one compact list with links to all of the current Emacs