Re: Contents

[Dan Mueth <d-mueth uchicago edu>]

(I changed the subject, since this is really more about the contents list
than the glossary.)

On Tue, 13 Jun 2000, Ali Abdin wrote:

> I just joined the list - so forgive me if this has been awnsered. But how do
> you plan on organizing the help stuff based on 'topic'.I do not think we
> should manually put man/info/sgml files in under different topics (that
> would be a lot of work and what about new apps?)
> 
> So lets envision this scenario
> Somebody creates a brand new PPP dial-up utility and creates his SGML file
> and it gets installed. How would the 'glossary' learn that it should go
> under the 'networking' sub-group?
> 
> It would be hard to ask all apps to install a file somewhere telling under
> what Glosarry item it falls under.
> 
> There needs to be an 'intelligent' way to sort items into categories -
> Unfortunately, I am not smart enough to see how? Does anybody else?

Ali,

This is a good question, and one of the main issues we have to deal with
to create a good contents list.  (BTW: I noticed you referred to the
glossary, where I think you may have meant the contents. There has been a
bit of confusion on these terms, so for clarity: The glossary is a list of
definitions, which will probably either be determined from a single
glossary file, or from merging glossary definitions from multiple files.
There are special DocBook tags for dealing with glossary items. The Index
is a list of document sections, generated by parsing DocBook indexing tags
in one or more SGML/XML file. The contents is a structured tree-style
heirarchy of documents sorted by topic.)

The Contents needs to be able to detect all the documentation installed on
the given system (info pages, man pages, HOWTO's, FAQ's, and
GNOME/KDE/other SGML/XML files).  It then needs to sort this all into a
reasonable heirarchy, preferably by subject, not format or title.  We will
need to come up with a nice categorization.

The one idea I have heard is similar to the one you mention - each
documentation file is accompanied by a meta file which describes the
documentation file, and perhaps explicitly says where it belongs in the
contents.  We discussed this briefly at GUADEC, although in no great
detail.  This file should ideally be packaged with the documentation.  It
could be one file per document, or one file describing multiple documents.  
An alternate idea would be to have the documents themselves describe what
they are about or where they belong in the Contents using meta information
tags.  Properly implementing either one of these solutions would require a
joint effort of all the main documentation projects(LDP, KDE, GNOME, OSWG,
...) to develop a new standard for this.  If we decide this is the right
way to do things, we may develop this in the future.  I doubt we can
achieve this before GNOME 2.0.

So, if we think this is the best long term solution we can find, we can
imagine doing a temporary solution in this direction.  For example, we
could make a large file containing this information for all the standard
documents on major distributions.  The browser could parse this file,
determine which objects are actually installed, and present those in the
right place in the Contents.  It might also look for other meta files for
packages which actually present them (ie. probably just GNOME apps for
now).

Of course if anybody has another approach asides from using meta-tags in
the documentation or external files containing this information, please
describe these other alternatives.

Dan