Skip to content

Commit

Permalink
Merge pull request #509 from ndw/custom-titlepages
Browse files Browse the repository at this point in the history
Document how to customize title pages
  • Loading branch information
ndw authored Sep 21, 2024
2 parents 61aef37 + de14cb1 commit a190427
Show file tree
Hide file tree
Showing 11 changed files with 330 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ class TestCase {
doFirst {
println("Processing ${testname}.html with ${config.name}")
println(config.parameters)
println(dbxsl)
}
*/

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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'])

Expand Down Expand Up @@ -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)))
Expand Down
10 changes: 5 additions & 5 deletions properties.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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'
}
170 changes: 170 additions & 0 deletions src/guide/xml/ch03.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
24 changes: 21 additions & 3 deletions src/guide/xml/changelog.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion src/guide/xml/guide.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
70 changes: 70 additions & 0 deletions src/test/resources/book.014.xsl
Original file line number Diff line number Diff line change
@@ -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>
1 change: 1 addition & 0 deletions src/test/resources/expected/book.014.html
Original file line number Diff line number Diff line change
@@ -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>
Binary file added src/test/resources/media/out.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/test/resources/media/yoyodyne.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit a190427

Please sign in to comment.