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

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

At Cisco we have implemented complex profiling in our DITAVAL by relying
on the following:
1. Set a default global behavior (in our case, "exclude" all profiled
content)
2. Set a default on one specific attribute to override the global
default to make it "include" by default.
3. Set explicit values for each and every attribute-value pair selected
by the user at publishing time to include (for all but one of our
profiling attributes) or exclude (for one specific attribute).

I read the DITA 1.1 DITAVAL spec once when I implemented this logic, and
didn't find it at all confusing or lacking. However, some of our
developers read it and remained confused and uninformed, and I had to
explain to them how to take our publishing UI and generate the correct
DITAVAL file. There is definitely room for improvement, but nothing that
I feel requires addressing in the current release. If the TC does
however feel we should clarify the DITAVAL processing topics, I think we
should more explicitly call out the ability to set a default for the
entire DITAVAL file, as well as for a specific attribute, and also point
out the 3 levels of default/override I mention above.


--
Gershon

-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com] 
Sent: Tuesday, January 05, 2010 11: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/