OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
Expand all | Collapse all

Filtering logic for

  • 1.  Filtering logic for

    Posted 01-05-2010 22:09
    
    
    
    
    
    
    
    
    
    

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



  • 2.  RE: [dita] Filtering logic for

    Posted 01-05-2010 22:21
    
    
    
    
    
    
    
    
    
    
    
    

    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/



  • 3.  RE: [dita] Filtering logic for

    Posted 01-05-2010 22:29
    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
    


  • 4.  RE: [dita] Filtering logic for

    Posted 01-05-2010 23:01
    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
    
    
    


  • 5.  RE: [dita] Filtering logic for

    Posted 01-06-2010 16:28
    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
     
     
    
     
    
    


  • 6.  RE: [Potential SPAM] RE: [dita] Filtering logic for

    Posted 01-06-2010 16:50
    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	
    	
    
    


  • 7.  Re: Filtering logic for

    Posted 01-06-2010 17:59

    Hi, Joel:

    In fact, the scheme provides an alternative to defining values with element types.

    The scheme is a specialized map. As the collection structure in DITA, maps are well suited to defining lists of values or even hierarchies of values for a category. Map aggregation provides a way to merge lists or hierarchies (including schemes defined by separate teams). Schemes also give you a way to attach properties to a controlled value such as a more readable label (via the navtitle attribute or subelement). It's quite convenient.


    Hoping that clarifies,


    Erik Hennum
    ehennum AT us DOT ibm DOT com


    "Joel Finkle" <Joel.Finkle@imagesolutions.com> wrote on 01/06/2010 08:49:37 AM:

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

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



  • 8.  RE: [dita] Filtering logic for

    Posted 01-06-2010 17:15
    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, 


  • 9.  RE: [dita] Filtering logic for

    Posted 01-07-2010 18:59
    Bruce asked:
    > Do we want to mandate this [implementations] for every feature ...?
    
    I'd say yes, require one or two implementations for every feature.  No
    exceptions. If it is a simple feature, the implementation may only
    require that we create or update the DTDs, XSDs, and related files, post
    a zip with the updates on the TC Web site, and get a couple of folks to
    install and try them out.
    
    In any case we should always require that new or updated DTDs, XDSs, and
    specification topics be available before any new or updated feature is
    finally accepted for inclusion in a particular version of the DITA spec.
    
       -Jeff
    
    > 


  • 10.  RE: [dita] Filtering logic for

    Posted 01-06-2010 17:30
    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"                                                
                 


  • 11.  RE: [dita] Filtering logic for

    Posted 01-06-2010 22:39
    (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
    
    


  • 12.  Re: [dita] Filtering logic for

    Posted 01-06-2010 23:08
    On 1/6/10 4:35 PM, "Su-Laine Yeo" 


  • 13.  RE: [dita] Filtering logic for

    Posted 01-07-2010 04:29
    Eliot, that's a brilliant way of looking at it. I've gone from being
    depressed about this feature to actually being excited about it. Cool!
    
    :) 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/
    
    
    
    


  • 14.  RE: [dita] Filtering logic for

    Posted 01-07-2010 18:52
    
    
    
    
    
    
    
    
    
    
    

    So, if I'm following this discussion correctly, this issue is pretty much resolved:

    1.  The feature as approved by the DITA TC stays in as part of DITA 1.2.

    2.  There is still a question about a part of proposal being omitted from the draft DITA 1.2 spec. and what, if anything, we should do about that.  Robert suggested leaving it out of DITA 1.2.

    3.  We'll try to come up with a better process for DITA 1.3.

    So what do we want to do about item #2?  If the omitted description was really part of the proposal that was approved by the TC, is there a reason not to include it now other than that that is more work for the 4th review and we are getting tired?  To be legalistic, to leave something out that was previously approved by a vote of the TC really requires another vote by the TC.  I guess we don’t have to be legalistic about everything and I could live with this either way.  Mostly we just need to make a decision.

       -Jeff

    >



  • 15.  RE: [dita] Filtering logic for

    Posted 01-09-2010 00:00
    
    
    
    
    
    
    
    
    
    
    

    Thanks Jeff for the summary. Regarding item #2, I also believe it should be left out. I assume that we if nobody asks for it to be re-added, we don’t need to discuss it further, right?

    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/

    From: Ogden, Jeff [mailto:jogden@ptc.com]
    Sent: Thursday, January 07, 2010 10:52 AM
    To: Su-Laine Yeo; Eliot Kimber
    Cc: dita
    Subject: RE: [dita] Filtering logic for <enumerationdef> element

    So, if I'm following this discussion correctly, this issue is pretty much resolved:

    1.  The feature as approved by the DITA TC stays in as part of DITA 1.2.

    2.  There is still a question about a part of proposal being omitted from the draft DITA 1.2 spec. and what, if anything, we should do about that.  Robert suggested leaving it out of DITA 1.2.

    3.  We'll try to come up with a better process for DITA 1.3.

    So what do we want to do about item #2?  If the omitted description was really part of the proposal that was approved by the TC, is there a reason not to include it now other than that that is more work for the 4th review and we are getting tired?  To be legalistic, to leave something out that was previously approved by a vote of the TC really requires another vote by the TC.  I guess we don’t have to be legalistic about everything and I could live with this either way.  Mostly we just need to make a decision.

       -Jeff

    >



  • 16.  RE: [dita] Filtering logic for

    Posted 01-07-2010 15:53
    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
    
    
    > 


  • 17.  RE: [dita] Filtering logic for

    Posted 01-11-2010 22:14
    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/