Automatic Menu Substitution In Gnome Help Documentation

[Matt Keenan <Matt Keenan Sun COM>]

Hi,

I am investigating into the best solution for automatic menu location substitution
within Gnome Help documentation. Currently all gnome applications have their menu
location hard coded into the xml help documentation they deliver. This is fine for
vanilla gnome, but most distributions will change the menu structure and therefore
the location applications will differ from distro to distro. This causes a real
headache for documentation, as each distro face the dilemma of either :

    I. Using the vanilla documentation even though it points the user to the wrong menu
       location
   II. Branching the documentation locally and make their own menu location changes.


Most cases documentation gets branched, which in my opinion is wrong as it means
other changes made locally never get commited back to the community and they
both then get out of sync very quickly, which is costly for all.

So that's the background, what are the possible solutions.


- How to determine what the menu locations

  We need to determine how the menu locations are to be determined, either by new data
  file or existing files.

  1. Data file containing menu locations of applications, something like
     /usr/share/yelp/toc.xml that is delivered by yelp which defines what categories of
     belong where within the yelp toc structure (which I know is under discussion at the moment)
     This would need to be patched by individual distros, but easier to patch one file
     rather than have to branch all documentation.
  2. Attempt to use ".desktop" files and interpret from them what menu locations are much
     like gnome-panel does when creating the menus in the first place.
  3. Some scrollkeeper data file like scrollkeeper_cl.xml. I know scrollkeeper is required
     by yelp and scrollkeeper-update needs to be run at post-install for apps that deliver
     help, but I don't fully understand why.
  4. Using something from gnome-doc-utils, again I don't know it well enough to make
     suggestions if someone can make a suggestion I would be glad to investigate further.

- Documentation Changes Required

  All current xml documentation would need to be changed so that the menu location
  text contains some reference to new menu ENTITY's and would get substituted in at
  either runtime or compile time. This would be a one time change only and not that
  difficult once the right structure/entity has been determined.

  Or is there some xsl means of achieving this.

- Automatic Substitution

  1. Runtime Solution

     This would involve amending yelp to automatically substitute in the menu locations
     into the xml documentation as it processes them from xml to html at run time.

     Depending on how the menu locations are determined would define what the changes are
     required within yelp if any.

     Could this be done entirely by xslt and stylesheet processing ? as I know yelp has
     it's own set of stylesheets that it uses when converting the xml doc's into html
     before it displays it.

     - If using .desktop files to determine location then code similar to that in gnome-panel
       would need to be placed into yelp.
     - If using a toc.xml type solution then we would just need to read this file.
     - If using scrollkeeper data file what would need to be done ?
     - gnome-doc-utils ?


  2. Compile/Build Time Solution

     As each component builds the menu locations are placed into the xml docs ENTITY's.

     - If using .desktop files then each module would need to know how to parse the
       desktop file to determine what the menu location is.
     - Using toc.xml type data file would require that yelp be built and installed before
       all other apps that deliver help... kind of messy.
     - What would need to be done is using the scrollkeeper solution. This might be nice
       as scrollkeeper is actually built/installed much earlier in the stack.
     - Again gnome-doc-utils is it a possibility ?


I really would appreciate feedback/opinions/pointers... what do people think is this
something the gnome community would see as useful ? I would mean improved co-operation
between all doc writers, and result in better documentation for entire GNOME project.

Cheers

Matt

--
        __.--'\     \.__./     /'--.__
    _.-'       '.__.'    '.__.'       '-._
  .'       Matt Keenan (mattman)          '.
 /       Sun Microsystems Ireland           \
|                                            |
|   E-Mail : Matt Keenan Sun Com             |
|            mattman iol ie                  |
|                                            |
|  Irish Fantasy League Of American Football |
|           http://www.iflaf.com             |
|                                            |
|        Happy Hookers Golf Society          |
|   http://www.iol.ie/~mattman/golf/hhgs.htm |
|                                            |
|   Phone  : +353 1 8199251, Sun Ext : 19251 |
 \         .---.              .---.         /
  '._    .'     '.''.    .''.'     '.    _.'
     '-./            \  /            \.-'
                      ''