Re: gnome-doc-process script

[Shaun McCance <shaunm gnome org>]

On Tue, 2005-12-20 at 17:16 -0500, Peter Williams wrote:
> Hi,
> 
> Attached is a patch that adds a new script called gnome-doc-process to
> gnome-doc-utils. The idea is to provide a wrapper around xsltproc that's
> slightly easier to use for common operations. It'll guess default values
> for a lot of the XSL template parameters and make sure that you specify
> the ones that can't be guessed. For instance, to make HTML out of a
> sample docbook file, I just do:
> 
> gnome-doc-process -m html -t top.xhtml ../press_release/docbook/C/press_release.xml 
> 
> in the simplest case. This automatically dumps the output into
> press_release/C/, with the toplevel output into
> press_release/C/top.xhtml. There's also a cute feature where if you pass
> a "--lang ja" option, it'll do the same processing with /C/ replaces
> with /ja/ in the input and output. Hopefully this will make it easy to
> automate doc generation in makefiles.
> 
> I also have sketchy support for an OMF mode that will use the db2omf
> template. My hope is to use develop specialized XSL templates for
> generating web-friendly HTML and then add another mode to use those
> templates: "-m htmlweb" or something like that.
> 
> Comments? This is obviously not perfect, but I think it's a good
> starting point for some kind of tool that will make everyone's life
> easier.

I'm not going to have a chance to play with this until after
Christmas, but this is really cool.  My intention was always
to have a script like this in gnome-doc-utils.  I just never
got around to doing it yet.  A few comments:

I'm not so sure about the language substitution thing.  It
just feels very un-unixy to give it an input file but have
it operate on another file.

We probably want some way to pass arbitrary XSLT parameters.
Otherwise, people will end up eschewing the script in favor
of xsltproc whenever they need some parameter.  Perhaps just
have --param and --stringparam arguments as well?

There are a couple of parameters that will probably be used
quite a lot, so we should provide direct arguments for them.
For instance, the path to admonition graphics is going to
vary for different people's HTML builds.  People might want
to control the chunk depth as well, although I think they
should just use the (undocumented) processing instruction.

Anyway, great stuff.  Don't let my hectic holiday schedule
keep you from hacking.  You might even consider converting
gnome-doc-utils.make to use gnome-doc-process.  Bear in mind
that gnome-doc-utils itself does have to bootstrap off its
local copy of itself to build itself.  So you'd basically
have to do what it already does for xml2po.

--
Shaun