This past semester I taught a new course entitled Phonological Theory. Apart from the content, I decided to experiment a bit with the technical details, specifically using pandoc and reveal.js to do the slides and lecture notes.
I’m a pretty consistent LaTeX user, so to the extent I do slides I do them in beamer. There is nothing inherently problematic with this, and AUCTeX saves typing a lot of the boilerplate, but writing two–three presentations per week is still time-consuming. I also tend to do the non-recommended thing and put a lot of text on my slides; my justification (apart from the fact that it lets me pace the lectures at least the first time around) is that I use beamerarticle to produce a more text-like notes document that is then quite detailed.
So why pandoc? Well, partly just for the fun of it. My slides + notes workflow also fits quite well with its philosophy of producing multiple output formats from a single input. Perhaps most importantly, markdown is obviously less ‘noisy’ than LaTeX. Compare this:
## Slide title ##
* Item 1
* Item 2
* Subitem 1
* Subitem 2
* Item 3
and this:
\begin{frame}{Slide title}
\begin{itemize}
\item Item 1
\item Item 2
\begin{itemize}
\item Subitem 1
\item Subitem 2
\end{itemize}
\item Item 3
\end{itemize}
\end{frame}
Even if you’re pretty proficient in LaTeX and filter out the visual noise, I think it’s pretty obvious that the former is a bit less horrible.
Anyway, I’ve now taught the entire course using this workflow, and overall I think I was quite happy with it. The workflow carries over nicely and although there were things that took a bit more work than they would have done if I were using LaTeX I think I felt at least as productive when using pandoc.
The good
Writing markdown is of course a piece of cake. I’m using Emacs with markdown-mode and pandoc-mode, which makes it even easier. Consider the task of indenting a sublist, e.g. making a list item (and all its subitems) into a subitem of something else. In markdown-mode, it’s a matter of a single keystroke, while in LaTeX it’d involve a whole new environment and possibly other adjustments.
The text would usually carry over from slides to notes quite painlessly, so that’s good. Pandoc-mode also has a handy feature called a project settings file which allows you to reuse pandoc settings (e.g. includes, bibliography files, CSL files etc.) across multiple input files – having chosen a single set of options it’s easy to use them for all the .md files in that directory. If, for whatever reason, you need to use a different set of options for an individual document, that’s also possible with per-file settings.
Pandoc also gives you a lot of latitude to tweak how the output looks like, since you have full access to the templates it uses to build the output. This means that my lecture notes look pretty much like any other documents I write and don’t use the default TeX settings.
I really liked Reveal.js. It looks pretty nice (though see below) and it has some nifty features. Some are perhaps more pretty than really useful, but I though the overview mode and the speaker notes were especially handy (the speaker notes in particular are nice when you don’t want to put something on the slide but still have it in the notes).
The less good, and some tips
I did run into some issues that needed resolving, although partly they involve just shaking off the LaTeX mentality. An obvious issue is the lack of access to LaTeX macros. Pandoc has support for a subset of TeX maths in non-TeX output, so it is possible to use things like $\rightarrow$ or $\emptyset$ (which you need a lot in a course like that), but getting a feature matrix (for which you’d use some version of array) is more difficult. Still, it’s not as crippling as Word, so that’s an advantage already. I didn’t really run into a case where there was no way to write what I wanted to write, but I did end up typing out $\rightarrow$ a bit more often than I would have wished. (I should probably just have assigned some keystrokes to the right symbols, but I never got round to it.)
(Pandoc-mode does come with something called @@-directives, which can be kicked into a shape resembling TeX macros, but they’re still pretty limited and also require more Elisp skills than I could dust off while writing a new course from scratch.)
Diagrams and drawings are another potentially problematic issue. Thankfully, pandoc comes with the filter facility, and the example repository contains a filter that takes TikZ code and feeds it straight into the output when the output is TeX but creates an image file and embeds it if the output is something else. With a little bit of hacking I was able to make it understand environments like forest (which I recommend for drawing trees) and generally have the pictures assume the desired look and feel. So that’s doable.
One potential issue that it took me some time to figure out was getting speaker notes to play nicely. Reveal.js presentations can be shown as static files, but then you don’t have access to speaker notes. To get the notes, you need to run a local server using some Node.js magic or other. For one thing, this obviously means that you need to lug your laptop around to the lecture and hope it works. More importantly, reveal.js seems to assume your presentation resides in the same folder as the reveal.js files. If you have multiple source and output files in the directory for your course, you probably don’t want to clutter it with its js, css and so on, but rather keep it in a separate folder. But this means that when you run grunt serve from the reveal.js folder, you don’t get access to your files. To fix that, you need to go open Gruntfile.js and find the lines
connect: {
server: {
options: {
port: port,
base: '.'
}
}
},
Change the base option to '../', and it will serve files from the directory above reveal.js, which is what you probably want.
One feature that I miss in reveal.js is a counterpart to beamer’s allowframebreaks option. It does support manual slide breaking, but that is obviously fragile (not least because the screen in the lecture room doesn’t necessarily have the same proportions as yours, so you don’t have a 100% reliable guide to when the slide is overfull). Of course you don’t have this problem if you don’t put too much text on your slide.
A final thing that is not so much a problem as a consequence of lack of time for my part is that changing the look and feel of reveal.js beyond the stock themes requires passable CSS skills, and I definitely did not have time for that.
Conclusion
I found the pandoc + reveal.js route to be a good alternative to beamer for teaching. I think I’ll stick to LaTeX/beamer rather than pandoc for serious paper-writing, since the loss of the LaTeX power is only partially compensated by the relative ease of markdown, but for teaching I would recommend this alternative.
