spec: Canonicalize specification of specification

41 files changed, 141 insertions, 157 deletions

diff --git a/spec/spec/appl-config-group.yml b/spec/spec/appl-config-group.yml
index 746cc5d2..03e62449 100644
--- a/spec/spec/appl-config-group.yml
+++ b/spec/spec/appl-config-group.yml
@@ -16,22 +16,20 @@ spec-info:
     attributes:
       description:
         description: |
-          This mandatory attribute shall be the description of the application
-          configuration group.
+          It shall be the description of the application configuration group.
         spec-type: str
       name:
         description: |
-          This mandatory attribute defines the application configuration group
-          human readable name.
+          It shall be human readable name of the application configuration
+          group.
         spec-type: str
       text:
         description: |
-          This mandatory attribute states the requirement for the application
-          configuration group.
+          It shall state the requirement for the application configuration
+          group.
         spec-type: requirement-text
     description: |
-      This set of attributes specifies application configuration group
-      specification items.
+      This set of attributes specifies an application configuration group.
     required-attributes: all
 spec-name: Application Configuration Group Item Type
 spec-type: appl-config-group
diff --git a/spec/spec/appl-config-option-constraints.yml b/spec/spec/appl-config-option-constraints.yml
index 13024f91..614d2e56 100644
--- a/spec/spec/appl-config-option-constraints.yml
+++ b/spec/spec/appl-config-option-constraints.yml
@@ -12,18 +12,24 @@ spec-info:
     attributes:
       max:
         description: |
-          This attribute defines the maximum value.
+          It shall be the maximum value of the application configuration
+          option.
         spec-type: int-or-str
       min:
         description: |
-          This attribute defines the minimum value.
+          It shall be the minimum value of the application configuration
+          option.
         spec-type: int-or-str
       set:
         description: |
-          This attribute defines a set of valid values.
+          It shall be the set of valid values for the application configuration
+          option.
         spec-type: list-int-or-str
       texts:
-        description: null
+        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.
         spec-type: requirement-text-list
     description: |
       This set of attributes defines application configuration option
diff --git a/spec/spec/appl-config-option-feature-enable.yml b/spec/spec/appl-config-option-feature-enable.yml
index b93eac82..024bac46 100644
--- a/spec/spec/appl-config-option-feature-enable.yml
+++ b/spec/spec/appl-config-option-feature-enable.yml
@@ -15,8 +15,8 @@ spec-info:
   dict:
     attributes: {}
     description: |
-      This set of attributes specifies application configuration feature enable
-      option specification items.
+      This set of attributes specifies an application configuration feature
+      enable option.
     required-attributes: all
 spec-name: Application Configuration Feature Enable Option Item Type
 spec-type: appl-config-option-feature-enable
diff --git a/spec/spec/appl-config-option-feature.yml b/spec/spec/appl-config-option-feature.yml
index da70e114..b4ecdcfa 100644
--- a/spec/spec/appl-config-option-feature.yml
+++ b/spec/spec/appl-config-option-feature.yml
@@ -16,12 +16,12 @@ spec-info:
     attributes:
       default:
         description: |
-          This mandatory attribute shall describe what happens if the
-          configuration option is undefined.
+          It shall describe what happens if the configuration option is
+          undefined.
         spec-type: str
     description: |
-      This set of attributes specifies application configuration feature option
-      specification items.
+      This set of attributes specifies an application configuration feature
+      option.
     required-attributes: all
 spec-name: Application Configuration Feature Option Item Type
 spec-type: appl-config-option-feature
diff --git a/spec/spec/appl-config-option-name.yml b/spec/spec/appl-config-option-name.yml
index bc224b47..2916dfcf 100644
--- a/spec/spec/appl-config-option-name.yml
+++ b/spec/spec/appl-config-option-name.yml
@@ -12,7 +12,7 @@ spec-info:
     assert:
     - re: ^(CONFIGURE_|BSP_)[A-Z0-9_]+$
     description: |
