Merge from origin/emacs-25

0ffc9ce Update admin/authors.el
0ad7410 Update Antinews in ELisp manual
ea0f750 Fix comments on window height macros
0bbdeed Fix 'url-http-create-request' when cookies are used
0045998 Fix cross reference in frames.texi
1392894 ; * etc/DEBUG: Minor copyedits.
304a5c8 ; * etc/DEBUG: Improve documentation of getting control to GDB.
56bf7d7 Fix regexp-opt documentation (bug #17862)
803ad6f ; Fix documentation of seq-subseq
ed4530d * lisp/emacs-lisp/gv.el (gv-ref): Fix example of PLACE in doc...
88ea396 ; Spelling fixes
17197d0 Fix tags-query-replace docstring
80a7f8b Clarify documentation of precision in format specs
88a5052 Improve and clarify documentation of subprocesses
89eb09f * etc/PROBLEMS: Mention gnutls-cli 3.5.3 (Bug#24247).

# Conflicts:
#	etc/PROBLEMS
#	src/process.c

17 files changed, 619 insertions, 445 deletions

diff --git a/admin/authors.el b/admin/authors.el
index 3e9e005e222..198a8e4d260 100644
--- a/admin/authors.el
+++ b/admin/authors.el
@@ -621,6 +621,8 @@ Changes to files in this list are not listed.")
     ;; windowsnt.h to ms-w32.h.
     ("Geoff Voelker" :wrote "w32-fns.el" "w32.c" "w32.h" "w32heap.c"
      "w32heap.h" "w32inevt.c" "w32proc.c" "w32term.c" "ms-w32.h")
+    ("Bob Weiner" :changed "dframe.el" "etags.c" "info.el" "quail.el"
+     "rmail.el" "rmailsum.el" "speedbar.el")
     ("Morten Welinder" :wrote "dosfns.c" "[many MS-DOS files]" "msdos.h")
     ("Eli Zaretskii" :wrote "bidi.c" "[bidirectional display in xdisp.c]"
      "[tty menus in term.c]")
diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi
index 4b084014994..17d765de142 100644
--- a/doc/lispref/anti.texi
+++ b/doc/lispref/anti.texi
@@ -6,132 +6,110 @@
 @c This node must have no pointers.
 
 @node Antinews
-@appendix Emacs 23 Antinews
+@appendix Emacs 24 Antinews
 @c Update the elisp.texi Antinews menu entry with the above version number.
 
 For those users who live backwards in time, here is information about
-downgrading to Emacs version 23.4.  We hope you will enjoy the greater
+downgrading to Emacs version 24.5.  We hope you will enjoy the greater
 simplicity that results from the absence of many Emacs @value{EMACSVER}
 features.
 
-@section Old Lisp Features in Emacs 23
+@section Old Lisp Features in Emacs 24
 
 @itemize @bullet
 @item
-Support for lexical scoping has been removed; all variables are
-dynamically scoped.  The @code{lexical-binding} variable has been
-removed, and so has the @var{lexical} argument to @code{eval}.  The
-@code{defvar} and @code{defconst} forms no longer mark variables as
-dynamic, since all variables are dynamic.
-
-Having only dynamic binding follows the spirit of Emacs extensibility,
-for it allows any Emacs code to access any defined variable with a
-minimum of fuss.  But @xref{Dynamic Binding Tips}, for tips to avoid
-making your programs hard to understand.
+The requirement that @code{setq} and @code{setf} must be called with
+an even number of arguments has been removed.  You can now call them
+with an odd number of arguments, and Emacs will helpfully supply a
+@code{nil} for the missing one.  Simplicity rules!
 
 @item
-Calling a minor mode function from Lisp with a @code{nil} or omitted argument
-does not enable the minor mode unconditionally; instead, it toggles
-the minor mode---which is the straightforward thing to do, since that
-is the behavior when invoked interactively.  One downside is that it
-is more troublesome to enable minor modes from hooks; you have to do
-something like
-
-@example
-(add-hook 'foo-hook (lambda () (bar-mode 1)))
-@end example
-
-@noindent
-or define @code{turn-on-bar-mode} and call that from the hook.
+@kbd{M-x shell} and @kbd{M-x compile} set the @env{EMACS} environment
+variable, as they should, to indicate that the subprocess is run by
+Emacs.  This is so packages that took years to learn how to work
+around that setting could continue using their code to that effect.
 
 @item
-The @code{prog-mode} dummy major mode has been removed.  Instead of
-using it as a crutch to meet programming mode conventions, you should
-explicitly ensure that your mode follows those conventions.
-@xref{Major Mode Conventions}.
+The @code{save-excursion} form saves and restores the mark, as
+expected.  No more need for the new @code{save-mark-and-excursion},
+which has been deleted.
 
 @item
-Emacs no longer supports bidirectional display and editing.  Since
-there is no need to worry about the insertion of right-to-left text
-messing up how lines and paragraphs are displayed, the function
-@code{bidi-string-mark-left-to-right} has been removed; so have many
-other functions and variables related to bidirectional display.
-Unicode directionality characters like @code{U+200E} LEFT-TO-RIGHT
-MARK have no special effect on display.
+We have removed the @code{text-quoting-style} variable and the
+associated functionality that translates quote characters in messages
+displayed to the user and in help buffers.  Emacs now shows exactly
+the same quote characters as you wrote in your code!  Likewise,
+@code{substitute-command-keys} leaves the quote characters alone.  As
+you move back in time, Unicode support becomes less and less
+important, so no need to display those fancy new quotes the Unicode
+Standard invented.
 
 @item
-Emacs windows now have most of their internal state hidden from Lisp.
-Internal windows are no longer visible to Lisp; functions such as
-@code{window-parent}, window parameters related to window arrangement,
-and window-local buffer lists have all been removed.  Functions for
-resizing windows can delete windows if they become too small.
-
-The action-function feature for controlling buffer display has
-been removed, including @code{display-buffer-overriding-action} and
-related variables, as well as the @var{action} argument to
-@code{display-buffer} and other functions.  The way to
-programmatically control how Emacs chooses a window to display a
-buffer is to bind the right combination of @code{pop-up-frames} and
-other variables.
+Regular expressions have been simplified by removing support for
+Unicode character properties in regexp classes.  As result,
+@code{[:alpha:]} and @code{[:alnum:]} will match any character with a
+word syntax, and @code{[:graph:]} and @code{[:print:]} will match any
+multibyte character, including surrogates and unassigned codepoints.
+Once again, this is in line with diminishing importance of Unicode as
+you move back in time.
 
 @item
-The standard completion interface has been simplified, eliminating the
-@code{completion-extra-properties} variable, the @code{metadata}
-action flag for completion functions, and the concept of
-completion categories.  Lisp programmers may now find the choice
-of methods for tuning completion less bewildering, but if a package
-finds the streamlined interface insufficient for its needs, it must
-implement its own specialized completion feature.
+Evaluating @samp{(/ @var{n})} will now yield @var{n}.  We have
+realized that interpreting that as in Common Lisp was a bad mistake
+that needed to be corrected.
 
 @item
-@code{copy-directory} now behaves the same whether or not the
-destination is an existing directory: if the destination exists, the
-@emph{contents} of the first directory are copied into it (with
-subdirectories handled recursively), rather than copying the first
-directory into a subdirectory.
+The @code{pcase} form was significantly simplified by removing the
+UPatterns @code{quote} and @code{app}.  To further simplify this
+facility, we've removed @code{pcase-defmacro}, since we found no need
+for letting Lisp programs define new UPatterns.
 
 @item
-The @var{trash} arguments for @code{delete-file} and
-@code{delete-directory} have been removed.  The variable
-@code{delete-by-moving-to-trash} must now be used with care; whenever
-it is non-@code{nil}, all calls to @code{delete-file} or
-@code{delete-directory} use the trash.
+We've removed the text properties @code{cursor-intangible} and
+@code{cursor-sensor-functions}, replacing them by the much simpler
+@code{intangible}, @code{point-entered}, and @code{point-left}
+properties.  The latter are implemented on a much lower level, and
+therefore are better integrated with user expectations.  For similar
+reasons, @code{cursor-intangible-mode} and @code{cursor-sensor-mode}
+were removed; use the hook variable @code{inhibit-point-motion-hooks}
+which is no longer obsolete.
 
 @item
-Because Emacs no longer supports SELinux file contexts, the
-@var{preserve-selinux-context} argument to @code{copy-file} has been
-removed.  The return value of @code{backup-buffer} no longer has an
-entry for the SELinux file context.
+Process creation and management functions were significantly improved
+and simplified by removing @code{make-process} and the @code{pipe}
+connection type.  Redirecting @code{stderr} of a subprocess should be
+done with shell facilities, not by Emacs.
 
 @item
-For mouse click input events in the text area, the Y pixel coordinate
-in the @var{position} list (@pxref{Click Events}) now counts from the
-top of the header line, if there is one, rather than the top of the
-text area.
+We decided that shutting up informative messages is bad for user
+interaction, so we've removed the @code{inhibit-message} variable
+which could be used to that effect.
 
 @item
-Bindings in menu keymaps (@pxref{Format of Keymaps}) now sometimes get
-an additional @var{cache} entry in their definitions, like this:
+Support for generators and for finalizers has been removed, as we
+found no real need for these facilities.
 
-@example
-(@var{type} @var{item-name} @var{cache} . @var{binding})
-@end example
-
-@noindent
-The @var{cache} entry is used internally by Emacs to record equivalent
-keyboard key sequences for invoking the same command; Lisp programs
-should never use it.
-@c Not really NEWS-worthy then...
+@item
+Due to excessive complexity and the diminishing need for Unicode
+support, the functions @code{string-collate-lessp} and
+@code{string-collate-equalp} were removed.  Their locale-independent
+counterparts @code{string-lessp} and @code{string-equal} are so much
+more simple and yield predictable results that we don't see any
+situation where the locale-dependent collation could be useful in
+Emacs.  As result, the @file{ls-lisp.el} package sorts files in a
+locale-independent manner.
 
 @item
-The @code{gnutls} library has been removed, and the function
-@code{open-network-stream} correspondingly simplified.
-Lisp programs that want an encrypted network connection must now call
-external utilities such as @command{starttls} or @command{gnutls-cli}.
+In preparation for removal in some past version of Emacs of the
+bidirectional editing support, we started by deleting two functions
+@code{bidi-find-overridden-directionality} and
+@code{buffer-substring-with-bidi-context}.
 
 @item
-Tool bars can no longer display separators, which frees up several
-pixels of space on each graphical frame.
+Time conversion functions, such as @code{current-time-string}, no
+longer accept an optional @var{zone} argument.  If you need to change
+the current time zone (why?), do that explicitly with
+@code{set-time-zone-rule}.
 
 @item
 As part of the ongoing quest for simplicity, many other functions and
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a3bff0b07ac..3297e5308ae 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -228,7 +228,7 @@ To view this manual in other formats, click
 
 Appendices
 
-* Antinews::                Info for users downgrading to Emacs 23.
+* Antinews::                Info for users downgrading to Emacs 24.
 * GNU Free Documentation License:: The license for this documentation.
 * GPL::                     Conditions for copying and changing GNU Emacs.
 * Tips::                    Advice and coding conventions for Emacs Lisp.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 53406d114af..7736438126c 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1992,8 +1992,7 @@ Window Ordering}.
 
 Normally, each frame has its own minibuffer window at the bottom, which
 is used whenever that frame is selected.  If the frame has a minibuffer,
-you can get it with @code{minibuffer-window} (@pxref{Definition of
-minibuffer-window}).
+you can get it with @code{minibuffer-window} (@pxref{Minibuffer Windows}).
 
 @cindex frame without a minibuffer
 @cindex surrogate minibuffer frame
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index e54cf301d4e..f9d5096dbea 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -27,9 +27,18 @@ with the subprocess or to control it.  For example, you can send
 signals, obtain status information, receive output from the process, or
 send input to it.
 
+  In addition to processes that run programs, Lisp programs can open
+connections of several types to devices or processes running on the
+same machine or on other machines.  The supported connection types
+are: TCP and UDP network connections, serial port connections, and
+pipe connections.  Each such connection is also represented by a
+process object.
+
 @defun processp object
 This function returns @code{t} if @var{object} represents an Emacs
-subprocess, @code{nil} otherwise.
+process object, @code{nil} otherwise.  The process object can
+represent a subprocess running a program or a connection of any
+supported type.
 @end defun
 
   In addition to subprocesses of the current Emacs session, you can
@@ -67,7 +76,7 @@ Processes}.
 @cindex process creation
 
   There are three primitives that create a new subprocess in which to run
-a program.  One of them, @code{start-process}, creates an asynchronous
+a program.  One of them, @code{make-process}, creates an asynchronous
 process and returns a process object (@pxref{Asynchronous Processes}).
 The other two, @code{call-process} and @code{call-process-region},
 create a synchronous process and do not return a process object
@@ -82,15 +91,14 @@ fashion, their common arguments are described here.
 @cindex execute program
 @cindex @env{PATH} environment variable
 @cindex @env{HOME} environment variable
-  In all cases, the function's @var{program} argument specifies the
-program to be run.  An error is signaled if the file is not found or
-cannot be executed.  If the file name is relative, the variable
-@code{exec-path} contains a list of directories to search.  Emacs
-initializes @code{exec-path} when it starts up, based on the value of
-the environment variable @env{PATH}.  The standard file name
-constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
-usual in @code{exec-path}, but environment variable substitutions
-(@samp{$HOME}, etc.)@: are not recognized; use
+  In all cases, the functions specify the program to be run.  An error
+is signaled if the file is not found or cannot be executed.  If the
+file name is relative, the variable @code{exec-path} contains a list
+of directories to search.  Emacs initializes @code{exec-path} when it
+starts up, based on the value of the environment variable @env{PATH}.
+The standard file name constructs, @samp{~}, @samp{.}, and @samp{..},
+are interpreted as usual in @code{exec-path}, but environment variable
+substitutions (@samp{$HOME}, etc.)@: are not recognized; use
 @code{substitute-in-file-name} to perform them (@pxref{File Name
 Expansion}).  @code{nil} in this list refers to
 @code{default-directory}.
@@ -106,27 +114,36 @@ system-dependent.
 @end defopt
 
   @strong{Please note:} The argument @var{program} contains only the
-name of the program; it may not contain any command-line arguments.  You
-must use a separate argument, @var{args}, to provide those, as
-described below.
+name of the program file; it may not contain any command-line
+arguments.  You must use a separate argument, @var{args}, to provide
+those, as described below.
 
   Each of the subprocess-creating functions has a @var{buffer-or-name}
-argument that specifies where the standard output from the program will
-go.  It should be a buffer or a buffer name; if it is a buffer name,
-that will create the buffer if it does not already exist.  It can also
-be @code{nil}, which says to discard the output, unless a custom filter function
-handles it.  (@xref{Filter Functions}, and @ref{Read and Print}.)
-Normally, you should avoid having multiple processes send output to the
-same buffer because their output would be intermixed randomly.
-For synchronous processes, you can send the output to a file instead
-of a buffer.
+argument that specifies where the output from the program will go.  It
+should be a buffer or a buffer name; if it is a buffer name, that will
+create the buffer if it does not already exist.  It can also be
+@code{nil}, which says to discard the output, unless a custom filter
+function handles it.  (@xref{Filter Functions}, and @ref{Read and
+Print}.)  Normally, you should avoid having multiple processes send
+output to the same buffer because their output would be intermixed
+randomly.  For synchronous processes, you can send the output to a
+file instead of a buffer (and the corresponding argument is therefore
+more appropriately called @var{destination}).  By default, both
+standard output and standard error streams go to the same destination,
+but all the 3 primitives allow optionally to direct the standard error
+stream to a different destination.
 
 @cindex program arguments
-  All three of the subprocess-creating functions have a @code{&rest}
-argument, @var{args}.  The @var{args} must all be strings, and they are
-supplied to @var{program} as separate command line arguments.  Wildcard
-characters and other shell constructs have no special meanings in these
-strings, since the strings are passed directly to the specified program.
+  All three of the subprocess-creating functions allow to specify
+command-line arguments for the process to run. For @code{call-process}
+and @code{call-process-region}, these come in the form of a
+@code{&rest} argument, @var{args}.  For @code{make-process}, both the
+program to run and its command-line arguments are specified as a list
+of strings.  The command-line arguments must all be strings, and they
+are supplied to the program as separate argument strings.  Wildcard
+characters and other shell constructs have no special meanings in
+these strings, since the strings are passed directly to the specified
+program.
 
 @cindex environment variables, subprocesses
   The subprocess inherits its environment from Emacs, but you can
@@ -147,6 +164,7 @@ The value of this variable is a list of directories to search for
 programs to run in subprocesses.  Each element is either the name of a
 directory (i.e., a string), or @code{nil}, which stands for the default
 directory (which is the value of @code{default-directory}).
+@xref{Locating Files, executable-find}, for the details of this search.
 @cindex program directories
 
 The value of @code{exec-path} is used by @code{call-process} and
@@ -210,11 +228,11 @@ a shell command:
   The following two functions are useful for combining a list of
 individual command-line argument strings into a single string, and
 taking a string apart into a list of individual command-line
-arguments.  These functions are mainly intended for
-converting user input in the minibuffer, a Lisp string, into a list of
-string arguments to be passed to @code{call-process} or
-@code{start-process}, or for converting such lists of arguments into
-a single Lisp string to be presented in the minibuffer or echo area.
+arguments.  These functions are mainly intended for converting user
+input in the minibuffer, a Lisp string, into a list of string
+arguments to be passed to @code{make-process}, @code{call-process} or
+@code{start-process}, or for converting such lists of arguments into a
+single Lisp string to be presented in the minibuffer or echo area.
 Note that if a shell is involved (e.g., if using
 @code{call-process-shell-command}), arguments should still be
 protected by @code{shell-quote-argument};
@@ -331,7 +349,7 @@ string specifies a file name to redirect error output into.
 You can't directly specify a buffer to put the error output in; that is
 too difficult to implement.  But you can achieve this result by sending
 the error output to a temporary file and then inserting the file into a
-buffer.
+buffer when the subprocess finishes.
 @end table
 
 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
@@ -346,13 +364,15 @@ results become visible on the screen only when Emacs redisplays that
 buffer in the normal course of events.
 
 The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
+line arguments for the program.  Each string is passed to
+@var{program} as a separate argument.
 
 The value returned by @code{call-process} (unless you told it not to
 wait) indicates the reason for process termination.  A number gives the
 exit status of the subprocess; 0 means success, and any other value
 means failure.  If the process terminated with a signal,
-@code{call-process} returns a string describing the signal.
+@code{call-process} returns a string describing the signal.  If you
+told @code{call-process} not to wait, it returns @code{nil}.
 
 In the examples below, the buffer @samp{foo} is current.
 
@@ -507,10 +527,10 @@ inputinput@point{}
 
 @defun call-process-shell-command command &optional infile destination display
 This function executes the shell command @var{command} synchronously.
-The arguments are handled as in @code{call-process}.  An old calling
-convention allowed passing any number of additional arguments after
-@var{display}, which were concatenated to @var{command}; this is still
-supported, but strongly discouraged.
+The other arguments are handled as in @code{call-process}.  An old
+calling convention allowed passing any number of additional arguments
+after @var{display}, which were concatenated to @var{command}; this is
+still supported, but strongly discouraged.
 @end defun
 
 @defun process-file-shell-command command &optional infile destination display
@@ -571,33 +591,169 @@ from the process only while waiting for input or for a time delay.
 @cindex pipe
   An asynchronous process is controlled either via a @dfn{pty}
 (pseudo-terminal) or a @dfn{pipe}.  The choice of pty or pipe is made
-when creating the process, based on the value of the variable
-@code{process-connection-type} (see below).  Ptys are usually
-preferable for processes visible to the user, as in Shell mode,
-because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@:
-between the process and its children, whereas pipes do not.  For
-subprocesses used for internal purposes by programs, it is often
-better to use a pipe, because they are more efficient, and because
-they are immune to stray character injections that ptys introduce for
-large (around 500 byte) messages.  Also, the total number of ptys is
-limited on many systems and it is good not to waste them.
+when creating the process, by default based on the value of the
+variable @code{process-connection-type} (see below).  If available,
+ptys are usually preferable for processes visible to the user, as in
+Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z},
+etc.)@: between the process and its children, and because interactive
+programs treat ptys as terminal devices, whereas pipes don't support
+these features.  However, for subprocesses used by Lisp programs for
+internal purposes, it is often better to use a pipe, because pipes are
+more efficient, and because they are immune to stray character
+injections that ptys introduce for large (around 500 byte) messages.
+Also, the total number of ptys is limited on many systems and it is
+good not to waste them.
+
+@defun make-process &rest args
+This function is the basic low-level primitive for starting
+asynchronous subprocesses.  It returns a process object representing
+the subprocess.  Compared to the more high-level @code{start-process},
+described below, it takes keyword arguments, is more flexible, and
+allows to specify process filters and sentinels in a single call.
+
+The arguments @var{args} are a list of keyword/argument pairs.
+Omitting a keyword is always equivalent to specifying it with value
+@code{nil}.  Here are the meaningful keywords:
+
+@table @asis
+@item :name @var{name}
+Use the string @var{name} as the process name; if a process with this
+name already exists, then @var{name} is modified (by appending
+@samp{<1>}, etc.)@: to be unique.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.  If the value is @code{nil},
+the subprocess is not associated with any buffer.
+
+@item :command @var{command}
+Use @var{command} as the command line of the process.  The value
+should be a list starting with the program's executable file name,
+followed by strings to give to the program as its arguments.  If
+the first element of the list is @code{nil}, Emacs opens a new
+pseudoterminal (pty) and associates its input and output with
+@var{buffer}, without actually running any program; the rest of the
+list elements are ignored in that case.
+
+@item :coding @var{coding}
+If @var{coding} is a symbol, it specifies the coding system to be
+used for both reading and writing of data from and to the
+connection.  If @var{coding} is a cons cell
+@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
+will be used for reading and @var{encoding} for writing.  The coding
+system used for encoding the data written to the program is also used
+for encoding the command-line arguments (but not the program itself,
+whose file name is encoded as any other file name; @pxref{Encoding and
+I/O, file-name-coding-system}).
+
+If @var{coding} is @code{nil}, the default rules for finding the
+coding system will apply.  @xref{Default Coding Systems}.
+
+@item :connection-type @var{TYPE}
+Initialize the type of device used to communicate with the subprocess.
+Possible values are @code{pty} to use a pty, @code{pipe} to use a
+pipe, or @code{nil} to use the default derived from the value of the
+@code{process-connection-type} variable.  This parameter and the value
+of @code{process-connection-type} are ignored if a non-@code{nil}
+value is specified for the @code{:stderr} parameter; in that case, the
+type will always be @code{pipe}.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
+
+@item :stop @var{stopped}
+If @var{stopped} is non-@code{nil}, start the process in the
+stopped state.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided, which can be overridden later.
+@xref{Filter Functions}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used, which can be overridden later.
+@xref{Sentinels}.
+
+@item :stderr @var{stderr}
+Associate @var{stderr} with the standard error of the process.  A
+non-@code{nil} value should be either a buffer or a pipe process
+created with @code{make-pipe-process}, described below.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
+
+@defun make-pipe-process &rest args
+This function creates a bidirectional pipe which can be attached to a
+child process.  This is useful with the @code{:stderr} keyword of
+@code{make-process}.  The function returns a process object.
+
+The arguments @var{args} are a list of keyword/argument pairs.
+Omitting a keyword is always equivalent to specifying it with value
+@code{nil}.
+
+Here are the meaningful keywords:
+
+@table @asis
+@item :name @var{name}
+Use the string @var{name} as the process name.  As with
+@code{make-process}, it is modified if necessary to make it unique.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :coding @var{coding}
+If @var{coding} is a symbol, it specifies the coding system to be
+used for both reading and writing of data from and to the
+connection.  If @var{coding} is a cons cell
+@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
+will be used for reading and @var{encoding} for writing.
+
+If @var{coding} is @code{nil}, the default rules for finding the
+coding system will apply.  @xref{Default Coding Systems}.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
+
+@item :stop @var{stopped}
+If @var{stopped} is non-@code{nil}, start the process in the
+stopped state.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided, which can be changed later.
+@xref{Filter Functions}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used, which can be changed later.
+@xref{Sentinels}.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
 
 @defun start-process name buffer-or-name program &rest args
