This weekend I’m doing some work on the MathTran website. The main goal is to move it to Django, and to clean up and improve the content while I’m at it. I’m not much of a web-wizard. I know about HTML and JavaScript of course, and to get dynamic baseline alignment of bitmap mathematics I even did a bit of Ajax programming. But I’ve not developed on a website that has a database backend yet, although that is one of my ambitions for the MathTran site.

I’ve read a lot of the online documentation for Django late last year, and I’ve spent about 5 days reading as a print copy of The Django book and spent some time writing some sample Django code. (I like to understand the principles of a programming language or environment before I start using it.) But now I’m ready to start coding.

I’ve created a mathtran_website sandbox on my development machine, and have set it up to serve static pages. But I’m getting the navigation and footer from a single place, using Django’s template system. Previously I was using static HTML, and this meant that whenever the navigation changed I had to change all of the site’s web pages. So having the navigation stored in a single place is a great convenience, and gives me a freedom to change things.

I can now move on to the content. I’ve copied much of the present content into Django templates, but I really don’t like writing raw HTML, and so I’m thinking of using reStructuredText (ReST). I particularly like the way in which it separates the authoring of the text and the creation of the link. Another plus is that the source for the Django documentation is written using ReST.

I’ve now set up a trial page to use ReST, and I’ve come across some problems. The first is that now I’ve got my a template, say mathml.html and some ReST text mathml.txt, where the template consists just of

{% extends 'base.html' %}

{% load markup %}

{% block title %}MathML page title{% endblock %}

{% block content %}

{{ rest|restructuredtext }}

{% endblock %}

Following the Don’t Repeat Yourself (DRY) template, it makes sense to have a single template for all the ReST pages, and to place the page title elsewhere. Well, that’s fine, except storing the page title in mathml.txt (which is where it should go) and then retrieving it does not seem to be straightforward.

Experience Djangonauts will at this point say: You should be using flatpages – it’s the right tool for this job. And they may be completely correct, provided one is already running Django with a database. But I’m not at this situation yet. I want to move my (static) website onto Django, and then deal with setting up the database. And with a flatpage the title and the content are stored separately, and so it’s already recognised that there’s a problem in supplying a page title along with content when using ReST. There’s something else I don’t like about flatpages, which is that they are consulted only when Django raises a 404 error. I don’t know if this actually causes a performance problem, but I don’t like it conceptually – what I like about is that it records what URLs the site responds to, and flatpages contradicts this.

But all this is a diversion from the main task, which is deciding whether to use ReST, and recoding the existing pages using ReST. Well, I’ve done enough to decide that ReST is worth using, and I can write some simple code that will hook it up into the Django framework, so that part of the problem can proceed. And to handle the page title I’ll do some sort of hack, such as using the first line of the ReST file as the page title, and not passing it on to restructuredtext filter.

Oh, and there is a second problem. On the MathTran home page there’s a data entry form for sending TeX-encoded mathematics to the MathTran service. But that is more easily solved – ReST provides a raw directive that allow material to go through directly.

So to conclude for today:

  1. I am able to set up Django to serve up ReST encoded pages (without having to use flatpages and thus set up a database).
  2. I can code up the content using ReST (but I need to use a hack to get the title, and use the raw directive at places.
  3. I’ve translated part of one page to ReST, and know how to do the rest (sorry about this accidental pun).
  4. I’ve more or less got set up the code that uses Django to serve these pages.