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

["Ogden, Jeff" <jogden@ptc.com>]

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 <glossentry> element, but I only noticed it
> after we voted in the proposal and therefore shut up. With hind-sight,
> now that we're reopening so many "approved" proposals, moving forward
> I'll be less strict with myself on these issues in order to bring them
> up sooner rather than later in our spec writing process.
> 
> Gershon
> 
> -----Original Message-----
> From: ekimber [mailto:ekimber@reallysi.com]
> Sent: Thursday, September 03, 2009 1:20 AM
> To: Ogden, Jeff; dita
> Subject: Re: [dita] Issue: glossary.dtd does not conform to 1.2 spec
> filenaming rules
> 
> On 9/2/09 4:53 PM, "Ogden, Jeff" <jogden@ptc.com> wrote:
> 
> > 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.
> 
> Fair enough, if that is the consensus of the TC. I bring it up because
> it's a rather obvious bug made more obvious by our new language around
> vocabulary module coding rules.
> 
> If it caused me an implementation difficulty it will almost certainly
> cause others implementation difficulties.
> 
> > Is the problem with the name for glossary.dtd or is it really
> > glossary.ent and glossary.mod that are the problem?
> 
> 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.
> 
> > 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?
> 
> You put it in it's own directory.
> 
> You should never, as a matter of practice, be putting local shells in
> the distribution directory for the TC-provided shells.
> 
> If you're using the Toolkit to manage all your doctypes, then the
> easiest thing to do is to create a plugin with your local shells,
which
> keeps things clearly separated and automates management of the master
> catalog.
> 
> This does require that you always refer to your shells by public ID,
> absolute URL or URI, or by a relative path that gets to the right
place.
> Simply having "concept.dtd" map to a particular shell would not be
good
> practice.
> 
> > Do we have the same issue with glossary.xsd?
> 
> Yes.
> 
> > 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"
> 
> We wouldn't have to change these (they would need to still resolve to
> my
> proposed "shell" versions of those files that then pull in the
> correctly-named versions.
> 
> We would need to new public IDs and URIs for the correctly-named
> versions of these modules. Users using the old names would be
> unaffected
> (at least in 1.2). Users starting from scratch could of course point
to
> the properly-named versions directly.
> 
> Thus change, if done this way, wouldn't break any existing tools.
> 
> Note that we can *never* in 1.x define a topic type called "glossary"
> since that name is already taken, so if we want to define a topic type
> that is a collection of glossary entries and glossary groups, we'd
have
> to call it something else.
> 
> 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