-      This attribute value defines an application configuration option name.
+      It shall be the name of an application configuration option.
 spec-name: Application Configuration Option Name
 spec-type: appl-config-option-name
 type: spec
diff --git a/spec/spec/appl-config-option-value.yml b/spec/spec/appl-config-option-value.yml
index 783df269..7842d2bb 100644
--- a/spec/spec/appl-config-option-value.yml
+++ b/spec/spec/appl-config-option-value.yml
@@ -19,18 +19,16 @@ spec-info:
   dict:
     attributes:
       constraints:
-        description: |
-          This mandatory attribute shall list the constraints of the
-          configuration option value.
+        description: null
         spec-type: appl-config-option-constraints
       default-value:
         description: |
-          This mandatory attribute shall describe the default value of the
+          It shall shall describe the default value of the application
           configuration option.
         spec-type: int-or-str
     description: |
       This set of attributes specifies application configuration initializer or
-      integer option specification items.
+      integer option.
     required-attributes: all
 spec-name: Application Configuration Value Option Item Type
 spec-type: appl-config-option-value
diff --git a/spec/spec/appl-config-option.yml b/spec/spec/appl-config-option.yml
index bba2d55f..2cb7d0e9 100644
--- a/spec/spec/appl-config-option.yml
+++ b/spec/spec/appl-config-option.yml
@@ -16,38 +16,38 @@ spec-info:
     attributes:
       appl-config-option-type:
         description: |
-          This mandatory attribute shall be the application configuration
-          option type.
+          It shall be the application configuration option type.
         spec-type: name
       description:
         description: |
-          This mandatory attribute shall be the description of the application
-          configuration option.
+          It shall be the description of the application configuration option.
+          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.
         spec-type: str
       index-entries:
         description: |
-          This mandatory attribute defines additional application configuration
-          option document index entries.  The application configuration option
-          name is automatically added to the document index.
+          It shall be a list of additional application configuration option
+          document index entries.  The application configuration option name is
+          automatically added to the document index.
         spec-type: list-str
       name:
-        description: |
-          This mandatory attribute defines the application configuration option
-          name.
+        description: null
         spec-type: appl-config-option-name
       notes:
         description: |
-          This mandatory attribute shall be the notes to the application
-          configuration option.
+          It shall be the notes to the application configuration option.
         spec-type: optional-str
       text:
         description: |
-          This mandatory attribute states the requirement for the application
-          configuration option.
+          It shall state the requirement for the application configuration
+          option.
         spec-type: requirement-text
     description: |
-      This set of attributes specifies application configuration option
-      specification items.
+      This set of attributes specifies an application configuration option.
     required-attributes: all
 spec-name: Application Configuration Option Item Type
 spec-type: appl-config-option
diff --git a/spec/spec/build-asflag.yml b/spec/spec/build-asflag.yml
index 4adfbc7e..ec7ede8f 100644
--- a/spec/spec/build-asflag.yml
+++ b/spec/spec/build-asflag.yml
@@ -11,7 +11,7 @@ spec-info:
   str:
     description: |
       It shall be an option for the assembler.  The options are used to
-      compile the sources of this item.  The options defined by this attribute
+      assemble the sources of this item.  The options defined by this attribute
       succeed the options presented to the item by the build item context.
 spec-name: Build Assembler Option
 spec-type: build-asflag
diff --git a/spec/spec/build-config-file.yml b/spec/spec/build-config-file.yml
index 063ad7dd..238fd787 100644
--- a/spec/spec/build-config-file.yml
+++ b/spec/spec/build-config-file.yml
@@ -16,12 +16,11 @@ spec-info:
     attributes:
       content:
         description: |
-          This mandatory attribute defines 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 substitution it is recommended to link them in the
-          proper order.
+          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
+          substitution it is recommended to link them in the proper order.
         spec-type: str
       install-path:
         description: null
