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