Re: Documentation on the web

[Patrick Costello <Patrick Costello Sun COM>]

Hi Sean, 

You are doing some great work in getting GNOME user documentation onto the web. Your approach looks very promising, and looks like a great contribution. Some thoughts, suggestions and questions: 

- I think that this approach is the most useful for the "heavyweight" documentation. The stuff that people like to bookmark and reference from time to time. Or even print out. The GNOME 2.2 Desktop User Guide, the GNOME 2.2 Desktop Accessibility, the GNOME 2.2 System Administration Guide, for example. The fairly long revision cycle for these larger books would suit the library approach. 

- I think that trying to provide a comprehensive library of the individual application online Help manuals could prove to be mission impossible. These manuals are constant works-in-progress, always under revision, and therefore always out-of-date if placed in a library. Users are less likely to want to access the application manuals as works of reference. 

- Does your approach offer a resolution to the permanently out-of-date status of project-support documentation, such as the GNOME Documentation Style Guide and the Human Interface Guidelines? There have been updated revs of both the GDSG and the HIG putback to CVS for some time, but the updates have never made it onto the web. It would be really great if your approach broke that logjam. 

Thanks, 

Pat
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

-- 
*************************************
Patrick Costello, GNOME Documentation
Phone: 		01 819 9077 [ext 19077]
*************************************