specdoc: Use mapper substitutions for descriptions

15 files changed, 49 insertions, 51 deletions

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