4. More DocBook specific things

The dreaded “Smart Quotes
Section numbering, main Table of Contents, section Table of Contents
Questions & Answers
Adding headers and footers to HTML output

The dreaded “Smart Quotes

It appears that the dust has settled on this. For a long time, it was common to see inverted question marks or weird dice-face looking things in place of proper double and single quotes. To elaborate a bit, the regular ASCII charcter set, or nationalised variants such as ISO-8859-1 don't actually define left and right quotes. In some contexts the ` character has been abused as a left-quote, and, indeed in the 1990s this actually looked good on many browsers.

However, these days the position of ` and ' has been clarified, and the font people have listened. The ` is now “GRAVE ACCENT” in Unicode-speak, and ' is “ACUTE ACCENT”, and look accordingly. For stunning detail on this issue, see here.

For our purposes it is enough to know to never use `. It is permissible, and easy, to use ' to quote strings. However, the royal way of quoting strings in DocBook is to use <quote>. For example, <quote>quoted</quote> ends up like this: “quoted”.

For comparison: regular double quotes "quoted", abusing the GRAVE ACCENT `quoted', using regular single quotes (aka ACUTE ACCENT) 'quoted', the royal way: “A quoted ‘quote’ looks like this”.


Ok, these rarely used and truly spice up your output so it won't look DocBookish anymore. To make things pretty, we need to edit our config.xsl a bit. Watch the numbers:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  <!-- Use ids for filenames -->
  <xsl:param name="use.id.as.filename" select="'1'"/>
  <!-- Turn on admonition graphics. -->
  <xsl:param name="admon.graphics" select="'1'"/>
  <xsl:param name="admon.graphics.path"></xsl:param>
  <!-- Configure the stylesheet to use -->
  <xsl:param name="html.stylesheet" select="'docbook.css'"/>

<xsl:param name="chunk.section.depth" select="0"></xsl:param>
<xsl:param name="callout.graphics" select="'1'"></xsl:param> 1
<xsl:param name="callout.graphics.path"></xsl:param> 2



This turns on graphical callout numbers


This configures the callouts graphics to be in the same directory as the html

Sure looks pretty! You need to copy the number graphics over from the same place where you found warn.jpg etc, the files are called 1.png and onwards.

The syntax is not too hard, add <co id="something"/> (note the closing /!) to your <screen> or <programlisting> and add a <calloutlist> below, like this:

  <callout arearefs="graphics">
    This turns on graphical callout numbers 

There is also a “hidden” syntax for if you don't want to insert things in the text you refer to, perhaps because it is auto-generated. I haven't been able to get this to work though.

Section numbering, main Table of Contents, section Table of Contents

DocBook knows several document types, like book and article. Each of these comes with certain preset defaults which specify if sections are numbered, if the Table of Contents is repeated for each section etc.

You might want to change these settings individually, which is possible by adding the following to the XSL configuration:

<xsl:param name="generate.section.toc.level" select="1"></xsl:param>
<xsl:param name="section.autolabel" select="1"></xsl:param>
<xsl:param name="section.autolabel.max.depth" select="1"></xsl:param>

In order this enables the output of a section level ToC, turns on the enumeration (numbering) of sections, but limits that numbering to the first nesting level - ie, sections within sections don't get additional numbers.

Questions & Answers

1. How can I add a spiffy Questions & Answers section?
2. How does a Qandaset work?
3. Can you show some code?

How can I add a spiffy “Questions & Answers” section?

By using a Qandaset!


How does a Qandaset work?

As you would expect it to - with the minor exception that it can only live outside of a <para>


Can you show some code?

   <qandaentry><question><para>How can I add a spiffy <quote>Questions & Answers</quote> section?</para></question>
   <answer><para>By using a Qandaset!</para></answer>

Adding headers and footers to HTML output

In the HTML headers section of “DocBook XSL: The Complete Guide” we read that we can use the following to do this:

<xsl:template name="user.footer.content">
  <P class="copyright">© 2002  Megacorp, Inc.</P>

However, things are not as easy as they appear. For some reason or other, part of the toolchain decides that it needs to mess with lower case tags you insert here. The easy solution is to upper case all these, as is done above. A lot of HTML also works in lower case but specifically javascript breaks. This for all you Google AdSense users out there :-)