RE: [dita] Filtering logic for <enumerationdef> element

[Robert D Anderson <robander@us.ibm.com>]

Hi Su-Laine,

Earlier versions of the subject scheme have been in use within IBM for many
years. Those versions have gone through small changes over time, leading to
the version that was proposed to (and approved by) the TC. If it is taken
out of the spec or made non-normative, I do not see why any new people
would see a reason to try it out, meaning that we will be in exactly the
same situation in the future -- IBM will contribute the proposal just as it
is now. Until then, people outside of IBM will continue looking for similar
functions and will come up with alternate implementations that do not work
together.

Regarding DITA 1.3, I will be thrilled to have a better process. But, we
should not impose that process after the fact on one specific proposal from
DITA 1.2. We established a process for DITA 1.2 proposals, and that process
was followed with this just as it was with other proposals.
* The initial proposal was made, and the TC approved moving on to the full
proposal (as it did with most items).
* The full proposal was written, sent to the TC, and approved for inclusion
in DITA 1.2.
* The proposal was written up in the spec, which was sent out for review.
For this item in particular, all of the content has been available for
review in the language spec since fall 2008.
* The proposal was implemented in one tool (the DITA Open Toolkit) in
May/June of 2009
* Only minor changes resulted from reviews of the language spec, and there
was no new information in the three official drafts last year.

At any of those points, TC members could have objected to this item as a
whole, or to individual points. There was certainly a lot of discussion at
the first two points, but in the end the proposal passed. We've said at
many points in the last two years that the only changes we would still
accept to DITA 1.2 were bug fixes or low-impact changes to new features
(but only when the change was critical and could not wait for 1.3). I
personally feel that by this very late point it is too late to remove an
entire new item, especially when up to this now the only review comments on
that item have been relatively minor; the removal of this entire item would
certainly constitute a major change to the language specification as it has
existed for over a year.

For the specific item you mentioned that seems to have been dropped from
the proposal - you are right that it was missed in the spec write-up. My
thought on that is, if nobody noticed that item was missing up to this
point, then it stays out, particularly since it is not required by any of
the rest of the proposal. The TC can address it in 1.3, using whatever new
approval process is in place.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit


                                                                           
             "Su-Laine Yeo"                                                
             <su-laine.yeo@jus                                             
             tsystems.com>                                              To 
                                       Robert D                            
             01/05/2010 05:58          Anderson/Rochester/IBM@IBMUS,       
             PM                        "Ogden, Jeff" <jogden@ptc.com>,     
                                       "DITA TC"                           
                                       <dita@lists.oasis-open.org>         
                                                                        cc 
                                                                           
                                                                   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/