ABSOLUTELY NO WARRANTY | free software

# find

1   Introduction

This document explains how to use rst2pdf. Here is the very short version:

rst2pdf.py mydocument.txt -o mydocument.pdf

That will, as long as mydocument.txt is a valid Restructured Text (ReST) document, produce a file called mydocument.pdf which is a PDF version of your document.

Of course, that means you just used default styles and settings. If it looks good enough for you, then you may stop reading this document, because you are done with it. If you are reading this in a PDF, it was generated using those default settings.

However, if you want to customize the output, or are just curious to see what can be done, let´s continue.

2   Command line options

Some of these options' defaults can be changed by creating a configuration file

3   Configuration File

Since version 0.8, rst2pdf will read (if it is available) configuration files in /etc/rst2pdf.conf and ~/.rst2pdf/config.

The user's file at ~/.rst2pdf/config will have priority over the system's at /etc/rst2pdf.conf [1]

Here's an example file showing some of the currently available options:

# This is an example config file. Modify and place in ~/.rst2pdf/config

[general]
# A comma-separated list of custom stylesheets. Example:
# stylesheets="fruity.json,a4paper.json,verasans.json"
stylesheets=""

# Create a compressed PDF
# Use true/false (lower case) or 1/0
# Example: compressed=true
compressed=false

# A colon-separated list of folders to search for fonts. Example:
# font_path="/usr/share/fonts:/usr/share/texmf-dist/fonts/"
font_path=""

# Language to be used for hyphenation support
language="en_US"

# Default page header and footer
header=None
footer=None

# What to do if a literal block is too large. Can be
# shrink/truncate/overflow
fit_mode="shrink"

# What is the maximum level of heading that starts in a new page.
# 0 means no level starts in a new page.
break_level=0

Included with rst2pdf is an example file with every option in it.

4   Pipe usage

If no input nor output are provided, stdin and stdout will be used respectively

You may want to use rst2pdf in a linux pipe as such:

cat readme.txt | rst2pdf | gzip -c > readme.pdf.gz

or:

curl http://docutils.sourceforge.net/docs/user/rst/quickstart.txt | rst2pdf > quickstart.pdf

If no input argument is provided, stdin will be used:

cat readme.txt | rst2pdf -o readme.pdf

If outpufile is set to dash '-', output goes to stdout:

rst2pdf -o - readme.txt > output.pdf

5   Headers and Footers

ReST supports headers and footers, using the header and footer directive:

.. header::

   This will be at the top of every page.

Often, you may want to put a page number there, or a section name.The following magic tokens will be replaced (More will be added as rst2pdf evolves):

###Page###

Replaced by the current page number.

###Title###

Replaced by the document title

###Section###

Replaced by the currect section title

###SectNum###

Replaced by the currect section number. Important: You must use the sectnum directive for this to work.

Headers and footers are visible by default but they can be disabled by specific Page Templates for example, cover pages. You can also set headers and footers via command line options or the configuration file.

6   Footnotes

Currently rst2pdf doesn't support real footnotes, and converts them to endnotes. There is a real complicated technical reason for this: I can't figure out a clean way to do it right.

You can get the same behaviour as with rst2html by specifying --inline-footnotes, and then the footnotes will appear where you put them (in other words, not footnotes, but "in-the-middle-of-text-notes" or just plain notes.)

7   Images

This |biohazard| means you have to run.

.. |biohazard| image:: ../rst2pdf/tests/input/images/biohazard.png

.. image:: home.png
   :width: 3in

.. image:: home.png
   :width: 80%

.. image:: home.png
   :width: 7cm

8   Styles

You can style paragraphs with a style using the class directive:

.. class:: special

This paragraph is special.

This one is not.

Or inline styles using custom interpreted roles:

.. role:: redtext

I like color :redtext:`red`.

For more information about this, please check the ReST docs.

The only special thing about using rst2pdf here is the syntax of the stylesheet.

You can make rst2pdf print the default stylesheet:

rst2pdf --print-stylesheet

If you want to add styles, just create a stylesheet, (or take the standard stylesheet and modify it) and pass it with the -s option:

rst2pdf mydoc.txt -s mystyles.txt

Those styles will always be searched in these places, in order:

