(DOCSP-12202): Add option directives to mongosh options page

Author: jeff-allen-mongo

source/reference/options.txt

@@ -18,38 +18,40 @@ Use the following options to control various aspects of your
 General Options
 ---------------
 
-.. setting:: --eval <javascript>
+.. program:: mongosh
+
+.. option:: --eval <javascript>
 
    Evaluates a JavaScript expression that is specified as an argument.
    The |mdb-shell| does not load its own environment when evaluating
    code. As a result, many options of the shell environment are not
    available when using this option.
 
-.. setting:: --help, -h
+.. option:: --help, -h
 
    Returns information on the options and use of the |mdb-shell|.
 
-.. setting:: --norc
+.. option:: --norc
 
    Prevents the shell from sourcing and evaluating
    :file:`~/.mongorc.js` on start up.
 
-.. setting:: --shell
+.. option:: --shell
 
    Enables the shell interface. If you invoke the ``mongosh``
    command and specify a JavaScript file as an argument, or use
-   ``--eval`` to specify JavaScript on the command line, the
-   ``--shell`` option provides the user with a shell prompt after
-   the file finishes executing.
+   :option:`--eval <--eval>` to specify JavaScript on the command line,
+   the :option:`--shell <--shell>` option provides the user with a shell
+   prompt after the file finishes executing.
 
-.. setting:: --version
+.. option:: --version
 
    Returns the |mdb-shell| release number.
 
 Connection Options
 ------------------
 
-.. setting:: --host <hostname>
+.. option:: --host <hostname>
 
    Specifies the name of the host machine where the
    :binary:`~bin.mongod` or :binary:`~bin.mongos` is running. If this is
@@ -64,9 +66,9 @@ Connection Options
 
          <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
 
-   For TLS/SSL connections (``--tls``),
+   For TLS/SSL connections (:option:`--tls <--tls>`),
      The |mdb-shell| shell verifies that the hostname
