From bc2af0d0abebe37e5bb3a5b9e43d568d8537f2e3 Mon Sep 17 00:00:00 2001 From: Kristen James Eberlein Date: Sun, 7 Aug 2022 08:07:15 -0400 Subject: [PATCH] Final edits for stage three proposal, #15 --- ...n-attribute-to-certain-table-elements.dita | 2 +- ...ing-an-element-to-the-section-element.dita | 4 +- ...ting-constraint-and-expansion-modules.dita | 2 +- .../archSpec/base/configuration.dita | 10 +- .../archSpec/base/ditaspecialization.dita | 36 ++--- .../example-constrain-a-domain-using-rng.dita | 51 +++---- ...onstraints-apply-multiple-constraints.dita | 32 +++-- ...nts-redefine-content-model-attributes.dita | 15 +- ...ng-constraints-redefine-content-model.dita | 15 +- ...lace-base-element-w-domain-extensions.dita | 16 ++- ...les-constraints-implemented-using-rng.dita | 8 +- ...ples-expansion-implemented-using-dtds.dita | 6 +- ...mples-expansion-implemented-using-rng.dita | 8 +- .../archSpec/base/expansion-module-rules.dita | 105 +++++++------- .../archSpec/base/expansion-modules.dita | 2 +- .../base/overview-of-expansion-modules.dita | 94 +++++++------ ...n-attribute-to-certain-table-elements.dita | 86 ++++++------ ...ing-an-element-to-the-section-element.dita | 130 +++++++++--------- ...ting-constraint-and-expansion-modules.dita | 117 ++++++++-------- .../base/specialization-rules-elements.dita | 8 +- 20 files changed, 393 insertions(+), 354 deletions(-) diff --git a/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita b/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita index 7ce75f66..9f9a58a4 100644 --- a/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita +++ b/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita @@ -1,6 +1,6 @@ - + Example: Adding an attribute to certain table elements using DTDs In this scenario, a company makes extensive use of complex diff --git a/specification/archSpec/base/adding-an-element-to-the-section-element.dita b/specification/archSpec/base/adding-an-element-to-the-section-element.dita index 22883afb..ab89c805 100644 --- a/specification/archSpec/base/adding-an-element-to-the-section-element.dita +++ b/specification/archSpec/base/adding-an-element-to-the-section-element.dita @@ -1,6 +1,6 @@ - + Example: Adding an element to the <xmlelement>section</xmlelement> element using DTDs In this scenario, a DITA architect wants to modify the content @@ -36,7 +36,7 @@
  • First, the DITA architect creates the element specialization module: sectionDescDomain.mod. This single .mod file defines the parameter entity, - content model, attributes, and value for the + content model, attributes, and value for the class attribute for sectionDesc.<?xml version="1.0" encoding="UTF-8"?> diff --git a/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita b/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita index 8e808a65..c33a1991 100644 --- a/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita +++ b/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita @@ -1,6 +1,6 @@ - + Example: Aggregating constraint and expansion modules using DTDs The DITA architect wants to add some extension modules to the diff --git a/specification/archSpec/base/configuration.dita b/specification/archSpec/base/configuration.dita index 95c82d78..0b1ac4df 100644 --- a/specification/archSpec/base/configuration.dita +++ b/specification/archSpec/base/configuration.dita @@ -2,8 +2,10 @@ Document-type configuration - Document-type configuration enables the definition of DITA document - types that include only the vocabulary modules that are required for a given set of - documents. There is no need to modify the vocabulary modules. Document-type - configurations are implemented as document-type shells. + Document-type configuration enables the + definition of DITA document types that include only the vocabulary + modules that are required for a given set of documents. There is no + need to modify the vocabulary modules. Document-type + configurations are implemented using + document-type shells. diff --git a/specification/archSpec/base/ditaspecialization.dita b/specification/archSpec/base/ditaspecialization.dita index b40f5570..9db8a281 100644 --- a/specification/archSpec/base/ditaspecialization.dita +++ b/specification/archSpec/base/ditaspecialization.dita @@ -2,9 +2,9 @@ Overview of DITA extension facilities - DITA provides three extension facilities: Document-type configuration, - specialization, and element-type configuration. In addition, generalization can be applied to - reverse specialization. + DITA provides three extension facilities: + Document-type configuration, specialization, and element-type + configuration. @@ -23,15 +23,22 @@
    Specialization
    -
    Specialization enables the creation of new element types in a way that preserves the - ability to interchange those new element types with conforming DITA applications. - Specializations are implemented as vocabulary modules, which are integrated into - document-type shells.

    Specializations declare the elements and entities that are unique - to a specialization. The separation of the vocabulary and its declarations into modules - makes it easy to extend existing modules, because new modules can be added without - affecting existing document types. It also makes it easy to assemble elements from - different sources into a single document-type shell and to reuse specific parts of the - specialization hierarchy in more than one document-type shell.

    +
    Specialization enables the creation of new element types in a + way that preserves the ability to interchange those new element + types with conforming DITA applications. Specializations are + implemented as vocabulary modules, which are integrated into + document-type shells.

    Specializations declare the elements and + entities that are unique to a specialization. The separation of + the vocabulary and its declarations into modules makes it easy + to extend existing modules, because new modules can be added + without affecting existing document types. It also makes it + easy to assemble elements from different sources into a single + document-type shell and to reuse specific parts of the + specialization hierarchy in more than one document-type + shell.

    DITA content that uses specializations + can be treated as or converted to unspecialized markup through + the process of generalization. The information about the + original specialized form can be retained.
    Element-type configuration
    @@ -56,11 +63,6 @@     - -
    Generalization
    -
    Generalization is the process of reversing a specialization. It converts specialized - elements or attributes into the original types from which they were derived.
    -     diff --git a/specification/archSpec/base/example-constrain-a-domain-using-rng.dita b/specification/archSpec/base/example-constrain-a-domain-using-rng.dita index df971bbe..9e2fa1ac 100644 --- a/specification/archSpec/base/example-constrain-a-domain-using-rng.dita +++ b/specification/archSpec/base/example-constrain-a-domain-using-rng.dita @@ -1,30 +1,33 @@ - - Example: Constrain a domain module using RNG - In this scenario, a DITA architect wants - to use only a subset of the elements defined in the highlighting - domain. They want to use b - and i but not + + Example: Constrain a domain module using RNG + In this scenario, a DITA architect wants to + use only a subset of the elements defined in the highlighting domain. + They want to use b and + i but not line-through, overline, sup, sup, tt, or u. Their implementation uses RNG for its grammar files. - - - - constraintsexamplesrestricting content model for a - domain - examplesconstraintsrestricting content model for a - domain - - - - -

    When using RNG, domains can be constrained directly in the document-type shells.

    -
      -
    1. + + + + constraintsexamplesrestricting + content model for a + domain + examplesconstraintsrestricting + content model for a + domain + + + + +

      When using RNG, domains can be constrained directly in the + document-type shells.

      +
        +

      1. They open the document-type shell for topic in an XML editor, and then they modify the "MODULE INCLUSIONS" division to exclude the elements that

        2. -
      2. They make similar changes to all the - other document-type shells in which they want to +
      3. They make similar changes to all the other + document-type shells in which they want to constrain the highlighting domain.
        4. -
      -       +
    +     diff --git a/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita b/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita index c8ce0b62..3c9f634e 100644 --- a/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita +++ b/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita @@ -1,16 +1,17 @@ - - Example: Apply multiple constraints to a single document-type shell using RNG + + Example: Apply multiple constraints to a single document-type + shell using RNG In this scenario, the DITA architect wants to apply multiple constraints to a document-type shell. - constraintsexamplesapplying multiple - constraints - examplesconstraintsapplying multiple - constraints + constraintsexamplesapplying + multiple constraints + examplesconstraintsapplying + multiple constraints @@ -43,20 +44,22 @@ Not applicable Highlighting domain - Reduces the highlighting domain elements to b and - i + Reduces the highlighting domain elements to + b and + i Not applicable ph - Remove the ph element, allowing only domain - extensions + Remove the ph element, allowing + only domain extensions -

    The constraint modules that target the topic and - section elements must be combined, since both elements are - defined in topicMod.rng. The other constraints can be implemented - directly in the document-type shell.

    +

    The constraint modules that target the + topic and section + elements must be combined, since both elements are + defined in topicMod.rng. The other constraints + can be implemented directly in the document-type shell.

    1. The DITA architect creates a constraint @@ -144,5 +147,4 @@

    -     diff --git a/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita b/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita index 1ace1aee..3a1e4f30 100644 --- a/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita +++ b/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita @@ -1,9 +1,10 @@ - Example: Constrain attributes for the <xmlelement>section</xmlelement> element using - RNG + id="reference_cfb_ck4_5pexample-rng-constraints-redefine-content-model-attributes" + rev="2.0"> + Example: Constrain attributes for the + <xmlelement>section</xmlelement> element using RNG In this scenario, a DITA architect wants to redefine the attributes for the section element. They want to make the id @@ -11,10 +12,10 @@ - constraintsexamplesrestricting attributes for an - element - examplesconstraintsrestricting attributes for an - element + constraintsexamplesrestricting + attributes for an element + examplesconstraintsrestricting + attributes for an element diff --git a/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita b/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita index 43816b17..b03923b7 100644 --- a/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita +++ b/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita @@ -1,8 +1,9 @@ - - Example: Redefine the content model for the <xmlelement>topic</xmlelement> element using - RNG + + Example: Redefine the content model for the + <xmlelement>topic</xmlelement> element using RNG In this scenario, a DITA architect for Acme, Incorporated wants to redefine the content model for the topic document type. They want to omit the @@ -14,10 +15,10 @@ - constraintsexamplesredefining the content - model - examplesconstraintsredefining the content - model + constraintsexamplesredefining the + content model + examplesconstraintsredefining the + content model diff --git a/specification/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita b/specification/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita index b8525624..02316a3c 100644 --- a/specification/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita +++ b/specification/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita @@ -1,7 +1,8 @@ - - Example: Replace a base element with the domain extensions using RNG + + Example: Replace a base element with the domain extensions using + RNG In this scenario, the DITA architect wants to remove the ph element but allow the extensions of ph that exist in the highlight, @@ -9,10 +10,12 @@ - constraintsexamplesreplacing base element with domain - extensions - examplesconstraintsreplacing base element with domain - extensions + constraintsexamplesreplacing base + element with domain + extensions + examplesconstraintsreplacing base + element with domain + extensions @@ -40,5 +43,4 @@ - diff --git a/specification/archSpec/base/examples-constraints-implemented-using-rng.dita b/specification/archSpec/base/examples-constraints-implemented-using-rng.dita index 605544d2..ce05c176 100644 --- a/specification/archSpec/base/examples-constraints-implemented-using-rng.dita +++ b/specification/archSpec/base/examples-constraints-implemented-using-rng.dita @@ -1,7 +1,7 @@ - - Examples: Constraints implemented using RNG - This section of the specification contains examples of constraints implemented using - RNG + + Examples: Constraints implemented using RNG + This section of the specification contains examples of + constraints implemented using RNG diff --git a/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita b/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita index a121fec0..fc5d6d83 100644 --- a/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita +++ b/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita @@ -1,7 +1,7 @@ - - Examples: Expansion implemented using DTDs - This section of the specification contains examples of + + Examples: Expansion implemented using DTDs + This section of the specification contains examples of extension modules that are implemented using DTDs. diff --git a/specification/archSpec/base/examples-expansion-implemented-using-rng.dita b/specification/archSpec/base/examples-expansion-implemented-using-rng.dita index 721f6fd5..cd89386f 100644 --- a/specification/archSpec/base/examples-expansion-implemented-using-rng.dita +++ b/specification/archSpec/base/examples-expansion-implemented-using-rng.dita @@ -1,7 +1,7 @@ - - Examples: Expansion implemented using RNG - This section of the specification contains examples of extension modules implemented - using RNG. + + Examples: Expansion implemented using RNG + This section of the specification contains examples of + extension modules implemented using RNG. diff --git a/specification/archSpec/base/expansion-module-rules.dita b/specification/archSpec/base/expansion-module-rules.dita index 0b8eb51d..c9a28f40 100644 --- a/specification/archSpec/base/expansion-module-rules.dita +++ b/specification/archSpec/base/expansion-module-rules.dita @@ -1,49 +1,53 @@ - - Expansion module rules + + Expansion module rules + There are certain rules that apply to the design and - implementation of expansion modules. These rules all stem - from the requirement that, after generalization, the content model of - a element affected by an expansion module must match the original - content model for that element. - - - - design and implementation rulesexpansion - modules - expansion modulesdesign and implementation - rules - - - - + implementation of expansion modules. These rules all + stem from the requirement that the content model of a specialized + element must be consistent with the content model of the + specialization base. After generalization, the content model of an + element affected by an expansion module must match the original + content model for that element. + + + + + design and implementation rulesexpansion + modules + expansion modulesdesign and implementation + rules + + + + -
    - -
    Specialization base of expanded elements
    -
    -

    Elements that are added to content models by - expansion models must be specializations of existing elements - that are permitted in the content model.

    -
    -     - -
    Content model of expanded elements
    -
    +
    + +
    Specialization base of expanded elements
    +
    +

    Elements that are added to content models by expansion models + must be specializations of existing elements that are permitted + in the original content model.

    +
    +     + +
    Content model of expanded elements
    +

    Elements that are added to content models by expansion models must be allowed only where their specialization base is allowed.

    For example, when creating an expansion model that adds a specialization of data to ol, - the specialization of data must only + the specialization of data must only be allowed before any li elements, as that is the only place that the data element is allowed in the content model for an ordered list.

    -
    -     +
    +
    Ordinality of expanded elements
    @@ -81,22 +85,23 @@
    - -
    Aggregation of expansion modules
    -
    -

    The content model of an element can be modified by either of the following - element-configuration modules:

    -
      -
    • Constraint module
      • -
    • Expansion module
      • -
    -

    The content model of an element can be modified only by a single element-type - configuration module. If multiple constraints or extensions need to be - applied to a single element, the element configurations must be combined - into a single module that reflects all the constraints and expansions that - were defined in the original separate modules.

    -
    -     -
    -     + +
    Aggregation of expansion modules
    +
    +

    The content model of an element can be modified by either of + the following element-configuration modules:

    +
      +
    • Constraint module
      • +
    • Expansion module
      • +
    +

    The content model of an element can be modified only by a + single element-type configuration module. If multiple + constraints or extensions need to be applied to a single + element, the element configurations must be combined into a + single module that reflects all the constraints and expansions + that were defined in the original separate modules.

    +
    +     + +     diff --git a/specification/archSpec/base/expansion-modules.dita b/specification/archSpec/base/expansion-modules.dita index 52e2e386..86be8886 100644 --- a/specification/archSpec/base/expansion-modules.dita +++ b/specification/archSpec/base/expansion-modules.dita @@ -1,6 +1,6 @@ - + Expansion modules Expansion modules enable the extension of content models and attribute lists for individual elements. Expansion modules are the diff --git a/specification/archSpec/base/overview-of-expansion-modules.dita b/specification/archSpec/base/overview-of-expansion-modules.dita index 99669c78..7576a150 100644 --- a/specification/archSpec/base/overview-of-expansion-modules.dita +++ b/specification/archSpec/base/overview-of-expansion-modules.dita @@ -1,54 +1,58 @@ - - Overview of expansion modules - Expansion modules enable information architects to include specialized attributes or - elements in specific element types, without making them globally available. - - - - expansion modulesoverview - - - - -

    An expansion module can perform the following functions:

    -
    - -
    Expand content models
    -
    -

    Expansion modules extend the content models of specific elements, without - making the specialized elements available wherever the specialization base - is permitted.

    -

    For example, an expansion for + + Overview of expansion modules + Expansion modules enable information architects to include + specialized attributes or elements in specific element types, without + making them globally available. + + + + expansion + modulesoverview + + + + +

    An expansion module can perform the following functions:

    +
    + +
    Expand content models
    +
    +

    Expansion modules extend the content models of specific + elements, without making the specialized elements available + wherever the specialization base is permitted.

    +

    For example, an expansion for section can make a new element (sectionDesc) available as an optional, child element. The sectionDesc element is specialized from p, but it is available only within section.

    -

    The elements must be defined in a separate element domain that declares the - content models and attribute lists for the new elements.

    -
    -     - -
    Expand attribute lists
    -
    -

    Expansion modules extend the attribute lists of specific elements by adding - attributes specialized from either base or - props.

    -

    For example, an expansion for - entry, row, and - colspec can make cell-purpose - available only on those elements. The cell-purpose - attribute is specialized from base.

    -

    The additional attribute can be either defined - directly within the expansion module, or it can be defined in a - separate attribute-specialization module. In either case, the - token used as value for the specializations - attribute must be defined.

    -
    -     -
    - +

    The elements are defined in a separate element domain that + declares the content models and attribute lists for the new + elements.

    +
    +     + +
    Expand attribute lists
    +
    +

    Expansion modules extend the attribute lists of specific + elements by adding attributes specialized from either + base or props.

    +

    For example, an expansion for + entry, row, + and colspec can make + cell-purpose available only on those + elements. The cell-purpose attribute is + specialized from base.

    +

    The additional attribute can be either defined directly within + the expansion module, or it can be defined in a separate + attribute-specialization module. In either case, the token used + as value for the specializations attribute + must be defined.

    +
    +     +
    +     diff --git a/specification/archSpec/base/rng-adding-an-attribute-to-certain-table-elements.dita b/specification/archSpec/base/rng-adding-an-attribute-to-certain-table-elements.dita index 355a797b..bd00993d 100644 --- a/specification/archSpec/base/rng-adding-an-attribute-to-certain-table-elements.dita +++ b/specification/archSpec/base/rng-adding-an-attribute-to-certain-table-elements.dita @@ -1,46 +1,48 @@ - - Example: Adding an attribute to certain table elements using RNG - In this scenario, a company makes extensive use of complex tables to present product - listings. They occasionally highlight individual cells, rows, or columns for various - purposes. The DITA architect wants to implement a semantically meaningful way to identify - the purpose of various table elements. - - - - expansion modulesexamplesexpanding attributes for - an element - examplesexpansion modulesexpanding attributes for - an element - - - - -

    The DITA architect decides to create a new attribute (cell-purpose) and - add it to the content model of the following elements:

    -
      -
    • entry
      • -
    • row
      • -
    • colspec
      • -
    • stentry
      • -
    • strow
      • -
    -

    The new attribute will be specialized from - base, and it will take a small set of tokens as - values.

    + + Example: Adding an attribute to certain table elements using + RNG + In this scenario, a company makes extensive use of complex + tables to present product listings. They occasionally highlight + individual cells, rows, or columns for various purposes. The DITA + architect wants to implement a semantically meaningful way to identify + the purpose of various table elements. + + + + expansion modulesexamplesexpanding + attributes for an element + examplesexpansion modulesexpanding + attributes for an element + + + + +

    The DITA architect decides to create a new attribute + (cell-purpose) and add it to the content model of + the following elements:

    +
      +
    • entry
      • +
    • row
      • +
    • colspec
      • +
    • stentry
      • +
    • strow
      • +
    +

    The new attribute will be specialized from base, + and it will take a small set of tokens as values.

    The DITA architect decides to integrate the attribute declaration and its assignment to elements into a single expansion module. An alternate approach would be to put each <!ATTLIST declaration in its own separate expansion module, thus allowing DITA architects who construct document-type shells to decide the elements to which to apply the attribute.

    -
      -
    1. -

      The DITA architect creates an expansion module: +

        +
      1. +

        The DITA architect creates an expansion module: cellPurposeAtt.rng. It contains the following code:

        - <?xml version="1.0" encoding="UTF-8"?> + <?xml version="1.0" encoding="UTF-8"?> <?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> <grammar @@ -85,11 +87,11 @@ <ref name="cellPurposeAtt"/> </define> </grammar> -
        2. -
      2. -

        They then update the catalog.xml - file to include the expansion module.

        -
        3. + +
      3. +

        They then update the catalog.xml file to + include the expansion module.

        +

      4. They integrate the expansion module into the document-type shell:

        @@ -115,8 +117,8 @@ </optional> </define> </div>
        5. -
      5. After checking the test file to ensure that the attribute lists are modified as - expected, the work is done.
        6. -
      - +
    2. After checking the test file to ensure that the attribute lists + are modified as expected, the work is done.
      3. +
    +     diff --git a/specification/archSpec/base/rng-adding-an-element-to-the-section-element.dita b/specification/archSpec/base/rng-adding-an-element-to-the-section-element.dita index 328feb04..c3730e20 100644 --- a/specification/archSpec/base/rng-adding-an-element-to-the-section-element.dita +++ b/specification/archSpec/base/rng-adding-an-element-to-the-section-element.dita @@ -1,37 +1,42 @@ - - Example: Adding an element to the <xmlelement>section</xmlelement> element using - RNG - In this scenario, a DITA architect wants to modify the content model for the - section element. He wants to add an optional - sectionDesc element that is specialized from - p; the sectionDesc can occur once and - must be directly after the section title. - - - - expansion modulesexamplesexpanding content model of - section - examplesexpansion modulesexpanding content model of - section - - - - - -

    To accomplish this, the DITA architect needs to create the following modules and - integrate them into the document-type shells:

    -
      -
    • An element domain module that defines the sectionDesc - element
      • -
    • An expansion module that adds the sectionDesc element - to the content model for section
      • -
    -
      -
    1. First, the DITA architect creates the element domain - module: sectionDescDomain.rng. It contains - the following + + Example: Adding an element to the <xmlelement>section</xmlelement> + element using RNG + In this scenario, a DITA architect wants to modify the content + model for the section element. He wants to add + an optional sectionDesc element that is + specialized from p; the + sectionDesc can occur once and must be + directly after the section title. + + + + expansion modulesexamplesexpanding + content model of + section + examplesexpansion modulesexpanding + content model of + section + + + + + +

      To accomplish this, the DITA architect needs to create the + following modules and integrate them into the document-type + shells:

      +
        +
      • An element domain module that defines the + sectionDesc element
        • +
      • An expansion module that adds the + sectionDesc element to the content + model for section
        • +
      +
        +
      1. First, the DITA architect creates the element domain module: + sectionDescDomain.rng. It contains the + following code:<?xml version="1.0" encoding="UTF-8"?> <?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> @@ -80,26 +85,27 @@ </define> </div> </grammar>
        2. -
      2. The DITA architect adds the element domain module to the - catalog.xml file.
        3. -
      3. -

        Next, the DITA architect modifies the document-type shell (in this example, - the one for topic) to integrate the element domain module:

        - <div> +
      4. The DITA architect adds the element domain module to the + catalog.xml file.
        5. +
      5. +

        Next, the DITA architect modifies the document-type shell (in + this example, the one for topic) to integrate the element + domain module:

        + <div> <a:documentation>MODULE INCLUSIONS</a:documentation> ... <include href="urn:example:names:tc:dita:rng:sectionDescDomain.rng:2.0"/> </div> -

        At this point, the new domain is integrated into the document-type shell. - However, the new element is not added to the content model for - section.

        -
        6. -
      6. -

        Next, the DITA architect created an expansion module - (sectionExpansionMod.rng) that adds the - sectionDesc element to the content model of - section:

        - <?xml version="1.0" encoding="UTF-8"?> +

        At this point, the new domain is integrated into the + document-type shell. However, the new element is not added to + the content model for section.

        +
        7. +
      7. +

        Next, the DITA architect created an expansion module + (sectionExpansionMod.rng) that adds the + sectionDesc element to the content + model of section:

        + <?xml version="1.0" encoding="UTF-8"?> <?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0" @@ -127,14 +133,14 @@ </div> </grammar> -

        Note that the expansion module directly integrates - topicMod.rng.

        -
        8. -
      8. -

        Finally, the DITA architect integrates the expansion module into the - document-type shell and removes the inclusion statement for - topicMod.rng:

        - <div> +

        Note that the expansion module directly integrates + topicMod.rng.

        +
        9. +
      9. +

        Finally, the DITA architect integrates the expansion module + into the document-type shell and removes the inclusion + statement for topicMod.rng:

        + <div> <a:documentation>ELEMENT-TYPE CONFIGURATION INTEGRATION</a:documentation> <include href="sectionExpansionMod.rng"/> </div> @@ -148,10 +154,10 @@ ... <include href="urn:example:names:tc:dita:rng:sectionDescDomain.rng:2.0"/> </div> -
        10. -
      10. After updating the catalog.xml file to include the - expansion module and testing, the work is done.
        11. -
      -       -       +
      2. +
    2. After updating the catalog.xml file to + include the expansion module and testing, the work is done.
      3. +
    +     +     diff --git a/specification/archSpec/base/rng-aggregating-constraint-and-expansion-modules.dita b/specification/archSpec/base/rng-aggregating-constraint-and-expansion-modules.dita index 908953e0..b8f1b922 100644 --- a/specification/archSpec/base/rng-aggregating-constraint-and-expansion-modules.dita +++ b/specification/archSpec/base/rng-aggregating-constraint-and-expansion-modules.dita @@ -1,52 +1,56 @@ - - Example: Aggregating constraint and expansion modules using RNG - The DITA architect wants to add some extension modules to the document-type shell for - topic. The document-type shell already integrates a constraint module. - -

    The following table lists the constraint module and the extension modules that the DITA - architect wants to integrate into the document-type shell for topic.

    - - - Type of element configuration - File name - What it does - - - Constraint - topicSectionConstraint.rng - -

    Constrains topic:

    -
      -
    • Removes abstract
      • -
    • Makes shortdesc required
      • -
    • Removes related-links
      • -
    • Disallows topic nesting
      • -
    -

    Constrains section:

    -
      -
    • Makes id required
      • -
    -     -     - - Expansion - sectionExpansionMod.rng - Adds sectionDesc to the content model of - section - - - Expansion - tableCellAttExpansion.rng - Adds cellPurpose to the attribute lists for certain table - elements - -     -

    Because all of these element-configuration modules target elements declared in - topicMod.rng, the DITA architect needs to combine them into a - single element-configuration module like the following:

    - <?xml version="1.0" encoding="UTF-8"?> + + Example: Aggregating constraint and expansion modules using + RNG + The DITA architect wants to add some extension modules to the + document-type shell for topic. The document-type shell already + integrates a constraint module. + +

    The following table lists the constraint module and the extension + modules that the DITA architect wants to integrate into the + document-type shell for topic.

    + + + Type of element configuration + File name + What it does + + + Constraint + topicSectionConstraint.rng + +

    Constrains topic:

    +
      +
    • Removes abstract
      • +
    • Makes shortdesc required
      • +
    • Removes related-links
      • +
    • Disallows topic nesting
      • +
    +

    Constrains section:

    +
      +
    • Makes id required
      • +
    +     +     + + Expansion + sectionExpansionMod.rng + Adds sectionDesc to the content + model of section + + + Expansion + tableCellAttExpansion.rng + Adds cellPurpose to the attribute lists + for certain table elements + +     +

    Because all of these element-configuration modules target elements + declared in topicMod.rng, the DITA architect + needs to combine them into a single element-configuration module like + the following:

    + <?xml version="1.0" encoding="UTF-8"?> <?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0" @@ -122,13 +126,14 @@ </div> </grammar> -

    When the DITA architect edits the document-type shell to - integrate the element configuration module, they also - need to do the following:

    -
      -
    • Remove the include statement for topicMod.rng
      • -
    • Add section to the "ID-DEFINING ELEMENT OVERRIDES" - division
      • -
    -     +

    When the DITA architect edits the document-type shell to integrate + the element configuration module, they also need + to do the following:

    +
      +
    • Remove the include statement for + topicMod.rng
      • +
    • Add section to the "ID-DEFINING ELEMENT + OVERRIDES" division
      • +
    +     diff --git a/specification/archSpec/base/specialization-rules-elements.dita b/specification/archSpec/base/specialization-rules-elements.dita index 44cdd368..3698b66e 100644 --- a/specification/archSpec/base/specialization-rules-elements.dita +++ b/specification/archSpec/base/specialization-rules-elements.dita @@ -14,11 +14,15 @@

    A specialized element type has the following characteristics:

    + +

    Robert Anderson and I both think that the 2nd bullet point needs + expansion, to cover the effects of expansion modules.

    +
    • A properly-formed class attribute that specifies the specialization hierarchy of the element
      • -
    • A content model that is the same or less inclusive than that of the element from which it - was specialized after generalization
      • +
    • A content model that is the same or less inclusive than that of + the element from which it was specialized
    • A set of attributes that are the same or a subset of those of the element from which it was specialized, except for specializations of base or props