HOWTO: Docutils2fo 0.6

Contents

Convert to PDF

You will need a FO processor to convert to PDF. An open source, complete implementation, fop, is available at:

http://ci.apache.org/projects/xmlgraphics/fop/snapshots/

In addition, if you want to inclue any math in your document, download jeuclid:

http://jeuclid.sourceforge.net/

If you use ASCII math in your document, you will also have to download the asciimathml.py and install it.

https://github.com/favalex/python-asciimathml/blob/master/asciimathml.py

Here is an example of converting file file.rst to out.pdf.

rst2xml.py --strip-comments --trim-footnote-reference-space file.rst | fop -xml - -xsl xsl_fo/docutils_to_fo.xsl -pdf out.pdf

In this case, rst converts file.rst to XML, and the fop processor both converts the XML file to FO, and then processes that file. You can achieve the same result in several steps:

  1. rst2xml.py --strip-comments --trim-footnote-reference-space file.rst file.xml
  2. xsltproc xsl_fo/docutils_to_fo.xsl file.xml > file.fo
  3. fop -fo file.fo -pdf out.pdf

The script docutils_to_fo.sh combines several of these steps to make converstion easier, and adds a few nice features, but it functions more of a convenience than as a necessary tool; one does not need it to convert. It is a work in progress, and serves as an example of how one could writes his own simple script to convert to PDF. The essential conversion utilities are the FO processor, and the XSL stylesheets themselves.

Post Processing a Document

You may need to further process the XML document created by rst2xml.py before converting it to FO in two cases: to include raw XML, and to include MathML. In both cases, use the rstxml2xml.py script included in the scripts folder:

rst2xml.py --strip-comments --trim-footnote-reference-space file.rst\
|rstxml2xml.py | fop -xml - -xsl xsl_fo/docutils_to_fo.xsl -pdf out.pdf

Install the script in the normal way:

python setup.py install

The script can also be used if you wish to convert the document in steps.

  1. rst2xml.py --strip-comments --trim-footnote-reference-space file.rst file.xml
  2. rstxml2xml.py file.xml > file_fixed.xml
  3. xsltproc xsl_fo/docutils_to_fo.xsl file_fixed.xml > file.fo
  4. fop -fo file.fo -pdf out.pdf

Including Raw XML

If you have included raw XML, such as:

.. raw:: XML

<math ....

<!--etc-->

The XML will be converted to plain text, unless you use the rstxml2xml.py script.

Converting ASCII MathML to MathML

If you have included ASCII MathML in your document, you should also use the rstxml2xml.py script. If you do not post process the document, the math will appear as ASCII text. If you post process it, the equations will appear formatted.

Customize

In order to change the defaults of the stylesheets, you will need to create a new stylesheet which imports the standard stylesheet, and then process this stylesheet.

As an example, consider that you might want to change your top and bottom margins from the default fo 1 inch to 1.5 inches. First, create the following stylesheet:

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version="1.1"
    >
    <xsl:import href="xsl_fo/docutils_to_fo.xsl"/>
    <xsl:attribute-set name="page-margins">
        <xsl:attribute name="margin-top">1.5in</xsl:attribute>
        <xsl:attribute name="margin-bottom">1.5in</xsl:attribute>
    </xsl:attribute-set>
</xsl:stylesheet>

Save this stylesheet with any name you want. In this case, I've saved as custom.xsl. Next, I process the document in the normal way, except that I used custom.xsl as my stylesheet instead of docutils_to_fo.xsl

rst2xml.py --strip-comments --trim-footnote-reference-space <file.rst> | fop -xml - -xsl custom.xsl -pdf out.pdf

Attribute Sets

When you import the docutils_to_fo.xsl stylesheet, you also import all of its rules, except the ones you re-write. In the example above, the attribute set in docutils_to_fo.xsl looks like this:

<xsl:attribute-set name="page-margins">
    <xsl:attribute name="margin-left">1.0in</xsl:attribute>
    <xsl:attribute name="margin-right">1.0in</xsl:attribute>
    <xsl:attribute name="margin-top">1.0in</xsl:attribute>
    <xsl:attribute name="margin-bottom">1.0in</xsl:attribute>
</xsl:attribute-set>

I changed the attribute for margin-top and margin-bottom, but left the margin-right and margin-left unchanged. You can also add to attribute sets. In this case, the page-margins attribute gets applied to the sequence of pages--practically the whole document. So in order to change the font size to 14 points, I could create the attribute set as:

