review and fix the three new apt-transport- manpages

References: https://lists.debian.org/debian-l10n-english/2018/01/msg00002.html

1 files changed, 20 insertions, 20 deletions

diff --git a/doc/apt-transport-https.1.xml b/doc/apt-transport-https.1.xml
index 97137fc2c..9d2f05dd0 100644
--- a/doc/apt-transport-https.1.xml
+++ b/doc/apt-transport-https.1.xml
@@ -30,21 +30,21 @@
 
 <refsect1><title>Description</title>
 <para>This APT transport allows the use of repositories accessed via the
-HTTP Secure protocol (HTTPS) also referred to as HTTP over TLS. It is available
-by default since apt 1.5 and was before that available in a <package>apt-transport-https</package>
-package. Note that a transport is never called directly by
+HTTP Secure protocol (HTTPS), also referred to as HTTP over TLS. It is available
+by default since apt 1.5 and was available before that in the package
+<package>apt-transport-https</package>. Note that a transport is never called directly by
 a user but used by APT tools based on user configuration.</para>
 <para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
-which, as indicated by the appended S is wrapped in an encrypted layer known as
-Transport Layer Security (TLS) which provides end-to-end encryption.
+which, as indicated by the appended S, is wrapped in an encrypted layer known as
+Transport Layer Security (TLS) to provide end-to-end encryption.
 A sufficiently capable attacker can still observe the communication partners
 and deeper analyse of the encrypted communcation might still reveal important details.
 An overview over available alternative transport methods is given in &sources-list;.</para>
 </refsect1>
 
 <refsect1><title>Options</title>
-<para>The HTTPS protocol is based on the HTTP protocol and as such this implementation
-has the same relation meaning that all options supported by &apt-transport-http; are also
+<para>The HTTPS protocol is based on the HTTP protocol, so
+all options supported by &apt-transport-http; are also
 available via <literal>Acquire::https</literal> and will default to the same values specified
 for <literal>Acquire::http</literal>. This manpage will only document the options
 <emphasis>unique to https</emphasis>.</para>
@@ -55,26 +55,26 @@ for <literal>Acquire::http</literal>. This manpage will only document the option
 the server certificate. An alternative certificate authority (CA) can be
 configured with the <literal>Acquire::https::CAInfo</literal> option and its
 host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
-The option specifies a file is made of the concatenation of the CA certificates
-(in PEM format) creating the chain used for the verification of the path
-from the root (self signed one). If the remote server provides the
+The CAInfo option specifies a file made up of CA certificates (in PEM format)
+concatenated together to create the chain which APT should use to verify the
+path from your self-signed root certificate. If the remote server provides the
 whole chain during the exchange, the file need only contain the root
 certificate. Otherwise, the whole chain is required. If you need to support
 multiple authorities, the only way is to concatenate everything.</para>
 <para>A custom certificate revocation list (CRL) can be configured with the options
 <literal>Acquire::https::CRLFile</literal> and
-<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal> respectively.
-Like the previous option a file in PEM format needs to be specified.</para>
+<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal>.
+As with the previous option, a file in PEM format needs to be specified.</para>
 </refsect2>
 
 <refsect2><title>Disabling security</title>
-<para>When authenticating the server, if the certificate verification fails
-for some reason (expired, revoked, man in the middle, …), the connection fails.
+<para>During server authentication, if certificate verification fails
+for some reason (expired, revoked, man in the middle, etc.), the connection fails.
 This is obviously what you want in all cases and what the default value (true)
 of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
 variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
-setting this option to "false" allows you to skip peer certificate verification and
-make the exchange succeed. Again, this option is for debugging or testing purpose
+setting this option to "<literal>false</literal>" allows you to skip peer certificate verification and
+make the exchange succeed. Again, this option is for debugging or testing purposes
 only as it removes all security provided by the use of HTTPS.</para>
 <para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
 host-specific variant can be used to deactivate a security feature: The certificate
@@ -83,13 +83,13 @@ DNS name used to access it. By default, as requested by RFC 2818, the name of th
 mirror is checked against the identity found in the certificate. This default behavior
 is safe and should not be changed, but if you know that the server you are using has a
 DNS name which does not match the identity in its certificate, you can set the option to
-"false", which will prevent the comparison to be done.</para>
+"<literal>false</literal>", which will prevent the comparison from being performed.</para>
 </refsect2>
 
 <refsect2><title>Client authentication</title>
-<para>Beside the password based authentication available (see &apt-authconf;) HTTPS supports
-authentication based on client certificates as well via <literal>Acquire::https::SSLCert</literal>
-and <literal>Acquire::https::SSLKey</literal>. They respectively should be set to the filename of
+<para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
+authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
+and <literal>Acquire::https::SSLKey</literal>. These should be set respectively to the filename of
 the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
 In practice the use of the host-specific variants of both options is highly recommended.</para>
 </refsect2>