OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


Hi Bruce,

Yes, those would be good issues for the Adoption TC to address. I don't
think I've discussed the feature overview with JoAnn, but let's discuss
it offline when JoAnn is ready (presumably after she comes back from
vacation).

Cheers,
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/


-----Original Message-----
From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com] 
Sent: Thursday, January 07, 2010 7:53 AM
To: Su-Laine Yeo; DITA TC
Subject: RE: [dita] Filtering logic for <enumerationdef> element

Hi, Su-Laine -- you asked:

>  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?

This feature roadmap sort of function falls squarely into the Adoption
TC's scope, and the feature overview that JoAnn is working on is one
obvious place to address it. In addition to describing the purpose and
function of the feature (and maybe a rudimentary take on how to tag
content appropriately for it, though that belongs mostly in the lang
ref), your question calls for an assessment of how dependent it is on
tool vendors catching up before it's useful, and maybe even an
indication of what kinds of questions to ask the vendors to be sure of
compliance and support. My memory is foggy here--are you helping JoAnn
with this? I know she's under great time pressure because of her
imminent vacation.

	/Bruce


> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
> Sent: Wednesday, January 06, 2010 5:36 PM
> To: DITA TC
> 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/IssueC
> ontrolledValues12031.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]