Doc updates for mc RELEASE.2024-01-05T05-04-32Z (#1112)

Doc updates for these `mc` changes:

- New option for `mc mirror`: `--summary`
- Clarify `mc sql --json-input` also works with `.ndjson`

NDJSON clarified with a discussion in `mc sql` and an example of setting
`content-type` in `mc cp`.

Staged:

http://192.241.195.202:9000/staging/DOCS-1104/linux/reference/minio-mc/mc-mirror.html#mc.mirror.-summary


http://192.241.195.202:9000/staging/DOCS-1104/linux/reference/minio-mc/mc-sql.html#mc.sql.-json-input

http://192.241.195.202:9000/staging/DOCS-1104/linux/reference/minio-mc/mc-sql.html#input-formats

http://192.241.195.202:9000/staging/DOCS-1104/linux/reference/minio-mc/mc-cp.html#add-a-content-type-value

Fixes https://github.com/minio/docs/issues/1104

source/reference/minio-mc/mc-cp.rst

@@ -163,7 +163,7 @@ Parameters
 
    Enclose the entire list of key-value pairs passed to :mc-cmd:`~mc cp --encrypt` in double-quotes ``"``.
 
-   :mc-cmd:`~mc cp --encrypt` can use the ``MC_ENCRYPT`` environment variable for retrieving a list of encryption key-value pairs as an alternative to specifying them on the command line.
+   :mc-cmd:`~mc cp --encrypt` can use the :envvar:`MC_ENCRYPT` environment variable for retrieving a list of encryption key-value pairs as an alternative to specifying them on the command line.
 
 .. mc-cmd:: --encrypt-key
    :optional:
@@ -178,7 +178,7 @@ Parameters
    Enclose the entire list of key-value pairs passed to 
    :mc-cmd:`~mc cp --encrypt-key` in double quotes ``"``.
 
-   :mc-cmd:`~mc cp --encrypt-key` can use the ``MC_ENCRYPT_KEY``
+   :mc-cmd:`~mc cp --encrypt-key` can use the :envvar:`MC_ENCRYPT_KEY`
    environment variable for retrieving a list of encryption key-value pairs
    as an alternative to specifying them on the command line.
 
@@ -449,6 +449,35 @@ command only applies to S3-to-S3 copy.
    :start-after: start-versioning-admonition
    :end-before: end-versioning-admonition
 
+Add a ``content-type`` Value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc cp --attr` to add a ``content-type`` value.
+This command only applies to S3-to-S3 copy.
+
+.. code-block:: shell
+   :class: copyable
+
+   mc cp --attr="content-type=CONTENT-TYPE" SRCALIAS/SRCPATH TGTALIAS/TGTPATH
+
+- Replace ``CONTENT-TYPE`` with the desired content type (also called a `media type <https://www.iana.org/assignments/media-types/media-types.xhtml>`__).
+
+- Replace :mc-cmd:`SRCALIAS <mc cp SOURCE>` with the :mc:`alias <mc alias>` of a source S3-compatible host.
+
+- Replace :mc-cmd:`SRCPATH <mc cp SOURCE>` with the path to the object on the source S3-compatible host.
+
+- Replace :mc-cmd:`TGTALIAS <mc cp TARGET>` with the :mc:`alias <mc alias>` of a target S3-compatible host.
+
+- Replace :mc-cmd:`TGTPATH <mc cp TARGET>` with the path to the object on the target S3-compatible host.
+  Omit the object name to use the ``SRCPATH`` object name.
+
+The following example sets a ``content-type`` of ``application/json``:
+
+.. code-block::
+   :class: copyable
+
+    mc cp data.ndjson --attr="content-type=application/json" myminio/mybucket                              
+
 
 Behavior
 --------

source/reference/minio-mc/mc-mirror.rst

@@ -78,8 +78,9 @@ Parameters
 ~~~~~~~~~~
 
 .. mc-cmd:: SOURCE
+   :required:
 
-   *REQUIRED* The file(s) or object(s) to synchronize to the :mc-cmd:`~mc mirror TARGET` S3 host.
+   The file(s) or object(s) to synchronize to the :mc-cmd:`~mc mirror TARGET` S3 host.
 
    For objects on S3-compatible hosts, specify the path to the object as ``ALIAS/PATH``, where:
 
@@ -100,8 +101,9 @@ Parameters
    If specifying a directory, :mc:`mc mirror` synchronizes all files in the directory.
 
 .. mc-cmd:: TARGET
+   :required:
 
-   *REQUIRED* The full path to bucket to which :mc:`mc mirror` synchronizes SOURCE objects. Specify the ``TARGET`` as ``ALIAS/PATH``, where:
+   The full path to bucket to which :mc:`mc mirror` synchronizes SOURCE objects. Specify the ``TARGET`` as ``ALIAS/PATH``, where:
 
    - ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible host, *and*
 
@@ -114,18 +116,24 @@ Parameters
    :mc:`mc mirror` uses the object or file names from the :mc-cmd:`~mc mirror SOURCE` when synchronizing to the ``TARGET`` bucket.
 
 .. mc-cmd:: --attr
-   
+   :optional:
 
    Add custom metadata for mirrored objects. Specify key-value pairs as ``KEY=VALUE\;``. 
    For example, ``--attr key1=value1\;key2=value2\;key3=value3``.
 
 .. mc-cmd:: --disable-multipart
-   
+   :optional:
 
    Disables multipart upload for the synchronization session.
 
-.. mc-cmd:: --encrypt-key
+.. mc-cmd:: --dry-run
+   :optional:
 
+   Perform a mock mirror operation.
+   Use this operation to test that the :mc:`mc mirror` operation will only mirror the desired objects or buckets.
+
+.. mc-cmd:: --encrypt-key
+   :optional:
 
    Encrypt or decrypt objects using server-side encryption with client-specified keys. 
    Specify key-value pairs as ``KEY=VALUE``.
@@ -140,24 +148,18 @@ Parameters
    You can only delete encrypted objects if you specify the correct :mc-cmd:`~mc mirror --encrypt-key` secret key.
 
 .. mc-cmd:: --exclude
-   
+   :optional:
 
    Exclude object(s) in the :mc-cmd:`~mc mirror SOURCE` path that match the specified object name pattern.
 
 .. mc-cmd:: --exclude-storageclass
-   
+   :optional:
 
    Exclude object(s) on the :mc-cmd:`~mc mirror SOURCE` that have the specified storage class.
    You can use this flag multiple times in a command to exclude objects from more than one storage class.
 
    Use this to exclude objects with storage classes that require rehydration or restoration of objects, such as migrating from an AWS S3 bucket where some objects have the ``GLACIER`` or ``DEEP_ARCHIVE`` storage classes.
 
-.. mc-cmd:: --dry-run
-   
-
-   Perform a mock mirror operation. 
-   Use this operation to test that the :mc:`mc mirror` operation will only mirror the desired objects or buckets.
-
 .. --limit-download and --limit-upload included here
 
 .. include:: /includes/linux/minio-client.rst
@@ -165,26 +167,26 @@ Parameters
    :end-before: end-mc-limit-flags-desc
 
 .. mc-cmd:: --md5
-   
+   :optional:
 
    Forces all uploads to calculate MD5 checksums.
 
 .. mc-cmd:: --monitoring-address
-   
+   :optional:
 
    Creates a `Prometheus <https://prometheus.io/>`__ endpoint for monitoring mirroring activity. 
    Specify the local network adapter and port address on which to create the scraping endpoint. 
    Defaults to ``localhost:8081``).
 
 .. mc-cmd:: --newer-than
