MoinMoin for notebook-wiki (and WordPress, you are trying the patience of my affections)

For two days short of a full calendar year I have been keeping a wiki of my computing notes. A wiki, a lightly organized website structure, is much better than a nest of files in subdirectories if you are trying to keep track of what you have learned and accumulate a record of your experiments and experience. And running it on a server means it is available to you more or less everywhere.

I have been using MediaWiki, the software that powers Wikipedia. I know it pretty well, having fiddled with Wikipedia ever since it emerged from the miasma of unrealized memes. But this year of MediaWiki has been frustrating. The application is good for mixing markdown with HTML — markdown is very low maintenance and HTML is helpful when you want fine control of formatting or to include something from a website — but MW’s brand of markdown sometimes has small problems (for instance, numbering of an ordered list sometimes resets when a line of “preformatted” content is interspersed among the numbered items). And a whole MediaWiki site is not so easy to back up — the simplest thing is to dump the whole MySQL database, but then that’s a large file to deal with every day.

Finally this morning I broke down and installed MoinMoin, and transferred my whole MediaWiki database into it. MoinMoin isn’t as good with HTML as MediaWiki is, but its brand of markdown is simpler than MediaWiki’s. I like the fact that each page is stored as a flat text-file, meaning that backup with mercurial is very efficient — only individual diff patch-files are pushed to server.

I dare say markdown will replace HTML in many environments.

Best of all, MoinMoin looks pretty good in w3m, my text-only browser of choice.


For a while it didn’t look as though I would be permitted to post this. WordPress has drastically redone its software, and I could no longer see most of what I had written; nor could I preview my text or assign categories to it. Beside the non-functional text field there was a little remark: “Blogs are not just for long posts. Why not post a photo or video instead?”

I chose WordPress over other sites because I liked their software; it seemed the best tool for what I wanted to do. If I stop liking it, the whole relationship will be in danger. I don’t mean to sound like a pretty girl with too many suitors, but no company should take my patronage for granted. I don’t need a slick interface — not at all — and I don’t need social media. If that’s all you have for me, it’s “goombye pliz”.


(grumble, grumble, a little later)

After posting the abortion of this note as a “quotation” (since WordPress’s parsers determined that there was no content in the original “text” format), I later became able to edit it in the familiar interface, with the minimum functionality I require. What a mess. If your product works, leave it alone, people.


Yes, I said text-only browser. W3m, made in Japan, the homeland of craftsmanship. I am a man of command-line temperament and of words written and then revised and then revised again. Spare me your sticky GUI; spare! o spare me your tweets and friending and live webcam feeds, and let me type what I have to type and have it read by those who have the patience to read.

Classical Chinese syllabus posted; using Landslide for markdown-to-HTML5

In my teaching this year, I’m going to avoid course management software like Courseworks and Blackboard entirely, and build my own little password-protected site, for the practice.

I’ve posted the syllabus publicly as HTML5, the first time I’ve attempted to use that format. I constructed it using the wonderful Markdown language, which I converted to HTML5 using Landslide. Landslide is very convenient and (in v. 1.0.1) was easy to install and operate. I also tried using Pandoc (v. 1.5.1.1, via apt-get on Ubuntu 10.04; newer versions have unworkable dependencies) with the -w slidy option, but Landslide looks much better, at least with the default options.

