Re: [xslt] Re: [xml] Improvement of the on-line documentation

[Daniel Veillard <veillard redhat com>]

  Switching to the gnome doc list, where this looks more appropriate.
  To give a bit of context, this is about the new API indexes showing up
  at http://gnome.org/

On Thu, Jan 24, 2002 at 08:06:06PM -0700, John Fleck wrote:
> On Thu, Jan 24, 2002 at 09:29:43AM -0500, Daniel Veillard wrote:
> >   As some of you may already have noticed, the web site format now
> > includes a new section called "API Indexes". It includes a new set
> > of index pages for the existing documentation which were seriously
> > missing naviagtion and indexing. The Alphabetic entry is a general
> > keyword index, Constructors provides pointer to functions returning
> > a given type, Function/Type points to a usually larger set of function
> > taking a given type as its argument, Module is an index of the
> > symbols per modules and Symbols is an alphabetically sorted index of
> > all the library symbols.
> > 
> >   In the hope this is useful and will decrease the number of questions
> > left unanswered due to navigation and location problems in the
> > documentation.
> > 
> > Daniel
> > 
> > P.S.: the index construction is automated based on the existing gtk-doc
> >       extraction tool, some python code to generate an XML description
> >       and an XSLT module to integrate with the web site.
> > 
> 
> Daniel -
> 
> This is terrific. Can this be generalized for use with other packages
> that use gtk-doc?

  The extraction part of it, yes, it then generate XML descriptions
of the API with comments and another XML file containing cross references.

  The problem is that the extraction code is ugly. It scans the .txt
genrated files first to build the API information and then scans the
SGML (actually  a slightly tweaked version of them) to add comments to
all the definitions. This mean it has to scan the DocBook generated
descriptions to extract the comments, and this truely sucks. The proper way
would be to get gtk-doc to dump directly as a generic XML API description
not a DocBook documentation orient view of those informations. I would
have done it if I had the sligtest idea of how to write Perl, and the more
I look at perl code the strongest my headache becomes, sorry can't do.
It was easier for me to write python code extracting the informations
from the postprocessed SGML.

  I don't know if the gtk-doc authors are ready to provide this
XML dumping of the description. If this was the case then I would certainly
be able to write a truly generic tool to extract indesces and possibly
XSLT stylesheets for them

Daniel

-- 
Daniel Veillard      | Red Hat Network https://rhn.redhat.com/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/