specdoc: Use mapper substitutions for descriptions

18 files changed, 75 insertions, 62 deletions

diff --git a/rtemsqual/specdoc.py b/rtemsqual/specdoc.py
index 43ecc613..cd525234 100644
--- a/rtemsqual/specdoc.py
+++ b/rtemsqual/specdoc.py
@@ -27,7 +27,7 @@
 from typing import Any, Dict, Iterator, Optional, Set, Tuple
 
 from rtemsqual.sphinxcontent import get_reference, get_section_label, \
-    SphinxContent
+    SphinxContent, SphinxMapper
 from rtemsqual.items import Item, ItemCache
 from rtemsqual.specverify import NAME
 
@@ -63,7 +63,12 @@ def _a_or_an(value: str) -> str:
     return "a"
 
 
+def _get_ref_specification_type(value: Any, key: str) -> str:
+    return get_reference(get_section_label(value[key], _SECTION_PREFIX))
+
+
 class _Documenter:
+    # pylint: disable=too-many-instance-attributes
     def __init__(self, item: Item, documenter_map: _DocumenterMap):
         self._name = item["spec-type"]
         self.section = item["spec-name"]
@@ -72,9 +77,17 @@ class _Documenter:
         self._item = item
         self._documenter_map = documenter_map
         self.used_by = set()  # type: Set[str]
+        self._mapper = SphinxMapper(item)
+        self._mapper.add_get_reference("spec", "/spec-name",
+                                       _get_ref_specification_type)
         assert self._name not in documenter_map
         documenter_map[self._name] = self
 
+    def _substitute(self, text: str) -> str:
+        if text:
+            return self._mapper.substitute(text)
+        return text
+
     def get_section_reference(self) -> str:
         """ Returns the section reference. """
         return get_reference(get_section_label(self.section, _SECTION_PREFIX))
@@ -142,14 +155,14 @@ class _Documenter:
                 content.wrap(
                     self.get_value_type_phrase("The attribute value", "shall",
                                                info["spec-type"]))
-                content.paste_and_add(info["description"])
+                content.paste_and_add(self._substitute(info["description"]))
 
     def document_dict(self, content: SphinxContent, _variant: str, shall: str,
                       info: Any) -> None:
         """ Documents an attribute set. """
         if shall == "may":
             content.paste("The value may be a set of attributes.")
-        content.paste_and_add(info["description"])
+        content.paste_and_add(self._substitute(info["description"]))
         has_explicit_attributes = len(info["attributes"]) > 0
         if has_explicit_attributes:
             required_attributes = info["required-attributes"]
@@ -184,20 +197,21 @@ class _Documenter:
                 "The attribute value", "shall",
                 info["generic-attributes"]["spec-type"])
             content.paste(type_phrase)
-            content.paste_and_add(info["generic-attributes"]["description"])
+            content.paste_and_add(
+                self._substitute(info["generic-attributes"]["description"]))
 
     def document_value(self, content: SphinxContent, variant: str, shall: str,
                        info: Any) -> None:
         """ Documents a value. """
         content.paste(self.get_value_type_phrase("The value", shall, variant))
-        content.paste_and_add(info["description"])
+        content.paste_and_add(self._substitute(info["description"]))
 
     def document_list(self, content: SphinxContent, _variant: str, shall: str,
                       info: Any) -> None:
         """ Documents a list value. """
         content.paste(
             self.get_list_phrase("The value", shall, info["spec-type"]))
-        content.paste_and_add(info["description"])
+        content.paste_and_add(self._substitute(info["description"]))
 
     def document_none(self, content: SphinxContent, _variant: str, shall: str,
                       _info: Any) -> None:
