[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Filtering logic for <enumerationdef> element
(merging threads) Thanks Robert. I'm so sorry to have sidetracked the discussion. I am used to thinking that cutting scope from a project will get it out the door faster and with better quality, but I'm slowly learning that it's not the case here. So I'm not going to ask for scope reductions. That said, we still have the problems that I was hoping to address via scope reduction, i.e. the spec is big and certain parts of it are very difficult to understand. It is a problem for DITA adopters if they spend a lot of time trying to wrap their heads around features that will be of little practical benefit. Subject scheme maps have plenty of potential benefit, but only if there is support from tools, particularly authoring tools. If we don't have authoring tool vendors implementing a feature, then for the vast majority of adopters the feature is of little practical benefit. When I read things that are difficult to understand and unlikely to be of practical benefit to adopters, I want to save adopters from wasting their time trying to understand it. Can anyone suggest how to solve this problem? I don't have information I can provide publicly at this time about the XMetaL team's plans for supporting this feature. But as an informal observation on past public discussions, I haven't seen any signs of authoring tool vendors jumping up and down to implement it. JoAnn and Joel made good points about the need for controlled values. XMetaL does have a way to get a picklist of values into the authoring interface using DITA conditional processing attributes without specializing DITA (go to C:\Program Files\XMetaL 6.0\Author\Conditional Text\configs and edit the text file named ct_config.xml). It doesn't do everything that the Subject Scheme Maps feature prescribes, but it does the basic thing, which is define a list of allowed values that then appear in checkboxes in the UI. Su-Laine -----Original Message----- From: Joel Finkle [mailto:Joel.Finkle@imagesolutions.com] Sent: Wednesday, January 06, 2010 8:50 AM To: JoAnn Hackos; Su-Laine Yeo; Robert D Anderson; Ogden, Jeff; DITA TC Subject: [dita] RE: [Potential SPAM] RE: [dita] Filtering logic for <enumerationdef> element I'm coming into this in the middle, so please feel free to shout me down if I'm getting off topic. I agree strongly with JoAnn's statement that controlled lists are critical. Many such controlled lists will be industry-wide, and can be specializations. Others will be company-specific: lists of products, lists of facilities, authorized signers, etc. Making those kinds of lists extensions in the DITA types seems exhausting. I would prefer to see something in the type definitions that says, "This object expects authors to enter one item selected from a set of things of the class FOO." (or zero or one, or one to n or zero to n...) Then, the authoring software could be *configured* such that there is a list of FOOs that can be selected where needed. Best of both worlds? ---- Joel Finkle Director, Regulatory Informatics Image Solutions, Inc. 100 South Jefferson Road Whippany, NJ 07981 T: 847.989.6028 joel.finkle@imagesolutions.com -----Original Message----- From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] Sent: Wednesday, January 06, 2010 10:28 AM To: Su-Laine Yeo; Robert D Anderson; Ogden, Jeff; DITA TC Subject: [Potential SPAM] RE: [dita] Filtering logic for <enumerationdef> element Importance: Low 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: Robert D Anderson [mailto:robander@us.ibm.com] Sent: Wednesday, January 06, 2010 9:29 AM To: Su-Laine Yeo Cc: DITA TC; Ogden, Jeff 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]