[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Filtering logic for <enumerationdef> element
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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]