OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-02-2009 06:12
    It was wrong in 1.1, but it's really wrong in 1.2, where we're more concrete
    about conformance rules for shell DTDs and vocabulary modules.
    
    The spec is quite clear that topic type modules and shells should be named
    to reflect the topic element type name.
    
    That means the module currently named "glossary.*" should be "glossentry.*".
    
    I realize that just renaming the files would probably break a lot of things.
    
    My suggestion is to rename the files and create "dummy" versions of the
    originally-named files that simply pull in the correctly-named files via
    entity reference or XSD include.
    
    The catalogs could point to the correctly-named files since any system doing
    catalog-based resolution shouldn't care what the system ID of the resolved
    file is.
    
    This aspect of glossentry has bothered me for a while, but it caused me an
    actual processing problem because I have scripts that depend on topic
    modules (in particular, the standard-provided shells) having the same name
    as the topic type (in my case, I have a list of topic type names from which
    I can construct the filenames of the shells as well as the public IDs for
    each shell, except for glossentry).
    
    I fixed the problem locally by renaming glossary.dtd to glossentry.dtd, but
    that's not really a sustainable solution.
    
    Cheers,
    
    E.
    
    ----
    Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
    email:  ekimber@reallysi.com 


  • 2.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-02-2009 21:26
    Actually, I'd much rather have the module named "glossary" rather than
    "glossentry." I think "glossentry" is confusing for everybody. I never
    remember that that is where I'm supposed to start. In general, the whole
    thing needs to be fixed for 1.3
    JoAnn
    
    
    On 9/2/09 12:11 AM, "Eliot Kimber" 


  • 3.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-02-2009 21:37
    On 9/2/09 4:25 PM, "Joann Hackos" 


  • 4.  RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-02-2009 21:57
    
    
    
    
    
    
    
    
    
    
    

    I’m inclined to think that we’ve lived with the inconsistency between glossary and glossentry for a couple of years now without serious problems, so we can probably ignore it for DITA 1.2 and deal with it, if it needs to be dealt with at all, as part of DITA 1.3.

    Is the problem with the name for glossary.dtd or is it really glossary.ent and glossary.mod that are the problem?

    If I create a new map or topic doctype shell that reuses an existing type, but includes a different set of domains or does something different in terms of topic nesting, do I have to use the same file name for the new shell's DTD?  How can that work?

    Do we have the same issue with glossary.xsd?

    In addition to the file name, is there a problem with the PUBLIC IDs and URIs that we use:

    PUBLIC "-//OASIS//DTD DITA Glossary//EN"     

    PUBLIC "-//OASIS//ELEMENTS DITA Glossary//EN"  

    PUBLIC "-//OASIS//ENTITIES DITA Glossary//EN"

    URI "urn:oasis:names:tc:dita:xsd:glossary.xsd"

    URI "urn:oasis:names:tc:dita:xsd:glossaryMod.xsd"     

    Changing the PUBLIC IDs or URIs would be an even bigger deal than changing the filenames.

        -Jeff

    > -----Original Message-----

    > From: ekimber [mailto:ekimber@reallysi.com]

    > Sent: Wednesday, September 02, 2009 2:11 AM

    > To: dita

    > Subject: [dita] Issue: glossary.dtd does not conform to 1.2 spec

    > filenaming rules

    >

    > It was wrong in 1.1, but it's really wrong in 1.2, where we're more

    > concrete

    > about conformance rules for shell DTDs and vocabulary modules.

    >

    > The spec is quite clear that topic type modules and shells should be

    > named

    > to reflect the topic element type name.

    >

    > That means the module currently named "glossary.*" should be

    > "glossentry.*".

    >

    > I realize that just renaming the files would probably break a lot of

    > things.

    >

    > My suggestion is to rename the files and create "dummy" versions of the

    > originally-named files that simply pull in the correctly-named files

    > via

    > entity reference or XSD include.

    >

    > The catalogs could point to the correctly-named files since any system

    > doing

    > catalog-based resolution shouldn't care what the system ID of the

    > resolved

    > file is.

    >

    > This aspect of glossentry has bothered me for a while, but it caused me

    > an

    > actual processing problem because I have scripts that depend on topic

    > modules (in particular, the standard-provided shells) having the same

    > name

    > as the topic type (in my case, I have a list of topic type names from

    > which

    > I can construct the filenames of the shells as well as the public IDs

    > for

    > each shell, except for glossentry).

    >

    > I fixed the problem locally by renaming glossary.dtd to glossentry.dtd,

    > but

    > that's not really a sustainable solution.

    >

    > Cheers,

    >

    > E.

    >

    > ----

    > Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

    > email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

    > office: 610.631.6770 | cell: 512.554.9368

    > 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

    > www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com

    > <http://blog.reallysi.com> | www.rsuitecms.com

    > <http://www.rsuitecms.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



  • 5.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-02-2009 22:21
    On 9/2/09 4:53 PM, "Ogden, Jeff" 


  • 6.  RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-04-2009 16:40
    In the lang ref, in topic.dita, I find a mention of a 


  • 7.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-04-2009 16:44
    On 9/4/09 11:40 AM, "Bruce Nevin (bnevin)" 


  • 8.  RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-08-2009 09:55
    Further to Eliot's comment:
    "It's primarily with the modules--the spec currently doesn't require
    shells to have any particular name, although the convention of making
    the shell the same as the topic type is pretty well established."
    
    So maybe we should close this hole in the 1.2 spec and add this
    convention along with all the others we've already added in 1.2? Seems
    silly to me to suggest conventions for everything else and not suggest
    any for the shell name.
    
    I also agree with Eliot that if the glossary vs. glossentry caused him
    pain, it's likely to trip up others too. I vote for the bug fix Eliot
    suggests. I've had the same concerns about the confusion of "glossary"
    shell being driven by a 


  • 9.  RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-08-2009 14:52
    Are the conventions all "SHOULD" rather than "MUST"?
    
    Because there can be different doctype shells that use the same types
    and you should use different names for different shells, how can we have
    a convention that all the shells be named after the type?  We can choose
    to use the type name for one (perhaps the only one) that we include as
    an offici8al part of the specification, but we can't impose this as a
    requirement on others.
    
       -Jeff
    
    > -----Original Message-----
    > From: Gershon Joseph (gerjosep) [mailto:gerjosep@cisco.com]
    > Sent: Tuesday, September 08, 2009 5:55 AM
    > To: ekimber; Ogden, Jeff; dita
    > Subject: RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec
    > filenaming rules
    > 
    > Further to Eliot's comment:
    > "It's primarily with the modules--the spec currently doesn't require
    > shells to have any particular name, although the convention of making
    > the shell the same as the topic type is pretty well established."
    > 
    > So maybe we should close this hole in the 1.2 spec and add this
    > convention along with all the others we've already added in 1.2? Seems
    > silly to me to suggest conventions for everything else and not suggest
    > any for the shell name.
    > 
    > I also agree with Eliot that if the glossary vs. glossentry caused him
    > pain, it's likely to trip up others too. I vote for the bug fix Eliot
    > suggests. I've had the same concerns about the confusion of "glossary"
    > shell being driven by a 


  • 10.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-08-2009 14:59
    On 9/8/09 9:52 AM, "Ogden, Jeff" 


  • 11.  RE: [dita] Issue: glossary.dtd does not conform to 1.2 spec filenaming rules

    Posted 09-08-2009 15:08
    Eliot, you are correct.
    
    I should have said that it is a good practice to use different file
    names for different shells. Using unique names reduces the chance of
    confusion, it allows different people or different organizations to
    organize their DITA files differently without creating conflicts, and it
    allows the DITA TC to organize things differently from release to
    release without having to worry about name conflicts.
    
        -Jeff
    
    > -----Original Message-----
    > From: ekimber [mailto:ekimber@reallysi.com]
    > Sent: Tuesday, September 08, 2009 10:59 AM
    > To: Ogden, Jeff; Gershon Joseph (gerjosep); dita
    > Subject: Re: [dita] Issue: glossary.dtd does not conform to 1.2 spec
    > filenaming rules
    > 
    > On 9/8/09 9:52 AM, "Ogden, Jeff" 


  • 12.  Re: [dita] Issue: glossary.dtd does not conform to 1.2 specfilenaming rules

    Posted 09-08-2009 16:52
    On 9/8/09 10:07 AM, "Ogden, Jeff"