diff --git a/specification/archSpec/base/aboutconditionalprocessing.dita b/specification/archSpec/base/aboutconditionalprocessing.dita index 8ab2378e..54adabf1 100644 --- a/specification/archSpec/base/aboutconditionalprocessing.dita +++ b/specification/archSpec/base/aboutconditionalprocessing.dita @@ -27,34 +27,42 @@
conditional-processing profile
-
A set of rules that are provided to a processor for use at - rendering time. These rules are based on one or more DITAVAL - documents.I'm not certain "conditional processing profile" warrants a - separate definition. I added it after going through some of the - following topics, and seeing a distinctions between a DITAVAL - document and a [set of conditions sent as input to a processor] - – for example, DITA-OT or an editor can apply conditions from - multiple DITAVAL documents as a single conditional processing - profile.
+
A set of rules that are provided to a processor for use at rendering time. These rules + are based on one or more DITAVAL documents.I'm not certain "conditional processing profile" warrants a + separate definition. I added it after going through some of the following topics, and + seeing a distinctions between a DITAVAL document and a [set of conditions sent as input + to a processor] – for example, DITA-OT or an editor can apply conditions from multiple + DITAVAL documents as a single conditional processing profile.

+ TO RESOLVE 11 May 2026: Recommend removing this + term +

DITAVAL document
A document that specifies a set of rules that define which elements to include, exclude, or flag. A DITAVAL document can be a file on the file system, a set of rules stored in memory, or another way of storing information that is expressed using DITAVAL - syntax. + syntax.

Do we need to explicitly mention passthrough in the first sentence, or is passthrough considered to be part of flagging? If the latter, we should explicitly state that in the topic where we give a high-level overview of the sort of rules that can be defined using a DITAVAL document.

- I think it could be - considered a form of flagging. Given that I expect usage is low, and it is so nebulous - ("do this and something might happen, if your rendering format enables it"), I don't - think it deserves a whole topic on its own. Could we broaden the definition of flagging - to say that it also encompasses the "passthrough" value, and then extend the "Flagging" - topic to cover both?
+

+ I think it could be considered a + form of flagging. Given that I expect usage is low, and it is so nebulous ("do this + and something might happen, if your rendering format enables it"), I don't think it + deserves a whole topic on its own. Could we broaden the definition of flagging to + say that it also encompasses the "passthrough" value, and then extend the "Flagging" + topic to cover both? + TO RESOLVE 11 May 2026: How about if we update the + definition of "flagging" below to clarify that this can also include other + modifications to the output, such as preserving DITA attributes in the rendered + output, or through the use of add-outputclass, processing matching + DITA elements as if they had a specified outputclass + attribute. +

+
filtering
@@ -65,14 +73,18 @@

Do we need to broaden the definition of filtering and mention inclusion also?

+

+ I'm wary of trying to pin down a broad + term like "including", but I don't really know. The assumption of the spec, and I assumed + of spec readers, was that the DITA content is rendered in some way (in an editor, as HTML, + as PDF, etc), and that by default the DITA content is meant for publishing. For that + reason, we go out of our way to say *not* to render data elements and foreign elements, + but we don't do the reverse for paragraphs, tables, etc.

I'm not sure though, beause + "include" is clearly a value you can specity in DITAVAL.

 + TO RESOLVE 11 May 2026: how about if we just update this to + say "The process of including or excluding content at rendering time" +

- I'm wary of trying to pin down a broad - term like "including", but I don't really know. The assumption of the spec, and I assumed of - spec readers, was that the DITA content is rendered in some way (in an editor, as HTML, as - PDF, etc), and that by default the DITA content is meant for publishing. For that reason, we - go out of our way to say *not* to render data elements and foreign elements, but we don't do - the reverse for paragraphs, tables, etc.

I'm not sure though, beause "include" is clearly a - value you can specity in DITAVAL.
flagging
diff --git a/specification/archSpec/base/aboutditavaldocuments.dita b/specification/archSpec/base/aboutditavaldocuments.dita index c63596df..9ca08588 100644 --- a/specification/archSpec/base/aboutditavaldocuments.dita +++ b/specification/archSpec/base/aboutditavaldocuments.dita @@ -31,6 +31,23 @@ a good conceptual overview with supporting details. Given the complexity of conditional processing, I think that is what we need here.

+

+ TO RESOLVE 11 May 2026: how about if we add a follow-up + paragraph that says "the behaviors above can be associated with the following actions"

    +
  1. Instruct processors to include matching content
    2. +
  2. Instruct processors to exclude matching content
    3. +
  3. Instruct processors to mark matching revisions
    4. +
  4. Instruct processors to flag matching content with styles also specified on the + prop or revprop element
    5. +
  5. Instruct processors to pass the matching attribute through to rendered output, when + applicable
    6. +
  6. Instruct processors to treat the matching content as if the element has an + outputclass attribute, with the value specified in the + prop (or revprop?) element using + add-outputclass
    7. +
+

While the DITAVAL markup is not part of the DITA topic or map vocabulary and cannot be specialized, the XML itself is part of the @@ -44,6 +61,10 @@ might include alternate text to indicate the start and end points of revised content or stylistic formatting when no specific flagging behavior is specified.

+

+ TO RESOLVE 11 May 2026: how about we just add that sentence + here, or in the list I suggested adding above +

diff --git a/specification/archSpec/base/basic-dita-terminology.dita b/specification/archSpec/base/basic-dita-terminology.dita index c71be957..2a043a37 100644 --- a/specification/archSpec/base/basic-dita-terminology.dita +++ b/specification/archSpec/base/basic-dita-terminology.dita @@ -15,7 +15,18 @@ assumes that we retain current use of "DITA processor" as used in the specification. Jarno noted that HTML5 uses producer/ consumer, where producer is aimed more at rules for authors / creators of DITA content and consumer is a tool that acts upon - the content.

+ the content.

+ TO RESOLVE 11 May 2026: this is a hard one. How + about we add the term but with a broad definition stating that a processor is an + implementation of DITA that renders DITA content or implements features of the + DITA specification. This can include editors that attempt to render DITA + content as anything other than plain text, processors that render DITA content + as some other format, content management systems that process relationships + between DITA documents, and other systems that attempt to handle DITA content as + anything other than plain XML.

Or, if we can't come up with wording that works + with that, just skip this and not define a DITA + processor.

+

DITA document
@@ -34,8 +45,12 @@ ONE document with sibling topics. Also, not to over-complicate, but an ordinary topic also allows sibling topics (as children), so what really distinguishes this is that it allows "root" - siblings, but I don't think we have a word for - that. + siblings, but I don't think we have a word for that.

+ TO RESOLVE 11 May 2026: + recommend replacing with "...which cannot be + specialized, but which allows for a DITA document with + multiple root-level sibling topics" +

@@ -66,13 +81,23 @@

Suggest removing the last sentence of the definition. It uses the word 'must'; also, it needs to be better aligned with the topic about architectural attributes.

+

+ Having @class is such a core part of being a DITA + element that I'd be inclined to keep it, except that 1) we could + just remove "must" (it's a statement of fact, not a rule) and 2) I + am continually confused by the term "exhibit" in this context. Also, + <dita> doesn't have class and is a DITA element, so it's an + oddball. + TO RESOLVE 11 May 2026: suggest we

    +
  1. confirm that somewhere in this spec we do say that you have + to have class, which I'm pretty sure we do, + and then
    2. +
  2. delete the sentence as Kris suggested
    3. +
+

- Having @class is such a core part of being a DITA element that I'd be - inclined to keep it, except that 1) we could just remove "must" (it's a - statement of fact, not a rule) and 2) I am continually confused by the term - "exhibit" in this context. Also, <dita> doesn't have class and is a DITA - element, so it's an oddball. diff --git a/specification/archSpec/base/behaviors.dita b/specification/archSpec/base/behaviors.dita index 4551e8ed..16a47f44 100644 --- a/specification/archSpec/base/behaviors.dita +++ b/specification/archSpec/base/behaviors.dita @@ -7,5 +7,14 @@ navigation; linking; content reuse (using direct or indirect addressing); conditional processing; branch filtering; chunking; and more. In addition, translation of DITA content is expedited through the use of the dir, translate, and - xml:lang attributes. + xml:lang attributes.We need to rewrite this. The "attributes that indicate" is no longer accurate now that + we got rid of @domains. DITA processing is not "affected by" navigation, linking, etc; + those are the features, implied and explicit, that require processing. The translation + attributes now have their own section and are not described in this one.

TO RESOLVE 15 + May 2026: Rewrite to say that DITA enables a lot of features such as automated + navigation and linking, content reuse, and conditional processing. Some of these are + implicit, such as navigation and linking that can be derived from the order of the + map, while other features have explicit processing rules defined in the + specification.

 diff --git a/specification/archSpec/base/branch-filtering-implications-of-processing-order.dita b/specification/archSpec/base/branch-filtering-implications-of-processing-order.dita index 6c6df168..e207730a 100644 --- a/specification/archSpec/base/branch-filtering-implications-of-processing-order.dita +++ b/specification/archSpec/base/branch-filtering-implications-of-processing-order.dita @@ -11,8 +11,10 @@ requirement comes from the fact that the branch filtering process can result in new or renamed keys, key scopes, or URIs that make up the key space.

Do we remember what "relaed attributes" are - in the following note? Can we keep it simple and just say that keyref attribute is - disallowed? + in the following note? Can we keep it simple and just say that keyref attribute is disallowed?

+ TO RESOLVE 11 May 2026: I think it is just keyref, in which + case, we should just say that. Recommend we double check and verify. +

The keyref attribute and related attributes are explicitly disallowed on ditavalref. This prevents any confusion resulting from a keyref that resolves to additional key- or resource-renaming diff --git a/specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita b/specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita index d846fa4e..b798e3a3 100644 --- a/specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita +++ b/specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita @@ -19,6 +19,10 @@

We need to look at the instances of "should" in this topic. Can they be recast? Do we need to introduce RFC-2119 language?

+

+ TO RESOLVE 11 May 2026: just need to do the editorial pass + and clean up each use of should, use RFC if needed +

The semantic role reflects the class hierarchy of the referencing topicref elementWe do not say how or where. For mapgroup, I believe it is only specified here in this topic. I think either we need this as part of every mapgroup element definition, in "Processing expectations", or we - need a clear table here listing every element where this behavior does not - apply.

+ need a clear table here listing every element where this behavior does not apply.

+ TO RESOLVE 11 May 2026: I believe the + impose-role attribute is now available for this, we should say so and + link to the topic about it +

