oXygen XML Editor

Docbook Stylsheet Customisation

1. Depth of section numbering
2. Parameters to xsl stylesheets
3. tips and warnings
4. Toc depth, how to change it
5. Figures and Tables in Toc.
6. Changing chapter headings
7. How to customise localised text
8. Numbering format
9. bg color on programlisting
10. Decorating titles
11. Using locale specific content

1.

Depth of section numbering

Bob Stayton



>I want to limit the section numbering - let me say - to depth 4 in 
> HTML output. Is there an easy way to do this?

> But unfortunately the deeper sections are still numbered with the number 
> of the last numbered section, e.g.:

> 1.2.2.1. Counters
> ...
> 1.2.2.1.. \addtocounter

> What I want is no number at all for the deeper sections.

Actually, you can do it with just parameters and the gentext templates. These lines in your stylesheet customization file will do what I think you want, assuming you want to omit the unnumbered section titles from the TOC.


<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="toc.section.depth" select="2"/>
<xsl:param name="section.label.includes.component.label" select="1"/>

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
    <l:context name="title-numbered">
      <l:template name="sect3" text="%t"/>
      <l:template name="sect4" text="%t"/>
      <l:template name="sect5" text="%t"/>
    </l:context>

    <l:context name="section-xref-numbered">
      <l:template name="sect3" 
	  text="the section called &#8220;%t&#8221;"/>
      <l:template name="sect4" 
	  text="the section called &#8220;%t&#8221;"/>
      <l:template name="sect5" 
	  text="the section called &#8220;%t&#8221;"/>
    </l:context>

  </l:l10n>
</l:i18n>

The first parameter turns on section numbering, and the second one limits the TOC list to sect2 at the most. The third parameter adds the chapter number to the numbering (the usual for multiple chapter numbering).

The <l:i18n> stuff customizes the gentext templates, in this case for English. You'll have to do something for other languages if you use them. It redefines how the section titles and cross references are generated for sect3 through sect5 when in the 'sections being numbered' context. In this case, although sections are being numbered, you want these section levels to just display %t (title) and not %n (number).

2.

Parameters to xsl stylesheets

Bob Stayton



>  In my driver file, which variable will I need to
> set
> - to change the default paper format (to A4)?

Set 'paper.type' to A4.

> - to set widow/orphan values?
> - to prevent a header from appearing at the bottom of a page?

No parameters for these yet.


> - to adjust vertical spacing between listitems?

The 'list.item.spacing' parameter does that, but it is not a single value. It is an attribute set. See sourceforge.net for an example.

There is also 'compact.list.item.spacing' for spacing="compact" lists, and 'list.block.spacing' to specify space between whole lists.

I keep this fo reference page bookmarked: sourceforge.net For awhile it was out of date, but I believe it is now being kept up to date with the stylesheet releases.

3.

tips and warnings

Dan York




> I am working with admonitions, specifically 
> <tip> and <warning
> and would like to include a graphic.

> I have tried using 
> <tip graphic="tip.gif">Tie your shoe laces...</tip> but
> cannot seem to output the graphic in html (I'm using chunk.xsl).

You do not need to do anything in your DocBook code... just make sure that you are enabling the admonition graphics in the XSL stylesheets. In your customization layer, you will need to set the parameters:

  
<!-- Should graphics be used for admonitions (notes, warnings)? 0 or 1 -->
  <xsl:param name="admon.graphics" select="1"/>

  <!-- If 1 above, what is path to graphics? Make sure it ends in "/" and
       make sure that it is all on one line. -->
  <xsl:param name="admon.graphics.path">images/</xsl:param>

  <!-- Again, if 1 above, what is the filename extension for admon
       graphics? -->
  <xsl:param name="admon.graphics.extension" select="'.gif'"/>
  

On this latter one, Norm's default is to use the PNG graphics. (Note that these comments are ones that I include in my customization layer.)

If you do not have a customization layer, you need one. See some of the pointers on docbook.org I also have a page with links to my customization layer at my site

Next you need to copy the graphics you want to use to the subdirectory mentioned in the parameters (and relative to where your document is). Then just generate the files. It works great. You can see them in our online manual which contains 2 Warnings and a Note. This page was generated with the XSL stylesheets.

4.

Toc depth, how to change it

Bob Stayton


> I am using DocBook 4.1.2. with Xalan and the DocBook XSL.

> I want to be able to increase my table of content levels on the chapter
> pages in my book but not on my main ToC. Does anyone know if this is
> possible.

I presume you mean for HTML output, in which case it does not appear to be possible by changing a parameter. Both the book TOC and the chapter TOC use the same global parameter 'toc.section.depth'. You'd have to create a customization layer that defined a new parameter and a modified TOC-generating template to use it. The TOC machinery is not simple, however. This would make a fine feature request, though. 8^)

5.

Figures and Tables in Toc.

Bob Stayton


> I am  attempting to have my figures and tables included in the ToC. I
> have tried <xsl:param name="titles" select="'figure'"/> in my customization
> layer but I'm still having no joy.

It seems that these are supported in the fo stylesheets for PDF output, but not in the html stylesheets. If you look in the fo/param.xsl file, you'll see these parameters:

<xsl:param name="generate.division.figure.lot" select="1" />  
<xsl:param name="generate.division.example.lot" select="1" /> 
<xsl:param name="generate.division.equation.lot" select="1" />
<xsl:param name="generate.division.table.lot" select="1" />

But these are not in html/param.xsl, nor do they appear in the html templates.

6.

Changing chapter headings

Bob Stayton


> 1.  I want to remove the word "Chapter" from each Chapter and replace it
> with something else (eg; instead of "Chapter 1" I would like "Topic 1").
> I have searched for where the word is inserted in the xsl sheets but
> can't find it anywhere. Is this hardcoded?

No, it is internationalized. 8^) The generated text is in the common/en.xml and other language files.

