How to customize Docbook with stylesheet ? Where do I find good resources?

Question

I have to make some form of documentation of the projects I did , along with screenshots etc , and I'd like to make it less plain , so I tried adding CSS to my file , but it didn't work . After some browsing I found out that XSL or XSLT would be needed for this , which I never used , and couldn't find any good tutorial / documentation / examples.

Answer 1

You have to distinguish different parts of DocBook - authoring and processing (output result).

Authoring

DocBook authoring is quite straigthforward - to get the best result use special GUI XML editors like XMLMind XML Editor or OxygenXML Author instead of plain text editors (I'm not affiliated in any way with XMLMind or Oxygen). Of course, you can ask, why I mentioned the authoring tools instead of customization itself and how these tools are related to customization? The answer is: any XML editor itself can be fully customized in a way, you need it for a productive work. There are mostly nothing related to DocBook XSL Stylesheets there but any editor can be customized to get the most appropriate result for authoring. And many parts of this customization are related to XSLT/XPath.

Processing

This part fully depends on your knowledge of XSLT field and, in the same time, what result you want to get (expect). DocBook stylesheets were designed to get a result (output files) irrespective of your XSLT knowledge BUT the result complexity will be fully depend on the level of your knowledge. Here are a simple list to get know you where you need to go:

1. If you know nothing about XSLT - you get the default result out of box.

2. If you are ready to make a tiny dig into DocBook parameters and tune them - you get the result more suitable for your needs. I.e. you can tune your page font for PDF (body.font.master), choose, what document headings include in TOC (generate.toc), etc. You need only one file to tune: <docbook-xsl-distro-dir>/<output_type>/param.xsl, where docbook-xsl-distro-dir - is your directory with DocBook XSL Stylesheets, <output_type> - type of output result you need to get (fo > print, html > html). To find out what each parameter is suitable for, you can use either DocBook XSL reference or/and (recommended!) the book DocBook XSL: The Complete Guide by Bob Stayton (available online).

3. If you are ready to dig into the depths of a customization - you need to get really complex result for your output. In that case you need:

   • to get know XSLT (DocBook XSL Stylesheets are written in XSLT 1.0). I would recommend XSLT Quickly (from Manning publishing);
   • to read DocBook XSL: The Complete Guide throughly;
   • to get know HTML or XSL:FO (depend on output).