Unless otherwise instructed, a specialized topicref element that references a map supplies a role for the referenced content. This means that, in effect, the class attribute of the referencing element cascades to top-level topicref diff --git a/specification/archSpec/base/chunk-attribute-combine.dita b/specification/archSpec/base/chunk-attribute-combine.dita index a7616c55..e103313d 100644 --- a/specification/archSpec/base/chunk-attribute-combine.dita +++ b/specification/archSpec/base/chunk-attribute-combine.dita @@ -43,6 +43,10 @@

What's the difference between the content of li[3] and [li4]?

+

+ TO RESOLVE 11 May 2026: I think this is resolved, item 3 + was commented out +

diff --git a/specification/archSpec/base/conditional-processing-and-subject-schemes.dita b/specification/archSpec/base/conditional-processing-and-subject-schemes.dita index 1ab4638b..554d641b 100644 --- a/specification/archSpec/base/conditional-processing-and-subject-schemes.dita +++ b/specification/archSpec/base/conditional-processing-and-subject-schemes.dita @@ -8,7 +8,10 @@ Not sure if need this topic. Started to fill in info but it would cover exactly what is in … don't want to duplicate information, - especially normative rules. + especially normative rules.

+ TO RESOLVE 11 May 2026: see if Kris will let me delete this + topic +

diff --git a/specification/archSpec/base/condproc.dita b/specification/archSpec/base/condproc.dita index 21b4d780..59451dad 100644 --- a/specification/archSpec/base/condproc.dita +++ b/specification/archSpec/base/condproc.dita @@ -3,10 +3,8 @@ "concept.dtd"> Conditional processing<!-- (profiling)--> - - Conditional processing is based on attributes specified in the DITA - source. + Conditional + processing is based on attributes specified in the DITA source.

The following content was in the container topic for the DITAVAL @@ -15,17 +13,23 @@

Conditional processing code should provide a report of any attribute values encountered in content that do not have an action associated with them.

- - I'm less - convinced it needs to be a normative statement. I think it can be a - helpful addition to a processor, but it can also be a big annoyance. - If anything about it is normative, I think it needs to be MAY, - allowing processors to choose whether such notification is - appropriate for their use cases. - -

Maybe we should have a topic here in the architectural section - about errors? We could move some of the normative statements about - errors from the element-reference topics to here.

+

+ I'm less convinced it needs to be a + normative statement. I think it can be a helpful addition to a processor, but it can also + be a big annoyance. If anything about it is normative, I think it needs to be MAY, + allowing processors to choose whether such notification is appropriate for their use + cases. + +

Maybe we should have a topic here in the architectural section about errors? We could + move some of the normative statements about errors from the element-reference topics to + here.

+ + TO RESOLVE 11 May 2026: How about if we just add a + statement to the "Expectaions for conditional processing" topic that says a processor + might do this (non-normative), so that it's there as something we can reference but + doesn't add any rules for processors. I really don't think this specific issue should be a + normative rule, whether it is SHOULD or MAY. +

diff --git a/specification/archSpec/base/definition-of-ditamaps.dita b/specification/archSpec/base/definition-of-ditamaps.dita index 2f97a176..172649cf 100644 --- a/specification/archSpec/base/definition-of-ditamaps.dita +++ b/specification/archSpec/base/definition-of-ditamaps.dita @@ -48,8 +48,18 @@ they can be used and reused in multiple different contexts.

provides...book maps"? We could say "The DITA specifications provide" (plural)? That seems simpler for an overview topic than trying to explain "This package has one specialization - and another package [out later] has book - maps"

+ and another package [out later] has book maps"

+ TO RESOLVE 11 May 2026: + suggest we update to say that the base DITA + specification includes the structure for generic + maps and topics, as well as the specialized subject + scheme, while the related DITA for Technical Content + specification includes several specialized map and + topic types, such as creating concept, task, + reference, and troubleshooting topics, as well as + book maps to represent printed or book-oriented + publications. +

DITA maps establish relationships through the nesting of topicref elements and the application of the collection-type attribute. Relationship tables also can be used to associate topics with diff --git a/specification/archSpec/base/determining-effective-attribute-values.dita b/specification/archSpec/base/determining-effective-attribute-values.dita index caa5a5c4..87c8dfb3 100644 --- a/specification/archSpec/base/determining-effective-attribute-values.dita +++ b/specification/archSpec/base/determining-effective-attribute-values.dita @@ -29,6 +29,12 @@ evaluated.

The following note is problematic. It contains a normative statement, but we explicitly state that notes are non-normative.

Discussed at TC call on 28 May 2019.

+

+ TO RESOLVE 11 May 2026: I think + this is the hardest bit we have left. We need to dig up those + notes from 2019 to find out what the TC said + there. +

The processing-supplied default values do not cascade to other maps. For example, most processors will supply a default value of toc="yes" when no toc attribute is diff --git a/specification/archSpec/base/dita-map-processing.dita b/specification/archSpec/base/dita-map-processing.dita index d3f2bdf1..94875656 100644 --- a/specification/archSpec/base/dita-map-processing.dita +++ b/specification/archSpec/base/dita-map-processing.dita @@ -4,4 +4,15 @@ DITA map processing Introduction to this chapter to be written later, when content is more stable. + + I cannot entirely remember the history + of this section. I believe it was largely created as a placeholder for a bunch of + missing topics about general map usage / processing. Those topics have now been added, + but have overlap with topics in "DITA Processing". And at this point I'm not clear on + the distinction between this section (DITA map processing) and the other (DITA + processing). I don't think there is one, I think this was a temporary section created as + a placeholder for new content, that is now adding confusion.

TO RESOLVE 15 May 2026: I + think the top level sections within this section should be merged into the more + general "DITA processing" section.

 + diff --git a/specification/archSpec/base/dita-maps-and-their-usage.dita b/specification/archSpec/base/dita-maps-and-their-usage.dita index 5ffe80dc..651f0802 100644 --- a/specification/archSpec/base/dita-maps-and-their-usage.dita +++ b/specification/archSpec/base/dita-maps-and-their-usage.dita @@ -18,6 +18,12 @@ looking at the 104 references to "linking".)"

Can we please add a related link [from the related-links topic] to the related-links section of the spec?

+

+ TO RESOLVE 11 May 2026: Sure, add a link. I've now + gone through the full "topic wish list" from this page, we still need to check + that it doesn't overlap with all the sections called out below, then delete the + TODO section and table. +

TODO: Current topics with applicable content diff --git a/specification/archSpec/base/ditaaddressing.dita b/specification/archSpec/base/ditaaddressing.dita index d4357256..640fb201 100644 --- a/specification/archSpec/base/ditaaddressing.dita +++ b/specification/archSpec/base/ditaaddressing.dita @@ -4,11 +4,15 @@ DITA addressing - +

This needs a complete redo to be an effective introduction to the current content.

+

+ TO RESOLVE 11 May 2026: suggest asking our magic robot for + a good overview, and if it cannot give us a good starting point for the content, just go + with what we have. +

diff --git a/specification/archSpec/base/ditamap-attributes.dita b/specification/archSpec/base/ditamap-attributes.dita index d8a146f5..22edcda0 100644 --- a/specification/archSpec/base/ditamap-attributes.dita +++ b/specification/archSpec/base/ditamap-attributes.dita @@ -26,15 +26,18 @@ - We currently redefine a lot of - attributes in this topic that are more comprehensively defined in the - element reference; we need to reconcile those that are defined - differently and ideally reuse definitions.
-

Kris Eberlein, 28 September 2022

-

I alphabeticized the attributes in this topic. I also added them - to draft comments in the definitions in the "Attributes" topics, - so that we could consider them side-by-side.

-
+ We currently redefine a lot of attributes in this topic that are + more comprehensively defined in the element reference; we need to reconcile those that + are defined differently and ideally reuse definitions.
+

Kris Eberlein, 28 September 2022

+

I alphabeticized the attributes in this topic. I also added them to draft + comments in the definitions in the "Attributes" topics, so that we could + consider them side-by-side.

+

+ TO RESOLVE 11 May 2026: compare side-by-side, set + up conref level reuse if we can, and if not, just make sure they do not conflict + and move on. +

DITA maps often encode structures that are specific to a particular medium or output, for example, Web pages or a PDF document. Attributes, such as @@ -42,6 +45,11 @@ processors interpret the DITA map for each kind of output.

The following paragraph seems off ...

+

+ TO RESOLVE 11 May 2026: I think I know what it + was going for, but at this point I think just delete the + paragraph +

Many of the following attributes are not available in DITA topics; individual topics, diff --git a/specification/archSpec/base/ditamarkup.dita b/specification/archSpec/base/ditamarkup.dita index 91d1af28..c2d6f8d1 100644 --- a/specification/archSpec/base/ditamarkup.dita +++ b/specification/archSpec/base/ditamarkup.dita @@ -17,6 +17,10 @@

This is not the final location for this content, nor is the umbrella title of "DITA markup" the correct title. Thoughts on where this content should go very welcome ...

+

+ TO RESOLVE 11 May 2026: I can't find this topic used in our + current hierarchy. Suggest deleting from the repo. +

diff --git a/specification/archSpec/base/document-type-shells.dita b/specification/archSpec/base/document-type-shells.dita index 32365cfb..a8d3e228 100644 --- a/specification/archSpec/base/document-type-shells.dita +++ b/specification/archSpec/base/document-type-shells.dita @@ -46,6 +46,10 @@

The illustration needs to be updated to include expansion modules.

WEK 15 Oct 2022: Updated image source PPTX and PNG file

+

+ TO RESOLVE 11 May 2026: I think this is + done? +

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 diff --git a/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita b/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita index e231e536..2495acd3 100644 --- a/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita +++ b/specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita @@ -69,6 +69,12 @@ entities, sectionDesc-d-p-expansion and sectionDesc - that seems like a leftover extra entity from the domain days that does not really make sense here?"

+

+ TO RESOLVE 11 May 2026: I want + to delete the extra "expansion" entity, I think it's not + used for anything now that we got rid of + domains +

When the content model for section is redefined in the expansion module, it references the parameter @@ -96,6 +102,12 @@ why do we use the "expansion" entity and not the element name? I would expect the element name here with the other element names."

+

+ TO RESOLVE 11 May 2026: We + should switch this to use the element name, it should work + like other specialized elements in a content + model +