-   
+   :optional:
 
    Mirror object(s) newer than the specified number of days.
-   Specify a string in ``#d#hh#mm#ss`` format. 
+   Specify a string in ``#d#hh#mm#ss`` format
    For example: ``--newer-than 1d2hh3mm4ss``.
 
 .. mc-cmd:: --older-than
-   
+   :optional:
 
    Mirror object(s) older than the specified time limit.
    Specify a string in ``#d#hh#mm#ss`` format.
@@ -193,7 +195,7 @@ Parameters
    Defaults to ``0`` (all objects).
 
 .. mc-cmd:: --overwrite
-   
+   :optional:
 
    Overwrites object(s) on the :mc-cmd:`~mc mirror TARGET`.
 
@@ -205,19 +207,19 @@ Parameters
    ``mc mirror`` logs an error and continues to synchronize other objects.
 
 .. mc-cmd:: --preserve, a
-   
+   :optional:
 
    Preserve file system attributes and bucket policy rules of the :mc-cmd:`~mc mirror SOURCE` on the :mc-cmd:`~mc mirror TARGET`.
 
 .. mc-cmd:: --region
-   
+   :optional:
 
    Specify the ``string`` region when creating new bucket(s) on the target.
 
    Defaults to ``"us-east-1"``.
 
 .. mc-cmd:: --remove
