From 09b2c3edccc31c4863d022bb9d7a98f7c9001fa8 Mon Sep 17 00:00:00 2001 From: Kristen James Eberlein Date: Tue, 18 May 2021 08:28:49 -0400 Subject: [PATCH 1/2] Added draft comment with feedback from Robert Anderson --- ...g-requirements-for-element-configuration-modules.dita | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita b/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita index a8ede1a0..73142733 100644 --- a/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita +++ b/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita @@ -119,6 +119,15 @@

Need an example of this. And do we really want to recommend that people do this? When would doing this make sense/be a best practice?

+

Comment from Robert Anderson, 17 May 2021: " I think you would + most likely want to chain them if you're reusing someone else's + constraint. For example, if someone wants to use the strict task + from OASIS but also wants to constrain <step>, they could + import their module to constrain step, which then imports the + OASIS constraint for taskbody, which imports the core task + module. I find it hard to imagine chaining more than a couple, + because every one you add becomes more specific to your + configuration."

From 300ad09c7fe7c471b5118a7597a469d66266e93d Mon Sep 17 00:00:00 2001 From: Kristen James Eberlein Date: Mon, 14 Jun 2021 14:05:07 -0400 Subject: [PATCH 2/2] Updated based on stage 3 review comments --- ...n-attribute-to-certain-table-elements.dita | 36 ++++++++++++++--- ...nstraints-processing-interoperability.dita | 20 +++++----- .../archSpec/base/document-type-shells.dita | 4 +- .../archSpec/base/expansion-module-rules.dita | 24 +++++++++++ .../base/overview-of-expansion-modules.dita | 2 +- ...nts-for-element-configuration-modules.dita | 6 +++ .../base/specialization-class-attribute.dita | 26 +++++++----- .../base/specialization-rules-elements.dita | 18 ++------- ...cialization-specializations-attribute.dita | 40 ++++++++----------- .../specialization-vocabulary-modules.dita | 11 ++--- 10 files changed, 112 insertions(+), 75 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 57dccdf5..382f84c1 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 @@ -18,7 +18,7 @@

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