-This function creates a new asynchronous subprocess and starts the
-program @var{program} running in it.  It returns a process object that
-stands for the new subprocess in Lisp.  The argument @var{name}
-specifies the name for the process object; if a process with this name
-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.
+This function is a higher-level wrapper around @code{make-process},
+exposing an interface that is similar to @code{call-process}.  It
+creates a new asynchronous subprocess and starts the specified
+@var{program} running in it.  It returns a process object that stands
+for the new subprocess in Lisp.  The argument @var{name} specifies the
+name for the process object; as with @code{make-process}, it is
+modified if necessary to make it 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 subprocess.
+The rest of @var{args} are strings that specify command 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
@@ -639,14 +795,14 @@ subprocess running @var{program} in it, and returns its process
 object.
 
 The difference from @code{start-process} is that this function may
-invoked a file handler based on the value of @code{default-directory}.
+invoke a file handler based on the value of @code{default-directory}.
 This handler ought to run @var{program}, perhaps on the local host,
 perhaps on a remote host that corresponds to @code{default-directory}.
 In the latter case, the local part of @code{default-directory} becomes
 the working directory of the process.
 
 This function does not try to invoke file name handlers for
-@var{program} or for the @var{program-args}.
+@var{program} or for the rest of @var{args}.
 
 Depending on the implementation of the file handler, it might not be
 possible to apply @code{process-filter} or @code{process-sentinel} to
