Irreal

There’s a disadvantaged group of people in our industry that use Markdown to prepare their text for output to, say, PDF or HTML. I call these folks disadvantaged because Markdown, although fine for preparing simple documents for publication, has some serious deficiencies when compared to Org mode. I’m not talking the syntax, which is different from Org’s but just as good. Org is more powerful as a markup language but really shines as an embedded mode of Emacs which provides editing commands specialized to Org that aid in producing serious documents.

Another problem with Markdown is that there isn’t a Markdown but several. The original Markdown was relatively simple so users such as GitHub extended it but, of course, each in different ways. The result is that there are several dialects of Markdown. While there are ports of Org mode to other editors, there is still only one Org mode markup language.

Org mode provides a very comfortable and flexible writing environment that can easily handle complex documents. Still, sometimes you need to deliver Markdown for certain applications, Websites, or sharing with users who aren’t Emacsers. That’s not a problem because Org can export to Markdown. But there are problems.

Franco Pasut has a useful post that looks at exporting from Org to Markdown. In particular, he explains how to covert Org tables to Markdown tables. The TL;DR is to use Pandoc specifying the --to-gfm option. He also discusses some problems with exporting code blocks to Markdown. If you find yourself having to export to Markdown, you should probably take a look at Pasut’s post.

Like many people, Simon Pugnet likes to keep a record of his exercising. His regime includes several types of exercise such as running, sit-ups, and pushups. Also like many of us, he maintains a daily journal so, of course, it made sense to record the exercising in his (Org mode) journal. He does this by adding a third level headline for each exercise under the second level headline Exercises. The first level headlines are the date so this gives Pugnet an “Exercises” headline for each day.

You may not think this is an optimal setup but it’s a reasonable one. Now, however, Pugnet wanted to generate a table of his daily exercise and maybe even some graphs. He solved that by writing a bit of Elisp, which you can see in his blog post about his setup. It would certainly have been easier to record the data in an Org table to begin with, which is what I do for things like this but I do like the idea of keeping everything in the journal and extracting the data you need for whatever project you’re working on. It take a little more work but everything is in one place and easy to find.

In any event, the reason I’m writing about this is that Pugnet’s code is a nice illustration of how to parse Org files and extract data from the entries. You can, of course, do that with regular expression search and other ad hoc methods but Org provides you with functions that take care of all that for you. It’s worth studying Pugnet’s post just to get an idea of how to do these things.

Chris Mariana has an interesting video on how to prevent losing files when writing in Org mode. It’s a useful post but not really enough to write about. The TL;DR is that it explains how to locate files that were saved with org-attach.

That video, though, led me to another video of his on writing in Org mode, which is an elementary introduction to writing documents with Org. Mariana begins by noting that a big advantage of this approach is that you’re writing in plain text and that brings many advantages such as easy version control, flexible export, and others. And, of course, although he doesn’t mention it, the avoidance of lock in: your plain text document will always be readable even if you change text editors or yours disappears.

From there, he moves on to the basic structure of an Org document and some of the ways to manipulate it. Org, of course, can be thought of as two things:

1. A lightweight markup language
2. An Emacs mode that implements many features including an easy way to edit and operate on Org documents from within Emacs

Mariana’s video is more about the second of those although he does cover a few of the markup features. He also shows some of the flexibility of the export system. You won’t become an expert in writing with Org from this video but it does gives you a good feeling for what the process is like and why you might want to find out more.

The video is 17 minutes long so plan accordingly.

I recently came across this post by Chung-hong Chan on academic writing in Emacs that really annoyed me. It’s not anything that Chan said that put my back up but rather a common supposition that he mentioned that I and almost everyone else seems to accept uncritically. That supposition is that of course we can’t ask our project collaborators to learn Emacs and Org mode. No, it’s incumbent on us to learn Word or Google Docs instead.

You know what? I’m over that nonsense. I’m not going to write in Word and if you want to collaborate on a paper or article with me it’s going to be in Org mode, Markdown, or even LaTeX but not some brain-dead word processor like Word. Even if—heaven forfend—our target publisher requires Word, I will insist on a rational development language that we can convert to Word as the last step.

Really, do you want to collaborate with people who say they don’t have the necessary cognitive cycles to learn Emacs? Of course, they do have those cycles but they’d rather have you inconvenienced than them. Just say no.

Chan introduces the notion of “highest common factor” to justify Word as the lingua franca of collaboration but I submit that it’s really the “lowest common factor” and that serious collaborators should level up to at least Markdown rather than insisting everyone else stoop to Word.

Again, I’m not objecting to Chan’s article—which is, in fact, a nice exposition of how he uses Emacs for academic writing—but rather to the notion that it’s somehow incumbent on those of us using a rational writing environment to defer those who aren’t.