<xsl:attribute-set name="page-margins">
    <xsl:attribute name="margin-top">1.5in</xsl:attribute>
    <xsl:attribute name="margin-bottom">1.5in</xsl:attribute>
    <xsl:attribute name="font-size">14pt</xsl:attribute>
</xsl:attribute-set>

Most of the customization occurs through attribute sets. If you are familiar with CSS, then the syntax will look very similar, and is in many cases exactly the same. If you have doubts, check out the FO specs online.

Other Ways to Customize

The other ways to customize are to re-write an entire template rule, change a parameter, or, in one case, change a variable. All these methods are explained below.

Headers and Footers

Create a header

In the document (not the config file), use the following:

.. header::

   A Christmas Carol

The header will appear on every page.

Create a page number in a header or footer

(NOT SURE I WANT TO IMPLEMENT THIS)

In the document (not the config file), use the following:

.. role:: page-num

.. footer::

   Charles Dickens.

   :page-num:`1`

Page numbers will be generated automatically.

Change space between header and body text

<xsl:variable name="region-body-margin-top">.5in<xsl:variable>
<xsl:variable name="region-body-margin-bottom">.5in<xsl:variable>

Footnotes and Endnotes

Changing the default footnote separator

Rewrite the named template make-footnote-separator:

<!--gets rid of separator-->
<xsl:template name="make-footnote-separator"/>

Changing the size of the label

The attribute set "default-footnote-label-inline" sets the formatting of the label in the text:

<!--changes size form 8 to 10 pts-->
<xsl:attribute-set name="default-footnote-label-inline">
    <xsl:attribute name="font-size">10pt</xsl:attribute>
</xsl:attribute-set>

Changing the space between label and footnote at bottom of page

<xsl:attribute-set name="footnote-list-block">
    <xsl:attribute name="provisional-distance-between-starts">18pt</xsl:attribute>
</xsl:attribute-set>

Changing space between footnotes

<xsl:attribute-set name="footnote-list-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Note: Use space-before.conditionality ="retain" to set space between first footnote and text. Or, set space-after in the footnote separator text, and use space-after.conditionality ="retain".

Changing space between paragraphs in footnotes

<xsl:attribute-set name="footnote-paragraph-block">
    <xsl:attribute name="space-before">15pt</xsl:attribute>
</xsl:attribute-set>

Dedication

Putting the dedication on its own page

The default template for the dedication is:

<xsl:template match="topic[@classes='dedication']">
    <xsl:apply-templates/>
</xsl:template>

Change this to:

<xsl:template match="topic[@classes='dedication']">
    <fo:block break-before = "page" break-after="page">
        <xsl:apply-templates/>
    </fo:block>
</xsl:template>

Dedication Title

Change the dedication-title-block attribute set:

<xsl:attribute-set name="dedication-title-block">
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Dedication paragraphs

To change the characteristics of the paragraphs of the dedication, use the dedication-paragraph-block and dedication-first-paragraph-block.

<xsl:attribute-set name="dedication-paragraph-block">
    <xsl:attribute name="font-style">italic</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="dedication-first-paragraph-block"
    use-attribute-sets = "dedication-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

Abstract

Putting the abstract on its own page

The default template for the abstract is:

<xsl:template match="topic[@classes='abstract']">
    <xsl:apply-templates/>
</xsl:template>

Change this to:

<xsl:template match="topic[@classes='abstract']">
    <fo:block break-before = "page" break-after="page">
        <xsl:apply-templates/>
    </fo:block>
</xsl:template>

Abstract Title

Change the abstract-title-block attribute set:

<xsl:attribute-set name="abstract-title-block">
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Abstract paragraphs

To change the characteristics of the paragraphs of the abstract, use the abstract-paragraph-block and abstract-first-paragraph-block.

<xsl:attribute-set name="abstract-paragraph-block">
    <xsl:attribute name="font-style">italic</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="abstract-first-paragraph-block"
    use-attribute-sets = "abstract-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

TOC

Putting toc on its own page

For a break before, use the break-before = page in the attribute set toc-title-block:

<xsl:attribute-set name="toc-title-block">
    <xs:attribute name="break-before">page</xs:attribute>
</xsl:attribute-set>

Use a page break in the element that comes after it.