@@ -660,19 +816,20 @@ this function does nothing and returns @code{nil}.
 @end defun
 
 @defun start-process-shell-command name buffer-or-name command
-This function is like @code{start-process}, except that it uses a shell
-to execute the specified command.  The argument @var{command} is a shell
-command name.  The variable @code{shell-file-name} specifies which shell to
-use.
+This function is like @code{start-process}, except that it uses a
+shell to execute the specified @var{command}.  The argument
+@var{command} is a shell command string.  The variable
+@code{shell-file-name} specifies which shell to use.
 
 The point of running a program through the shell, rather than directly
-with @code{start-process}, is so that you can employ shell features such
-as wildcards in the arguments.  It follows that if you include any
-arbitrary user-specified arguments in the command, you should quote them
-with @code{shell-quote-argument} first, so that any special shell
-characters do @emph{not} have their special shell meanings.  @xref{Shell
-Arguments}.  Of course, when executing commands based on user input
-you should also consider the security implications.
+with @code{make-process} or @code{start-process}, is so that you can
+employ shell features such as wildcards in the arguments.  It follows
+that if you include any arbitrary user-specified arguments in the
+command, you should quote them with @code{shell-quote-argument} first,
+so that any special shell characters do @emph{not} have their special
+shell meanings.  @xref{Shell Arguments}.  Of course, when executing
+commands based on user input you should also consider the security
+implications.
 @end defun
 
 @defun start-file-process-shell-command name buffer-or-name command
