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

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

The short-term aspect of this thread is what to do in 1.2. The
longer-term aspect is how should we change our process.

Su-Laine and Jeff have spoken to the latter, that "we should require one
or two implementations on the ground before including a new feature in
the spec."

Do we want to mandate this for every feature, or only for those that
require complex changes in processing? For example, <sectiondiv> is
unlikely to cause problems, and if we had that policy in place for 1.2
lack of "one or two implementations" of <sectiondiv> should not hold up
the release. (OTOH, such relatively simple features are relatively
simple to implement and test.)

Most shackles are home-made.

	/B

> -----Original Message-----
> From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] 
> Sent: Wednesday, January 06, 2010 11:28 AM
> To: Su-Laine Yeo; Robert D Anderson; Ogden, Jeff; DITA TC
> Subject: RE: [dita] Filtering logic for <enumerationdef> element
> 
> My problem with the optional/non-normative suggestions is 
> that I believe there is a very considerable need in the 
> community for lists of controlled values. Having writers type 
> in values is just not acceptable
> -- too many errors occur. Perhaps someone knows of another 
> way, short of a complete specialization, to get a picklist of 
> values into an editor using DITA conditional processing 
> attributes, not proprietary functionality.
> 
> I agree with Robert's contention that information architects 
> and managers need a mechanism for specifying controlled 
> values. That's not a comment on the current proposal's 
> details. I would like to know that they will work and will be 
> implemented in the various XML editors. 
> 
> JoAnn
> 
> JoAnn Hackos PhD
> President
> Comtech Services, Inc.
> joann.hackos@comtech-serv.com
> Skype joannhackos
>  
>  
> 
>  
> 
> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Tuesday, January 05, 2010 3:58 PM
> To: Robert D Anderson; Ogden, Jeff; DITA TC
> 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/IssueC
> ontrolledV
> alues12031.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/
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS 
> TC that generates this mail.  Follow this link to all your 
> TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
> oups.php 
> 
>