|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
Packit Service |
76cb02 |
<section id="sec-verbatim">
|
|
Packit Service |
76cb02 |
<title>Extending the Verbatim Rendering</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section id="sec-literal-options">
|
|
Packit Service |
76cb02 |
<title>Dblatex Specific Options</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>There are few attributes or options specific to
|
|
Packit Service |
76cb02 |
<command>dblatex</command> to render verbatim blocks:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<itemizedlist>
|
|
Packit Service |
76cb02 |
<listitem><para>The <sgmltag>role</sgmltag> attribute of
|
|
Packit Service |
76cb02 |
<sgmltag>screen</sgmltag>, <sgmltag>programlisting</sgmltag>, and
|
|
Packit Service |
76cb02 |
<sgmltag>literallayout</sgmltag> can take the following special values:
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<variablelist>
|
|
Packit Service |
76cb02 |
<varlistentry>
|
|
Packit Service |
76cb02 |
<term>wrap</term>
|
|
Packit Service |
76cb02 |
<listitem>
|
|
Packit Service |
76cb02 |
<para>The verbatim lines can break and wrap when they are longer than the
|
|
Packit Service |
76cb02 |
available width. It is the default behaviour.</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</varlistentry>
|
|
Packit Service |
76cb02 |
<varlistentry>
|
|
Packit Service |
76cb02 |
<term>overflow</term>
|
|
Packit Service |
76cb02 |
<listitem>
|
|
Packit Service |
76cb02 |
<para>The verbatim lines never break and go into the margin when they are too
|
|
Packit Service |
76cb02 |
long.</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</varlistentry>
|
|
Packit Service |
76cb02 |
<varlistentry>
|
|
Packit Service |
76cb02 |
<term>scale</term>
|
|
Packit Service |
76cb02 |
<listitem>
|
|
Packit Service |
76cb02 |
<para>The verbatim block is automatically scaled so that the longest line or
|
|
Packit Service |
76cb02 |
specified column count
|
|
Packit Service |
76cb02 |
fits in the available page width. See <xref linkend="sec-scale-verbatim"/>.
|
|
Packit Service |
76cb02 |
</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</varlistentry>
|
|
Packit Service |
76cb02 |
</variablelist>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</para></listitem>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<listitem><para>The parameter <parameter>literal.role</parameter> can be used
|
|
Packit Service |
76cb02 |
to set the default role to apply. By default the value is an empty string.
|
|
Packit Service |
76cb02 |
</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<listitem><para>The parameter <parameter>literal.class</parameter> can be used
|
|
Packit Service |
76cb02 |
to set the default <parameter>literallayout</parameter> class when
|
|
Packit Service |
76cb02 |
no class attribute is given. By default the value is
|
|
Packit Service |
76cb02 |
<literal>monospaced</literal>.</para></listitem>
|
|
Packit Service |
76cb02 |
</itemizedlist>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
<section id="sec-scale-verbatim">
|
|
Packit Service |
76cb02 |
<title>Scaling Feature</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The user can scale the verbatim block so that the longest line fits in
|
|
Packit Service |
76cb02 |
the available page width, or so that the page contains at least a specified width expressed in columns.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The scaling feature is enabled when the parameter <parameter>literal.extensions</parameter> is set as follow:
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<variablelist>
|
|
Packit Service |
76cb02 |
<varlistentry>
|
|
Packit Service |
76cb02 |
<term>scale</term>
|
|
Packit Service |
76cb02 |
<listitem>
|
|
Packit Service |
76cb02 |
<para>The scaling is performed only when the <sgmltag>role</sgmltag> attribute
|
|
Packit Service |
76cb02 |
is set to "scale", or when the <sgmltag>role</sgmltag> attribute is not set and the parameter <parameter>literal.role</parameter> is set to "scale".</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</varlistentry>
|
|
Packit Service |
76cb02 |
<varlistentry>
|
|
Packit Service |
76cb02 |
<term>scale.by.width</term>
|
|
Packit Service |
76cb02 |
<listitem>
|
|
Packit Service |
76cb02 |
<para>The scaling is performed when the <sgmltag>role</sgmltag> attribute
|
|
Packit Service |
76cb02 |
or <parameter>literal.role</parameter> is properly set, or when the attribute
|
|
Packit Service |
76cb02 |
<sgmltag>width</sgmltag> is set. When width is set the block is scaled so that
|
|
Packit Service |
76cb02 |
the specified width fits in the page width.</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</varlistentry>
|
|
Packit Service |
76cb02 |
</variablelist>
|
|
Packit Service |
76cb02 |
</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Here are some listing examples with several attribute combinations producing or not the scaling. In these examples the parameter <parameter>literal.extensions</parameter> is set to "scale.by.width".</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting width="110">
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
The listing is scaled and lines are wrapped after 110 characters. Check yourself:
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
|
|
Packit Service |
76cb02 |
0 1 2 3 4 5 6 7 8 9 10 11
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</programlisting>]]>
|
|
Packit Service |
76cb02 |
</programlisting>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting width="110" role="overflow">
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
There is no scaling because the role has precedence over the width attribute:
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
|
|
Packit Service |
76cb02 |
0 1 2 3 4 5 6 7 8 9 10 11
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</programlisting>]]>
|
|
Packit Service |
76cb02 |
</programlisting>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting role="scale">
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
The listing is scaled to display the longest line with no break:
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
|
|
Packit Service |
76cb02 |
0 1 2 3 4 5 6 7 8 9 10 11
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</programlisting>]]>
|
|
Packit Service |
76cb02 |
</programlisting>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting width="110" role="scale">
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
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.
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 1234567 9 123456789
|
|
Packit Service |
76cb02 |
0 1 2 3 4 5 6 7 8 9 10 11
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</programlisting>]]>
|
|
Packit Service |
76cb02 |
</programlisting>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Formatting embedded elements</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The programlisting and screen environments are supported by dblatex, but
|
|
Packit Service |
76cb02 |
the implementation is rather conservative, that is, most of the elements
|
|
Packit Service |
76cb02 |
embedded in such environments are not rendered like in normal environment
|
|
Packit Service |
76cb02 |
(e.g. bold, enphasis, etc.). Only the contained text is printed out. For the
|
|
Packit Service |
76cb02 |
elements whose rendering is lost, <command>dblatex</command> prints out a
|
|
Packit Service |
76cb02 |
warning message.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>For example, let's compile the following programlisting fragment:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting><programlisting>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
zone <replaceable>zone_name</replaceable>
|
|
Packit Service |
76cb02 |
<optional><replaceable>class</replaceable></optional> {
|
|
Packit Service |
76cb02 |
type delegation-only;
|
|
Packit Service |
76cb02 |
};
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</programlisting></programlisting>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para><command>dblatex</command> warns that the <sgmltag>optional</sgmltag>
|
|
Packit Service |
76cb02 |
and <sgmltag>replaceable</sgmltag> elements are not supported (i.e. not
|
|
Packit Service |
76cb02 |
rendered) in the programlisting:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para><screen>$ dblatex progfrag.xml
|
|
Packit Service |
76cb02 |
Build the book set list...
|
|
Packit Service |
76cb02 |
Build the listings...
|
|
Packit Service |
76cb02 |
XSLT stylesheets DocBook - LaTeX 2e (devel)
|
|
Packit Service |
76cb02 |
===================================================
|
|
Packit Service |
76cb02 |
Warning: the root element is not an article nor a book
|
|
Packit Service |
76cb02 |
Warning: programlisting wrapped with article
|
|
Packit Service |
76cb02 |
replaceable not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
optional not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
replaceable not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
replaceable not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
optional not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
replaceable not supported in programlisting or screen
|
|
Packit Service |
76cb02 |
...
|
|
Packit Service |
76cb02 |
</screen></para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>If you want those elements be formatted in bold, or italic you need to
|
|
Packit Service |
76cb02 |
override the templates used in <literal>latex.programlisting</literal> mode,
|
|
Packit Service |
76cb02 |
as follow:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para><programlisting><xsl:template match="replaceable|optional" mode="latex.programlisting">
|
|
Packit Service |
76cb02 |
<xsl:param name="co-tagin" select="'<:'"/>
|
|
Packit Service |
76cb02 |
id="co-verb-par1" />
|
|
Packit Service |
76cb02 |
<xsl:param name="rnode" select="/"/> <co id="co-verb-par2" />
|
|
Packit Service |
76cb02 |
<xsl:param name="probe" select="0"/> <co id="co-verb-par3" />
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<xsl:call-template name="verbatim.boldseq"> <co id="co-verb-template" />
|
|
Packit Service |
76cb02 |
<xsl:with-param name="co-tagin" select="$co-tagin"/>
|
|
Packit Service |
76cb02 |
<xsl:with-param name="rnode" select="$rnode"/>
|
|
Packit Service |
76cb02 |
<xsl:with-param name="probe" select="$probe"/>
|
|
Packit Service |
76cb02 |
</xsl:call-template>
|
|
Packit Service |
76cb02 |
</xsl:template></programlisting><calloutlist>
|
|
Packit Service |
76cb02 |
<callout arearefs="co-verb-par1 co-verb-par2 co-verb-par3">
|
|
Packit Service |
76cb02 |
<para>These parameters are required in <literal>latex.programlisting</literal>
|
|
Packit Service |
76cb02 |
mode.</para>
|
|
Packit Service |
76cb02 |
</callout>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<callout arearefs="co-verb-template">
|
|
Packit Service |
76cb02 |
<para>The predefined template makes bold the verbatim text of the
|
|
Packit Service |
76cb02 |
element.</para>
|
|
Packit Service |
76cb02 |
</callout>
|
|
Packit Service |
76cb02 |
</calloutlist></para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>If formatting setup is not enough, you can also render these elements
|
|
Packit Service |
76cb02 |
as if they were in a normal environment. To do this, you need to override the
|
|
Packit Service |
76cb02 |
templates used in <literal>latex.programlisting</literal> mode, as
|
|
Packit Service |
76cb02 |
follow:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para><programlisting><xsl:template match="replaceable|optional" mode="latex.programlisting">
|
|
Packit Service |
76cb02 |
<xsl:param name="co-tagin" select="'<:'"/>
|
|
Packit Service |
76cb02 |
<xsl:param name="rnode" select="/"/>
|
|
Packit Service |
76cb02 |
<xsl:param name="probe" select="0"/>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<xsl:call-template name="verbatim.embed"> <co id="co-verb-template2" />
|
|
Packit Service |
76cb02 |
<xsl:with-param name="co-tagin" select="$co-tagin"/>
|
|
Packit Service |
76cb02 |
<xsl:with-param name="rnode" select="$rnode"/>
|
|
Packit Service |
76cb02 |
<xsl:with-param name="probe" select="$probe"/>
|
|
Packit Service |
76cb02 |
</xsl:call-template>
|
|
Packit Service |
76cb02 |
</xsl:template> </programlisting><calloutlist>
|
|
Packit Service |
76cb02 |
<callout arearefs="co-verb-template2">
|
|
Packit Service |
76cb02 |
<para>To enable the normal mode rendering within a verbatim environment, call
|
|
Packit Service |
76cb02 |
the verbatim.embed template, and pass the mandatory parameters.</para>
|
|
Packit Service |
76cb02 |
</callout>
|
|
Packit Service |
76cb02 |
</calloutlist></para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para></para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
<section id="sec-literal-env">
|
|
Packit Service |
76cb02 |
<title>Creating a new Verbatim Environment</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para><command>dblatex</command> heavily relies upon the listing latex package
|
|
Packit Service |
76cb02 |
to display the <sgmltag>screen</sgmltag>, <sgmltag>programlisting</sgmltag>, and
|
|
Packit Service |
76cb02 |
<sgmltag>literallayout</sgmltag> blocks.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The global listing setup can be overwritten with
|
|
Packit Service |
76cb02 |
<parameter>literal.layout.options</parameter> but the user can also provide its
|
|
Packit Service |
76cb02 |
own listing environment to use instead of the default environment, by using the following procedure:</para>
|
|
Packit Service |
76cb02 |
<procedure>
|
|
Packit Service |
76cb02 |
<step><para>Create the new listing environment in a customized latex style, like
|
|
Packit Service |
76cb02 |
the following example. It is required that the environment name starts with the
|
|
Packit Service |
76cb02 |
string <literal>"lst"</literal>. If not, <command>dblatex</command> raises an
|
|
Packit Service |
76cb02 |
error because it cannot recognize it as a special verbatim environment.
|
|
Packit Service |
76cb02 |
<programlisting language="tex">
|
|
Packit Service |
76cb02 |
%%
|
|
Packit Service |
76cb02 |
%% This style is derivated from the db2latex one
|
|
Packit Service |
76cb02 |
%%
|
|
Packit Service |
76cb02 |
\NeedsTeXFormat{LaTeX2e}
|
|
Packit Service |
76cb02 |
\ProvidesPackage{mystyle}[2012/02/03 My DocBook Style]
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
%% Just use the original package and pass the options
|
|
Packit Service |
76cb02 |
\RequirePackageWithOptions{db2latex}
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
%% New listing environment doing what I want
|
|
Packit Service |
76cb02 |
\lstnewenvironment{lstblock}[1][]
|
|
Packit Service |
76cb02 |
{\lstset{numbers=left,numberstyle=\tiny,float,#1}}
|
|
Packit Service |
76cb02 |
{}
|
|
Packit Service |
76cb02 |
]]></programlisting>
|
|
Packit Service |
76cb02 |
</para></step>
|
|
Packit Service |
76cb02 |
<step><para>Specify to <command>dblatex</command> the listing environment name
|
|
Packit Service |
76cb02 |
through the <parameter>literal.environment</parameter> parameter, either on the
|
|
Packit Service |
76cb02 |
command line or with a user XSL stylesheet.
|
|
Packit Service |
76cb02 |
<screen>
|
|
Packit Service |
76cb02 |
$ dblatex -s mystyle.sty -P literal.environment=lstblock file.xml
|
|
Packit Service |
76cb02 |
]]></screen>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</para></step>
|
|
Packit Service |
76cb02 |
</procedure>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
</section>
|