Two small matters in Landslide v. 1.0.1, which I’ve reported as issues:

  • Not all of the functionality is described in the README file; .qr, for example, is currently only described in one of the sample files (https://github.com/adamzap/landslide/blob/master/samples/example1/slides.md).
  • Although ordinary Chinese text in Unicode displays correctly, high codepoints (represented in UTF-8 as surrogate pairs) do not. High codepoints are rare, but the failure of software to handle them correctly is not.

Thanks to Norm Kabir and WES Skeith for the inspiration of their own markdown-based course materials.

LaTeX and electronic documents

The current issue of TUGboat (32.2, 2011), the Communications of the TeX Users Group, has eight papers in a section called “Electronic Documents,” dealing with various issues affecting the relationship between LaTeX and the latest fashions in on-line publishing and mobile devices. The ePub format, standard on most e-readers, remains a significant rival to the dominance of PDF, widely used for long-term document storage, and several of the articles address the challenges ePub presents.

All are worth reading; I single out these two as especially useful:

A third noteworthy paper is Axel Kielhorn’s “Multi-target publishing” (based on a German original, also 2011), which describes pathways from LaTeX to PDF or ePub output by way of John Gruber’s Markdown language (currently at http://daringfireball.net/projects/markdown/). The chief element of these pathways is Pandoc, on which see http://johnmacfarlane.net/pandoc (accessed 20120107); the main Github repository is currently at https://github.com/jgm/pandoc (accessed 20120107).

Choice of formats for basic code documentation

I have begun making my code available on BitBucket but I want to include some sort of README or other documentation in each code repository I set up. When plain text doesn’t meet my needs, I’ve been unsure what to turn to.

An interlocutor argued for Markdown, but in practice all that really means is trying to adhere to Markdown principles in my plain text — actually interpreting Markdown (as HTML, LaTeX, etc.) requires the user to have a separate application, something I can’t assume.

Plain text will do for most cases, but more functionality is required when my README/doc needs math or tables. In the past I would have gone with HTML, but HTML now seems to be experiencing backward-incompatible growing pains and risks turning into Frankenstein. The competitor was PDF, which I had thought was proprietary but apparently I was wrong.

My plan now is to generate PDF from .tex and include both files, but only when text alone is inadequate. Ordinarily, however, I will just include an ASCII .txt file with newlines at 79 columns.

Longevity vs. versatility of code

Until very recently, I have used HTML only as a simple markup language for presenting static information. It was quite satisfactory for posting announcements or writing, and easy to automate for formatting large collections of material from my research databases. Even though the databases might be updated daily, a given data dump was static as soon as it was generated.

Now that I am trying to use HTML for interactive tasks, I can’t avoid facing its drawbacks any longer. One serious problem is that HTML is “stateless” — commands take place without persistence of context, so you either have to turn to cookies (of which many users are suspicious) or supplement it with Javascript or other languages. Another problem is that certain seemingly simple tasks have not been standardized (as of HTML 4), so solutions vary by browser. An example that bothered me recently was styling a “browse” button used for file upload. I’ve identified a number of workarounds, but HTML 4 has no native way to do this, and every workaround increases the risk of obsolescence or outright failure in unplanned-for environments. As Jukka Korpela writes, “The Browse button is particularly ‘immune’ to any presentational suggestions; it’s typically a ‘hard-wired’ part of the browser’s user interface.” It’s also dismaying how differently some non-”web-safe” colors and background images appear when viewed in different browsers.

I’ve gotten used to the incompatibilities between Python 2 and 3, which fazed me at first. But everything connected with the web seems to be subject to a higher margin of “not quite” than any compiled or scripting language proper that I’ve seen.

The model of longevity in traditional scholarship — the world in which I cut my teeth — assumes that what you produce in your 20s will still be around and basically accessible when you’re in your 70s, at least. Mathematical writings from 120 years ago are still cited with some frequency, and I possess philological books on the order of 1000 years old that are still basically quite usable and remain in print for that reason. I can even make my way around 1400-year old Chinese dictionary manuscripts without too much pain. But the amount of tweaking needed to keep code alive is a high trade-off for what I grant is its immense flexibility.

At bottom, I think this is a difference in economic outlook: When I work as a scholar, I labor to produce a description of something I can show to be true, and to present it in such a way that my thinking can be reproduced and challenged by anyone for a very long time to come. In exchange, I am paid essentially nothing for what I hope is intellectual substance of quality and intrinsic worth.

There is a different model of value involved in coding, and a different time-frame.