Re: indexing

[Dan Mueth <d-mueth uchicago edu>]

On Sat, 29 Jul 2000 battery841@mypad.com wrote:

> On Sat, Jul 29, 2000 at 11:12:11PM +0300, Ali Abdin wrote:
> > is what I see in the docs:
> > 
> > 1) Index - i.e. Table of Contents thing
> > 
> > 2) Glossary - List of terms (for easy searching of the docs).
> Okay.  Here are the terms which I have been taught in school, and what most
> publishers follow.
> 
> Index - A giant reference of terms and subjects in that particular book or
> manual which have page numbers by them, showing where the topic's information
> is located
> 
> Glossary - Similar to an index, but instead of a page number, it has a
> definition.
> 
> Table of Contents - The TOC shows the chapter and sub-chapter structure.  This
> belongs at the very beginning.  It also has page numbers on where to go for that
> chapter or sub-chapter.
> 
> I hope this helps.  Remember, I learned this in school, so it maybe incorrect,
> and this is based on my own definintions on each thing.
> Kevin

Thanks for defining these.  There has been some confusion, but these
are the right definitions.  Things are complicated somewhat because each
concept appears both in the rendered document as well as in a tab in the
help browser, with slightly (except for contents where it is
greatly) different meaning.  In particular:

Table of Contents (TOC) (in document) - This is generated automatically
based on the <sect> tags and appears at the top of the document.

Contents List (in browser) - This is a subject-sorted tree showing the
various documents on a system.  It is not part of the DocBook system,
since it only makes sense in a context of multiple documents.  The current
help system does not have it.  The current Nautilus system has it although
it is not sorted in a nice way.  We will need the OMF system to do it
properly.

Index (in document) - This is what you always see in the back of books. It
lists a lot of words and concepts in the book and lists the relevant page
numbers.  In DocBook, you do the indexing by hand using <index>,
<indexterm>, ...  This produces an index at the end of your document, as
you would find in a book.  The main work here is having somebody who knows
how to index (which is an art unto itself) go through and put in the
indexing tags.  Right now, I don't think any of our documents have
indexing.  We have been fortunate to have a few indexers join the GDP in
the last couple days, so we should start seeing indexes appear in some of
our documents soon.

Index List (in browser) - This is an index listing which is similar to the
Index in the back of a document, but is displayed in the help browser in a
browsable list.  Functionally, it is similar to the Index at the back of
a document.  It is much more convenient to present the index to the user
in the browser however.  It also allows one to merge multiple
indexes.  For example, a "general index" (ie. if the help browser is
opened outside of the context of a single application) would include
indexes from the GNOME Panel manual, GNOME Control Center manual, the CD
player (gtcd) manual, and any other parts of GNOME which a user would
consider a basic part of the desktop (ie. probably not Gnumeric).  Think
of somebody who wants to know how to quit GNOME or play a CD and doesn't
know which application's documentation the answer to their question lies
in.  Thus, the browser Index will depend upon the context the browser was
opened in, or possibly the selected document being viewed.

Glossary (in document) - This is essentially a dictionary covering words
in the document.  In DocBook, it is done using <glossary>, <glossterm>,
etc.  I believe this typically produces a glossary section at the end of
the document next to the index, similar to many books.  I think we will
have a single big super-glossary which all applications can share.  I
haven't played with glossaries in DocBook or figured out exactly how we
will deal with having one big glossary which many documents can share.

Glossary List (in browser) - This should be an alphabetical, browsable
list of all the terms in our super-glossary.  A user can go to this
Glossary tab and type/select any term they are curious about to see the
definition.

There are of course some questions which are still open.  For example,
should we also display the TOC in the browser?  (This would be the fourth
pane, if we used a paned system.)  It would be useful, but we may be
constrained by the UI (which has not been designed yet).  Also, the idea
of user context is an interesting one.  We want to display information
which is relevant to their context (eg. We do not want to have the Abiword
printing information in the Index List if the context is Gnumeric and the
user is searching for information on printing.)  It would be nice to get
some help from somebody who has experience with these issues.  Anybody
listening who falls into that category?

Dan