@@ -31,8 +30,8 @@ spec-info:
         spec-type: build-target
     description: |
       This set of attributes specifies a configuration file placed in the build
-      tree.  The files are generated during the configure command execution and
-      are placed in the build tree.
+      tree.  The configuration file is generated during the configure command
+      execution and are placed in the build tree.
     required-attributes: all
 spec-name: Build Configuration File Item Type
 spec-type: build-config-file
diff --git a/spec/spec/build-config-header.yml b/spec/spec/build-config-header.yml
index e622a363..98a332a2 100644
--- a/spec/spec/build-config-header.yml
+++ b/spec/spec/build-config-header.yml
@@ -29,11 +29,11 @@ spec-info:
         description: null
         spec-type: build-target
     description: |
-      This set of attributes specifies configuration header files.  The
-      configuration header files are generated during configure command
-      execution and are placed in the build tree.  All collected configuration
-      defines are written to the configuration header file during the configure
-      command execution.  To have all configuration defines from sibling items
+      This set of attributes specifies configuration header file.  The
+      configuration header file is generated during configure command execution
+      and is placed in the build tree.  All collected configuration defines are
+      written to the configuration header file during the configure command
+      execution.  To have all configuration defines from sibling items
       available it is recommended to link them in the proper order.
     required-attributes: all
 spec-name: Build Configuration Header Item Type
diff --git a/spec/spec/build-cppflag.yml b/spec/spec/build-cppflag.yml
index d22c5594..600df752 100644
--- a/spec/spec/build-cppflag.yml
+++ b/spec/spec/build-cppflag.yml
@@ -11,8 +11,9 @@ spec-info:
   str:
     description: |
       It shall be an option for the C preprocessor.  The options are used to
-      compile the sources of this item.  The options defined by this attribute
-      succeed the options presented to the item by the build item context.
+      preprocess the sources of this item.  The options defined by this
+      attribute succeed the options presented to the item by the build item
+      context.
 spec-name: Build C Preprocessor Option
 spec-type: build-cppflag
 type: spec
diff --git a/spec/spec/build-group.yml b/spec/spec/build-group.yml
index 209eb2fd..f25365bb 100644
--- a/spec/spec/build-group.yml
+++ b/spec/spec/build-group.yml
@@ -22,8 +22,8 @@ spec-info:
         spec-type: build-install-list
       ldflags:
         description: |
-          This mandatory attribute defines a list of options for the linker.
-          They are used to link programs referenced by this item.
+          It shall be a list of options for the linker.  They are used to link
+          executables referenced by this item.
         spec-type: list-str
       use-after:
         description: null
diff --git a/spec/spec/build-install.yml b/spec/spec/build-install.yml
index 4037c8b7..84e5f66b 100644
--- a/spec/spec/build-install.yml
+++ b/spec/spec/build-install.yml
@@ -12,16 +12,16 @@ spec-info:
     attributes:
       destination:
         description: |
-          This mandatory attribute defines the install destination directory.
+          It shall be the install destination directory.
         spec-type: str
       source:
         description: |
-          This mandatory attribute defines the source files to be installed in
-          the destination directory.  The path to a source file shall be
-          relative to the directory of the :file:`wscript`.
+          It shall be the list of source files to be installed in the
+          destination directory.  The path to a source file shall be relative
+          to the directory of the :file:`wscript`.
         spec-type: list-str
     description: |
-      This set of attributes specifies artefacts installed by a build item.
+      This set of attributes specifies files installed by a build item.
     required-attributes: all
 spec-name: Build Install Directive
 spec-type: build-install
diff --git a/spec/spec/build-option-name.yml b/spec/spec/build-option-name.yml
index 08831de0..c62b6161 100644
--- a/spec/spec/build-option-name.yml
+++ b/spec/spec/build-option-name.yml
@@ -12,7 +12,7 @@ spec-info:
     assert:
     - re: ^[a-zA-Z_][a-zA-Z0-9_]*$
     description: |
