More process-related doc and manual small edits

* doc/lispref/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.

* lisp/net/network-stream.el (open-network-stream): Doc fix.

* src/process.c (Fset_process_inherit_coding_system_flag)
(Fset_process_query_on_exit_flag): Doc fix (mention return value).
(Fmake_network_process): Doc fix.

6 files changed, 146 insertions, 98 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 16a0696b9f9..e56317ad70a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+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.
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index fd8bc717d09..0a763b4e146 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1133,13 +1133,14 @@ 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
@@ -1264,14 +1265,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
@@ -1506,6 +1509,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"}.
@@ -1522,7 +1526,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
@@ -1546,6 +1550,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
@@ -1556,8 +1561,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
@@ -1565,10 +1570,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
@@ -1576,7 +1585,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.
 
@@ -1604,7 +1613,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
 
@@ -1614,7 +1623,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.
@@ -1633,7 +1642,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
@@ -1645,7 +1654,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.
@@ -1665,7 +1674,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,
@@ -1826,6 +1835,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
@@ -1855,8 +1866,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
@@ -1874,10 +1888,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
@@ -1905,7 +1920,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}.
@@ -1915,35 +1930,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:
 
@@ -1960,14 +1988,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
@@ -1986,22 +2015,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
@@ -2025,18 +2054,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.
 
@@ -2057,7 +2088,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}.
@@ -2074,7 +2105,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.
@@ -2127,7 +2158,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}
@@ -2143,7 +2175,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}
@@ -2154,7 +2186,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
@@ -2165,18 +2197,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.
@@ -2200,7 +2232,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
@@ -2222,8 +2254,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.
@@ -2244,6 +2276,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}.
 
@@ -2251,7 +2288,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.
@@ -2288,7 +2325,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}
@@ -2304,10 +2341,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
@@ -2316,7 +2354,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.
@@ -2324,20 +2362,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.
@@ -2354,11 +2392,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
@@ -2382,20 +2418,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
@@ -2533,7 +2559,7 @@ 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
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 026b99872f0..16cf1e347a1 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-04-18  Glenn Morris  <rgm@gnu.org>
+
+        * net/network-stream.el (open-network-stream): Doc fix.
+
 2012-04-17  Chong Yidong  <cyd@gnu.org>
 
         * emacs-lisp/tabulated-list.el (tabulated-list-print): Fix typos.
diff --git a/lisp/net/network-stream.el b/lisp/net/network-stream.el
index 7a3d47ef1d1..81d05eabc5a 100644
--- a/lisp/net/network-stream.el
+++ b/lisp/net/network-stream.el
@@ -125,9 +125,8 @@ values:
   certificate.  This parameter will only be used when doing TLS
   or STARTTLS connections.
 
-If :use-starttls-if-possible is non-nil, do opportunistic
-STARTTLS upgrades even if Emacs doesn't have built-in TLS
-functionality.
+:use-starttls-if-possible is a boolean that says to do opportunistic
+STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
 
 :nowait is a boolean that says the connection should be made
   asynchronously, if possible."
diff --git a/src/ChangeLog b/src/ChangeLog
index 42c582994cf..fb4da407b70 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,9 @@
+2012-04-18  Glenn Morris  <rgm@gnu.org>
+
+        * process.c (Fset_process_inherit_coding_system_flag)
+        (Fset_process_query_on_exit_flag): Doc fix (mention return value).
+        (Fmake_network_process): Doc fix.
+
 2012-04-17  Eli Zaretskii  <eliz@gnu.org>
 
         * xdisp.c (string_buffer_position_lim): Limit starting position to
diff --git a/src/process.c b/src/process.c
index dc43191ebef..f6ea5d75e1a 100644
--- a/src/process.c
+++ b/src/process.c
@@ -1070,7 +1070,9 @@ is more appropriate for saving the process buffer.
 
 Binding the variable `inherit-process-coding-system' to non-nil before
 starting the process is an alternative way of setting the inherit flag
-for the process which will run.  */)
+for the process which will run.
+
+This function returns FLAG.  */)
   (register Lisp_Object process, Lisp_Object flag)
 {
   CHECK_PROCESS (process);
@@ -1083,7 +1085,8 @@ DEFUN ("set-process-query-on-exit-flag",
        2, 2, 0,
        doc: /* Specify if query is needed for PROCESS when Emacs is exited.
 If the second argument FLAG is non-nil, Emacs will query the user before
-exiting or killing a buffer if PROCESS is running.  */)
+exiting or killing a buffer if PROCESS is running.  This function
+returns FLAG.  */)
   (register Lisp_Object process, Lisp_Object flag)
 {
   CHECK_PROCESS (process);
@@ -2794,7 +2797,7 @@ The stopped state is cleared by `continue-process' and set by
 :filter-multibyte BOOL -- If BOOL is non-nil, strings given to the
 process filter are multibyte, otherwise they are unibyte.
 If this keyword is not specified, the strings are multibyte if
-`default-enable-multibyte-characters' is non-nil.
+the default value of `enable-multibyte-characters' is non-nil.
 
 :sentinel SENTINEL -- Install SENTINEL as the process sentinel.