From 62419203ae64c6b5d131a815b172d9e110a9ce72 Mon Sep 17 00:00:00 2001 From: Kristen James Eberlein Date: Fri, 14 May 2021 19:54:14 -0400 Subject: [PATCH] Edited config and coding req chapters prior to distributing stage 3 #15 --- ...n-attribute-to-certain-table-elements.dita | 3 - .../archSpec/base/coding-requirements.dita | 6 +- ...ration-specialization-and-constraints.dita | 6 +- .../archSpec/base/configuration.dita | 8 +-- .../archSpec/base/constraint-rules.dita | 8 +-- .../archSpec/base/constraints-overview.dita | 14 +++-- ...nstraints-processing-interoperability.dita | 6 ++ .../archSpec/base/ditaspecialization.dita | 30 +++++----- .../document-type-shells-equivalence.dita | 10 ++-- .../archSpec/base/document-type-shells.dita | 60 +++++++++---------- .../archSpec/base/dtd-coding-overview.dita | 10 ++-- ...coding-requirements-expansion-modules.dita | 7 --- .../example-constrain-a-domain-using-rng.dita | 10 +--- ...onstraints-apply-multiple-constraints.dita | 3 - ...nts-redefine-content-model-attributes.dita | 3 - ...ng-constraints-redefine-content-model.dita | 3 - ...lace-base-element-w-domain-extensions.dita | 3 - ...les-constraints-implemented-using-rng.dita | 8 +-- .../archSpec/base/examples-constraints.dita | 8 +-- ...ples-expansion-implemented-using-dtds.dita | 8 +-- ...mples-expansion-implemented-using-rng.dita | 8 +-- .../base/generalization-elements.dita | 4 +- ...n-w-cross-specialization-dependencies.dita | 10 ++-- .../base/recognizedconstraintmechanisms.dita | 21 ++----- .../base/relax-ng-coding-doctype-shell.dita | 4 +- .../base/relax-ng-coding-element-types.dita | 12 ++-- ...coding-requirements-expansion-modules.dita | 40 +++++++++---- .../base/rules-document-type-shells.dita | 10 ++-- ...ialization-including-non-dita-content.dita | 2 +- .../base/specialization-modularization.dita | 12 ++-- .../base/specialization-overview.dita | 6 +- .../base/specialization-rules-elements.dita | 5 +- ...cialization-specializations-attribute.dita | 8 +-- .../specialization-vocabulary-modules.dita | 9 ++- .../archSpec/base/using-relax-ng.dita | 10 ++-- 35 files changed, 172 insertions(+), 203 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 c8d7f395..1e6bbecf 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 @@ -33,9 +33,6 @@ 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.

- -

Tested and verified that this works as written.