-      It shall be the name of the option.
+      It shall be the name of the build option.
 spec-name: Build Option Name
 spec-type: build-option-name
 type: spec
diff --git a/spec/spec/build-script.yml b/spec/spec/build-script.yml
index 32c4fc6a..4ae7d2c8 100644
--- a/spec/spec/build-script.yml
+++ b/spec/spec/build-script.yml
@@ -76,7 +76,8 @@ spec-info:
         description: null
         spec-type: build-use-before-list
     description: |
-      This set of attributes specifies build scripts.
+      This set of attributes specifies a build script.  The optional attributes
+      may be required by commands executed through the scripts.
     required-attributes:
     - do-build
     - do-configure
diff --git a/spec/spec/build-start-file.yml b/spec/spec/build-start-file.yml
index 35d64213..b942c355 100644
--- a/spec/spec/build-start-file.yml
+++ b/spec/spec/build-start-file.yml
@@ -33,8 +33,8 @@ spec-info:
         description: null
         spec-type: build-target
     description: |
-      This set of attributes specifies a start file to build which is used to
-      link an executable.
+      This set of attributes specifies a start file to build.  A start file is
+      used to link an executable.
     required-attributes: all
 spec-name: Build Start File Item Type
 spec-type: build-start-file
diff --git a/spec/spec/build.yml b/spec/spec/build.yml
index 1bdc5639..d91deb8e 100644
--- a/spec/spec/build.yml
+++ b/spec/spec/build.yml
@@ -16,7 +16,7 @@ spec-info:
     attributes:
       build-type:
         description: |
-          This mandatory attribute defines the build type.
+          It shall be the build item type.
         spec-type: name
     description: |
       This set of attributes specifies a build item.
diff --git a/spec/spec/glossary-group.yml b/spec/spec/glossary-group.yml
index 24863b2e..305d6152 100644
--- a/spec/spec/glossary-group.yml
+++ b/spec/spec/glossary-group.yml
@@ -16,11 +16,11 @@ spec-info:
     attributes:
       name:
         description: |
-          It defines the human readable name of the glossary group.
+          It shall be the human readable name of the glossary group.
         spec-type: str
       text:
         description: |
-          It states the requirement for the glossary group.
+          It shall state the requirement for the glossary group.
         spec-type: str
     description: |
       This set of attributes specifies a glossary group.
diff --git a/spec/spec/glossary-term.yml b/spec/spec/glossary-term.yml
index d1c10b5b..c6493fc8 100644
--- a/spec/spec/glossary-term.yml
+++ b/spec/spec/glossary-term.yml
@@ -16,11 +16,11 @@ spec-info:
     attributes:
       term:
         description: |
-          It names the glossary term.
+          It shall be the glossary term.
         spec-type: str
       text:
         description: |
-          It gives the definition of the glossary term.
+          It shall be the definition of the glossary term.
         spec-type: str
     description: |
       This set of attributes specifies a glossary term.
diff --git a/spec/spec/glossary.yml b/spec/spec/glossary.yml
index 847851ba..d3a9e134 100644
--- a/spec/spec/glossary.yml
+++ b/spec/spec/glossary.yml
@@ -16,10 +16,10 @@ spec-info:
     attributes:
       glossary-type:
         description: |
-          It defines the glossary item type.
+          It shall be the glossary item type.
         spec-type: name
     description: |
-      This set of attributes specifies glossary items.
+      This set of attributes specifies a glossary item.
     required-attributes: all
 spec-name: Glossary Item Type
 spec-type: glossary
diff --git a/spec/spec/interface-forward-declaration.yml b/spec/spec/interface-forward-declaration.yml
index ae8302ea..853d8cc7 100644
--- a/spec/spec/interface-forward-declaration.yml
+++ b/spec/spec/interface-forward-declaration.yml
@@ -16,8 +16,8 @@ spec-info:
     attributes:
       interface-target:
         description: |
