Re: Proposal: XSL Stylesheets

[Gregory Leblanc <gleblanc linuxweasel com>]

So, nobody else has replied to this yet, and I said I would, so here I
am.  Hey, it's only been a bit more than a month...

On Thu, 2001-10-25 at 14:55, Eric Baudais wrote:
> Date: 31 Dec 1969 23:59:59 +0000
> 
> In GNOME 1.4 the GDP has used their own DTD or DocBook and DSSSL stylesheets 
> for the DocBook SGML docs.  In GNOME 2.0 we are going to use DocBook XML and 
> therefore need some new stylesheets and a new way of constructing them.
> 
> Traditionally the DSSSL stylesheet has been an all-inclusive stylesheet 
> covering print as well as HTML.  This has worked fine since few knew how to 
> modify them and they have rarely needed to be changed.  With the advent of 
> the switch to XML the XSL stylesheets make changing how the documentation is 
> displayed easier.  Also a greater number of people know how to write and 
> modify XSL.

I don't see that we'll want to be changing the stylesheets very
frequently.  These are the essence of how our GNOME documentation
branding works, and we'll want to come up with a consistent look and
feel that we stick with, at least until GNOME 2.2.

> Proposal:
> 
> Since a greater number of people know how to write and modify the stylesheets 
> we need a better way to construct a stylesheet.  The stylesheets should be 
> modularized into multiple files.  Each file should be named after the top 
> level tag the templates in the stylesheet modify.
> 
> Ex: 
> 
> <!-- Custom template to make the term tag bold.-->
> <xsl:template match="variablelist//term">
>   <xsl:call-template name="inline.boldseq"/>
> </xsl:template>
> 
> </xsl:stylesheet>
> 
> The above example should be placed in the file called "variablelist.xsl" since 
> it matches to the variablelist tag.
> 
> A file should not depend on another or be in conflict to another.  All the 
> customizations should take place inside the file and not modify the behavior 
> of the customization, but modify the behavior of the base stylesheet.
> 
> The base stylesheet will be the most recent stable version Norman Walsh's 
> docbook-xsl stylesheets found at: http://www.sourceforge.net/projects/docbook/

I don't think there is any reason to do this.  I can see a number of
places that this strategy could hinder us.  If we allow authors to
choose which customizations they're using, it could lead to a very
un-unified appearance to our docs.  Making things seem cohesive is hard
enough with many varied authors, let alone with variable stylesheets. 
If authors have to pick and choose between stylesheets, they'll be a lot
more tempted to play with them, and perhaps change their markup to see
what the appearance is.  I do see that perhaps this could lead some
authors to add their own stylesheet tweaks, instead of messing with
their DocBook markup.  However, if they do this, it will just compound
the first problem, as we won't even have a controlled set of stylesheet
tweaks that people are using.
So, in short, I don't really think it's a good idea to break things up
into micro-stylesheets.  Instead, we should decide on how the
stylesheets render things, and have a single good stylesheet that we
use.  At the moment, I think all of our customizations will be to the
XSLT stuff, and we'll have to wait on XSLFO, until we've got less time
constraints to get a good set of stylesheets made for online
documentation.
	Greg