Skip to content

Commit

Permalink
Added titlepage customization section
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndw
ndw committed Sep 21, 2024
1 parent 317f104 commit de14cb1
Show file tree
Hide file tree
Showing 4 changed files with 197 additions and 9 deletions.
10 changes: 5 additions & 5 deletions properties.gradle
View file
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
View file
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
View file
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
View file
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

0 comments on commit de14cb1

Please sign in to comment.