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 [future process changes]


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

> -----Original Message-----
> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
> Sent: Wednesday, January 06, 2010 12:15 PM
> To: JoAnn Hackos; Su-Laine Yeo; Robert D Anderson; Ogden, Jeff; DITA
TC
> Subject: RE: [dita] Filtering logic for <enumerationdef> element
> 
> 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, <sectiondiv> is
> unlikely to cause problems, and if we had that policy in place for 1.2
> lack of "one or two implementations" of <sectiondiv> should not hold
up
> the release. (OTOH, such relatively simple features are relatively
> simple to implement and test.)
> 
> Most shackles are home-made.
> 
> 	/B
> 
> > -----Original Message-----
> > From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com]
> > Sent: Wednesday, January 06, 2010 11:28 AM
> > To: Su-Laine Yeo; Robert D Anderson; Ogden, Jeff; DITA TC
> > Subject: RE: [dita] Filtering logic for <enumerationdef> element
> >
> > 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: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> > Sent: Tuesday, January 05, 2010 3:58 PM
> > To: Robert D Anderson; Ogden, Jeff; DITA TC
> > 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
> > ontrolledV
> > alues12031.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/
> >
> >
> >
---------------------------------------------------------------------
> > To unsubscribe from this mail list, you must leave the OASIS
> > TC that generates this mail.  Follow this link to all your
> > TCs in OASIS at:
> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
> > oups.php
> >
> >


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