[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Conditional processing for <prop action ="include">
Hi Gershon, > ... 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. I've got language now for the <prop> element in particular that clarifies this without making any changes to the current behaviors. I'll be checking that in to SVN today. I also added one sample to go along with the existing sample that makes these 1.1 behaviors clearer. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit "Gershon Joseph (gerjosep)" <gerjosep@cisco.com> wrote on 01/11/2010 07:44:54 AM: > RE: [dita] Conditional processing for <prop action ="include"> > > 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/ > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]