Creating presentations using restructured text

Suppose you are a nerd. Specifically, an open-source-using nerd.

Who am I kidding, you are reading my blog, of course you are an open-source-using nerd.

Let's try again: you are an open-source-using nerd who needs to do a presentation at your local LUG/programming language conference/Linux event/bar mitzvah.

In that case, you probably want to show some slides. I am here to help you create your slides the nerd way.

A regular guy would do them using, say, PowerPoint or a similar program like OOo's Impress

However, since you are who you are, you know there are problems in that direction.

  1. How do you keep a versioned history of such documents? (Yes, they are XML now. It's compressed so, unless you want to version-control the uncompressed... forget it, it's awful)
  2. If you use one of those, and you have to use someone else's computer, he is bound to have installed the other.
  3. You will feel dirty inside.
  4. It's not at all like programming. You like programming.
  5. It's completely separate from creating, for example, a handout, or a larger document that complements the slides.

So, let's get unconventional. There are a bunch of presentation tools that don't have those problems, from MagicPoint to Prosper (or Beamer), to Tobogan [1], to s5 and others.

All of them would be cool for you. But I think you can do better, because there are problems with them.

  • LaTeX (used with prosper or beamer): well, you need to know LaTeX. If you want code syntax highlighting you need another package. If you want to use your pet TT font it's not obvious, and the results are... not very inspiring for the amount of noise. Here's how you create a slide with four items in it in beamer:

    \section{Section no. 2}
    \subsection{Lists I}
    \begin{frame}\frametitle{unnumbered lists}
    \item Introduction to  \LaTeX
    \item Course 2
    \item Termpapers and presentations with \LaTeX
    \item Beamer class

    Personally I prefer my markup lighter.

  • MagicPoint: needs manuals. Really, really needs manuals. Also, it will create your slides, and nothing else.

  • s5: looks dead. It's nicer with rst2s5.

And of course, the killer argument: if I were to recommend you use one of those, I wouldn't have bothered writing this!

So, let's go to what I will do for my next conference: I will use a PDF. Specifically, I will use a PDF I built using rst2pdf [2]

If you are not familiar with reStructured Text by all means follow that link and get acquainted, because it's the bet thing since sliced bread [3] [4] [5] .

So, how do you create slides using rst2pdf? It's very simple. So simple, I will use an example file.

This is my first slide

* It has, of course, items in it

* More than one item

    1. Numbered lists, too

This is my second slide

rst2pdf can display code nicely:

.. code-block:: python

    for x in range(7):
        print "cute!"

This is my third slide

Also, you can use math!

.. math::

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

That is *not* an image.

This is my 4th slide

Other features include:

* Images, including SVG

* Tables

* Font embedding (Type1 and TTF)

* Extensible

* Background (like this one)

* Page transitions

.. header::

        Rst2pdf Slide Demo

.. footer::

        © Roberto Alsina, 2009

Now, that was not all that hard to grasp, was it? And what's the result?

Here is the file seen in oKular:


And here you can get the PDF file for yourself.

Of course, you are noticing things in that image or PDF that are not in the code I posted above, like "where is the background coming from?" or "Where did he specify that funky aspect ratio?".

Well, the answer is this stylesheet:

{"pageSetup": {
    "width": "16cm",
    "height": "9cm",
    "margin-top": "0cm",
    "margin-bottom": "0cm",
    "margin-left": "0cm",
    "margin-right": "0cm",
    "margin-gutter": "0cm",
    "spacing-header": "5mm",
    "spacing-footer": "5mm",
    "firstTemplate": "cutePage"
"pageTemplates" : {
    "cutePage": {
        "frames": [
            ["10%", "10%", "80%", "80%"]
        "background" : "background.svg"

The background.svg is done with inkscape.

And to go from these files to the PDF, this is the command:

rst2pdf slides.txt -b1 -s

The -b1 is so there is a page break after each section (that would be just before each title).

You can show this PDF file with any PDF viewer, but I like Okular's presentation mode a lot, and if you want fancy, you could try Impressive.

Impressive can do neat page transitions, but if you like them [6] and prefer to use another PDF viewer, you can use rst2pdf's page transition support by adding something like this at the end of each section:

.. raw:: pdf

   Transition Split 1 90 I

I won't tell you what that means, only aim you in the general direction of the FM

And that's it. There's your slideshow.

If you want to add things like a nice handout where you mix one slide / one page of text, that's not hard to do, but I wil leave it as an exercise to the reader.

And if you use this... let me know!

[1] jaja, no, you didn't know that one. Only I know it because I wrote it. But don't worry, we will not be using it today.
[2] Yes, I wrote most of rst2pdf. No, I am not impartial about it in any way. It's my baby!
[3] Hell, have you ever tried documenting a server using sliced bread? It's hard!
[4] It also means you are 90% there about learning how to use Sphinx.
[5] In fact, what's so awesome about sliced bread? It's 4 times more expensive as tastier, crusty, yummy bread.
[6] Why? They are so 1997!