Re: Opinions sought and an update

[John Fleck <jfleck inkstain net>]

On Thu, 2003-05-08 at 20:47, Malcolm Tredinnick wrote:
> 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
[snip]
> 
> The second document is aimed at people trying to build things from CVS
> and wondering how it all works. 

This is completely excellent. I'd love to read them, since my "I don't
want to be a hacker" personna is a reasonable target audience.

> (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.
> 

I think HTML is reasonable. Remembers that's how gtk-doc docs are
installed, so we've lived with that format for developer docs of this
sort for a while.

Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com
http://www.gnome.org/learn/users-guide/latest/

"Not only isn't reality real - it's an illusion created by unreal people to
sell real people unnecesary cars." - Griffy