refactor rsyslog module parameter documentation for mmsnmptrapd

* mmsnmptrapd: split parameter docs into reference pages

doc/source/configuration/modules/mmsnmptrapd.rst

@@ -57,30 +57,34 @@ this module, with the help of filters or multiple rulesets and ruleset
 bindings. In short words, all capabilities rsyslog offers to control
 output modules are also available to mmsnmptrapd.
 
-**Configuration Parameters**:
+Module Parameters
+-----------------
 
-Note: parameter names are case-insensitive.
+.. note::
 
--  **$mmsnmptrapdTag** [tagname]
+   Parameter names are case-insensitive; camelCase is recommended for
+   readability.
 
-   Tells the module which start string inside the tag to look for. The
+.. list-table::
-   default is "snmptrapd". Note that a slash is automatically added to
+   :widths: 30 70
-   this tag when it comes to matching incoming messages. It MUST not be
+   :header-rows: 1
-   given, except if two slashes are required for whatever reasons (so
-   "tag/" results in a check for "tag//" at the start of the tag field).
 
--  **$mmsnmptrapdSeverityMapping** [severitymap]
+   * - Parameter
-   This specifies the severity mapping table. It needs to be specified
+     - Summary
-   as a list. Note that due to the current config system **no
+   * - :ref:`param-mmsnmptrapd-tag`
-   whitespace** is supported inside the list, so be sure not to use any
+     - .. include:: ../../reference/parameters/mmsnmptrapd-tag.rst
-   whitespace inside it.
+        :start-after: .. summary-start
-   The list is constructed of Severity-Name/Severity-Value pairs,
+        :end-before: .. summary-end
-   delimited by comma. Severity-Name is a case-sensitive string, e.g.
+   * - :ref:`param-mmsnmptrapd-severitymapping`
-   "warning" and an associated numerical value (e.g. 4). Possible values
+     - .. include:: ../../reference/parameters/mmsnmptrapd-severitymapping.rst
-   are in the rage 0..7 and are defined in RFC5424, table 2. The given
+        :start-after: .. summary-start
-   sample would be specified as "warning/4".
+        :end-before: .. summary-end
-   If multiple instances of mmsnmptrapd are used, each instance uses
+
-   the most recently defined $mmsnmptrapdSeverityMapping before itself.
+.. toctree::
+   :hidden:
+
+   ../../reference/parameters/mmsnmptrapd-tag
+   ../../reference/parameters/mmsnmptrapd-severitymapping
 
 **Caveats/Known Bugs:**
 
@@ -93,10 +97,9 @@ warning severities. The default tag is used.
 
 ::
 
-  $ModLoad mmsnmptrapd # needs to be done just once
+  module(load="mmsnmptrapd" severityMapping="warning/4,error/3") # needs to be done just once
   # ... other module loads and listener setup ...
   *.* /path/to/file/with/originalMessage # this file receives unmodified messages
-  $mmsnmptrapdSeverityMapping warning/4,error/3
   *.* :mmsnmptrapd: # now message is modified
   *.* /path/to/file/with/modifiedMessage # this file receives modified messages
   # ... rest of config ...

doc/source/reference/parameters/mmsnmptrapd-severitymapping.rst

@@ -0,0 +1,63 @@
+.. _param-mmsnmptrapd-severitymapping:
+.. _mmsnmptrapd.parameter.module.severitymapping:
+
+severityMapping
+===============
+
+.. index::
+   single: mmsnmptrapd; severityMapping
+   single: severityMapping
+
+.. summary-start
+
+Defines severity string to numeric code mappings.
+
+.. summary-end
+
+This parameter applies to :doc:`../../configuration/modules/mmsnmptrapd`.
+
+:Name: severityMapping
+:Scope: module
+:Type: string
+:Default: module=none
+:Required?: no
+:Introduced: at least 5.8.1, possibly earlier
+
+Description
+-----------
+This specifies the severity mapping table. It must be specified as a list.
+Note that **no whitespace** is supported inside the list, as it will likely
+lead to parsing errors. The list is
+constructed of Severity-Name/Severity-Value pairs, delimited by comma.
+Severity-Name is a case-sensitive string, e.g. ``warning`` and an associated
+numerical value (e.g. 4). Possible values are in the range 0..7 and are defined
+in `RFC5424, table 2 <https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1>`_.
+The given sample would be specified as ``warning/4``. The mapping is defined
+when the module is loaded using the ``module()`` statement. This setting applies
+to all subsequent actions that use this module instance. To use different
+mappings, load separate instances of the module in different rulesets.
+
+Module usage
+------------
+.. _param-mmsnmptrapd-module-severitymapping:
+.. _mmsnmptrapd.parameter.module.severitymapping-usage:
+
+.. code-block:: rsyslog
+
+   module(load="mmsnmptrapd" severityMapping="warning/4,error/3")
+
+Legacy names (for reference)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historic names/directives for compatibility. Do not use in new configs.
+
+.. _mmsnmptrapd.parameter.legacy.mmsnmptrapdseveritymapping:
+
+- $mmsnmptrapdSeverityMapping — maps to severityMapping (status: legacy)
+
+.. index::
+   single: mmsnmptrapd; $mmsnmptrapdSeverityMapping
+   single: $mmsnmptrapdSeverityMapping
+
+See also
+--------
+See also :doc:`../../configuration/modules/mmsnmptrapd`.

doc/source/reference/parameters/mmsnmptrapd-tag.rst

@@ -0,0 +1,57 @@
+.. _param-mmsnmptrapd-tag:
+.. _mmsnmptrapd.parameter.module.tag:
+
+tag
+===
+
+.. index::
+   single: mmsnmptrapd; tag
+   single: tag
+
+.. summary-start
+
+Specifies the tag prefix that identifies messages for processing.
+
+.. summary-end
+
+This parameter applies to :doc:`../../configuration/modules/mmsnmptrapd`.
+
+:Name: tag
+:Scope: module
+:Type: word (see :doc:`../../rainerscript/constant_strings`)
+:Default: module=snmptrapd
+:Required?: no
+:Introduced: at least 5.8.1, possibly earlier
+
+Description
+-----------
+Tells the module which start string inside the tag to look for. The default is
+``snmptrapd``. Note that a slash (``/``) is automatically appended to this tag for
+matching. You should not include a trailing slash unless you specifically need
+to match a double slash. For example, setting ``tag="tag/"`` results in a
+check for ``tag//`` at the start of the tag field.
+
+Module usage
+------------
+.. _param-mmsnmptrapd-module-tag:
+.. _mmsnmptrapd.parameter.module.tag-usage:
+
+.. code-block:: rsyslog
+
+   module(load="mmsnmptrapd" tag="snmptrapd")
+
+Legacy names (for reference)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historic names/directives for compatibility. Do not use in new configs.
+
+.. _mmsnmptrapd.parameter.legacy.mmsnmptrapdtag:
+
+- $mmsnmptrapdTag — maps to tag (status: legacy)
+
+.. index::
+   single: mmsnmptrapd; $mmsnmptrapdTag
+   single: $mmsnmptrapdTag
+
+See also
+--------
+See also :doc:`../../configuration/modules/mmsnmptrapd`.