BibTeX and Gitit
By John Lenz. June 26, 2012.
This post is part four (and the planned final part) in my series on managing LaTeX references using pandoc. In the first post, I described at a high level how I manage my LaTeX references. The second and third posts contain some haskell code to manage these marked up BibTeX files. In this post, I describe how I use gitit to browse and edit these files in a web browser.
As a side note, after writing the second and third posts, I am considering posting the code from them on hackage so people can use these programs without copying code from blog posts. Also, haskell has the nice feature that compiled binaries can be run without having haskell installed. (Pandoc uses this to provide a windows binary.) So I could also provide binary downloads for the tools which could be used as is without installing haskell. At the moment, I haven't done that since you need a little familiarity with the command line and mercurial to work with these files, and for people who know their way around the command line, running "cabal install" or "runhaskell" isn't that hard.
Well, back to the content of this post. Gitit is another really nice program built around pandoc that we can leverage to work with our BibTeX files. Gitit is a web server that provides a wiki where the pages and their history are stored in git, mercurial, or darcs. The syntax of the pages is markdown and pandoc is used to convert the pages to HTML for display. This should sound very similar to the third post. Gitit also supports plugins, so the idea is to take the code from the third post and make it a gitit plugin.
The advantages of gitit are:
- it converts the marked up BibTeX files to HTML on demand so we don't need to run a tool,
- allow browsing of the marked up BibTeX from any computer,
- allow editing and previewing from the web browser,
- since the marked up BibTeX files I write are sometimes mini surveys, browsing them from the web is nice when I am trying to refresh my memory about theorems or open problems in some area. Also, math formulas are rendered nicely.
The disadvantages are:
- There is a bunch of setup and configuration required.
- Mercurial hooks can be used to run the code from the third post on update and commit, or a shell script can be written to run the code. This provides almost all the same advantages for much less setup cost.
- The benefit is only worth the setup cost if the server is accessible on the internet, and configuring and maintaining a server has a high overhead.
Since I am already running a web server on the computer in my home, the overhead for me isn't that much. But even with gitit set up and running, most of the time I edit with Vim locally and push with mercurial instead of through the gitit web interface. (Note that gitit is nice if you push commits over ssh the web pages are automatically updated.) If I wasn't already running a server, I might not bother with gitit and instead work out something with mercurial hooks or hakyll or something like that.
Gitit Install and Config
Install gitit using the normal instructions. Next, edit the gitit config file and switch to mercurial and perhaps edit the option for default math. Then you will want to push the pages to the gitit repo. I skipped setting up caching since there is hardly any traffic. I also proxy gitit from apache over ssl as described in the README. I set http authentication in the gitit config and then in the apache config use
AuthType Basic with a manually updated list of users and passwords. At the moment, I allow browsing without authentication but only authenticated users are allowed to edit. This does mean anyone can browse my pages, but this is useful sometimes for example I can send links to collaborators. But I still want these pages to be semi-private, so I forbid search engines from indexing the content using robots.txt. You might consider instead just requiring logins to both view and edit content.
Once all the above configuration is done and working, gitit will serve and allow editing of pages. The only downside is the raw BibTeX will be shown in the code blocks. Luckily, gitit supports plugins and we have already written all the code! All we need to do is take the code from this post, delete the
main functions, import
Network.Gitit.Interface, and add the following:
plugin :: Plugin plugin = mkPageTransform transformBlock
For your convenience, you can download the resulting file here. Drop that file in your gitit plugins directory and add the plugin to the gitit config.