Re: Automatic Glossaries

[Shaun McCance <shaunm gnome org>]

On Fri, 2004-01-09 at 14:30, Sean Wheller wrote:
> On Friday 09 January 2004 22:05, Shaun McCance wrote:
> > On Fri, 2004-01-09 at 13:47, Sean Wheller wrote:
> > > On Friday 09 January 2004 19:45, Shaun McCance wrote:
> > > > On Fri, 2004-01-09 at 10:23, Sean Wheller wrote:
> > > > > Hi,
> > > > >
> > > > > Can we use Automatically Generated Glossary in GNOME2 Documents?
> > > > >
> > > > > Will Yelp stylesheets handle it?
> > > >
> > > > I'm not sure how you expect glossaries to be generated automatically.
> > > > The definitions have to come from somewhere.  While DocBook allows you
> > > > to put glossterms inline, this is only for the purpose of linking to
> > > > the appropriate glossentry in the glossary.
> > > >
> > > > There's no provision in DocBook for putting the glossdef inline in your
> > > > content.  Even if there were, I wouldn't recommend using it, as it
> > > > would be a content management nightmare.
> > >
> > > Please see
> > > http://www.sagehill.net/docbookxsl/Glossaries.html
> > >
> > > http://www.sagehill.net/docbookxsl/GlossDatabase.html
> >
> > Ugh, that's hardly creating a glossary automatically.  It's just a very
> > bad way of including an external glossary file.  If you want to keep the
> > glossary in an additional file (which I consider to be a good idea) then
> > what's the problem with just including it with XInclude?  I don't see
> > any need to abuse the format here.
> >
> > --
> > Shaun
> 
> Actually Shaun some would disagree with you. The automation provided by this 
> method is a timesave to say the least. Managing a glossary using XInclude can 
> be hardwork as you have to XInclude each glossentry that you want to insert 
> to the book. If you just include the root element, glossary, then your 
> document ends up containing glossterms that do not appear in the book.
> 
> This auto method ensures that the glossary contain glossterms that are only 
> relevant to the book. IMHO, its a far more eloquent solution. All I have to 
> do is maintain and keep growing my database. The more I add the easier life 
> becomes:-)
> 
> However, I do understand that it can cause some overhead under yelp. Perhaps a 
> target for the future:-)

Yes, I see your point.  It's not so much automatically creating the
glossary as it is automatically stripping it.

Nonetheless, this isn't a standard DocBook feature.  It's particular to
the processing system.  This isn't a criticism.  DocBook is a very loose
format, and all processing systems have limitations and extensions.

This, however, is a criticism:  I don't like the particular way this is
done by Norm's stylesheets.  Including a dummy glossentry, for instance,
just to conform to the DTD, is really bad form and guarantees that your
DocBook will bomb spectacularly with any other processor.

I prefer when extensions are done in a way that degrades gracefully with
processors that don't implement the feature.  I think a much better way
of doing this would be to include the entire glossary by some standard
mechanism (XInclude, entities, whatever) and then having a processing
instruction that informs the processor to strip out glossentry elements
that aren't referenced in the document.  If you then used a processor
that doesn't understand the processing instruction, the worst that
happens is that you have extra entries.

Anyway, I've only got three days till feature freeze, and I still don't
have working man and info converters.  This is definately 2.8 material.

--
Shaun