Re: generating standalone html with gnome xsl stylesheets (gtkmm)

[Peter Williams <peter newton cx>]

On Thu, 2005-12-29 at 13:51 -0600, Shaun McCance wrote:
> I think the TOC sidebar can be generated using the existing
> autotoc templates.  A little CSS and a few parameters can go
> a long way in generalizing the output.  As far as speed goes,
> there are some nice tricks that can make this sort of thing
> really fly, but I'll have to dig into it more.

I was a little reticent to write my own TOC templates, but they're not
very long so I don't feel too bad about it in the end. The main
difference is in the chunking behavior: you want a list of the other
chunks, but also the sections within the current chunk. I think this
would be hard to do with the autotoc.

(Although maybe it would make more sense to have two sidebar TOCs: one
showing the elements within the current chunk, and one showing the
overall structure.)

Anyway, if you have the time to look into speeding things up, that'd be
great, but it's not your responsibility.

> The only thing I'm not convinced of is that these need to
> be separate stylesheets.  I think most of this stuff can
> really be merged directly into the db2html stylesheets.
> The default output of those should be suitable for display
> on the web.  Yelp can set parameters and do customizations
> as much as needed.

I still like my approach:

	* It feels more natural to me that the basic stylesheets just do
straightforward formatting, and then a higher-level layer adds on the
polish and optional stuff to make things prettier. This makes more sense
(to me) than having one complicated stylesheet that includes all the
pretty formatting but can have it disabled via a collection of
parameters. I visualize the setup as a class inheritance graph:

	db2html.xsl -> class DB2HtmlBasic
	db2htmlweb.xsl -> class DB2HtmlWeb : DB2HtmlBasic

	* I think separate stylesheets would be a lot easier to use: instead of
having to remember to set parameters X, Y, and Z to special values, you
just have to remember to use the web stylesheets.

	* IMHO the patch shows that layering on top of the basic stylesheets is
a pretty painless procedure. I think it's actually simpler than
equivalent XSL code that implements the same features controlled by
parameters.

> Combine this all with your gnome-doc-process script and
> we've got a powerful but simple DocBook toolchain.  And
> fast.  Let's not forget fast.  I love fast.

I don't know about you, but I remember trying to generate docs from SGML
using Jade. Packages all had autoconf switches to enable building docs
because it pretty much never worked right. Life is good these days.

Peter

-- 
Peter Williams / peter newton cx