[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Filtering logic for <enumerationdef> element
Hi Robert and Jeff,
Regarding the question of making a feature optional vs. marking it as non-normative: If something is optional but normative, we will still be limited in future versions of DITA 1.x to keep the spec backwards-compatible, so problems in the spec will still have the potential to haunt us. Whereas if the section is non-normative (or taken out of the spec entirely) it won’t haunt us.
Regarding the groups in IBM that are eager for this feature: Can you not give them support for a feature that isn't in the normative DITA spec? The main reason to mark something non-normative is so that if the users hate some aspect of it, we can fix the problem in the next round of the spec instead of telling the users, "sorry, can't change that because of backwards-compatibility". I agree entirely with Jeff's suggestion that for 1.3, we should require one or two implementations on the ground before including a new feature in the spec.
Su-Laine
-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com]
Sent: Tuesday, January 05, 2010 2:29 PM
To: Ogden, Jeff
Cc: DITA TC; Su-Laine Yeo
Subject: RE: [dita] Filtering logic for <enumerationdef> element
Hi Su-Laine,
I haven't fully processed this, and I haven't thought specifically about
the specific subject scheme cases in quite a while, so I need to think it
through before commenting on the specific examples of filtering based on
the enumeration rather than on the attribute. Basically, I've been staring
at the spec and trying to edit / comment for the last 9 hours, and I'm at
my limit for the day.
That said - for your specific questions:
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?
The DITA-OT does filtering based on the Subject Scheme. I would object to
making it non-normative, as I know there are groups within IBM that are
very eager for this feature. Making it non-normative would of course
require a vote of the TC (which has already voted to include this overall
feature).
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
"Ogden, Jeff"
<jogden@ptc.com>
To
01/05/2010 05:20 "Su-Laine Yeo"
PM <su-laine.yeo@justsystems.com>,
"DITA TC"
<dita@lists.oasis-open.org>
cc
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]
Sent: Tuesday, January 05, 2010 5:06 PM
To: DITA TC
Subject: [dita] 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, 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
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]