-          It shall be the UID of the interface target which defines forward
-          declaration.
+          It shall be the UID of the interface target type declared by the
+          forward declaration.
         spec-type: uid
     description: |
       This set of attributes specifies a forward declaration.
diff --git a/spec/spec/interface-include.yml b/spec/spec/interface-include.yml
index 16b68e95..30524426 100644
--- a/spec/spec/interface-include.yml
+++ b/spec/spec/interface-include.yml
@@ -16,8 +16,8 @@ spec-info:
     attributes:
       enabled-by:
         description: |
-          This mandatory attribute defines under which conditions the interface
-          container is included.
+          It shall define under which conditions the interface container is
+          included.
         spec-type: enabled-by
     description: |
       It defines the interface include role of links and is used to indicate
diff --git a/spec/spec/interface.yml b/spec/spec/interface.yml
index 15acaae0..95b6a3cb 100644
--- a/spec/spec/interface.yml
+++ b/spec/spec/interface.yml
@@ -16,10 +16,10 @@ spec-info:
     attributes:
       interface-type:
         description: |
-          This mandatory attribute defines the interface type.
+          It shall be the interface item type.
         spec-type: name
     description: |
-      This set of attributes specifies interface specification items.
+      This set of attributes specifies an interface specification item.
     required-attributes: all
 spec-name: Interface Item Type
 spec-type: interface
diff --git a/spec/spec/link.yml b/spec/spec/link.yml
index 748ce840..bd6aff8d 100644
--- a/spec/spec/link.yml
+++ b/spec/spec/link.yml
@@ -12,14 +12,15 @@ spec-info:
     attributes:
       role:
         description: |
-          This mandatory attribute defines the role of the link.
+          It shall be the role of the link.
         spec-type: name
       uid:
         description: |
-          This mandatory attribute defines the link target item UID.
+          It shall be the absolute or relative UID of the link target item.
         spec-type: uid
     description: |
-      This attribute value shall a link to a specification item.
+      This set of attributes specifies a link from one specification item to
+      another specification item.
     required-attributes: all
 spec-name: Link
 spec-type: link
diff --git a/spec/spec/links.yml b/spec/spec/links.yml
index 77092dfa..665f9135 100644
--- a/spec/spec/links.yml
+++ b/spec/spec/links.yml
@@ -5,13 +5,12 @@ enabled-by: true
 links:
 - role: spec-member
   uid: root
-spec-description: |
-  This attribute value shall be a list of links to specification items.
+spec-description: null
 spec-example: null
 spec-info:
   list:
     description: null
     spec-type: link
-spec-name: Item Links Type
+spec-name: Link List
 spec-type: links
 type: spec
diff --git a/spec/spec/requirement-functional.yml b/spec/spec/requirement-functional.yml
index f68aef19..46ed7cd0 100644
--- a/spec/spec/requirement-functional.yml
+++ b/spec/spec/requirement-functional.yml
@@ -16,7 +16,7 @@ spec-info:
     attributes:
       functional-type:
         description: |
-          This mandatory attribute defines the functional type of the requirement.
+          It shall be the functional type of the requirement.
         spec-type: requirement-functional-type
     description: |
       This set of attributes specifies a functional requirement.
diff --git a/spec/spec/requirement-non-functional.yml b/spec/spec/requirement-non-functional.yml
index 11abaf57..410446bf 100644
--- a/spec/spec/requirement-non-functional.yml
+++ b/spec/spec/requirement-non-functional.yml
@@ -16,8 +16,7 @@ spec-info:
     attributes:
       non-functional-type:
         description: |
-          This mandatory attribute defines the non-functional type of the
-          requirement.
+          It shall be the non-functional type of the requirement.
         spec-type: requirement-non-functional-type
     description: |
       This set of attributes specifies a non-functional requirement.
