Prefer "tls" to "ssl" in documentation

* doc/misc/gnus.texi (NNTP): Refer to 'nntp-open-tls-stream'.
(Direct Functions, Customizing the IMAP Connection): Add
commentary about desirability of STARTTLS.  Correct
documentation about use of GnuTLS.  Use 'tls in example.
* lisp/gnus/nnimap.el (nnimap-server-port): Mention 'tls in
preference to 'ssl.
* lisp/gnus/nntp.el (nntp-open-connection-function)
(nntp-never-echoes-commands): Document 'nntp-open-tls-stream' as
preferred to 'nntp-open-ssl-stream'.

doc/misc/gnus.texi

@@ -14089,7 +14089,7 @@ indirect ones (three pre-made).
 Non-@code{nil} means the nntp server never echoes commands.  It is
 reported that some nntps server doesn't echo commands.  So, you may want
 to set this to non-@code{nil} in the method for such a server setting
-@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for
+@code{nntp-open-connection-function} to @code{nntp-open-tls-stream} for
 example.  The default value is @code{nil}.  Note that the
 @code{nntp-open-connection-functions-never-echo-commands} variable
 overrides the @code{nil} value of this variable.
@@ -14145,18 +14145,26 @@ functions is also affected by commonly understood variables
 @findex nntp-open-network-stream
 @item nntp-open-network-stream
 This is the default, and simply connects to some port or other on the
-remote system.  If both Emacs and the server supports it, the
+remote system.  If both Emacs and the server supports it, the connection
-connection will be upgraded to an encrypted @acronym{STARTTLS}
+will be upgraded to an encrypted @acronym{STARTTLS} connection
-connection automatically.
+automatically.  If you want to avoid the possibility of a malicious
+intermediary blocking the use of @acronym{STARTTLS}, use
+@code{nntp-open-tls-stream} instead.
 
-@item network-only
+@item nntp-open-plain-stream
-The same as the above, but don't do automatic @acronym{STARTTLS} upgrades.
+@itemx network-only
+The same as the above, but don't do automatic @acronym{STARTTLS}
+upgrades.  Only use this if you want anyone to be able to read your
+traffic.
 
 @findex nntp-open-tls-stream
 @item nntp-open-tls-stream
 Opens a connection to a server over a @dfn{secure} channel.  To use
-this you must have @uref{https://www.gnu.org/software/gnutls/, GnuTLS}
+this, your Emacs must have been compiled with GnuTLS support
-installed.  You then define a server as follows:
+@uref{https://www.gnu.org/software/gnutls/, GnuTLS}.  You can check this
+using the @code{gnutls-available-p} command.
+
+You then define a server as follows:
 
 @lisp
 ;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}}
@@ -14168,26 +14176,10 @@ installed.  You then define a server as follows:
       (nntp-address "snews.bar.com"))
 @end lisp
 
-@c FIXME openssl s_client should be deprecated in favor of gnutls.
 @findex nntp-open-ssl-stream
 @item nntp-open-ssl-stream
-Opens a connection to a server over a @dfn{secure} channel.  To use
+This is the old name for @code{nntp-open-tls-stream}, and is
-this you must have @uref{https://www.openssl.org/, OpenSSL}
+completely equivalent.
-@ignore
-@c Defunct URL, ancient package, so don't mention it.
-or @uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay}
-@end ignore
-installed.  You then define a server as follows:
-
-@lisp
-;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}}
-;; @r{however, @samp{openssl s_client -port} doesn't like named ports.}
-;;
-(nntp "snews.bar.com"
-      (nntp-open-connection-function nntp-open-ssl-stream)
-      (nntp-port-number 563)
-      (nntp-address "snews.bar.com"))
-@end lisp
 
 @findex nntp-open-netcat-stream
 @item nntp-open-netcat-stream
@@ -14529,7 +14521,7 @@ Here's an example method that's more complex:
         (nnimap-inbox "INBOX")
         (nnimap-split-methods default)
         (nnimap-expunge t)
-        (nnimap-stream ssl))
+        (nnimap-stream tls))
 @end example
 
 @table @code
@@ -14555,11 +14547,12 @@ How @code{nnimap} should connect to the server.  Possible values are:
 
 @table @code
 @item undecided
-This is the default, and this first tries the @code{ssl} setting, and
+This is the default, and this first tries the @code{tls} setting, and
 then tries the @code{network} setting.
 
-@item ssl
+@item tls
-This uses standard @acronym{TLS}/@acronym{SSL} connections.
+This uses standard @acronym{TLS}/@acronym{SSL} connections.  @code{ssl}
+is an equivalent but deprecated way to specify this.
 
 @item network
 Non-encrypted and unsafe straight socket connection, but will upgrade

lisp/gnus/nnimap.el

@@ -51,7 +51,7 @@
 
 (defvoo nnimap-server-port nil
   "The IMAP port used.
-If `nnimap-stream' is `ssl', this will default to `imaps'.  If not,
+If `nnimap-stream' is `tls', this will default to `imaps'.  If not,
 it will default to `imap'.")
 
 (defvoo nnimap-use-namespaces nil
@@ -63,10 +63,10 @@ names of your nnimap groups.")
 
 (defvoo nnimap-stream 'undecided
   "How nnimap talks to the IMAP server.
-The value should be either `undecided', `ssl' or `tls',
+The value should be either `undecided', `tls' or `ssl' (deprecated),
 `network', `starttls', `plain', or `shell'.
 
-If the value is `undecided', nnimap tries `ssl' first, then falls
+If the value is `undecided', nnimap tries `tls' first, then falls
 back on `network'.")
 
 (defvoo nnimap-shell-program (if (boundp 'imap-shell-program)

lisp/gnus/nntp.el

@@ -82,8 +82,9 @@ as its single argument, or one of the following special values:
   upgrading to a TLS connection via STARTTLS if possible.
 - `nntp-open-plain-stream' specifies an unencrypted network
   connection (no STARTTLS upgrade is attempted).
-- `nntp-open-ssl-stream' or `nntp-open-tls-stream' specify a TLS
+- `nntp-open-tls-stream' specifies a TLS network connection (the
-  network connection.
+  equivalent value `nntp-open-ssl-stream' is accepted for backwards
+  compatibility).
 
 Apart from the above special values, valid functions are as
 follows; please refer to their respective doc string for more
@@ -100,7 +101,7 @@ For indirect connections:
   "Non-nil means the nntp server never echoes commands.
 It is reported that some nntps server doesn't echo commands.  So, you
 may want to set this to non-nil in the method for such a server setting
-`nntp-open-connection-function' to `nntp-open-ssl-stream' for example.
+`nntp-open-connection-function' to `nntp-open-tls-stream' for example.
 Note that the `nntp-open-connection-functions-never-echo-commands'
 variable overrides the nil value of this variable.")