Fix problems with the docs for the remap.config ConfigFile Parameters (#6079)

* Fix problems with the docs for the remap.config ConfigFile Parameters

This includes problems that inhibit rendering as well as consistency and
semantic issues.

* Fix implicit long hyphen

Author: ocket8888

docs/source/overview/delivery_services.rst

@@ -647,7 +647,7 @@ Describes how HTTP "Range Requests" should be handled by the Delivery Service at
 .. _ds-slice-block-size:
 
 Range Slice Request Block Size
--------------------------------------
+------------------------------
 The block size in bytes that is used for `slice <https://github.com/apache/trafficserver/tree/master/plugins/experimental/slice>`_ plugin.
 
 This can only and must be set if the :ref:`ds-range-request-handling` is set to ``3``.

docs/source/overview/profiles_and_parameters.rst

@@ -584,30 +584,38 @@ This configuration file can only be affected by the special ``maxRevalDurationDa
 
 remap.config
 ''''''''''''
-This configuration file can only be affected by Parameters on a :ref:`Profile <profiles>` assigned to a :term:`Delivery Service`. Then, for every Parameter assigned to that :ref:`Profile <profiles>` that has the Config File value "remap.config" -, a parameter will be added to the line for that :term:`Delivery Service` like so: :file:`@pparam={Value}` where ``Name`` is of the form `<plugin>.pparam` and ``Value`` are the plugin pparam arguments. Each argument should have its ow n parameter Repeated arguments are allowed but a warning is issued.
+This configuration file can only be affected by Parameters on a :ref:`Profile <profiles>` assigned to a :term:`Delivery Service`. Then, for every Parameter assigned to that :ref:`Profile <profiles>` that has the Config File value "remap.config" -, a parameter will be added to the line for that :term:`Delivery Service` of the form :samp:`@pparam={Value}` where ``Value`` is the Parameter's Value_. Each argument should have its own Parameter. Repeated arguments are allowed, but a warning is issued by :term:`t3c` when processing configuration for cache servers that serve content for the :term:`Delivery Service` with a :ref:`Profile <profiles>` that includes duplicate arguments.
 
-For backwards compatibility a special case exists for the ``cachekey.config`` "term"`Delivery Service` parameter. This is of the form: :file:`pparam=--{Name}={Value}` where ``Name`` is the Parameter's :ref:`parameter-name`, and ``Value`` is its Value_.  A warning will be issued if these parameters are used along with ``cachekey.pparam`` parameters.
+For backwards compatibility, a special case exists for the ``cachekey.config`` Config File for Parameters on :term:`Delivery Service` Profiles_ that can also affect this configuration file. This is of the form: :samp:`pparam=--{Name}={Value}` where ``Name`` is the Parameter's :ref:`parameter-name`, and ``Value`` is its Value_.  A warning will be issued by :term:`t3c` when processing configuration for cache servers that serve content for the :term:`Delivery Service` with a :ref:`Profile <profiles>` that uses a Parameter with the Config File ``cachekey.config`` as well as at least one with the Config File ``cachekey.pparam``.
 
-The following plugins have support for adding args with following parameter `Config File`
-  - ``background_fetch.pparam`` `<https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>` Note the --config=bg_fetch.conf arg is already added by t3c.
-  - ``cachekey.pparam`` `<https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html>`
-  - ``cache_range_requests.pparam`` `<https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cache_range_requests.en.html>`
-  - ``slice.pparam`` `<https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/slice.en.html>`  Note the --blocksize=<val> is already handled in the :ref:`tp-services-delivery-service` view in Traffic Portal.
-  - ``url_sig.pparam`` `<https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/url_sig.en.html>`. Note the config file is already added by t3c.
+The following plugins have support for adding args with following parameter Config File values.
 
-.. note:: cachekey.config is deprecated but available for backwards compatibility.  cachekey.config Name and Value will be converted to the pparam syntax with '--' added as a prefix to the name.  Any "empty" param value (ie: separator) will add an extra '=' to the key.
+- ``background_fetch.pparam`` Note the ``--config=bg_fetch.conf`` argument is already added to ``remap.config`` by :term:`t3c`.
+- ``cachekey.pparam``
+- ``cache_range_requests.pparam``
+- ``slice.pparam`` Note the :samp:`--blocksize={val}` plugin parameter is specifiable directly on :term:`Delivery Services` by setting their :ref:`ds-slice-block-size` property.
+- ``url_sig.pparam`` Note the configuration file for this plugin is already added by :term:`t3c`.
+
+.. seealso:: For more information about these plugin parameters, refer to `the Apache Traffic Server documentation for the background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_, `the Apache Traffic Server documentation for the cachekey plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html>`_, `the Apache Traffic Server documentation for the cache_range_requests plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cache_range_requests.en.html>`_, `the Apache Traffic Server documentation for the slice plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/slice.en.html>`_, and `the Apache Traffic Server documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/url_sig.en.html>`_, respectively.
+
+.. deprecated:: ATCv6
+	``cachekey.config`` is deprecated but available for backwards compatibility. ``cachekey.config`` Parameters will be converted by :term:`t3c` to the "pparam" syntax with ``--`` added as a prefix to the :ref:`parameter-name`. Any "empty" param value (i.e. separator) will add an extra ``=`` to the key.
 
 .. table:: Equivalent cachekey.config/cachekey.pparam entries
 
-  +------------------------+---------------------+--------------------------+----------------------------------+
-  | :ref:`parameter-name`  | `Config File`_      | Value_                   | Result                           |
-  +========================+=====================+==========================+==================================+
-  | remove-all-params      | cachekey.config     | true                     | @pparam=--remove-all-params=true |
-  | cachekey.pparam        | remap.config        | --remove-all-params=true | @pparam=--remove-all-params=true |
-  | separator              | cachekey.config     |                          | @pparam=--separator=             |
-  | cachekey.pparam        | remap.config        | --separator=             | @pparam=--separator=             |
-  | cachekey.pparam        | cachekey.pparam     | -o                       | @pparam=-o (no config equiv)     |
-  +------------------------+---------------------+--------------------------+----------------------------------+
+	+------------------------+---------------------+------------------------------+--------------------------------------+
+	| :ref:`parameter-name`  | Config File         | Value_                       | Result                               |
+	+========================+=====================+==============================+======================================+
+	| remove-all-params      | cachekey.config     | ``true``                     | ``@pparam=--remove-all-params=true`` |
+	+------------------------+---------------------+------------------------------+--------------------------------------+
+	| cachekey.pparam        | remap.config        | ``--remove-all-params=true`` | ``@pparam=--remove-all-params=true`` |
+	+------------------------+---------------------+------------------------------+--------------------------------------+
+	| separator              | cachekey.config     | (empty value)                | ``@pparam=--separator=``             |
+	+------------------------+---------------------+------------------------------+--------------------------------------+
+	| cachekey.pparam        | remap.config        | ``--separator=``             | ``@pparam=--separator=``             |
+	+------------------------+---------------------+------------------------------+--------------------------------------+
+	| cachekey.pparam        | cachekey.pparam     | ``-o``                       | ``@pparam=-o``                       |
+	+------------------------+---------------------+------------------------------+--------------------------------------+
 
 
 .. seealso:: For an explanation of the syntax of this configuration file, refer to `the Apache Traffic Server remap.config documentation <https://docs.trafficserver.apache.org/en/7.1.x/admin-guide/files/remap.config.en.html>`_.