diff --git a/spec/spec/requirement.yml b/spec/spec/requirement.yml
index 1bb145af..fbbd5b3a 100644
--- a/spec/spec/requirement.yml
+++ b/spec/spec/requirement.yml
@@ -16,7 +16,7 @@ spec-info:
     attributes:
       requirement-type:
         description: |
-          This mandatory attribute defines the requirement type.
+          It shall be the requirement item type.
         spec-type: name
       rationale:
         description: |
@@ -25,7 +25,7 @@ spec-info:
         spec-type: optional-str
       text:
         description: |
-          This mandatory attribute defines the requirement text.
+          It shall state the requirement.
         spec-type: requirement-text
     description: |
       This set of attributes specifies a requirement.
diff --git a/spec/spec/root.yml b/spec/spec/root.yml
index 93fd3a9b..42bca776 100644
--- a/spec/spec/root.yml
+++ b/spec/spec/root.yml
@@ -10,26 +10,22 @@ spec-info:
     attributes:
       SPDX-License-Identifier:
         description: |
-          This mandatory attribute defines the license of this item.
+          It shall be the license of the item.
         spec-type: spdx-license-identifier
       copyrights:
         description: |
-          This mandatory attribute defines the copyright holders and copyright
-          information of this item.
+          It shall be the list of copyright statements of the item.
         spec-type: copyrights
       enabled-by:
         description: |
-          This mandatory attribute defines the conditions under which this item
-          is enabled.
+          It shall define the conditions under which the item is enabled.
         spec-type: enabled-by
       links:
-        description: |
-          This mandatory attribute defines the links of this items to other
-          items.
+        description: null
         spec-type: links
       type:
         description: |
-          This mandatory attribute defines the type of this item.
+          It shall be the item type.
         spec-type: name
     description: |
       This is the root specification item type.
diff --git a/spec/spec/spdx-license-identifier.yml b/spec/spec/spdx-license-identifier.yml
index 380b61bc..21899ca8 100644
--- a/spec/spec/spdx-license-identifier.yml
+++ b/spec/spec/spdx-license-identifier.yml
@@ -14,7 +14,7 @@ spec-info:
     - eq: BSD-2-Clause
     - eq: CC-BY-SA-4.0
     description: |
-      This attribute value defines the license of this item expressed though an
+      This attribute value defines the license of the item expressed though an
       SPDX License Identifier.
 spec-name: SPDX License Identifier
 spec-type: spdx-license-identifier
diff --git a/spec/spec/spec-attribute-value.yml b/spec/spec/spec-attribute-value.yml
index f824de54..6b318790 100644
--- a/spec/spec/spec-attribute-value.yml
+++ b/spec/spec/spec-attribute-value.yml
@@ -12,16 +12,14 @@ spec-info:
     attributes:
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          attribute.
+          It shall be the description of the attribute value.
         spec-type: optional-str
       spec-type:
         description: |
-          This mandatory attribute defines the specification type of the
-          specified attribute.
+          It shall be the specification type of the attribute value.
         spec-type: name
     description: |
-      This attribute set specifies an attribute value.
+      This set of attributes specifies an attribute value.
     required-attributes: all
 spec-name: Attribute Value Specification
 spec-type: spec-attribute-value
diff --git a/spec/spec/spec-bool.yml b/spec/spec/spec-bool.yml
index 12f932b6..d491abe5 100644
--- a/spec/spec/spec-bool.yml
+++ b/spec/spec/spec-bool.yml
@@ -22,8 +22,7 @@ spec-info:
         spec-type: bool
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          boolean value.
+          It shall be the description of the specified boolean value.
         spec-type: optional-str
     description: |
       This attribute set specifies a boolean value.
diff --git a/spec/spec/spec-dict.yml b/spec/spec/spec-dict.yml
index 411d0370..26096b8c 100644
--- a/spec/spec/spec-dict.yml
+++ b/spec/spec/spec-dict.yml
@@ -12,23 +12,21 @@ spec-info:
     attributes:
       attributes:
         description: |
