Re: [dita-adoption] Scoped Keys article uploaded

[Eliot Kimber <ekimber@contrext.com>]

Feedback on Scoped Keys article:

1. This sentence:

"Generally it's the first definition the processor finds when it traverses
the map breadth-first."

Is not sufficiently precise. The rule is: within a single map document,
the first definition in depth-first (document) order takes precedence.
Within the tree of directly-referenced maps the first definition in the
first map found in breadth-first traversal of the map tree takes
precedence.

This is difficult to explain clearly because there are two different tree
contexts: the tree of elements within a given map document and the tree of
maps represented by the map-to-map references starting with the root map.

Not sure I can offer guidance on how to make this clear in this context...

Note also that with key scopes, the scope-qualified keys from any scope
are taken to occur within the parent scope at the point of occurrence of
the child scope, meaning that a key defined in a child scope will override
the same qualified key name that occurs *later* in the parent scope. I
don't think this case is every explicitly presented in this article (and
I'm not sure it's necessary but it's probably worth mentioning somewhere).

For example, in this map:

<map>
 <topicgroup keyscope="s1">
   <keydef key="k1" href="topic-01.dita"/>
 </topicgroup>
 <keydef key="s1.k1" href="topic-02.dita"/>
</map>

The key "s1.k1" resolves to topic-01.dita because the scope-qualified
keydefs from the child scope are "pulled up" into the parent scope to
produce this effective map:

<map>
<keydef key="s1.k1" href="topic-01.dita"/>
<topicgroup keyscope="s1">
   <keydef key="k1" href="topic-01.dita"/>
 </topicgroup>
 <keydef key="s1.k1" href="topic-02.dita"/>
</map>

It's a wrinkle that produces the result users would expect (or at least
the effect they would want if they thought it about deeply) but it's a
challenge to explain clearly without getting into the details of key
definition copying up and down the scope hierarchy.


2. The first example map under Scoped Keys has key scopes that don't
include any keys--I think that might confuse readers and lead to the
conclusion that keys can be defined in topics. I think the example would
be clearer if there was at least one key definition in each scope shown.

3. This note is now out of date:









"Clearly, the processor must create two copies of get-started.dita to
resolve the key to two different values. While the mechanism has not been
finalized as of this article's publication, assume an implicit use of the
copy-to attribute to create two copies of the topic."





The mechanism is finalized. Here's what the current 1.3 draft spec says:


"If a topic that contains key references is reused in multiple key scopes
within a given root map such that its references resolve differently in
each use context, processors MUST produce multiple copies of the source
topic in resolved output for each distinct set of effective key
definitions that are referenced by the topic. In such cases, authors can
use the @copy-to attribute to specify different source URIs for each
reference to a topic."


The spec doesn't (and can't) say what processors do in the case that
authors don't specify @copy-to--how the deliverable details are
constructed in that case is entirely processor dependent.

4. Likewise, this statement is out of date:









"This example also brings up the interesting question of how scoped keys
and ditaval filtering, particularly scoped ditavals?also introduced in
DITA 1.3?are going to interact. Again, as of publication, that question
has not been entirely resolved, but stay tuned for more information from
the OASIS Technical Com."





This topic: 
http://www.oxygenxml.com/dita/1.3/specs/index.html#archSpec/base/branch-fil
tering-resource-names.html


Defines the mechanisms and processing rules for branch filtering and keys.

5. Under "Reuse implications for named key spaces", I think the use of
"the full path" in this statement:

"you can simply define the key using the full path in the reused topic as
the key name"





Risks confusing the scope qualified name with paths in URLs. I would
prefer to use terms like "scope qualified" or "fully scope qualified"
instead of "path". I understand the analogy but I think it risks confusing
users.

6. This paragraph:









"This double-naming might or might not prove technically problematic for
key reuse, but it will certainly prove confusing for writers. The best
policy, as always, is to make a decision about whether or not to
explicitly name root map key spaces to ensure no duplications or potential
conflicts like the example above. For example, either you decide never to
explicitly name key spaces on root maps and always to add a keyscope
attribute to mapref when referencing any root map as a sub-map; or you
decide always to explicitly name name key spaces on root maps and never to
add a keyscope attribute to mapref when referencing any root map as a
sub-map."





