Re: db2html templates for standalone pages rather than yelp

[Shaun McCance <shaunm gnome org>]

On Tue, 2005-11-29 at 20:29 -0500, Peter Williams wrote:
> Hi all,
> 
> I've been looking at the tools that we have right to convert DocBook
> files into HTML for posting online. The db2html.xsl templates in
> gnome-doc-utils seem to be the preferred method, but it looks like their
> output is customized to Yelp and not viewing in a standalone web
> browser:

They're not intentionally done that way.  In fact, the
whole idea of the gnome-doc-utils stylesheets is that
we can use my XSLT efforts outside of Yelp.  If there
are changes that would make the output look better in
a web browser, then we should just make those changes
in the default rendering.  Yelp can always override
what it needs to.

> 	* There's no sidebar with a TOC

Well, we have to consider what we'd want such a thing
to look like.  I don't want to output something made
specifically for the Gnome website, so we have to be
generic enough with this.  And we need to be able to
turn it off with a parameter.

> 	* There's no page header or footer

There's a page footer giving links to the previous
and next pages.  I'm open to suggestions on how best
to render headers and footers outside of Yelp.

> 	* The columns are too wide for comfortable reading in a 
> 	  maximized web browser

Something like this would do the trick:

div[class ~= "body"] { max-width: 600px; }

> Are there templates like the current ones that are tuned for creating
> 'standalone' XHTML pages rather than ones for viewing within Yelp? (If
> not, I might look into writing some: with them, it probably wouldn't be
> too hard to write a tool that just takes a DocBook file and blasts it to
> a website where people can read beautiful docs.)

As I said, changes that make stand-alone XHTML look
better should just go directly into the stylesheets.
There are some other things, like the default look
of admonitions and certain other block objects.

I'd love to wrap the stylesheets up with a script
to make it easier to do transforms on the command
line.  Make command line options out of the really
useful XSLT parameters.  Maybe have a standard way
to install customization layers and an easy way to
load them up with the script.

All of this can and should go into gnome-doc-utils.
I just haven't really done it because I've focused
more on the Yelp side of things.  I want all our
website DocBook builds to use gnome-doc-utils, and
I want them to start looking good.

Patches welcome. :)

// Shaun