Home/ Questions/Q 8646093
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-12T12:42:52+00:00

I’m trying to customize DocBook XSL’s HTML output. <section> level X generates heading level

  • 0

I’m trying to customize DocBook XSL’s HTML output.

<section> level X generates heading level X + 1.

e.g. <sect1> -> <h2> but I work with <section> tags, not <sectX>. I understand why it happens but I would like to change this behavior so that section of a given level generates the same level heading. I tried studying the titlepage templates, but they don’t really make sense to me and I can’t find the actual code that generates the <hX> tags.

As an example, I have a docbook document that looks something like this:

<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
[other namespace definitions]
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://docbook.org/ns/docbook docbook.xsd" version="5.0">
  <info>
    <title>Document Title</title>
    <orgname>Company</orgname>
  </info>
  <section>
    <title>INTRODUCTION</title>
    <section>
      <title>Overview</title>
      <para>This document defines [...]</para>
    </section>
    <section>
      <title>More Information</title>
      <para>[...]</para>
    </section>
    <section>
      <title>Aim</title>
      <para>This Document will be used to [...]</para>
      <table>
        [irrelevant table code]
      </table>
    </section>
    <section>
      <title>Related Documents</title>
      <para>[...]</para>
    </section>
  </section>
  <section>
    <title>ANOTHER SECTION</title>
    <para>This section provides [...]</para>
  </section>
</article>

This generates the following HTML code:

  <html>
  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <title>Document Title</title>
  <meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1">
  <link rel="stylesheet" href="style.css" type="text/css">
  <link rel="stylesheet" href="print.css" type="text/css" media="print">
  <!--[if IE]>
          <link type="text/css" rel="stylesheet" href="ie.css">
          <![endif]-->
  </head>
  <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  <div class="article" title="Document Title">
    <div class="titlepage">
      <div>
        <div>
          <h1 class="title"><a name="d0e1"></a>Document Title</h1>
        </div>
      </div>
      <hr>
    </div>
    <div class="toc">
      <p>
        <b>Table of Contents</b>
      </p>
      <dl>
        <dt><span class="section"><a href="#d0e7">INTRODUCTION</a></span></dt>
        <dd>
        <dl>
          <dt><span class="section"><a href="#d0e10">Overview</a></span></dt>
          <dt><span class="section"><a href="#d0e15">More Information</a></span></dt>
          <dt><span class="section"><a href="#d0e20">Aim</a></span></dt>
          <dt><span class="section"><a href="#d0e48">Related Documents</a></span></dt>
        </dl>
        </dd>
        <dt><span class="section"><a href="#d0e53">ANOTHER SECTION</a></span></dt>
      </dl>
    </div>
    <div class="section" title="INTRODUCTION">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a name="d0e7"></a>INTRODUCTION</h2>
          </div>
        </div>
      </div>
      <div class="section" title="Overview">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a name="d0e10"></a>Overview</h3>
            </div>
          </div>
        </div>
        <p>
          This document defines [...]
        </p>
      </div>
      <div class="section" title="More Information">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a name="d0e15"></a>More Information</h3>
            </div>
          </div>
        </div>
        <p>
          [...]
        </p>
      </div>
      <div class="section" title="Aim">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a name="d0e20"></a>Aim</h3>
            </div>
          </div>
        </div>
        <p>
          This Document will be used to [...]
        </p>
        <div class="table">
          [irrelevant table code]
        </div>
        <br class="table-break">
      </div>
      <div class="section" title="Related Documents">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a name="d0e48"></a>Related Documents</h3>
            </div>
          </div>
        </div>
        <p>
          [...]
        </p>
      </div>
    </div>
    <div class="section" title="ANOTHER SECTION">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a name="d0e53"></a>ANOTHER SECTION</h2>
          </div>
        </div>
      </div>
      <p>
        This section provides [...]
      </p>
    </div>
  </div>
  </body>
  </html>

Thanks!

~Slampisko

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    Create a customization of the template named “section.heading” in sections.xsl. Below is an excerpt from that template. You only need to change $level + 1 to $level.

    <!-- HTML H level is one higher than section level -->
<xsl:variable name="hlevel">
  <xsl:choose>
    <!-- highest valid HTML H level is H6; so anything nested deeper
         than 5 levels down just becomes H6 -->
    <xsl:when test="$level &gt; 5">6</xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="$level + 1"/>   
    </xsl:otherwise>
  </xsl:choose>
</xsl:variable>
<xsl:element name="h{$hlevel}">
  <xsl:attribute name="class"><xsl:value-of select="$class"/></xsl:attribute>
  <xsl:if test="$css.decoration != '0'">
    <xsl:if test="$hlevel&lt;3">
      <xsl:attribute name="style">clear: both</xsl:attribute>
    </xsl:if>
  </xsl:if>
  <xsl:if test="$allow-anchors != 0 and $generate.id.attributes = 0">
    <xsl:call-template name="anchor">
      <xsl:with-param name="node" select="$section"/>
      <xsl:with-param name="conditional" select="0"/>
    </xsl:call-template>
  </xsl:if>
  <xsl:if test="$generate.id.attributes != 0 and not(local-name(.) = 'appendix')">
    <xsl:attribute name="id"><xsl:value-of select="$id"/></xsl:attribute>
  </xsl:if>
  <xsl:copy-of select="$title"/>
</xsl:element>
    • 0