dita — archive

[Jonatan Lundin]

Hi,
I've had some problems with my mail. Hopefully it gets through now.
Br,
Jonatan
 

***********************
Jonatan Lundin
Information Architect
+46 (0)21 440 11 11
Citec Information, Sweden
www.citec.com



From: Jonatan Lundin
Sent: Mon 1/11/2010 1:12 AM
To: Su-Laine Yeo; Robert D Anderson
Cc: DITA TC
Subject: RE: [dita] Conditional processing for <prop action ="include">





Hi,
 
I thought of, again, share some feedback about concerns regarding the filtering logic. Forgive me if I’m interrupting something or have misunderstood things, but the feedback maybe helpful when clarifying the arch spec. Maybe this is not the right forum to bring up my concerns, but feedback can never harm. Please also correct me if I'm wrong.
 
First of all I share the confusion about how the include statement is to be interpreted. From my content management experience you have two perspectives on what to filter; (1) either you want to say what is included and implicitly everything else shall be excluded or you (2) want to say what is excluded and implicitly everything else is included. The (1) is used when a larger amount of occurrences are to be excluded than included and (2) when a larger amount of occurrences are to be included.
 
In DITA 1.1 you must first say that all element having a value of a specific attribute must be excluded and then say which elements to be included by defining a specific value. Of course it would be better if tools would interpret include as to exclude everything else? 
 
Consider the following:
 
Conditions in instance
<p product=”A B” platform=”X”>Text…
<p product=”A D” platform=”Y”>Text…
<p product=”B D” platform=”Z”>Text…
<p product=”D” platform=”X Z”>Text…
…
<p product=”Z” platform=”X Z”>Text…
 
 
You want to create an output containing only product A. You use the include statement since it is more convenient than saying to exclude all product B to Z.
<prop att=”product” action=”exclude”/>
<prop att=”product” value=”A” action=”include”/>
 
But what if the DITAVAL is according to
<prop att=”product” action=”exclude”/>
<prop att=”product” value=”A” action=”include”/>
<prop att=”platform” action=”exclude”/>
<prop att=”platform” value=”Z” action=”include”/>
 
What will be the output? Using several attributes for filtering can make complex situations.
 
One scenario is to have the DITAVAL only contain an “include” or “exclude” statement:
<val>
            <include>
                        <prop att=”product” val=”A”>
                        <prop att=”product” val=”B”>
                        <prop att=”product” val=”C”>
            </include>
</val>
Or 
<val>
            <exclude>
                        <prop att=”product” val=”A”>
                        <prop att=”product” val=”B”>
                        <prop att=”product” val=”C”>
            </exclude>
</val>
 
The DITAVAL can then not contain both an “include” and “exclude” element. The processing would be that element carrying an attribute value that is said to be included shall be included and then all elements in same instance having an attribute value that do not meet the include statement are excluded in the output.
 
Another solution that has been discussed (available as a proposal for 1.3) in the machine industry SC is to only use one (1) attribute for filtering. The “audience”, “platform” and “product” are, at least to me, not enough for machine industry applications. In machine industry domain I’m used to use product components (material parts, sub assemblies etc) as the entity for filtering – thus nor the product or platform apply. There are also other areas you want to use for filtering, like “media”, “type-of-deliverable”, “technology-standard” etc. To add more filtering attributes would clutter a UI even more. You can specialize and also the otherprops attribute is available which is great. Instead the today available filtering attributes are replaced by one generic (then the chain to 1.0 will be broken).
 
But using the subject scheme as a mechanism allows for a more flexible approach using only one (1) attribute for filtering. Consider a subject scheme as:
 
<subjectdef keys=”component”>
            <subjectdef keys=”A”/>
<subjectdef keys=”B”/>
</subjectdef>
<subjectdef keys=”platform”>
            <subjectdef keys=”X”/>
<subjectdef keys=”Y”/>
</subjectdef>
<enumerationdef>
            <attributedef name=”otherprops”/>
            <subjectdef keyref=”component”/>
            <subjectdef keyref=”platform”/>
</enumerationdef>
 
Then when applying the condition in instance the subject category name is also used:
 
<p otherprops=”(component=’A’) (platform=’X’)”>
 
The technical writer will also be aware of the subject categories. The DITAVAL processing engine must evaluate each subject category for inclusion or exclusion. Nothing prevents tools to do like this in DITA 1.2? Of course then to build expressions using AND, OR etc would enhance the flexibility even further (or make it even more complex).
 
Best regards,
Jonatan
 

***********************
Jonatan Lundin
Information Architect
+46 (0)21 440 11 11
Citec Information, Sweden
www.citec.com



From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
Sent: Sat 1/9/2010 3:29 AM
To: Robert D Anderson
Cc: DITA TC
Subject: RE: [dita] Conditional processing for <prop action ="include">



(I wrote the following message over the past couple of days before Jonatan's message came in, so it doesn't address any of the issues he raised.)

Thanks Robert. I had a feeling it would end up as #5.

You're right of course about "include" statements being operative when the default action is set to "exclude". I'd forgotten about the option to specify the default that was added in DITA 1.1. I think the parts of the spec that I mentioned still need to be clarified to make it more clear when "include" statements are operative. E.g., the example in the <val> element description is wrong. I'll suggest specific changes on the TC wiki.

I am still concerned about the substance of the processing rules for the <enumerationdef> element. The spec currently uses an example to prescribe processor behaviour and says:

"This hierarchical enumeration affects filtering and flagging as follows:
- When filtering includes or excludes Linux explicitly and doesn't identify RedHat explicitly, processes should also apply the filtering operation to the RedHat content because RedHat is a special kind of Linux.
- When filtering includes RedHat explicitly and doesn't explicitly exclude Linux, processes should include the general Linux content because the general Linux content applies to RedHat Linux.
- When filtering excludes RedHat explicitly and doesn't explicitly include or exclude Linux, processes should include the general Linux content because the exclusion doesn't necessarily apply to other kinds of Linux."

Under DITA 1.1 processing rules, in a DITAVAL file you can say that a particular attribute defaults to either inclusion or exclusion. If you say that the @platform attribute defaults to inclusion, then "exclude" statements are operative and "include" statements are non-operative. If you say that the @platform attribute defaults to exclusion, then "include" statements are operative and "exclude" statements are non-operative. You can't have a DITAVAL file that says to include some platforms and exclude other platforms, and expect both types of statements to be operative.

I rewrote the above rules in the spirit of what I think the spec is trying to say. Is the following right?:

For the following cases, processors should be aware of hierarchies of attributes defined in subject scheme maps, and process them differently than they would if the attributes were not defined in a hierarchy:
- If a processor is instructed to exclude Linux and an element has @platform = "RedHat", it should be excluded because RedHat is a special kind of Linux. A processor unaware of the relationship between RedHat and Linux would include the element.
- If a processor is instructed to include Redhat and an element has @platform = "Linux", it should be included because the general Linux content applies to RedHat. A processor unaware of the relationship between RedHat and Linux would exclude the element.
-  If a processor is instructed to include Linux and an element has @platform = "Redhat", it should be included because RedHat is a special kind of Linux. A processor unaware of the relationship between RedHat and Linux would exclude the element.

For the following case, there is no expected difference in the processing of attributes defined in subject scheme maps and attributes that are not defined in subject scheme maps:
- If a processor is instructed to exclude Redhat and an element has @platform = "Linux", it should be included because the exclusion doesn't necessarily apply to other kinds of Linux.

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/