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.dita
Title: DITA Proposed
Feature # 20
DITA Proposed Feature #
20
action
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)"
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).
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
basis
Paul 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.
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/