Skip to content

Notes on how to resolve draft comments #1006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robander merged 1 commit into from
May 15, 2026
Merged

Notes on how to resolve draft comments #1006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 37 additions & 25 deletions specification/archSpec/base/aboutconditionalprocessing.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,34 +27,42 @@
</dlentry>
<dlentry>
<dt>conditional-processing profile</dt>
<dd>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.<draft-comment author="rodaande" time="21 March 2022"
>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.</draft-comment></dd>
<dd>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.<draft-comment author="rodaande"
time="21 March 2022">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.<p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: Recommend removing this
term</draft-comment>
</p></draft-comment></dd>
</dlentry>
<dlentry>
<dt>DITAVAL document</dt>
<dd>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.<!--<draft-comment author="rodaande" audience="spec-editors" time="18 March 2022">Do we need to / should we state here that this can be a file on the file system, a set of rules in memory, or any other way of storing filtering information that can be expressed using DITAVAL syntax?</draft-comment>--><draft-comment
author="Kristen J Eberlein" time="21 March 2022">
syntax.<draft-comment author="Kristen J Eberlein" time="21 March 2022">
<p>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.</p>
</draft-comment><draft-comment author="rodaande" time="25 March 2022">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?</draft-comment></dd>
<p>
<draft-comment author="rodaande" time="25 March 2022">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?</draft-comment>
<draft-comment author="robander">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 <xmlatt>add-outputclass</xmlatt>, processing matching
DITA elements as if they had a specified <xmlatt>outputclass</xmlatt>
attribute.</draft-comment>
</p>
</draft-comment></dd>
</dlentry>
<dlentry>
<dt>filtering</dt>
Expand All @@ -65,14 +73,18 @@
<draft-comment author="Kristen J Eberlein" time="21 March 2022">
<p>Do we need to broaden the definition of filtering and mention
inclusion also?</p>
<p>
<draft-comment author="rodaande" time="25 March 2022">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.<p>I'm not sure though, beause
"include" is clearly a value you can specity in DITAVAL.</p></draft-comment>
<draft-comment author="robander">TO RESOLVE 11 May 2026: how about if we just update this to
say "The process of including or excluding content at rendering time"</draft-comment>
</p>
</draft-comment>
<draft-comment author="rodaande" time="25 March 2022">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.<p>I'm not sure though, beause "include" is clearly a
value you can specity in DITAVAL.</p></draft-comment>
<dl>
<dlentry>
<dt>flagging</dt>
Expand Down
21 changes: 21 additions & 0 deletions specification/archSpec/base/aboutditavaldocuments.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.</p>
<p>
<draft-comment author="robander">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"<ol
id="ol_mqm_1c4_fjc">
<li>Instruct processors to include matching content</li>
<li>Instruct processors to exclude matching content</li>
<li>Instruct processors to mark matching revisions</li>
<li>Instruct processors to flag matching content with styles also specified on the
<xmlelement>prop</xmlelement> or <xmlelement>revprop</xmlelement> element</li>
<li>Instruct processors to pass the matching attribute through to rendered output, when
applicable</li>
<li>Instruct processors to treat the matching content as if the element has an
<xmlatt>outputclass</xmlatt> attribute, with the value specified in the
<xmlelement>prop</xmlelement> (or revprop?) element using
<xmlatt>add-outputclass</xmlatt></li>
</ol></draft-comment>
</p>
</draft-comment>
<p>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
Expand All @@ -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.</p>
<p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: how about we just add that sentence
here, or in the list I suggested adding above</draft-comment>
</p>
</draft-comment>
</body>
</topic>
43 changes: 34 additions & 9 deletions specification/archSpec/base/basic-dita-terminology.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.</p></draft-comment>
the content.</p><p>
<draft-comment author="robander">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 <b>can</b> 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.<p>Or, if we can't come up with wording that works
with that, just skip this and not define a DITA
processor.</p></draft-comment>
</p></draft-comment>
<dl>
<dlentry>
<dt>DITA document</dt>
Expand All @@ -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.</draft-comment></li>
siblings, but I don't think we have a word for that.<p>
<draft-comment author="robander">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"</draft-comment>
</p></draft-comment></li>
</ul></p>
</dd>
</dlentry>
Expand Down Expand Up @@ -66,13 +81,23 @@
<p>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.</p>
<p>
<draft-comment author="robander" audience="spec-editors"
time="26 may 2021">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,
&lt;dita> doesn't have class and is a DITA element, so it's an
oddball.</draft-comment>
<draft-comment author="robander">TO RESOLVE 11 May 2026: suggest we <ol
id="ol_kkn_l24_fjc">
<li>confirm that somewhere in this spec we do say that you have
to have <xmlatt>class</xmlatt>, which I'm pretty sure we do,
and then</li>
<li>delete the sentence as Kris suggested</li>
</ol></draft-comment>
</p>
</draft-comment>
<draft-comment author="robander" audience="spec-editors" time="26 may 2021"
>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, &lt;dita> doesn't have class and is a DITA
element, so it's an oddball.</draft-comment>
</dd>
</dlentry>
<dlentry>
Expand Down
11 changes: 10 additions & 1 deletion specification/archSpec/base/behaviors.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <xmlatt>dir</xmlatt>, <xmlatt>translate</xmlatt>, and
<xmlatt>xml:lang</xmlatt> attributes.</shortdesc>
<xmlatt>xml:lang</xmlatt> attributes.<draft-comment author="robander" time="15 May 2026"
>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.<p>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.</p></draft-comment></shortdesc>
</concept>
6 changes: 4 additions & 2 deletions specification/archSpec/base/branch-filtering-implications-of-processing-order.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.</p>
<draft-comment author="rodaande" time="4 Apr 2022">Do we remember what "relaed attributes" are
in the following note? Can we keep it simple and just say that keyref attribute is
disallowed?</draft-comment>
in the following note? Can we keep it simple and just say that keyref attribute is disallowed?<p>
<draft-comment author="robander">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.</draft-comment>
</p></draft-comment>
<note>The <xmlatt>keyref</xmlatt> attribute and related attributes are explicitly disallowed on
<xmlelement>ditavalref</xmlelement>. This prevents any confusion resulting from a
<xmlatt>keyref</xmlatt> that resolves to additional key- or resource-renaming
Expand Down
11 changes: 9 additions & 2 deletions specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@
<draft-comment author="Kristen J Eberlein" audience="spec-editors" time="04 July 2019">
<p>We need to look at the instances of "should" in this topic. Can they be recast? Do we need
to introduce RFC-2119 language?</p>
<p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: just need to do the editorial pass
and clean up each use of should, use RFC if needed</draft-comment>
</p>
</draft-comment>
<p>The semantic role reflects the <xmlatt>class</xmlatt> hierarchy of
the referencing <xmlelement>topicref</xmlelement> element<ph
Expand All @@ -40,8 +44,11 @@
statement: "the non-default behavior should be clearly specified"<p>We 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.</p></draft-comment>
need a clear table here listing every element where this behavior does not apply.</p><p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: I believe the
<xmlatt>impose-role</xmlatt> attribute is now available for this, we should say so and
link to the topic about it</draft-comment>
</p></draft-comment>
<p>Unless otherwise instructed, a specialized <xmlelement>topicref</xmlelement> element that
references a map supplies a role for the referenced content. This means that, in effect, the
<xmlatt>class</xmlatt> attribute of the referencing element cascades to top-level topicref
Expand Down
4 changes: 4 additions & 0 deletions specification/archSpec/base/chunk-attribute-combine.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@
</ul>
<draft-comment author="Kristen J Eberlein" time="04 February 2022">
<p>What's the difference between the content of li[3] and [li4]?</p>
<p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: I think this is resolved, item 3
was commented out</draft-comment>
</p>
</draft-comment>
</conbody>
</concept>
5 changes: 4 additions & 1 deletion specification/archSpec/base/conditional-processing-and-subject-schemes.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@
<draft-comment author="rodaande" audience="spec-editors" time="21 March 2022">Not sure if need
this topic. Started to fill in info but it would cover exactly what is in <xref
href="processing-controlled-attribute-values.dita"/> … don't want to duplicate information,
especially normative rules.</draft-comment>
especially normative rules.<p>
<draft-comment author="robander">TO RESOLVE 11 May 2026: see if Kris will let me delete this
topic</draft-comment>
</p></draft-comment>
<p/>
</conbody>
</concept>
Loading
Loading