Re: [dita] Implication of subjectdef with a keyref (was Gathering restricted values using a subject scheme map)

[Jim Tivy <jimt@bluestream.com>]

One way to go with 1.3 clarification  is the controlled values in child list interpretation described here:

2.2.3.2 Defining controlled values for attributes
...
The parent <subjectdef> element defines the category, and the children <subjectdef> elements define the
controlled values.
...

That for 1.3 we use a simple child list interpretation of enumerated controlled values under one category subject.  Contemplation of using a descendant list and leaf node vs all nodes could be deferred for discussion in the 2.0 timeframe.

A clarification is needed for the use case of a child list where some of these children have children themselves.  It seems that a processor should ignore descendants in this case.

In Radu's example below the values for outputclass would be "none" and "floatLeft" (not  "left" as it is a non child descendant).  The interpretation of keyref being it references the "resource" defined by the key" and effectively transcludes it -  which in this case would transclude this in place of the keyref:

<subjectdef keys="floatLeft">
   <subjectdef keys="left"/>
</subjectdef>

This transclude interpretation might suit other subjectdef keyref use cases.

This is based on the idea that the "resource" being bound to the "floatLeft" key is: 
<subjectdef keys="floatLeft">
   <subjectdef keys="left"/>
</subjectdef>

You might also argue that the resource bound to the floatLeft key does not include the children (It is a single subject) - that is likely less useful.

In any event, if you want "none" and "left" construct the keyref as: 
        <subjectdef keyref="left"/>

But if floatLeft subjectdef had lots of children you have to keyref them all in.

Only way around that is to introduce descendant node text into the spec 2.2.3.2 with a qualification of 
whether it uses leaf nodes or all nodes.  

Seems to define a keyref of a subjectdef to mean "copy children here" in the context of evaluating an enumerationdef might works in this case but may run counter to other 
subjectScheme keyref uses cases.

<!DOCTYPE subjectScheme PUBLIC "-//OASIS//DTD DITA Subject Scheme Map//EN" "subjectScheme.dtd">
<subjectScheme>
    <subjectdef keys="floatLeft">
        <subjectdef keys="left"/>
    </subjectdef>
    <subjectdef keys="outputclassFig">
        <subjectdef keys="none"/>
        <subjectdef keyref="floatLeft"/>
    </subjectdef>
    <enumerationdef>
        <attributedef name="outputclass"/>
        <subjectdef keyref="outputclassFig"/>
    </enumerationdef>
</subjectScheme>

On Tue, Jul 26, 2016 at 9:30 AM, Eliot Kimber <ekimber@contrext.com> wrote:

Radu's example has a top-level subjectdef that is then referenced by key from within another top-level subjectdef. This example can be generalized as:

<subjectdef keys="toplevel-01">
  <subjectdef keys="child-01"/>
</subjectdef>
<subjectdef keys="toplevel-02">
  <subjectdef keys="child-02"/>
  <subjectdef keyref="toplevel-01"/>
</ subjectdef>
<enumerationdef>
  <attributedef name="attribute-A"/>
  <subjectdef keyref="toplevel-02"/>
</enumerationdef>

The question is what is the implication of the keyref to toplevel-01 within toplevel-02?

The specification says that top-level subjectdefs (by which I think we mean subjectdefs with no direct-parent subjectdefs) define categories and that their children/descendants (spec is inconsistent on this point) define the allowed values. (2.2.3.2 "Defining controlled values for attributes" and 2.2.3.4 "Processing controlled attribute values")

Because toplevel-01 is a top-level subject definition, it clearly defines a category.

However, the language in 2.2.3.4 "Processing controlled attribute values" makes it clear that all the descendants of a top-level subject definition are treated as potential values. In that case, non-leaf, non-root subject definitions act as both categories (in the sense that they name and collect a set of subordinate subjects) and values.

Given that, my analysis is that the reference to a root subject from within another subject must treat the referenced subject as though it had occurred at the point of reference, namely that it defines both an allowed value and a category containing it's descendant subjects (if any).

If this were not the case then in the example above it would be impossible to define an enumerated list where the allowed values were ["child-02", "toplevel-01"] because it would be impossible to declare the subject "toplevel-01" as both a top-level subject and a descendant subject because of key precedence rules (because only the first definition of toplevel-01 would be used).

However, if toplevel-01 is treated as a value when referenced, then it would be possible to define the value list for toplevel-02 as either ["child-02", "toplevel-01", "child-01"] (reference to "toplevel-01") or just ["child-02", "child-01"] (reference to "child-01" instead of to "toplevel-01".

That is, an interpretation of the spec that says top-level subjects are treated as top-level subjects in all use contexts disallows at least one important use case.

One counter argument to this analysis would be to require the use of key scopes: because key scope names do not contribute to the effective enumeration values, you could use a separate key scope to define "toplevel-01" as a non-root subject and then refer to it in that key scope, e.g.:

<subjectdef keyscope="scope-01" keys="child-subjects-01">
  <subjectdef keys="toplevel-01"/>
</subjectdef>
<subjectdef keys="toplevel-01">
  <subjectdef keys="child-01"/>
</subjectdef>
<subjectdef keys="toplevel-02">
  <subjectdef keys="child-02"/>
  <subjectdef keyref="scope-01.toplevel-01"/>
</ subjectdef>
<enumerationdef>
  <attributedef name="attribute-A"/>
  <subjectdef keyref="toplevel-02"/>
</enumerationdef>

Here the reference to "toplevel-01" in the scope "scope-01" is unambiguously a reference to a non-top-level subject definition.

However, this solution would require duplicating subject definitions just so that you could use the same key name as a top-level category or a descendant value, which seems unnecessary.

Cheers,

Eliot

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php