OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  DITA 1.1 DTD error

    Posted 01-06-2007 17:32
    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
    


  • 2.  Re: [dita] DITA 1.1 DTD error

    Posted 01-08-2007 03:32
    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" 


  • 3.  RE: [dita] DITA 1.1 DTD error

    Posted 01-08-2007 15:09
    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:
    
        


  • 4.  RE: [dita] DITA 1.1 DTD error

    Posted 01-08-2007 21:16
    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" 


  • 5.  RE: [dita] DITA 1.1 DTD error

    Posted 01-09-2007 14:09
    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" 


  • 6.  Re: [dita] DITA 1.1 DTD error

    Posted 01-09-2007 14:25
    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
    
    


  • 7.  RE: [dita] DITA 1.1 DTD error

    Posted 01-09-2007 15:45
    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
    
    >