## Talking Org-mode

One of the advantages of the Emacs1 editor is that there are much great extensions available2. Among them, one of the true gems is definitely Org-mode (thanks Manuel for pointer!). The developers of Org are proud that their extension actually brought many people to deal with the Emacs, and thereafter to discover its ingenuity. Emacs’ high availability and expandability through Elisp is certainly of its advantages, and it acts like a cross-OS virtual machine for applications which have been putted on this Editor as a platform.

## What’s Org-mode?

Org-mode3 (stable: 7.8.03) is a Emacs major mode which basically is a ultra versatile plain text outliner for taking notes. If one likes to gain an overview of Org, the huge capabilities are confusing at first. A reason for this is that Org is pretty much open in its scope, and people are using it for different tasks, as note taker, organizer, scheduler, for to-do-lists, project management, etc. etc. But in this post, I would like to focus mainly on Org as a publishing platform. Some features of Org are capable of achieving fancy things, even if Org is seen as a mere frontend to HTML or LaTeX, and even for your blog with Org2blog (see below).

A remarkable feature of Org is the build-in table editor which provides auto-alignment-as-you-write, easy rearrangement and also spreadsheet capabilities. The table mode is setted up as a minor mode (orgtbl-mode) and therefore it could be also employed for any non-Org documents (e.g. HTML or LaTeX source files) through its create-within-comment facility (“radio tables”)4. Tables within LaTeX are a real pain to create without any helpers, and orgtbl comes pretty handy for that: in a random LaTeX document, a radio table skeleton could be inserted through M-x orgtbl-insert-radio-table (a comment.sty environment is used to wrap the source table). After that, activate the minor mode through M-x orgtbl-mode and start writing the table source within the comment environment. When it’s time, push C-c C-c within the Org table to create resp. refresh the corresponding LaTeX table – isn’t that just marvellous?5

A basic sample document would look like this:

\documentclass{scrartcl}
\usepackage{comment}

\begin{document}
Hello, world!

\begin{tabular}{lllll}
Monday & Tuesday & Wednesday & Thursday & Friday \\
Rain & Rain & Rain & Rain & Rain \\
\end{tabular}

\begin{comment}
#+ORGTBL: SEND foo orgtbl-to-latex :splice nil :skip 0
| Monday | Tuesday | Wednesday | Thursday | Friday |
| Rain   | Rain    | Rain      | Rain     | Rain   |
\end{comment}

\end{document}


## Babel

Org-mode has several outstanding features, and among them its environment for literate programming, Babel, could be emphazised to demonstrate Org-mode’s incredible functionality. Within an Org document, source code could be written directly into to literal environments or even hot-included from external files into code blocks. From these it could be included to and excluded from into the same document to do really fancy things like to hot-create diagrams for example (this is comparable to what Aditya Mahajan achieves with his Filter module for ConTeXt). Any code could be executed interactively or on-publish-time, it could be tangled (extracted) in a structured way into individual source code files and woven (exported) into the exported document in the same process. A feature likes this comes pretty useful e.g. when you are writing about code for a journal article, but it all goes much further like into reproducible research papers. Thus, even as a publishing frontend Org-mode develops an enormous potential.

For a little demonstration, please check out the following setup:

• a Python source block puts out a list of 300 random integer pairs,
• a Gnuplot code block takes them over and puts out an graph from these,
• both code blocks get executed when the export happens,
• the Python source is printed out,
• while the Gnuplot source block gets replaced by the resulting image:6

Here’s a Python script prints out a random tabular of integer pairs:

import random
out="| %s | %s |"
for x in range(0, 300):
pair=(random.randrange(1000), random.randrange(1000))
print out % pair


An here’s the resulting graph:

By the way, here are the preceeding lines of the Org source:7

Here's a Python script prints out a random tabular of integer pairs:

#+srcname: foo
#+begin_src python :results output raw :exports code
import random
out="| %s | %s |"
for x in range(0, 300):
pair=(random.randrange(1000), random.randrange(1000))
print out % pair
#+end_src

An here's the resulting graph:

#+begin_src gnuplot :var data=foo :file gnuplot.png :exports results
reset
set terminal png size 500,375
plot data u 1:2 notitle
#+end_src

By the way, here are the preceeding lines of the Org source:[7]


## Org2blog

Furthermore, I would like to point right further to the extension Org2blog, which provides export to WordPress directly from the running Org mode. It might not be so interesting to publish your checkboxed todo-lists on your blog, but when it comes to how elegant Org handles features like sections, links, footnotes, etc. it really makes up a deluxe editing frontend for WordPress, plus, of course the features which have been discussed here so far could be forwarded directly to your blog easily with that extension.

Unfortunately, Org2blog isn’t available through the package management so far (see here), so it must be installed manually. Basically, there are three ways to do so,

1. you could clone the repositories of Org2blog (and the needed Elisp implementation of XML-RPC) somewhere into the Emacs search path 8,
2. you could get the ELPA extension retrieval package.el into charge 9,
3. and finally, you could use el-get for retrieving the add-ons 10.