@@ -687,9 +844,14 @@ asynchronous subprocesses.  If it is non-@code{nil}, then ptys are
 used, when available.  Otherwise, pipes are used.
 
 The value of @code{process-connection-type} takes effect when
-@code{start-process} is called.  So you can specify how to communicate
-with one subprocess by binding the variable around the call to
-@code{start-process}.
+@code{make-process} or @code{start-process} is called.  So you can
+specify how to communicate with one subprocess by binding the variable
+around the call to these functions.
+
+Note that the value of this variable is ignored when
+@code{make-process} is called with a non-@code{nil} value of the
+@code{:stderr} parameter; in that case, Emacs will communicate with
+the process using pipes.
 
 @smallexample
 @group
@@ -703,117 +865,6 @@ use the function @code{process-tty-name} (@pxref{Process
 Information}).
 @end defvar
 
-@defun make-process &rest args
-This function is like @code{start-process}, but takes keyword arguments.
-
-The arguments @var{args} are a list of keyword/argument pairs.
-Omitting a keyword is always equivalent to specifying it with value
-@code{nil}.  Here are the meaningful keywords:
-
-@table @asis
-@item :name @var{name}
-Use the string @var{name} as the process name.  It is modified if
-necessary to make it unique.
-
-@item :buffer @var{buffer}
-Use @var{buffer} as the process buffer.
-
-@item :command @var{command}
-Use @var{command} as the command line of the process.  @var{command}
-is a list starting with the program's executable file name, followed
-by strings to give to program as arguments.
-
-@item :coding @var{coding}
-If @var{coding} is a symbol, it specifies the coding system to be
-used for both reading and writing of data from and to the
-connection.  If @var{coding} is a cons cell
-@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
-will be used for reading and @var{encoding} for writing.
-
-If @var{coding} is @code{nil}, the default rules for finding the
-coding system will apply.  @xref{Default Coding Systems}.
-
-@item :connection-type @var{TYPE}
-Initialize the type of device used to communicate with the subprocess.
-Possible values are @code{pty} to use a pty, @code{pipe} to use a
-pipe, or @code{nil} to use the default derived from the value of
-the @code{process-connection-type} variable.
-
-@item :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.
-@xref{Query Before Exit}.
-
-@item :stop @var{stopped}
-If @var{stopped} is non-@code{nil}, start the process in the
-stopped state.
-
-@item :filter @var{filter}
-Initialize the process filter to @var{filter}.  If not specified, a
-default filter will be provided.  @xref{Filter Functions}.
-
-@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.  If not specified,
-a default sentinel will be used.  @xref{Sentinels}.
-
-@item :stderr @var{stderr}
-Associate @var{stderr} with the standard error of the process.
-@var{stderr} is either a buffer or a pipe process created with
-@code{make-pipe-process}.
-@end table
-
-The original argument list, modified with the actual connection
-information, is available via the @code{process-contact} function.
-@end defun
-
-@defun make-pipe-process &rest args
-This function creates a bidirectional pipe which can be attached to a
-child process (currently only useful with the @code{:stderr} keyword
-of @code{make-process}).
-
-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}.
-Here are the meaningful keywords:
-
-@table @asis
-@item :name @var{name}
-Use the string @var{name} as the process name.  It is modified if
-necessary to make it unique.
-
-@item :buffer @var{buffer}
-Use @var{buffer} as the process buffer.
-
-@item :coding @var{coding}
-If @var{coding} is a symbol, it specifies the coding system to be
-used for both reading and writing of data from and to the
-connection.  If @var{coding} is a cons cell
-@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
-will be used for reading and @var{encoding} for writing.
-
-If @var{coding} is @code{nil}, the default rules for finding the
-coding system will apply.  @xref{Default Coding Systems}.
-
-@item :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.
-@xref{Query Before Exit}.
-
-@item :stop @var{stopped}
-If @var{stopped} is non-@code{nil}, start the process in the
-stopped state.
-
-@item :filter @var{filter}
-Initialize the process filter to @var{filter}.  If not specified, a
-default filter will be provided.  @xref{Filter Functions}.
-
-@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.  If not specified,
-a default sentinel will be used.  @xref{Sentinels}.
-@end table
-
-The original argument list, modified with the actual connection
-information, is available via the @code{process-contact} function.
-@end defun
-
 @node Deleting Processes
 @section Deleting Processes
 @cindex deleting processes
@@ -843,14 +894,19 @@ they exit.
 
 @defun delete-process process
 This function deletes a process, killing it with a @code{SIGKILL}
-signal.  The argument may be a process, the name of a process, a
-buffer, or the name of a buffer.  (A buffer or buffer-name stands for
-the process that @code{get-buffer-process} returns.)  Calling
-@code{delete-process} on a running process terminates it, updates the
-process status, and runs the sentinel immediately.  If the
-process has already terminated, calling @code{delete-process} has no
-effect on its status, or on the running of its sentinel (which will
-happen sooner or later).
+signal if the process was running a program.  The argument may be a
+process, the name of a process, a buffer, or the name of a buffer.  (A
+buffer or buffer-name stands for the process that
+@code{get-buffer-process} returns.)  Calling @code{delete-process} on
+a running process terminates it, updates the process status, and runs
+the sentinel immediately.  If the process has already terminated,
+calling @code{delete-process} has no effect on its status, or on the
+running of its sentinel (which will happen sooner or later).
+
+If the process object represents a network, serial, or pipe
+connection, its status changes to @code{closed}; otherwise, it changes
+to @code{signal}, unless the process already exited.  @xref{Process
+Information, process-status}.
 
 @smallexample
 @group
@@ -892,7 +948,8 @@ This function returns a list of all processes that have not been deleted.
 
 @defun get-process name
 This function returns the process named @var{name} (a string), or
-@code{nil} if there is none.
+@code{nil} if there is none.  The argument @var{name} can also be a
+process object, in which case it is returned.
 
 @smallexample
 @group
@@ -906,7 +963,9 @@ This function returns the process named @var{name} (a string), or
 This function returns the command that was executed to start
 @var{process}.  This is a list of strings, the first string being the
 program executed and the rest of the strings being the arguments that
-were given to the program.
+were given to the program.  For a network, serial, or pipe connection,
+this is either @code{nil}, which means the process is running or
+@code{t} (process is stopped).
 
 @smallexample
 @group
@@ -917,18 +976,19 @@ were given to the program.
 @end defun
 
 @defun process-contact process &optional key
