RE: [dita] Groups - Proposal #12035: Generic collation element

[Deborah_Pickett@moldflow.com]

Hi Paul,

I see where you're coming from, and
I think I agree with you, but...

If a standard is to be of use to implementors,
there needs to be some explanation about expected processing, otherwise
it can happen that there isn't enough context for implementors to understand
what the feature is for.

Other standards manage this by using
RFC 2119's MAY, SHOULD, MUST, etc., stating that "This section is
normative" or "This section is informative".  It doesn't
seem that DITA 1.1 does this (yet).

I'm happy to tag the normative vs. informative
bits for #12035 if people think that it's worthwhile.

-- 
Deborah Pickett
Information Architect, Moldflow Corporation, Melbourne
Deborah_Pickett@moldflow.com

"Grosso, Paul" <pgrosso@ptc.com>

08/29/2007 03:12 AM

To	<dita@lists.oasis-open.org>
cc
Subject	RE: [dita] Groups - Proposal #12035: Generic collation element

> -----Original Message-----
> From: Deborah_Pickett@moldflow.com 
> [mailto:Deborah_Pickett@moldflow.com] 
> Sent: Wednesday, 2007 August 22 20:33
> To: Grosso, Paul
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] Groups - Proposal #12035: Generic 
> collation element (dita-proposal-collation-newtemplate.html) uploaded
> 
> "Grosso, Paul" <pgrosso@ptc.com> wrote on 21/08/2007
11:41:39 PM:
> > The text above talks about sorting glossaries, but where in
> > the DITA spec do we talk about sorting glossaries?
> 
> Nowhere, apparently, and that surprises me.  I expected the 
> description of bookmap's <glossarylist> to talk about 
> sorting, but on inspection, I see that it doesn't.  Is there
> a consensus that it should? 

We had some discussion of this topic at today's TC meeting.
Let me try to restart the email discussion here.

The latest proposal is at
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/25045/dit
a-proposal-collation-newtemplate.html

Starting from 50,000 feet up, an XML application standard
generally defines a vocabulary (e.g., set of elements and
attributes) and set of constraints (e.g., content models
and data types) via some sort of recognized language that
accomplishes this (DTDs, XML Schemas, etc.).  Furthermore,
in almost all such cases, certain application semantics
are defined by the specific standard.  These application
semantics usually include such things as which elements
and attributes should have associated linking semantics
or graphic referencing semantics or index-generating
semantics, and so on, and often these kinds of semantics
are defined by the application's written specification
(aka, the standard defining that application).  In the
case of DITA, we also define processing semantics associated 
with specialization, domains, conrefs, maps, etc.

On the other hand, there is almost always a set of semantics,
usually in the realm of "formatting" or "styling",
that is
not defined in the application's written specification, but
is left (as far as the standard is concerned) variable to be
determined by a stylesheet or other specification that is
separate from the standard for the application.

Exactly where one draws the line between the application
semantics defined in the standard and those left to a
stylesheet or other specification is always a question.
Things like what group of elements gets treated as a table,
what elements/attributes have indexing semantics (and just
what those semantics are and how an index is generated),
and what markup has associated sorting semantics are 
examples of things that could go either way.  However, 
it is important for the standard to draw this line, 
because both users and implementors need to know what 
to expect from an implementation that purports to support 
the standard.

The current DITA standard does not associate pure sorting 
semantics with anything; indexing semantics (which includes
sorting but also many other things) are associated with 
indexterm and related elements.

I would not want to get into defining and associating
sorting semantics in DITA 1.2.  This means that sorting 
related processing is not part of the DITA standard; 
instead such should be among those semantics left to be 
determined by a stylesheet or other specification.

So that brings us to the question of what this proposal 
should be proposing.  I would phrase the user requirement 
as being able to associate a sort of metadata with an element 
where the metadata in question can be called the "collate key"
for the element in question.

Period.  The DITA spec does not define how such "collate key"
metadata might affect the processing of the element.  In fact, 
contrary to a previous comment of mine, I now think the DITA 
spec shouldn't even define error handling.  It should just make 
an unambiguous statement about how the presence of a collate-as 
element assigns "collate key" metadata to a given element.  

Perhaps something like:

 If an element has one or more collate-as elements as children
 and also none of its ancestors has any collate-as elements as 
 children, the content that element's first collate-as child 
 will be considered the "collate key" value for that element.
 The "collate key" is metadata that may be used by processing
 (defined elsewhere than the DITA specification) such as sorting
 or any other case where processing auto-generates or re-orders
 items based on "collate key" values for those items.
 
I would also say something like:

 The index-sort-as element is used by index processing as defined
 elsewhere in this specification.  Index processing does not use
 the "collate key" metadata.

Some things I would specifically NOT say (because I think they
start to define behaviors and/or processing that do not belong
in the DITA spec) include:

* The contents of collate-as are never rendered to the final output

* any discussion of sorting beyond mentioning it as one possible
  (externally defined) process that might make use of the 
  "collate key" metadata.

* Default handling of the element (to ignore it)

* cases where it should be consulted (list generation).

* It is an error for an element to have more than one collate-as
  element for a child.  [Yes, I changed my mind on this one.]

* DITA implementations ....  [Other than adding an element to
  the DITA vocabulary, this proposal shouldn't propose anything
  that DITA implementations need to do differently.]

paul