Note that this expansion module also constrains the content model of section to only include certain block diff --git a/specification/archSpec/base/evaluating-conditional-processing-attributes.dita b/specification/archSpec/base/evaluating-conditional-processing-attributes.dita index 3c2d2142..a0fce19a 100644 --- a/specification/archSpec/base/evaluating-conditional-processing-attributes.dita +++ b/specification/archSpec/base/evaluating-conditional-processing-attributes.dita @@ -30,7 +30,10 @@ (since it applies to extendedProd). The second list item is still included; even though it does apply to extendedProd, it also applies to basicProd, which was not excluded.

Probably want the following bit to become - a screen capture + a screen capture

+ TO RESOLVE 11 May 2026: If someone wants to put in a screen + capture, great, otherwise just go with this +

The result will look something like the following:

ADMIN Set the configuration options:

  • Set your blink rate
    • diff --git a/specification/archSpec/base/example-chunk-managing-links.dita b/specification/archSpec/base/example-chunk-managing-links.dita index f3dff776..c7b74a76 100644 --- a/specification/archSpec/base/example-chunk-managing-links.dita +++ b/specification/archSpec/base/example-chunk-managing-links.dita @@ -203,6 +203,14 @@
  • A need to have unambiguous links to each instance of the topic

+

+ TO RESOLVE 11 May 2026: Within the context – this is a + paragraph about how implementations can do their own thing. So if you need + "unambiguous" resolution across different implementations, you can't rely on that and + need to consider alternate reuse mechanisms. We can rephrase to just say "...and + unambiguous links to those split topics that resolve the same way across all DITA + implementations" +

diff --git a/specification/archSpec/base/example-contraints-correct-machinery-task-constraint.dita b/specification/archSpec/base/example-contraints-correct-machinery-task-constraint.dita index ea3ab6de..4f8ba048 100644 --- a/specification/archSpec/base/example-contraints-correct-machinery-task-constraint.dita +++ b/specification/archSpec/base/example-contraints-correct-machinery-task-constraint.dita @@ -11,7 +11,10 @@ Is this example still relevant in DITA 2.0? It can still be valid as an example, but I think earlier examples cover the same type of update, and we no longer need to "fix" the machinery task in 2.0. If it is still necessary, it probably needs to - be moved out of the base. + be moved out of the base.

+ TO RESOLVE 11 May 2026: Recommend deleting this + example +

This example assumes that the information architect has already implemented her own document-type shell for the machinery task information type.
    diff --git a/specification/archSpec/base/example-ditaval-subjectscheme.dita b/specification/archSpec/base/example-ditaval-subjectscheme.dita index cda3a5d8..219e3cd1 100644 --- a/specification/archSpec/base/example-ditaval-subjectscheme.dita +++ b/specification/archSpec/base/example-ditaval-subjectscheme.dita @@ -8,6 +8,10 @@ Show a ditaval doc and subject scheme - for example, ditaval that excludes "windows" and subject scheme that makes that cover "win2000 / winvista" etc. Or maybe we should just conref in the full example from + href="processing-controlled-attribute-values.dita"/>

    + TO RESOLVE 11 May 2026: Is it allowed for us to briefly + describe the situation, and then link to that other topic, rather than extending our page + count by reusing the entire example. I would suggest doing that. +

    diff --git a/specification/archSpec/base/example-of-an-index-range.dita b/specification/archSpec/base/example-of-an-index-range.dita index 7daa3807..cc6bc47e 100644 --- a/specification/archSpec/base/example-of-an-index-range.dita +++ b/specification/archSpec/base/example-of-an-index-range.dita @@ -36,18 +36,23 @@ range would continue to the end of the map.

    I think this should be a reportable error or warning since it's almost certainly not the author's intent for a range to span to - the end of the publication. - -

    Eliot, I disagree. If the map is a submap that is consumed by a larger publication (for - example, a map of examples of using keys), I think the default range boundary of "end of - the map" might be entirely appropriate.

    -

    Also, this is example is stating behavior about ranges defined in maps that we do not lay - out in – in particular, that the presence of an end - element in a map signifies that the end-of-the-range is the end of the topic that - contains the end element. This makes good sense to me, but it conflicts with the usual - expectation that an indexterm element in a map (or prolog) is a - point reference to the start of the topic title.

    -     + the end of the publication.

    + +

    Eliot, I disagree. If the map is a submap that is consumed by a larger publication + (for example, a map of examples of using keys), I think the default range boundary of + "end of the map" might be entirely appropriate.

    +

    Also, this is example is stating behavior about ranges defined in maps that we do not + lay out in – in particular, that the presence of an + end element in a map signifies that the end-of-the-range is the end of the + topic that contains the end element. This makes good sense to me, but it conflicts + with the usual expectation that an indexterm element in a map + (or prolog) is a point reference to the start of the topic title.

    + + TO RESOLVE 11 May 2026: Recommend we keep this example + and paragraph as-is, but add a sentence (or add a clause to this sentence) saying that a + processor could report the missing end range (because a processor could totally choose + to do that) +

diff --git a/specification/archSpec/base/example-of-nested-indexterm-elements.dita b/specification/archSpec/base/example-of-nested-indexterm-elements.dita index 31f30e96..fa2d6afb 100644 --- a/specification/archSpec/base/example-of-nested-indexterm-elements.dita +++ b/specification/archSpec/base/example-of-nested-indexterm-elements.dita @@ -5,8 +5,12 @@ This example contains a multilevel indexterm element. - Do we - want to keep or jettison this topic? Enhance it? + Do we want to keep or jettison + this topic? Enhance it?

+ TO RESOLVE 12 May 2026: recommend dropping the topic, it is + not linked in any map, and the only link *to* it is from a draft comment in + "merging-index-elements.dita" +

Given the following indexterm elements:

<indexterm>cheese <indexterm>sheeps milk 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 d91b7653..49612f40 100644 --- a/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita +++ b/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita @@ -57,6 +57,11 @@ cover that in the coding requirements topic. If people start with copying-and-pasting from the module that they are overriding, they won't have that and will get errors.

+

