OASIS Darwin Information Typing Architecture (DITA) TC

Forwarding Bob's comments on the @id topic

Thanks,

Robert

Hi Robert,

Thanks for helping me out with posting my comments for the TC.

My comments:

Paragraph 2

"An element must have a valid value for the @id attribute before it can be
referenced using a fragment identifier."

I think most experienced DITA people would realize this text refers to a
conref. It might be clearer to simply use the term conref rather than
"fragment identifier".

The last sentence seems out of place in the paragraph. Recommend making it
a separate paragraph.

Paragraph 3

"All values for the @id attribute must be XML name tokens."

It might be helpful to include a reference to a resource defining XML name
tokens.

Paragraph 4

"The @id attribute for most other elements within topics and maps is not
declared to be an XML ID; this means that XML parsers do not require that
the values of those @id attributes be unique."

"this means": vague antecedent. Should clarify. Perhaps substitute
"therefore" or "thus".

"For this reason, tools might provide an additional layer of validation to
flag violations of this rule."

Is "might" normative here? Should this word be formatted according to the
same convention as "should" and "must" elsewhere in this section?

Paragraph 5

"Within documents that contain multiple topics, identifiers are scoped to
the individual topic, excluding child topics."
The last clause could be clearer. Does this clause mean that if a document
includes a topic and that topic includes child topics, the scope of the
ids is the parent topic, not the child topic?

"This is true even if one of those topics is nested within the other"
Vague antecedent. Should clarify. Suggestion: "The sections may have the
same value for @id even if one of those topics is nested within the
other."

Note
General observation; The note seems easy to overlook, but the point is
important. We might consider adding a heading to this paragraph rather
than making it a note.

"... the presence or absence of an @id attribute on the <fn> element will
affect how the element is processed."

Recommend revising to
"... the presence or absence of an @id attribute on the <fn> element affects
how the element is processed."