reStructured Text tips and tricks

I have been using rst for a good long while now, and this is what I've found to work. I use vim as my editor.

Taking notes in class

I use rst to take notes in all my classes. It started by taking notes with only knowing a few simple rst commands and directives. I knew enough to do headings and bulleted lists.

I first started in my religion class. My teacher did not use powerpoint, and hardly ever wrote anything on the board. His tests cover what is talked about during lecture. Taking notes on my laptop was a must.

As I've gotten better at using rst and vim, I've taken much better notes. Admonitions are great for side information. My religion teacher will make a point, but explain something else to help make it. The sidebar admonition is wonderful for such things. In my religion class this usually includes things such as cultural background, major events contemporary with the text, word etymologies, etc.

I later decided to try to figure out how to get latex equations to pop out of my rst source files. I use the raw directive to achieve that. I followed a tutorial on how to do it.

I have some experience writing latex equations, but I wasn't that fast. I started by simply transcribing hand-taken notes after class. Initially this took a long time. As I got better at it, I decided to give a try in physics class.

My physics teacher teaches using powerpoint slides, and her equations are all done with Microsoft equation. I'm sure it was very painful for her to input all those with the interface that Microsoft equation has. Things tripped me up a bit. My first day there were lots of rst and latex errors, and I missed the tail end of quite a few slides. Things like vector quantities are written in latex like \overrightarrow{L}, which is very long to type.

I got the hang of doing the equations in physics. I was still fairly far behind with the vector quantities.

As I got faster in physics, I decided to give my calculus class a try. My teacher writes examples on the board and explains them as he goes. Pretty much every math class I've had is taught that way. Usually my handwritten notes are simply a transcription of the examples. I occasionally get a sentence written, but hardly ever.

My first day of latex/rst note taking in math was no picnic, but I got the hang of it more quickly than I did with the vector quantities in physics.

Vim helpfulness

Vim has been a lifesaver for my note taking. Some of the tricks I've picked up while doing rst stuff.

Vim's spelling checker

I am a terrible speller. This does make the equations look pretty ugly if I'm using vim in a terminal instead of gvim.

Vim's regex search and replace.

No more typing \overrightarrow. I just type \ora and run a search and replace to expand it to the true function name.

Vim's registers.

When creating the heading for a new section, it can be annoying when the name gets to be more than ten characters or so. I have a macro that loads from my .vimrc to help simplify this:

let @h = "yypVr"

I simply type @h and then type the character I want to use for the heading: '=', '-', '~', etc...

I could also have a separate macro that could simply create a '=' heading, or a '-' heading. I've found that its convenient to have one that I can specify at the time I need it.

Math and Equations

Sometimes, typed notes are absolutely indispensable. Many of my classes are technical, and I need to take down equations, and I need to take them down quickly.

Some equations can be written as text: if x=5*3, then x is 15.

That does not scale at all, especially in higher math and physics classes. You really need to be able to represent the actual mathematics in mathematic notation. If $x=5 \times 3$ then $x$ is $15$. Depending on your medium, this example should have rendered differently.

I include the following at the top of each source document:

.. role:: raw-math(raw)
    :format: latex html

This registers a role called "raw-math" that I can use both inline, or in display mode. This allows for more complicated markup such as the following:

$$ W \approx \sum{f(x_k) \Delta x} $$ $$ W = \int_{a}^{b}{f(x) dx} $$

This is simply LaTex math markup being passed by the docutils writer raw to latex. It also passes it raw to html output, after which jsMath, or another output such as MathML, can take over to render the equation.


I've created a Makefile to use in my notes directories. It reads the directory, and builds a list of targets based on the files present. I can type 'make allpdf' to generate the latex files, and then run pdflatex. The result is a nicely formatted pdf for each day of notes.

The formats I have targets for are: html, pdf, tex, xhtml.

The xhtml target runs the rst2html result through tidy and then itex2MML. The result is that all of my latex equations are valid MathML representations of my equations. They look very nice in Firefox. I don't think MathML is compatible with Safari, but I've read that with a plugin, Internet Explorer can display it.

itex2MML seems to only compile properly on Linux. It's been on my todo list for some time to write a pure Python replacement.

jsMath doesn't need anything else special in the Makefile, unless I want to generate html that includes the appropriate script tag in the header. Currently my Makefile doesn't do that.

Here is the meat of the makefile I have:

itex2MML = ~/sandbox/itex2mml/itex/itex2MML
TIDY = ~/sandbox/itex2mml/tidyExp/tidy -4mz -q

allhtml: $(shell find . -name "*.rst" | sed 's/rst/html/')
allxhtml: $(shell find . -name "*.rst" | sed 's/rst/xhtml/')
allpdf: $(shell find . -name "*.rst" | sed 's/rst/pdf/')
alltex: $(shell find . -name "*.rst" | sed 's/rst/tex/')
all: allxhtml allpdf

%.html: %.rst
        rst2html $< > $@

%.tex: %.rst
        rst2latex --hyperlink-color 0 $< > $@

%.pdf: %.tex
        pdflatex $<
        pdflatex $<

%.xhtml: %.html
        sed "s/\\$$\\$$\(.*\)\\$$\\$$/\\\[\1\\\]/g" $< | $(TIDY)  | \
        $(itex2MML) > $@

%.png: %.plot
        gnuplot $< > $@

        rm -f *.html *.pdf *.aux *.tex *.out *.log *.xhtml $(shell find . \
        -name "*.plot" | sed 's/\.plot$$/\.png/g')

As I take notes, I'll build html copies of all of my notes. That catches any problems I have with my ReST syntax. The LaTeX syntax errors get dealt with later. Because of Vim's support for makefiles, and the line number error detection, this makes it a breeze to catch anything that's gone wrong. Some errors I just don't worry about, because the teacher is moving fast enough that I don't want to get behind.

When someone else in class asks for a copy of my typed notes, I whip up a pdf and e-mail it to them.

The clean target gets rid of anything that is produced directly or as a side effect to any targets that are built. Sometimes I'll whip up a gnuplot graph in a math or science class. I save the definitions in a *.plot file. Sometimes, I simply add a png file directly without having a plot file present, so the clean directive lists all plot files, and then switches the extension to try to delete using sed.

Notice I run pdflatex twice. This is because of the ToC generation, and other things that latex needs to run twice to do correctly.

Writing papers

rst is also useful for writing papers. I've only written a few documents to be turned in using rst, but I've been pleased with the output.

One example is the design document for the major projects in my computer science course. Using rst2newlatex produces very professional looking output. The automatically generated table of contents is very nicely done. The graders could see what I had included in the whole document just by glancing at the first page. It took me less time to do it in rst than it would have if I'd done it in straight latex.

Python Class

I've been teaching a Beginners' Python class for interested co-workers off the clock, and I've been using ReST for my lesson notes. I modified the CSS to suit my needs, and added google-code-prettify to do syntax highlighting on the docutils-literal blocks.

I simply copied the default css file that docutils uses, and modified it to give the desired look. I had to modify the html template that rst2html uses, and included the script tag that imports prettify.js. I only made one change to the prettify.js file. By default, it only prettifies pre elements that have a special class name. I changed that name to docutils-literal because all of my code blocks were code. I didn't want to litter my rst sources with class directives.

The resulting html files are not published to my site, so I don't have them included here. They are deployed as simple html files, and only have the extra prettify.js file that accompanies them. I created a make target called publish. Since I use vim, I can rebuild and publish all html files by simply typing :make publish. The directive looks something like this:

publish: allhtml
    scp *.html prettify.js servername:/path/to/site/