Suggestions
Search:
 

FAQ

1. DB2LaTeX Meta-FAQ
1.1. What is DB2LaTeX?
1.2. Where can I find DB2LaTeX?
1.3. Why use DB2LaTeX instead of FO/FOP/Xtreme/...?
2. DB2LaTeX Installation
2.1. Why Can't LaTeX Find its 'Figures' for Admonitions?
2.2. Why is There French in DB2LaTeX Output?
3. DB2LaTeX Customization
3.1. How to do I Choose Block Style Instead of Indented Paragraphs?
3.2. Issues for Double-sided Print Documents
3.3. How do I get LaTeX Default Fonts (e.g., Computer Modern)?
3.4. How do I Modify the LaTeX Preamble in DB2LaTeX's Output?
3.5. PDFs Open With a Weird Magnification or Blank Page
3.6. Unwanted Overlapping of Text in Headers and Footers
4. Revision of DB2LaTeX Behaviour
4.1. Why Have Tables Changed and How Do I Make Them Work?
4.2. What's the Deal with Linebreaks and Hyphenation in URLs and Monospace Text?
4.3. How Should I Mark Up Figures and MediaObjects?
5. General
5.1. Handling Character Entities

FAQ items (and errors) were contributed by j-devenish at users.sourceforge.net

1. DB2LaTeX Meta-FAQ

1.1. What is DB2LaTeX?
1.2. Where can I find DB2LaTeX?
1.3. Why use DB2LaTeX instead of FO/FOP/Xtreme/...?
1.1.

What is DB2LaTeX?

Please see the introduction.

1.2.

Where can I find DB2LaTeX?

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.

1.3.

Why use DB2LaTeX instead of FO/FOP/Xtreme/...?

2. DB2LaTeX Installation

2.1. Why Can't LaTeX Find its 'Figures' for Admonitions?
2.2. Why is There French in DB2LaTeX Output?
2.1.

Why Can't LaTeX Find its 'Figures' for Admonitions?

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

Why is There French in DB2LaTeX Output?

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>

3. DB2LaTeX Customization

3.1. How to do I Choose Block Style Instead of Indented Paragraphs?
3.2. Issues for Double-sided Print Documents
3.3. How do I get LaTeX Default Fonts (e.g., Computer Modern)?
3.4. How do I Modify the LaTeX Preamble in DB2LaTeX's Output?
3.5. PDFs Open With a Weird Magnification or Blank Page
3.6. Unwanted Overlapping of Text in Headers and Footers
3.1.

How to do I Choose Block Style Instead of Indented Paragraphs?

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

Issues for Double-sided Print Documents

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}
3.3.

How do I get LaTeX Default Fonts (e.g., Computer Modern)?

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

How do I Modify the LaTeX Preamble in DB2LaTeX's Output?

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.

3.5.

PDFs Open With a Weird Magnification or Blank Page

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

Unwanted Overlapping of Text in Headers and Footers

[Note] 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

4. Revision of DB2LaTeX Behaviour

4.1. Why Have Tables Changed and How Do I Make Them Work?
4.2. What's the Deal with Linebreaks and Hyphenation in URLs and Monospace Text?
4.3. How Should I Mark Up Figures and MediaObjects?
4.1.

Why Have Tables Changed and How Do I Make Them Work?

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

  • Colname is not understood (and is ignored).
  • Colwidth is understood if colnum   is used (though widths must be LaTeX-compatible or of the 1* form).
  • If you specify colwidth, text it becomes wrappable and justified.
  • You may use the 'align' attribute in colspecs and in individual cells. The "justify" alignment in a colspec implies a "1*" colwidth unless an explicit colwidth is given.
  • The "justify" alignment is only understood when used in a colspec.
  • If align is used without colwidth, the text will not be wrapped and the column width will be the minimum required to fit the text.
  • 1* style is only supported if tabularx is allowed. Note that it will force the table width to fill the column width.
  • The pgwide and orient attributes are not supported, though they could be in future.
  • Mixed style 1*+2pt is not supported and probably won't be in future unless we release a LaTeX style file that can calculate this. Using 2pt+1* will probably cause the wrong width calculation to be made.
  • Spans and morerows are not supported, so you will have to touch these up manually.

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

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

4.2.

What's the Deal with Linebreaks and Hyphenation in URLs and Monospace Text?

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.

4.3.

How Should I Mark Up Figures and MediaObjects?

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] 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”).

Table 1. Important Attributes and Variables for ImageObject and MediaObject Selection

Element Pertinent Attribute Consider This Recommendation
imageobject role $use.role.for.mediaobject Use a value of 1  to enable support. If not enabled, merely the first imageobject is chosen (unless $latex.graphics.formats is used).
imageobject role $preferred.mediaobject.role Normally, leave this empty and use the "latex" role. However, if you have documents that use a different role, you can set this variable to that role. A typical example would be "pdf".
imageobject role Attribute value. Use a value of latex  (preferred) or tex  (deprecated). These can co-exist with roles such as html. If no imageobject matches @role="latex" or @role="tex" then the stylesheets merely choose the first imageobject. If $preferred.mediaobject.role is not empty, that role is checked before the "latex" role.
imagedata fileref Attribute value. If used with a latex mediaobject role, we recommend that you do not include the filename extension at the end of the fileref. For example, use fileref="abc"  instead of fileref="abc.eps". This allows LaTeX to choose the correct image format amongst the ones that it knows about.
imagedata format $latex.graphics.formats If you use filename extensions in filerefs and do not use roles for mediaobjects, DB2LaTeX will use imagedata format attributes. Set this variable to "EPS" for LaTeX or "PDF,PNG,TIFF" for pdfTeX.

Example 1. Using the features described in 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>

5. General

5.1. Handling Character Entities
5.1.

Handling Character Entities

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 &nbsp; 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

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.