+ TO RESOLVE 12 May 2026: we cover it for attribute + lists. Recommend updating the "overview of coding requirements" for RNG, and add a + comment about how it is used, then delete this draft comment. +

  • They then integrate the constraint module into the document-type shell for topic by adding an diff --git a/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita b/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita index 0f93489a..3c6bf4a5 100644 --- a/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita +++ b/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita @@ -9,6 +9,10 @@

    The following is content that Eliot Kimber suggested be included in the DITA 2.0 specification as part of the review of proposal #647. It has not been edited.

    +

    + TO RESOLVE 12 May 2026: do an editing pass and then mark it + ready for larger TC review +

    A subject scheme map may be included in a map as either a normal sub map or as a peer root map and associated with a key scope on the map diff --git a/specification/archSpec/base/expansion-modules-processing-and-interoperability.dita b/specification/archSpec/base/expansion-modules-processing-and-interoperability.dita index 58145317..0b64287f 100644 --- a/specification/archSpec/base/expansion-modules-processing-and-interoperability.dita +++ b/specification/archSpec/base/expansion-modules-processing-and-interoperability.dita @@ -20,6 +20,22 @@

    And what happens if one wants to apply multiple expansion modules and a constraint to an element type? I'm assuming that they would need to be aggregated into a single element-configuration module.

    +

    + TO RESOLVE 12 May 2026:

      +
    • why? I'd say - why not? if you have an expansion module for @thing1, and + a module for @thing2, both DTD and RNG let you add them independently. + This is because you can have multiple attribute definitions, they are + all combined to create the set of attributes. We should not restrict + this. (We cannot prevent it, and shouldn't say it's invalid.)
      • +
    • For content models - yes, they must be combined, because unlike with + attributes you only have one spot to declare the content model. So if + you want to add 2 things into <section> or <body>, you have one + spot to redeclare that content model.
      • +

    It looks like we used to say this in the following commented-out + paragraph. I'd suggest either restoring that paragraph, maybe with an edit, + or just keep the current language and resolve the comment, because it's just + how grammar files work.

    +

    Constraint modules cannot remove attributes that are contributed by expansion diff --git a/specification/archSpec/base/extending-a-subject-scheme.dita b/specification/archSpec/base/extending-a-subject-scheme.dita index 85d7a2af..2a693cb2 100644 --- a/specification/archSpec/base/extending-a-subject-scheme.dita +++ b/specification/archSpec/base/extending-a-subject-scheme.dita @@ -11,13 +11,16 @@ are extended by the current subject-scheme map. The values in the referenced subject-scheme map are merged with the values in the current subject-scheme map; the result is equivalent to specifying all of the values in a single subject scheme map.

    - I - think we need to make a normative statement about this for DITA 2.0. - I realize that doing so would require developing detailed content - about processing subject scheme maps, since they have different - processing expectations than DITA maps in general. Also, see the - following draft comment (from the 1.3 time frame), which had been - commented out of this topic. + I think we need to make a + normative statement about this for DITA 2.0. I realize that doing so would require developing + detailed content about processing subject scheme maps, since they have different processing + expectations than DITA maps in general. Also, see the following draft comment (from the 1.3 + time frame), which had been commented out of this topic.

    + TO RESOLVE 12 May 2026: I almost think we should just go + with the statement above and leave this as-is, and not place new rules / new restrictions + on schemeref. We state above how it works, restating it with a normative THIS IS HOW IT + SHOULD HAPPEN won't change any processors. +

    I added this topic to address comments made by Chris Nitchie in the targeted review. FYI, the paragraph above was in the DITA 1.2 @@ -36,6 +39,12 @@ Chris stated " ... the use of keyref in subject schemes to recombine subject definitions is never covered anywhere."

    We need additional normative content in this topic ...

    +

    + TO RESOLVE 12 May 2026: Agree this isn't how keys work + anywhere, keys were terribly overloaded with subject schemes but it's too late to change + that. I think the text above may suffice (again) for how to handle + schemeref. +

    diff --git a/specification/archSpec/base/flagging.dita b/specification/archSpec/base/flagging.dita index 686fac69..0fac0179 100644 --- a/specification/archSpec/base/flagging.dita +++ b/specification/archSpec/base/flagging.dita @@ -30,6 +30,10 @@ style-conflict topic, where it did not belong. It's general information about how processors should handle flagging.

    +

    + TO RESOLVE 12 May 2026: I think no action is needed, can + remove this draft comment +

    When flagging methods are specified for elements at different levels of the containment hierarchy, the diff --git a/specification/archSpec/base/index-ranges.dita b/specification/archSpec/base/index-ranges.dita index 0bfbde89..eb356a85 100644 --- a/specification/archSpec/base/index-ranges.dita +++ b/specification/archSpec/base/index-ranges.dita @@ -88,6 +88,11 @@ <indexterm>Potato <indexterm end="yellow"/> <indexterm> +

    + TO RESOLVE 12 May 2026: Try to come up with a simple + wording tweak to describe it based on our understanding from long + ago +

  • When index ranges with the same identifier overlap, the effective range is determined by matching diff --git a/specification/archSpec/base/introduction-to-dita.dita b/specification/archSpec/base/introduction-to-dita.dita index 665d20f5..c0801fb4 100644 --- a/specification/archSpec/base/introduction-to-dita.dita +++ b/specification/archSpec/base/introduction-to-dita.dita @@ -29,6 +29,21 @@ non-normative – and point users to the normative coverage of the topic.

    In a parallel move, I think we'll need to move coverage of critical DITA attributes into a more prominent place in the spec.

    +

    + TO RESOLVE 12 May 2026: Not sure how best to + resolve this. I don't think we need to explicitly declare "non-normative" just + because it's giving an overview rather than normative RFC rules – most of the + spec isn't made up of RFC rules.

    We could

      +
    • Run a magic robot across it and see if this information is + duplicated elsewhere
      • +
    • If so, either reuse by conref, or make sure that the wording is + consistent, or replace with pointers
      • +
    • and leave it at that, as long as the info is accurate we keep it + here
      • +
    • The critical attributes bit already has additional draft comments + specific to that section
      • +

    +

    diff --git a/specification/archSpec/base/linking-and-addressing-terms.dita b/specification/archSpec/base/linking-and-addressing-terms.dita index 49202105..61c45f04 100644 --- a/specification/archSpec/base/linking-and-addressing-terms.dita +++ b/specification/archSpec/base/linking-and-addressing-terms.dita @@ -41,7 +41,12 @@ rephrase something like this, but not sure where to put the "such as" here:

    An attribute that specifies an address or a that specifies key that resolves to an address.

    or maybe

    An attribute that specifies - an address or that specifies a key.

    + an address or that specifies a key.

    + TO RESOLVE 12 May 2026: how about "An + attribute that specifies an address, such as conref and href, or + specifies an indirect reference to an address, such as conkeyref and + keyref" +

    • diff --git a/specification/archSpec/base/links-between-maps.dita b/specification/archSpec/base/links-between-maps.dita index d4fa699a..3efe3967 100644 --- a/specification/archSpec/base/links-between-maps.dita +++ b/specification/archSpec/base/links-between-maps.dita @@ -16,6 +16,10 @@

    When this topic is reviewed, we should also check the definition of scope="peer" in the scope topic.

    +

    + TO RESOLVE 12 May 2026: I suppose, just make sure + we're consistent with language in that topic +

    The keys that are defined by the peer map belong to any key scopes that are declared on the topicref element that @@ -31,6 +35,11 @@

    Should the following statement about what processors do "when a reference to a peer map cannot be resolved" contain RFC-2119 language?

    +

    + TO RESOLVE 12 May 2026: I don't think so, because + resolution is up to them, and it's meaningless to say processors MAY or SHOULD + recover any way they wish +

    Note the inverse implication; if the peer map is not available, then it is impossible to diff --git a/specification/archSpec/base/merging-index-elements.dita b/specification/archSpec/base/merging-index-elements.dita index 663f4edc..fd34c2dc 100644 --- a/specification/archSpec/base/merging-index-elements.dita +++ b/specification/archSpec/base/merging-index-elements.dita @@ -34,6 +34,13 @@ href="example-of-nested-indexterm-elements.dita"/>)

    What are other critical aspects?

    +

    + TO RESOLVE 12 May 2026: I can't find a reference to + this anywhere in the base spec. I can't remember what prompted it, but if it + goes in, we need to review for accuracy, not sure we want to put much more work + in beyond that

    But to resolve, we need to first determine where this topic + goes and insert it into the map

    +

    Do we make the following RFC-2119 statement for DITA 2.0. Thoughts?

    @@ -41,6 +48,10 @@ the same content are ″merged″ to form a single index entry in the resulting index, and all contributed page numbers are included in that index entry.

    +

    + TO RESOLVE 12 May 2026: Don't care, can make it, or + can say that processors can do this and leave it up to them +

    (For processors that support indexing) If multiple indexterm elements exist that would result in matching index entries, a processor This is the correct behavior. By "identical content" is a little too strict. Probably need to say something like "content that the processor considers to be the same. For example, by normalizing white space."

    +

    + TO RESOLVE 12 May 2026: Same as above, I dont' + really care if it is normative, just needs a bit of a wording + tweak +

    Eliot raised the following scenario in his review of the indexing content:

    @@ -89,6 +105,15 @@ apple

    If a company's styleguide does not want locators on parents of leaf nodes, I'd expect authors to spend time "massaging" index markup in order to generate an index that followed the styleguide requirements.

    +

    + TO RESOLVE 12 May 2026: Do we really want to lay + out all possible options, or just leave this up to processors? If we want to lay + out these options, then we should say that processors can choose how + primary/secondary entries like this are combined, and give all three as examples + of valid cases. I think either 1 or 2 are both perfectly valid, number 3 is + valid if your style guide says "don't do this", and there could be other options + for other formats +

    diff --git a/specification/archSpec/base/metadata-in-maps-and-topics.dita b/specification/archSpec/base/metadata-in-maps-and-topics.dita index 23035f79..e73692bb 100644 --- a/specification/archSpec/base/metadata-in-maps-and-topics.dita +++ b/specification/archSpec/base/metadata-in-maps-and-topics.dita @@ -24,7 +24,9 @@ We should have a related link from this topic to the section on cascading; this is a conceptual topic about metadata and should not repeat the processing rules, but reading this I immediately want to know *which* elements cascade and - how that works. + how that works.

    + TO RESOLVE 12 May 2026: Add that link +

    When the same metadata element or attribute is specified in both a map and a topic, by default the value in the map takes precedence. The assumption is that the for a while now. Based on discussion at today's TC (1 june 2021) this would be interpreted as the title of the source of the quotation - thus the removal of href/reftitle. OK to update accordingly, or does that need - further confirmation from TC? + further confirmation from TC?

    + TO RESOLVE 12 May 2026: Just update + based on that understanding from 2021 +

    diff --git a/specification/archSpec/base/relax-ng-coding-constraint-modules.dita b/specification/archSpec/base/relax-ng-coding-constraint-modules.dita index 151c121d..2e605bf4 100644 --- a/specification/archSpec/base/relax-ng-coding-constraint-modules.dita +++ b/specification/archSpec/base/relax-ng-coding-constraint-modules.dita @@ -42,7 +42,10 @@

    For a more complete example, see strictTaskbodyConstraintMod.rng, delivered with the DITA 1.3 grammar files.

    Need to update the above example statement for 2.0 to refer - to the correct name of the tech comm 2.0 spec. + to the correct name of the tech comm 2.0 spec.

    + TO RESOLVE 13 May 2026: Update to read "delivered with + the DITA 2.0 Technical Content specification." +

    @@ -87,6 +90,11 @@ topicMod.rng.

    Need an example of this

    +

    + TO RESOLVE 13 May 2026: If someone wants to + create this example, great, otherwise we leave it out as we did in + 1.3 +

    diff --git a/specification/archSpec/base/specialization-class-attribute.dita b/specification/archSpec/base/specialization-class-attribute.dita index 3e2d4f3e..cd3c4487 100644 --- a/specification/archSpec/base/specialization-class-attribute.dita +++ b/specification/archSpec/base/specialization-class-attribute.dita @@ -103,6 +103,15 @@

    In addition, it would benefit by an edit that started by asking "What exactly are we trying to convey here? What are the critical points?

    +

    + TO RESOLVE 13 May 2026: Ensure this goes into the + generalization review

    What it's trying to convey: specifically, that you can + specialize new elements within a module that don't come from base, and don't come off + of a new element in the intermediate module. When doing that, you have to say what the + element was in the intermediate module. Basically, the class attribute needs to have a + token for every module that led to this module (regardless of whether the element name + changed along the way).

    +

    The following code sample shows the value of a class attribute for an element in the guiTask module, which is specialized from task. The diff --git a/specification/archSpec/base/specialization-rules-elements.dita b/specification/archSpec/base/specialization-rules-elements.dita index a8fe5d1b..70a5ce43 100644 --- a/specification/archSpec/base/specialization-rules-elements.dita +++ b/specification/archSpec/base/specialization-rules-elements.dita @@ -23,6 +23,12 @@

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

    +

    + TO RESOLVE 13 May 2026: Can we add a sentence to that + same bullet, something like: "When using expansion modules to add a new element to + the content model, the generalized form of any new element is also allowed in the + original content model. +

    • A properly-formed class attribute that @@ -61,6 +67,12 @@ prefix on all names.

      We should consider moving the above note elsewhere.

      +

      + TO RESOLVE 13 May 2026: At this point, I'd be fine leaving + it here, but maybe change the use of "should", like "When domain modules are intended for + wide use, it is a good idea to reduce conflicts with other domains by giving elements very + specific names or using domain-specific prefixes on all names. +

      diff --git a/specification/archSpec/base/subjectSchema.dita b/specification/archSpec/base/subjectSchema.dita index 3e64c02b..ff0e0ccf 100644 --- a/specification/archSpec/base/subjectSchema.dita +++ b/specification/archSpec/base/subjectSchema.dita @@ -61,6 +61,11 @@ resolve as text or links" -- in a way that is clear, accurate, and short enough that it actually gets read. So, I think we need some work on this paragraph.

      +

      + TO RESOLVE 13 May 2026: Can we take out the however, and + maybe have a new paragraph instead of a second sentence, saying that keys bound to a + controlled value do not typically result in links or generated text. +

      diff --git a/specification/archSpec/base/the-key-scope-attribute.dita b/specification/archSpec/base/the-key-scope-attribute.dita index 5e18e446..c75d5c24 100644 --- a/specification/archSpec/base/the-key-scope-attribute.dita +++ b/specification/archSpec/base/the-key-scope-attribute.dita @@ -26,7 +26,11 @@ to merge with existing key scope rules to ensure no duplication / no conflicting content.

      Update Oct 14 2021: there is now a longer example of the non-intersecting behavior in so probably want to - remove the simpler example from this page

      + remove the simpler example from this page

      + TO RESOLVE 13 May 2026: No strong opinion here; could + remove the example or leave it to have something useful in context. Could also add a + related link back/forth between the two topics. +

      All key scopes are contiguous and non-intersecting. Within a root map, two distinct key scopes with the same name have no relationship with each other aside from that implied by their relative locations in the key scope hierarchy. They do not, for diff --git a/specification/archSpec/base/theformatattribute.dita b/specification/archSpec/base/theformatattribute.dita index 7960b20c..5f24dfb8 100644 --- a/specification/archSpec/base/theformatattribute.dita +++ b/specification/archSpec/base/theformatattribute.dita @@ -73,6 +73,17 @@

      I think we need to have an example of the expected processing behaviour. I think it is a good candidate for the new chapter on "DITA map processing".

      +

      + TO RESOLVE 13 May 2026: Not sure which example was + being requested here, but I think

        +
      1. The previous paragraph references reltable behavior; I think we should take + out that line and instead reference the new topic on relationship tables, which + describes this rule. We already have it there + in reltable elementref topic, + and should take out this third description of the rule.
        2. +
      2. The following paragraph mentions a behavior that is undefined, so I don't + think we need an example of expected processing?
        3. +
      +

      diff --git a/specification/archSpec/base/thekeyrefattribute.dita b/specification/archSpec/base/thekeyrefattribute.dita index eb3b917e..2905c53f 100644 --- a/specification/archSpec/base/thekeyrefattribute.dita +++ b/specification/archSpec/base/thekeyrefattribute.dita @@ -22,7 +22,15 @@
    • Overlap with existing content - likely needs to merge, definitely remove duplication
    • This topic uses a key and the langRef links to it from the definition for @keyref, so if this topic goes away, be sure to update that keyref
      • -
    +

    + TO RESOLVE 13 May 2026: Looking at the TOC, it's probably fine + to keep a topic here about the keyref attribute, but maybe we should update the title to + "About the..." or "Using the..." or "Referencing a key name with the..."? Same goes for the + topic a bit further down, "The keyscope attribute"

    Also, based on discussion at the TC + meeting May 12 2026, assuming we stick with the conclusion at that meeting that keyref can + only go to topics (from map) or topics + subelements (from topic), we should definitely call + that out here.

    +

    For elements that only refer to topics or non-DITA resources, the value of the keyref attribute is a key name. For elements that can refer to elements within maps or topics, the value of the keyref diff --git a/specification/archSpec/base/thekeysattribute.dita b/specification/archSpec/base/thekeysattribute.dita index 49cd5e65..7b096d32 100644 --- a/specification/archSpec/base/thekeysattribute.dita +++ b/specification/archSpec/base/thekeysattribute.dita @@ -23,7 +23,10 @@ needs to be here as it defines normative rules about the syntax of a key attribute. The following paragraph comes from reuse-general but in the base spec this is the only use, so should probably be taken out of the reuse file. Need to go over this section more closely now - that attribute content has moved here. + that attribute content has moved here.

    + TO RESOLVE 13 May 2026: Move from "reuse" to just use it here, + and do a quick edit pass to get this ready for TC review. +

    A key cannot resolve to sub-topic elements, although a keyref attribute can do so by combining a key diff --git a/specification/common/reuse-w-lwdita/reuse-map.dita b/specification/common/reuse-w-lwdita/reuse-map.dita index dcdb806d..37b68bf8 100644 --- a/specification/common/reuse-w-lwdita/reuse-map.dita +++ b/specification/common/reuse-w-lwdita/reuse-map.dita @@ -20,6 +20,12 @@

    And then the example should illustrate not just a DITA map creating navigational hierarchy, but also a map that references a key-definition map.

    +

    + TO RESOLVE 13 May 2026: At this point I would probably + leave this as-is – it doesn't discuss keyref but it also doesn't discuss href. I think + it's acceptable for the map to discuss how it creates these relationships between + topics, without discussing the specifics of how to address those topics. +

    A map describes the relationships among a set of DITA topics. @@ -58,6 +64,13 @@ titles are rendered; certainly users get confused about this. And do we cover processing expectations for submaps somewhere?

    +

    + TO RESOLVE 13 May 2026: There is a new topic about this + specific issue. We should add a cross reference to it here, in the following paragraph + that is already filtered for just the base specification / not lwdita. I would leave + the lwdita one alone, unless / until the lwdita spec adds a version of the same + topic. +

    The title element can be used to provide a title for the map. In some scenarios the diff --git a/specification/common/reuse-w-lwdita/reuse-topicmeta.dita b/specification/common/reuse-w-lwdita/reuse-topicmeta.dita index 494c35e7..2a9ee56e 100644 --- a/specification/common/reuse-w-lwdita/reuse-topicmeta.dita +++ b/specification/common/reuse-w-lwdita/reuse-topicmeta.dita @@ -30,12 +30,20 @@ specify metadata about the entire map or for specific topic references? I think that would be useful for readers of the LwDITA spec.

    +

    + TO RESOLVE 13 May 2026: How about a follow up paragraph, + applicable to both specs, that just … says that? "Metadata specified using this (element + / component) can be used at the map level for metadata that is applicable to the entire + map, or at the topic reference level for metadata that applies a topic or branch of a + map." +

    Attributes
    -

    The following attributes are available on this element: .

    +

    The following attributes are available on this element: .

    diff --git a/specification/common/reuse-w-lwdita/reuse-topicref.dita b/specification/common/reuse-w-lwdita/reuse-topicref.dita index 080c247e..ffa2f9da 100644 --- a/specification/common/reuse-w-lwdita/reuse-topicref.dita +++ b/specification/common/reuse-w-lwdita/reuse-topicref.dita @@ -20,7 +20,11 @@ keyref="attributes-common/attr-keys">keys.

    Updated style here to match the common attribute style, but still need to make sure the href topic is updated with the same info - in arch spec. + in arch spec.

    + TO RESOLVE 13 May 2026: Double check the linked topic + to ensure content is consistent, update to reuse content with conref if possible, and + move on. +

    For this element, the href attribute references the resource that is represented by the topicref. See for detailed information on supported values and processing implications. References to diff --git a/specification/introduction/written-specification.dita b/specification/introduction/written-specification.dita index fac4d3a3..22df6a35 100644 --- a/specification/introduction/written-specification.dita +++ b/specification/introduction/written-specification.dita @@ -15,7 +15,11 @@

    The specification contains several parts:

    Reminder to - adjust this to reflect the final organization / actual parts. + adjust this to reflect the final organization / actual parts.

    + TO RESOLVE 13 May 2026: We can already update some + of this but I think this draft comment will be one of the last resolved, when we + are ready with the final structure and the names of each section +

    • Introduction
    • Architectural specification
      • diff --git a/specification/langRef/attributes/attribute-groups.dita b/specification/langRef/attributes/attribute-groups.dita index 7e93c177..5851a488 100644 --- a/specification/langRef/attributes/attribute-groups.dita +++ b/specification/langRef/attributes/attribute-groups.dita @@ -40,11 +40,9 @@
      Architectural attributes -

      This group contains a set of attributes that are defined for - document-level elements such as topic and - map.

      +

      This group contains a set of attributes that are defined for document-level elements such + as topic and map.

      @@ -62,15 +60,17 @@
      Common map attributes -

      This group contains attributes that are - frequently used on map elements.

      +

      This group contains attributes that are frequently used on map + elements.

      I've added draft comments to the attribute definitions in this section that explain how the attribute is defined in the "DITA map attributes" topic.

      +

      + TO RESOLVE 13 May 2026: I think there is nothing to + resolve here, can remove +

      @@ -152,9 +152,8 @@
      Data-element attributes -

      This group contains attributes that are defined on the - data element and its specializations. - This group contains attributes that are defined on the data + element and its specializations.

      @@ -188,10 +187,8 @@
      Display attributes -

      This group contains attributes that affect the - rendering of many elements.

      +

      This group contains attributes that affect the rendering of many + elements.

      @@ -209,10 +206,8 @@
      ID and conref attributes -

      This group contains the attributes that enable the - naming and referencing of elements.

      +

      This group contains the attributes that enable the naming and referencing of + elements.

      @@ -245,6 +240,11 @@

      What is specialized from include? Both base (if any) and technical content ...

      +

      + TO RESOLVE 13 May 2026: Is this a suggestion that we list + the specializations here? They are all in the technical content spec: coderef, svgref, + mathmlref. We could list those but I don't think it is necessary. +

      @@ -259,10 +259,9 @@
    +

    + TO RESOLVE 13 May 2026: Double check each to make + sure the latest content is consistent, and remove the draft comment

    But also … + it might be a good idea to keep this draft comment (and others for the + keys/keyref stuff) until after that section is fully reviewed, so that we have + an easy way to find these "content should be consistent" + issues

    +

    linking (common map attributes)
    -
    Specifies linking characteristics of a topic specific to the - location of this reference in a map. - The text - below matches Specifies linking characteristics of a topic specific to the location of this + reference in a map. + The text below matches 1.3 spec text but I'm - nervous about "cannot link" type definition. It's describing - how to generate links based on the current context in the map - - it's not describing what the topic itself is allowed to - link to, which is how I interpret "can".The - following values are valid:
    + format="html" scope="external">1.3 spec text but I'm nervous about "cannot + link" type definition. It's describing how to generate links based on the current + context in the map - it's not describing what the topic itself is allowed to link to, + which is how I interpret "can".

    + TO RESOLVE 13 May 2026: Yeah we should remove the + can/cannot and replace with a description of the intent here... like, targetonly + "The topic or resource can be the target of any context based linking, but is not + meant to be updated with links related to this context."

    similarly, none could + be "The topic or resource does not participate in any context-based + linking"

    +

    The following values are valid:
    targetonly
    -
    A topic can only be linked to and cannot link to other - topics.
    +
    A topic can only be linked to and cannot link to other topics.
    sourceonly
    -
    A topic cannot be linked to but can link to other - topics.
    +
    A topic cannot be linked to but can link to other topics.
    normal
    -
    A topic can be linked to and can link to other topics. - Use this to override the linking value of a parent topic. -
    +
    A topic can be linked to and can link to other topics. Use this to override the + linking value of a parent topic.
    none
    -
    A topic cannot be linked to or link to other - topics.
    +
    A topic cannot be linked to or link to other topics.
    -
    -

    Here is the content from the "DITA map attributes" - topic:

    +
    +

    Here is the content from the "DITA map attributes" topic:

    linking
    -

    By default, the relationships between the topics - that are referenced in a map are reciprocal:

    +

    By default, the relationships between the topics that are referenced in a map + are reciprocal:

      -
    • Child topics link to parent topics and vice - versa.
      • -
    • Next and previous topics in a sequence link to - each other.
      • +
    • Child topics link to parent topics and vice versa.
      • +
    • Next and previous topics in a sequence link to each other.
    • Topics in a family link to their sibling topics.
      • -
    • Topics referenced in the table cells of the same - row in a relationship table link to each other. A - topic referenced within a table cell does not (by - default) link to other topics referenced in the - same table cell.
      • +
    • Topics referenced in the table cells of the same row in a relationship + table link to each other. A topic referenced within a table cell does not + (by default) link to other topics referenced in the same table cell.
    -

    This behavior can be modified by using the - linking attribute, which enables - an author or information architect to specify how a - topic participates in a relationship. The following - values are valid:

    +

    This behavior can be modified by using the linking + attribute, which enables an author or information architect to specify how a + topic participates in a relationship. The following values are valid:

    linking="none"
    -
    Specifies that the topic does not exist in the - map for the purposes of calculating links.
    +
    Specifies that the topic does not exist in the map for the purposes of + calculating links.
    linking="sourceonly"
    -
    Specifies that the topic will link to its - related topics but not vice versa.
    +
    Specifies that the topic will link to its related topics but not vice + versa.
    linking="targetonly"
    -
    Specifies that the related topics will link to - it but not vice versa.
    +
    Specifies that the related topics will link to it but not vice versa. +
    linking="normal"
    -
    Default value. It specifies that linking will - be reciprocal (the topic will link to related - topics, and they will link back to it).
    +
    Default value. It specifies that linking will be reciprocal (the topic + will link to related topics, and they will link back to it).
    -

    Authors also can create links directly in a topic by - using the xref or - link elements, but in most - cases map-based linking is preferable, because links - in topics create dependencies between topics that can - hinder reuse.

    -

    Note that while the relationships between the topics - that are referenced in a map are reciprocal, the - relationships merely imply reciprocal links in - generated output that includes links. The rendered - navigation links are a function of the presentation - style that is determined by the processor.

    +

    Authors also can create links directly in a topic by using the + xref or link elements, but + in most cases map-based linking is preferable, because links in topics create + dependencies between topics that can hinder reuse.

    +

    Note that while the relationships between the topics that are referenced in a + map are reciprocal, the relationships merely imply reciprocal links in + generated output that includes links. The rendered navigation links are a + function of the presentation style that is determined by the processor.

    +

    + TO RESOLVE 13 May 2026: Ensure there is nothing + conflicting, and add a link from here to the more architectural info that gives + all the details +

    name (data-element attributes)
    -
    Defines a unique name for the object.Do we need to - specify the scope of "unique" here?
    +
    Defines a unique name for the object.Do we need to specify the scope of "unique" here?

    + TO RESOLVE 13 May 2026: ha, it often won't be + unique because you often use the same name for all instances of a specific type of + metadata. Maybe we just get rid of "unique" +

    otherrole
    @@ -796,34 +810,28 @@
    processing-role (common map attributes)
    -
    Specifies whether the referenced - resource is processed normally or treated as a resource that is - only included in order to resolve references, such as key or - content references. The following values are valid:
    +
    Specifies whether the referenced resource is processed + normally or treated as a resource that is only included in order to resolve references, + such as key or content references. The following values are valid:
    normal
    -
    Indicates that the resource is a readable part of the - information set. It is included in navigation and search - results. This is the default value for the +
    Indicates that the resource is a readable part of the information set. It is + included in navigation and search results. This is the default value for the topicref element.
    resource-only
    -
    Indicates that the resource should be used only for - processing purposes. It is not included in navigation or - search results, nor is it rendered as a topic. This is - the default value for the keydef - element.
    +
    Indicates that the resource should be used only for processing purposes. It is + not included in navigation or search results, nor is it rendered as a topic. This + is the default value for the keydef element.
    - +
    -

    For HDITA, the equivalent of - processing-role is +

    For + HDITA, the equivalent of processing-role is data-processing-role.

     @@ -1047,21 +1055,23 @@ (common map attributes)
    Specifies whether the target is available for searching. The following - values are valid: yes, - no, and - -dita-use-conref-target. -

    Here is the content from the "DITA map attributes" - topic:

    + conkeyref="reuse-attributes/inherit-in-map"/> The following values are valid: + yes, no, and + -dita-use-conref-target. +

    Here is the content from the "DITA map attributes" topic:

    search
    -
    Specifies whether the topic is included in search - indexes.
    +
    Specifies whether the topic is included in search indexes.
    +

    + TO RESOLVE 13 May 2026: Update to use the same + description, these are very similar but not exact. If the description is this + short and similar it should be reused with conref. +

    @@ -1103,10 +1113,8 @@
    toc (common map attributes)
    -
    Specifies whether a topic appears in the table of contents - (TOC) based on the current map context. The following - values are valid:
    +
    Specifies whether a topic appears in the table of contents (TOC) based on the current + map context. The following values are valid:
    yes
    The topic appears in a generated TOC.
    @@ -1117,23 +1125,25 @@
    -dita-use-conref-target
    -
    See for - more information.
    +
    See for more information.
    -
    -

    Here is the content from the "DITA map attributes" - topic:

    +
    +

    Here is the content from the "DITA map attributes" topic:

    toc
    -
    Specifies whether topics are excluded from navigation - output, such as a Web site map or an online table of - contents. By default, topicref - hierarchies are included in navigation output; - relationship tables are excluded.
    +
    Specifies whether topics are excluded from navigation output, such as a Web + site map or an online table of contents. By default, + topicref hierarchies are included in navigation + output; relationship tables are excluded.
    +

    + TO RESOLVE 13 May 2026: I read that and kind of + hate "web site map". Kind of think we should delete that bit from the other topic, + and replace the first sentence there with a reused sentence from + here. +

    diff --git a/specification/langRef/attributes/lwdita-common-attributes.dita b/specification/langRef/attributes/lwdita-common-attributes.dita index 9cdb2c64..066b0a16 100644 --- a/specification/langRef/attributes/lwdita-common-attributes.dita +++ b/specification/langRef/attributes/lwdita-common-attributes.dita @@ -9,6 +9,11 @@

    These brief definitions have not been edited or reviewed for DITA 2.0

    +

    + TO RESOLVE 13 May 2026: Hold this until later once we've + finished with reviews of the equivalent sections in the TC, then do a quick edit to make + sure nothing is inconsistent, and move on +

    @@ -16,7 +21,7 @@

    Where is the definition for keys in the DITA 2.0 - spec?

    + spec?

    TO RESOLVE 13 May 2026: this is hidden inside a conref, I don't think it applies anymore, can be removed
    diff --git a/specification/langRef/attributes/universalAttributes.dita b/specification/langRef/attributes/universalAttributes.dita index 85ff8b37..2679c408 100644 --- a/specification/langRef/attributes/universalAttributes.dita +++ b/specification/langRef/attributes/universalAttributes.dita @@ -12,6 +12,12 @@ topic ... Look at it in outline form, and check that the sections, titles, and content all make logical sense with the topic title of "Universal attribute group".

    +

    + TO RESOLVE 13 May 2026: Not sure what to change here. + Looking at the topic at dita-lang.org, the only thing that really stands out is the + heading "Common attribute groups". Maybe we can delete that title, check the remaining + content in that section for accuracy, and be done? +

    @@ -60,6 +66,10 @@

    Why do we need to mention that two attributes are available for specialization here? I think it makes the paragraph hard to read.

    +

    + TO RESOLVE 13 May 2026: Agreed. Either take it + out, or make that a second sentence if the info is useful. +

    This group includes common metadata attributes, two of which are available for specialization: base, importance, @@ -83,6 +93,17 @@

    Why do we provide information about specialization and custom document-type shells here? I think that information could be removed.

    +

    + TO RESOLVE 13 May 2026: I think because they're all + in all of the base shells distributed by oasis? But I don't care, fine with + removing this

    On second thought – it's because each of the groups above provides + a list / summary of attributes in the group. These 5 are in the metadata group + because they are picked up with that attribute group in the gramma files (via + specialization), and on every element in the base vocabulary. I think it would + be inconsistent for this section to group every attribute below *except* for + those five. There may be a better way to phrase it, but I think they need to be + listed

    +

    @@ -251,6 +272,15 @@ text"? And how about adding "Processors often add text or images to ensure that readers of the generated content understand whether the step is optional or required." to the end of the example?

    +

    + TO RESOLVE 13 May 2026:

      +
    • maybe change to "… although applications can modify how content is rendered + based on the value of the importance attribute
      • +
    • And update the example with something like "For example, in steps of a task + topic, processors often add text or images to highlight that a step is + optional or required"
      • +
    +

    @@ -271,8 +301,10 @@ processing.I don't like "The role must be consistent...", that seems like best practice that cannot be normative – and I could easily say outputclass="flashy" which makes my element show up with - sparkles, and has nothing to do with "the basic semantic and expectations for the - element". + sparkles, and has nothing to do with "the basic semantic and expectations for the element".

    + TO RESOLVE 13 May 2026: how about saying "the role + can be", or even a lower-case should, rather than "must be"? +

    platform @@ -281,8 +313,11 @@ I think this could specify a platform that is not an operating system or hardware, right? The current definition explicitly limits platform to those two … maybe "Specifies a platform or platforms to - which the element applies, such as the operating system or hardware relevant to a - task." + which the element applies, such as the operating system or hardware relevant to a task."

    + TO RESOLVE 13 May 2026: maybe "Indicates the + content is relevant to the specified platform, such as an operating system or + hardware." +

    product @@ -315,6 +350,12 @@ element was modified. The rev attribute can be used for flagging. It cannot be used for filtering nor is it sufficient to be used for version control.

    +

    + TO RESOLVE 13 May 2026: Sounds good, I might say + "can be used for flagging revisions" just because that sentence feels a bit odd + ending in "for flagging" but really don't care, fine with using the text with or + without that update. +

    @@ -337,6 +378,11 @@ suggested processing defaults for each element? I thought it covered whether an element was block or in-line and whether there were considerations that translators needed to be aware of.

    +

    + TO RESOLVE 13 May 2026: Can we update to "See + (link) for information on additional considerations on translating DITA + elements." +

    @@ -351,6 +397,11 @@ time="29 September 2022" platform="dita">

    Do we also want to direct readers to the architectural topics about the xml:lang attribute?

    +

    + TO RESOLVE 13 May 2026: Yes, should provide a cross + reference, not sure if that will work in the lwdita spec but can figure that out + later +

    diff --git a/specification/langRef/base/defaultSubject.dita b/specification/langRef/base/defaultSubject.dita index 0af88357..0211e05c 100644 --- a/specification/langRef/base/defaultSubject.dita +++ b/specification/langRef/base/defaultSubject.dita @@ -16,6 +16,11 @@

    Do we want to make a normative statement about how processors should handle default values for attributes when they are specified by defaultSubject?

    +

    + TO RESOLVE 13 May 2026: I think this would be covered by + the "how to determine attributes" topic, and does not need an extra rule + here +

    Comments from review D:

    @@ -45,6 +50,12 @@ scheme but your grammar files only allow "x" and "y", then you've set up a scheme that means every usage of that element is automatically an error condition.

    +

    + TO RESOLVE 13 May 2026: That referenced topic is the one + we are stuck on, but that is where the rules for this should be specified. I think this + section could / should be updated with a link to that section, because it's highly + relevant when reading about this topic. +

    diff --git a/specification/langRef/base/ditavalref.dita b/specification/langRef/base/ditavalref.dita index de400fac..aec51bd8 100644 --- a/specification/langRef/base/ditavalref.dita +++ b/specification/langRef/base/ditavalref.dita @@ -90,8 +90,11 @@ This topic overall has far more processing information than seems appropriate for an element reference topic; there is likely a lot of overlap / duplication of information contained in the Branch Filtering section of the arch spec. Most - of this information should be moved there, likely including the full set of - Limitations. + of this information should be moved there, likely including the full set of Limitations.

    + TO RESOLVE 13 May 2026: Needs an editing pass, moving + most of the architectural info into the "Branch filtering" section of the arch + spec +

    The following limitations apply when using the ditavalref element; these limitations cannot be enforced in a DTD or other XML grammar files.

    When the use of the ditavalref @@ -110,9 +113,14 @@ scheme for the conflicting copies.

    Need more information about what situation the processor is recovering from ...

    - For the above, it would be recovering from - a map that instructs it to create two files of the same name, with different filter - conditions applied.

    +

    + For the above, it would be recovering from a map that + instructs it to create two files of the same name, with different filter conditions + applied. + TO RESOLVE 13 May 2026: To add when moving the content + into arch spec, this rule should be in the arch spec +

    +

    Specialization hierarchy @@ -142,7 +150,11 @@ resource-only. DITA 1.3 said that format MUST be ditaval, and that no value other than "resource-only" is valid for processing role. Should these be #FIXED in - the grammar files?

    + the grammar files?

    + TO RESOLVE 13 May 2026: Can raise this at TC, but it's + fine / low impact if we just keep the same definitions from 1.3 and don't make these + fixed +

    diff --git a/specification/langRef/base/dvrResourcePrefix.dita b/specification/langRef/base/dvrResourcePrefix.dita index 7854602d..f4606723 100644 --- a/specification/langRef/base/dvrResourcePrefix.dita +++ b/specification/langRef/base/dvrResourcePrefix.dita @@ -45,8 +45,11 @@ Example The ditavalmeta element refers to arch spec examples, that - might be better here as well, given the new complexity of added resourceid - elements. + might be better here as well, given the new complexity of added resourceid elements.

    + TO RESOLVE 13 May 2026: Yes, we should have these + examples in the arch spec and refer to those from here, these examples are needed in the + arch spec +

    How <xmlelement>dvrResourcePrefix</xmlelement> affects resource file names

    The following code sample shows a simple branch with a parent and child topic, where the diff --git a/specification/langRef/base/dvrResourceSuffix.dita b/specification/langRef/base/dvrResourceSuffix.dita index ef424d8d..b6100224 100644 --- a/specification/langRef/base/dvrResourceSuffix.dita +++ b/specification/langRef/base/dvrResourceSuffix.dita @@ -56,8 +56,10 @@ Example The ditavalmeta element refers to arch spec examples, that - might be better here as well, given the new complexity of added resourceid - elements. + might be better here as well, given the new complexity of added resourceid elements.

    + TO RESOLVE 13 May 2026: Yes, ensure these examples or + equivalents exist in the arch spec, and then link to them from here +

    How <xmlelement>dvrResourceSuffix</xmlelement> affects resource file names

    The following code sample shows a simple branch with a parent and child topic, where the diff --git a/specification/langRef/base/enumerationdef.dita b/specification/langRef/base/enumerationdef.dita index 8664b9a8..4366105a 100644 --- a/specification/langRef/base/enumerationdef.dita +++ b/specification/langRef/base/enumerationdef.dita @@ -113,6 +113,10 @@

    We need to ensure that nothing in the "Usage information" section conflicts with what we specify in the final topic about "Determining effective attribute values.

    +

    + TO RESOLVE 13 May 2026: Can hold this until that topic is + completed, then just ensure we are consistent / no conflicts +

    @@ -121,8 +125,8 @@ conkeyref="reuse-attributes/ref-idandconrefatts"/>, base, class, outputclass, and status.

    + keyref="attributes-universal/attr-outputclass">outputclass, and + status.

    Example diff --git a/specification/langRef/base/foreign.dita b/specification/langRef/base/foreign.dita index 00014c93..12d3e9c4 100644 --- a/specification/langRef/base/foreign.dita +++ b/specification/langRef/base/foreign.dita @@ -33,8 +33,10 @@ content unless otherwise instructed. If a processor cannot render the content, it MAY issue a warning.

    - The following content needs editing. + The following content needs editing.

    + TO RESOLVE 13 May 2026: We or the magic robots should do + a single editing pass and call it done +

    The enabler of the foreign vocabulary must provide the processing and override the base processing for foreign.

      @@ -64,6 +66,13 @@

      Is the following example valid now that we have an SVG reference domain?

      +

      + TO RESOLVE 13 May 2026: I think we had that discussion in + 1.3 and decided to just go with it, we can do the same here, particularly since that svg + domain is over in the technical content spec / not here in the base spec. BUT we should + change the container to <svg-container> which matches what that technical-content + spec has. +

      The following code sample shows a specialization of foreign that is used to hold SVG diff --git a/specification/langRef/base/mapref.dita b/specification/langRef/base/mapref.dita index e2483e36..09050a60 100644 --- a/specification/langRef/base/mapref.dita +++ b/specification/langRef/base/mapref.dita @@ -33,15 +33,25 @@ Navigation > TOC.

      We should plan a review that covers both architectural and element-reference topics about maps.

      +

      + +

      There is a new architectural topic about maps that describes relationship tables, and + says that the root map has the union of all relationship tables from submaps; we + should reference that for the relationship table bit. It does not get "added" to the + parent map, which might not be the root map.

      + + TO RESOLVE 13 May 2026: This is at least the 4th spot we + cover the relationship table info. This should be replaced with a link to the new + relationship table topic in the map. +

      The terms "container map" and "parent map" here are unclear. How are they different?

      -       - -

      There is a new architectural topic about maps that describes relationship tables, and - says that the root map has the union of all relationship tables from submaps; we should - reference that for the relationship table bit. It does not get "added" to the parent map, - which might not be the root map.

      +

      + TO RESOLVE 13 May 2026: Ugh, we should be consistent, + they mean the same thing, shouldn't we be saying referenced map / referencing + map? +

      diff --git a/specification/langRef/base/related-links.dita b/specification/langRef/base/related-links.dita index 66e8c07f..e9a3b992 100644 --- a/specification/langRef/base/related-links.dita +++ b/specification/langRef/base/related-links.dita @@ -24,7 +24,10 @@ of ancestor, parent, child, descendant, next, previous, or sibling.

      Assuming we add an architectural section that covers how link roles are implied by the map, and can result in generated links, we should link to it from - this topic with a related link. + this topic with a related link.

      + TO RESOLVE 13 May 2026: the latest draft of that new + topic doesn't cover the PDF aspect … probably should add it +

      It would be good to replace the reference to a CTR reltable with an example of a reltable that provides links between topics and external resources.

      +

      + TO RESOLVE 11 May 2026: recommend just leaving this + simple table here, but providing bi-directional links (using a reltable!!) between this + and the new architectural topic about relationship tables +

      @@ -59,7 +64,9 @@ topic-to-topic links. The relcell elements can contain topicref elements, which are then related to other topicref elements in the same row (although not necessarily in - the same cell).

      + the same cell).TO RESOLVE 11 May 2026: the following line + should be sync'ed with the other reltable topic that I believe uses "Within the scope of a + root map, the …"

      Within a root map, the effective relationship table is the union of all relationship tables in the map hierarchy.

      @@ -78,6 +85,16 @@

      Consensus from editors' call today: this example needs a significant rework.

      +

      + TO RESOLVE 11 May 2026: See above. I think options are

        +
      1. Ask TC for volunteers to come up with a better one (which also might end up better + off in the arch topic)
        2. +
      2. Leave it alone (with some cleanup after it), and put a better one in the + architectural topic
        3. +
      3. Just do the cleanup after the table and move on
        4. +
      +

      In the following code sample, a relationship table is defined with three columns: one for "concept", one for "task", and one for "reference". Three cells are defined within each row. The first @@ -112,6 +129,10 @@ </map>

      A graphical version of the relationship table in an editor might look like this:

      Replace with a screen capture

      +

      + TO RESOLVE 11 May 2026: recommend just leaving this as a + table, the intent is clear enough? +

      type="concept" @@ -141,6 +162,13 @@

      This organization as a definition list bothers me; it's simply a list of file names, it feels like there should be more explanatory text, even something like "links to"

      +

      + TO RESOLVE 11 May 2026: recommend keeping the definition + list layout, with a file name as the term, but replace the "definition" with prose that + explains what each item links to and why.

      But it might also be good to move the + "Reltables are an inherently …" follow up paragraph over to the architectural spec + topic.

      +

      diff --git a/specification/langRef/base/resourceid.dita b/specification/langRef/base/resourceid.dita index 370b0169..5603428a 100644 --- a/specification/langRef/base/resourceid.dita +++ b/specification/langRef/base/resourceid.dita @@ -21,7 +21,11 @@ This topic needs to be sync'ed with content in the architectural spec. I think it would make sense for much of the appid-role content to be moved into a section of the "DITA Addressing" chapter, and that content really - needs to be reviewed together with this topic after the sync. + needs to be reviewed together with this topic after the sync.

      + TO RESOLVE 13 May 2026: Not sure I still feel that way + about appid-role, given that this is the only element that uses it. So to resolve, maybe + just ensure that this topic is reviewed. +

      The appid and appname attributes work in combination to specify a specific ID for an application. Multiple appid values can be associated with a @@ -80,7 +84,8 @@

      Attributes -

      The following attributes are available on this element: and the attributes defined below.

      +

      The following attributes are available on this element: and the attributes defined below.

      appname
      @@ -233,6 +238,13 @@ Example: Using a <xmlelement>resourceid</xmlelement> element to XXX +

      + This clearly needs an update

      + TO RESOLVE 13 May 2026: I think Eliot agreed to + rework or recreate this example, as an example that reproduces the former copy-to + behavior +

      +

      In the following code sample, anchor components are defined for two different references to the same topic. Each use of the topic represents the documentation for a different model of the same diff --git a/specification/langRef/base/titlealt.dita b/specification/langRef/base/titlealt.dita index 4d004ec5..5cad1bcc 100644 --- a/specification/langRef/base/titlealt.dita +++ b/specification/langRef/base/titlealt.dita @@ -54,13 +54,18 @@

      Processing expectations - Questions - as I read this more closely:

      Some of this language implies a - specific type of processor, which we've had trouble with in the - past; language may need to be more processor agnostic

      Given - the complications, the number of required samples, and the impact - on processing, it feels like this deserves a page in the - architectural specifciation.

       + Questions as I read this more + closely:

      Some of this language implies a specific type of processor, which we've had + trouble with in the past; language may need to be more processor agnostic

      Given the + complications, the number of required samples, and the impact on processing, it feels like + this deserves a page in the architectural specifciation.

      + TO RESOLVE 13 May 2026: options

        +
      • Ask the magic robots to turn this into an architectural spec topic and then rework + it
        • +
      • Just go through and clean up use of "processor" in this topic
        • +
      • Just leave it and move on
        • +
      +

      The processing of an alternative title depends on its roles. Processors SHOULD support the following tokens for the title-role attribute:

      @@ -124,8 +129,7 @@ Attributes

      The following attributes are available on this element: and title-role.

      + keyref="attributes-common/attr-title-role">title-role.

      Examples diff --git a/specification/langRef/containers/ditaval-d.dita b/specification/langRef/containers/ditaval-d.dita index c8c3308a..e5625445 100644 --- a/specification/langRef/containers/ditaval-d.dita +++ b/specification/langRef/containers/ditaval-d.dita @@ -7,7 +7,13 @@ a DITA map for multiple audiences.The child topics here all refer to a "map branch implied by a ditavalref" – we should probably define "implied" as a term in this case, that we can easily refer to (or if we already define it, uses of the phrase "implied by a - ditavalref" should link there). + ditavalref" should link there).

      + TO RESOLVE 13 May 2026: Make sure that one of

        +
      • that phrase is defined in the arch spec topics about branch filtering, or
        • +
      • we switch to whatever term is used in the arch spec topics
        • +
      +

      diff --git a/specification/langRef/ditaval/revprop.dita b/specification/langRef/ditaval/revprop.dita index d13558d7..67883b2d 100644 --- a/specification/langRef/ditaval/revprop.dita +++ b/specification/langRef/ditaval/revprop.dita @@ -99,6 +99,11 @@

      Do we want to be more specify about what values are supported here? Hex codes or names for color, character, but what for styles? Refer to XSL: FO spec?

      +

      + TO RESOLVE 13 May 2026: At this point I think no, + whatever a processor wants to support they can use here, which also means if it + was allowed in 1.x it's allowed in 2.0 +

      diff --git a/specification/non-normative/changes-1.3-to-2.0/added-to-standard.dita b/specification/non-normative/changes-1.3-to-2.0/added-to-standard.dita index 09f41658..bdf3f810 100644 --- a/specification/non-normative/changes-1.3-to-2.0/added-to-standard.dita +++ b/specification/non-normative/changes-1.3-to-2.0/added-to-standard.dita @@ -6,8 +6,15 @@ usability of the standard or to address use cases where DITA 1.3 failed to offer an acceptable solution. There's really no way in this summary document to know where the new elements are allowed. Should this be specified - here somewhere – in changes to the content models of elements, for example? - + here somewhere – in changes to the content models of elements, for example?

      + TO RESOLVE 13 May 2026: There are so many content + model changes I don't think we can or should list them all, but we could do a + review of this topic and add that to items where it seems most useful

      also + take note: some of these (I see <diagnostics>) are only relevant in the + technical content spec and shouldn't be listed as additions to the base. I + think those should be removed from this and (at the same time, making sure + we don't lose them) added to the other.

      +

      Domains diff --git a/specification/non-normative/changes-1.3-to-2.0/modified-in-standard.dita b/specification/non-normative/changes-1.3-to-2.0/modified-in-standard.dita index d3657f1a..e3175a17 100644 --- a/specification/non-normative/changes-1.3-to-2.0/modified-in-standard.dita +++ b/specification/non-normative/changes-1.3-to-2.0/modified-in-standard.dita @@ -23,8 +23,16 @@

      Is there where we would put that - linktext has been moved from commonElements to - TopicMod? + linktext has been moved from commonElements to TopicMod?

      + TO RESOLVE 13 May 2026: Maybe a new section at + the end for grammar-related changes, list this and the new <dita> module + in the base spec (not sure if more should be listed but possibly, we could + call out that outputclass moved into univ-atts because that will impact + migrations

      also need to fix the "attributes added to" table, it + mentions specializations of body (but that is for things in the TC + spec), it needs a fix for <prop> as that attribute was renamed + add-outputclass

      +

      Content Model Changes diff --git a/specification/non-normative/changes-1.3-to-2.0/new-features-and-enhancements-in-dita-2-0.dita b/specification/non-normative/changes-1.3-to-2.0/new-features-and-enhancements-in-dita-2-0.dita index 03c63bc8..fe2418e9 100644 --- a/specification/non-normative/changes-1.3-to-2.0/new-features-and-enhancements-in-dita-2-0.dita +++ b/specification/non-normative/changes-1.3-to-2.0/new-features-and-enhancements-in-dita-2-0.dita @@ -10,6 +10,12 @@ technical details, but should instead focus on the benefit these changes offer to implementations. More of WHY the TC thought a change was beneficial rather than how it was implemented.

      +

      + TO RESOLVE 13 May 2026: I don't think this is actionable + now, but could be added as an XML comment to remind any editors of the purpose.

      I also + see much of this has yet to be written. Is this topic even included in the base spec? + There is a new migration topic that has a lot of this info

      +

      diff --git a/specification/non-normative/changes-1.3-to-2.0/overview.dita b/specification/non-normative/changes-1.3-to-2.0/overview.dita index 506beeaf..4e84b28a 100644 --- a/specification/non-normative/changes-1.3-to-2.0/overview.dita +++ b/specification/non-normative/changes-1.3-to-2.0/overview.dita @@ -6,6 +6,10 @@ standard. It includes changes to both the base and technical content editions. should this document in some way indicate which is base - and which is technical content? + and which is technical content?

      + TO RESOLVE 13 May 2026: Logically I'm not sure it + makes sense to have the technical content stuff here, that should be in the TC + spec +

      diff --git a/specification/non-normative/changes-1.3-to-2.0/removed-attributes.dita b/specification/non-normative/changes-1.3-to-2.0/removed-attributes.dita index 41872866..b2ed1359 100644 --- a/specification/non-normative/changes-1.3-to-2.0/removed-attributes.dita +++ b/specification/non-normative/changes-1.3-to-2.0/removed-attributes.dita @@ -15,6 +15,11 @@ (alt, navtitle, etc.), as well as attributes like otherjob (which was available only on audience.

      +

      + TO RESOLVE 13 May 2026: I'd say just leave this + organization, doesn't matter if it was a common attribute or only on one element, they + were still removed +

      The attributes listed in the following table no longer exist in DITA. They are not available on any elements.

      @@ -129,6 +134,9 @@ are NOT retained generally. They only existed on object, so should they be moved into the table in the above section?

      +

      + TO RESOLVE 13 May 2026: yes +

      Certain attributes, while retained generally, have been removed from the attribute lists for specific elements.

      diff --git a/specification/non-normative/elementsMerged.dita b/specification/non-normative/elementsMerged.dita index 57912635..69a1102d 100644 --- a/specification/non-normative/elementsMerged.dita +++ b/specification/non-normative/elementsMerged.dita @@ -770,6 +770,12 @@ alt element within image contains translatable text. Localization of the image would be separate."

      +

      + TO RESOLVE 13 May 2026: For those two, can we change the + block/inline column to say "N/A (container element)", and in the final notes colum, say + that "The nested alt element has translatable text, and the + referenced image may also require translation." +

      diff --git a/specification/non-normative/file-names-in-the-base-dita-edition.dita b/specification/non-normative/file-names-in-the-base-dita-edition.dita index 2cc9f12a..87e66d46 100644 --- a/specification/non-normative/file-names-in-the-base-dita-edition.dita +++ b/specification/non-normative/file-names-in-the-base-dita-edition.dita @@ -63,10 +63,15 @@ -

      The names of the expansion modules listed in the "Example" - column are taken from the example topics. They do not follow a - consistent pattern. I suspect that the same is true for file - names used in the constraint example topics.

      +

      The names of the expansion modules listed in the "Example" column are taken from the + example topics. They do not follow a consistent pattern. I suspect that the same is true + for file names used in the constraint example topics.

      +

      + TO RESOLVE 13 May 2026: These rules are no longer + mandatory and should not be mandatory, so we should just pick one pattern (ideally + matching our existing task constraint) and use htat in all the constraint/expansion + module pattern recommendations +

      where:

        @@ -142,6 +147,11 @@

        Also, is including "Mod" in element-domain or constraint files something we really want to do, or was it necessary for the RNG-to-DITA/XSD converter?

        +

        + TO RESOLVE 13 May 2026: See comment in earlier draft + comment. Also, "Mod" definitely isn't required in the name but is probably good to + recommend for consistency, all the other content-model modules use it. +

        where:

          diff --git a/specification/non-normative/information-about-migrating-to-dita-2-0.dita b/specification/non-normative/information-about-migrating-to-dita-2-0.dita index 7862e458..d45129a5 100644 --- a/specification/non-normative/information-about-migrating-to-dita-2-0.dita +++ b/specification/non-normative/information-about-migrating-to-dita-2-0.dita @@ -7,7 +7,23 @@ Initial draft of this topic includes all changes from both the base specification and the technical content specification.

          It does not currently - cover the duplicate learning modules that were removed.

           + cover the duplicate learning modules that were removed.

          + TO RESOLVE 13 May 2026:

            +
          • We have a bunch of other topics I found when working through draft + comments, that may also contain some of this info. Need to use one or + the other, and make sure the one we use is complete / comprehensive for + the base spec.
            • +
          • But we also need to move all the technical-content related changes over + to the technical content spec.
            • +
          • Learning is odd because that wasn't even technical-content. I think this + page should note that technical content also included changes that are + covered in that spec; then we could still add a note in this + non-normative appendix stating that learning is not provided as a 2.0 + standard but that all modules can be updated for compatibility, or + whatever wording we've been using.
            • +
          + +

          Markup to migrate for DITA 2.0

          The following elements and attributes have been removed from the grammar as obsolete.