-   
+   :optional:
 
    Removes object(s) on the Target that do not exist on the Source.
 
@@ -241,18 +243,24 @@ Parameters
       In prior versions, specifying ``/path/to/directory`` would result in the removal of the ``/path/to`` folder if ``directory`` did not exist.
 
 .. mc-cmd:: --retry
+   :optional:
 
    In case of errors during mirror process, retry on each errored object.
 
-.. mc-cmd:: storage-class, sc
+.. mc-cmd:: --storage-class, sc
-   
+   :optional:
 
    Set the storage class for the new object(s) on the :mc-cmd:`~mc mirror TARGET`. 
 
    See the Amazon documentation on :aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>` for more information on S3 storage classses.
 
-.. mc-cmd:: --watch, w
+.. mc-cmd:: --summary
+   :optional:
 
+   On completion, output a summary of the data that was synchronized.
+
+.. mc-cmd:: --watch, w
+   :optional:
 
    Use ``--watch`` flag to mirror objects from Source to Target, where the Target may also have additional objects not present on the Source.
 

source/reference/minio-mc/mc-sql.rst

@@ -15,21 +15,17 @@ Syntax
 
 .. start-mc-sql-desc
 
-The :mc:`mc sql` command provides an S3 Select interface for performing sql
+The :mc:`mc sql` command provides an S3 Select interface for performing sql queries on objects in the specified MinIO deployment.
-queries on objects in the specified MinIO deployment. 
 
 .. end-mc-sql-desc
 
-See :s3-docs:`Selecting content from objects 
+See :s3-docs:`Selecting content from objects <selecting-content-from-objects>` for more information on S3 Select behavior and limitations.
-<selecting-content-from-objects>` for more information on S3 Select behavior
-and limitations.
 
 .. tab-set::
 
    .. tab-item:: EXAMPLE
 
-      The following command queries all objects in the
+      The following command queries all objects in the ``mydata`` bucket on the ``myminio`` MinIO deployment:
-      ``mydata`` bucket on the ``myminio`` MinIO deployment:
 
       .. code-block:: shell
          :class: copyable
@@ -63,36 +59,36 @@ Parameters
 ~~~~~~~~~~
 
 .. mc-cmd:: ALIAS
+   :required:
 
-   *Required* The full path to the bucket or object to run the SQL query
+   The full path to the bucket or object to run the SQL query against.
-   against. Specify the :ref:`alias <alias>` of a configured
+   Specify the :ref:`alias <alias>` of a configured S3 service as the prefix to the ``ALIAS`` path.
-   S3 service as the prefix to the ``ALIAS`` path. For example:
+   For example:
 
    .. code-block:: shell
 
       mc sql [FLAGS] play/mybucket
 
 .. mc-cmd:: --query, e
+   :required:
 
-
+   The SQL statement to execute on the specified :mc-cmd:`~mc sql ALIAS` directory or object.
-   *Required* The SQL statement to execute on the specified 
+   Wrap the entire SQL query in double quotes ``"``.
-   :mc-cmd:`~mc sql ALIAS` directory or object. Wrap the entire SQL query in 
-   double quotes ``"``.
 
    Defaults to ``"select * from S3Object"``.
 
 .. mc-cmd:: --csv-input
+   :optional:
 
-
+   The data format for ``.csv`` input objects.
-   *Optional* The data format for ``.csv`` input objects. Specify a string of
+   Specify a string of comma-seperated ``key=value,...`` pairs.
-   comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for
+   See :ref:`mc-sql-csv-format` for more information on valid keys.
-   more information on valid keys.
 
 .. mc-cmd:: --compression
+   :optional:
 
-
+   The compression type of the input object.
-   *Optional* The compression type of the input object. Specify one of the
+   Specify one of the following supported values:
-   following supported values:
 
    - ``GZIP``
    - ``BZIP2``
@@ -106,71 +102,62 @@ Parameters
    - ``SNAPPY`` `Snappy <http://google.github.io/snappy/>`__ framed stream
 
 .. mc-cmd:: --csv-output
