I create my slide decks from ReStructuredText, which is a text markup format. Working this way makes it easy to add into source control, fast to work with, and also accessible since I don’t use a mouse or other pointing device so traditional slide deck creation programs are kind of difficult. Text-based wins every time for me. While working on a new slide template, I ran into some difficulties and had to figure out how to inspect what was going on. I seem to struggle with this every time so I am writing my troubleshooting guide here for when I need it next.

Debugging Rst

I generate slides with the rst2pdf command but for debugging purposes, try rst2pseudoxml instead. This shows me which styles are actually being used and therefore I can edit the stylesheet to amend the thing I’m looking at, rather than making changes at random! It’s not XML at all but it’s enough to see which styles are in play.

Sometimes the rst2html is also helpful as it also closes tags so you can see where something starts and finishes. Also pay attention to the program output as it usually spits out some really useful warnings (and the ones about fonts are right at the top and may scroll out of sight).

Debugging Pygments

Pygments styles each element of highlighted code with a specific style. So the function name is one style and the brackets another, the arguments a third, and so on. I don’t use pygments enough to remember what all the styles are called and I always seem to struggle to herd all my code into looking good at one time! To figure out how to style a specific element, try this:

1. Put the code into its own file
2. Run pygments to get HTML output: pygmentize -o test.html test.php
3. Look at the resulting output – the style names are in the CSS classes in the HTML, those are the styles you need to change in your rst2pdf stylesheet

Such minor points but they do make the tools easier to work with so here they are. I’ll be able to find them next time and if they’re useful to you too, then great! Feel free to add your own tips and tricks in the comments :)