-
  1. First, the DITA architect creates the attribute domain module for the cell-purpose attribute: diff --git a/specification/archSpec/base/coding-requirements.dita b/specification/archSpec/base/coding-requirements.dita index 68344690..ac294857 100644 --- a/specification/archSpec/base/coding-requirements.dita +++ b/specification/archSpec/base/coding-requirements.dita @@ -2,7 +2,7 @@ Coding practices for DITA grammar files - This section collects all of the rules for creating modular DTD, RELAX NG, or XML Schema - grammar files to represent DITA document types, specializations, and constraints. - + This section collects all of the rules for creating modular DTD or RELAX NG-based + grammar files that represent DITA document types, specializations, constraints, and expansion + modules. diff --git a/specification/archSpec/base/configuration-specialization-and-constraints.dita b/specification/archSpec/base/configuration-specialization-and-constraints.dita index 1fe93dff..208cad2d 100644 --- a/specification/archSpec/base/configuration-specialization-and-constraints.dita +++ b/specification/archSpec/base/configuration-specialization-and-constraints.dita @@ -5,7 +5,7 @@ expansion The extension facilities of DITA allow document-type shells, vocabulary - modules, and element-configuration modules (constraints and expansion) to be combined to create - specific DITA document types. Vocabulary modules also can be specialized to meet requirements - that are not satisfied by existing markup. + modules, and element-configuration modules (constraint and expansion) to be combined to + create specific DITA document types. Vocabulary modules also can be specialized to meet + requirements that are not satisfied by existing markup. diff --git a/specification/archSpec/base/configuration.dita b/specification/archSpec/base/configuration.dita index 63b32d1d..95c82d78 100644 --- a/specification/archSpec/base/configuration.dita +++ b/specification/archSpec/base/configuration.dita @@ -2,8 +2,8 @@ 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. 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 as document-type shells. diff --git a/specification/archSpec/base/constraint-rules.dita b/specification/archSpec/base/constraint-rules.dita index 2be1da59..1d1f0998 100644 --- a/specification/archSpec/base/constraint-rules.dita +++ b/specification/archSpec/base/constraint-rules.dita @@ -22,7 +22,7 @@

    The content model and attributes of an element can be constrained by only one constraint module. If two constraint modules exist that constrain the content model or attributes for a specific element, those two modules must be replaced with a new constraint module that - reflects the aggregation of the two original constraint modules.

    + reflects the aggregation of the two original modules.

    @@ -32,9 +32,9 @@ be omitted from the domain extension group or parameter entity. In such a case, there is no separate constraint declaration, because the content model is configured directly in the document-type shell.

    -

    A domain module can be constrained by only one constraint module. This - means that all restrictions for the extension elements that are defined in the domain must be - contained within that one constraint module.

    +

    A domain module can be constrained by only one constraint module. This means that all + restrictions for the extension elements that are defined in the domain must be contained + within that one constraint module.

     diff --git a/specification/archSpec/base/constraints-overview.dita b/specification/archSpec/base/constraints-overview.dita index e0b8cec5..eff89b27 100644 --- a/specification/archSpec/base/constraints-overview.dita +++ b/specification/archSpec/base/constraints-overview.dita @@ -2,10 +2,10 @@ Overview of constraints - Constraint modules enable information architects to restrict the - content models or attributes of OASIS-defined DITA grammars. A constraint is a simplification of - an XML grammar such that any instance that conforms to the constrained grammar also will conform - to the original grammar. + Constraint modules enable information architects to restrict the content models or + attributes of DITA elements. A constraint is a simplification of an XML grammar such that any + instance that conforms to the constrained grammar also will conform to the original + grammar. @@ -45,11 +45,13 @@
    Restrict the elements that are available in a domain

    Constraint modules can restrict the set of extension elements that are provided in a domain. - They also can restrict the content models for the extension - elements.

    + They also can restrict the content models for the extension elements.

    For example, a constraint on the programming domain can reduce the list of included extension elements to codeph and codeblock.

    + For DITA implementations that use RNG-based grammar file, restricting the set of + extension elements that are provided in a domain can be handled simply by document-type + configuration.
    diff --git a/specification/archSpec/base/constraints-processing-interoperability.dita b/specification/archSpec/base/constraints-processing-interoperability.dita index de7daef3..9f13193a 100644 --- a/specification/archSpec/base/constraints-processing-interoperability.dita +++ b/specification/archSpec/base/constraints-processing-interoperability.dita @@ -27,6 +27,12 @@ document type. Thus, for a processor to determine whether a document instance is compatible with another document type, the document instance MUST declare any constraints on the document type.

    + +

    For DITA 2.0, we've removed the requirement to add tokens for constraints. So, I think we need + to remove this normative statement. Do we want to replace it with anything? Another statement + about constraints and interoperability? This reminds we that we might want to stress for folks + that we have removed the entire concept of strong and weak constraints ...

    +

    For example, an unconstrained task is compatible with an unconstrained topic, because the task element can be generalized to topic. However, if the topic is constrained to require the diff --git a/specification/archSpec/base/ditaspecialization.dita b/specification/archSpec/base/ditaspecialization.dita index 248fcc35..3d92109a 100644 --- a/specification/archSpec/base/ditaspecialization.dita +++ b/specification/archSpec/base/ditaspecialization.dita @@ -16,22 +16,22 @@

    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. 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 as document-type shells.
    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 are 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.

    + 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.
    Element-type configuration
    @@ -39,17 +39,17 @@

    Element-type configuration enables DITA architects to modify the content models and attribute lists for individual elements, without modifying the vocabulary modules in which the elements are defined.

    -

    There are two types of element configuration: Constraints and expansion. Both - constraints and expansions are implemented as modules that are integrated into - document-type shells:

    +

    There are two types of element configuration: Constraint and expansion. Both constraint + and expansion are implemented as modules that are integrated into document-type + shells:

    -
    Constraints
    +
    Constraint
    Constraint modules enables the restriction of content models and attribute lists for individual elements.
     -
    Expansions
    +
    Expansion
    Expansion modules enable the expansion of content models and attribute lists for individual elements.
     diff --git a/specification/archSpec/base/document-type-shells-equivalence.dita b/specification/archSpec/base/document-type-shells-equivalence.dita index 34c86684..2e109ef7 100644 --- a/specification/archSpec/base/document-type-shells-equivalence.dita +++ b/specification/archSpec/base/document-type-shells-equivalence.dita @@ -14,7 +14,7 @@

    A DITA document type is defined by the following:

      -
    • The set of vocabulary and element-configuration modules (constraints and +
    • The set of vocabulary and element-configuration modules (constraint and expansion) that are integrated by the document type shell
    • The values of the class attributes of all the elements in the document
      • @@ -31,9 +31,9 @@
    • It has a distinct system identifier.
    • If it has a public identifier, the public identifier is unique.
    - The public or system identifier that is associated with a given document-type shell is - not, by itself, necessarily distinguishing. This is because two different people or groups - might use the same modules and constraints to assemble equivalent document type shells, while - giving them different names or public identifiers. + The public or system identifier that is associated with a given document-type shell is not + necessarily distinguishing. Two different people or groups might use the same modules and + constraints to assemble equivalent document type shells, while giving them different names or + public identifiers.     diff --git a/specification/archSpec/base/document-type-shells.dita b/specification/archSpec/base/document-type-shells.dita index 9f470e66..b0c033ba 100644 --- a/specification/archSpec/base/document-type-shells.dita +++ b/specification/archSpec/base/document-type-shells.dita @@ -14,49 +14,47 @@ -

    A DITA document must either have an associated document-type definition - or all required attributes must be made explicit in the document instances. - Most DITA documents have an associated document-type shell. DITA documents that - reference a document-type shell can be validated using standard XML processors. - Such validation enables processors to read the XML grammar files and determine - default values for the specializations and class - attributes. -

    +

    A DITA document either must have an associated document-type definition or all required + attributes must be made explicit in the document instances. Most DITA documents have an + associated document-type shell. DITA documents that reference a document-type shell can + be validated using standard XML processors. Such validation enables processors to read + the XML grammar files and determine default values for the + specializations and class attributes.

    The following figure illustrates the relationship between a DTD-based DITA document, its document-type shell, the vocabulary modules that it uses, and the - element-configuration modules (constraints and expansions) that it integrates. + element-configuration modules (constraint and expansion) that it integrates. Similar structure applies to DITA documents that use other XML grammars.

    - - Document type shell - - Diagram showing a typical architecture of a DITA document type shell. At the top left a - DITA document file named myTopic.dita refers to a document - type of 'myTopic'. An arrow from this file points to a document-type shell file - named myTopic.dtd. Arrows point to several other modules. A - constraint module is named strictMyTopicConstraint.mod. - Structural modules are named mytopic.ent, - mytopic.mod, topic.ent, and - topic.mod. Domain modules are named - myPhraseDomain.ent, + + Document type shell + + Diagram showing a typical architecture of a DITA document type shell. At the + top left a DITA document file named myTopic.dita refers to + a document type of 'myTopic'. An arrow from this file points to a document-type + shell file named myTopic.dtd. Arrows point to several other + modules. A constraint module is named + strictMyTopicConstraint.mod. Structural modules are + named mytopic.ent, mytopic.mod, + topic.ent, and topic.mod. Domain + modules are named myPhraseDomain.ent, myPhraseDomain.mod, highlightDomain.ent, highlightDomain.mod, programmingDomain.ent, and programmingDomain.mod. The structural and domain - modules are grouped together and labeled vocabulary modules. - - + modules are grouped together and labeled vocabulary modules. + +

    The illustration needs to be updated to include expansion modules.

    The DITA specification contains a starter set of document-type shells. These document-type shells are commented and can be used as templates for creating custom document-type - shells. While the OASIS-provided document-type shells can be used without any - modification, creating custom document-type shells is a best practice. If the - document-type shells need to be modified in the future, for example, to include a - specialization or integrate a constraint, the existing DITA documents will not need to - be modified to reference a new document-type shell.

    + shells.

    +

    While the OASIS-provided document-type shells can be used without any modification, + creating custom document-type shells is a best practice. If the document-type shells + need to be modified in the future, for example, to include a specialization or integrate + a constraint, the existing DITA documents will not need to be modified to reference a + new document-type shell.

    diff --git a/specification/archSpec/base/dtd-coding-overview.dita b/specification/archSpec/base/dtd-coding-overview.dita index dbafb587..57a69d9a 100644 --- a/specification/archSpec/base/dtd-coding-overview.dita +++ b/specification/archSpec/base/dtd-coding-overview.dita @@ -49,11 +49,11 @@

    Every element in a DITA DTD defines its content model using an entity. This enables element configuration.

    For example, rather than directly setting what is allowed in - ph, that element sets its content model to - %ph.content;; that entity defines the actual content model. A - constraint module can redefine the %ph.content; model to remove selected - elements, or an expansion module can redefine the %ph.content; module to add - elements.. + ph, that element sets its content model to + %ph.content;; that entity defines the actual content model. A constraint module can redefine the %ph.content; model to + remove selected elements, or an expansion module can redefine the + %ph.content; module to add elements. diff --git a/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita b/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita index 75527b67..27645889 100644 --- a/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita +++ b/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita @@ -45,13 +45,6 @@ expansion attribute and should not be included in the base-attribute-extensions entity in the document-type shell.

    - -

    Should we call this - tagname.attributes parameter - entity? Or would - Domain.attributes parameter - entity be more appropriate?

    -     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 afa141d2..fa72def9 100644 --- a/specification/archSpec/base/example-constrain-a-domain-using-rng.dita +++ b/specification/archSpec/base/example-constrain-a-domain-using-rng.dita @@ -19,9 +19,6 @@ - -

    Tested; verified that it works as written.

    -

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

    1. @@ -55,12 +52,7 @@ </div> The information architect made an arbitrary choice as to where in the document-type shell she would implement the constraint. It can be placed either in the "Element-type - configuration integration" or the "Module inclusions" section. -

      I assume that if someone does this redefinition in the "Element-type configuration - integration" section, then the domain module would not be included in the "Module - inclusions" section?

      -       + configuration integration" or the "Module inclusions" section.
    2. She makes similar changes to all the other document-type shells in which she wants to constrain the highlighting domain.
      3. 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 df826b85..b7a98b5e 100644 --- a/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita +++ b/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita @@ -15,9 +15,6 @@ - -

      Tested; verified that this works as written

      -

      Here is a list of the constraint modules and what they do:

      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 f8748453..cc53ab65 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 @@ -18,9 +18,6 @@ - -

      Tested; verified that this works as written.

      -
      1. He creates a file named id-requiredSectionContraintMod.rng, where 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 5bc10790..6f64b9ab 100644 --- a/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita +++ b/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita @@ -19,9 +19,6 @@ - -

        Tested; verified that this works as written.

        -
        1. She creates a .mod file using the following naming conventions: 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 19b5cf14..4aead178 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 @@ -16,9 +16,6 @@ - -

          Tested; verified that it works as written.

          -
          1. diff --git a/specification/archSpec/base/examples-constraints-implemented-using-rng.dita b/specification/archSpec/base/examples-constraints-implemented-using-rng.dita index be57236a..605544d2 100644 --- a/specification/archSpec/base/examples-constraints-implemented-using-rng.dita +++ b/specification/archSpec/base/examples-constraints-implemented-using-rng.dita @@ -2,10 +2,6 @@ Examples: Constraints implemented using RNG - - - - - - + This section of the specification contains examples of constraints implemented using + RNG diff --git a/specification/archSpec/base/examples-constraints.dita b/specification/archSpec/base/examples-constraints.dita index dc073577..05e82038 100644 --- a/specification/archSpec/base/examples-constraints.dita +++ b/specification/archSpec/base/examples-constraints.dita @@ -2,10 +2,6 @@ Examples: Constraints implemented using DTDs - - - - - - + This section of the specification contains examples of constraints implemented using + DTD. diff --git a/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita b/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita index 8d77e4b3..29528707 100644 --- a/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita +++ b/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita @@ -2,10 +2,6 @@ Example: Expansion implemented using DTD - - - - - - + This section of the specification contains examples of extension modules implemented + using DTD. diff --git a/specification/archSpec/base/examples-expansion-implemented-using-rng.dita b/specification/archSpec/base/examples-expansion-implemented-using-rng.dita index 24a699f2..721f6fd5 100644 --- a/specification/archSpec/base/examples-expansion-implemented-using-rng.dita +++ b/specification/archSpec/base/examples-expansion-implemented-using-rng.dita @@ -2,10 +2,6 @@ Examples: Expansion implemented using RNG - - - - - - + This section of the specification contains examples of extension modules implemented + using RNG. diff --git a/specification/archSpec/base/generalization-elements.dita b/specification/archSpec/base/generalization-elements.dita index bbdae665..e8a574ba 100644 --- a/specification/archSpec/base/generalization-elements.dita +++ b/specification/archSpec/base/generalization-elements.dita @@ -18,8 +18,8 @@

            For example, the step element has a class attribute value of "- topic/li task/step ". If the - task module is being generalized, the step element is renamed to its - more general form from the topic module: li.

            + task module is generalized, the step element is renamed to its more + general form from the topic module: li.

            For specific concerns when generalizing structural types with dependencies on non-ancestor modules, see .

            diff --git a/specification/archSpec/base/generalization-w-cross-specialization-dependencies.dita b/specification/archSpec/base/generalization-w-cross-specialization-dependencies.dita index ac1c611a..a158cd0e 100644 --- a/specification/archSpec/base/generalization-w-cross-specialization-dependencies.dita +++ b/specification/archSpec/base/generalization-w-cross-specialization-dependencies.dita @@ -8,13 +8,13 @@

            When a structural specialization has a dependency on a domain specialization, then the domain cannot be generalized without also generalizing the reusing structural specialization.

            -

            For example, a structural specialization codeConcept might incorporate and - require the codeblock element from the programming domain. A +

            For example, a structural specialization codeConcept might incorporate + and require the codeblock element from the programming domain. A generalization process that turns programming domain elements back into topic elements would convert codeblock to pre, making a document - that uses codeConcept invalid. However, codeConcept could be generalized to concept or topic, - without generalizing programming domain elements, as long as the target document type includes - the programming domain.

            + that uses codeConcept invalid. However, codeConcept could + be generalized to concept or topic, without generalizing programming domain elements, as long as + the target document type includes the programming domain.

            When a structural specialization has a dependency on another structural specialization, then both must be generalized together to a common ancestor.

            For example, if the task elements in checklist were generalized without also generalizing diff --git a/specification/archSpec/base/recognizedconstraintmechanisms.dita b/specification/archSpec/base/recognizedconstraintmechanisms.dita index 3fabd32c..f5136dc1 100644 --- a/specification/archSpec/base/recognizedconstraintmechanisms.dita +++ b/specification/archSpec/base/recognizedconstraintmechanisms.dita @@ -2,16 +2,9 @@ Recognized XML-document grammar mechanisms - - The DITA standard recognizes the following XML-document grammar - mechanisms by which conforming DITA vocabulary modules and document types can be constructed: - document type declarations (DTDs), XML Schema declarations (XSDs), and RELAX NG - grammars. - Conforming DITA document types and vocabulary modules can be - constructed using several XML document-grammar mechanisms. The DITA specification provides - coding requirements for DTDs and RNG; it also includes grammar files constructed using those - mechanisms. - + Conforming DITA document types and vocabulary modules can be constructed using several + XML document-grammar mechanisms. The DITA specification provides coding requirements for DTDs + and RNG; it also includes grammar files constructed using those mechanisms. @@ -20,15 +13,9 @@ -

            This specification defines implementation requirements for all of these - document grammar mechanisms. The OASIS DITA Technical Committee recognizes that other XML - grammar languages might provide similar modularity and extensibility mechanisms. However, - because the Technical Committee has not yet defined implementation requirements for those - languages, their conformance cannot be determined.

            Of these document-grammar mechanisms, RELAX NG grammars offer the easiest-to-use syntax and the most precise constraints. For this reason, the RELAX NG definitions of the standard DITA - vocabularies are the normative versions. The DTD and XSD versions - shipped by OASIS are generated from the RELAX NG version using open source tools.

            + vocabularies are the normative versions.

             diff --git a/specification/archSpec/base/relax-ng-coding-doctype-shell.dita b/specification/archSpec/base/relax-ng-coding-doctype-shell.dita index a17691cc..fc500a0e 100644 --- a/specification/archSpec/base/relax-ng-coding-doctype-shell.dita +++ b/specification/archSpec/base/relax-ng-coding-doctype-shell.dita @@ -20,7 +20,7 @@

            Because RELAX NG modules are self-integrating, RNG-based document-type shells only need to - include vocabulary modules and element-configuration modules (constraints and + include vocabulary modules and element-configuration modules (constraint and expansion).

            An RNG-based document-type shell contains the following sections:

              @@ -73,7 +73,7 @@
              Element-type configuration integration

              This section of the document-type shell contains includes for element-type configuration modules (constraints and expansions). + >element-type configuration modules (constraint and expansion). Because the element-configuration module imports the module that it override, any module that is configured in this section (including the base topic or map diff --git a/specification/archSpec/base/relax-ng-coding-element-types.dita b/specification/archSpec/base/relax-ng-coding-element-types.dita index d1955b1a..8db8baea 100644 --- a/specification/archSpec/base/relax-ng-coding-element-types.dita +++ b/specification/archSpec/base/relax-ng-coding-element-types.dita @@ -72,13 +72,13 @@

              tagname.content
              Defines the complete content model for the element tagname. The content model pattern can be overridden in element-configuration - modules (constraints and expansion).
              + modules (constraint and expansion).
              tagname.attributes
              Defines the complete attribute list for the element tagname, except for class. The attribute list declaration can be - overridden in element-configuration modules (constraints and + overridden in element-configuration modules (constraint and expansion).
               @@ -87,12 +87,8 @@ element element whose name value is the element type name and whose content is a reference to the tagname.content and - tagname.attlist patterns. In OASIS grammar - files, the longName attribute in the DITA architecture namespace - is also used to help enable generation of DTD and XSD grammar files. -

              Are we removing the stuff for generating DTD and XSD from the RNG?

              -               + tagname.attlist + patterns.
              tagname.attlist
              diff --git a/specification/archSpec/base/rng-coding-requirements-expansion-modules.dita b/specification/archSpec/base/rng-coding-requirements-expansion-modules.dita index 48eced07..c148f7c3 100644 --- a/specification/archSpec/base/rng-coding-requirements-expansion-modules.dita +++ b/specification/archSpec/base/rng-coding-requirements-expansion-modules.dita @@ -11,22 +11,42 @@ requirementsRNGexpansion expansion modulesRNGcoding requirements - expansion modulesRNGnaming conventions for - patterns - naming conventionsexpansion modulesnaming - conventions for patterns + + RNGcoding requirementsexpansion modules -
              - Expansion modules -

              Expansion modules have the following coding requirements:

              - -

              What needs to go here?

              -               +
              +

              Expansion modules are implemented by importing the expansion modules into a + document-type shell in place of the vocabulary module that the expansion module + modifies. The expansion module itself imports the vocabulary module to be expanded; + within the import, the module redefines the patterns as needed to implement the + expansion.

              +

              For example, an expansion module that modifies the content model of + section imports the base module + topicMod.rng. Within that import, it expands the + section.content pattern:

              + <a:documentation>CONTENT MODEL AND ATTRIBUTE LIST OVERRIDES</a:documentation> + <include href="urn:oasis:names:tc:dita:rng:topicMod.rng:2.0"> + <define name="section.content" combine="interleave"> + <optional> + <ref name="title"/> + </optional> + <optional> + <ref name="sectionDesc"/> + </optional> + <zeroOrMore> + <ref name="section.cnt"/> + </zeroOrMore> + </define> + </include> + </div> +

              Note that the specialized element sectionDesc must be + declared in an element domain module that also is integrated into the document-type + shell.

              diff --git a/specification/archSpec/base/rules-document-type-shells.dita b/specification/archSpec/base/rules-document-type-shells.dita index 3496500d..2e46a237 100644 --- a/specification/archSpec/base/rules-document-type-shells.dita +++ b/specification/archSpec/base/rules-document-type-shells.dita @@ -20,9 +20,9 @@
              XML grammars
              -

              While the DITA specification only defines coding requirements for DTD, RELAX NG, and - XML Schema documents, conforming DITA documents MAY - use other document-type constraint languages, such as Schematron.

              +

              While the DITA specification only defines coding requirements for DTD and RELAX NG, + conforming DITA documents MAY use other + document-type constraint languages, such as Schematron.

               @@ -30,8 +30,8 @@

              With two exceptions, a document-type shell MUST NOT directly define element or attribute types; it only includes vocabulary and element-configuration modules (constraints and expansions). The exceptions - to this rule are the following:

                + >and element-configuration modules (constraint and expansion). The exceptions to + this rule are the following:
                • The ditabase document-type shell directly defines the dita element.
                • RNG-based shells directly specify values for the specializations diff --git a/specification/archSpec/base/specialization-including-non-dita-content.dita b/specification/archSpec/base/specialization-including-non-dita-content.dita index 8261fb25..95d6cc1f 100644 --- a/specification/archSpec/base/specialization-including-non-dita-content.dita +++ b/specification/archSpec/base/specialization-including-non-dita-content.dita @@ -61,7 +61,7 @@ The following statement needs to be updated to refer to the eventual final name of the DITA-techcomm package.

                  For more information, see the svgDomain.mod file that is shipped with - the OASIS DITA distributions. For an example of including the SVG domain in a document type + the OASIS DITA distributions. For an example of including the SVG domain in a document-type shell, see task.dtd.

                  diff --git a/specification/archSpec/base/specialization-specializations-attribute.dita b/specification/archSpec/base/specialization-specializations-attribute.dita index 86dc5adb..34b885d9 100644 --- a/specification/archSpec/base/specialization-specializations-attribute.dita +++ b/specification/archSpec/base/specialization-specializations-attribute.dita @@ -4,10 +4,10 @@ <xmlatt>specializations</xmlatt> attribute rules and syntax The specializations attribute enables processors to determine what - attribute extensions are available in a document. The attribute is declared on the root element - for each topic or map type. Each attribute domain defines a token to declare the extension; the - effective value of the specializations attribute is composed of these - tokens. + attribute specializations are available in a document. The attribute is declared on the root + element for each topic or map type. Each attribute domain defines a token to declare the + extension; the effective value of the specializations attribute is composed of + these tokens. diff --git a/specification/archSpec/base/specialization-vocabulary-modules.dita b/specification/archSpec/base/specialization-vocabulary-modules.dita index c9e97096..76840290 100644 --- a/specification/archSpec/base/specialization-vocabulary-modules.dita +++ b/specification/archSpec/base/specialization-vocabulary-modules.dita @@ -27,12 +27,17 @@
                  structural module
                  A vocabulary module that defines a top-level map or topic type. Structural modules also can define specializations of, or reuse elements from, domain or other structural modules. - When this happens, the structural module becomes dependent.
                  + When this happens, the structural module becomes dependent. +

                  The second and third sentence in the definition are problematic, especially the third + sentence. We should clarify which structural modules becomes dependent, and what is in + dependent on.

                  +
              element domain module
              A vocabulary module that defines one or more specialized element types that can be - integrated with maps or topics.
              + integrated into maps or topics.
              attribute domain module
              diff --git a/specification/archSpec/base/using-relax-ng.dita b/specification/archSpec/base/using-relax-ng.dita index fb3c31cf..1e7af993 100644 --- a/specification/archSpec/base/using-relax-ng.dita +++ b/specification/archSpec/base/using-relax-ng.dita @@ -17,12 +17,10 @@
              Easy use of foreign markup
              The DITA grammar files maintained by OASIS depend on this feature of RELAX NG in order - to capture metadata about document-type shells and modules; such - metadata is used to generate the DTD- and XSD-based versions of the grammar - files.

              The foreign vocabulary feature also can be used to include Schematron - rules directly in RELAX NG grammars. Schematron rules can check for patterns that either - are not expressible with RELAX NG directly or that would be difficult to - express.

              + to capture metadata about document-type shells and modules.

              The foreign vocabulary + feature also can be used to include Schematron rules directly in RELAX NG grammars. + Schematron rules can check for patterns that either are not expressible with RELAX NG + directly or that would be difficult to express.
              RELAX NG div element