[Emacs-diffs] /srv/bzr/emacs/trunk r107293: * lispref/processes.texi (Network): Document open-network-stream :parameters.

[Glenn Morris]

------------------------------------------------------------
revno: 107293
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-15 00:48:45 -0800
message:
  * lispref/processes.texi (Network): Document open-network-stream :parameters.
  * etc/NEWS: Related markup.
modified:
  doc/lispref/ChangeLog
  doc/lispref/processes.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-14 16:41:16 +0000
+++ b/doc/lispref/ChangeLog     2012-02-15 08:48:45 +0000
@@ -1,3 +1,7 @@
+2012-02-15  Glenn Morris  <address@hidden>
+
+       * processes.texi (Network): Document open-network-stream :parameters.
+
 2012-02-14  Chong Yidong  <address@hidden>
 
        * keymaps.texi (Format of Keymaps): The CACHE component of keymaps

=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi        2012-02-02 07:21:20 +0000
+++ b/doc/lispref/processes.texi        2012-02-15 08:48:45 +0000
@@ -1939,9 +1939,10 @@
 @code{process-command} to determine whether a network connection or
 server is stopped; a address@hidden value means yes.
 
address@hidden open-network-stream name buffer-or-name host service
-This function opens a TCP connection, and returns a process object
-that represents the connection.
address@hidden encrypted network connections
address@hidden open-network-stream name buffer-or-name 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.
@@ -1955,6 +1956,83 @@
 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).
+
address@hidden 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:
+
address@hidden @code
+
address@hidden :nowait @var{boolean}
+If address@hidden, try to make an asynchronous connection.
+
address@hidden :type @var{type}
+The type of connection.  Options are:
+
address@hidden @code
address@hidden plain
+An ordinary, unencrypted connection.
address@hidden tls
address@hidden ssl
+A TLS (``Transport Layer Security'') connection.
address@hidden nil
address@hidden 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.
address@hidden starttls
+As for @code{nil}, but if STARTTLS fails drop the connection.
address@hidden shell
+A shell connection.
address@hidden table
+
address@hidden :always-query-capabilities @var{boolean}
+If address@hidden, always ask for the server's capabilities, even when
+doing a @samp{plain} connection.
+
address@hidden :capability-command @var{capability-command}
+Command string to query the host capabilities.
+
address@hidden :end-of-command @var{regexp}
address@hidden :end-of-capability @var{regexp}
+Regular expression matching the end of a command, or the end of the
+command @var{capability-command}.  The latter defaults to the former.
+
address@hidden :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
+if supported.
+
address@hidden :success @var{regexp}
+Regular expression matching a successful STARTTLS negotiation.
+
address@hidden :use-starttls-if-possible @var{boolean}
+If address@hidden, do opportunistic STARTTLS upgrades even if Emacs
+doesn't have built-in TLS support.
+
address@hidden :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
address@hidden, meaning to query @code{auth-source} for this information
+(@pxref{Top,,auth-source, auth, Emacs auth-source Library}).
+Only used for TLS or STARTTLS.
+
address@hidden :return-list @var{cons-or-nil}
+The return value of this function.  If omitted or @code{nil}, return a
+process object.  Otherwise, a cons of the form @code{(@var{process-object}
+. @var{plist})}, where @var{plist} has keywords:
+
address@hidden @code
address@hidden :greeting @var{string-or-nil}
+If address@hidden, the greeting string returned by the host.
address@hidden :capabilities @var{string-or-nil}
+If address@hidden, the host's capability string.
address@hidden :type @var{symbol}
+The connection type: @samp{plain} or @samp{tls}.
address@hidden table
+
address@hidden table
+
 @end defun
 
 @node Network Servers

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-15 07:55:18 +0000
+++ b/etc/NEWS  2012-02-15 08:48:45 +0000
@@ -1289,6 +1289,7 @@
 ** `glyphless-char-display' can now distinguish between graphical and
 text terminal display, via a char-table entry that is a cons cell.
 
++++
 ** `open-network-stream' can now be used to open an encrypted stream.
 It now accepts an optional `:type' parameter for initiating a TLS
 connection, directly or via STARTTLS.  To do STARTTLS, additional