+   :optional:
 
+   The data format for ``.csv`` output.
+   Specify a string of comma-seperated ``key=value,...`` pairs.
+   See :ref:`mc-sql-csv-format` for more information on valid keys.
 
-   *Optional* The data format for ``.csv`` output. Specify a string of
+   See the S3 API :s3-api:`CSVOutput <API_CSVOutput.html>` for more information.
-   comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for
-   more information on valid keys.
-
-   See the S3 API :s3-api:`CSVOutput <API_CSVOutput.html>` for more
-   information.
 
 .. mc-cmd:: --csv-output-header
+   :optional:
 
-
+   The header row of the ``.csv`` output file.
-   *Optional* The header row of the ``.csv`` output file. Specify a string of
+   Specify a string of comma-separated fields as ``field1,field2,...``.
-   comma-separated fields as ``field1,field2,...``.
 
    Omit to output a ``.csv`` with no header row.
 
 .. mc-cmd:: --encrypt-key
+   :optional:
 
+   The encryption key to use for performing Server-Side Encryption with Client Keys (SSE-C).
+   Specify comma seperated key-value pairs as ``KEY=VALUE,...``.
 
-   *Optional* The encryption key to use for performing Server-Side Encryption
+   - For ``KEY``, specify the MinIO deployment :mc-cmd:`alias <mc alias>` and full path to the bucket, including any bucket prefixes.
-   with Client Keys (SSE-C). Specify comma seperated key-value pairs as
+     Separate the alias and bucket path with a forward slash ``\``.
-   ``KEY=VALUE,...``.
+     For example, ``play/mybucket``.
 
-   - For ``KEY``, specify the MinIO deployment 
+   - For ``VALUE``, specify the data key to use for encryption object(s) in the bucket or bucket prefix specified to ``KEY``.
-     :mc-cmd:`alias <mc alias>` and full path to the bucket, including any
-     bucket prefixes. Separate the alias and bucket path with a forward slash 
-     ``\``. For example, ``play/mybucket``
 
-   - For ``VALUE``, specify the data key to use for encryption object(s) in
+   :mc-cmd:`~mc sql --encrypt-key` can use the :envvar:`MC_ENCRYPT_KEY` environment variable for populating the list of encryption key-value pairs as an alternative to specifying them on the command line.
-     the bucket or bucket prefix specified to ``KEY``.
-
-   :mc-cmd:`~mc sql --encrypt-key` can use the ``MC_ENCRYPT_KEY``
-   environment variable for populating the list of encryption key-value
-   pairs as an alternative to specifying them on the command line.
 
 .. mc-cmd:: --json-input
+   :optional:
 
-
+   The data format for ``.json`` or ``.ndjson`` input objects.
-   *Optional* The data format for ``.json`` input objects. Specify the type of 
+   Specify the type of the JSON contents as ``type=<VALUE>``.
-   the JSON contents as ``type=<VALUE>``. The value can be either:
+   The value can be either:
 
    - ``DOCUMENT`` - JSON `document <https://www.json.org/json-en.html>`__.
    - ``LINES`` - JSON `lines <http://jsonlines.org/>`__.
 
-   See the S3 API :s3-api:`JSONInput <API_JSONInput.html>` for more
+   See the S3 API :s3-api:`JSONInput <API_JSONInput.html>` for more information.
-   information.
 
 .. mc-cmd:: --json-output
+   :optional:
 
-
+   The data format for the ``.json`` output.
-   *Optional* The data format for the ``.json`` output. Supports the 
+   Supports the ``rd=value`` key, where ``rd`` is the ``RecordDelimiter`` for the JSON document.
-   ``rd=value`` key, where ``rd`` is the ``RecordDelimiter`` for the JSON
-   document.
 
    Omit to use the default newline character ``\n``.
 
