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. 126.96.36.199, 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.
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:
- Alan Wetmore, “e-Readers and LaTeX,” reviews current e-readers and the problems they have displaying PDFs.
- S. K. Venkatesan, “On the use of TeX as an authoring language for HTML5,” proposes a TeX syntax for generating HTML5.
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).
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.
- The official news
- The specification itself
- A discursive account (see section “PDF 1.7 – Adobe goes ISO”
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.
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.
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.