OASIS Darwin Information Typing Architecture (DITA) TC

---------- Forwarded message ---------
Date: Mon, Apr 14, 2025, 2:54 PM
Subject: DITA review content from Bob Johnson: indirect addressing


Hi Robert,

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

My comments:

"Indirect key-based addressing"
Appears to limit the discussion to addressing, but keys are also used as
variables. I suggest revising the title to reflect that use.
Use as variables might more effectively be addressed as a separate topic,
or set of topics. We might consider two sections: keys for addressing and
keys as variables.

Side note: Personally, I am not a fan of using keys as variables. It works
well in English, but when you move to languages with gender  or
inflection, you can get in to grammatical trouble very quickly. But I
realize that they are used for this purpose extensively, so we do have to
address this implementation.


"key definition
A <topicref> element that binds one or more key names to zero or more
resources."

The <keydef> element now exists as well. Definition should be updated to
include <keydef>.

Setting key names with the @keys attribute
Should be updated for the <keydef> element.

The @keyref attribute
Shortdesc should be simplified; use an ordered list in first para for key
options

Cross-deliverable addressing and linking
This is an important topic, and should not  be  buried so deeply. This
should be a top-level topic in this section.


"The attributes that are common to the key-defining element and the
key-referencing element, other than the @keys, @processing-role, and @id
attributes, are combined as for content references, including the special
processing for the @xml:lang, @dir, and @translate attributes."

Sentence is unclear to me. I am not sure what is intended here in this
passage.

"In such cases, authors can use <resourceid> within topic references to
specify distinct anchor components for each instance of the topic."
Is this the right element for the stated purpose?

"with the @appid-role attribute set to deliverable-anchor to specify
different source URIs for each reference to a topic."

The sentence is incomplete.  Is there missing content or should the
sentence be combined with the previous sentence?

"Example: How key scopes with the same name interact"

"In this scenario, both product A and product B share a key scope name
using."
        "using" should be in quotation marks as other keyscope names are in other
topics. Otherwise, the sentence looks incomplete.
        "share a key scope name using"
    recommend revising to:
        "share a key scope named 'using'
        In revision, recommend a different scope name than "using"; a different
scope name would help avoid the confusion.