5.3. Creating Permalinks

5.3. Creating Permalinks
Prev	Chapter 5. (X)HTML Customizations	Next

Difficulty: ★☆☆ (easy)

Keywords: permalinks, ¶, component.title

Problem

You need for every appendix, chapter, section, etc. a small hint (often depicted as “¶”) which points to the division itself. This “permalink” simplies the retrieval and indentification of such a division.

Solution

You need an ID attribute on your division (chapter, section, examples, etc.) to make it work. The permalinks.xsl stylesheet is a named template which expects an id parameter.

Example 5.1. Permalink Stylesheet (permalinks.xsl)

Download File 'permalinks/permalinks.xsl'

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" 
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:param name="generate.permalink" select="1"/>
  <xsl:param name="permalink.text">¶</xsl:param>

  <xsl:template name="permalink">
    <xsl:param name="node" select="."/>

    <xsl:if test="$generate.permalink != '0'">
      <span class="permalink">
        <a alt="Permalink" title="Permalink">
          <xsl:attribute name="href">
            <xsl:call-template name="href.target">
              <xsl:with-param name="object"  select="$node"/>
            </xsl:call-template>
          </xsl:attribute>
          <xsl:copy-of select="$permalink.text"/>
        </a>
      </span>
    </xsl:if>
  </xsl:template>
</xsl:stylesheet>

	Contains parameter `generate.permalink` to switch on or off permalink creation.
	Contains parameter `permalink.text` which is inserted as the permalink text.
	Creates a `span` element as a wrapper element which contains all information about the permalink.
	Creates an HTML `a` element. The pointer in the `href` attribute is used from the `id` parameter.
	Creates a `href` attribute with the correct link, regardless if it points to a chunked file or not.

This is of course not enough. Use the following steps to include it into your customization layers:

Create a customization layer as shown in Section 2.3, “Writing Customization Layers”.

Include the stylesheet from Example 5.1, “Permalink Stylesheet (permalinks.xsl)” into your customization layer:

<xsl:stylesheet version="1.0"
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <!-- ... -->
  <xsl:include href="permalinks.xsl"/>
  <!-- Add here more xsl:include's of the following files -->
</xsl:stylesheet>

Add xsl:include tags to your customization layer with points to one or all of the following files to include permalinks in their respective elements.

For appendices, chapters, prefaces, etc. use the component.title template (originates from {xhtml,xhtml-1_1,html}/component.xsl):

Download File 'permalinks/component.title.xsl'

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml"
  exclude-result-prefixes="d">
  
  <xsl:template name="component.title">
    <xsl:param name="node" select="."/>
    
    <xsl:variable name="level">
      <xsl:choose>
        <xsl:when test="ancestor::d:section">
          <xsl:value-of select="count(ancestor::d:section)+1"/>
        </xsl:when>
        <xsl:when test="ancestor::d:sect5">6</xsl:when>
        <xsl:when test="ancestor::d:sect4">5</xsl:when>
        <xsl:when test="ancestor::d:sect3">4</xsl:when>
        <xsl:when test="ancestor::d:sect2">3</xsl:when>
        <xsl:when test="ancestor::d:sect1">2</xsl:when>
        <xsl:otherwise>1</xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <xsl:element name="h{$level+1}" namespace="http://www.w3.org/1999/xhtml">
      <xsl:attribute name="class">title</xsl:attribute>
      <xsl:if test="$generate.id.attributes = 0">
        <xsl:call-template name="anchor">
          <xsl:with-param name="node" select="$node"/>
          <xsl:with-param name="conditional" select="0"/>
        </xsl:call-template>
      </xsl:if>
      <xsl:apply-templates select="$node" mode="object.title.markup">
        <xsl:with-param name="allow-anchors" select="1"/>
      </xsl:apply-templates>
      <xsl:call-template name="permalink">
        <xsl:with-param name="node" select="$node"/>
      </xsl:call-template>
    </xsl:element>
  </xsl:template>
</xsl:stylesheet>

For figures, examples, procedures, tables, etc. use the formal.object.heading template (originates from {xhtml,xhtml-1_1,html}/formal.xsl):

Download File 'permalinks/formal.object.heading.xsl'

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml"
  exclude-result-prefixes="d">
  
  <xsl:template name="formal.object.heading">
    <xsl:param name="object" select="."/>
    <xsl:param name="title">
      <xsl:apply-templates select="$object" mode="object.title.markup">
        <xsl:with-param name="allow-anchors" select="1"/>
      </xsl:apply-templates>
    </xsl:param>
    <p class="title">
      <b><xsl:copy-of select="$title"/></b>
      <xsl:call-template name="permalink">
        <xsl:with-param name="node" select="$object"/>
      </xsl:call-template>
    </p>
  </xsl:template>
