New and Improved: Two-Wrongs Now Powered By Org Mode
This blog has been dormant for a while. A large part of it is because I’ve had a million other things to do1 which hasn’t changed, so that will still slow publishing down, but another part of it has been that I have dreaded writing the html sources to these blog posts. It’s just such an inefficient use of the little time I have. So I have been on-and-off looking into alternative publishing systems.
The culmination of my effort2 a word used very lightly here … we’re talking at most like half a lunch break per week. :( has resulted in this site now being generated with Emacs Org mode.
I wish I had switched to doing that long ago.
Design Changes
You may notice that I have taken the opportunity to throw in a couple of design changes along with the backend stuff. I don’t take design modifications on this site lightly, because the design is probably the thing I get the most positive feedback about. People really liked the previous design, so I’ve tried to keep the new one in the same spirit.
There are two major changes compared to the previous version.
- I have attempted to remove clutter from the general layout. The previous design was very free of clutter too3 which people appear to like, but I hope I have improved that aspect even further.
- I have freed up a narrower column on the side of articles4 This second column is not visible on narrower screens (such as phones in portrait mode). When reading on such a device, the margin notes will be collected at the bottom of the article, with convenient hyperlinks there and back again. But I have a feeling that people reading on such a device are not interested in the deviations from the main content to as large a degree anyway., where I can put remarks that aren’t fully relevant to the main point, but nonetheless interesting supplementary material. The idea is that I can then make the main text shorter and more to the point, and fill the margin with notes that may be of interest for people who want a deeper reading.
What Org Mode Is
Org is both a markup language and an extension to Emacs – since it’s based on plain text, you can write Org documents without ever using Emacs, but the Org mode Emacs extension is indisputably a good thing and it contains hotkeys and commands that make it easy to organise text5 There is even an extension to Emacs that lets you structure your programming source code using an Org-like paradigm. I have just started using it and I already find myself navigating my code bases with less effort.. If you have experience with something like OneNote or Evernote, you can think of Org mode as the open, free and simple version of those commercial applications. No lock-in, no limitations.
Org mode and the available extensions does not cover all of the requirements for generating this website, but I can just type up a couple of Emacs Lisp functions to handle the missing cases, and they integrate really nicely with everything else6 Which is probably a familiar sensation to other Emacs users out there. Another great thing about Emacs is how easy it is to write code that integrates seamlessly with the existing plugins and scripts..
Why Org Mode
I have long wanted to move away from the previous system I wrote for statically generating this website. The previous system was decent, but it was a big operation to extend it. I made some feeble attempts at new systems7 Most promising was something based on Makefiles and regular POSIX tools (awk, m4, find, sed and so on), but eventually I had to give up; anything I wanted to do would take way too long to create., but when I found out about Org publishing – that was it. There is no way I can top Org for this.
There are many things to like about Org mode, but this is for my readers. I’ll try to focus on some features that make the reading experience better on the web.
Source Code Blocks
As you can hopefully see below, I can now include syntax highlighted code in browsers8 browsers with graphics, anyway. And it’s essentially zero effort on my part.
;; Turn a file-tags mapping into a tag-files mapping (defun tw-invert-alist (alist) "Invert ALIST, turning key-values into value-keys." (when alist (let ((inverted (tw-invert-alist (cdr alist))) (key (caar alist))) ;; file (dolist (value (cdar alist) inverted) ;; tags (if (alist-get value inverted) (push key (alist-get value inverted)) (push (cons value (list key)) inverted))))))
Org simply generates html markup that mimicks whatever colours are currently used in my editor. Org also understands that what’s inside that code block is Lisp code, so Emacs can highlight it properly.9 This means it can also run the code in the code blocks and insert the result somewhere else in the document. Nifty, but I don’t yet know what I’ll use it for…
Tables and Structural Editing
Org mode makes it easy to create tables. Table 1 shows a quickly calculated measure of the effort of creating a table when using Org compared to writing html directly.
| Format | Keypresses | Comparison |
|---|---|---|
| HTML | 84 | 227% |
| Org | 37 | 100% |
Highly structural elements are always an annoyance with html10 Although the
worst is probably having to type <p></p> around all paragraphs… and Org
mode alleviates this a lot by being designed around managing structural
documents.
Oh, yeah, and as you may have noticed there I also get stuff like captions and references and such for free.
Control over Content
Org makes it very easy to have fine grained control over the content down to the level of sections11 I can, for example, mark a section as a draft and not have it exported as soon as it hits the server even though the rest of the article is published.. It also makes it easy to combine dynamic and static content.12 I can finally insert static content into any dynamic page and vice versa.
Hyperlinks
Table of Contents
Org mode makes it easy to create internal hyperlinks in a document, create hyperlinks between documents, and even refer directly to a section of a page. Which let’s me have a table of contents! You’ll see it on the right of the main body text if you are on a wider screen, and inline if you are on a narrower screen.13 You’ll have to excuse the weird vertical spacing here; forcing a table of contents into the middle of an article belongs to the unusual. The styling is created with the assumption that the table of contents goes where the table of contents normally goes.
That’s something I’ve wanted for a long time.
Inline (and Full-width) Maths
Org mode integrates quite nicely with LaTeX maths syntax14 using MathJax for export, so this will let me embed stuff like
\[ \int_o^r f(r) ds \]
without having to resort to only inaccurate verbal descriptions. This may come in handy for a future article I’m planning.
RSS
So this is where I could use your help, actually! I have configured Org to generate an rss feed for my posts, but I don’t use any sort of web syndication like rss myself so I can’t verify whether it’s working the way it’s supposed to. Please tell me if something is wrong!
update: I have now learned that the rss is probably working – with the exception of two things:
- There are no post previews embedded in the rss (something I should deal with at some point), and
- Since the rss generator is new, rss readers mark all my past posts as unread. This was something I tried to take measures against because I was afraid it was going to happen, but at this point I’m not sure there’s any way to fix it. I fully understand if you want to unsubscribe from the feed after this. It is not okay of me to break your trust and spam like that.
update: Legacy html Format Articles
I also should mention that the way I’ve kept all old posts is by simply embedding their old html sources directly into Org documents. This means that they are not manually reformatted to the new Org source format yet – and therefore don’t get the advantages such as sidenotes and synax highlighting. This is something I plan on doing piece by piece as I go.