Opinions sought and an update

[Malcolm Tredinnick <malcolm commsecure com au>]

There are two purposes to this mail: keeping people informed and seeking
advice about a packaging problem.

(1) Things I am working on
---------------------------
I am putting the finishing touches on the first draft of two documents
at the moment. One is a tutorial about how to upgrade the build systems
of GNOME modules to use automake 1.7 and appropriate versions of
autoconf, libtool and friends. Eventually maintainers are going to have
to upgrade all their modules or we are going to be stuck maintaining
automake-1.4 builds for no reason except laziness. This document aims to
provide a step-by-step guide to what is required and possibly encourage
maintainers to tidy things up as they go (the amount of rubbish in some
of the build systems is disappointing). So this document is aimed at
module maintainers (whether they are platform GNOME modules or
third-party developers who have just cut and pasted what they have seen
elsewhere).

The second document is aimed at people trying to build things from CVS
and wondering how it all works. It is an article describing each of the
steps involved from the moment you run "autogen.sh" until "make
install". This has been partially inspired by a bunch of build questions
that I have seen on various lists lately and John Fleck's "I don't want
to be a hacker" Dave Mason impersonation. Maybe we can make the build
process less fearful, so you do not need to have large amounts of
experience to report accurately what went wrong.

James Henstridge has volunteered to review the first document. He may
also be nominated to volunteer to review the second one as well, barring
any more willing candidates. So there is some chance the documents will
be factually correct.

(2) Opinions sought
--------------------
Both of the above documents are destined for the gnome-devel-docs module
in CVS. That module is starting to collect a few useful documents that
are not available anywhere. So I have been fiddling with the build files
and setting it so that we can make a release of the module. Even _if_
those articles eventually get put on the web somewhere, I see some
benefit in also having them available as a tarball. I often grab a few
minutes of hacking time on the train to and from work and having
documents like those sitting on my laptop is useful; on the Internet
they would be inaccessible in those moments.

The problem then becomes: in what format should these documents be
installed? They are distributed as Docbook XML. No problems there.
However, viewing the files in that format is a bit messy. My experience
is that Yelp is not really a wonderful tool for viewing long HTML
documents. Gecko-based browsers (Mozilla, Epiphany, Galeon), although
they understand the xml-stylesheet processing instruction, do not parse
the DTD, so entity substitution from external subsets do not occur.
My documents are littered with standard Docbook entities like —,
“ an ”. I have not played with devhelp enough to know if
it is appropriate or not.

Which leaves the possibility of turning the XML files into HTML or XHTML
and installing that. I quite like this option. the documents are
viewable in any reasonable browser. I can wrap a nice stylesheet around
things, including a print stylesheet so that printing a single page
verison of the document looks nice (modulo the annoying printing bugs
with images in Mozilla-derived browsers). The documents are accessible
(in the sense that they do not suck when viewed in links).

The only downside is a build annoyance where I have to mess around with
the OMF files so that they have the right attributes values in the
format and identifier elements for the installed documents. For the
limited number of documents in gnome-devel-docs at the moment, some sed
magic has taken care of that.

Can anybody think of any other downsides to the approach I am taking?
This has sort of been discussed before, with no real conclusion (see,
for example, a thread that Mathieu Lacage started around January 21 this
year). I am looking for a solution that works _now_, rather than
something that would be nice to have in the future. We are slowly
starting to get a number of documents that are useful for people
developing for GNOME-based platforms (not just those working on GNOME
itself) and not having them available seems a bit silly.

Thoughts?

Malcolm


-- 
How many of you believe in telekinesis? Raise my hand...