indexing

[Alexander Kirillov <kirillov math sunysb edu>]

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. 

 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. 

Comments? Volunteers?

Sasha