Re: [dita-comment] Comments on Ditaval and Ditavalref in DITA 1.3 spec

["Robert D Anderson" <robander@us.ibm.com>]

Hi Richard,

Thanks for the comments, and for the others that you submitted the same day on context hooks and metadata cascading. At today's DITA TC meeting, we finished discussing those that needed to go to the TC for follow-up; I've logged the comments and summarized responses here:
https://wiki.oasis-open.org/dita/DITA-1.3-public-review-1

I felt some of the comments in this thread could use with more complete responses, so I've added those below.

> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/contentmodels/cmtcd.html#cmtcd__ditavalref
>  
> How can a <ditavalref/> specified for an entire bookmap? At present
> it seems only possible for different child elements of the bookmap,
> but not the entire bookmap (which I think would be my first use case).

It's not possible to use a single ditavalref element within a bookmap, that applies to the entire bookmap. This is a side effect or limitation of any domain element that is combined with a structural specialization.

Specifically, <ditavalref> is a specialization of <topicref>. Domain specializations can be used anywhere the ancestor element appears, but cannot appear anywhere the ancestor element cannot. In a simple map, that means the <ditavalref> can appear almost anywhere - including as a child of <map>, resulting in filters that apply to the entire map. The bookmap format restricts where <topicref> can appear, which in turn restricts where <ditavalref> can appear. The same is true of <topichead>, which is a domain specialization of <topicref> and thus can only appear in a bookmap at locations that also allow <topicref>.

Alternatives include, but probably are not limited to:
* Specify the conditions externally, to a processor (not using ditavalref)
* Create a wrapper map that does nothing but import the bookmap; use the <ditavalref> in the reference to the bookmap
* Least convenient of these, repeat the ditavalref in each major branch of the bookmap

We will update the specification to help clarify that structural specializations like bookmap, which limit the use of the general <topicref> element, will also limit the use of <ditavalref> in those locations.

> ----------------
>  
> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/archSpec/base/usage-of-conditional-processing-
> attributes.html#usage-of-conditional-processing-attributes
>  
> Near the beginning of this topic, a brief sentence explaining the
> purpose/use case of groups would be helpful to the novice.
>  
> Near the end of the topic, a very small but complete example with
> grouped attributes and DITAVAL would help the novice. To me this
> whole topic actually only became clear after reading the topic afterwards.

I will add a sentence near the beginning as requested.

The small, complete example, which you located in the following topic, was originally part of this topic. It was moved out as a result of review comments that indicated the topic was overloaded, so I'm not sure how to reconcile the issue. At the moment we plan to leave the example in the following topic; reading the two together (grouping syntax, and filtering) is probably necessary to understand how filtering works with the groups.

> ----------------
>  
> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/archSpec/base/filtering.html#filtering
>  
> For completeness sake, in the first ordered list, add a third bullet
> point about what happens when the attribute is empty.

Agreed. Elsewhere the specification explicitly states that empty filtering attributes are equivalent to unspecified attributes, but the list in this topic could be confusing if you are not aware of that language.

> ----------------
>  
> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/langRef/base/ditavalref.html#ditavalref
>  
> Before the second example it says:
> “In the following branch, assume alternate rules are specified for
> the condition audience="novice". In that case, the condition
> specified in highLevel.ditaval takes precedence and so applies to
> the entire branch.”
>  
> If highLevel.ditaval has a generic rule such as <prop att="audience"
> action="" (which does not explicitly list the value “novice” )
> -- does this still have precedence?

Yes, the higher level exclude rule still has precedence, whether it is a generic rule or an explicit value. We will clarify this in the language.

> ----------------
>  
> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/langRef/ditaval/ditaval-val.html#ditaval-val
>  
> The note at the end of the figure says:
> Note: If two groups with the same name exist on different
> attributes, each group will evaluate the same way. For example,
> rules for the database group in this sample would evaluate the same
> whether the group is used within @product or @platform. See
> Conditional processing (profiling) for suggestions on how to handle
> similar groups on different attributes.
>  
> It seems to me that the same <val> syntax is used for two distinct
> cases. Would it not be sounder and less problematic to differentiate
> the syntax when defining rules for groups as compared to simple attributes?
>  
> For example, use
> <prop action="" att="product" group="database" val="dbFIRST"/>
> instead of
> <prop action="" att="database" val="dbFIRST"/>
>  
> Also, I don’t see why having the same groups across different
> attributes would need to be supported.

At this point, we're not able to change the design. The current design comes from the existing syntax for specialized attributes, which work the same way. In DITA 2.0, the four attributes now allowed to take groups will likely become specialized attributes, which would allow an automated process to migrate the groups into actual specialized attributes.

I can think of no good reason to use the same group across different attributes, but we cannot prevent an author from adding that to a file. The note at the end of this topic serves to acknowledge that it can be done, but we did not want to create additional processing complexity or exceptions to handle it.

> ----------------
>  
> http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part2-tech-
> content/langRef/ditaval/ditaval-prop.html#ditaval-prop
>  
> The third bullet point says “A <prop> element with an @att attribute
> and a @value attribute sets an action for that value within that
> attribute.”  The last part “within that attribute” is not true if a
> group is being specified (at least unless my suggestion in the
> previous comment is taken up).
>  
>  
> Further down, section “Attributes”, when defining the attribute
> @val: Worth mentioning that @val only takes a single value and not
> space separated list of values? Or, if my interpretation is wrong,
> state the opposite.

Agreed about the third bullet point, I will update this. In the Attributes section, the definition of @val already begins with "The value to be acted upon", so this is already limited to a single value.

Thanks again for the comments and detailed review.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)