Put something like this in your XSL customization file:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0";>
  <l:l10n language="de">
    <l:gentext key="nav-next" text="N&auml;chste Seite"/>
    <!-- other customizations here -->
  </l:l10n>
</l:i18n>

Note that the language files now use the l: namespace.

The trick here is the select="document('') attribute. This special syntax reads the current document (the stylesheet file) into the 'local.l10n.xml' variable. When the stylesheet goes to generate text, the stylesheet first scans that variable for a match before going to the standard language files. The use of the namespace prevents accidentally picking up any literal result elements that might be lurking in the stylesheet (unlikely, but possible).

7.

How to customise localised text

Bob Stayton


> I was wondering if there is a nice way to change some of the
> entries in the localized text messages defined in the common
> directory.

> For example I want to change the entry

> <gentext key="nav-next" text="Vor"/>

> to

> <gentext key="nav-next" text="N&auml;chste Seite"/>

> in the de.xml file. But on the head of each xml file
> you can see this message

> <!-- This file is generated automatically. -->
> <!-- Do not edit this file by hand! -->
> <!-- See http://docbook.sourceforge.net/ -->

> Actually I don't want to change every entry in the file
> only a few of them. The new entries should overwrite the
> old ones defined in the standard files. Is there any good way=20
> to this customization and beeing updateable through next=20
> releases of the stylesheets?

Yes, there is. Norm has provided a customization feature to that. Put something like this in your XSL customization file:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0";>
  <l:l10n language="de">
    <l:gentext key="nav-next" text="N&auml;chste Seite"/>
    <!-- other customizations here -->
  </l:l10n>
</l:i18n>

Note that the language files now use the l: namespace.

The trick here is the select="document('') attribute. This special syntax reads the current document (the stylesheet file) into the 'local.l10n.xml' variable. When the stylesheet goes to generate text, the stylesheet first scans that variable for a match before going to the standard language files. The use of the namespace prevents accidentally picking up any literal result elements that might be lurking in the stylesheet (unlikely, but possible).

8.

Numbering format

Bob Stayton



> has anyone an idea how to change the headers of sections, chapters etc from

> 1.
> 2.
> 2.1.
> 2.2.
> 2.3.
> 2.3.1.
> 2.3.2.
> 3.

> to 

> 1
> 2
> 2.1
> 2.2
> 2.3
> 2.3.1
> 2.3.2
> 3

> by removing the dot?

The dots are part of the generated text strings defined in common/en.xml (or whatever lang you use) in the stylesheet distribution. In that file, the <l:context name="title-numbered"> element has entries like this:


<l:template name="chapter" text="Chapter&#160;%n.&#160;%t"/>
                                                ^
                                                ^

The %n is the number, and &#160; is non-breaking space. You can customize these strings in a customization layer as described in this doc: sagehill

That extra dot in the TOC is a stylesheet parameter.

<xsl:param name="autotoc.label.separator" select="'. '"/>

Set that to just a space.

9.

bg color on programlisting

Bob Stayton


> I want to customize the programlisting with a
> background color.

The attribute set shade.verbatim.properties can be customized to apply the properties you need. You shouldn't need to customize the template code to change the color.

Try this in your fo customization layer:

<xsl:attribute-set name="shade.verbatim.properties">
   border-color="thin black ridge"
   background-color="silver"
</xsl:attribute-set>

Attribute sets are merged, so these values should override the default background color and add the border color.

See this reference for more information on customizing attribute sets: sagehill

10.

Decorating titles

Bob Stayton



> For Chapter Titles, Section Titles, and Part Titles I need to be able to add a 
> horizontal rule across the page either above the title, below, or both. Any 
> suggestions for how to modify the XSL titlepage template to make this happen? 
> (Or anywhere else where the XSL attribute templates can be customised to do 
> this).

> (Using Saxon/FOP).

You can do this without modifying templates because there is an attribute-set for section titles that you can customize. For example, a rule below would be done with the following in a customization layer:

<xsl:attribute-set name="section.title.properties">
  <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
</xsl:attribute-set>

See this doc for more info on using such attribute-sets: Bobs pages

You'll also need an XSL-FO reference to know what all the possible properties are.

11.

Using locale specific content

Bob Stayton

The common/fr.xml file included with the 1.62.0 distribution is indeed generated from the gentext/locale/fr.xml file in CVS. The generator stylesheet now fills in any missing items in a given translation with English so at least nothing breaks in runtime because of a missing string.

You should use the distributed fr.xml file as a guide to what needs translation. Any item with a lang="en" was inserted during the build to backfill missing items. It is possible that other items in the source fr.xml file are also untranslated, but the generator cannot detect those.

You don't have CVS checkin authorization, so just send an updated file directly to me (not the list because attachments are stripped off) and I will incorporate the changes. You can edit the distributed file or a copy of the CVS file, I can handle either one.

I'll add a README to the locale directory to explain this process.