-
-This function returns information about how a network or serial
-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}.
+This function returns information about how a network, a serial, or a
+pipe connection was set up.  When @var{key} is @code{nil}, it returns
+@code{(@var{hostname} @var{service})} for a network connection,
+@code{(@var{port} @var{speed})} for a serial connection, and @code{t}
+for a pipe connection.  For an ordinary child process, this function
+always returns @code{t} when called with a @code{nil} @var{key}.
 
 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
-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 the connection, server, serial port, or pipe; that is, the list of
+keywords and values specified in @code{make-network-process},
+@code{make-serial-process}, or @code{make-pipe-process}, except that
+some of the values represent the current status instead of what you
+specified.
 
 For a network process, the values include (see
 @code{make-network-process} for a complete list):
@@ -953,8 +1013,9 @@ this value is the actual port number.
 @code{:local} and @code{:remote} are included even if they were not
 specified explicitly in @code{make-network-process}.
 
-For a serial process, see @code{make-serial-process} and
-@code{serial-process-configure} for a list of keys.
+For a serial connection, see @code{make-serial-process} and
+@code{serial-process-configure} for the list of keys.  For a pipe
+connection, see @code{make-pipe-process} for the list of keys.
 
 If @var{key} is a keyword, the function returns the value corresponding
 to that keyword.
@@ -962,10 +1023,12 @@ to that keyword.
 
 @defun process-id process
 This function returns the @acronym{PID} of @var{process}.  This is an
-integer that distinguishes the process @var{process} from all other
-processes running on the same computer at the current time.  The
-@acronym{PID} of a process is chosen by the operating system kernel when the
-process is started and remains constant as long as the process exists.
+integral number that distinguishes the process @var{process} from all
+other processes running on the same computer at the current time.  The
+@acronym{PID} of a process is chosen by the operating system kernel
+when the process is started and remains constant as long as the
+process exists.  For network, serial, and pipe connections, this
+function returns @code{nil}.
 @end defun
 
 @defun process-name process
@@ -989,11 +1052,11 @@ for a process that has exited.
 @item signal
 for a process that has received a fatal signal.
 @item open
-for a network connection that is open.
+for a network, serial, or pipe connection that is open.
 @item closed
-for a network connection that is closed.  Once a connection
-is closed, you cannot reopen it, though you might be able to open
-a new connection to the same place.
+for a network, serial, or pipe connection that is closed.  Once a
+connection is closed, you cannot reopen it, though you might be able
+to open a new connection to the same place.
 @item connect
 for a non-blocking connection that is waiting to complete.
 @item failed
@@ -1011,9 +1074,11 @@ if @var{process-name} is not the name of an existing process.
 @end group
 @end smallexample
 
-For a network connection, @code{process-status} returns one of the symbols
-@code{open} or @code{closed}.  The latter means that the other side
-closed the connection, or Emacs did @code{delete-process}.
+For a network, serial, or pipe connection, @code{process-status}
+returns one of the symbols @code{open}, @code{stop}, or @code{closed}.
+The latter means that the other side closed the connection, or Emacs
+did @code{delete-process}.  The value @code{stop} means that
+@code{stop-process} was called on the connection.
 @end defun
 
 @defun process-live-p process
@@ -1024,24 +1089,29 @@ process is considered alive if its status is @code{run}, @code{open},
 
 @defun process-type process
 This function returns the symbol @code{network} for a network
-connection or server, @code{serial} for a serial port connection, or
-@code{real} for a real subprocess.
+connection or server, @code{serial} for a serial port connection,
+@code{pipe} for a pipe connection, or @code{real} for a subprocess
+created for running a program.
 @end defun
 
 @defun process-exit-status process
 This function returns the exit status of @var{process} or the signal
 number that killed it.  (Use the result of @code{process-status} to
 determine which of those it is.)  If @var{process} has not yet
-terminated, the value is 0.
+terminated, the value is 0.  For network, serial, and pipe connections
+that are already closed, the value is either 0 or 256, depending on
+whether the connection was closed normally or abnormally.
 @end defun
 
 @defun process-tty-name process
 This function returns the terminal name that @var{process} is using for
 its communication with Emacs---or @code{nil} if it is using pipes
-instead of a terminal (see @code{process-connection-type} in
+instead of a pty (see @code{process-connection-type} in
 @ref{Asynchronous Processes}).  If @var{process} represents a program
 running on a remote host, the terminal name used by that program on
-the remote host is provided as process property @code{remote-tty}.
+the remote host is provided as process property @code{remote-tty}.  If
+@var{process} represents a network, serial, or pipe connection, the
+value is @code{nil}.
 @end defun
 
 @defun process-coding-system process
@@ -1085,8 +1155,10 @@ This function sets the process plist of @var{process} to @var{plist}.
 
   Asynchronous subprocesses receive input when it is sent to them by
 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.
+specify the process to send input to, and the input data to send.  If
+the subprocess runs a program, the data appears on the standard input
+of that program; for connections, the data is sent to the connected
+device or program.
 
 @c FIXME which?
   Some operating systems have limited space for buffered input in a
@@ -1149,12 +1221,14 @@ The function returns @var{process}.
 @end defun
 
 @defun process-running-child-p &optional process
-This function will tell you whether a @var{process} has given control
-of its terminal to its own child process.  If this is true, the
-function returns the numeric ID of the foreground process group of
-@var{process}; it returns @code{nil} if Emacs can be certain that this
-is not so.  The value is @code{t} if Emacs cannot tell whether this is
-true.
+This function will tell you whether a @var{process}, which must not be
+a connection but a real subprocess, has given control of its terminal
+to a child process of its own.  If this is true, the function returns
+the numeric ID of the foreground process group of @var{process}; it
+returns @code{nil} if Emacs can be certain that this is not so.  The
+value is @code{t} if Emacs cannot tell whether this is true.  This
+function signals an error if @var{process} is a network, serial, or
+pipe connection, or is the subprocess is not active.
 @end defun
 
 @node Signals to Processes
@@ -1187,17 +1261,22 @@ user ``hung up the phone'', i.e., disconnected.)
   The argument @var{process} must be either a process, a process
 name, a buffer, a buffer name, or @code{nil}.  A buffer or buffer name
 stands for a process through @code{get-buffer-process}.  @code{nil}
-stands for the process associated with the current buffer.  An error
-is signaled if @var{process} does not identify a process.
+stands for the process associated with the current buffer.  Except
+with @code{stop-process} and @code{continue-process}, an error is
+signaled if @var{process} does not identify an active process, or if
+it represents a network, serial, or pipe connection.
 
   The argument @var{current-group} is a flag that makes a difference
 when you are running a job-control shell as an Emacs subprocess.  If it
 is non-@code{nil}, then the signal is sent to the current process-group
 of the terminal that Emacs uses to communicate with the subprocess.  If
 the process is a job-control shell, this means the shell's current
-subjob.  If it is @code{nil}, the signal is sent to the process group of
-the immediate subprocess of Emacs.  If the subprocess is a job-control
-shell, this is the shell itself.
+subjob.  If @var{current-group} is @code{nil}, the signal is
+sent to the process group of the immediate subprocess of Emacs.  If
+the subprocess is a job-control shell, this is the shell itself.  If
+@var{current-group} is @code{lambda}, the signal is sent to the
+process-group that owns the terminal, but only if it is not the shell
+itself.
 
   The flag @var{current-group} has no effect when a pipe is used to
 communicate with the subprocess, because the operating system does not
@@ -1228,21 +1307,29 @@ Emacs.
 @end defun
 
 @defun stop-process &optional process current-group
-This function stops the process @var{process} by sending the
-signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
+This function stops the specified @var{process}.  If it is a real
+subprocess running a program, it sends the signal @code{SIGTSTP} to
+that subprocess.  If @var{process} represents a network, serial, or
+pipe connection, this function inhibits handling of the incoming data
+from the connection; for a network server, this means not accepting
+new connections.  Use @code{continue-process} to resume normal
 execution.
 
 Outside of Emacs, on systems with job control, the stop character
-(usually @kbd{C-z}) normally sends this signal.  When
-@var{current-group} is non-@code{nil}, you can think of this function as
-typing @kbd{C-z} on the terminal Emacs uses to communicate with the
-subprocess.
+(usually @kbd{C-z}) normally sends the @code{SIGTSTP} signal to a
+subprocess.  When @var{current-group} is non-@code{nil}, you can think
+of this function as typing @kbd{C-z} on the terminal Emacs uses to
+communicate with the subprocess.
 @end defun
 
 @defun continue-process &optional process current-group