Another way to put the TOC on its own page (besides using a whole new page run, the preferred method for more involved documents), is to rewrite the matching template. The default is:

<xsl:template match="topic[@classes='contents']">
    <xsl:apply-templates/>
</xsl:template>

Rewrite this to:

<xsl:template match="topic[@classes='contents']">
    <fo:block break-before = "page" break-after="page">
        <xsl:apply-templates/>
    </fo:block>
</xsl:template>

Formatting the title

Use the attribue set toc-title-block:

<xsl:attribute-set name="toc-title-block">
    <xs:attribute name="text-align">left</xs:attribute>
</xsl:attribute-set>

Setting the defaults on each entry

Use the toc-entry-defaults-block to set properties for all of the toc entries at once:

<xsl:attribute-set name="toc-entry-defaults-block">
    <xsl:attribute name="space-after">3pt</xsl:attribute>
    <xsl:attribute name="text-align-last">justify</xsl:attribute>
</xsl:attribute-set>

Formatting the entries

Use the attribute-set toc-level1/2...-block:

<xsl:attribute-set name="toc-level1-block" >
</xsl:attribute-set>

<xsl:attribute-set name="toc-level2-block" >
    <xsl:attribute name="start-indent">10mm</xsl:attribute>
</xsl:attribute-set>

<!--etc-->

Format the toc numbers

The format of the numbers for toc entry takes the same format as the section numbers. See section numbers.

Sections

Formatting titles

Use the attribute-sets 'title-level1-block', 'title-level1-block', etc, to format the titles for each section. Docutils to fo allows sections to go 7 levels deep. Headings are blocks and can take any property of a block.

<xsl:attribute-set name="default-section-title-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="keep-with-next">always</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="title-level1-block" use-attribute-sets="default-section-title-block">
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="font-size">16</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="title-level2-block" use-attribute-sets="default-section-title-block">
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="font-size">14</xsl:attribute>
    <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

Creating section numbers

At the start of the document, put:

.. sectnum::

Formatting section numbers

Use the 'parm#' identifier plus the 'number-format' to format the section numbers. The value for formatting can take a combination of punctuation and numbers, letters, or Roman numberals

<xsl:param name="number-section1">1</xsl:param>
<xsl:param name="number-section2">.1</xsl:param>
<xsl:param name="number-section3">.1</xsl:param>
<xsl:param name="number-section4">.1</xsl:param>
<xsl:param name="number-section5">.1</xsl:param>
<xsl:param name="number-section6">.1</xsl:param>
<xsl:param name="number-section7">.1</xsl:param>
<xsl:param name="number-section8">.1</xsl:param>
<xsl:param name="number-section9">.1</xsl:param>

# (I.), (II.), (III.), etc
heading1.number-format = (I.)

# i.), ii.), etc
heading2.number-format = i.)

# .1., .2., .3., etc
heading3.number-format = .1.

# a, b, c, etc
heading4.number-format = a

# A, B, C., etc
heading5.number-format = A

Body Elements

Changing characteristics of paragraphs

<xsl:attribute-set name="paragraph-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Changing characteristics of first paragraphs

<xsl:attribute-set name="first-paragraph-block" use-attribute-sets="paragraph-block">
</xsl:attribute-set>

Block quote

The default template is:

<xsl:template match="block_quote[not(@classes)]">
    <xsl:apply-templates/>
</xsl:template>

To change, (to put space ater, for example):

<xsl:template match="block_quote[not(@classes)]">
    <xsl:apply-templates/>
    <fo:block space-after="24pt"/>
</xsl:template>

<!--or-->

<xsl:template match="block_quote[not(@classes)]">
    <fo:block space-after="24pt">
        <xsl:apply-templates/>
    </fo:block>
</xsl:template>

Changing characteristics of pargraphs in a Quote

Use the block-quote-paragraph-block attribute set:

<xsl:attribute-set name="block-quote-paragraph-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="start-indent">20mm</xsl:attribute>
    <xsl:attribute name="end-indent">20mm</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="block-quote-first-paragraph-block" use-attribute-sets="block-quote-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

Changing characteristics of the attribution for a quote

Use the block-quote-attributeion-block attribute.

<xsl:attribute-set name="block-quote-attribution-block">
    <xsl:attribute name="text-align">right</xsl:attribute>
</xsl:attribute-set>

Literal Block

To change the characteristics of a literal block, use the literal-block attribute set:

<xsl:attribute-set name="literal-block">
    <xsl:attribute name="font-family">monospace</xsl:attribute>
    <xsl:attribute name="font-size">8</xsl:attribute>
    <xsl:attribute name="white-space">pre</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Transition Block

To change the characteristics of a transition block, use the transition-block attribute set:

<xsl:attribute-set name="transition-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>

Document Title

To change the characteristics of the document title, use the document-title-block attribute set:

<xsl:attribute-set name="document-title-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="font-size">24pt</xsl:attribute>
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Document Subtitle

To change the characteristics of the document subtitle, use the document-subtitle-block attribute set:

<xsl:attribute-set name="document-subtitle-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="font-size">18pt</xsl:attribute>
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Bullet List

Formatting the bullet list

Use the attribute set 'bullet-list-block' and 'bullet-level2-list-block' property to format the space after and before, the left and right indent, and any other property you want to set on the list, such as font for font-size:

<xsl:attribute-set name="bullet-list-block" >
    <xsl:attribute name="start-indent">5mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">5mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="bullet-level2-list-block" >
    <xsl:attribute name="start-indent">15mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">5mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

To format space between bullets and text, change the attribute 'provisional-distance-between-starts'.

To format space between items

Use the 'bullet-list-item' and 'bullet-level2-list-item' attribute set.

<xsl:attribute-set name="bullet-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>


<xsl:attribute-set name="bullet-level2-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Choosing the text for the bullet

Use the parameter 'bullet-list' and 'bullet-list-level2' to change the default bullet:

<xsl:param name="bullet-text">&#x2022;</xsl:param>
<xsl:param name="bullet-text-level2">&#x00B0;</xsl:param>

Formatting the paragraphs

Use the 'bullet-list-item-body-block' attribute set to format the text of the bullet list. This identifier can take any block property:

<xsl:attribute-set name="bullet-list-item-body-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Enumerated List

Formatting the enumerated list

Use the attribute set 'enumerated-list-block' and 'enumerated-level2-list-block' property to format the space after and before, the left and right indent, and any other property you want to set on the list, such as font for font-size:

<xsl:attribute-set name="enumerated-list-block" >
    <xsl:attribute name="start-indent">5mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">5mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="enumerated-level2-list-block" >
    <xsl:attribute name="start-indent">15mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">10mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

To format space between enumerateds and text, change the attribute 'provisional-distance-between-starts'.

To format space between items

Use the 'enumerated-list-item' and 'enumerated-level2-list-item' attribute set.

<xsl:attribute-set name="enumerated-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>


<xsl:attribute-set name="enumerated-level2-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

Use the 'enumerated-list-item-body-block' attribute set to format the text of the enumerated list. This identifier can take any block property:

<xsl:attribute-set name="enumerated-list-item-body-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Line Blocks

Formatting the entire line block

Use the 'outer-line-block' attribute-set to format the entire line block. This identifier can take any block property:

<xsl:attribute-set name="outer-line-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the lines

The lines have the attribute-set 'level1-line-block', 'level2-line-block' and so fourth. Each level indicates how many levels the line is nested. Lines may be nesed up to 5 levels deep. It makes sense to set overall properties with the 'outer-line-block' attribute-set, and to use the 'evel#-line-block' to set the indents of for each level:

<xsl:attribute-set name="level1-line-block">
    <xsl:attribute name="start-indent">10mm</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="level2-line-block">
    <xsl:attribute name="start-indent">20mm</xsl:attribute>
</xsl:attribute-set>

Create a stanza title

In order to create a title for a stanza, in the document (not the configuration file) include the line in a title_reference:

| `stanza title 1`
| A one, two, a one two three four
|
| `stanza title 2`
| Half a bee, philosophically,
|     must, *ipso facto*, half not be.
| But half the bee has got to be,
|     *vis a vis* its entity.  D'you see?
|
| `stanza title 3`
| But can a bee be said to be
|     or not to be an entire bee,
|         when half the bee is not a bee,
|             due to some ancient injury?
|
| Singing...

Formatting the stanza title

Use the 'stanza-title-block' attribute-set to format the stanza title:

<xsl:attribute-set name="stanza-title-block">
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="space-before">12</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

You cannot do any formatting with a title reference (the text between the ``). If you need to do inline markup on part of a stanza title, only put the `` around the part that does not need the markup:

| *stanza title* `3`
| But can a bee be said to be

If you need to format the entire stanza title, use the following work around:

.. role:: title

| *stanza title 3* :title:`x`
| But can a bee be said to be
|     or not to be an entire bee,
|         when half the bee is not a bee,
|             due to some ancient injury?

Number lines

In order to number the lines in a verse, import the number_verse.xsl stylehseet, and set the parameter 'number-verse' to the appropriate increment.

<!--numbers every 5th line-->
<xsl:import href="xsl_fo/docutils_to_fo.xsl"/>
<xsl:import href="xsl_fo/custom/number_verse.xsl"/>
<xsl:param name="number-verse">5</xsl:param>

Make numers closer to line

By default, docutils to fo puts the number to the very right of the margin. Set the attribute 'right-indent' to a positive number to make the numbers appear closer to the lines:

<xsl:attribute-set name="outer-line-block">
    <xsl:attribute name="right-indent">20mm</xsl:attribute>
</xsl:attribute-set>

Keeping the lines on the same page

If the line block is relatively short, use the 'keep-on-same-page' property.

<xsl:attribute-set name="outer-line-block">
    <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
</xsl:attribute-set>

If the line block is long, using this property could lead to huge space on a page.

Creating space between stanzas

Use a blank line to control the space between stanzas. There is no othe way to control space. The rst2xml.py utility marks a new set of line blocks when it detects a new indentation. In contrast, real verse is marked by the space between stanzas.

Definition List

Formatting the definition list

Use the attribute set 'definition-list-block' to change the characteristics of the entire definition.

<xsl:attribute-set name="definition-list-block" >
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting space between items

An item consists of both the term and definition. Use the 'definition-list-item-block' attribute set.

<xsl:attribute-set name="definition-list-item-block" >
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the term

Use the 'definition-term-block' to change the properties of the term, such as the space below:

<xsl:attribute-set name="definition-term-block">
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Formatting the definition

The definition can consist of more than one paragraph. To format each of these paragraphs, and the space before or after, use the 'definition-block' attribute set:

<xsl:attribute-set name="definition-block">
</xsl:attribute-set>

Formatting the classifier

Use the 'classifier-inline' attribute set to format the classifier:

<xsl:attribute-set name="classifier-inline">
    <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

The 'definition-list-paragraph' attribute-set formats the parapgraphs in the definition:

<xsl:attribute-set name="definition-paragraph-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="start-indent">30pt</xsl:attribute>
</xsl:attribute-set>

Field List

Formatting the field list

Use the 'field-list-block' attribute set to format the space after and before, the left and right indent, and any other property you want to set on the list, such as font for font-size:

<xsl:attribute-set name="field-list-block" >
    <xsl:attribute name="start-indent">0mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">30mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

To format space between field and text change the 'provisional-distance-between-starts' attribute:

<xsl:attribute name="provisional-distance-between-starts">40mm</xsl:attribute>

format items

Use the 'field-list-items' attribute set.

<xsl:attribute-set name="field-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the field names

Use the 'field-list-item-label-block' attribute-set, which can take any inline properties:

<xsl:attribute-set name="field-list-item-label-block">
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

Use the 'field-body-block' attribute-set to format the text of the bullet list. This identifier can take any block property:

<xsl:attribute-set name="field-body-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Note that using the 'space-before' property has the same effect as controlling the space between each paragraph, without putting unwated space before the first paragraph.

Option List

Formatting the option list format

The option list can either be formatted as a list, with the options as labels to the left of the description; or as a definition list, with the options serving as the terms, and the descriptions in a paragraph right below. For an option list with lenghty options, a definition list may work better.

By default, the stylesheets process the options list as a list. If you wish to format them as a definition list, use the following:

<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.1"
>

    <xsl:import href="xsl_fo/docutils_to_fo.xsl"/>
    <xsl:import href="xsl_fo/custom/option_list_as_definition.xsl"/>

</xsl:stylesheet>

Default (as list)

Choosing the options separator

By default, the docutils to FO convertor uses a comma to separate options. To change the default, use the 'options-separator' parameter:

<xsl:param name="options-separator">| </xsl:param>

Formatting the option list

Use the 'option-list-block' attribute-set to format the space after and before, the left and right indent, and any other property you want to set on the list, such as font for font-size:

