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


(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]