[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Filtering logic for <enumerationdef> element
Among other things Su-Laine wrote: > would anyone object to marking the entire Subject
Scheme topic set as being non-normative for DITA 1.2? I’m not expressing an opinion on if we should or shouldn’t
do this for DITA 1.2, but if the TC chooses to make a change along the lines of
this suggestion, I think the right way to do it is to make the “Subject
Schema feature” optional rather than non-normative. That is, implementers
don’t have to implement it, but if they do implement it, they need to do
so by following the must, should, and may requirements. You could of
course go into the proposal and make more or even all of it should or may
rather than must. Or if you really want to make it non-normative, I think we
should just remove it from the DITA 1.2 spec. entirely and keep it around as a
draft spec. for people to implement and try out informally and we could then decide
what to do for DITA 1.3. For DITA 1.3 I think we should do something like
this for all proposal (require one or perhaps even two implementations of all
proposals before final approval of a feature and inclusion in the DITA spec.). -Jeff From: Su-Laine Yeo
[mailto:su-laine.yeo@justsystems.com] 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, it’ll 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 JustSystems
Canada, Inc. XMetaL Community Forums:
http://forums.xmetal.com/ |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]