Conditional processing for <prop action ="include">

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

Title: Conditional processing for <prop action ="include">

Hi everyone,

There is a substantive issue crossing multiple topics in the DITA 1.2 draft spec, so I thought I’d bring it up here. The issue is the expected processing behavior for the action=”include” value on the DITAVAL <prop> element.

Background:

There has been quite a bit of confusion in the DITA community about how action=”include” is supposed to work. People commonly expect that if they have some content tagged as platform=”macintosh” and other content tagged as platform=”windows”, then if they want to produce a version of the document for the Mac they can say <prop att = “platform” val = “macintosh” action= “include”/>. In the OT this does not produce desired results as “include” statements are ignored by the OT.

The DITA 1.1 description is here: http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/ditaval-prop.html and it says, “Include the content in output. This is the default behavior unless otherwise set.” It does not say whether “include” statements are only for the benefit of people looking at the DITAVAL file (which is how the spec has apparently been interpreted by the OT developers) or whether “include” statements are supposed to be acted upon by processors. Nor does it give any guidance as to how processors should address cases in which there are conflicting “include” and “exclude” statements. E.g. there is no guidance on what to do with content tagged with platform=”macintosh windows” if you have <prop att = “platform” val = “macintosh” action= “include”/> and <prop att = “platform” val = “windows” action= “exclude”/>.

Issues in the draft DITA 1.2 spec:

The draft DITA 1.2 spec covers filtering include/exclude statements in the following topics:

- <prop> element: Same description as in DITA 1.1.. Ambiguous about whether “include” statements are intended to be operative

- Conditional Processing: Says, ‘ If all the values in an attribute have been set to "exclude", the attribute evaluates to "exclude” ‘

which implies by omission that “include” statements are non-operative.

- <enumerationdef> element: Defines filtering behaviour for this element in a way that implies that “include” statements are operative.

- <val> element: Has an example in which it implies the “include” statements are operative.

Question for the TC:

I think our options are as follows:

1) Change the spec to say that “include” statements are non-operative, and remove “include” statements from all examples.

2) Change the spec  to say that “include” statements are operative. Classify the level of expectation as may, should, or must. Define expected behaviour in the case of conflicts between “include” and “exclude” statements. Classify the level of expectation for conflict-resolution behaviour as may, should, or must.

3) Change the spec to  say that the behavior of “include” is currently undefined, and remove “include” statements from all examples.

4) Status quo - make no changes.

5) Variations on the above?

My first choice is #3. Option #2 does not seem feasible for DITA 1.2. Thoughts?

Cheers,

Su-Laine

Su-Laine Yeo
Solutions Consultant

JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com

www.justsystems.com

XMetaL Community Forums: http://forums.xmetal.com/