OASIS Darwin Information Typing Architecture (DITA) TC

We just noticed that the longdescref attribute on the 
object element in commonElements.mod is missing the 
trailing "f" in the version 1.1 dated 30 Nov 2006 available at
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/21381/dit
a1.1.zip





Is there a later version that I missed?

If not, then this looks like a bug in the DTDs.

paul

Hi Paul,

It has been that way since DITA 1.0. It looks like it was correct back in
the pre-OASIS version, which means it may have been a casualty of the DTD
spacing/comment cleanup at the time the standard was approved.

Because it was in DITA 1.0, this gets into the realm of the backwards
compatibility vs bug area. It is clearly a bug. But, it's just as clearly
backwards incompatible to change the name of an attribute. Changing it will
break existing 1.0 documents, if by any chance somebody is using the
attribute today.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Grosso, Paul" 

I'd think that, if there were anyone using this attribute,
they would have noticed the bug and reported it.  In particular,
I doubt the toolkit handles longdescre properly, so there isn't
really any backward compatibility issues since such an attribute
never worked.

Also, as it stands, the XSDs now validate a different doctype
than the DTDs, as the XSD has:

    

I would favor option 2 or 3. Option two probably makes the most sense,
given that I do not anticipate any tools specifically supporting
"longdescre" (even if they do support setting it).

Given that there will be a DTD update for this - I would also like to
include one non-functional change in the DTDs. There is a parameter entity
in the DTDs called filter-atts. It includes all of the attributes that the
spec says are to be used for filtering, flagging, etc. It also includes the
new base attribute, which the spec says is not to be used for filtering. I
would like to move this out of the entity and into the locations which use
this entity. As I said, not a functional change, but it may prevent
misconceptions that come about through browsing the DTD -- which I know
many of you do on weekends.

Thanks-

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Grosso, Paul" 

After thinking about this more and consulting a few co-workers, I'd really
prefer Paul's third approach now:
> 3.  allow both longdescref and longdescre attributes on object
>     for 1.1---deprecating longdescre and removing it in 2.0--so
>     that any legacy files using the misspelling won't cause
>     validation errors when used with the DTDs, but indicate
>     that implementations do not need to do anything with the
>     longdescre attribute (since I'm sure no implementations
>     do anything with it now).

I do think it's relatively unlikely that people are using this attribute
today. However, I think it's possible that somebody would set it without
noticing that a letter was missing. They wouldn't know it was broken unless
they looked at the docs at the same time, or carefully checked the output
to find it was not working.

Rather than have people blame DITA (or their current tool) when their docs
no longer validate, I'd rather deprecate it for a while first. We can have
the toolkit warn people and explain how to fix the problem; the language
reference can indicate that tools may issue an error for the bad version.

Anybody else care about this, aside from myself and Paul?

Thanks-

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

Robert D Anderson/Rochester/IBM@IBMUS wrote on 01/08/2007 03:15:22 PM:

> I would favor option 2 or 3. Option two probably makes the most sense,
> given that I do not anticipate any tools specifically supporting
> "longdescre" (even if they do support setting it).
>
> Given that there will be a DTD update for this - I would also like to
> include one non-functional change in the DTDs. There is a parameter
entity
> in the DTDs called filter-atts. It includes all of the attributes that
the
> spec says are to be used for filtering, flagging, etc. It also includes
the
> new base attribute, which the spec says is not to be used for filtering.
I
> would like to move this out of the entity and into the locations which
use
> this entity. As I said, not a functional change, but it may prevent
> misconceptions that come about through browsing the DTD -- which I know
> many of you do on weekends.
>
> Thanks-
>
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> (507) 253-8787, T/L 553-8787
>
> "Grosso, Paul" 

I agree with Robert. I feel we should add the correctly spelled 
attribute and let the mistake filter out in 2.0; and the we should 
deprecate the bad attribute in 1.1. It's only a minor DTD/XSD update 
that's low risk (well, almost no-risk) and some documentation updates.

