It’s amazing how good snow is for your productivity. Maybe I should move to Antarctica.
Anyways, I added some rudimentary support for displaying source code using the listings package. Let me show you how this was done as an example of how to add support for whatever packages and macros you would like.
So first of all, plasTeX is pretty smart about understanding the packages that you are using in a Latex document. It will parse your preamble and do the best it can to load and parse the packages you are using as well. This is great if you have, say, some custom macros put aside that you always reference. So if you put a \usepackage{mymacros} in your preamble, plasTeX will find the mymacros.sty file the same way Latex would, parse the file, and then understand how to expand the macros contained therein. This is the default behavior.
For more complicated packages, like listings, for example, there’s a better way. Instead of letting plasTeX load and parse the source, we can choose to tell plasTeX about which commands we care about directly in python. This saves a lot of time and adds a lot of flexibility. (By the way, this has already been done for a bunch of packages that you might want to use, like amsmath, amssymb, graphicx and more.)
Now, when plasTeX finds a \usepackage command in your preamble, before it tries to load the latex source, it will look for a python module on the path which shares the same name as the package specified. This means if I put a file called listings.py somewhere in my python path, when plasTeX sees the \usepackage{listings} at the top of my file, this module will get loaded instead of the Latex source. For convenience, I have the wplpost program add the wplatex package directory to the python path, so you can just add any package code to that directory, reinstall, and everything should work automatically.
Great. So what should go in the python package definition. This is easy: you just define a class for any command that the package let’s you use. In our case, the listings package defines a new environment called lstlisting. When you put source code in this environment, the package will render it in your Latex output. Thus I have the following class definition in the file wplatex/listings.py
from plasTeX.Base.LaTeX.Verbatim import verbatim
# This should be a verbatim environment
class lstlisting(verbatim):
pass
In most cases, your new class will derive from either the plasTeX.Base.Command or plasTeX.Base.Environment classes, depending on whether you want to tell plasTeX about a new command or a new environment. In the current case, we want to use a special kind of environment, a verbatim environment, since we don’t want to do any rendering or parsing of the code inside. That’s why I’ve derived this class from verbatim.
In the future, this class could override some of its base class’ methods, particularly invoke(), and do some preprocessing like figure out what language to use and add any formatting information. It’s nice to notice, though, that just telling plasTeX about the command by creating a dummy class is enough for it to now recognize it in a Latex source file.
We’re almost done. The only thing left to do is to tell renderer what we want to see when plasTeX encounters one of these environments. The code for the renderer is contained in the file wplate/renderer.py. I added the following method to the WPRenderer class:
def do_lstlisting(self, node):
'''Encode Source code blocks
Arguments:
- `node`:
'''
return u'<sourcecode language=Python>%s</sourcecode>' % unicode(node)
Ridiculously simple, no? All this method does is return a unicode string which we would like to see in the output. The command
unicode(node)
renders all the children of our lstlisting node in plasTeX’s internal tree representation of our document. Since we’ve already told plasTeX that the lstlisting environment should be verbatim, this will just return all the text found inside. We then plug that in between WordPress’ tag for source code and return the result.
And that’s it! After reinstalling the wplatex package to udpate the code, the wplpost program now understands how to post source code. Not bad for two or three lines of code. In fact, in continuing with the incredibly self-referential tone of the past couple posts, I’ve used this functionality in writing the post you’re reading. Here’s a screenshot.
You can take a look at the source code to see how I’ve implemented other commands and environments. There’s still a lot to do, but I hope this post makes it clear how easy it is to add or customize the output that you send to WordPress. If you do get around to adding support for more things, I hope you’ll drop me an e-mail. And now, I’m making myself some spaghetti.
