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: Filtering logic for <enumerationdef> element


Title: Filtering logic for <enumerationdef> element

Hi again,

It looks like there has been an omission in copying some of the contents of http://www.oasis-open.org/committees/download.php/26359/IssueControlledValues12031.html into the spec. I noted the missing part in my review comments on the wiki, but am bringing it up on the mailing list because if I understand it correctly, I disagree with the what the missing part says.

The missing part would logically go into the <enumerationdef> element description. The missing part refers to the following example in the <enumerationdef> element description:

 <!-- Define application values -->

  <subjectdef keys="app" navtitle="Applications">

    <subjectdef keys="apacheserv" navtitle="Apache Web Server" href=""subject/apache.dita"/>

    <subjectdef keys="mysql"      navtitle="MySQL Database"    href=""subject/sql.dita"/>

  </subjectdef>

  <!-- Define types of tasks -->

  <subjectdef keys="taskType" navtitle="Task type">

    <subjectdef keys="setup"        navtitle="Setting up"/>

    <subjectdef keys="operate"      navtitle="Operating"/>

    <subjectdef keys="troubleshoot" navtitle="Troubleshooting"/>

  </subjectdef>

  <!-- Define an enumeration of the otherprops attribute, equal to

       each value in the application or task type subjects.

       This makes the following values valid for th eotherprops attribute:

       app, apacheserv, mysql, taskType, setup, operate, troubleshoot -->

<enumerationdef>

    <attributedef name="otherprops"/>

    <subjectdef keyref="app"/>

    <subjectdef keyref="taskType"/>

  </enumerationdef>

</subjectScheme>

The content of the missing part is as follows:

*********************************

The writer can then supplies the mysql and troubleshooting keys in the otherprops attribute to indicate that the content pertains to both the MySQL database and the troubleshooting task:

Figure 5. contentTopic.dita

<task ...>

  ...

  <note otherprops="mysql troubleshoot">Please check to make sure

the daemon is running.</note>

  ...

</task>

When an attribute is bound to multiple enumerations, DITA processing determines exclusion for filtering based on the enumeration category rather than on the attribute. The following example filters notes and other content that applies to MySQL and not other software applications regardless of which tasks are specified by the otherprops attribute:

<val>

·       <prop att="otherprops" val="mysql" action="exclude"/>

</val>

*********************************

My concerns with it are as follows: First, the use of a single conditional attribute for multiple meanings is not an optimal practice, because it cannot be processed correctly without both a map and a processor that is aware of this particular feature. Second and more importantly, the behaviour would result in incorrect filtering in cases where two <subjectdef> elements in an <enumerationdef> are two lists of the *same* type of thing, which is a plausible use case. For example, if your organization has many applications that are developed by different teams, you might have several lists of applications defined as <subjectdef keys="apps1" navtitle="Team 1 applications"> and <subjectdef keys="apps2" navtitle="Team 2 applications"> and <subjectdef keys="apps3" navtitle="Team 3 applications">.

I propose that we leave the missing part out. If it is left out, the expected filtering behaviour for attributes defined in <enumerationdef> will be the same as for attributes that are not defined in <enumerationdef>. If we leave the missing part out we should also change the example that is currently in the spec for the <enumerationdef> element.

If we decide to put the missing part in, itll need some clarification, e.g. change DITA processing determines to DITA processors should determine…”

As another aside, have tools been developed that do any processing of <enumerationdef> or other subject scheme elements?  If not, would anyone object to marking the entire Subject Scheme topic set as being non-normative for DITA 1.2? I am very concerned about how difficult it is to properly review this content from an armchair, i.e. without actually *using* the feature, and I am concerned that there may be undetected problems with it that we regret later. The fact that a significant omission like this is being identified at a very late stage is a reminder of the limitations of armchair-reviewing. I am not proposing any DTD changes here, just marking certain spec pages as non-normative in order to give ourselves more flexibility to improve the spec in DITA 1.3 or later.

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]