• What you specify using --stylesheet_path
• The option stylesheet_path in the config file
• The current folder
• ~/.rst2pdf/styles
• The styles folder within rst2pdf's installation folder.

You can use multiple -s options, or pass more than one stylesheet separated with commas. They are processed in the order you give them so the last one has priority.

rst2pdf mydoc.txt -s twocolumn,serif,murphy,legal

"fontsAlias" : {
  "stdFont": "Helvetica",
  "stdBold": "Helvetica-Bold",
  "stdItalic": "Helvetica-Oblique",
  "stdBoldItalic": "Helvetica-BoldOblique",
  "stdMono": "Courier"
},

["normal" , {
  "parent": "base"
}],

"fontName":"Times-Roman",
"fontSize":10,
"leading":12,
"leftIndent":0,
"rightIndent":0,
"firstLineIndent":0,
"alignment":TA_LEFT,
"spaceBefore":0,
"spaceAfter":0,
"bulletFontName":"Times-Roman",
"bulletFontSize":10,
"bulletIndent":0,
"textColor": black,
"backColor":None,
"wordWrap":None,
"borderWidth": 0,
"borderPadding": 0,
"borderColor": None,
"borderRadius": None,
"allowWidows": 1,
"allowOrphans": 0

["normal" , {
  "fontName" : "fonty"
}]

/usr/share/texmf-dist/fonts/type1/urw/palatino/uplb8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplbi8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplr8a.pfb
/usr/share/texmf-dist/fonts/type1/urw/palatino/uplri8a.pfb
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplb8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplbi8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplr8a.afm
/usr/share/texmf-dist/fonts/afm/urw/palatino/uplri8a.afm

rst2pdf mydoc.txt -s mystyle.style --font-path /usr/share/texmf-dist/fonts

[ "title", { "fontName" : "URWPalladioL-Bold" } ]

'ITC Bookman'            : 'URW Bookman L',
'ITC Avant Garde Gothic' : 'URW Gothic L',
'Palatino'               : 'URW Palladio L',
'New Century Schoolbook' : 'Century Schoolbook L',
'ITC Zapf Chancery'      : 'URW Chancery L'

"embeddedFonts" : [ ],

"embeddedFonts" : [ "Tuffy" ],

"embeddedFonts" : [ ["Tuffy.ttf","Tuffy_Bold.ttf","Tuffy_Italic.ttf","Tuffy_Bold_Italic.ttf"] ],

"embeddedFonts" : [ ["Tuffy.ttf","Tuffy.ttf","Tuffy.ttf","Tuffy.ttf"] ],

"fontsAlias" : {
  "stdFont": "Tuffy",
  "stdBold": "Tuffy_Bold",
  "stdItalic": "Tuffy_Italic",
  "stdBoldItalic": "Tuffy_Bold_Italic",
  "stdMono": "Courier"
},

["heading1" , {
  "parent": "normal",
  "fontName": "Tuffy_Bold",
  "bulletFontName": "Tuffy_Bold",
  "fontSize": 18,
  "bulletFontSize": 18,
  "leading": 22,
  "keepWithNext": true,
  "spaceAfter": 6
}],

"pageSetup" : {
  "size": "A4",
  "width": null,
  "height": null,
  "margin-top": "2cm",
  "margin-bottom": "2cm",
  "margin-left": "2cm",
  "margin-right": "2cm",
  "spacing-header": "5mm",
  "spacing-footer": "5mm",
  "margin-gutter": "0cm"
},

{
    "pageSetup" : {
        "size": "A5",
    },
    "fontsAlias" : {
        "stdFont": "Times-Roman",
    },
    "styles" : [
        ["normal" , {
        "fontSize": 14
        }]
    ]
}

9   Syntax Highlighting

.. code-block:: python

    def myFun(x,y):
        print x+y

def myFun(x,y):
    print x+y

rst2pdf mydoc.rst -o mydoc.pdf -s mystyle.json,murphy

>>> my_string="python is great"
>>> my_string.find('great')
10
>>> my_string.startswith('py')
True

Traceback (most recent call last):
    File "error.py", line 9, in ?
    main()
    File "error.py", line 6, in main
    print call_error()
    File "error.py", line 2, in call_error
    r = 1/0