<xsl:attribute-set name="option-list-block">
    <xsl:attribute name="start-indent">0mm</xsl:attribute>
    <xsl:attribute name="provisional-distance-between-starts">50mm</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

To format space between option and text, chance the 'provisional-distance-between-starts' attribute:

<xsl:attribute name="provisional-distance-between-starts">40mm</xsl:attribute>

Formating items

Use the 'option-list-item' attribute set.

<xsl:attribute-set name="option-list-item">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the options without the argument

Use the 'option-inline' attribute-set to format only the option without the arguments of the options. This identifier can take any inline properties:

<xsl:attribute-set name="option-inline">
    <xsl:attribute name="font-family">monospace</xsl:attribute>
</xsl:attribute-set>

Formatting the arguments of the options

Use the 'option-argument-inline' attribute-set to format just the option of the arugment. This identifier can take any inline properties:

<xsl:attribute-set name="option-argument-inline">
    <xsl:attribute name="font-family">monospace</xsl:attribute>
    <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

Formatting the description

Use the 'option-list-item-body' attribue set to format the text of the option list.

Formatting the paragraphs

Use the 'option-list-item-body-block' attribute-set to format the text of the list. This identifier can take any block property:

<xsl:attribute-set name="option-list-item-body-block">
</xsl:attribute-set>

Note that using the 'space-before' property has the same effect as controlling the space between each paragraph, without putting unwated space before the first paragraph.

As definition list

Formatting the option list

Use the 'option-list-definition-block' to format the entire option list:

<xsl:attribute-set name="option-list-definition-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting each item

Use the attribute-set 'option-list-item-block'.

<xsl:attribute-set name="option-list-item-block">
    <xsl:attribute name="space-before">8pt</xsl:attribute>
</xsl:attribute-set>

Formatting the options

Use the 'option-group-block' attribute set:

<xsl:attribute-set name="option-group-block">
    <xsl:attribute name="keep-with-next">always</xsl:attribute>
</xsl:attribute-set>

Formatting the description

The description contains one or more paragraphs. To format all of these at once, use the 'option-list-description-block' attribute set:

<xsl:attribute-set name="option-list-description-block">
    <xsl:attribute name="start-indent">16pt</xsl:attribute>
    <xsl:attribute name="space-before">8pt</xsl:attribute>
</xsl:attribute-set>

Fomratting the paragraphs in the description

Use the 'option-list-paragraph-block':

<xsl:attribute-set name="option-list-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

Formatting the options without the argument

Use the 'option-inline' attribute-set. (See above for the default section.)

Formatting the arguments of the options

Use the 'option-argument-inline' attribute-set. (See above in the default section.)

Inline

emphasis

Use the emphasis-inline attribute set to change the default behavior of the emphsis element.

<xsl:template match="emphasis">
    <fo:inline xsl:use-attribute-sets="emphasis-inline">
        <xsl:apply-templates/>
    </fo:inline>
</xsl:template>

strong

<xsl:attribute-set name="strong-inline" >
    <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

reference

<xsl:attribute-set name="basic-link-inline" >
    <xsl:attribute name="text-decoration">underline</xsl:attribute>
    <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

literal

<xsl:attribute-set name="literal-inline">
    <xsl:attribute name="font-family">monospace</xsl:attribute>
    <xsl:attribute name="font-size">8</xsl:attribute>
    <xsl:attribute name="white-space">pre</xsl:attribute>
</xsl:attribute-set>

title-reference

<xsl:attribute-set name="title-reference-inline" >
    <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

Admonitions

Titles

Each admonishment has its own title formed by the following parameters:

<xsl:param name="attention-title">Attention!</xsl:param>
<xsl:param name="caution-title">Caution!</xsl:param>
<xsl:param name="danger-title">!Danger!</xsl:param>
<xsl:param name="error-title">Error</xsl:param>
<xsl:param name="hint-title">Hint</xsl:param>
<xsl:param name="important-title">Important</xsl:param>
<xsl:param name="note-title">Note</xsl:param>
<xsl:param name="tip-title">Tip</xsl:param>
<xsl:param name="warning-title">Warning!</xsl:param>

To change the default titles, simply change the parameters.

Formating the the title blocks

Each title block inherits its property from the default-admonition-title-block attribute-set.

<xsl:attribute-set name="default-admonition-title-block">
    <xsl:attribute name="space-after">10pt</xsl:attribute>
    <xsl:attribute name="font-size">larger</xsl:attribute>
    <xsl:attribute name="color">red</xsl:attribute>
