Disclaimer: this is a very nerdy blog entry. It is about lightweight markup languages and why I think that Org-mode is the best lightweight markup language for many use-cases. And with lightweight markup language, I do mean the syntax, the way you express headings, lists, font variations such as bold face or italic, and such things.

Please do note that this is not about Emacs. This is about Org-mode syntax and its advantages even when used outside of Emacs. You can type Org-mode in vim, notepad.exe, Atom, Notepad++, and all other text editors out there. And in my opinion it does have advantages compared to the other, common lightweight markup standards such as Markdown, AsciiDoc, Wikitext or reStructuredText.

Of course, Org-mode is my favorite syntax. Despite my personal choice you will see that I've got some pretty convincing arguments that underline my statement as well. So this is not just a matter of personal taste.

If you already have a grin on your face because you don't have any clue what this is all about: keep on reading. It makes an excellent example for making fun of nerds at your next dinner party. ;-)

Org-Mode Is Intuitive, Easy to Learn and Remember

Here you are. This is almost anything you need to know about Org-mode syntax:

* This Is A Heading
** This Is A Sub-Heading
*** And A Sub-Sub-Heading
Paragraphs are separated by at least one empty line.
*bold* /italic/ _underlined_ +strikethrough+ =monospaced=
[[http://Karl-Voit.at][Link description]]
http://Karl-Voit.at → link without description
: Simple pre-formatted text such as for source code.
: This also respects the line breaks. *bold* is not bold here.
- list item
- another item
- sub-item
1. also enumerated
2. if you like
- [ ] yet to be done
- [X] item which is done

I've seen many coworkers who typed Org-mode markup when taking notes in their text editor. And they did not even know anything about it. So it is that intuitive I'd say.

While I was learning Org-mode, I did not even use a cheat-sheet for the syntax as I normally do. It was very natural for me to type Org-mode right from the start.

Tables are a bit more complicated like in all other markup languages I know of:

You most probably won't type a table like this outside of Emacs. The manual alignment without tool-support is very tedious. But even here you are able to deliver a perfectly fine Org-mode table by simply ignoring the alignment altogether:

Pandoc lists six different Markdown flavors as output formats. This is an absolutely bad situation which foils the original idea behind lightweight markup languages. When some web service tells me that I can use "Markdown" for a text field, I have to dig deeper to find out which of those many different Markdown standards the web page is talking about. After this I will have to continue and look for a cheat-sheet of this dialect because nothing is more difficult to differentiate than multiple standards that are almost the same but not really the same. A usability hell. I get furious every time I have to enter this hell.

With Org-mode, life is easy. The snippet from the previous section explains all there is. Any tool that interprets Org-mode accepts this simple and easy to remember syntax.

Org-Mode Is Consistent

Many lightweight markup languages do offer multiple ways of typing headings. There are basically three ways of defining headings:

I prefer the prefix heading style. Org-mode use this as well with * as prefix characters. The more asterisks, the deeper the level of the heading is.

Pre- and postfix headings do offer bad usability. The user has manually synchronize the number of prefix character with the number of postfix characters. And it is totally unclear how something like = heading == with different numbers of pre/postfix characters is going to turn out when being interpreted.

And in case the user already used a markup language with simple prefix headings, it is not logical why there is the need for the postfix characters at all.

Even worse than this is the underlined heading category. The user is completely irritated for multiple reasons. Besides the tedious manual work to align the stupid heading characters with the heading title, it is not clear what characters must be used for those heading lines. If you've got a bigger document with different levels of headings you get confused which heading character stands for which heading level.

Are the tilde characters level one? Or was it the equals characters? And how about asterisks? Without a cheat-sheet, the occasional markup user is completely lost.

This gets even more worse: some markup languages let you choose your "order" of heading characters. This results in weird situations. For example one author is starting to write a reStructuredText document using her favorite heading syntax. A second author is joining in and has to analyze the document in order to know what heading syntax he must use.

You can visualize the hierarchy of the section adornments in the
current buffer by invoking rst-display-adornments-hierarchy, bound
on C-c C-a C-d. A temporary buffer will appear with fake section
titles rendered in the style of the current document. This can be
useful when editing other people's documents to find out which section
adornments correspond to which levels.

Yes, you got it right, it is true: this function's only purpose is to generate a dummy-hierarchy of headings to visualize which markup has to be used for heading 1, which one for heading 2 and so forth just for this single document. What a bad design decision of the markup when you need such hacks just to know how a heading should look like in a markup even if you are familiar with in the first place.

Here is one more: some markup languages even allow mixed heading styles. You can use an underlined heading style for heading level 1, a prefix style for level 2, another underlining style for level 3 and so forth. Now the chaos is a perfect one.

Let's have a look at a different markup element: external links. As you already remember in Org-mode, a link looks like this:

[[http://Karl-Voit.at][my home page]]

The only difficult thing here is to remember that the URL is at the beginning and the description follows after the URL. Many markup languages do add additional and unnecessary levels of difficulties.

The form is simple but for complex URLs, the [Text] might look like being part of the URL itself. Not beautiful but at least something I could live with.

Markdown:

[Text](http://example.com)
[Text](http://example.com "Title")

Brackets or parentheses first? Why using different kind of markup characters in the first place like only brackets? Is the Title part of the URL? Why not part of Text? Very confusing design decisions from my point of view.

reStructuredText:

`Text <http://example.com/>`_

Holy moly. This is some weird stuff. First, you have to grave accents ` and not apostrophes '. Then what about the underscore character at the end? This is as complicated as you can define a simple URL. I'd even prefer the hard to type HTML version of linking. A disaster for something which has "lightweight" in its class name.

Org-Mode Can Be Easily Typed

The simple syntax of Org-mode does not imply typing unnecessary characters. You don't have to manually align something like underlined headings. Anybody using a simple text editor is very fast at adding markup for headings, font variations, and so forth. The previous section proved that other markup languages clearly fail in many cases.

Org-Mode Makes Sense Outside of Emacs

You don't have to use the Emacs editor to write and work with Org-mode markup text. As I mentioned above, many people already do so just because Org-mode is an intuitive and clean way of typing text characters.

When you've got text information in Org-mode markup, you can process it with many tools. Most prominent and most important examples are files pushed within a GitHub repository and the swiss army knife named Pandoc which is able to convert Org-mode to dozens of formats like HTML, odt (LibreOffice), docx (Word), LaTeX, PDF, and so forth.

Org-Mode Has Excellent Tool Support (If You Want)

As I mentioned in the beginning, this is not an article about Emacs. Nevertheless for anybody not familiar with Emacs I have to mention that with Emacs there is a tool that supports (not only) in writing Org-mode syntax in a perfect way.

For Org-mode it is really easy to learn. Basically you just have to use TAB for toggle the collapsing and expanding of headings, lists, and blocks. It's Alt and the arrow keys to move around headings, list items, and even table columns/rows. Ctrl-Return creates a new heading or list item without the need of entering the markup characters and manually matching indentation levels at all.

That's it. With those three things you're good to write Org-mode syntax efficiently. The basic file open/save, finding help, exiting Emacs stuff is accessible with icons or the menu. No need to learn more keyboard shortcuts if you don't want to.

Having experienced this great tool-support, users typically are eager to learn more. You don't have to. You might be happy with Org-mode for capturing minutes of meetings and your shopping list. However, others do master a few additional things and write whole eBookswithin Org-mode.

Summary

Lightweight markup languages are designed to be used with a minimum effort compared to full-blown and therefore more complicated markup languages such as HTML or LaTeX.

Some are doing their job better than others. In my experience, many design decisions of widely adapted markups such as Markdown or reStructuredText (and others) are questionable from a usability point of view. At least I do have some issues when I have to use them in my daily life.

Unfortunately, I hardly see any people out there using Org-mode as a markup language outside of Emacs although there are very good reasons for it as an easy to learn and easy to use markup language.

With this blog article I wanted to point out the usefulness of Org-mode even when you are not using Emacs as an writing tool.

In this specific case, pandoc seems to have a more strict parser related to leading spaces for #-lines, or keywords. I'm pretty sure that the pandoc project accepts this issue as a bug. In doubt, the interpretation of Emacs is the definition, or golden-standard, of Org-mode syntax. Even this beta-version of a syntax definition does not mention optional spaces before keywords. The manual mentions org-element-parse-buffer and org-lint which would be most probably the best choice for defining the official standard if you would search for one.

However, this does not relate at all with the intention of this article: the design of the (basic) Org-mode syntax compared to other lightweight markup languages. All the issues mentioned where other markups show inconsistencies and usability issues where Org-mode seems to have advantages still do apply here. Completely independent of the standardization argument. My personal believe is, that if there would be more use of Org-mode syntax elements outside of Emacs, there would be a much higher pressure on formally defining Org-mode as a syntax which pandoc and even Emacs could use as the golden standard.

So far, there is not even the necessity of defining this golden standard because nobody outside of the Emacs community knows or even is using Org-mode. And this is what I tried to change a bit because other markup languages do tend to hurt my geeky soul when I do have to use them. ;-)