Re: [dita] Conditional processing for <prop action ="include">

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

Hi Su-Laine,

> 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.

Does "only for the benefit of people looking at DITAVAL" mean that this
would never have any effect except that people reading the file see it? If
so - that is not the case. It is possible to set a default value of
"exclude" for a single attribute or for all attributes; in that case, all
property values may default to "exclude", and only those that explicitly
say "include" are treated as include.

Specifically, in the description of the prop element, it says in DITA 1.1:

There can be at most one occurrence of a "prop" element with no attribute
specified (setting a default action for every prop element), at most one
for each attribute with no value specified (setting the default action for
a specific attribute), and at most one with each attribute value
specification (to avoid conflicting actions for the same attribute value).

Thus - prop with no attribute specified sets a default action for every
prop element. To set the default to "exclude":
<prop action="exclude"/>

A prop with an attribute and no value sets a default for that attribute. To
set the default for @platform to exclude:
<prop att="platform" action="exclude"/>

> 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”/>.

That behavior is covered in the processing spec, in the section about
conditional processing - specifically, the section "Filtering logic":
http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html

When there are two values, evaluate each. If any evaluate to "include", the
element is included. If all values in a single attribute evaluate to
"exclude", it is excluded.

> 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.

I don't get the same implication from that - but perhaps that's because I'm
familiar with the "exclude everything (or this attribute) by default"
option. Maybe that needs to be made clear?

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

This may need to be reconciled, but I'm not sure - the include statements
are operative.

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

Same as above - they 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.

We cannot do that - they are (or may be) operative. At the most, we should
provide additional explanation that clarifies when they are or are not
operative.

> 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.

I believe this behavior is already part of the spec. Certainly the conflict
resolution behavior has been defined from DITA 1.0.

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

Can't do that (per above).

> 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?

I think that #4 is appropriate - because in my opinion all of these cases
are covered. An alternative is #5 - which is, leave the status quo, but
provide better examples for prop when used to set defaults.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

"Su-Laine Yeo" <su-laine.yeo@justsystems.com> wrote on 01/05/2010 03:21:45
PM:

> "Su-Laine Yeo" <su-laine.yeo@justsystems.com>
> 01/05/2010 03:21 PM
>
> To
>
> "DITA TC" <dita@lists.oasis-open.org>
>
> cc
>
> Subject
>
> [dita] 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/