ZeroDivisionError: integer division or modulo by zero
Exit 1

.. code-block:: python
   :include: setup.py

.. code-block:: python
   :include: ../rst2pdf/flowables.py
   :start-at: class Separation(Flowable):
   :end-before: class Reference(Flowable):

10   Raw Directive

Rst2pdf has a very limited mechanism to pass commands to reportlab, the PDF generation library. You can use the raw directive to insert pagebreaks and spacers (other reportlab flowables may be added if there's interest), and set page transitions.

The syntax is shell-like, here's an example:

One page

.. raw:: pdf

    PageBreak

Another page. Now some space:

.. raw:: pdf

    Spacer 0,200
    Spacer 0 200

And another paragraph.

The unit used by the spacer by default is points, and using a space or a comma is the same thing in all cases.

.. raw:: pdf

   Transition effect duration [optional arguments]

.. raw:: pdf

   Transition Glitter 3 90

.. raw:: pdf

   Transition Dissolve 1
   PageBreak

11   Mathematics

If you have Matplotlib installed, rst2pdf supports a math role and a math directive. You can use them to insert formulae and mathematical notation in your documents using a subset of LaTeX syntax, but doesn't require you have LaTeX installed.

For example, here's how you use the math directive:

.. math::

   \frac{2 \pm \sqrt{7}}{3}

And here's the result:

.. math::

   \frac{2 \pm \sqrt{7}}{3}

If you want to insert mathematical notation in your text like this: :math:`\pi` that is the job of the math role:

This is :math:`\pi`

Produces: This is :math:`\pi`

Currently, the math role is slightly buggy, and in some cases will produce misaligned and generally broken output. Also, while the math directive embeds fonts and draws your formula as text, the math role embeds an image. That means:

• You can't copy the text of inline math
• Inline math will look worse when printed, or make your file larger.

So, use it only in emergencies ;-)

You can also use an inline substitution of the math directive for things you use often, which is the same as using the math role:

This is the square of x: |xsq|

.. |xsq| math:: x^2

This is the square of x: |xsq|

math:: x^2

.. |xsq| math:: x^2

You don't need to worry about fonts, the correct math fonts will be used and embedded in your PDF automatically (they are included with matplotlib).

For an introduction to LaTeX syntax, see the "Typesetting Mathematical Formulae" chapter in "The Not So Short Introduction to LaTeX 2e":

http://www.tex.ac.uk/tex-archive/info/lshort/english/lshort.pdf

Basically, the inline form $a^2$ is similar to the math role, and the display form is similar to the math directive.

Rst2pdf doesn't support numbering equations yet.

12   Hyphenation

If you want good looking documents, you want to enable hyphenation.

To do it, you need to install Wordaxe [2].

If after installing it you get the letter "s" or a black square instead of a hyphen, that means you need to replace the rl_codecs.py file from reportlab with the one from wordaxe.

For more information, see this issue in rst2pdf's bug tracker.

Also, you may need to set hyphenation to true in one or more styles, and the language for hyphenation via the command line or paragraph styles.

For english, this should be enough:

["bodytext" , {
  "alignment": "TA_JUSTIFY",
  "hyphenation": true
}],

If you are not an english speaker, you need to change the language.

You can use the -l or --language option. The currently available dictionaries for wordaxe are:

• de_DE
• da
• en_GB
• en_US
• ru

However, since Wordaxe version 0.2.6, it can use the PyHyphen library if it's available. PyHyphen can use any OpenOffice dictionary, and can even download them automatically. [3]

For example, this will enable german hyphenation globally:

rst2pdf -l de_DE mydocument.txt

If you are creating a multilingual document, you can declare styles with specific languages. For example, you could inherit bodytext for german:

["bodytext_de" , {
  "parent": "bodytext",
  "alignment": "TA_JUSTIFY",
  "hyphenation": true,
  "language": "de_DE"
}],

And all paragraps declared of bodytext_de style would have german hyphenation:

.. class:: bodytext_de

Ein Vierteljahrhundert hindurch hatte ich Kopf, Herz, Hand und--Füße der
Schilderung der Alpenwelt und ihrer Bewohner gewidmet mit dem
erfreulichen Erfolg, daß die deutsche Leserwelt es gewöhnt geworden war,
beim Anblick meines Namens auf Büchern sofort an die--Alpen zu denken.

