Extending the Verbatim Rendering

Extending the Verbatim Rendering
Prev	Chapter 3. Using dblatex	Next

Dblatex Specific Options
Scaling Feature
Formatting embedded elements
Creating a new Verbatim Environment

Dblatex Specific Options

There are few attributes or options specific to dblatex to render verbatim blocks:

The role attribute of screen, programlisting, and literallayout can take the following special values:
wrap
The verbatim lines can break and wrap when they are longer than the available width. It is the default behaviour.
overflow
The verbatim lines never break and go into the margin when they are too long.
scale
The verbatim block is automatically scaled so that the longest line or specified column count fits in the available page width. See the section called “Scaling Feature”.
The parameter literal.role can be used to set the default role to apply. By default the value is an empty string.
The parameter literal.class can be used to set the default literallayout class when no class attribute is given. By default the value is monospaced.

Scaling Feature

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.

The scaling feature is enabled when the parameter literal.extensions is set as follow:

scale: The scaling is performed only when the role attribute is set to "scale", or when the role attribute is not set and the parameter literal.role is set to "scale".
scale.by.width: The scaling is performed when the role attribute or literal.role is properly set, or when the attribute width is set. When width is set the block is scaled so that the specified width fits in the page width.

Here are some listing examples with several attribute combinations producing or not the scaling. In these examples the parameter literal.extensions is set to "scale.by.width".

<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>

<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>

<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>

<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>

Formatting embedded elements

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, dblatex prints out a warning message.

For example, let's compile the following programlisting fragment:

<programlisting>
 
zone <replaceable>zone_name</replaceable> 
<optional><replaceable>class</replaceable></optional> { 
    type delegation-only;
};    
 
</programlisting>

dblatex warns that the optional and replaceable elements are not supported (i.e. not rendered) in the programlisting:

$ 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
...

If you want those elements be formatted in bold, or italic you need to override the templates used in latex.programlisting mode, as follow:

<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.boldseq"> 
     <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>

	These parameters are required in `latex.programlisting` mode.
	The predefined template makes bold the verbatim text of the element.

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 latex.programlisting mode, as follow:

<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"> 
     <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>

To enable the normal mode rendering within a verbatim environment, call the verbatim.embed template, and pass the mandatory parameters.

Creating a new Verbatim Environment

dblatex heavily relies upon the listing latex package to display the screen, programlisting, and literallayout blocks.

The global listing setup can be overwritten with literal.layout.options but the user can also provide its own listing environment to use instead of the default environment, by using the following procedure:

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 "lst". If not, dblatex raises an error because it cannot recognize it as a special verbatim environment.

%%
%% 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}}
  {}

Specify to dblatex the listing environment name through the literal.environment parameter, either on the command line or with a user XSL stylesheet.
```
$ dblatex -s mystyle.sty -P literal.environment=lstblock file.xml
```

Prev	Up	Next
Musical Notation	Home	Creating an Index