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.
- - First, the DITA architect creates the attribute domain module for the
- cell-purpose attribute:
+
-
+
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."
- The DITA architect updates the catalog.xml file to include the
- expansion module.
+ 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)."
+
- 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 a8ede1a0..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
@@ -119,6 +119,21 @@
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."
+ 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 @domainsResponse 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 @@
- 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
+ was specialized after generalization
- A set of attributes that are the same or a subset of those of the element from which it
- was specialized
+ was specialized, except for specializations of base or
+ props
- 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.