dita — archive
Conditional processing for
I agree with you that (2) is too complex for 1.2 at this stage, (1) is ugly, and (4) should not persist since as you say users are getting confused. That suggests (3) tweaking spec language to reduce confusion. But what should it say?I did some looking back to see what the intended behavior is. I found the proposal in MarkMail, and some subsequent discussion. Particularly relevant is this from Apr 11, 2006 discussion by Michael Priestly at http://tinyurl.com/yejbupm
The current proposal is as follows:
First, preserve 1.0 behavior:
<prop att="audience" val="programmer" action="exclude/> -- acts according
to 1.0 doc (if "programmer" is the only value in the "audience" attribute
of an element, the element is excluded).
<prop att="audience" val="programmer" action="include/> -- acts according
to 1.0 doc (effectively ignored, since content is included by default
anyway - used for convenience in tracking lists of potential values in
a ditaval file) Your proposal would arguably break the above 1.0
behavior, and hence backwards compatibility. (I say "arguably" because
the spec only talks about how to evaluate exclude behavior - because
the include action was a no-op, and not documented in the spec, it
doesn't have documented behavior, just existing behavior in the
toolkit, which ignores the value).
Here are some more extensive excerpts from the email archive:IssueNumber20.ditaTitle: DITA Proposed Feature # 20DITA Proposed Feature # 20action
The action to be taken. The options are:include
Include the content in output.
This is the default behavior
unless otherwise set.exclude
Exclude the content from output (if
all values in the particular attribute
are excluded).passthrough
Include the content in output, and
preserve the attribute value as
part of the output stream for
further processing. For example,
add to the class attribute in html
output, using the format for
generalized values: eg
class="programminglanguage(programmer)"Discussion by Michael at http://tinyurl.com/yejbupm
Apr 11, 2006The current proposal is as follows:
First, preserve 1.0 behavior:
<prop att="audience" val="programmer" action="exclude/> -- acts according
to 1.0 doc (if "programmer" is the only value in the "audience" attribute
of an element, the element is excluded).
<prop att="audience" val="programmer" action="include/> -- acts according
to 1.0 doc (effectively ignored, since content is included by default
anyway - used for convenience in tracking lists of potential values in
a ditaval file) Your proposal would arguably break the above 1.0
behavior, and hence backwards compatibility. (I say "arguably" because
the spec only talks about how to evaluate exclude behavior - because
the include action was a no-op, and not documented in the spec, it
doesn't have documented behavior, just existing behavior in the
toolkit, which ignores the value).
Second, allow defaults to change 1.0 behavior:
<prop att="product" action="exclude"/> -- excludes any value in the
"product" attribute, so any products that aren't explicitly included
are excluded by default.
<prop action="exclude"/> -- excludes any value in any attribute
Neither of these options are exactly equivalent to your proposed behavior, but
I think they do provide an equivalent level of control. I think the ability to
define different defaults for different attributes could be particularly
useful: if you never build docs for more than one product, but often for more
than one platform, you can set "product" default to exclude, and "platform"
default to include, for example.
To get the behavior below, an author would need to set two elements rather
than one:
1. change the default for the attribute they want to generally exclude
2. explicitly include the values in that attribute they want included
I realize that's an extra step, but I think it's a necessary extra step to:
- preserve backwards compatibility
- allow different behaviors on a per-attribute basisPaul Prescod on May 9, 2006 "Updated conditional processing feature":* <prop att="audience" val="programmer" action="flag".../>
would match against both audience="programmer"
and role="programmer"
* <prop att="role" val="programmer" action="flag" .../>
would only match against role="programmer".There's more in the thread "RE: [dita] Inverse conditionals: was: RE: [dita] New DITA Issues", e.g. starting from Chris Wong Jul 29, 2005 and reading back along the thread, and the subsequent exchange by Paul Prescod and Chris Wong with the earlier part of the thread deleted.
From: Su-Laine Yeo [mailto:[email protected]]
Sent: Tuesday, January 05, 2010 3:22 PM
To: DITA TC
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 ConsultantJustSystems Canada, Inc.
Office: 778-327-6356
[email protected]XMetaL Community Forums: http://forums.xmetal.com/