Touches on an interesting and important limitation in scoped keys and I
hadn't thought about this specific case before (scope names coming from
referenced map elements).


Within a parent scope you can have two scopes with the same scope name,
e.g.:

<map>
 <mapref keyscope="s1" href="map1.ditamap"/>




 <mapref keyscope="s1" href="map2.ditamap"/>
</map>

References to key names "s1.*" will resolve to the keys as defined in
map1.ditamap, by the rule that qualified key names from child scopes are
taken to occur at the point of reference of the child scope.

In the case reflected in the quoted paragraph you could inadvertently
create this case and get unexpected results because the scope names from
the map reference and the referenced map are *merged*.

So if my source map was


<map>
 <mapref keyscope="s1" href="map1.ditamap"/>
 <mapref keyscope="s2" href="map2.ditamap"/>
</map>

But map1.ditamap was:

<map keyscope="s2">
 ...
</map>

Then references to key names "s2.*" will resolve to map1, not map2 and it
wouldn't be immediately obvious why.

I think that argues for *not* setting key scope names on map elements
unless the scope names are very carefully controlled. My reasoning is that
authors of using maps have ultimate control over all aspects of key
definition (because they can override any keys) and putting scope names on
submaps makes their jobs harder (because they might need to do more
overrides to work around an unwanted scope name). Putting all scope names
on map references avoids the problem (at least to the degree that it can
be avoided).

In point of fact the ability to make scope-qualified references doesn't
really have much value except where the key spaces are carefully
controlled within a set of coordinated maps. Scope-qualified keys really
becomes a syntactic shortcut that avoids the need to declare the
fully-qualfied key names within the root map. So perhaps spending too much
time worrying about the implications of merged scope names is not time
well spent...

7. The term "compliant processor" is problematic for two reasons.
<pedantry-alert> First one conforms to standards but complies with laws,
so the correct term is "conforming processor".</pedantry-alert>. The
second is that conformance of the processor is really not relevant--it's
sufficient to say that a processor can (in the sense that it is
technically possible) do the right thing because there's enough
information in the source data to be able to do it (whereas in DITA 1.2
there is not enough information). So I think it's sufficient to say "a
processor can resolve the xref ..."

8. I think the term "treat" in the phrase "how to treat the
cross-deliverable linking mechanism" is problematic. I read "treat" as
"interpret the semantics of the markup" but I think the intended meaning
is "how the output is generated". I think it would be better as "how to
implement generation of cross-deliverable links in deliverables". That is,
there is no option on how to treat the links semantically: the semantic is
unambiguous and invariant: it's a link to the target key in the context of
the target root map. The challenge is how to implement that link (and how
to do the data processing required to implement the link) for generation
of a specific deliverable type.



9. This statement: "A key defined within a key space applies only within
that key space." bothers me in that "applies only within" isn't completely
clear. The pedantically-correct version of this statement would be "For a
key defined within a key space, unqualified references to that key will
only be resolvable from topicrefs in or topics referenced from within that
key space." A better way to make the original statement might be "A key
defined within a key space can only be referenced by the the unqualified
key name from within that key space."

Cheers,

Eliot























----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 7/19/15, 11:07 PM, "Leigh White" <dita-adoption@lists.oasis-open.org on
behalf of Leigh.White@ixiasoft.com> wrote:

>Hi all,
>
>I noticed on the agenda for tomorrow's meeting the note "DITA 1.3 Scoped
>Keys Tutorial (Leigh White; date not confirmed)"
>
>I uploaded the first draft of this document last week, at
>https://www.oasis-open.org/apps/org/workgroup/dita-adoption/download.php/5
>6085/ScopedKeysFeatureArticle.pdf.
>
>Apologies for not sending a notification sooner; I thought there was
>something automatic. Also, I was not quite aware the format was a
>tutorial (it's been referred to as "article," "whitepaper" and several
>other things), so I might have to go back to the drawing board a bit
>based on initial feedback.
>
>Best,
>Leigh
>
>Leigh White
>DITA Specialist
> 
>IXIASOFT 
>825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
>tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 (GMT -6:00)
>leigh.white@ixiasoft.com / www.ixiasoft.com