Re: library.gnome.org status

[Shaun McCance <shaunm gnome org>]

On Mon, 2007-04-16 at 14:03 +0200, Frederic Peters wrote:
> Hi Goran, (and gnome-web-list@)
> 
> You are in the same timezone as me, it will make things easier :)
> 
> > - XSLT styles (locators/gtkdoc/gtkdoc.xslt and locators/gdu/gdu.xslt)
> > are not producing markup acording to mockups. Main problem is that there
> > is no navigation sidebar. I also don't know how to include list of
> > languages avaibile as some languages can fail to build (maybe script can
> > try to build all languages first and then reprocess them to include
> > language selector, but that is far from optimal solution)
> 
> As I said in my blog post, my XSLT skills are rusty; also from
> previous experience I don't think it is wise to do everything using
> XSLT.  See next paragraph...

You certainly want to do the bulk of the DocBook processing with
XSLT.  Otherwise, you can't leverage the work that's already been
put into gnome-doc-utils.  Trust me, you do *NOT* want to be in
the business of maintaining your own DocBook tool chain.

If it makes sense to post-process the output from the XSLT, then
let's do that.  That may be necessary if (e.g.) we want some sort
of dynamic content directly in the pages.

> > - There are no index files for browsing documentation by module or GNOME
> > release, and removing old content on upgrade is totaly broken. There are
> > small XML chunks (index.LANG.xml) in output that include informations
> > like localized document title and abstract. My plan was to parse them
> > after building is done and regenerate index pages. Index pages should be
> > localized, and generated for each language avaibile.
> 
> I agree on the goal, it would also be possible to parse omf files to
> get that information.  I would prefer to to this step, "decorating"
> the raw xhtml files, with straight Python (+ a template language, I
> have not been following that closely, genshi or kid come to mind).
> In a second phase this generation could be moved to a web application
> to support things like annotations...
> 
> /module/version/ -> generate list of languages + table of contents
> /module/         -> generate list of versions
> /                -> generate list of modules (and separate help from
>                     API reference)
> 
> Is this easy for you to copy the .omf files in /module/version/ ?

Given that everything useful in the OMF files is actually
generated from the DocBook by gnome-doc-utils, I don't think
that working from the OMF files gains us anything.  We can
also expose some gnome-doc-utils interfaces if necessary.

--
Shaun