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: [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: 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/IssueControlledV
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_workgroups.php




The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from all computers.


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