@@ -334,9 +348,9 @@ def document(config: dict, item_cache: ItemCache) -> None:
     documenter_map = {}  # type: _DocumenterMap
     root_item = item_cache[config["root-type"]]
     _create_str_documenter(
-        item_cache, "Name",
-        f"A string is a valid name if it matches with the ``{NAME.pattern}`` "
-        "regular expression.", documenter_map)
+        item_cache, "Name", "A string is a valid name if it matches with the "
+        f"``{NAME.pattern.replace('$', '$$')}`` regular expression.",
+        documenter_map)
     _create_str_documenter(
         item_cache, "UID",
         "The string shall be a valid absolute or relative item UID.",
diff --git a/rtemsqual/tests/spec-doc/root.yml b/rtemsqual/tests/spec-doc/root.yml
index 6be990a4..e96711e8 100644
--- a/rtemsqual/tests/spec-doc/root.yml
+++ b/rtemsqual/tests/spec-doc/root.yml
@@ -8,7 +8,8 @@ spec-example: null
 spec-info:
   bool:
     assert: true
-    description: null
+    description: |
+      A reference to ${.:/spec-name}.
   dict:
     attributes:
       type:
diff --git a/rtemsqual/tests/test_specdoc.py b/rtemsqual/tests/test_specdoc.py
index d07e2f1a..5ccd20f2 100644
--- a/rtemsqual/tests/test_specdoc.py
+++ b/rtemsqual/tests/test_specdoc.py
@@ -76,7 +76,7 @@ Root
 
 A value of this type shall be of one of the following variants:
 
-* The value may be a boolean.
+* The value may be a boolean. A reference to :ref:`SpecTypeRoot`.
 
 * The value may be a set of attributes. All explicitly defined attributes shall
   be specified. The following attributes are explicitly defined for this type:
diff --git a/spec/spec/appl-config-option-constraints.yml b/spec/spec/appl-config-option-constraints.yml
index 614d2e56..1e33835a 100644
--- a/spec/spec/appl-config-option-constraints.yml
+++ b/spec/spec/appl-config-option-constraints.yml
@@ -29,12 +29,12 @@ spec-info:
         description: |
           It shall be a list of constraints specific to this application
           configuration option.  For general constraints, use a link with the
-          :ref:`SpecTypeConstraintLinkRole` to a constraint item.
+          ${constraint-role:/spec-name} to a constraint item.
         spec-type: requirement-text-list
     description: |
       This set of attributes defines application configuration option
       constraints.  Additional constraints can be added through the links of
-      the item using the :ref:`SpecTypeConstraintLinkRole`.
+      the item using the ${constraint-role:/spec-name}.
     required-attributes: none
 spec-name: Application Configuration Option Constraint Set
 spec-type: appl-config-option-constraints
diff --git a/spec/spec/appl-config-option.yml b/spec/spec/appl-config-option.yml
index 2cb7d0e9..24af8d8d 100644
--- a/spec/spec/appl-config-option.yml
+++ b/spec/spec/appl-config-option.yml
@@ -24,9 +24,8 @@ spec-info:
           The description should be short and concentrate on the average case.
           All special cases, usage notes, constraints, error conditions,
           configuration dependencies, references, etc. should be described in
-          the notes.  The
-          :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items have
-          an attribute for constraints.
+          the notes.  The ${appl-config-option-value:/spec-name} items have an
+          attribute for constraints.
         spec-type: str
       index-entries:
         description: |
diff --git a/spec/spec/build-action-set-test-state.yml b/spec/spec/build-action-set-test-state.yml
index e07bd231..28aa0894 100644
--- a/spec/spec/build-action-set-test-state.yml
+++ b/spec/spec/build-action-set-test-state.yml
@@ -15,9 +15,10 @@ spec-info:
     generic-attributes:
       description: |
         The keys shall be test program names.  The names shall correspond to
-        the name of a :ref:`SpecTypeBuildTestItemType` item.  Due to the
-        processing order of items, there is no way to check if the name
-        specified by the attribute key is valid.
+        the name of a ${build-test-program:/spec-name} or
+        ${build-ada-test-program:/spec-name} item.  Due to the processing order
+        of items, there is no way to check if the name specified by the
+        attribute key is valid.
       spec-type: build-test-state
     required-attributes: all
 spec-name: Build Option Set Test State Action
diff --git a/spec/spec/build-action.yml b/spec/spec/build-action.yml
index 535fde3a..462e03f6 100644
--- a/spec/spec/build-action.yml
+++ b/spec/spec/build-action.yml
@@ -14,9 +14,9 @@ spec-info:
         description: |
           It shall be the name of a test program.  The action appends the
           action value to the ``CPPFLAGS`` of the test program.  The name shall
-          correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType`
-          item.  Due to the processing order of items, there is no way to check
-          if the name specified by the attribute value is valid.
+          correspond to the name of a ${build-test-program:/spec-name} item.
+          Due to the processing order of items, there is no way to check if the
+          name specified by the attribute value is valid.
         spec-type: str
       assert-aligned:
         description: |
@@ -150,7 +150,7 @@ spec-info:
       find-program:
         description: |
           The action tries to find the program specified by the action value.
-          Uses the ``${PATH}`` to find the program.  Returns the result of the
+          Uses the ``$${PATH}`` to find the program.  Returns the result of the
           find operation, e.g. a path to the program.
         spec-type: none
       find-tool:
@@ -214,8 +214,8 @@ spec-info:
         spec-type: none
       substitute:
         description: |
-          The action Performs a ``${VARIABLE}`` substitution on the action
-          value.  Use ``$$`` for a plain ``$`` character.
+          The action Performs a ``$${VARIABLE}`` substitution on the action
+          value.  Use ``$$$$`` for a plain ``$$`` character.
         spec-type: none
     description: |
       This set of attributes specifies a build option action.
diff --git a/spec/spec/build-ada-test-program.yml b/spec/spec/build-ada-test-program.yml
index 92272940..66a470f7 100644
--- a/spec/spec/build-ada-test-program.yml
+++ b/spec/spec/build-ada-test-program.yml
@@ -62,10 +62,10 @@ spec-info:
     description: |
       This set of attributes specifies an Ada test program executable to build.
       Test programs may use additional objects provided by
-      :ref:`SpecTypeBuildObjectsItemType` items.  Test programs have an
-      implicit ``enabled-by`` attribute value which is controlled by the option
-      action :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the test
-      state is set to ``exclude``, then the test program is not built.
+      ${build-objects:/spec-name} items.  Test programs have an implicit
+      ``enabled-by`` attribute value which is controlled by the option action
+      :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the test state
+      is set to ``exclude``, then the test program is not built.
     required-attributes: all
 spec-name: Build Ada Test Program Item Type
 spec-type: build-ada-test-program
diff --git a/spec/spec/build-config-file.yml b/spec/spec/build-config-file.yml
index 238fd787..f99bbca9 100644
--- a/spec/spec/build-config-file.yml
+++ b/spec/spec/build-config-file.yml
@@ -16,10 +16,10 @@ spec-info:
     attributes:
       content:
         description: |
-          It shall be the content of the configuration file. A ${VARIABLE}
+          It shall be the content of the configuration file. A $${VARIABLE}
           substitution is performed during the configure command execution
-          using the variables of the configuration set.  Use $$ for a plain $
-          character. To have all variables from sibling items available for
+          using the variables of the configuration set.  Use $$$$ for a plain
+          $$ character. To have all variables from sibling items available for
           substitution it is recommended to link them in the proper order.
         spec-type: str
       install-path:
diff --git a/spec/spec/build-include.yml b/spec/spec/build-include.yml
index c964906f..a3df76c5 100644
--- a/spec/spec/build-include.yml
+++ b/spec/spec/build-include.yml
@@ -13,13 +13,12 @@ spec-info:
       It shall be a path to header files.  The path is used by the C
       preprocessor to search for header files.  It succeeds the includes
       presented to the item by the build item context.  For an
-      :ref:`SpecTypeBuildGroupItemType` item the includes are visible to all
-      items referenced by the group item.  For :ref:`SpecTypeBuildBSPItemType`,
-      :ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`,
-      :ref:`SpecTypeBuildStartFileItemType`, and
-      :ref:`SpecTypeBuildTestProgramItemType` items the includes are only
-      visible to the sources specified by the item itself and they do not
-      propagate to referenced items.
+      ${build-group:/spec-name} item the includes are visible to all items
+      referenced by the group item.  For ${build-bsp:/spec-name},
+      ${build-objects:/spec-name}, ${build-library:/spec-name},
+      ${build-start-file:/spec-name}, and ${build-test-program:/spec-name}
+      items the includes are only visible to the sources specified by the item
+      itself and they do not propagate to referenced items.
 spec-name: Build Include Path
 spec-type: build-include
 type: spec
diff --git a/spec/spec/build-install-path.yml b/spec/spec/build-install-path.yml
index ead261be..03c1a829 100644
--- a/spec/spec/build-install-path.yml
+++ b/spec/spec/build-install-path.yml
@@ -11,7 +11,7 @@ spec-info:
   none: null
   str:
     description: |
-      It shall be the installation path of a :ref:`SpecTypeBuildTarget`.
+      It shall be the installation path of a ${build-target:/spec-name}.
 spec-name: Build Install Path
 spec-type: build-install-path
 type: spec
diff --git a/spec/spec/build-library.yml b/spec/spec/build-library.yml
index 8f3e1c5e..8cfe1afe 100644
--- a/spec/spec/build-library.yml
+++ b/spec/spec/build-library.yml
@@ -42,8 +42,8 @@ spec-info:
         spec-type: build-target
     description: |
       This set of attributes specifies a static library.  Library items may use
-      additional objects provided by :ref:`SpecTypeBuildObjectsItemType` items
-      through the build dependency links of the item.
+      additional objects provided by ${build-objects:/spec-name} items through
+      the build dependency links of the item.
     required-attributes: all
 spec-name: Build Library Item Type
 spec-type: build-library
diff --git a/spec/spec/build-test-program.yml b/spec/spec/build-test-program.yml
index 6afbcf28..29218cc0 100644
--- a/spec/spec/build-test-program.yml
+++ b/spec/spec/build-test-program.yml
@@ -53,10 +53,10 @@ spec-info:
     description: |
       This set of attributes specifies a test program executable to build.
       Test programs may use additional objects provided by
-      :ref:`SpecTypeBuildObjectsItemType` items.  Test programs have an
-      implicit ``enabled-by`` attribute value which is controlled by the option
-      action :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the test
-      state is set to ``exclude``, then the test program is not built.
+      ${build-objects:/spec-name} items.  Test programs have an implicit
+      ``enabled-by`` attribute value which is controlled by the option action
+      :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the test state
+      is set to ``exclude``, then the test program is not built.
     required-attributes: all
 spec-name: Build Test Program Item Type
 spec-type: build-test-program
diff --git a/spec/spec/interface-container.yml b/spec/spec/interface-container.yml
index 8106ea06..9f59b8ec 100644
--- a/spec/spec/interface-container.yml
+++ b/spec/spec/interface-container.yml
@@ -16,9 +16,9 @@ spec-info:
     attributes: {}
     description: |
       Items of this type specify an interface container.  The item shall have
-      exactly one link with the :ref:`SpecTypeInterfacePlacementLinkRole` to an
-      :ref:`SpecTypeInterfaceDomainItemType` item.  This link defines the
-      interface domain of the container.
+      exactly one link with the ${interface-placement:/spec-name} to an
+      ${interface-domain:/spec-name} item.  This link defines the interface
+      domain of the container.
     required-attributes: all
 spec-name: Interface Container Item Type
 spec-type: interface-container
diff --git a/spec/spec/interface-domain.yml b/spec/spec/interface-domain.yml
index 327b05ba..0ea33efa 100644
--- a/spec/spec/interface-domain.yml
+++ b/spec/spec/interface-domain.yml
@@ -24,9 +24,9 @@ spec-info:
         spec-type: str
     description: |
       This set of attributes specifies an interface domain.  Items of the types
-      :ref:`SpecTypeInterfaceContainerItemType` and
-      :ref:`SpecTypeInterfaceHeaderFileItemType` are placed into domains
-      through links with the :ref:`SpecTypeInterfacePlacementLinkRole`.
+      ${interface-container:/spec-name} and ${interface-header-file:/spec-name}
+      are placed into domains through links with the
+      ${interface-placement:/spec-name}.
     required-attributes: all
 spec-name: Interface Domain Item Type
 spec-type: interface-domain
diff --git a/spec/spec/interface-forward-declaration.yml b/spec/spec/interface-forward-declaration.yml
index c21da0a5..de6e1562 100644
--- a/spec/spec/interface-forward-declaration.yml
+++ b/spec/spec/interface-forward-declaration.yml
@@ -16,9 +16,9 @@ spec-info:
     attributes: {}
     description: |
       Items of this type specify a forward declaration.  The item shall have
-      exactly one link with the :ref:`SpecTypeInterfaceTargetLinkRole` to an
-      :ref:`SpecTypeInterfaceCompoundItemType` item.  This link defines the
-      type declared by the forward declaration.
+      exactly one link with the ${interface-target:/spec-name} to an
+      ${interface-compound:/spec-name} item.  This link defines the type
+      declared by the forward declaration.
     required-attributes: all
 spec-name: Interface Forward Declaration Item Type
 spec-type: interface-forward-declaration
diff --git a/spec/spec/interface-header-file.yml b/spec/spec/interface-header-file.yml
index 105e441d..f7965150 100644
--- a/spec/spec/interface-header-file.yml
+++ b/spec/spec/interface-header-file.yml
@@ -26,9 +26,9 @@ spec-info:
         spec-type: str
     description: |
       This set of attributes specifies a header file.  The item shall have
-      exactly one link with the :ref:`SpecTypeInterfacePlacementLinkRole` to an
-      :ref:`SpecTypeInterfaceDomainItemType` item.  This link defines the
-      interface domain of the header file.
+      exactly one link with the ${interface-placement:/spec-name} to an
+      ${interface-domain:/spec-name} item.  This link defines the interface
+      domain of the header file.
     required-attributes: all
 spec-name: Interface Header File Item Type
 spec-type: interface-header-file
diff --git a/spec/spec/requirement-validation.yml b/spec/spec/requirement-validation.yml
index d021896f..453d6ca0 100644
--- a/spec/spec/requirement-validation.yml
+++ b/spec/spec/requirement-validation.yml
@@ -16,8 +16,7 @@ spec-info:
     attributes:
       method:
         description: |
-          Validation by test is done through :ref:`SpecTypeTestCaseItemType`
-          items.
+          Validation by test is done through ${test-case:/spec-name} items.
         spec-type: requirement-validation-method
       text:
         description: |
@@ -28,7 +27,7 @@ spec-info:
             met, by analysing static properties of the software product.
 
           * *By inspection*: A statement shall be provided how the requirement
-            is met, by inspection of the :term:`source code`.
+            is met, by inspection of the ${/glos/term/sourcecode:/term}.
 
           * *By review of design*: A rationale shall be provided to demonstrate
             how the requirement is satisfied implicitly by the software design.
@@ -36,7 +35,7 @@ spec-info:
     description: |
       This set of attributes provides a requirement validation evidence.  The
       item shall have exactly one link to the validated requirement with the
-      :ref:`SpecTypeRequirementValidationLinkRole`.
+      ${requirement-validation-role:/spec-name}.
     required-attributes: all
 spec-name: Requirement Validation Item Type
 spec-type: requirement-validation