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

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

(I wrote the following message over the past couple of days before Jonatan's message came in, so it doesn't address any of the issues he raised.)

Thanks Robert. I had a feeling it would end up as #5.

You're right of course about "include" statements being operative when the default action is set to "exclude". I'd forgotten about the option to specify the default that was added in DITA 1.1. I think the parts of the spec that I mentioned still need to be clarified to make it more clear when "include" statements are operative. E.g., the example in the <val> element description is wrong. I'll suggest specific changes on the TC wiki. 

I am still concerned about the substance of the processing rules for the <enumerationdef> element. The spec currently uses an example to prescribe processor behaviour and says:

"This hierarchical enumeration affects filtering and flagging as follows:
- When filtering includes or excludes Linux explicitly and doesn't identify RedHat explicitly, processes should also apply the filtering operation to the RedHat content because RedHat is a special kind of Linux. 
- When filtering includes RedHat explicitly and doesn't explicitly exclude Linux, processes should include the general Linux content because the general Linux content applies to RedHat Linux. 
- When filtering excludes RedHat explicitly and doesn't explicitly include or exclude Linux, processes should include the general Linux content because the exclusion doesn't necessarily apply to other kinds of Linux."

Under DITA 1.1 processing rules, in a DITAVAL file you can say that a particular attribute defaults to either inclusion or exclusion. If you say that the @platform attribute defaults to inclusion, then "exclude" statements are operative and "include" statements are non-operative. If you say that the @platform attribute defaults to exclusion, then "include" statements are operative and "exclude" statements are non-operative. You can't have a DITAVAL file that says to include some platforms and exclude other platforms, and expect both types of statements to be operative.

I rewrote the above rules in the spirit of what I think the spec is trying to say. Is the following right?: 

For the following cases, processors should be aware of hierarchies of attributes defined in subject scheme maps, and process them differently than they would if the attributes were not defined in a hierarchy:
- If a processor is instructed to exclude Linux and an element has @platform = "RedHat", it should be excluded because RedHat is a special kind of Linux. A processor unaware of the relationship between RedHat and Linux would include the element.
- If a processor is instructed to include Redhat and an element has @platform = "Linux", it should be included because the general Linux content applies to RedHat. A processor unaware of the relationship between RedHat and Linux would exclude the element.
-  If a processor is instructed to include Linux and an element has @platform = "Redhat", it should be included because RedHat is a special kind of Linux. A processor unaware of the relationship between RedHat and Linux would exclude the element.

For the following case, there is no expected difference in the processing of attributes defined in subject scheme maps and attributes that are not defined in subject scheme maps:
- If a processor is instructed to exclude Redhat and an element has @platform = "Linux", it should be included because the exclusion doesn't necessarily apply to other kinds of Linux. 

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/



-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com] 
Sent: Tuesday, January 05, 2010 1:25 PM
To: Su-Laine Yeo
Cc: DITA TC
Subject: Re: [dita] Conditional processing for <prop action ="include">

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/