-   See the S3 API :s3-api:`JSONOutput <API_JSONOutput.html>` for more
+   See the S3 API :s3-api:`JSONOutput <API_JSONOutput.html>` for more information.
-   information.
 
 .. mc-cmd:: --recursive, r
+   :optional:
 
-
+   Recursively searches the specified :mc-cmd:`~mc sql ALIAS` directory using the :mc-cmd:`~mc sql --query` SQL statement.
-   *Optional* Recursively searches the specified :mc-cmd:`~mc sql ALIAS`
-   directory using the :mc-cmd:`~mc sql --query` SQL statement.
 
 Global Flags
 ~~~~~~~~~~~~
@@ -185,36 +172,29 @@ Examples
 Select all Columns in all Objects in a Bucket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use :mc:`mc sql` with the :mc-cmd:`~mc sql --recursive` and
+Use :mc:`mc sql` with the :mc-cmd:`~mc sql --recursive` and :mc-cmd:`~mc sql --query` options to apply the query to all objects  in a bucket:
-:mc-cmd:`~mc sql --query` options to apply the query to all objects 
-in a bucket:
 
 .. code-block:: shell
    :class: copyable
 
    mc sql --recursive --query "select * from S3Object" ALIAS/PATH
 
-- Replace :mc-cmd:`ALIAS <mc sql ALIAS>` with the 
+- Replace :mc-cmd:`ALIAS <mc sql ALIAS>` with the :ref:`alias <alias>` of the MinIO deployment.
-  :ref:`alias <alias>` of the MinIO deployment.
 
-- Replace :mc-cmd:`PATH <mc sql ALIAS>` with the path to the bucket
+- Replace :mc-cmd:`PATH <mc sql ALIAS>` with the path to the bucket on the MinIO deployment.
-  on the MinIO deployment.
 
 Run an Aggregation Query on an Object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use :mc:`mc sql` with the :mc-cmd:`~mc sql --query` option to query 
+Use :mc:`mc sql` with the :mc-cmd:`~mc sql --query` option to query an object on an MinIO deployment:
-an object on an MinIO deployment:
 
 .. code-block:: shell
 
    mc sql --query "select count(s.power) from S3Object" ALIAS/PATH
 
-- Replace :mc-cmd:`ALIAS <mc sql ALIAS>` with the 
+- Replace :mc-cmd:`ALIAS <mc sql ALIAS>` with the :ref:`alias <alias>` of the MinIO deployment.
-  :ref:`alias <alias>` of the MinIO deployment.
 
-- Replace :mc-cmd:`PATH <mc sql ALIAS>` with the path to the object
+- Replace :mc-cmd:`PATH <mc sql ALIAS>` with the path to the object on the MinIO deployment.
-  on the MinIO deployment.
 
 Behavior
 --------
@@ -224,30 +204,42 @@ Input Formats
 
 :mc:`mc sql` supports the following input formats:
 
-- ``.csv``
+.. list-table:: Input Format Types
-- ``.json``
+   :header-rows: 1
-- ``.parquet``
 		 
-For ``.csv`` file types, use :mc-cmd:`mc sql --csv-input` to 
+   * - Type
-specify the CSV data format. See :ref:`mc-sql-csv-format` for more 
+     - ``content-type`` Value
-information on CSV formatting fields.
 
-For ``.json`` file types, use :mc-cmd:`mc sql --json-input` to specify
+   * - ``.csv``
-the JSON data format.
+     - ``text/csv``
 
-For ``.parquet`` file types, :mc:`mc sql` automatically interprets the
+   * - ``.json``
-data format.
+     - ``application/json``
+
+   * - ``.parquet``
+     - none
+
+For ``.csv`` file types, use :mc-cmd:`mc sql --csv-input` to specify the CSV data format.
+See :ref:`mc-sql-csv-format` for more information on CSV formatting fields.
+
+For ``.json`` file types, use :mc-cmd:`mc sql --json-input` to specify the JSON data format.
+
+For ``.parquet`` file types, :mc:`mc sql` automatically interprets the data format.
+
+:mc:`mc sql` determines the type by the file extension of the target object.
+For example, an object named ``data.json`` is interpreted as a JSON file.
+
+You can query data of a supported type but a different extension if the object has the appropriate ``content-type``.
+For more information, see :mc-cmd:`mc cp --attr`.
 
 .. _mc-sql-csv-format:
 
 CSV Formatting Fields
 ~~~~~~~~~~~~~~~~~~~~~
 