</xsl:attribute-set>

The attribute sets for each admonition tite, are logically the name, followed by the string 'title-block'.

<xsl:attribute-set name="attention-title-block" use-attribute-sets="default-admonition-title-block">
</xsl:attribute-set>

The exact names are:

  • attention-title-block
  • caution-title-block
  • danger-title-block
  • error-title-block
  • hint-title-block
  • important-title-block
  • note-title-block
  • tip-title-block
  • admonition-custom-title-block
  • warning-title-block

Formating the the admonition blocks

Each admonition is wrapped in a block. Each block inherits its characteristics from the default:

<xsl:attribute-set name="default-admonition-outer-block">
    <xsl:attribute name="border-style">solid</xsl:attribute>
    <xsl:attribute name="border-width">1px</xsl:attribute>
    <xsl:attribute name="padding">6pt</xsl:attribute>
    <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
</xsl:attribute-set>

Changing the attributes in this attribute set changes them for all admonitions.

Each admonition has its own attribute-set, the name of the admonition followed by the string '-block.':

<xsl:attribute-set name="attention-block" use-attribute-sets="default-admonition-outer-block">
</xsl:attribute-set>

<xsl:attribute-set name="caution-block" use-attribute-sets="default-admonition-outer-block">
</xsl:attribute-set>

<!--etc-->

The names of these blocks are:

  • attention-block
  • caution-block
  • danger-block
  • error-block
  • hint-block
  • important-block
  • note-block
  • tip-block
  • admonition-custom-block
  • warning-block

Formatting the paragraphs within the admonition block

Use the attribute-set admonition-paragraphs-block to format paragraphs:

<xsl:attribute-set name="admonition-paragraph-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Body Directives

topic

Formatting the complete block

<xsl:attribute-set name="topic-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the title

<xsl:attribute-set name="topic-title-block">
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Rubric

<xsl:attribute-set name="rubric-block">
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="font-size">larger</xsl:attribute>
    <xsl:attribute name="color">red</xsl:attribute>
</xsl:attribute-set>

Epigraph

Formatting the complete block

<xsl:attribute-set name="epigraph-outer-block">
    <xsl:attribute name="start-indent">20mm</xsl:attribute>
    <xsl:attribute name="end-indent">20mm</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="text-align">right</xsl:attribute>
    <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

<xsl:attribute-set name="epigraph-paragraph-block">
    <xsl:attribute name="start-indent">inherit</xsl:attribute>
    <xsl:attribute name="end-indent">inherit</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the attribution

<xsl:attribute-set name="epigraph-attribution-block">
    <xsl:attribute name="text-align">right</xsl:attribute>
</xsl:attribute-set>

Highlights

Formatting the complete block

<xsl:attribute-set name="highlights-outer-block">
    <xsl:attribute name="start-indent">20mm</xsl:attribute>
    <xsl:attribute name="end-indent">20mm</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

<xsl:attribute-set name="highlights-paragraph-block">
    <xsl:attribute name="start-indent">inherit</xsl:attribute>
    <xsl:attribute name="end-indent">inherit</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Pull Quotes

Formatting the complete block

<xsl:attribute-set name="pull-quote-paragraph-block">
    <xsl:attribute name="start-indent">inherit</xsl:attribute>
    <xsl:attribute name="end-indent">inherit</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

<xsl:attribute-set name="pull-quote-first-paragraph-block" use-attribute-sets="block-quote-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

Formatting the attribution

<xsl:attribute-set name="pull-quote-attribution-block">
    <xsl:attribute name="text-align">right</xsl:attribute>
</xsl:attribute-set>

Container

Formatting the complete block

<xsl:attribute-set name="container-outer-block">
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs

<xsl:attribute-set name="container-paragraph-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Math

Formatting the complete block

The math block does not consist of paragraphs. It either consists of literal text, or MathML markup. To format the contents in either case:

<xsl:attribute-set name="mathml-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Images and Figures

An image conssits of just the image. A figure consists of the image, with an option for alternative text, a caption, and a legend. The legend can consist of body elements, such as paragraphs or a table.

Attribute sets for Images and Figures. The image property of alt and target are ignored by the stylesheets, since they have no use in PDF. In addtion, if the align is set to top or bottom, both properties that have no meaning for PDF, the stylesheets will report an error, and if strict is set to true, quit.