+ add it to the attribute lists of the following elements:

  • entry
  • row
    • @@ -29,13 +29,28 @@

    The new attribute will be specialized from base; it will have a small set of tokens that can be values for the new attribute.

    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 separate each + 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. First, the DITA architect creates the attribute domain module for the - cell-purpose attribute: +
    2. +

      Comments by Eliot Kimber:

      +

      [Re defining the attribute]: I don't really see the value in having the + "-expansion" distinction here--whether to use this as a global attribute or + through extension is really up to the doc type shell author. The definer of + the attribute domain may intend for it to be used only on specific element + types but that's not really their choice to make."

      +

      [Re the entity to be used in the @specializations attribute]: "Should there + be leading and trailing space in the replacement text?"

      +

      [Re adding the attribute to the elements]: "I first thought we shouldn't + allow this specialization-and-integration-in-one kind of module but I + convinced myself it's OK. However, we still need an example of not doing + this, for example, taking an *existing* attribute domain and using a + separate extension module to allow it in specific places, omitting the usual + global integration."

      +       First, the DITA architect creates the attribute domain module for + the cell-purpose attribute: acme-cellPurposeAttExpansion.ent.<!-- Define the attribute --> <!ENTITY % cellPurposeAtt-d-attribute-expansion "cell-purpose (sale | out-of-stock | new | last-chance | inherit | none) #IMPLIED" @@ -53,7 +68,11 @@ attribute definition entity ends in -expansion; this indicates that this is an expansion attribute and should not be included in the base-attribute-extensions entity in the - document-type shell. +

      Comment by Eliot Kimber: "See my comment above: I don't think we should + do this."

      +

      Comment by Robert Anderson: "[The note] should clarify that this entity is totally optional -- only useful here because we're adding the same attribute @@ -61,7 +80,12 @@ attribute to one element, you wouldn't want this entity."

    3. The DITA architect updates the catalog.xml file to include the - expansion module.
      4. + expansion module. +

      Comment by Eliot Kimber: "This is something almost everybody *would* do but + it's not actually required since the use of catalogs is not required by DITA + or by the use of DTDs generally, at least in theory (and in actual fact if + you are an Author/Editor user, which doesn't support catalogs)."

      +
    4. The DITA architect integrates this module into the document-type shell.<!-- ============================================================= --> <!-- DOMAIN ATTRIBUTES DECLARATIONS --> diff --git a/specification/archSpec/base/constraints-processing-interoperability.dita b/specification/archSpec/base/constraints-processing-interoperability.dita index 9f13193a..45aa73ce 100644 --- a/specification/archSpec/base/constraints-processing-interoperability.dita +++ b/specification/archSpec/base/constraints-processing-interoperability.dita @@ -23,16 +23,6 @@ unconstrained document type with an optional shortdesc element. Thus, the content processing for topic still works when topic is constrained to require a short description.

      -

      A constrained document type allows only a subset of the possible instances of the unconstrained - 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 @@ -41,5 +31,15 @@ a shortdesc element. However, if the task document type also has been constrained to require the shortdesc element, it is compatible with the constrained topic document type.

      + +

      For DITA 2.0, we've removed the requirement to add tokens for constraints; accordingly I + removed the following paragraph:

      +

      "A constrained document type allows only a subset of the possible instances of the + unconstrained 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."

      +

      Does this topic make sense without that paragraph? How do we need to rework it? Does it need + to cover anything about

      +       diff --git a/specification/archSpec/base/document-type-shells.dita b/specification/archSpec/base/document-type-shells.dita index 98f2a3ac..1b2ed88f 100644 --- a/specification/archSpec/base/document-type-shells.dita +++ b/specification/archSpec/base/document-type-shells.dita @@ -17,8 +17,8 @@

      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 + be validated using most 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 diff --git a/specification/archSpec/base/expansion-module-rules.dita b/specification/archSpec/base/expansion-module-rules.dita index 1a1f421b..c402e265 100644 --- a/specification/archSpec/base/expansion-module-rules.dita +++ b/specification/archSpec/base/expansion-module-rules.dita @@ -20,6 +20,12 @@ sentence, maybe at the top: "The generalized form of an expanded element's content model must match that of the unexpanded content model." All of what follows stems from this statement."

      +

      Comment by Eliot Kimber: "I think this is an expansion of the suggested qualification + of expansion I suggested for a much earlier point in the spec. I'm not sure it's + necessary to go into this level of detail because the constraints on expansion + should be clear based on the "no less constrained" requirement. That said, it's + always helpful to have examples. Maybe this is better represented as a set of + non-normative examples?"

      @@ -51,6 +57,11 @@ child of <ol>, and then make all following list items optional. It's valid because every list has at least one list item (that specialized thing), but it changes lists to make a required <li> optional."

      +

      Comment from Eliot Kimber: "I would say "violate" here, since per + Robert's comment, you can change the ordinality as long as the result is + consistent with the original. If A is only allowed before B you can't + change that but if A and B are in an OR group you can put them into a + sequence by extension."

      For example, a DITA architect wants to add a new specialization of @@ -72,6 +83,19 @@ alternate title takes its place, which again, we might need to redefine "ordinality" as "DITA ordinality" to cover specialization?"

      +

      Comment from Eliot: "Using title in section as an example is both + problematic but also very instructive. It's problematic because the + grammar is *less constrained* than the prose of the specification, + so the rule as stated in Kris' text is correct--the *prose* doesn't + allow <title> anywhere except as the first child of <section>, + so the solution proposed is correct, in particular, the requirement + to make a choice between <title> and the <specialization>, + *because of the prose-imposed rule*, a rule not expressed in the + grammars. A better example, or at least a more obvious one, would be + an expansion of an element whose base content model is a sequence + (i.e., prolog). That said, it's probably useful to focus on + <section> for this because so many people don't understand this + subtlety of <section>."

      diff --git a/specification/archSpec/base/overview-of-expansion-modules.dita b/specification/archSpec/base/overview-of-expansion-modules.dita index b67a73c2..b6912b12 100644 --- a/specification/archSpec/base/overview-of-expansion-modules.dita +++ b/specification/archSpec/base/overview-of-expansion-modules.dita @@ -27,7 +27,7 @@ p, but it is available only within section.

      The elements must be defined in a separate element domain that declares the - content model and attributes list for the new elements.

      + content models and attribute lists for the new elements.

       diff --git a/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita b/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita index 73142733..8e75be1c 100644 --- a/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita +++ b/specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita @@ -128,6 +128,12 @@ module. I find it hard to imagine chaining more than a couple, because every one you add becomes more specific to your configuration."

      +

      Comment from Eliot Kimber, 18 May 2021: "I would be tempted to + just drop this discussion entirely. I think it's an edge case + for the reasons Robert gives. It's also inherent in the way RNG + works: anyone who understands RNG well enough to do this + understands it enough to know that they *can* do it--we don't + have to tell them how to do it (or that it's possible)."

      diff --git a/specification/archSpec/base/specialization-class-attribute.dita b/specification/archSpec/base/specialization-class-attribute.dita index f2d7b58a..2ea0da25 100644 --- a/specification/archSpec/base/specialization-class-attribute.dita +++ b/specification/archSpec/base/specialization-class-attribute.dita @@ -50,16 +50,22 @@
      Rules - Question about the following statement. - If a topic has no integrated attribute domains in 2.0, the value of @specializations - will be empty. Is this really a MUST? Should we clarify to indicate that this must - be declared in the grammar, but does not necessarily need to have a value - I know - that has caused confusion in the past for a tool that reported errors for empty @domains -

      The root element of every topic and map MUST declare - the following attributes:

        -
      • class
        • -
      • specializations
        • -

      + Question about the following statement. If a topic has no + integrated attribute domains in 2.0, the value of @specializations will be empty. Is this + really a MUST? Should we clarify to indicate that this must be declared in the grammar, but + does not necessarily need to have a value - I know that has caused confusion in the past for + a tool that reported errors for empty @domains

      Response by Eliot Kimber, 18 May 2021:

      +

      If @specializations is only relevant to attribute specializations then I think it would + be sensible to allow it to be omitted, with an omitted @specializations being equivalent + to specializations="" (empty or whitespace-only value).

      +

      The counter to that approach is that you can't easily distinguish between really having + no attribute specializations and just forgetting to provide @specializations, but in + that case I think you'd get runtime failures if you actually had specializations that + weren't declared (i.e., your @props specializations aren't recognized so things don't + filter correctly).

      +

      Seems like an edge case in practice since DITA defines a number of out-of-the box + attribute specializations, including now all of the original conditional attributes.

      +

      Every DITA element (except the dita element that is used as the root of a ditabase document) MUST declare a class attribute.

      diff --git a/specification/archSpec/base/specialization-rules-elements.dita b/specification/archSpec/base/specialization-rules-elements.dita index e6bd22dd..44cdd368 100644 --- a/specification/archSpec/base/specialization-rules-elements.dita +++ b/specification/archSpec/base/specialization-rules-elements.dita @@ -18,25 +18,13 @@
    5. A properly-formed class attribute that specifies the specialization hierarchy of the element
    6. A content model that is the same or less inclusive than that of the element from which it - was specialized
      7. + was specialized after generalization
    7. A set of attributes that are the same or a subset of those of the element from which it - was specialized
      8. + was specialized, except for specializations of base or + props
    8. Values or value ranges of attributes that are the same or a subset of those of the element from which it was specialized
