OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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:
 
http://tinyurl.com/y9ter82
 
 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)"
 
Discussion by Michael at http://tinyurl.com/yejbupm
Apr 11, 2006
 
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.
 


From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
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 Id 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/



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]