</xsl:stylesheet>

For parts, use the division.title template (originates from {xhtml,xhtml-1_1,html}/division.xsl):

Download File 'permalinks/division.title.xsl'

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml"
  exclude-result-prefixes="d">
  
  <xsl:template name="division.title">
    <xsl:param name="node" select="."/>
    
    <h1>
      <xsl:attribute name="class">title</xsl:attribute>
      <xsl:call-template name="anchor">
        <xsl:with-param name="node" select="$node"/>
        <xsl:with-param name="conditional" select="0"/>
      </xsl:call-template>
      <xsl:apply-templates select="$node" mode="object.title.markup">
        <xsl:with-param name="allow-anchors" select="1"/>
      </xsl:apply-templates>
      <xsl:call-template name="permalink">
        <xsl:with-param name="node" select="$node"/>
      </xsl:call-template>
    </h1>
  </xsl:template>
</xsl:stylesheet>

For glossary terms, use the following template

Download File 'permalinks/glossterm.title.xsl'

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml"
  exclude-result-prefixes="d">
  
  <xsl:template match="d:glossentry/d:glossterm">
    <xsl:variable name="id" select="(@id|../@id)[last()]"/>
    <xsl:apply-imports/>
    <xsl:if test="$generate.permalink != 0">
      <xsl:message>Generating permalink for glossterm <xsl:value-of
          select="concat('&quot;', normalize-space(.), '&quot;')"/></xsl:message>
      <xsl:call-template name="permalink">
        <xsl:with-param name="node" select=".."/>
      </xsl:call-template>
    </xsl:if>
  </xsl:template>
</xsl:stylesheet>

For sections, use section.title (originates from {xhtml,xhtml-1_1,html}/sections.xsl):

Download File 'permalinks/section.title.xsl'

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml" exclude-result-prefixes="d">

  <xsl:template name="section.title">
    <xsl:variable name="section"
      select="(ancestor::d:section |
               ancestor::d:simplesect|
               ancestor::d:sect1|
               ancestor::d:sect2|
               ancestor::d:sect3| 
               ancestor::d:sect4| 
               ancestor::d:sect5)[last()]"/>

    <xsl:variable name="renderas">
      <xsl:choose>
        <xsl:when test="$section/@renderas = 'sect1'">1</xsl:when>
        <xsl:when test="$section/@renderas = 'sect2'">2</xsl:when>
        <xsl:when test="$section/@renderas = 'sect3'">3</xsl:when>
        <xsl:when test="$section/@renderas = 'sect4'">4</xsl:when>
        <xsl:when test="$section/@renderas = 'sect5'">5</xsl:when>
        <xsl:otherwise><xsl:value-of select="''"/></xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <xsl:variable name="level">
      <xsl:choose>
        <xsl:when test="$renderas != ''">
          <xsl:value-of select="$renderas"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:call-template name="section.level">
            <xsl:with-param name="node" select="$section"/>
          </xsl:call-template>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>

    <xsl:call-template name="section.heading">
      <xsl:with-param name="section" select="$section"/>
      <xsl:with-param name="level" select="$level"/>
      <xsl:with-param name="title">
        <xsl:apply-templates select="$section" mode="object.title.markup">
          <xsl:with-param name="allow-anchors" select="1"/>
        </xsl:apply-templates>
        <xsl:if test="$level = 1">
          <xsl:call-template name="permalink">
            <xsl:with-param name="node" select="$section"/>
          </xsl:call-template>
        </xsl:if>
      </xsl:with-param>
    </xsl:call-template>
  </xsl:template>
</xsl:stylesheet>

Use your customization layer to transform your DocBook document into (X)HTML.

Discussion

Permalinks are useful as it allows it easily to copy its URL. The DocBook XSL stylesheets allows the addition of permalinks in different locations, but the above customizations make the permalink more “attached” to its title.

All the above customization files create almost the same structure in regards to its permalink. For example, a chapter title looks like this in HTML:

<h2 class="title">The Chapter Title<span
      class="permalink"><a href="..." title="Permalink"
      alt="Permalink">¶</a></span>
</h1>

With CSS rules, you can style your permalink whatever you like.

Prev	Up	Next
5.2. Adding Authors to Table of Contents	Home	5.4. Creating Simple Navigation in Chapters