After Org2blog has been got and proper configured 11, you can publish from the running Org file directly with M-x org2blog/wp-post-buffer-and-publish 12. Actually, this post was created with Org-mode and Org2blog.

## Footnotes:

1 The current stable release is 23.4, but Emacs 24 is just around the corner. If you can’t wait to run one of its additional features (see here), there are unofficial snapshot packages available. Many stuff I’ve came across (like the Emacs Starter Kit) is already made up for Emacs 24.

2 For working with Emacs of course the manual is essential. Within a running Emacs, press C-h t to open the build-in tutorial. The classic introduction is O’Reilly’s Learning GNU Emacs (currently 3rd edition), and there’s also a title in Sam’s Teach Yourself series, a complete Howto from the Linux guys, and a tutorial at IBM Developer Works. Very brief I’ve found is the tutorial at the University of Chicago Library, and very useful also is the PocketReference. PeepCode features a great screencast on Emacs, which gives a great overview even over the advanced stuff.

3 Among the Org documentation there is a compact guide next to the much more detailed manual. Very useful also the the Refcard. There are several introductions, tutorials and screencasts available (see here), among them the talk of Carsten Dominik at Google Tech Talks provides a great overview of the different functions of Org. A fine German article could be found in Das freie Magazin 10 of 2009 (p. 18 sq.), and another very easy written English article could be found in the Linux Journal of 2007. Everything within Emacs is documented out, so you just have to M-x org-info to reach the build-in documentation. By the way, current Pandoc features Org as output format.

4 There’s a nice tutorial on Org tables, and a demonstration in Dominik’s talk at Google Tech Talks (00:29:00 sq.), The radio table feature is demonstrated in this screencast here for an HTML document.

5 The table source can be placed anywhere in the same document, and this feature has some further options like splicing if you have your own table headers (see here). By the way, the same is also possible for lists.

6 Gnuplot must be added to the default support for Elisp by altering the variable org-babel-load-languages in your .emacs file, please see this page here (the package of Gnuplot as well as gnuplot-mode must be installed). Org’s support for Gnuplot is well documented, see here. By the way, the Org feature Org-Plot is capable of running Gnuplot on any tabular data with a single preceding #+PLOT: line.

7 Please remark that I’ve hot-re-included the same document, just giving a line range. I’ve got that idea from this blogposting here.

8 First, save xml-rpc.el into ~/.emacs.d/, or better /usr/local/share/emacs/site-lisp/. After that, clone the Git repository of Org2blog with git clone http://github.com/punchagan/org2blog.git into the same folder (to expand also the subdir, copy also /usr/share/emacs/site-lisp/subdirs.el here). Then, both extensions must be activated by putting (require 'xml-rpc) and (require 'org2blog-autoloads) into ~/.emacs/ . When there isn’t any error message when Emacs starts up it all runs properly. But much more convenient is of course to get them via el-get.

9 Of course it’s more convenient to retrieve Elisp extensions through a build-in management. Actually, the add-on manager package.el, which queries the Emacs Lisp Package Archive (ELPA) and other repositories is going to be included into Emacs 24. On the ELPA package management, see this blog posting here.

10 el-get is capable to recognize individual code repositories. It is available as a package for current Ubuntu, but the current stable (3.1) brings some new features like list-packages (see here) – so the best idea would be to git clone https://github.com/dimitri/el-get into /usr/local/share/emacs/site-lisp/ instead. After that, (require 'el-get) and (el-get 'sync) (for automatic inits) must be added to ~/.emacs/. Retrieval information (“recipes”) for both extensions, xml-rpc-el as well as org2blog, are already included, so all you have to do within Emacs is to do M-x el-get-install for each package to retrieve it (BTW, they go into ~/.emacs.d/el-get/) – that’s the way we like it!

11 The contact information about your blog(s) have to be given to the variable org2blog/wp-blog-alist with at least url and username, and a good place would be also to store that into ~/.emacs/. The outline of this variable could be checked through C-h v org2blog/wp-blog-alist. For an example configuration, please check out the Org2blog README.

12 On the side of WordPress, Remote publishing: XML-RPC in wp-admin/options-writing.php must be checkboxed. There are meta tags like #+TITLE: and #+CATEGORY: available for your postings, please see the Org2blog README.

Hi Daniel, great article! I was planing a posting on org-mode for some time, but that would never have reached the depth of your presentation.

Actually I wrote my magister thesis as an org-mode file, which gave me all the advantages of org’s functionality for planing tasks, logging work aso. With a bit of tweaking you can even use reftex directly in org files.

I see also a great potential in org babel for philological work. You could work with portions of edited texts in TEI embedded in your org file. When you export the whole thing to LaTeX you can have a script extracting the relevant information and setting it with ledmac.

Keep up the good work!

[Thanks very much for appreciation and again, this marvelous pointer. Org is truly one of these things that could you make addicted to. It already took over large portions of my workflow and, just to begin with, I cannot imagine writing blog postings and taking notes without it, whatshowever! Greetings, Daniel]

[...] general org-mode examples, including org2blog [...]