doc/emacs/misc.texi (Network Security): Improve wording and indexing.

2 files changed, 41 insertions, 34 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 198de4f2636..3db0e851603 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2014-11-24  Eli Zaretskii  <eliz@gnu.org>
+
+        * misc.texi (Network Security): Improve wording and indexing of
+        last change.
+
 2014-11-24  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * misc.texi (Gnus Summary Buffer): Move the Network Security
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 2295414aa55..f2828c5426b 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -252,27 +252,30 @@ Exit the summary buffer and return to the group buffer.
 
 @node Network Security
 @section Network Security
-@cindex Network Security Manager
+@cindex network security manager
+@cindex NSM
 @cindex encryption
 @cindex SSL
 @cindex TLS
 @cindex STARTTLS
 
-After establishing a network connection, the connection is then passed
-on to the Network Security Manager (@acronym{NSM}).
+Whenever Emacs establishes any network connection, it passes the
+established connection to the @dfn{Network Security Manager}
+(@acronym{NSM}).  @acronym{NSM} is responsible for enforcing the
+network security under your control.
 
 @vindex network-security-level
 The @code{network-security-level} variable determines the security
-level.  If this is @code{low}, no security checks are performed.
+level that @acronym{NSM} enforces.  If its value is @code{low}, no
+security checks are performed.
 
 If this variable is @code{medium} (which is the default), a number of
-checks will be performed.  If the @acronym{NSM} determines that the
-network connection might be unsafe, the user is made aware of this,
-and the @acronym{NSM} will ask the user what to do about the network
-connection.
+checks will be performed.  If as result @acronym{NSM} determines that
+the network connection might be unsafe, it will make you aware of
+that, and will ask you what to do about the network connection.
 
-The user is given the choice of registering a permanent security
-exception, a temporary one, or whether to refuse the connection
+You can decide to register a permanent security exception for an
+unsafe connection, a temporary exception, or refuse the connection
 entirely.
 
 Below is a list of the checks done on the @code{medium} level.
@@ -281,24 +284,23 @@ Below is a list of the checks done on the @code{medium} level.
 
 @item unable to verify a @acronym{TLS} certificate
 If the connection is a @acronym{TLS}, @acronym{SSL} or
-@acronym{STARTTLS} connection, the @acronym{NSM} will check whether
+@acronym{STARTTLS} connection, @acronym{NSM} will check whether
 the certificate used to establish the identity of the server we're
 connecting to can be verified.
 
-While an invalid certificate is often the cause for concern (there may
-be a Man-in-the-Middle hijacking your network connection and stealing
-your password), there may be valid reasons for going ahead with the
-connection anyway.
-
-For instance, the server may be using a self-signed certificate, or
-the certificate may have expired.  It's up to the user to determine
-whether it's acceptable to continue the connection.
+While an invalid certificate is often the cause for concern (there
+could be a Man-in-the-Middle hijacking your network connection and
+stealing your password), there may be valid reasons for going ahead
+with the connection anyway.  For instance, the server may be using a
+self-signed certificate, or the certificate may have expired.  It's up
+to you to determine whether it's acceptable to continue with the
+connection.
 
 @item a self-signed certificate has changed
 If you've previously accepted a self-signed certificate, but it has
-now changed, that either means that the server has just changed the
-certificate, or this might mean that the network connection has been
-hijacked.
+now changed, that could mean that the server has just changed the
+certificate, but it might also mean that the network connection has
+been hijacked.
 
 @item previously encrypted connection now unencrypted
 If the connection is unencrypted, but it was encrypted in previous
@@ -311,44 +313,44 @@ When connecting to an @acronym{IMAP} or @acronym{POP3} server, these
 should usually be encrypted, because it's common to send passwords
 over these connections.  Similarly, if you're sending email via
 @acronym{SMTP} that requires a password, you usually want that
-connection to be encrypted.  If the connection isn't encrypted, the
+connection to be encrypted.  If the connection isn't encrypted,
 @acronym{NSM} will warn you.
 
 @end table
 
 If @code{network-security-level} is @code{high}, the following checks
-will be made:
+will be made, in addition to the above:
 
 @table @asis
 @item a validated certificate changes the public key
 Servers change their keys occasionally, and that is normally nothing
 to be concerned about.  However, if you are worried that your network
 connections are being hijacked by agencies who have access to pliable
-Certificate Authorities that issue new certificates for third-party
+Certificate Authorities which issue new certificates for third-party
 services, you may want to keep track of these changes.
 @end table
 
 Finally, if @code{network-security-level} is @code{paranoid}, you will
-also be notified the first time the @acronym{NSM} sees any new
+also be notified the first time @acronym{NSM} sees any new
 certificate.  This will allow you to inspect all the certificates from
 all the connections that Emacs makes.
 
-The following additional variables can be used to control
-@acronym{NSM} details.
+The following additional variables can be used to control details of
+@acronym{NSM} operation:
 
 @table @code
 @item nsm-settings-file
 @vindex nsm-settings-file
-The @acronym{NSM} stores details on the connections in this file.  It
-defaults to @file{~/.emacs.d/network-security.data}.
+This is the file where @acronym{NSM} stores details about connections.
+It defaults to @file{~/.emacs.d/network-security.data}.
 
 @item nsm-save-host-names
 @vindex nsm-save-host-names
-By default, host names will not be saved per non-@code{STARTTLS}
-connection.  Instead a host/port hash is used to identify connections.
+By default, host names will not be saved for non-@code{STARTTLS}
+connections.  Instead a host/port hash is used to identify connections.
 This means that one can't casually read the settings file to see what
-servers the user has connected to.  If this variable is @code{t}, host
-names will be saved in the file, too.
+servers the user has connected to.  If this variable is @code{t},
+@acronym{NSM} will also save host names in the nsm-settings-file.
 @end table