Merge pull request #509 from ndw/custom-titlepages

Document how to customize title pages

buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestCase.groovy

@@ -137,6 +137,7 @@ class TestCase {
       doFirst {
         println("Processing ${testname}.html with ${config.name}")
         println(config.parameters)
+        println(dbxsl)
       }
        */
 

buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestGenerator.groovy

@@ -118,6 +118,10 @@ class TestGenerator {
     testConfigurations.create('default')
       .withEnvironments(['default'])
 
+    testConfigurations.create('book-014')
+      .withEnvironments(['default'])
+      .withStylesheet("${uBuildDir}/../src/test/resources/book.014.xsl")
+
     testConfigurations.create('callouts')
       .withEnvironments(['verbatim', 'callouts'])
 
@@ -156,6 +160,7 @@ class TestGenerator {
      'presentation\\.': 'presentations',
      'glossary\\.00[1,2,3,4,5,6]': 'glossary-collection', // Not 7, 8, or 9!
      'glossary\\.01': 'glossary-collection',
+     'book\\.014': 'book-014',
     ].each { entry ->
       Pattern pat = ~"^.*${entry.key}.*\$"
       regexList.add(new Tuple(pat, testConfigurations.find(entry.value)))

properties.gradle

@@ -3,20 +3,20 @@ ext {
   xslTNGtitle = 'DocBook xslTNG'
   xslTNGbaseName = 'docbook-xslTNG'
   xslTNGversion = '2.2.0'
-  guideVersion = '2.2.0'
+  guideVersion = '2.2.0a'
   guidePrerelease = false
 
-  docbookVersion = '5.2CR5'
-  publishersVersion = '5.2CR5'
+  docbookVersion = '5.2'
+  publishersVersion = '5.2'
 
-  saxonVersion = '12.4'
+  saxonVersion = '12.5'
   saxonGroup = 'net.sf.saxon'
   saxonEdition = 'Saxon-HE'
   //saxonGroup = 'com.saxonica'
   //saxonEdition = 'Saxon-EE'
 
   metadataExtractorVersion = '2.18.0'
   jingVersion = '20220510'
-  xmlresolverVersion = '5.2.3'
+  xmlresolverVersion = '6.0.9'
   sincludeVersion = '5.2.4'
 }

src/guide/xml/ch03.xml

@@ -226,6 +226,176 @@ a customization layer.</para>
 </orderedlist>
 </section>
 
+<section xml:id="titlepages">
+<title>Customizing title pages</title>
+
+<para>All of the titled elements (books, chapters, sections, etc.) have “title pages”. That is,
+they have a
+<tag namespace="http://www.w3.org/1999/xhtml">header</tag> element that contains the
+elements from the <tag>info</tag> that should be presented in the title header.
+In practice, <tag>info</tag> is a wrapper for general metadata about the element and
+often contains many elements that shouldn’t be presented.</para>
+
+<para>There’s <emphasis>so</emphasis> much variation both in what goes in the
+<tag>info</tag> elements and in what users need to have in the title header, that
+there’s no practical way to control it simply with stylesheet parameters.</para>
+
+<para>Instead the stylesheets offer two customization mechanisms: first, each header is formed
+from a header template. You can change the titlepage template in your
+<link linkend="layer">customization layer</link>.</para>
+
+<para>For example, the default titlepage template for chapter headers is:</para>
+
+<programlisting language="xml"><![CDATA[<header>
+  <tmp:apply-templates select="db:title">
+    <h2><tmp:content/></h2>
+  </tmp:apply-templates>
+  <tmp:apply-templates select="db:subtitle">
+    <h3><tmp:content/></h3>
+  </tmp:apply-templates>
+</header>]]></programlisting>
+
+<para>The <code>tmp:apply-templates</code> elements aren’t as sophisticated as
+XSLT templates, but they let you select parts of the document. If nothing is
+selected, the content is ignored. When the title page template is evaluated, the context
+item is the <tag>info</tag> element.</para>
+
+<para>Inside the <code>tmp:apply-templates</code>, you can decide what HTML markup should
+appear. The
+<code>tmp:content</code> element will be replaced by the result of processing
+the element or elements you selected.</para>
+
+<para>As a consequence of that template, a chapter title page contains the
+chapter title in an <tag namespace="http://www.w3.org/1999/xhtml">h2</tag> and
+the subtitle in an <tag namespace="http://www.w3.org/1999/xhtml">h3</tag>. No
+other elements in the <tag>info</tag> are presented.</para>
+
+<para>Suppose you are writing a book where each chapter has a different author.
+You can add the authors to the chapter title page by updating the template in
+your customization layer. The stylesheets contain a
+<varname>v:templates</varname> variable for this purpose. Any templates that you
+put inside it will be used before the default templates.</para>
+
+<programlisting language="xml"><![CDATA[<xsl:variable name="v:templates" as="document-node()"
+              xmlns:v="http://docbook.org/ns/docbook/variables">
+  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns="http://www.w3.org/1999/xhtml">
+    <db:chapter context="parent::db:book">
+      <header>
+        <tmp:apply-templates select="db:title">
+          <h2><tmp:content/></h2>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:subtitle">
+          <h3><tmp:content/></h3>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:author">
+          <h3 class="author">
+            <tmp:content/>
+          </h3>
+        </tmp:apply-templates>
+      </header>
+    </db:chapter>
+  </xsl:document>
+</xsl:variable>]]></programlisting>
+
+<para>With that customization, a chapter title page contains the
+chapter title in an <tag namespace="http://www.w3.org/1999/xhtml">h2</tag>
+and the subtitle and authors in 
+<tag namespace="http://www.w3.org/1999/xhtml">h3</tag> elements, in that order.
+If you change the order of the <code>tmp:apply-template</code> elements, the
+order of the elements in the header will change.</para>
+
+<para>Another common requirement is to put a graphic on the title page of a
+book. Here’s how you might do that. (This example appears in the test suite
+as test <filename>book.014.xml</filename>.) Add the <tag>cover</tag> to your
+<tag>info</tag> element:</para>
+
+<programlisting language="xml"><![CDATA[<book xmlns="http://docbook.org/ns/docbook" version="5.2">
+<info>
+  <title>Unit Test: book.014</title>
+  <cover>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="../media/yoyodyne.png"/>
+      </imageobject>
+    </mediaobject>
+  </cover>
+  <editor>
+    <personname>
+      <firstname>Norman</firstname>
+      <surname>Walsh</surname>
+    </personname>
+    <email>[email protected]</email>
+  </editor>
+</info>
+…
+</book>]]></programlisting>
+
+<para>Then decide how you want that graphic in the header with a new book template:</para>
+
+<programlisting language="xml"><![CDATA[<xsl:variable name="v:templates" as="document-node()"
+              xmlns:v="http://docbook.org/ns/docbook/variables">
+  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns="http://www.w3.org/1999/xhtml">
+    <db:book>
+      <header>
+        <tmp:apply-templates select="db:cover/db:mediaobject">
+          <div class="cover">
+            <tmp:content/>
+          </div>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:title">
+          <h1><tmp:content/></h1>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:editor">
+          <div class="editor">
+            <h3><tmp:content/></h3>
+          </div>
+        </tmp:apply-templates>
+      </header>
+    </db:book>
+  </xsl:document>
+</xsl:variable>]]></programlisting>
+
+<para>This template will output the cover image, then the title, then the editor.
+If you want to update multiple templates, put them all in the same 
+<varname>v:templates</varname> element as siblings.</para>
+
+<para>Once you’ve output the elements in the header, you can use CSS to
+customize their appearance further.</para>
+
+<para>You can get a long way just by updating the title page templates, but not
+always far enough. If you can’t achieve what you need by changing a template,
+you can take full control.</para>
+
+<para>Each element generates its title page with the <mode>m:generate-titlepage</mode>
+mode. If you add a template in that mode to your customization layer, it has
+complete freedom to generate a custom title page.</para>
+
+<para>Here, for example, is a book title page template:</para>
+
+<programlisting language="xml"><![CDATA[<xsl:template match="db:book" mode="m:generate-titlepage">
+  <header>
+    <h1>
+      <xsl:apply-templates select="db:info/db:title" mode="m:titlepage"/>
+    </h1>
+    <p>Hello, world</p>
+  </header>
+</xsl:template>]]></programlisting>
+
+<para>With this XSLT template in your customization layer, the book title page
+will consist of the title in an 
+<tag namespace="http://www.w3.org/1999/xhtml">h1</tag>
+and the phrase “Hello, world” in a paragraph.
+In this case, the context item for the XSLT template is the main element, not
+its <tag>info</tag> child. But it will <emphasis>always</emphasis> have an
+<tag>info</tag> child, even if your original document didn’t have a wrapper
+around the titlepage metadata.</para>
+
+</section>
+
 <section xml:id="media">
 <title>Managing media</title>
 

src/guide/xml/changelog.xml

@@ -10,9 +10,27 @@ be of interest to users of the stylesheets. See the commits and pull requests on
 <link xlink:href="https://github.com/docbook/xslTNG/">the repository</link> for
 finer detail.</para>
 
-<!--
-Added panelset
--->
+<section xml:id="r220a">
+<info>
+  <title>Changes in version 2.2.0a</title>
+  <productnumber>2.2.0a</productnumber>
+  <date>2024-09-21</date>
+</info>
+<para>This is an intermediate version. It’ll be published as 2.2.1 shortly.</para>
+<itemizedlist>
+<listitem>
+  <para>Support <parameter>variablelist-panelset</parameter> presentation for
+  <tag>variablelist</tag> elements.
+  </para>
+</listitem>
+<listitem>
+  <para>Added <xref linkend="titlepages"/> to the guide.</para>
+</listitem>
+<listitem>
+  <para>(Note to self: review other PRs before publishing 2.2.1!)</para>
+</listitem>
+</itemizedlist>
+</section>
 
 <section xml:id="r220">
 <info>

src/guide/xml/guide.xml

@@ -14,7 +14,7 @@
 <pubdate/>
 <legalnotice>
 <literallayout><citetitle>DocBook xslTNG</citetitle>
-Copyright © 2020–2023 Norman Walsh.
+Copyright © 2020–2024 Norman Walsh.
 All Rights Reserved.</literallayout>
 
 <para>Permission is granted to copy, distribute and/or modify this

src/test/resources/book.014.xsl

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns:f="http://docbook.org/ns/docbook/functions"
+                xmlns:h="http://www.w3.org/1999/xhtml"
+                xmlns:m="http://docbook.org/ns/docbook/modes"
+                xmlns:v="http://docbook.org/ns/docbook/variables"
+                xmlns:xs="http://www.w3.org/2001/XMLSchema"
+                xmlns="http://www.w3.org/1999/xhtml"
+                exclude-result-prefixes="#all"
+                version="3.0">
+
+<!-- this is only intended to run against the built xslt output -->
+<xsl:import href="../../../build/xslt/docbook.xsl"/>
+
+<xsl:variable name="v:templates" as="document-node()"
+              xmlns:v="http://docbook.org/ns/docbook/variables">
+  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns="http://www.w3.org/1999/xhtml">
+    <db:book>
+      <header>
+        <tmp:apply-templates select="db:cover/db:mediaobject">
+          <div class="cover">
+            <tmp:content/>
+          </div>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:title">
+          <h1><tmp:content/></h1>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:editor">
+          <div class="editor">
+            <h3><tmp:content/></h3>
+          </div>
+        </tmp:apply-templates>
+      </header>
+    </db:book>
+    <db:chapter context="parent::db:book">
+      <header>
+        <tmp:apply-templates select="db:title">
+          <h2><tmp:content/></h2>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:subtitle">
+          <h3><tmp:content/></h3>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:author">
+          <h3 class="author">
+            <tmp:content/>
+          </h3>
+        </tmp:apply-templates>
+      </header>
+    </db:chapter>
+  </xsl:document>
+</xsl:variable>
+
+<xsl:template match="db:book" mode="m:docbook">
+  <xsl:message>Processing with book.014.xsl customization layer</xsl:message>
+  <xsl:next-match/>
+</xsl:template>
+
+<xsl:template match="db:book" mode="m:generate-titlepage">
+  <header>
+    <h1>
+      <xsl:apply-templates select="db:info/db:title" mode="m:titlepage"/>
+    </h1>
+    <p>Hello, world</p>
+  </header>
+</xsl:template>
+
+</xsl:stylesheet>

src/test/resources/expected/book.014.html

@@ -0,0 +1 @@
+<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" class="no-js"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><script>(function(H){H.className=H.className.replace(/\bno-js\b/,'js')})(document.documentElement)</script><title>Unit Test: book.014</title><meta name="viewport" content="width=device-width, initial-scale=1.0"/><link href="https://purl.org/dc/elements/1.1/" rel="schema.dc"/><meta content="2011-04-22T17:02:00-06:00" name="dc.modified"/><meta content="DocBook xslTNG" name="generator"/><link href="./css/docbook.css" rel="stylesheet" media="screen"/></head><body class="home"><nav class="top"></nav><main><article class="book division"><header><h1>Unit Test: book.014</h1><div class="editor"><h3><span class="editedby">Edited by </span><span class="first-last personname"><span class="firstname">Norman</span> <span class="surname">Walsh</span></span></h3></div></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#R_ch1"><span class="label">1</span><span class="sep">. </span>A brief history of Yoyodyne</a></li><li><a href="#R_ch2"><span class="label">2</span><span class="sep">. </span>Grovers Mill: No place like home</a></li><li><a href="#R_ch3"><span class="label">3</span><span class="sep">. </span>Stories of Planet 10</a></li></ul></div></div><section id="R_ch1" class="chapter component"><header><h2>Chapter <span class="label">1</span><span class="sep">. </span>A brief history of Yoyodyne</h2></header><p>…</p></section><section id="R_ch2" class="chapter component"><header><h2>Chapter <span class="label">2</span><span class="sep">. </span>Grovers Mill: No place like home</h2></header><p>…</p></section><section id="R_ch3" class="chapter component"><header><h2>Chapter <span class="label">3</span><span class="sep">. </span>Stories of Planet 10</h2></header><p>…</p></section></article></main><nav class="bottom"></nav></body></html>