Here is the result (made thinner to force hyphenation):

Ein Vierteljahrhundert hindurch hatte ich Kopf, Herz, Hand und--Füße der Schilderung der Alpenwelt und ihrer Bewohner gewidmet mit dem erfreulichen Erfolg, daß die deutsche Leserwelt es gewöhnt geworden war, beim Anblick meines Namens auf Büchern sofort an die--Alpen zu denken.

BTW: I have no idea what that says, I just copied it from project Gutenberg. Hopefully it's not offensive :-)

If you explicitly configure a language in a paragraph style and also pass a language in the command line, the style has priority, so remember:

13   Page Layout

By default, your document will have a single column of text covering the space between the margins. You can change that, though, in fact you can do so even in the middle of your document!

To do it, you need to define Page Templates in your stylesheet. The default stylesheet already has 3 of them:

"pageTemplates" : {
  "coverPage": {
      "frames": [
          ["0cm", "0cm", "100%", "100%"]
      ],
      "showHeader" : false,
      "showFooter" : false
  },
  "oneColumn": {
      "frames": [
          ["0cm", "0cm", "100%", "100%"]
      ]
  },
  "twoColumn": {
      "frames": [
          ["0cm", "0cm", "49%", "100%"],
          ["51%", "0cm", "49%", "100%"]
      ]
  }
}

A page template has a name (oneColumn, twoColumn), some options, and a list of frames. A frame is a list containing this:

[ left position, top position, width, height ]

For example, this defines a frame "at the very left", "at the very top", "a bit less than half a page wide" and "as tall as possible":

["0cm", "0cm", "49%", "100%"]

And this means "the bottom third of the page":

["0cm", "66.66%", "100%", "33.34%"]

You can use all the usual units, cm, mm, inch, and % which means "percentage of the page (excluding margins and headers or footers)". Using % is probably the smartest for columns and gives you a fluid layout, while the other units are better for more "fixed" elements.

Since we can have more than one template, there is a way to specify which one we want to use, and a way to change from one to another.

To specify the first template, do it in your stylesheet, in pageSetup (oneColumn is the default):

"pageSetup" : {
  "firstTemplate": "oneColumn"
}

Then, to change to another template, in your document use this syntax (will change soon, though):

.. raw:: pdf

   PageBreak twoColumn

That will trigger a page break, and the new page will use the twoColumn template.

You can see an example of this in the Montecristo folder in the source package.

The supported page template options and their defaults are:

• showHeader : True

• defaultHeader : None

  Has the same effect as the header directive in the document.

• showFooter : True

• defaultFooter : None

  Has the same effect as the footer directive in the document.

• background: None

  The background should be an image, which will be stretched to match your page, so use with caution.

14   Smart Quotes

Quoted from the smartypants documentation:

This feature can perform the following transformations:

Straight quotes ( " and ' ) into "curly" quote HTML entities Backticks-style quotes (``like this'') into "curly" quote HTML entities Dashes (-- and ---) into en- and em-dash entities Three consecutive dots (... or . . .) into an ellipsis entity This means you can write, edit, and save your posts using plain old ASCII straight quotes, plain dashes, and plain dots, but your published posts (and final PDF output) will appear with smart quotes, em-dashes, and proper ellipses.

You can enable this by passing the --smart-quotes option in the command line. By default, it's disabled. Here are the different values you can use (again, from the smartypants docs):

0

Suppress all transformations. (Do nothing.)

1

Performs default SmartyPants transformations: quotes (including ``backticks'' -style), em-dashes, and ellipses. "--" (dash dash) is used to signify an em-dash; there is no support for en-dashes.

2

Same as smarty_pants="1", except that it uses the old-school typewriter shorthand for dashes: "--" (dash dash) for en-dashes, "---" (dash dash dash) for em-dashes.

3

Same as smarty_pants="2", but inverts the shorthand for dashes: "--" (dash dash) for em-dashes, and "---" (dash dash dash) for en-dashes.

Currently, even if you enable it, this transformation will only take place in regular paragraphs, titles, headers, footers and block quotes.

In addition, there is currently an incompatibility between this and wordaxe's pyhyphen plugin, so it's not really usable in some cases.