DOCSP-26944 BACKPORT (#2250)

* DOCSP-26944 BACKPORT

* Build errors

* Build errors

* Build errors

Author: Dave Cuthbert

source/tutorial/configure-ssl-clients.txt

@@ -185,27 +185,34 @@ following options:
 
    mongo --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 <mongo
-   --tlsCertificateSelector>` option to specify the client certificate
-   from the system certificate store instead of using
-   :option:`--tlsCertificateKeyFile <mongo
-   --tlsCertificateKeyFile>`. If the CA file is also in the system
-   certificate store, you can omit the :option:`--tlsCAFile <mongo
-   --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 a
-   :binary:`~bin.mongo` shell with the following options:
-
-   .. code-block:: bash
-
-      mongo --tls  --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"
-
-   Although still available, the :binary:`~bin.mongo` shell
-   :option:`--ssl <mongo --ssl>`, :option:`--sslCAFile <mongo
-   --sslCAFile>`, :option:`--sslPEMKeyFile <mongo --sslPEMKeyFile>`,
-   :option:`--sslCertificateSelector <mongo --sslCertificateSelector>`
-   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 <mongo
+--tlsCertificateSelector>` option instead of
+:option:`--tlsCertificateKeyFile <mongo
+--tlsCertificateKeyFile>`.
+
+If the CA file is also in the system certificate store, you can omit the
+:option:`--tlsCAFile <mongo --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
+
+   mongo --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``
+
+If possible, you should use the ``tls`` alternatives instead.
 
 Avoid Use of ``--tlsAllowInvalidCertificates`` Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -366,21 +373,22 @@ following options:
 
    mongo --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
 
-On Windows and macOS,
-   You can also use the :option:`--sslCertificateSelector <mongo
-   --sslCertificateSelector>` option to specify the client certificate
-   from the system certificate store instead of using
-   :option:`--sslPEMKeyFile <mongo --sslPEMKeyFile>`. If the CA file
-   is also in the system certificate store, you can omit the
-   :option:`--sslCAFile <mongo --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 a :binary:`~bin.mongo` shell with the
-   following options:
-
-   .. code-block:: bash
-
-      mongo --ssl  --host hostname.example.com --sslCertificateSelector subject=myclient.example.net 
+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.
+
+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.mongo` with the following
+options:
+
+.. code-block:: bash
+
+   mongo --ssl  --host hostname.example.com --sslCertificateSelector subject=myclient.example.net 
 
 Avoid Use of ``--sslAllowInvalidCertificates`` Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~