Creating presentations using restructured text

Sup­pose you are a nerd. Specif­i­cal­ly, an open-­source-us­ing nerd.

Who am I kid­ding, you are read­ing my blog, of course you are an open-­source-us­ing nerd.

Let’s try again: you are an open-­source-us­ing nerd who needs to do a pre­sen­ta­tion at your lo­cal LUG/pro­gram­ming lan­guage con­fer­ence/Lin­ux even­t/bar mitz­vah.

In that case, you prob­a­bly want to show some slides. I am here to help you cre­ate your slides the nerd way.

A reg­u­lar guy would do them us­ing, say, Pow­er­Point or a sim­i­lar pro­gram like OOo’s Im­press

How­ev­er, since you are who you are, you know there are prob­lems in that di­rec­tion.

  1. How do you keep a ver­sioned his­to­ry of such doc­u­ments? (Yes, they are XML now. It’s com­pressed so, un­less you want to ver­sion-­con­trol the un­com­pressed… for­get it, it’s aw­ful)
  2. If you use one of those, and you have to use some­one else’s com­put­er, he is bound to have in­stalled the oth­er.
  3. You will feel dirty in­sid­e.
  4. It’s not at all like pro­gram­ming. You like pro­gram­ming.
  5. It’s com­plete­ly sep­a­rate from cre­at­ing, for ex­am­ple, a hand­out, or a larg­er doc­u­ment that com­ple­ments the slides.

So, let’s get un­con­ven­tion­al. There are a bunch of pre­sen­ta­tion tools that don’t have those prob­lem­s, from Mag­ic­Point to Pros­per (or Beam­er), to To­bo­gan [1], to s5 and oth­er­s.

All of them would be cool for you. But I think you can do bet­ter, be­cause there are prob­lems with them.

  • La­­TeX (used with pros­per or beam­er): well, you need to know La­­TeX. If you want code syn­­tax high­­­light­ing you need an­oth­er pack­­age. If you want to use your pet TT font it’s not ob­vi­ous, and the re­­sults are… not very in­­spir­ing for the amount of noise. Here’s how you cre­ate a slide with four items in it in beam­er:

     \sec­tion{Sec­tion no. 2} 
     \sub­sec­tion{Lists I} 
     \be­gin{frame}\fram­eti­tle{un­num­bered lists} 
     \item  In­tro­duc­tion to   \La­TeX 
     \item  Course 2
     \item  Termpa­pers and pre­sen­ta­tions with  \La­TeX 
     \item  Beam­er class

    Per­­son­al­­ly I pre­fer my markup lighter.

  • Mag­ic­­Point: needs man­u­al­s. Re­al­­ly, re­al­­ly needs man­u­al­s. Al­­so, it will cre­ate your slides, and noth­ing else.

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

And of course, the killer ar­gu­men­t: if I were to rec­om­mend you use one of those, I would­n’t have both­ered writ­ing this!

So, let’s go to what I will do for my next con­fer­ence: I will use a PDF. Specif­i­cal­ly, I will use a PDF I built us­ing rst2pdf [2]

If you are not fa­mil­iar with re­Struc­tured Text by all means fol­low that link and get ac­quaint­ed, be­cause it’s the bet thing since sliced bread [3] [4] [5] .

So, how do you cre­ate slides us­ing rst2pdf? It’s very sim­ple. So sim­ple, I will use an ex­am­ple 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 re­sult?

Here is the file seen in oKu­lar:


And here you can get the PDF file for your­self.

Of course, you are notic­ing things in that im­age or PDF that are not in the code I post­ed above, like “where is the back­ground com­ing from?” or “Where did he spec­i­fy that funky as­pect ra­tio?”.

Well, the an­swer 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 back­ground.svg is done with inkscape.

And to go from these files to the PDF, this is the com­mand:

rst2pdf slides.txt -b1 -s

The -b1 is so there is a page break af­ter each sec­tion (that would be just be­fore each ti­tle).

You can show this PDF file with any PDF view­er, but I like Oku­lar’s pre­sen­ta­tion mode a lot, and if you want fan­cy, you could try Im­pres­sive.

Im­pres­sive can do neat page tran­si­tion­s, but if you like them [6] and pre­fer to use an­oth­er PDF view­er, you can use rst2pdf’s page tran­si­tion sup­port by adding some­thing like this at the end of each sec­tion:

.. raw:: pdf

   Transition Split 1 90 I

I won’t tell you what that mean­s, on­ly aim you in the gen­er­al di­rec­tion of the FM

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

If you want to add things like a nice hand­out where you mix one slide / one page of tex­t, that’s not hard to do, but I wil leave it as an ex­er­cise to the read­er.

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!


Comments powered by Disqus
Contents © 2000-2013 Roberto Alsina