Re: glossary

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Fri, Jun 09, 2000 at 02:37:33PM -0500 or thereabouts, Dan Mueth wrote:
> 
> On Fri, 9 Jun 2000, Alexander Kirillov wrote:
> 
> > thanks to help from skud, the glossary has really progressed - take a
> > look at http://www.math.sunysb.edu/~kirillov/glossary

Rocking.
 
> This looks like a very strong start.  I am impressed with the rate it is
> progressing.  Generally, the definitions look very good.
> 
> > However, I became confused about what we really want. Do we want it to
> > be like a dictionary, with detailed descriptions? Or a very short
> > definition, say one line?  
> 
> I would vote for a detailed description, as in a dictionary.  Typically,
> the first sentence or two provides a pretty good definition, and the
> reader can stop there if they want.  Having further information(say a
> couple more sentences) for users who would like more details or examples
> will not detract from the definition. Excessively long definitions should
> clearly be avoided.

Now we all get to disagree on the nature of "excessively long" :)
I absolutely agree that individual entries should not be essays. 
I'll bet that one or two do end up noticeably longer than the majority.

> What about figures/screenshots?  It looks like the DTD allows them.  Do
> we want to use them?  I don't see any reason not to use them in cases
> where they are helpful.  If we do use them, it will place constraints on
> how we can present the definition.  For example, a pop-up tooltip-type box
> or a couple lines at the bottom of the screen would not provide enough
> room for most screenshots.

I like the idea of linking back to docs which include such a screen
shot, if we can manage that.
 
> > Will it be supplemented by an index or some
> > kind of search engine? How they should interact? Or it should be both
> > glossary and index in one? 

I think the index should be separate, most definitely. Interaction
between the two would be good, but I don't see how we can put them
both in the same thing really, without storing up trouble for ourselves.

An index, as I think of it, is for looking terms up and finding
out where they are mentioned. A glossary is for finding out what
they are. I imagine it comes from people adding glosses to manuscripts
a long time ago? (Bloody vandals, writing on book margins, eh? :)) We 
don't really know how all the docs are going to be generated yet, but 
currently with docbook, glossaries are generated by jade and indexes 
(indices?) with this collateindex script. I don't see how you'd 
interlink them and build them, but then someone said collateindex
was in perl, so I am scared of it already :)

> I see three likely uses of the glossary: (1) A word is used in a document
> and linked to the glossary. In this case, nothing fancy needs to be done,
> although it would be nice if we could render only the term in question,
> instead of pointing to the middle of a page of glossary definitions. (2)

Definitely.

> Somebody wants to look up a word which they heard/saw somewhere that
> wasn't linked to the glossary term(eg. on the web or in a discussion).  
> In this case, an alphabetical browse index would probably be the best way
> to find the term. Perhaps we could have a "Glossary" tab in the left pane
> of the browser which had this alphabetical browse index for the glossary.

Yeah. 

> (3) Somebody wants to enrich or entertain themselves by reading a bunch of
> definitions. This would be a relatively rare use for the glossary, but
> might be nice to have.  We could present a header page with the letters of
> the alphabet linking to pages showing all the terms starting with that
> letter.  Perhaps we could place some sort of a small button("Browse"?) on
> the "Glossary" tab I suggested above which opens this glossary browse
> page.

I like this. I would use it. I was surprised to discover that it wasn't
just me who would wander round /usr/doc or the manual pages thinking, 
"What else is on my system?" and reading it. But then, I am the sort
of person who looks things up in an encyclopaedia or a dictionary and
then gets sidetracked onto all the other entries.

Telsa