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.