FAQ

Please see the introduction.

The DB2LaTeX web site is at http://db2latex.sourceforge.net/. It also has a SourceForge project page. Please see the installation notes  and quickstart guide  for further information.

DB2LaTeX formats admonitions as LaTeX minipages (surrounded by a border) with helpful images ('icons') corresponding to the different types of admonition. However, you need to tell LaTeX where it can find those images. DB2LaTeX includes some EPS and PDF images that you can use if you want to. They can be found in the 'figures' folder within the 'latex' folder of the DB2LaTeX distribution. You may need to use this:

<xsl:variable name="latex.admonition.path">/path/to/db2latex/latex/figures</xsl:variable>

(You need not put a trailing slash on the end of the path, though POSIX-like operating systems usually don't mind if you do.)

Alternatively, you could copy the figures from the DB2LaTeX distribution into the directory containing the DB2LaTeX output (that is, put 'figures' into the directory that contains the LaTeX file). Then LaTeX will locate the images relative to its "current wrking directory".

A third option is to disable the use of images using:

<xsl:variable name="latex.admonition.path"></xsl:variable>

If you actually want LaTeX to look for the images in its working directory, specify '.' as the path:

<xsl:variable name="latex.admonition.path">.</xsl:variable>

You have not specified that you wish the 'gentext' language to be something other than French. For English, remove references to French:

<xsl:variable name="l10n.gentext.default.language">en</xsl:variable>
<xsl:variable name="latex.documentclass.common"></xsl:variable>
<xsl:variable name="latex.babel.language"></xsl:variable>

<xsl:variable name="latex.use.parskip">1</xsl:variable>

If you want double-sided book/report output, you will usually want chapters to begin on odd-numbered pages. For this, your \documentclass should include the 'twoside' and 'openright' options.

But by default, you will get headers and footers on the blank pages between chapters. This will occur when a chapter finishes on an odd-numbered page: the subsequent even-numbered page should be completely blank but by default fancyhdr will render text.

To prevent this, you can try including this in the .tex output of db2latex or another .tex file which is subject to \input or \usepackage:

\def\cleardoublepage{\clearpage\if@twoside%
  \ifodd\c@page\else\hbox{}\thispagestyle{empty}\newpage%
  \if@twocolumn\hbox{}\newpage\fi\fi\fi}

<xsl:variable name="latex.document.font">default</xsl:variable>

You can insert free text into the preamble using

<xsl:variable name="latex.book.preamble.post">...</xsl:variable>

or

<xsl:variable name="latex.article.preamble.post">...</xsl:variable>

You can also use $latex.override

See the documentation of vars.mod.xsl for a complete list of configurable variables.

This is to do with the default zoom rectangle of PDF documents. It is related to the first objects on the first page. I like to do this to produce convenient documents:

<xsl:variable name="latex.hyperref.param.pdftex">pdfstartview=FitH</xsl:variable>

Note that you can also configure other items, including the PDF summary window:

<xsl:variable name="latex.hyperref.param.pdftex"
  >pdfstartview=FitH, pdfhighlight=/O, pdfauthor={James Devenish}</xsl:variable>

You can prevent Adobe Acrobat Reader from displaying bookmarks when documents are opened:

<xsl:variable name="latex.hyperref.param.pdftex">pdfpagemode=UseNone</xsl:variable>

	Note
	Note: if you do not want headers, use: <xsl:variable name="latex.use.fancyhdr">0</xsl:variable>

There may be times when you have long section headings or narrow pages. In this case, the default header style of fancyhdr (capital letters) will fail because the text of one of the headings will overlap with the text of the other. To overcome this, try making your section titles shorter. If that is not possible, you can utilised truncate.sty to work around the problem. You might find truncate.sty on your disk at $TEXMF/tex/latex/misc/truncate.sty (or the equivalent of your distribution). If not, try CTAN. You will need to have this included the .tex file that db2latex produces, or in another .tex file that is subject to \input or \usepackage in the .tex file. It can instead be inserted into your DB2LaTeX output using the latex.book.preamble.post and latex.article.preamble.post variables (however, you will need to un  comment the \makeatletter and \makeatother lines).

% Safeguard against long headers.
\usepackage{truncate}
% Use an ellipsis when text would be larger than 49% of the text width.
% Preserve left/right text alignment using \hfill (works for English).
\fancyhead[ol]{\truncate{0.49\textwidth}{\sl\leftmark}}
\fancyhead[or]{\truncate{0.49\textwidth}{\hfill\sl\rightmark}}
% Use an ellipsis when text would be larger than 49% of the text width
% Preserve left/right text alignment using \hfill (works for English).
\fancyhead[el]{\truncate{0.49\textwidth}{\sl\leftmark}}
\fancyhead[er]{\truncate{0.49\textwidth}{\hfill\sl\rightmark}}
% Override the default from fancyhdr (which would be to have all-caps headings).
%\makeatletter
\renewcommand{\chaptermark}[1]{\markboth{%
  {\ifnum \c@secnumdepth>\m@ne \@chapapp\ \thechapter. \ \fi #1}}{}}
\renewcommand{\sectionmark}[1]{\markright{%
  {\ifnum \c@secnumdepth >\z@ \thesection. \ \fi #1}}}
%\makeatother

Recently, tables have been brought closer to the DocBook and CALS specifications whereby entries should be formatted as block text and surrounded by line borders. DB2LaTeX now supports paragraph block formatting (but this is not enabled by default).

Frames

Frames and borders are now closer to the OASIS CALS model defaults.

By default, the framing is "all" and rowsep="1" and colsep="1". You can, of course, override these as you wish.

Paragraph Wrapping

In assessing the current table-handling code it was noted that there is a gap between the best aesthetic rendering and what LaTeX can facilitate when given minimal DocBook markup.

A problem arises because LaTeX can either  have variable-width columns or  do paragraph wrapping. (This is common amongst much page design software and it is web browsers that have given most people the expectation that tables will be sized automatically.)

In this DB2LaTeX release, as in previous releases, the default column style is non-wrapped, centred text. This is wrong with regard to the DocBook specification but is advantageous because it allows column widths to shrink to the minimum required to hold the longest line and this prevents tables from swelling to the entire page width even when they contain small amounts of text. To compensate for this, DB2LaTeX will now honour several important table attributes and the colspec element. Therefore, many well-written DocBook documents can be rendered properly by DB2LaTeX. If you want paragraph-wrapped text, specify colwidths or the "justified" alignment. Furthermore, a wrap-by-default option is available (though it will force the table to occupy the entire column width unless explicit widths are given).

Supported Markup

Bold Column Headings

If you want headings to be bold, use the emphasis element (with role='bold') around the text in each entry.

If you need a LaTeX-specific feature then you can redefine the "latex.thead.row.entry" template:

<xsl:template name="latex.thead.row.entry">
<xsl:text>{\bfseries </xsl:text><xsl:apply-templates/><xsl:text>}</xsl:text>
</xsl:template>

Captions

Table captions are now typeset above tables (rather than below them). This is conventional in some publishing circles, as is having figure captions below the figures. This is configurable using $formal.title.placement.

A major improvement is that markup in titles will now be honoured. However, this could be detrimental for PDF output with hyperref bookmarks due to unintended link nesting.

Floats

If you want to remove the horizontal lines from above and below floats (tables and figures), use:

<xsl:template name="latex.float.preamble" />

	Note
	Informaltables are no longer LaTeX 'floats' and will not appear with captions or in the list of tables.

DB2LaTeX uses the url   and hyperref   packages to provide hyperlinks and URLs. However, there are certain situations when they will fail to give us the results we desire and where the two packages conflict (perhaps depending on what versions you have). To work around this, DB2LaTeX used to insert “optional hyphens”  after slashes in URLs. While this does indeed split URLs across lines, it has the unfortunate side effect of outputting hyphens when a URL is split across two lines. A new feature has now been added to DB2LaTeX which causes slash characters themselves to be the hyphenation characters. Therefore, in URLs, slashes will now behave like hyphens behave in regular text. Additionally, the url   LaTeX package can be used to hyphenate inline monospace sequences such as literal   and filename   and systemitem . These new features are enabled (by default) and work well with English. If they do not suit you, they can be disabled using:

<xsl:variable name="latex.hyphenation.tttricks">0</xsl:variable>

A deficiency of the ttricks is that only one hyphenation character can be used. Depending on the text of the document, the DB2LaTeX default characters might not be useful. It is possible to choose a different character and if this is a common requirement, instructions could appear here in future. A better solution would be to provide behaviour that is like David Carlisle's url package, which has several hyphenation characters. The nicest solution may be to utilise the url package itself. The current impediment is that use of the url package would result in monospace text becoming active hyperlinks.

Only ImageObjects are supported. If VideoObjects and AudioObjects are present they will be ignored -- any remaining ImageObjects or TextObjects will be used. TextObjects will never be used when ImageObjects are present.

If you have a single image, you may wish to do this:

<figure id='x1'><title>Caption</title>
  <mediaobject>
    <imageobject><imagedata fileref='y.png' scale='80' /></imageobject>
  </mediaobject>
</figure>

For some publications, you may prefer to have a short title and an explanatory caption:

<figure id='x1'><title>Title</title>
  <mediaobject>
    <imageobject><imagedata fileref='y.png' scale='80' /></imageobject>
    <caption><para>Explanatory caption.</para></caption>
  </mediaobject>
</figure>

The caption will be typeset as part of the title paragraph.

	Note
	Titles should not  have full stops (periods), but captions should.

If you have multiple images, use multiple mediaobjects:

<figure id='x2'><title>Title</title>
  <mediaobject>
    <imageobject><imagedata format='PNG' fileref='y.png' scale='80' /></imageobject>
    <caption><para>Explanatory caption.</para></caption>
  </mediaobject>
  <mediaobject>
    <imageobject><imagedata format='PNG' fileref='z.png' width='3cm' /></imageobject>
    <caption><para>Explanatory caption.</para></caption>
  </mediaobject>
</figure>

Each mediaobject will become a labelled 'subfigure' and the captions will appear with each subfigure (then the title will stand on its own).

You may also wish to investigate the effect of:

<xsl:variable name="latex.figure.title.style">\itshape </xsl:variable>

If multiple ImageData are present because you have an image in multiple formats, DB2LaTeX is fundamentally unable to choose the correct image format for your document. This is because DB2LaTeX does not know whether you will be using LaTeX or pdfTeX. Therefore, you must give it hints using roles and formats (see Table 1, “Important Attributes and Variables for ImageObject and MediaObject Selection”).

<figure id='x3'><title>Title</title>
  <mediaobject>
    <imageobject role='html'><imagedata format='GIF' fileref='y.gif' scale='80' /></imageobject>
    <imageobject role='html'><imagedata format='PNG' fileref='y.png' scale='80' /></imageobject>
    <imageobject role='latex'><imagedata fileref='y' width='3cm' /></imageobject>
    <caption><para>Explanatory caption.</para></caption>
  </mediaobject>
</figure>

For DocBook authors with multiple output modalities (such as LaTeX, HTML, plain text), the expression of symbols within text poses difficulties. For example, a non-breaking space in HTML needs to be expressed literally as   while in LaTeX it would be ~.

One way to provide a flexible mechanisms for symbols is to use DocBook's symbol element in combination with character entities.

For example, you could declare some entities in your DocBook files...

<!ENTITY nbsp   "<symbol>&amp;#160;</symbol>"> <!-- non-breaking space, U+00A0 ISOnum -->
<!ENTITY ndash  "<symbol>&amp;#8211;</symbol>"> <!-- en dash, U+2013 ISOpub -->
<!ENTITY hellip "<symbol>&amp;#8230;</symbol>"> <!-- horizontal ellipsis, U+2026 ISOpub -->

...and then insert this into the stylesheet you are using with db2latex...

<xsl:template match="symbol">
  <xsl:param name="entity"><xsl:value-of select="." /></xsl:param>
  <xsl:choose>
    <xsl:when test="$entity='&amp;#160;'"><xsl:text>~</xsl:text></xsl:when>
    <xsl:when test="$entity='&amp;#8211;'"><xsl:text>--</xsl:text></xsl:when>
    <xsl:when test="$entity='&amp;#8230;'"><xsl:text>\ldots</xsl:text></xsl:when>
    <xsl:otherwise>
      <xsl:call-template name="inline.charseq"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

...and then insert this into the stylesheet you are using with HTML output...

<xsl:template match="symbol">
  <xsl:param name="entity"><xsl:value-of select="." /></xsl:param>
  <xsl:choose>
    <-- Replace some high-order characters with ASCII equivalents -->
    <xsl:when test="$entity='&amp;#8211;'"><xsl:text>-</xsl:text></xsl:when>
    <xsl:when test="$entity='&amp;#8230;'"><xsl:text>...</xsl:text></xsl:when>
    <-- No need to modify &amp;#160; -->
    <xsl:otherwise>
      <xsl:call-template name="inline.charseq"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

(Note that DB2LaTeX and other DocBook stylesheets may have a 'dingbat' template, so you may wish to investigate that. Instead of the <xsl:text> above, you could call the dingbat template.)

In this way, you can adapt the symbols according to the output modality. Furthermore, you have the full flexibility of XSL templates which means that you can adapt your symbols with XSL logic. This is useful for output formats which have special requirements depending on the context of the text (such as can be the case with PDF).

	Warning
	Warning: symbol elements are not allowed within every other element and, therefore, are not a cure-all. Also, it will not work if the text is subsequently escaped (e.g. if the backslash in \ldots gets escaped).

For the bulk of your entities, you can probably replace this method with a proper XML/XSL mechanism, though I am not knowledgeable enough to know what such a method might be.