-The following table lists valid key-value pairs for use with
+The following table lists valid key-value pairs for use with :mc-cmd:`mc sql --csv-input` and :mc-cmd:`mc sql --csv-output`.
-:mc-cmd:`mc sql --csv-input` and :mc-cmd:`mc sql --csv-output`. 
+Certain key pairs are only valid for :mc-cmd:`~mc sql --csv-input`.
-Certain key pairs are only valid for :mc-cmd:`~mc sql --csv-input`
+See the documentation for S3 API :s3-api:`CSVInput <API_CSVInput.html>` for more information on S3 CSV formatting.
-See the documentation for S3 API :s3-api:`CSVInput <API_CSVInput.html>` for more 
-information on S3 CSV formatting.
 
 .. list-table::
    :header-rows: 1
@@ -260,29 +252,25 @@ information on S3 CSV formatting.
 
    * - ``rd``
      -
-     - The character that seperates each record (row) in the input ``.csv``
+     - The character that seperates each record (row) in the input ``.csv`` file.
-       file.
 
        Corresponds to ``RecordDelimiter`` in the S3 API ``CSVInput``.
 
    * - ``fd``
      -
-     - The character that seperates each field in a record. Defaults to 
+     - The character that seperates each field in a record. Defaults to ``,``.
-       ``,``.
 
        Corresponds to ``FieldDelimeter`` in the S3 API ``CSVInput``.
 
    * - ``qc``
      -
-     - The character used for escaping when the ``fd`` character is part of 
+     - The character used for escaping when the ``fd`` character is part of a value. Defaults to ``"``.
-       a value. Defaults to ``"``.
 
        Corresponds to ``QuoteCharacter`` in the S3 API ``CSVInput``.
 
    * - ``qec``
      -
-     - The character used for escaping a quotation mark ``"`` character
+     - The character used for escaping a quotation mark ``"`` character inside an already escaped value. 
-       inside an already escaped value. 
 
        Corresponds to ``QuoteEscapeCharacter`` in the S3 API ``CSVInput``.
 
@@ -296,31 +284,26 @@ information on S3 CSV formatting.
        - ``IGNORE`` - Ignore the first line.
        - ``USE`` - The first line is a header.
 
-       For ``NONE`` or ``IGNORE``, you must specify column positions
+       For ``NONE`` or ``IGNORE``, you must specify column positions ``_#`` to identify a column in the :mc-cmd:`~mc sql --query` statement.
-       ``_#`` to identify a column in the :mc-cmd:`~mc sql --query` 
-       statement.
 
-       For ``USE``, you can specify header values to identify a column in 
+       For ``USE``, you can specify header values to identify a column in the :mc-cmd:`~mc sql --query` statement.
-       the :mc-cmd:`~mc sql --query` statement.
 
        Corresponds to ``FieldHeaderInfo`` in the S3 API ``CSVInput``.
 
    * - ``cc``
      - Yes
-     - The character used to indicate a record should be ignored. The
+     - The character used to indicate a record should be ignored.
-       character *must* appear at the beginning of the record.
+       The character *must* appear at the beginning of the record.
 
        Corresponds to ``Comment`` in the S3 API ``CSVInput``.
 
    * - ``qrd``
      - Yes
-     - Specify ``TRUE`` to indicate that fields may contain record delimiter
+     - Specify ``TRUE`` to indicate that fields may contain record delimiter values (``rd``).
-       values (``rd``).
 
        Defaults to ``FALSE``.
 
-       Corresponds to ``AllowQuotedRecordDelimiter`` in the S3 API
+       Corresponds to ``AllowQuotedRecordDelimiter`` in the S3 API ``CSVInput``.
-       ``CSVInput``.
 
 S3 Compatibility
 ~~~~~~~~~~~~~~~~