Likwise, the figure figwidth property will be ignored, since there is not way to implement this property directy in FO.

In order to control the scaling, alignment, and width of images and figures, it is better to use the attribute sets than to try to set these properties in RST. The regions of 'image', 'figure', 'caption', and 'legend' are all wrapped in blocks. Use the attribute sets for these blocks to control the properties.

Formatting the entire figure block

<xsl:attribute-set name="figure-block">
</xsl:attribute-set>

Formatting the entire caption block

<xsl:attribute-set name="figure-caption-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:attribute name="font-size">smaller</xsl:attribute>
    <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>

Formatting the entire legend block

<xsl:attribute-set name="figure-legend-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs in the legend block

<xsl:attribute-set name="legend-paragraph-block">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
</xsl:attribute-set>

Formatting the first paragraph in the legend block

<xsl:attribute-set name="legend-first-paragraph-block" use-attribute-sets="legend-paragraph-block">
    <xsl:attribute name="space-before">0pt</xsl:attribute>
</xsl:attribute-set>

Formatting the entire image block

The image block contains no text or othe elements. None-the-less, it is wrapped in a block that allows formatting, including space before or after, alignment, and borders.

::
<xsl:attribute-set name="image-block"> </xsl:attribute-set>

Tables

Use the attribute-set table-block-container to format all the characteristics of a table.

<xsl:attribute-set name="table-block-container">
    <xsl:attribute name="space-before">12pt</xsl:attribute>
    <xsl:attribute name="space-after">12pt</xsl:attribute>
</xsl:attribute-set>

Changing the widths of the columns

The formatter uses the columns values generated by the rst2xml.py script to determine the width of the columns. In order to change this default, re-write the table template:

<!--sets the second two columns to twice the first column-->
<xsl:template match="table[not(@classes)]/tgroup">
    <fo:table-column column-number="1" column-width="proportional-column-width(5)"/>
    <fo:table-column column-number="2" column-width="proportional-column-width(10)"/>
    <fo:table-column column-number="3" column-width="proportional-column-width(10)"/>
    <xsl:apply-templates/>
</xsl:template>

Formatting captions

<xsl:attribute-set name="caption-block">
    <xsl:attribute name="text-align">center</xsl:attribute>
    <xsl:attribute name="space-before">6pt</xsl:attribute>
    <xsl:attribute name="space-after">6pt</xsl:attribute>
</xsl:attribute-set>

Placement of the caption

Use the parameter to place the the caption either at the top or bottom of the table:

<!--changes placement of caption to top of table-->
<xsl:param name="table-title-placement">bottom</xsl:param>

Formatting the table header

To format all of the cells in the header, use the table-header attribute-set.

<xsl:attribute-set name="table-header">
    <!--increases font size-->
    <xsl:attribute name="font-size">14/xsl:attribute>
</xsl:attribute-set>

Formatting the table header cells

Use the 'table-header-cell' attribute-set to format the cells in the heading. Note that this attribute set inherits the propertis of the default-cell attribute set (shown below).

<xsl:attribute-set name="table-header-cell" use-attribute-sets="default-cell">
    <xsl:attribute name="border-bottom">solid black 2px</xsl:attribute>
</xsl:attribute-set>

Formatting the paragraphs in the table header

<xsl:attribute-set name="table-header-block">
</xsl:attribute-set>

Formatting the table body

Use the table-body attribute-set to format all of the table body:

<xsl:attribute-set name="table-body">
</xsl:attribute-set>

Fromatting the rows

The attribute-set table-row formats the table row. Note that the defaults has the attribute "keep-together.within-page" set to "always" so that rows do not split across pages.

<xsl:attribute-set name="table-row">
    <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
</xsl:attribute-set>

Formatting the cells in the body

The cells are formatted with the table-cell attribute-set. This attribute set inherits its properties from the default-table-cell.

<xsl:attribute-set name="table-cell" use-attribute-sets="default-cell">
</xsl:attribute-set>

<xsl:attribute-set name="default-cell">
    <xsl:attribute name="border">solid black 1px</xsl:attribute>
    <xsl:attribute name="padding">1em</xsl:attribute>
    <xsl:attribute name="border-collapse">collapse</xsl:attribute>
</xsl:attribute-set>
View document source. Generated on: 2012-01-03 12:42 UTC. Generated by Docutils from reStructuredText source.