-          This mandatory attribute defines the explicitly defined attributes of
-          the specified attribute set.
+          It shall be the specification of the set of explicitly defined
+          attributes.
         spec-type: spec-attributes
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          attribute set.
+          It shall be the description of the attribute set.
         spec-type: optional-str
       generic-attributes:
         description: |
-          This optional attribute defines the generic attributes of the
-          specified attribute set.
+          It shall be the specification of the generic attributes of the
+          attribute set.
         spec-type: spec-generic-attributes
       required-attributes:
         description: |
-          This mandatory attribute defines the required attributes of the
-          specified attribute set.
+          It shall be the set of required attributes of the attribute set.
         spec-type: spec-required-attributes
     description: |
       This set of attributes specifies a set of attributes.
diff --git a/spec/spec/spec-float.yml b/spec/spec/spec-float.yml
index 1b0e4925..91cff502 100644
--- a/spec/spec/spec-float.yml
+++ b/spec/spec/spec-float.yml
@@ -19,11 +19,10 @@ spec-info:
         spec-type: spec-assert-float
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          floating-point value.
+          It shall be the description of the specified floating-point value.
         spec-type: optional-str
     description: |
-      This attribute set specifies a floating-point value.
+      This set of attributes specifies a floating-point value.
     required-attributes:
     - description
 spec-name: Floating-Point Value Specification
diff --git a/spec/spec/spec-generic-attributes.yml b/spec/spec/spec-generic-attributes.yml
index 71fb976d..35a9010f 100644
--- a/spec/spec/spec-generic-attributes.yml
+++ b/spec/spec/spec-generic-attributes.yml
@@ -12,13 +12,11 @@ spec-info:
     attributes:
       description:
         description: |
-          This mandatory attribute shall be the description of the generic
-          attributes.
+          It shall be the description of the generic attributes.
         spec-type: optional-str
       spec-type:
         description: |
-          This mandatory attribute defines the specification type of the
-          generic attribute values.
+          It shall be the specification type of the generic attribute values.
         spec-type: name
     description: |
       This set of attributes specifies generic attributes.  Generic attributes
diff --git a/spec/spec/spec-info.yml b/spec/spec/spec-info.yml
index 18ecf5c5..e6ef4fa8 100644
--- a/spec/spec/spec-info.yml
+++ b/spec/spec/spec-info.yml
@@ -12,34 +12,34 @@ spec-info:
     attributes:
       bool:
         description: |
-          This attribute specifies a boolean value.
+          It shall specify a boolean value.
         spec-type: spec-bool
       dict:
         description: |
-          This attribute specifies a set of attributes.
+          It shall specify a set of attributes.
         spec-type: spec-dict
       float:
         description: |
-          This attribute specifies a floating-point value.
+          It shall specify a floating-point value.
         spec-type: spec-float
       int:
         description: |
-          This attribute specifies an integer value.
+          It shall specify an integer value.
         spec-type: spec-int
       list:
         description: |
-          This attribute specifies a list of attributes or values.
+          It shall specify a list of attributes or values.
         spec-type: spec-list
       none:
         description: |
-          This attribute indicates that no value is required.
+          It specifies that no value is required.
         spec-type: none
       str:
         description: |
-          This attribute specifies a string.
+          It shall specify a string.
         spec-type: spec-str
     description: |
-      This attribute set specifies attribute values.
+      This set of attributes specifies attribute values.
     required-attributes: at-least-one
 spec-name: Specification Information
 spec-type: spec-info
diff --git a/spec/spec/spec-int.yml b/spec/spec/spec-int.yml
index 2f7394b0..6799fb77 100644
--- a/spec/spec/spec-int.yml
+++ b/spec/spec/spec-int.yml
@@ -19,11 +19,10 @@ spec-info:
         spec-type: spec-assert-int
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          integer value.
+          It shall be the description of the specified integer value.
         spec-type: optional-str
     description: |
