<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Extending the Verbatim Rendering</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="DocBook to LaTeX Publishing" /><link rel="up" href="ch03.html" title="Chapter 3. Using dblatex" /><link rel="prev" href="sec-music.html" title="Musical Notation" /><link rel="next" href="sec-index.html" title="Creating an Index" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Extending the Verbatim Rendering</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-music.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using dblatex</th><td width="20%" align="right"> <a accesskey="n" href="sec-index.html">Next</a></td></tr></table><hr /></div><div class="section" title="Extending the Verbatim Rendering"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-verbatim"></a>Extending the Verbatim Rendering</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="sec-verbatim.html#sec-literal-options">Dblatex Specific Options</a></span></dt><dt><span class="section"><a href="sec-verbatim.html#sec-scale-verbatim">Scaling Feature</a></span></dt><dt><span class="section"><a href="sec-verbatim.html#idp2586640">Formatting embedded elements</a></span></dt><dt><span class="section"><a href="sec-verbatim.html#sec-literal-env">Creating a new Verbatim Environment</a></span></dt></dl></div><div class="section" title="Dblatex Specific Options"><div class="titlepage"><div><div><h3 class="title"><a id="sec-literal-options"></a>Dblatex Specific Options</h3></div></div></div><p>There are few attributes or options specific to
<span class="command"><strong>dblatex</strong></span> to render verbatim blocks:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="sgmltag-element">role</code> attribute of
<code class="sgmltag-element">screen</code>, <code class="sgmltag-element">programlisting</code>, and
<code class="sgmltag-element">literallayout</code> can take the following special values:
</p><div class="variablelist"><dl><dt><span class="term">wrap</span></dt><dd><p>The verbatim lines can break and wrap when they are longer than the
available width. It is the default behaviour.</p></dd><dt><span class="term">overflow</span></dt><dd><p>The verbatim lines never break and go into the margin when they are too
long.</p></dd><dt><span class="term">scale</span></dt><dd><p>The verbatim block is automatically scaled so that the longest line or
specified column count
fits in the available page width. See <a class="xref" href="sec-verbatim.html#sec-scale-verbatim" title="Scaling Feature">the section called “Scaling Feature”</a>.
</p></dd></dl></div><p>
</p></li><li class="listitem"><p>The parameter <em class="parameter"><code>literal.role</code></em> can be used
to set the default role to apply. By default the value is an empty string.
</p></li><li class="listitem"><p>The parameter <em class="parameter"><code>literal.class</code></em> can be used
to set the default <em class="parameter"><code>literallayout</code></em> class when
no class attribute is given. By default the value is
<code class="literal">monospaced</code>.</p></li></ul></div></div><div class="section" title="Scaling Feature"><div class="titlepage"><div><div><h3 class="title"><a id="sec-scale-verbatim"></a>Scaling Feature</h3></div></div></div><p>The user can scale the verbatim block so that the longest line fits in
the available page width, or so that the page contains at least a specified width expressed in columns.</p><p>The scaling feature is enabled when the parameter <em class="parameter"><code>literal.extensions</code></em> is set as follow:
</p><div class="variablelist"><dl><dt><span class="term">scale</span></dt><dd><p>The scaling is performed only when the <code class="sgmltag-element">role</code> attribute
is set to "scale", or when the <code class="sgmltag-element">role</code> attribute is not set and the parameter <em class="parameter"><code>literal.role</code></em> is set to "scale".</p></dd><dt><span class="term">scale.by.width</span></dt><dd><p>The scaling is performed when the <code class="sgmltag-element">role</code> attribute
or <em class="parameter"><code>literal.role</code></em> is properly set, or when the attribute
<code class="sgmltag-element">width</code> is set. When width is set the block is scaled so that
the specified width fits in the page width.</p></dd></dl></div><p>
</p><p>Here are some listing examples with several attribute combinations producing or not the scaling. In these examples the parameter <em class="parameter"><code>literal.extensions</code></em> is set to "scale.by.width".</p><pre class="programlisting" width="110">
<programlisting width="110">
The listing is scaled and lines are wrapped after 110 characters. Check yourself:
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
0 1 2 3 4 5 6 7 8 9 10 11
</programlisting>
</pre><pre class="programlisting" width="110">
<programlisting width="110" role="overflow">
There is no scaling because the role has precedence over the width attribute:
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
0 1 2 3 4 5 6 7 8 9 10 11
</programlisting>
</pre><pre class="programlisting">
<programlisting role="scale">
The listing is scaled to display the longest line with no break:
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
0 1 2 3 4 5 6 7 8 9 10 11
</programlisting>
</pre><pre class="programlisting" width="110">
<programlisting width="110" role="scale">
The listing is scaled to fit up to 110 columns, and the lines are wrapped. In this case role is redundant because @width automatically produces scaling.
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
0 1 2 3 4 5 6 7 8 9 10 11
</programlisting>
</pre></div><div class="section" title="Formatting embedded elements"><div class="titlepage"><div><div><h3 class="title"><a id="idp2586640"></a>Formatting embedded elements</h3></div></div></div><p>The programlisting and screen environments are supported by dblatex, but
the implementation is rather conservative, that is, most of the elements
embedded in such environments are not rendered like in normal environment
(e.g. bold, enphasis, etc.). Only the contained text is printed out. For the
elements whose rendering is lost, <span class="command"><strong>dblatex</strong></span> prints out a
warning message.</p><p>For example, let's compile the following programlisting fragment:</p><pre class="programlisting"><programlisting>
zone <replaceable>zone_name</replaceable>
<optional><replaceable>class</replaceable></optional> {
type delegation-only;
};
</programlisting></pre><p><span class="command"><strong>dblatex</strong></span> warns that the <code class="sgmltag-element">optional</code>
and <code class="sgmltag-element">replaceable</code> elements are not supported (i.e. not
rendered) in the programlisting:</p><pre class="screen">$ dblatex progfrag.xml
Build the book set list...
Build the listings...
XSLT stylesheets DocBook - LaTeX 2e (devel)
===================================================
Warning: the root element is not an article nor a book
Warning: programlisting wrapped with article
replaceable not supported in programlisting or screen
optional not supported in programlisting or screen
replaceable not supported in programlisting or screen
replaceable not supported in programlisting or screen
optional not supported in programlisting or screen
replaceable not supported in programlisting or screen
...
</pre><p>If you want those elements be formatted in bold, or italic you need to
override the templates used in <code class="literal">latex.programlisting</code> mode,
as follow:</p><pre class="programlisting"><xsl:template match="replaceable|optional" mode="latex.programlisting">
<xsl:param name="co-tagin" select="'&lt;:'"/> <a id="co-verb-par1"></a><img src="images/callouts/1.png" alt="1" border="0" />
<xsl:param name="rnode" select="/"/> <a id="co-verb-par2"></a><img src="images/callouts/2.png" alt="2" border="0" />
<xsl:param name="probe" select="0"/> <a id="co-verb-par3"></a><img src="images/callouts/3.png" alt="3" border="0" />
<xsl:call-template name="verbatim.boldseq"> <a id="co-verb-template"></a><img src="images/callouts/4.png" alt="4" border="0" />
<xsl:with-param name="co-tagin" select="$co-tagin"/>
<xsl:with-param name="rnode" select="$rnode"/>
<xsl:with-param name="probe" select="$probe"/>
</xsl:call-template>
</xsl:template></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co-verb-par1"><img src="images/callouts/1.png" alt="1" border="0" /></a> <a href="#co-verb-par2"><img src="images/callouts/2.png" alt="2" border="0" /></a> <a href="#co-verb-par3"><img src="images/callouts/3.png" alt="3" border="0" /></a> </p></td><td valign="top" align="left"><p>These parameters are required in <code class="literal">latex.programlisting</code>
mode.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#co-verb-template"><img src="images/callouts/4.png" alt="4" border="0" /></a> </p></td><td valign="top" align="left"><p>The predefined template makes bold the verbatim text of the
element.</p></td></tr></table></div><p>If formatting setup is not enough, you can also render these elements
as if they were in a normal environment. To do this, you need to override the
templates used in <code class="literal">latex.programlisting</code> mode, as
follow:</p><pre class="programlisting"><xsl:template match="replaceable|optional" mode="latex.programlisting">
<xsl:param name="co-tagin" select="'&lt;:'"/>
<xsl:param name="rnode" select="/"/>
<xsl:param name="probe" select="0"/>
<xsl:call-template name="verbatim.embed"> <a id="co-verb-template2"></a><img src="images/callouts/1.png" alt="1" border="0" />
<xsl:with-param name="co-tagin" select="$co-tagin"/>
<xsl:with-param name="rnode" select="$rnode"/>
<xsl:with-param name="probe" select="$probe"/>
</xsl:call-template>
</xsl:template> </pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co-verb-template2"><img src="images/callouts/1.png" alt="1" border="0" /></a> </p></td><td valign="top" align="left"><p>To enable the normal mode rendering within a verbatim environment, call
the verbatim.embed template, and pass the mandatory parameters.</p></td></tr></table></div><p></p></div><div class="section" title="Creating a new Verbatim Environment"><div class="titlepage"><div><div><h3 class="title"><a id="sec-literal-env"></a>Creating a new Verbatim Environment</h3></div></div></div><p><span class="command"><strong>dblatex</strong></span> heavily relies upon the listing latex package
to display the <code class="sgmltag-element">screen</code>, <code class="sgmltag-element">programlisting</code>, and
<code class="sgmltag-element">literallayout</code> blocks.</p><p>The global listing setup can be overwritten with
<em class="parameter"><code>literal.layout.options</code></em> but the user can also provide its
own listing environment to use instead of the default environment, by using the following procedure:</p><div class="procedure"><ol class="procedure" type="1"><li class="step" title="Step 1"><p>Create the new listing environment in a customized latex style, like
the following example. It is required that the environment name starts with the
string <code class="literal">"lst"</code>. If not, <span class="command"><strong>dblatex</strong></span> raises an
error because it cannot recognize it as a special verbatim environment.
</p><pre class="programlisting">
%%
%% This style is derivated from the db2latex one
%%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mystyle}[2012/02/03 My DocBook Style]
%% Just use the original package and pass the options
\RequirePackageWithOptions{db2latex}
%% New listing environment doing what I want
\lstnewenvironment{lstblock}[1][]
{\lstset{numbers=left,numberstyle=\tiny,float,#1}}
{}
</pre><p>
</p></li><li class="step" title="Step 2"><p>Specify to <span class="command"><strong>dblatex</strong></span> the listing environment name
through the <em class="parameter"><code>literal.environment</code></em> parameter, either on the
command line or with a user XSL stylesheet.
</p><pre class="screen">
$ dblatex -s mystyle.sty -P literal.environment=lstblock file.xml
</pre><p>
</p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-music.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-index.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Musical Notation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Creating an Index</td></tr></table></div></body></html>