Re: Documentation on the web

[John Fleck <jfleck inkstain net>]

Shaun -

This is way cool! Is Jeff going to use it to automagically display our
docs on the GNOME web site?

John

On Sun, 2003-08-24 at 16:47, Shaun McCance wrote:
> 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
> 
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
-- 
John Fleck
jfleck inkstain net (h)
http://www.inkstain.net
http://www.gnome.org/learn/users-guide/latest/

"Become as one with the ball and the pin.
Then return shoes to the counter after use."
 - Zippy the Pinhead