Greetings!
I volunteered to review two sections.
DITA terminology, notation, and conventions
Similar to Stan, I believe that these sections are ready for review.
I'm a little confused why this is a separate section from the Introduction. Shouldn't all the terminology be together? Why is the RFC-2119 stuff up in the introduction only? I get that the SHOULD/MUST etc. stuff is not DITA-specific, but if I'm searching for why the formatting for SHOULD is different, I'd be confused that it isn't in the Notation section.
I will admit it's hard to read through definitions, just reading through a glossary. If I'm not reading the context, it's hard to know why these terms are pulled out, or if the definitions are correct. I had difficulty understanding the nuance between a thing and the thing type.
Indirect key-based addressing
-
I'm not sure everything has been looked at with new elements, such as <keytext>
-
Why is keydef not mentioned until the examples?
-
Core concepts for working with keys needs an edit by folks who understand the details.
Potentially a venn diagram for key spaces and scopes might help.
-
The @keyref attribute - needs an edit. What does "late bound" mean? (Also, since the dita-ot has the filter-stage property, do you need to talk about how that can relate to ditavals? Does that go here?)
What does bound mean?
-
Using keys for addressing - example needs a touch of revision to be more precise. Show the syntax for the xref.
-
Key scopes - I am going to keep asking for diagrams. I get lost in the words and would appreciate a visual.
I'm not someone writing processors, but I am confused by the example. I don't understand how you would identify a key scope by A and B.
-
I get that you can have multiple key names or key scope names by spaces, but why would you?
-
The @keyscope attribute - needs an example section?
I get that it works, but I don't see why I would do it.
-
Addressing Keys by scopes - what's a qualified or unqualified key definition? Should that be up in Core concepts? Needs a copy edit as well
-
Cross-deliverable addressing and linking - needs an edit. And it should be more explicit if the two examples are related.
Is @scope="peer" behavior similar between links and maps? Do we even ever discuss a peer map outside of keys? I only found one reference for when dealing with ditavals. (off topic, what is the point of scope=peer for a plain topicref ?)
-
Processing key references - needs an edit. What's a key name? Why isn't that listed in the core concepts?
What about that backwards compatibility note? Is this behavior changing?
Reusing a topic in multiple key scopes is missing information
Why is the error condition "May"?
-
Processing key references for navigation links and images - needs an edit, including title. what about <audio>, <video>, and the other elements in the multi-media domain? Why does <object> use @datakeyref? How about resolving mailto: links?
Also link to where alt text comes from? That you can resolve both the image and the alt text?
-
Processing key references on <topicref> elements - needs an edit. What is a level of key reference? Is that a key referring to a key referring to a key? or how nested referenced maps are? Does the amount of nesting need to be mentioned for topicrefs in general?
I'd like a combining metadata example somewhere.
-
Processing key references to generate text or link text - Needs an edit.
So, if you need an image with a longdescref, better to use a conkeyref? I honestly can't remember, now with <keytext> we no longer support <keywords><keyword>? does that behavior change and now if it's a topicref with a link, the keywords are used as metadata?
-
Examples: Key definitions for variable text - needs to be reworked for <keytext>
If you use a <keyword> to reference a key with an href, it will become a link? You don't have to use an <xref>? Does any element become a link, or only certain ones?
-
Example: Key definition with key reference - why would you do this? I don't know why I'd set a map up like this. I do see why I would do this in conkeyref examples.
-
Example: Links from <term> or <keyword> elements - If there are special behaviors for special elements, shouldn't that be described outside of the examples?
-
Example: Keys and collaboration - probably needs an edit, or I need more coffee to review.
I skipped the key scope examples for now.
hope this helps
Zoë