possible change/clarification to proposal #1207 as previously approved by the TC

Here is an e-mail discussion that Paul and
Robert started two weeks or so ago. I don’t know that we’ve
completely settled on the answer yet, but it seems likely that we will make a
change to item #21 in the keyref proposal (issue #1207) that the TC approved last
December. I don’t think the change is a big deal. It is all about how we
handle a fairly obscure error condition. I don’t know that this change
requires a vote by the TC since it will be included in the DITA 1.2 specification
which will eventually be voted on when the spec. is approved.  But, I
wanted to let the TC know about the likely change and put something into the public
archive.

 

    -Jeff

 

From: Ogden, Jeff

Sent: Tuesday, September 23, 2008
8:53 AM

To: 'Michael Priestley'

Cc: Grosso, Paul; 'Robert D
Anderson'; 'Eliot Kimber'

Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and Specialization Elements

 

Here is the wording of item #21 from
version 8b of issue 1207 (17 December 2007):

Key
references are not allowed on and will be treated as an error if used with href
or conkeyref attributes on topicref elements that reference maps or portions of
maps that define keys.

 

In the above “href” should
have been changed to “keyref”.

 

I’d be OK with a change requiring
(MUST) that keys defined in sub-maps that are referenced using keyrefs be
ignored.  I guess it is just the presence of the @keyref or @conkeyref
that causes the sub-map key definitions to be ignored and that key definitions
in sub-maps should be ignored even if the href or conref is used as a fallback
because the keyref or conkeyref can’t be resolved.

 

Do we require (MUST), suggest (SHOULD),
allow (MAY), or prohibit (MUST NOT) issuing error or warning messages when keys
in sub-maps referenced using keys are ignored? I’d be OK with MUST or
SHOULD. I’d be uncomfortable with MAY or MUST NOT.

 

I think we need to mention this to the
DITA TC since it is a change to what they approved.

 

The new wording for item 21 might be:

 

When
keyref or conkeyref attributes are present on topicref elements or
specializations that reference maps or portions of maps any key definitions
made in the referenced maps MUST be ignored and processors SHOULD issue an
error or warning message.

 

   -Jeff

 

From: Michael
Priestley [mailto:]

Sent: Monday, September 22, 2008
9:19 PM

To: Ogden, Jeff

Cc: Grosso, Paul; Robert D
Anderson

Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and Specialization Elements

 

Hi Jeff,

Belatedly
realizing I never sent my reply to this:

I
think disallowing keys on map references is going too far. There are lots of
cases where someone might want a key on a topic to be repointed to a branch of
topics, and vice versa, when the need for a particular subject gets
expanded/reduced for a new audience or context. For example, in my map I only
need a single topic to define "foobars" but someone else reusing my
map needs to expand the foobar topic (referenced by key) into a whole
chapter/set of topics. So they repoint the foobar key from my foobar topic to
their foobar submap, which then gets pulled in where the foobar topic used to
appear.

In an
ideal world, there would be no difference between maps pulled in by keyref and
by href. But we don't live in an ideal world, so the compromise (to avoid
requiring processors to thrash on key mapping/keyref resolution recursively)
was to say that keys in maps pulled in by keyref would be ignored (since they
are being discovered after keys have already been harvested). That solution is
friendly to processors, and still allows flexibility for authors since they
could choose to include the same map by href in a no-toc etc. setting to
discover the keys if they need them.

Michael
Priestley

Lead IBM DITA Architect



http://dita.xml.org/blog/25 

 

  
  
"Ogden, Jeff"
  <> 

  
09/10/2008
  11:24 AM 

  
  
  
   

    
    
To

    
    
    
"Robert D Anderson"
    <>, "Grosso, Paul"
    <> 

    
   

   

    
    
cc

    
    
    
Michael Priestley/Toronto/IBM@IBMCA 

    
   

   

    
    
Subject

    
    
    
RE: DITA 1.2 reviews of Commonly Referenced Attributes
    and Specialization Elements

    
   

  
  
 

  
   

    
    
 

    
    
    
 

    
   

  
  

  

 

My
thinking is along these lines:

It is an error to use keys to reference ditamaps.
That is what the

proposal calls for and it is the only thing
related to this that the

proposal is clear about. Not treating this as an
error is likely to

produce results that are different from what users
were expecting and it

may be difficult for them to understand why.

That we always want to tell the users about the
error.

How processors do or don't recover from the error
is up to the

processors. Different implementations will have
different philosophies

about this with some thinking the right thing to
do is to stop following

certain types of errors to avoid producing may
other errors or warnings

that are caused by the first error and others
thinking that it is better

to try to continue following errors in order to
find additional problems

in a single run even if some of those problems may
be caused by the

original error.

That as long as processors issue a message about
the error so users can

fix it, it doesn't really matter if different
implementations give

different results following such an error.
 We only need to worry about

getting the same or at least very similar results
when there are no

errors.

If we adopted the approach that implementations
are free to not produce

an error message and that implantations are free
to ignore key

definitions in maps referenced using keys, that
that is effectively

saying that the use of keys for map references
isn't an error. And I

don't think we want to do that.

   -Jeff

>