-This function resumes execution of the process @var{process} by sending
-it the signal @code{SIGCONT}.  This presumes that @var{process} was
-stopped previously.
+This function resumes execution of the process @var{process}.  If it
+is a real subprocess running a program, it sends the signal
+@code{SIGCONT} to that subprocess; this presumes that @var{process}
+was stopped previously.  If @var{process} represents a network,
+serial, or pipe connection, this function resumes handling of the
+incoming data from the connection.  For serial connections, data that
+arrived during the time the process was stopped might be lost.
 @end defun
 
 @deffn Command signal-process process signal
@@ -1260,12 +1347,28 @@ children of Emacs.  @xref{System Processes}.
 @cindex process output
 @cindex output from processes
 
-  The output that a subprocess writes to its standard output stream
-is passed to a function called the @dfn{filter function}.  The default
-filter function simply inserts the output into a buffer, which is
-called the associated buffer of the process (@pxref{Process
-Buffers}).  If the process has no buffer then the default filter
-discards the output.
+  The output that an asynchronous subprocess writes to its standard
+output stream is passed to a function called the @dfn{filter
+function}.  The default filter function simply inserts the output into
+a buffer, which is called the associated buffer of the process
+(@pxref{Process Buffers}).  If the process has no buffer then the
+default filter discards the output.
+
+  If the subprocess writes to its standard error stream, by default
+the error output is also passed to the process filter function.  If
+Emacs uses a pseudo-TTY (pty) for communication with the subprocess,
+then it is impossible to separate the standard output and standard
+error streams of the subprocess, because a pseudo-TTY has only one
+output channel.  In that case, if you want to keep the output to those
+streams separate, you should redirect one of them to a file---for
+example, by using an appropriate shell command via
+@code{start-process-shell-command} or a similar function.
+
+  Alternatively, you could use the @code{:stderr} parameter with a
+non-@code{nil} value in a call to @code{make-process}
+(@pxref{Asynchronous Processes, make-process}) to make the destination
+of the error output separate from the standard output; in that case,
+Emacs will use pipes for communicating with the subprocess.
 
   When a subprocess terminates, Emacs reads any pending output,
 then stops reading output from that subprocess.  Therefore, if the
@@ -1292,13 +1395,6 @@ from such processes, thus allowing them to produce more output before
 Emacs tries to read it.
 @end defvar
 
-  It is impossible to separate the standard output and standard error
-streams of the subprocess, because Emacs normally spawns the subprocess
-inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
-you want to keep the output to those streams separate, you should
-redirect one of them to a file---for example, by using an appropriate
-shell command.
-
 @menu
 * Process Buffers::         By default, output is put in a buffer.
 * Filter Functions::        Filter functions accept output from the process.
@@ -1333,7 +1429,7 @@ Before Exit}).  This confirmation is done by the function
 @code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
 
 @defun process-buffer process
-This function returns the associated buffer of the process
+This function returns the associated buffer of the specified
 @var{process}.
 
 @smallexample
@@ -1455,6 +1551,11 @@ standard output from the associated process.  @emph{All} output from
 that process is passed to the filter.  The default filter simply
 outputs directly to the process buffer.
 
+  By default, the error output from the process, if any, is also
+passed to the filter function, unless the destination for the standard
+error stream of the process was separated from the standard output
+when the process was created (@pxref{Output from Processes}).
+
   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 (see the function
@@ -1478,8 +1579,8 @@ cases, the right way to do this is with the macro
 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}, errors are not caught.
-This makes it possible to use the Lisp debugger to debug the
-filter function.  @xref{Debugger}.
+This makes it possible to use the Lisp debugger to debug filter
+functions.  @xref{Debugger}.
 
   Many filter functions sometimes (or always) insert the output in the
 process's buffer, mimicking the actions of the default filter.
@@ -1517,8 +1618,8 @@ text arrives, you could insert a line like the following just before the
 @end smallexample
 
   To force point to the end of the new output, no matter where it was
-previously, eliminate the variable @code{moving} and call
-@code{goto-char} unconditionally.
+previously, eliminate the variable @code{moving} from the example and
+call @code{goto-char} unconditionally.
 
 @ignore
   In earlier Emacs versions, every filter function that did regular
@@ -1841,10 +1942,11 @@ was not.
 @node Query Before Exit
 @section Querying Before Exit
 
-  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
+  When Emacs exits, it terminates all its subprocesses.  For
+subprocesses that run a program, it sends them the @code{SIGHUP}
+signal; connections are simply closed.  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
 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.
@@ -2138,13 +2240,14 @@ the @code{open-network-stream} function described below.
   To distinguish the different types of processes, the
 @code{process-type} function returns the symbol @code{network} for a
 network connection or server, @code{serial} for a serial port
-connection, or @code{real} for a real subprocess.
+connection, @code{pipe} for a pipe connection, or @code{real} for a
+real subprocess.
 
   The @code{process-status} function returns @code{open},
-@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}.
+@code{closed}, @code{connect}, @code{stop}, or @code{failed} for
+network connections.  For a network server, the status is always
+@code{listen}.  Except for @code{stop}, none of those values is
+possible for a real subprocess.  @xref{Process Information}.
 
   You can stop and resume operation of a network process by calling
 @code{stop-process} and @code{continue-process}.  For a server
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index a04e6938cef..f627c882fae 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -948,26 +948,42 @@ possible.  A hand-tuned regular expression can sometimes be slightly
 more efficient, but is almost never worth the effort.}.
 @c E.g., see http://debbugs.gnu.org/2816
 
-If the optional argument @var{paren} is non-@code{nil}, then the
-returned regular expression is always enclosed by at least one
-parentheses-grouping construct.  If @var{paren} is @code{words}, then
-that construct is additionally surrounded by @samp{\<} and @samp{\>};
-alternatively, if @var{paren} is @code{symbols}, then that construct
-is additionally surrounded by @samp{\_<} and @samp{\_>}
-(@code{symbols} is often appropriate when matching
-programming-language keywords and the like).
-
-This simplified definition of @code{regexp-opt} produces a
-regular expression which is equivalent to the actual value
-(but not as efficient):
+The optional argument @var{paren} can be any of the following:
+
+a string
+    the resulting regexp is preceded by @var{paren} and followed by
+    @samp{\)}, e.g. use @samp{"\\(?1:"} to produce an explicitly
+    numbered group.
+
+@code{words}
+    the resulting regexp is surrounded by @samp{\<\(} and @samp{\)\>}.
+
+@code{symbols}
+    the resulting regexp is surrounded by @samp{\_<\(} and @samp{\)\_>}
+    (this is often appropriate when maching programming-language
+    keywords and the like).
+
+non-@code{nil}
+    the resulting regexp is surrounded by @samp{\(} and @samp{\)}.
+
+@code{nil}
+    the resulting regexp is surrounded by @samp{\(?:} and @samp{\)},
+    if it is necessary to ensure that a postfix operator appended to
+    it will apply to the whole expression.
+
+The resulting regexp of @code{regexp-opt} is equivalent to but usually
+more efficient than that of a simplified version:
 
 @example
