[TASK] Improve documentation for confvals

Documentation/WritingReST/CheatSheet.rst

@@ -532,11 +532,13 @@ Source:
 :ref:`Configuration values <rest-confval>` (confval)
 ====================================================
 
+See also: :ref:`rest-confval`.
+
 **How it looks:**
 
 ..  confval:: title
-
-    :Required: true
+    :name: unique-title
+    :required: true
     :type: string or LLL reference
     :Scope: Display
     :Path: $GLOBALS > TCA > [table] > columns > [field]
@@ -548,8 +550,8 @@ Source:
 ..  code-block:: rst
 
     ..  confval:: title
-
-        :Required: true
+        :name: unique-title
+        :required: true
         :type: string or LLL reference
         :Scope: Display
         :Path: $GLOBALS > TCA > [table] > columns > [field]

Documentation/WritingReST/Reference/Code/Confval.rst

@@ -19,7 +19,6 @@ Using the :rst:`confval` directive has several benefits:
 
 *   The display is independent of the language of the configuration value
     – for example, unlike :ref:`PHP domain <rest-phpdomain>`.
-*   The values appear automatically in the generated keyword index.
 *   You can link directly to configuration values.
 *   The content element presents the data and its attributes in a
     well-structured way.
@@ -28,49 +27,175 @@ Each configuration value name may only be used once. In large references
 with different contexts you can define individual configuration schemas for
 each context.
 
+..  contents:: Table of contents
+
+..  _rest-confval-examples:
+
 Examples
 ========
 
 Required configuration value
 ----------------------------
 
 ..  confval:: label
-
-    :Required: true
+    :name: some-unique-label
+    :required: true
     :type: string or LLL reference
-    :Scope: Display
-    :Path: $GLOBALS > TCA > [table] > columns > [field]
 
     The name of the field as shown in the form.
 
 ..  code-block:: rst
 
     ..  confval:: label
-
-        :Required: true
+        :name: some-unique-label
+        :required: true
         :type: string or LLL reference
-        :Scope: Display
-        :Path: $GLOBALS > TCA > [table] > columns > [field]
 
         The name of the field as shown in the form.
 
-Configuration value with default value
---------------------------------------
+Example: Configuration value with default value adn custom parameter
+--------------------------------------------------------------------
 
 ..  confval:: fileCreateMask
-
+    :name: some-unique-fileCreateMask
     :type: text
-    :Default: 0664
-    :Path: $GLOBALS > TYPO3_CONF_VARS > SYS
+    :default: 0664
+    :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`
 
     File mode mask for Unix file systems (when files are uploaded/created).
 
 ..  code-block:: rst
 
     ..  confval:: fileCreateMask
-
+        :name: some-unique-fileCreateMask
         :type: text
-        :Default: 0664
-        :Path: $GLOBALS > TYPO3_CONF_VARS > SYS
+        :default: 0664
+        :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`
 
         File mode mask for Unix file systems (when files are uploaded/created).
+
+Confval directive API
+=====================
+
+Each confval must have at least a title. If that title is not unique within
+the manual the confval must also have the `:name:` attribute, followed by a
+unique name. Names are case-insensitive and convert all special signs into a dash.
+
+..  code-block:: rst
+
+    ..  confval:: [title]
+        :name: [unique-name]
+
+There are several reserved attributes:
+
+`:type:`
+    The type of the configuration value.
+`:default:`
+    The default value
+`:required:`
+    Is the configuration value required.
+`:name:`
+    The unique identifier, reserved internally by reStructuredText.
+`:class:`
+    Reserved internally by reStructuredText.
+`noindex`
+    Exclude from being able to be referenced and form indexes. Useful for
+    confvals that should be repeatedly displayed in different locations.
+
+All other attributes are output the way they are written:
+
+..  confval:: someSetting
+    :name: some-unique-someSetting
+    :type: string
+    :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['someSetting']`
+    :Some value: Lorem Ipsum
+
+    Lorem Ipsum Dolor sit
+
+..  code-block:: rst
+
+    ..  confval:: fileCreateMask
+        :name: some-unique-someSetting
+        :type: string
+        :default: 0664
+        :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`
+
+        Lorem Ipsum Dolor sit
+
+Confval menu
+============
+
+Confval entries can be listed in a special menu type, the confval-menu directive.
+
+If you put the directive somewhere on the page it will list all confvals that
+can be found on that page:
+
+..  confval-menu::
+    :display: table
+    :type:
+    :default:
+    :exclude: confval-1, confval-2
+
+..  code-block:: rst
+
+    ..  confval-menu::
+        :display: table
+        :type:
+        :default:
+        :exclude: confval-1, confval-2
+
+
+If you use a confval menu together with nested confvals it will only list
+its child confvals. This is usefull if you have several groups of confvals on
+the same page and want to list them in separate menues:
+
+..  confval-menu::
+    :display: table
+    :type:
+
+    ..  confval:: confval-1
+        :type: string
+
+        Some Description
+
+    ..  confval:: confval-2
+        :type: int
+        :default: 'Hello World'
+
+        Some Description
+
+..  code-block:: rst
+
+    ..  confval-menu::
+        :display: table
+        :type:
+
+        ..  confval:: confval-1
+            :type: string
+
+            Some Description
+
+        ..  confval:: confval-2
+            :type: int
+            :default: 'Hello World'
+
+            Some Description
+
+Confval-menu directive API
+==========================
+
+The confval-menu directive has the following options:
+
+`:display:`
+    'table', 'list', 'tree': Different display forms, just try them out
+`:name:`
+    Reserved by reStructuredText
+`:class:`
+    Reserved by reStructuredText
+`:exclude-noindex:`
+    Exclude all confvals that have the option `:noindex:`.
+`:exclude:`
+    Comma separated list of all identifiers / titles of convals to be excluded.
+
+All other parameters can be used to trigger listing of the property of the exact
+same name.