DOCSP-26944 BACKPORT (#2246)

Author: Dave Cuthbert

source/tutorial/configure-ssl-clients.txt

@@ -184,26 +184,35 @@ following options:
 
    mongosh --tls --host hostname.example.com --tlsCertificateKeyFile /etc/ssl/client.pem --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem
 
-On Windows and macOS,
-   You can also use the :option:`--tlsCertificateSelector <mongosh
-   --tlsCertificateSelector>` option to specify the client certificate
-   from the system certificate store instead of using
-   :option:`--tlsCertificateKeyFile <mongosh
-   --tlsCertificateKeyFile>`. If the CA file is also in the system
-   certificate store, you can omit the :option:`--tlsCAFile <mongosh
-   --tlsCAFile>` option as well. For example, to use a certificate
-   with the ``CN`` (Common Name) of ``myclient.example.net`` and the CA
-   file from the system certificate store on macOS, start
-   :binary:`~bin.mongosh` with the following options:
-
-   .. code-block:: bash
-
-      mongosh --tls  --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"
-
-   Although still available, :binary:`~bin.mongosh`
-   ``--ssl``, ``--sslCAFile``, ``--sslPEMKeyFile``, and
-   ``--sslCertificateSelector`` options
-   are :ref:`deprecated as of MongoDB 4.2 <4.2-tls>`.
+Windows and macOS
+`````````````````
+
+To specify a client certificate from the system certificate store, use 
+the :option:`--tlsCertificateSelector <mongosh
+--tlsCertificateSelector>` option instead of
+:option:`--tlsCertificateKeyFile <mongosh
+--tlsCertificateKeyFile>`.
+
+If the CA file is also in the system certificate store, you can omit the
+:option:`--tlsCAFile <mongosh --tlsCAFile>` option.
+
+For example, if a certificate with the ``CN`` (Common Name) of
+``myclient.example.net`` and the accompanying CA file are both in the
+macOS system certificate store, you can connect like this:
+
+.. code-block:: bash
+
+   mongosh --tls  --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"
+
+These options are :ref:`deprecated starting in MongoDB 4.2 <4.2-tls>`:
+
+- ``--ssl``
+- ``--sslCAFile``
+- ``--sslPEMKeyFile``
+- ``--sslCertificateSelector``
+
+There are available in ``mongosh``, but you should use the ``tls``
+alternatives instead.
 
 Avoid Use of ``--tlsAllowInvalidCertificates`` Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -362,19 +371,22 @@ following options:
 
    mongosh --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
 
-On Windows and macOS,
-   You can also use the ``--sslCertificateSelector`` option to specify 
-   the client certificate from the system certificate store instead of 
-   using ``--sslPEMKeyFile``. If the CA file is also in the system 
-   certificate store, you can omit the ``--sslCAFile`` option as well. 
-   For example, to use a certificate with the ``CN`` (Common Name) of
-   ``myclient.example.net`` and the CA file from the system certificate
-   store on macOS, start :binary:`~bin.mongosh` with the following
-   options:
+On Windows and macOS
+````````````````````
 
-   .. code-block:: bash
+You can also use the ``--sslCertificateSelector`` option to specify the
+client certificate from the system certificate store instead of using
+``--sslPEMKeyFile``. If the CA file is also in the system certificate
+store, you can omit the ``--sslCAFile`` option.
+
+For example, to use a certificate with the ``CN`` (Common Name) of
+``myclient.example.net`` and the CA file from the system certificate
+store on macOS, start :binary:`~bin.mongosh` with the following
+options:
+
+.. code-block:: bash
 
-      mongosh --ssl  --host hostname.example.com --sslCertificateSelector subject=myclient.example.net 
+   mongosh --ssl  --host hostname.example.com --sslCertificateSelector subject=myclient.example.net 
 
 Avoid Use of ``--sslAllowInvalidCertificates`` Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~