Re: indexing

[laszlo kovacs <laszlo kovacs Sun COM>]

> 
> Hi all:
> one feature almost all our docs are sorely missing (with the exception
> of the users guide for 1.2) is an index. I think we need to do something
> about it.
> 
> Ideal solution would be:
> 
>  a. we put tags like
> 
>    <indexterm><primary>Applets</primary>
>               <secondary>adding to panel</secondary>
>    </indexterm>
>    in our documents (in this case - in the panel manual when
>    discussing adding applets to panel).
> 
>  b. during db2html conversion, gnome-db2html would process this and
>  create an index for the document, or
> 
>  c. even better, index for documents for all core components
>  (panel, applets, nautilus,  control center,...), or  even all  gnome
>  docs is created from these tags at installation time, so we have a
>  common index.
> 
> Unfortunately, this is unrealistic. At the moment, gnome-db2html does
> not automatically produce an index. Neither, btw, does jade. However,
> I strongly feel that we need an index *now* - make it a hack if we
> must.

I wonder how much people know about the Scrollkeeper project (not very
informative web site is scrollkeeper.sourceforge.net). This project is
about metadata based document categorizing and storing the result in xml
file(s) exported to help browsers. There are pretty high chances that
the Help sidebar in Nautilus for Gnome 1.4 will use Scrollkeeper. We
aimed to add indexing functionality in Scrollkeeper after Gnome 1.4.
This contains index extraction (in case the index info is added to the
docs as detailed above), exporting this to help browsers and integrate
this with Nautilus. Going further implementation of search through index
and other parts of the documentation and metadata is also considered.
Both Scrollkeeper and its integration with Nautilus are run by the same
people.

> 
>  Suggestions:
> 
>  1. Create an index for each doc manually, i.e. in your doc, add
>     a section like this
> 
> <index><title>Index</title>
> <indexdiv><title>A</title>
> <indexentry>
>    <primaryie>Applets</primaryie>
>            <secondaryie>adding to panel
>               - see <xref linkend="appletadd">
>            </secondaryie>
>    </primaryie>
> 
> etc. Here "appletadd" is the id of sect1 discussing this topic.
> Obviously, the problem is that you must manually update the index
> whenever the document structure changes.
> 
> or:
> 
>   2. Create a common index for all core docs as a separate document;
> instead of <xref>, use something like
>  <indexentry>
>    <primaryie>Applets</primaryie>
>            <secondaryie>adding to panel
>               - see Panel manual, section <ulink type="gnome-help"
> url="help:panel?appletadd">Adding objects to panel</ulink>
>            </secondaryie>
>    </primaryie>
> 
> 
> Obviously, 2 would be better for the user (it is better to have one
> common index than 10 individual ones) but *much* harder to maintain. On the
> other hand, sections of our documents do not change all too
> often. I think either way it is something we can do before 1.4; my
> estimate is it would take 2-3 days (for one person) to write such an
> index. Yes, it is a hack, but it will do for now. I'd vote for 2.

1. would prolly suit the way how Scrollkeeper is intended to work
better, but I am sure it could also serve the other approach. One
question though, what's the point to add the index info to docs before
Gnome 1.4 if there is no index display and search implemented? Or am I
missing something?

Laszlo