- -

OK, what verbiage do we want to add here to cover what we permit with expansion - modules?

-

Suggestions from Chris Nitchie:

-
    -
  • Modify the 2nd bullet point to add "... after generalization. Specializations of - elements from the base element's content model are allowed, so long as they are only - allowed in the same location in the content model as the elements from which they are - specialized."
    • -
  • Modify the 3rd bullet point to add ""... except for specializations of @props or - @base."
    • -
-

DITA elements are never in a namespace. Only the DITAArchVersion attribute is in a DITA-defined namespace. All other attributes, except for those defined by the XML standard, are in no namespace.

diff --git a/specification/archSpec/base/specialization-specializations-attribute.dita b/specification/archSpec/base/specialization-specializations-attribute.dita index 34b885d9..0515ae0a 100644 --- a/specification/archSpec/base/specialization-specializations-attribute.dita +++ b/specification/archSpec/base/specialization-specializations-attribute.dita @@ -23,34 +23,28 @@
Syntax and rules -

The props and base attributes are the only two core - attributes available for specialization. Each specialization of one of these attributes + attributes available for specialization.

+

Each specialization of the props and base attributes MUST provide a token for use by the specializations attribute.

-
- -
attribute domains
-
-

The specializations token for an attribute specialization begins - with either props or base followed by a slash, - followed by the name of the new attribute:

- '@', props-or-base, ('/', attname)+ -

For example:

    -
  • If props is specialized to create myNewProp, - this results in the following token: @props/myNewProp
    • -
  • If base is specialized to create myFirstBase, - this results in the following token: @base/myFirstBase
    • -
  • If that specialized attribute myFirstBase is further - specialized to create mySecondBase, this results in the following - token: @base/myFirstBase/mySecondBase
    • -

-
- -
+

The specializations token for an attribute specialization begins with + either props or base followed by a slash, followed by the + name of the new attribute:

+ '@', props-or-base, ('/', attname)+ +

For example:

    +
  • If props is specialized to create myNewProp, this + results in the following token: @props/myNewProp
    • +
  • If base is specialized to create myFirstBase, this + results in the following token: @base/myFirstBase
    • +
  • If that specialized attribute myFirstBase is further specialized to + create mySecondBase, this results in the following token: + @base/myFirstBase/mySecondBase
    • +

- Example: Task with multiple domains + Example: <xmlatt>specializations attribute for </xmlatt> a task with multiple + domains

In this example, a document-type shell integrates the task structural module and the following domain modules:

diff --git a/specification/archSpec/base/specialization-vocabulary-modules.dita b/specification/archSpec/base/specialization-vocabulary-modules.dita index 76840290..7a40d1ad 100644 --- a/specification/archSpec/base/specialization-vocabulary-modules.dita +++ b/specification/archSpec/base/specialization-vocabulary-modules.dita @@ -25,14 +25,7 @@
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. -

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.

-
+
A vocabulary module that defines a top-level map or topic type.
element domain module
@@ -72,5 +65,7 @@ >MUST ultimately be specialized from elements defined by or used in the map module. Maps share some element types with topics but no map-specific elements can be used within topics.

+

Structural modules also can define specializations of, or reuse elements from, domain or + other structural modules. When this happens, the structural module becomes dependent.