Gershon.
--

Robert D Anderson wrote:
> After thinking about this more and consulting a few co-workers, I'd really
> prefer Paul's third approach now:
>> 3.  allow both longdescref and longdescre attributes on object
>>     for 1.1---deprecating longdescre and removing it in 2.0--so
>>     that any legacy files using the misspelling won't cause
>>     validation errors when used with the DTDs, but indicate
>>     that implementations do not need to do anything with the
>>     longdescre attribute (since I'm sure no implementations
>>     do anything with it now).
> 
> I do think it's relatively unlikely that people are using this attribute
> today. However, I think it's possible that somebody would set it without
> noticing that a letter was missing. They wouldn't know it was broken unless
> they looked at the docs at the same time, or carefully checked the output
> to find it was not working.
> 
> Rather than have people blame DITA (or their current tool) when their docs
> no longer validate, I'd rather deprecate it for a while first. We can have
> the toolkit warn people and explain how to fix the problem; the language
> reference can indicate that tools may issue an error for the bad version.
> 
> Anybody else care about this, aside from myself and Paul?
> 
> Thanks-
> 
> Robert D Anderson

fwiw, I've already decided to implement my suggestion #3
in Arbortext's imminent patch release (a one line addition
to the DTD) as far as the DTD is concerned.

I also note that it's pretty trivial using a wide variety
of tools to look for (using XPath notation just for
convenience) object[not(@longdescref)]/@longdescre and 
set that object element's @longdescref attribute to the
value had by that object element's @longdescre attribute.

As far as deprecating longdescre, I'd like to retract what
I said in my earlier suggestion.  (In fact, even when I
wrote it, I didn't mean literal "deprecation", but upon
rereading my comment, it does sound like I did.)

Since no version of spec itself refers to the longdescre
attribute, I see no reason to add text to the spec saying
that such an attribute is deprecated.  In fact, no such
attribute ever existed as far as the spec was concerned.
The "existence" of this attribute is really just an artifact
of a typo in one file of the distribution, but this attribute
in the true sense never existed as part of DITA 1.0 or 1.1,
and I have no desire to add a mention of it in the DITA 1.1
spec.  

Instead, we can put comments in the DTD explaining things,
and we can put a note somewhere in the distribution in some
README or Release Notes sort of file, but I would argue that
we shouldn't confuse the issue (which, I suspect, is probably
a non-issue for 99.9% of all DITA users) by mentioning this
in the DITA 1.1 spec (and then having to say in the 2.0 spec
that the deprecated longdescre attribute has been removed).

paul

> 

                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com] 
> Sent: Tuesday, 2007 January 09 08:09
> To: dita@lists.oasis-open.org
> Subject: RE: [dita] DITA 1.1 DTD error
> 
> After thinking about this more and consulting a few 
> co-workers, I'd really prefer Paul's third approach now:
>
> > 3.  allow both longdescref and longdescre attributes on object
> >     for 1.1---deprecating longdescre and removing it in 2.0--so
> >     that any legacy files using the misspelling won't cause
> >     validation errors when used with the DTDs, but indicate
> >     that implementations do not need to do anything with the
> >     longdescre attribute (since I'm sure no implementations
> >     do anything with it now).
> 
> I do think it's relatively unlikely that people are using 
> this attribute
> today. However, I think it's possible that somebody would set 
> it without
> noticing that a letter was missing. They wouldn't know it was 
> broken unless
> they looked at the docs at the same time, or carefully 
> checked the output
> to find it was not working.
> 
> Rather than have people blame DITA (or their current tool) 
> when their docs
> no longer validate, I'd rather deprecate it for a while 
> first. We can have
> the toolkit warn people and explain how to fix the problem; 
> the language
> reference can indicate that tools may issue an error for the 
> bad version.
> 
> Anybody else care about this, aside from myself and Paul?
> 
> Thanks-
> 
> Robert D Anderson