-      This attribute set specifies an integer value.
+      This set of attributes specifies an integer value.
     required-attributes:
     - description
 spec-name: Integer Value Specification
diff --git a/spec/spec/spec-list.yml b/spec/spec/spec-list.yml
index 2c60db37..76d824af 100644
--- a/spec/spec/spec-list.yml
+++ b/spec/spec/spec-list.yml
@@ -12,16 +12,14 @@ spec-info:
     attributes:
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          list.
+          It shall be the description of the list.
         spec-type: optional-str
       spec-type:
         description: |
-          This mandatory attribute defines the specification type of elements
-          of the specified list.
+          It shall be the specification type of elements of the list.
         spec-type: name
     description: |
-      This attribute set specifies a list of attributes or values.
+      This set of attributes specifies a list of attributes or values.
     required-attributes: all
 spec-name: List Specification
 spec-type: spec-list
diff --git a/spec/spec/spec-refinement.yml b/spec/spec/spec-refinement.yml
index ba6bb5e1..ec22d50d 100644
--- a/spec/spec/spec-refinement.yml
+++ b/spec/spec/spec-refinement.yml
@@ -16,13 +16,13 @@ spec-info:
     attributes:
       spec-key:
         description: |
-          This mandatory attribute defines the specification type refinement
-          attribute key of the specification refinement.
+          It shall be the specification type refinement attribute key of the
+          specification refinement.
         spec-type: name
       spec-value:
         description: |
-          This mandatory attribute defines the specification type refinement
-          attribute value of the specification refinement.
+          It shall be the specification type refinement attribute value of the
+          specification refinement.
         spec-type: name
     description: |
       It defines the specification refinement role of links.
diff --git a/spec/spec/spec-str.yml b/spec/spec/spec-str.yml
index 1ccba6f4..f117e3bf 100644
--- a/spec/spec/spec-str.yml
+++ b/spec/spec/spec-str.yml
@@ -18,11 +18,10 @@ spec-info:
         spec-type: spec-assert-str
       description:
         description: |
-          This mandatory attribute shall be the description of the specified
-          string attribute.
+          It shall be the description of the specified string attribute.
         spec-type: optional-str
     description: |
-      This attribute set specifies a string.
+      This set of attributes specifies a string.
     required-attributes:
     - description
 spec-name: String Specification
diff --git a/spec/spec/spec.yml b/spec/spec/spec.yml
index 7f33c78a..3bdd17b6 100644
--- a/spec/spec/spec.yml
+++ b/spec/spec/spec.yml
@@ -29,14 +29,14 @@ spec-example: |
       attributes:
         an-example-attribute:
           description: |
-            This mandatory attribute shall be an example.
+            It shall be an example.
           spec-type: optional-str
         example-number:
           description: |
-            This mandatory attribute shall be the example number.
+            It shall be the example number.
           spec-type: int
       description: |
-        This set of attributes gives an example.
+        This set of attributes specifies an example.
       required-attributes: all
   spec-name: Example Item Type
   spec-type: spec
@@ -46,25 +46,23 @@ spec-info:
     attributes:
       spec-description:
         description: |
-          This mandatory attribute shall be the description of the
-          specification type.
+          It shall be the description of the specification type.
         spec-type: optional-str
       spec-example:
         description: |
-          This mandatory attribute shall an example of the specification type.
+          If this value is present, then tt shall be an example of the
+          specification type.
         spec-type: optional-str
       spec-info:
-        description: |
-          This mandatory attribute defines the specification type information.
+        description: null
         spec-type: spec-info
       spec-name:
         description: |
-          This mandatory attribute shall be the human readable name of the
-          specification type.
+          It shall be the human readable name of the specification type.
         spec-type: optional-str
       spec-type:
         description: |
-          This mandatory attribute defines the specification type name.
+          It shall the specification type.
         spec-type: name
     description: |
       This set of attributes specifies specification types.