Documentation on the web

[Shaun McCance <shaunm wolfram com>]

As some of you know, I've spent the last week putting together a build
system to get all of the GNOME user documentation on the web.  It's not
exactly finished, but it is in a state where I can show it around and
start soliciting help.  You can get a tarball of the build tree at

http://www.gnome.org/~shaunm/dgo-030824-0.tar.gz

You can browse whatever I happen to have built most recently at

http://www.gnome.org/~shaunm/docs.gnome.org

Before extolling on the virtues of this thing, allow me to point out its
problems.  First, the DocBook to HTML transformations are done with the
Yelp stylesheets.  But the Yelp stylesheets insist on importing the 1.48
version of Norm Walsh's stylesheets.  Many people don't have 1.48, so
calling Yelp's stylesheets from outside of Yelp can be painful.

In fact, Yelp keeps its own copy of the 1.48 stylesheets, and its own
XML catalog file.  The situation is kind of hairy, but if you don't wamt
libxslt to pull Norm Walsh's stylesheets from the web for each and every
document you transform, you can do one of three things:

1) Install the 1.48 stylesheets from docbook.sourceforge.net

2) Edit /usr/share/sgml/docbook/yelp/yelp-customization.xsl (up to
isomorphism by different prefixes).  At the top, there's an import
line.  You can change the URL from

http://docbook.sourceforge.net/release/xsl/1.48/html/docbook.xsl

to

http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl

This requires that you have XML catalogs set up properly (as does option
1), and that you have some recent version of Norm Walsh's stylesheets
installed.  I have 1.58, and Yelp works fine with it.

3) Set the environment variable XML_CATALOG_FILES to
/usr/share/yelp/catalog.  Again, change prefix as necessary.

OK.  Now, another thing is that the DocBook transformation in this build
system is done with a stylesheet that imports Yelp's.  But it just
hard-codes the location of yelp-customization.xsl.  So you might need to
edit tools/db2html.xsl in the build directory from the tarball.


Yay.  Now for everything that's right with the system.  It's completely
automated.  You just write simple config files (.page and .docs, and
other types can be plugged in to suit different needs), and pages are
created for you.  The non-documentation HTML pages are created from the
.page files, and they automatically pull their text from all the
necessary locations.  The documentation is built from the .docs files,
and they automatically grab tarballs from ftp.gnome.org, pull what they
need out of them, and transform as necessary.

Also, this whole thing is fully internationalized.  Every config file
that contains text can contain multiple instances of the corresponding
XML element, each with the xml:lang attribute set.  This means that all
of the text in the build directory can be localized with intltool.  I
haven't set up all the intltool stuff yet, but it should be easy.

As for how localized stuff goes on the web, all of the non-docs files
get multiple copies with language extensions.  For instance, there will
be core.html, core.html.de, core.html.es, etc.  Apache automatically
serves the right one up based on your browser's languge setting.

The documentation pages get placed in separate directories for each
language.  The localized non-docs pages that link to the documentation
automatically link to the correct language directory for that language.
If the documentation doesn't exist for that language, it links to the
English documentation, and it notes on the page that the documentation
is untranslated.

I currently have the build system building for the 'de' locale, even
though I don't have any German translations in the config files.  But if
you set your browser language to German, you will see differences, since
titles and descriptions of documentation components are taken directly
from the OMF files.

So if you're interested, take a look.  It needs more documentation
plugged into it, and it needs a good categorization.  The categories
that are up there now were rather arbitrary.  I just wanted to get the
thing working.  And if this thing is to go up, it needs translators.

--
Shaun