-     (specified in the ``--host`` option or the
+     (specified in the :option:`--host <--host>` option or the
      connection string) matches the ``SAN`` (or, if ``SAN`` is not
      present, the ``CN``) in the certificate presented by the
      :binary:`~bin.mongod` or :binary:`~bin.mongos`. If ``SAN`` is
@@ -90,43 +92,45 @@ Connection Options
 
             mongodb+srv://server.example.com/?connectionTimeout=3000ms
 
-.. setting:: --ipv6
+.. option:: --ipv6
 
    Enables IPv6 support. the |mdb-shell| disables IPv6 by default.
 
    To connect to a MongoDB cluster via IPv6, you must specify
-   both ``--ipv6`` *and*  ``--host <mongod/mongos IPv6 address>``
+   both :option:`--ipv6 <--ipv6>` *and*
+   :option:`--host (mongod/mongos IPv6 address) <--host>`
    when starting the |mdb-shell|.
 
    :binary:`~bin.mongod` and :binary:`~bin.mongos` disable IPv6 support
-   by default. Specifying ``--ipv6`` when connecting to a
+   by default. Specifying :option:`--ipv6 <--ipv6>` when connecting to a
    ``mongod/mongos`` does not enable IPv6 support on the
    ``mongod/mongos``. For documentation on enabling IPv6 support on the
    ``mongod/mongos``, see :setting:`net.ipv6`.
 
-.. setting:: --port <port>
+.. option:: --port <port>
 
    Specifies the port where the :binary:`~bin.mongod` or
-   :binary:`~bin.mongos` instance is listening. If ``--port`` is not
+   :binary:`~bin.mongos` instance is listening. If
+   :option:`--port <--port>` is not
    specified, the |mdb-shell| attempts to connect to port ``27017``.
 
 TLS Options
 ~~~~~~~~~~~
 
-.. setting:: --tls
+.. option:: --tls
 
    Enables connection to a :binary:`~bin.mongod` or
    :binary:`~bin.mongos` that has |tls-ssl| support enabled.
 
    .. include:: /includes/fact-ssl-see-more.rst
 
-.. setting:: --tlsCertificateKeyFile <filename>
+.. option:: --tlsCertificateKeyFile <filename>
 
    Specifies the :file:`.pem` file that contains both the |tls-ssl|
    certificate and key for the :binary:`~bin.mongo` shell. Specify the
    file name of the :file:`.pem` file using relative or absolute paths.
 
-   This option is required when using the ``--tls`` option to connect to
+   This option is required when using the :option:`--tls <--tls>` option to connect to
    a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance that
    requires :ref:`client certificates
    <mongo-connect-require-client-certificates-tls>`. That is, the
@@ -138,24 +142,28 @@ TLS Options
 
    .. include:: /includes/fact-ssl-see-more.rst
 
-.. setting:: --tlsCertificateKeyFilePassword <value>
+.. option:: --tlsCertificateKeyFilePassword <value>
 
    Specifies the password to de-crypt the certificate-key file (i.e.
-   ``--tlsCertificateKeyFile``).
+   :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>`).
 
-   Use the ``--tlsCertificateKeyFilePassword`` option only if the
+   Use the
+   :option:`--tlsCertificateKeyFilePassword
+   <--tlsCertificateKeyFilePassword>` option only if the
    certificate-key file is encrypted. In all cases, the |mdb-shell|
    redacts the password from all logging and reporting output.
 
    If the private key in the PEM file is encrypted and you do not
-   specify the ``--tlsCertificateKeyFilePassword`` option; the
-   |mdb-shell| prompts for a passphrase.
+   specify the
+   :option:`--tlsCertificateKeyFilePassword
+   <--tlsCertificateKeyFilePassword>` option; the |mdb-shell| prompts
+   for a passphrase.
 
    See :ref:`ssl-certificate-password`.
 
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-.. setting:: --tlsCAFile <filename>
+.. option:: --tlsCAFile <filename>
 
    Specifies the :file:`.pem` file that contains the root certificate
    chain from the Certificate Authority. This file is used to validate
@@ -167,15 +175,15 @@ TLS Options
 
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-.. setting:: --tlsCRLFile <filename>
+.. option:: --tlsCRLFile <filename>
 
    Specifies the :file:`.pem` file that contains the Certificate
    Revocation List. Specify the file name of the :file:`.pem` file
    using relative or absolute paths.
 
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-.. setting:: --tlsAllowInvalidHostnames
+.. option:: --tlsAllowInvalidHostnames
 
    Disables the validation of the hostnames in the certificate presented
    by the :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. Allows
@@ -184,7 +192,7 @@ TLS Options
 
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-.. setting:: --tlsAllowInvalidCertificates
+.. option:: --tlsAllowInvalidCertificates
 
    .. versionadded:: 4.2
 
@@ -195,46 +203,50 @@ TLS Options
    .. note::
 
       Starting in MongoDB 4.0, if you specify
-      ``--tlsAllowInvalidCertificates`` when using x.509
+      :option:`--tlsAllowInvalidCertificates
+      <--tlsAllowInvalidCertificates>` when using x.509
       authentication, an invalid certificate is only sufficient to
       establish a |tls-ssl| connection but is *insufficient* for
       authentication.
 
    .. warning::
 
       Although available, avoid using the
-      ``--tlsAllowInvalidCertificates`` option if possible. If the use
-      of ``--tlsAllowInvalidCertificates`` is necessary, only use the
-      option on systems where intrusion is not possible.
+      :option:`--tlsAllowInvalidCertificates
+      <--tlsAllowInvalidCertificates>` option if possible. If the
+      use of :option:`--tlsAllowInvalidCertificates
+      <--tlsAllowInvalidCertificates>` is necessary, only
+      use the option on systems where intrusion is not possible.
 
       If the |mdb-shell| shell (and other
       :ref:`mongodb-tools-support-ssl`) runs with the
-      ``--tlsAllowInvalidCertificates`` option, the shell (and other
-      :ref:`mongodb-tools-support-ssl`) do not attempt to validate the
-      server certificates. This creates a vulnerability to expired
+      :option:`--tlsAllowInvalidCertificates
+      <--tlsAllowInvalidCertificates>` option, the shell (and
+      other :ref:`mongodb-tools-support-ssl`) do not attempt to validate
+      the server certificates. This creates a vulnerability to expired
       :binary:`~bin.mongod` and :binary:`~bin.mongos` certificates as
       well as to foreign processes posing as valid :binary:`~bin.mongod`
       or :binary:`~bin.mongos` instances. If you only need to disable
       the validation of the hostname in the |tls-ssl| certificates, see
-      ``--tlsAllowInvalidHostnames``.
+      :option:`--tlsAllowInvalidHostnames <--tlsAllowInvalidHostnames>`.
 
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-.. setting:: --tlsCertificateSelector <parameter>=<value>
+.. option:: --tlsCertificateSelector <parameter>=<value>
 
    Available on Windows and macOS as an alternative to
-   ``--tlsCertificateKeyFile``.
+   :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>`.
 
-   The ``--tlsCertificateKeyFile`` and
-   ``--tlsCertificateSelector`` options are mutually exclusive.
-   You can only specify one.
+   The :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>` and
+   :option:`--tlsCertificateSelector <--tlsCertificateSelector>` options
+   are mutually exclusive. You can only specify one.
 
    Specifies a certificate property in order to select a matching
    certificate from the operating system's certificate store.
 
-   ``--tlsCertificateSelector`` accepts an argument of the format
-   ``<property>=<value>`` where the property can be one of the
-   following:
+   :option:`--tlsCertificateSelector <--tlsCertificateSelector>` accepts
+   an argument of the format ``<property>=<value>`` where the property
+   can be one of the following:
 
    .. list-table::
       :header-rows: 1
@@ -264,7 +276,7 @@ TLS Options
 
       .. include:: /includes/fact-certificate-expiry-warning.rst
 
-.. setting:: --tlsDisabledProtocols <string>
+.. option:: --tlsDisabledProtocols <string>
 
    Disables the specified TLS protocols. The option recognizes the
    following protocols:
@@ -286,23 +298,25 @@ TLS Options
 
    Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS
    1.1+ is available on the system. To enable the
-   disabled TLS 1.0, specify ``none`` to ``--tlsDisabledProtocols``.
+   disabled TLS 1.0, specify ``none`` to
+   :option:`--tlsDisabledProtocols <--tlsDisabledProtocols>`.
 
 Authentication Options
 ----------------------
 
-.. setting:: --authenticationDatabase <dbname>
+.. option:: --authenticationDatabase <dbname>
 
    Specifies the authentication database where the specified
-   ``--username`` has been created. See
+   :option:`--username <--username>` has been created. See
    :ref:`user-authentication-database`.
 
 
-   If you do not specify a value for ``--authenticationDatabase``,
+   If you do not specify a value for
+   :option:`--authenticationDatabase <--authenticationDatabase>`,
    the |mdb-shell| uses the database specified in the connection
    string.
 
-.. setting:: --authenticationMechanism <name>
+.. option:: --authenticationMechanism <name>
 
    *Default*: SCRAM-SHA-1
 
@@ -359,41 +373,44 @@ Authentication Options
           `MongoDB Enterprise
           <http://www.mongodb.com/products/mongodb-enterprise-advanced?jmp=docs>`_.
 
-.. setting:: --gssapiHostName
+.. option:: --gssapiHostName
 
    Specify the hostname of a service using
    :manual:`GSSAPI/Kerberos </core/kerberos>`. Only required if the
    hostname of a machine does not match the hostname resolved by DNS.
 
    This option is available only in MongoDB Enterprise.
 
-.. setting:: --gssapiServiceName
+.. option:: --gssapiServiceName
 
    Specify the name of the service using
    :manual:`GSSAPI/Kerberos </core/kerberos>`. Only required if the service does not use the default name of ``mongodb``.
 
    This option is available only in MongoDB Enterprise.
 
-.. setting:: --password <password>, -p <password>
+.. option:: --password <password>, -p <password>
 
    Specifies a password with which to authenticate to a MongoDB database
    that uses authentication. Use in conjunction with the
-   ``--username`` and ``--authenticationDatabase`` options.
+   :option:`--username <--username>` and
+   :option:`--authenticationDatabase <--authenticationDatabase>`
+   options.
 
    To force the |mdb-shell| to prompt for a password, enter the
-   ``--password`` option as the last option and leave out the
+   :option:`--password <--password>` option as the last option and leave out the
    argument.
 
-.. setting:: --username <username>, -u <username>
+.. option:: --username <username>, -u <username>
 
    Specifies a username with which to authenticate to a MongoDB database
    that uses authentication. Use in conjunction with the
-   ``--password`` and ``--authenticationDatabase`` options.
+   :option:`--password <--password>` and
+   :option:`--authenticationDatabase <--authenticationDatabase>` options.
 
 Session Options
 ---------------
 
-.. setting:: --retryWrites
+.. option:: --retryWrites
 
    Enables :manual:`retryable writes </core/retryable-writes/>` as the
    default for sessions in the |mdb-shell|.