-(defun regexp-opt (strings &optional paren)
-  (let ((open-paren (if paren "\\(" ""))
-        (close-paren (if paren "\\)" "")))
-    (concat open-paren
-            (mapconcat 'regexp-quote strings "\\|")
-            close-paren)))
+(defun simplified-regexp-opt (strings &optional paren)
+ (let ((parens (cond ((stringp paren)       (cons paren "\\)"))
+                     ((eq paren 'words)    '("\\<\\(" . "\\)\\>"))
+                     ((eq paren 'symbols) '("\\_<\\(" . "\\)\\_>"))
+                     ((null paren)          '("\\(?:" . "\\)"))
+                     (t                       '("\\(" . "\\)")))))
+   (concat (car paren)
+           (mapconcat 'regexp-quote strings "\\|")
+           (cdr paren))))
 @end example
 @end defun
 
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 0b9529460f3..c5a6cb264d8 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -1060,8 +1060,9 @@ precision specifies how many decimal places to show; if zero, the
 decimal-point itself is also omitted.  For @samp{%s} and @samp{%S},
 the precision truncates the string to the given width, so @samp{%.3s}
 shows only the first three characters of the representation for
-@var{object}.  Precision has no effect for other specification
-characters.
+@var{object}.  For other specification characters, the effect of
+precision is what the local library functions of the @code{printf}
+family produce.
 
 @node Case Conversion
 @section Case Conversion in Lisp
diff --git a/etc/DEBUG b/etc/DEBUG
index 656e29a8b74..03efa3b10dd 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -190,24 +190,44 @@ kick in, provided that you run under GDB.
 
 ** Getting control to the debugger
 
+Setting a breakpoint in a strategic place, after loading Emacs into
+the debugger, but before running it, is the most efficient way of
+making sure control will be returned to the debugger when you need
+that.
+
 'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
 errors go through there.  If you are only interested in errors that
-would fire the debugger, breaking at 'maybe_call_debugger' is useful.
+would fire the Lisp debugger, breaking at 'maybe_call_debugger' is
+useful.
+
+Another technique for get control to the debugger is to put a
+breakpoint in some rarely used function.  One such convenient function
+is Fredraw_display, which you can invoke at will interactively with
+"M-x redraw-display RET".
 
-It is useful, when debugging, to have a guaranteed way to return to
-the debugger at any time.  When using X, this is easy: type C-z at the
-window where Emacs is running under GDB, and it will stop Emacs just
-as it would stop any ordinary program.  When Emacs is running in a
-terminal, things are not so easy.
+It is also useful to have a guaranteed way to return to the debugger
+at any arbitrary time.  When using X, this is easy: type C-z at the
+window where you are interacting with GDB, and it will stop Emacs just
+as it would stop any ordinary program.  (This doesn't work if GDB was
+attached to a running Emacs process; in that case, you will need to
+type C-z to the shell window from which Emacs was started, or use the
+"kill -TSTP" method described below.)
+
+When Emacs is displaying on a text terminal, things are not so easy,
+so we describe the various alternatives below (however, those of them
+that use signals only work on Posix systems).
 
 The src/.gdbinit file in the Emacs distribution arranges for SIGINT
-(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
-On modern POSIX systems, you can override that with this command:
+(C-g in Emacs on a text-mode frame) to be passed to Emacs and not give
+control back to GDB.  On modern systems, you can override that with
+this command:
 
    handle SIGINT stop nopass
 
 After this 'handle' command, SIGINT will return control to GDB.  If
 you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
+See the GDB manual for more details about signal handling and the
+'handle' command.
 
 A technique that can work when 'handle SIGINT' does not is to store
 the code for some character into the variable stop_character.  Thus,
@@ -216,26 +236,37 @@ the code for some character into the variable stop_character.  Thus,
 
 makes Control-] (decimal code 29) the stop character.
 Typing Control-] will cause immediate stop.  You cannot
-use the set command until the inferior process has been started.
-Put a breakpoint early in 'main', or suspend the Emacs,
-to get an opportunity to do the set command.
+use the set command until the inferior process has been started, so
+start Emacs with the 'start' command, to get an opportunity to do the
+above 'set' command.
 
-Another technique for get control to the debugger is to put a
-breakpoint in some rarely used function.  One such convenient function
-is Fredraw_display, which you can invoke at will interactively with
-"M-x redraw-display RET".
+On a Posix host, you can also send a signal using the 'kill' command
+from a shell prompt, like this:
 
-When Emacs is running in a terminal, it is sometimes useful to use a separate
-terminal for the debug session.  This can be done by starting Emacs as usual,
-then attaching to it from gdb with the 'attach' command which is explained in
-the node "Attach" of the GDB manual.
+   kill -TSTP Emacs-PID
 
-On MS-Windows, you can start Emacs in its own separate terminal by
-setting the new-console option before running Emacs under GDB:
+where Emacs-PID is the process ID of Emacs being debugged.  Other
+useful signals to send are SIGUSR1 and SIGUSR2; see "Error Debugging"
+in the ELisp manual for how to use those.
+
+When Emacs is displaying on a text terminal, it is useful to have a
+separate terminal for the debug session.  This can be done by starting
+Emacs as usual, then attaching to it from gdb with the 'attach'
+command which is explained in the node "Attach" of the GDB manual.
+
+On MS-Windows, you can alternatively start Emacs from its own separate
+console by setting the new-console option before running Emacs under
+GDB:
 
   (gdb) set new-console 1
   (gdb) run
 
+If you do this, then typing C-c or C-BREAK into the console window
+through which you interact with GDB will stop Emacs and return control
+to the debugger, no matter if Emacs displays GUI or text-mode frames.
+This is the only reliable alternative on MS-Windows to get control to
+the debugger, besides setting breakpoints in advance.
+
 ** Examining Lisp object values.
 
 When you have a live process to debug, and it has not encountered a
@@ -848,7 +879,7 @@ directed to the xterm window you opened above.
 Similar arrangement is possible on a character terminal by using the
 'screen' package.
 
-On MS-Windows, you can start Emacs in its own separate terminal by
+On MS-Windows, you can start Emacs in its own separate console by
 setting the new-console option before running Emacs under GDB:
 
   (gdb) set new-console 1
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 11532832c38..2e1044f16ea 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -578,6 +578,25 @@ you have a personal configuration file (normally ~/.aspell.conf), it
 can cause this error.  Remove that file, execute 'ispell-kill-ispell'
 in Emacs, and then try spell-checking again.
 
+*** Emacs eats all file descriptors when using kqueue file notifications.
+See <http://debbugs.gnu.org/22814>.
+
+When you have a large number of buffers running auto-revert-mode, and
+Emacs is configured to use the kqueue file notification library, it
+uses an own file descriptor for every watched file.  On systems with a
+small limit of file descriptors allowed per process, like OS X, you
+could run out of file descriptors.  You won't be able to open new files.
+
+auto-revert-use-notify is set to nil in global-auto-revert-mode, therefore.
+
+*** TLS problems, e.g., Gnus hangs when fetching via imaps
+http://debbugs.gnu.org/24247
+
+gnutls-cli 3.5.3 (2016-08-09) does not generate a "- Handshake was
+completed" message that tls.el relies upon, causing affected Emacs
+functions to hang.  To work around the problem, use older or newer
+versions of gnutls-cli, or use Emacs's built-in gnutls support.
+
 * Runtime problems related to font handling
 
 ** Characters are displayed as empty boxes or with wrong font under X.
diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el
index ccdae484fa6..7a2b3fe1563 100644
--- a/lisp/calendar/calendar.el
+++ b/lisp/calendar/calendar.el
@@ -905,7 +905,7 @@ styles."
   '(propertize (format "%s %d" (calendar-month-name month) year)
                'font-lock-face 'calendar-month-header)
   "Default format for calendar month headings with the American date style.
-Normally you should not customize this, but `calender-month-header'."
+Normally you should not customize this, but `calendar-month-header'."
   :group 'calendar
   :risky t
   :type 'sexp
@@ -915,7 +915,7 @@ Normally you should not customize this, but `calender-month-header'."
   '(propertize (format "%s %d" (calendar-month-name month) year)
                'font-lock-face 'calendar-month-header)
   "Default format for calendar month headings with the European date style.
-Normally you should not customize this, but `calender-month-header'."
+Normally you should not customize this, but `calendar-month-header'."
   :group 'calendar
   :risky t
   :type 'sexp
@@ -925,7 +925,7 @@ Normally you should not customize this, but `calender-month-header'."
   '(propertize (format "%d %s" year (calendar-month-name month))
                'font-lock-face 'calendar-month-header)
   "Default format for calendar month headings with the ISO date style.
-Normally you should not customize this, but `calender-month-header'."
+Normally you should not customize this, but `calendar-month-header'."
   :group 'calendar
   :risky t
   :type 'sexp
diff --git a/lisp/emacs-lisp/gv.el b/lisp/emacs-lisp/gv.el
index 93572e5e658..fa7ac64bf04 100644
--- a/lisp/emacs-lisp/gv.el
+++ b/lisp/emacs-lisp/gv.el
@@ -536,7 +536,7 @@ This macro only makes sense when used in a place."
   "Return a reference to PLACE.
 This is like the `&' operator of the C language.
 Note: this only works reliably with lexical binding mode, except for very
-simple PLACEs such as (function-symbol \\='foo) which will also work in dynamic
+simple PLACEs such as (symbol-function \\='foo) which will also work in dynamic
 binding mode."
   (let ((code
          (gv-letplace (getter setter) place
diff --git a/lisp/emacs-lisp/regexp-opt.el b/lisp/emacs-lisp/regexp-opt.el
index cf6653046b5..ef752858a4c 100644
--- a/lisp/emacs-lisp/regexp-opt.el
+++ b/lisp/emacs-lisp/regexp-opt.el
@@ -86,18 +86,44 @@
 ;;;###autoload
 (defun regexp-opt (strings &optional paren)
   "Return a regexp to match a string in the list STRINGS.
-Each string should be unique in STRINGS and should not contain any regexps,
-quoted or not.  If optional PAREN is non-nil, ensure that the returned regexp
-is enclosed by at least one regexp grouping construct.
-The returned regexp is typically more efficient than the equivalent regexp:
+Each string should be unique in STRINGS and should not contain
+any regexps, quoted or not.  Optional PAREN specifies how the
+returned regexp is surrounded by grouping constructs.
 
- (let ((open (if PAREN \"\\\\(\" \"\")) (close (if PAREN \"\\\\)\" \"\")))
-   (concat open (mapconcat \\='regexp-quote STRINGS \"\\\\|\") close))
+The optional argument PAREN can be any of the following:
 
-If PAREN is `words', then the resulting regexp is additionally surrounded
-by \\=\\< and \\>.
-If PAREN is `symbols', then the resulting regexp is additionally surrounded
-by \\=\\_< and \\_>."
+a string
+    the resulting regexp is preceded by PAREN and followed by
+    \\), e.g.  use \"\\\\(?1:\" to produce an explicitly numbered
+    group.
+
+`words'
+    the resulting regexp is surrounded by \\=\\<\\( and \\)\\>.
+
+`symbols'
+    the resulting regexp is surrounded by \\_<\\( and \\)\\_>.
+
+non-nil
+    the resulting regexp is surrounded by \\( and \\).
+
+nil
+    the resulting regexp is surrounded by \\(?: and \\), if it is
+    necessary to ensure that a postfix operator appended to it will
+    apply to the whole expression.
+
+The resulting regexp is equivalent to but usually more efficient
+than that of a simplified version:
+
+ (defun simplified-regexp-opt (strings &optional paren)
+   (let ((parens
+          (cond ((stringp paren)       (cons paren \"\\\\)\"))
+                ((eq paren 'words)    '(\"\\\\\\=<\\\\(\" . \"\\\\)\\\\>\"))
+                ((eq paren 'symbols) '(\"\\\\_<\\\\(\" . \"\\\\)\\\\_>\"))
+                ((null paren)          '(\"\\\\(?:\" . \"\\\\)\"))
+                (t                       '(\"\\\\(\" . \"\\\\)\")))))
+     (concat (car paren)
+             (mapconcat 'regexp-quote strings \"\\\\|\")
+             (cdr paren))))"
   (save-match-data
     ;; Recurse on the sorted list.
     (let* ((max-lisp-eval-depth 10000)
diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el
index e5004f8cdab..9859f28f8e8 100644
--- a/lisp/emacs-lisp/seq.el
+++ b/lisp/emacs-lisp/seq.el
@@ -137,7 +137,7 @@ the sequence, and its index within the sequence."
 
 (cl-defgeneric seq-subseq (sequence start &optional end)
   "Return the sequence of elements of SEQUENCE from START to END.
-END is inclusive.
+END is exclusive.
 
 If END is omitted, it defaults to the length of the sequence.  If
 START or END is negative, it counts from the end.  Signal an
diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index 890d55294cf..d37ab8a9817 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -1880,8 +1880,6 @@ Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
 If you exit (\\[keyboard-quit], RET or q), you can resume the query replace
 with the command \\[tags-loop-continue].
 Fourth arg FILE-LIST-FORM non-nil means initialize the replacement loop.
-Fifth and sixth arguments START and END are accepted, for compatibility
-with `query-replace-regexp', and ignored.
 
 If FILE-LIST-FORM is non-nil, it is a form to evaluate to
 produce the list of files to search.
diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
index 927d0bb8d57..81bb9b4721e 100644
--- a/lisp/url/url-http.el
+++ b/lisp/url/url-http.el
@@ -366,9 +366,10 @@ The string is based on `url-privacy-level' and `url-user-agent'."
              auth
              ;; Cookies
              (when (url-use-cookies url-http-target-url)
-               (url-cookie-generate-header-lines
-                host real-fname
-                (equal "https" (url-type url-http-target-url))))
+               (url-http--encode-string
+                (url-cookie-generate-header-lines
+                 host real-fname
+                 (equal "https" (url-type url-http-target-url)))))
              ;; If-modified-since
              (if (and (not no-cache)
                       (member url-http-method '("GET" nil)))
diff --git a/src/process.c b/src/process.c
index 29bf43e0f29..9a0ab00c505 100644
--- a/src/process.c
+++ b/src/process.c
@@ -980,7 +980,7 @@ If PROCESS has not yet exited or died, return 0.  */)
 DEFUN ("process-id", Fprocess_id, Sprocess_id, 1, 1, 0,
        doc: /* Return the process id of PROCESS.
 This is the pid of the external process which PROCESS uses or talks to.
-For a network connection, this value is nil.  */)
+For a network, serial, and pipe connections, this value is nil.  */)
   (register Lisp_Object process)
 {
   pid_t pid;
@@ -1004,8 +1004,8 @@ DEFUN ("process-command", Fprocess_command, Sprocess_command, 1, 1, 0,
        doc: /* Return the command that was executed to start PROCESS.
 This is a list of strings, the first string being the program executed
 and the rest of the strings being the arguments given to it.
-For a network or serial process, this is nil (process is running) or t
-\(process is stopped).  */)
+For a network or serial or pipe connection, this is nil (process is running)
+or t (process is stopped).  */)
   (register Lisp_Object process)
 {
   CHECK_PROCESS (process);
@@ -1237,13 +1237,13 @@ DEFUN ("process-query-on-exit-flag",
 DEFUN ("process-contact", Fprocess_contact, Sprocess_contact,
        1, 2, 0,
        doc: /* Return the contact info of PROCESS; t for a real child.
-For a network or serial connection, the value depends on the optional
-KEY arg.  If KEY is nil, value is a cons cell of the form (HOST
-SERVICE) for a network connection or (PORT SPEED) for a serial
-connection.  If KEY is t, the complete contact information for the
-connection is returned, else the specific value for the keyword KEY is
-returned.  See `make-network-process' or `make-serial-process' for a
-list of keywords.
+For a network or serial or pipe connection, the value depends on the
+optional KEY arg.  If KEY is nil, value is a cons cell of the form
+\(HOST SERVICE) for a network connection or (PORT SPEED) for a serial
+connection; it is t for a pipe connection.  If KEY is t, the complete
+contact information for the connection is returned, else the specific
+value for the keyword KEY is returned.  See `make-network-process',
+`make-serial-process', or `make pipe-process' for the list of keywords.
 If PROCESS is a non-blocking network process that hasn't been fully
 set up yet, this function will block until socket setup has completed.  */)
   (Lisp_Object process, Lisp_Object key)
@@ -1316,7 +1316,7 @@ a socket connection.  */)
 
 DEFUN ("process-type", Fprocess_type, Sprocess_type, 1, 1, 0,
        doc: /* Return the connection type of PROCESS.
-The value is either the symbol `real', `network', or `serial'.
+The value is either the symbol `real', `network', `serial', or `pipe'.
 PROCESS may be a process, a buffer, the name of a process or buffer, or
 nil, indicating the current buffer's process.  */)
   (Lisp_Object process)
@@ -6532,8 +6532,8 @@ See function `interrupt-process' for more details on usage.  */)
 DEFUN ("stop-process", Fstop_process, Sstop_process, 0, 2, 0,
        doc: /* Stop process PROCESS.  May be process or name of one.
 See function `interrupt-process' for more details on usage.
-If PROCESS is a network or serial process, inhibit handling of incoming
-traffic.  */)
+If PROCESS is a network or serial or pipe connection, inhibit handling
+of incoming traffic.  */)
   (Lisp_Object process, Lisp_Object current_group)
 {
   if (PROCESSP (process) && (NETCONN_P (process) || SERIALCONN_P (process)
diff --git a/src/window.h b/src/window.h
index c2898194854..a124b3311d0 100644
--- a/src/window.h
+++ b/src/window.h
@@ -920,7 +920,7 @@ wset_next_buffers (struct window *w, Lisp_Object val)
    ? WINDOW_CONFIG_SCROLL_BAR_HEIGHT (W)        \
    : 0)
 
-/* Height in pixels, and in lines, of the mode line.
+/* Height in pixels of the mode line.
    May be zero if W doesn't have a mode line.  */
 #define WINDOW_MODE_LINE_HEIGHT(W)      \
   (WINDOW_WANTS_MODELINE_P ((W))        \
@@ -930,7 +930,7 @@ wset_next_buffers (struct window *w, Lisp_Object val)
 #define WINDOW_MODE_LINE_LINES(W)       \
   WINDOW_WANTS_MODELINE_P (W)
 
-/* Height in pixels, and in lines, of the header line.
+/* Height in pixels of the header line.
    Zero if W doesn't have a header line.  */
 #define WINDOW_HEADER_LINE_HEIGHT(W)    \
   (WINDOW_WANTS_HEADER_LINE_P (W)       \