1

Granthinm
Blog on Open source, Digital humanities, and Sanskrit philology

Talking Org-mode
Daniel Stender Monday, February 27th, 2012

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.

Whats 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).

Radio tables within LaTeX

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 its time, push C-c C-c within the Org table to create resp. refresh the corresponding LaTeX table isnt that just marvellous?5 A basic sample document would look like this:
Granthinm -1/627.04.2012

2
\documentclass{scrartcl} \usepackage{comment}

\begin{document} Hello, world!

% BEGIN RECEIVE ORGTBL foo \begin{tabular}{lllll} Monday & Tuesday & Wednesday & Thursday & Friday \\ Rain & Rain & Rain & Rain & Rain \\ \end{tabular} % END RECEIVE ORGTBL foo

\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-modes 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:
q

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

Heres a Python script prints out a random tabular of integer pairs:

import random out="| %s | %s |"

Granthinm

-2/6-

27.04.2012

3
for x in range(0, 300): pair=(random.randrange(1000), random.randrange(1000)) print out % pair

An heres 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]

Granthinm

-3/6-

27.04.2012

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 isnt 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:
The current stable release is 23.4, but Emacs 24 is just around the corner. If you cant wait to run one of its additional features (see here), there are unofficial snapshot packages available. Many stuff Ive came across (like the Emacs Starter Kit) is already made up for Emacs 24.
1

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 OReillys Learning GNU Emacs (currently 3rd edition), and theres also a title in Sams Teach Yourself series, a complete Howto from the Linux guys, and a tutorial at IBM Developer Works. Very brief Ive 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.
2

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.
3

Theres a nice tutorial on Org tables, and a demonstration in Dominiks talk at Google Tech Talks (00:29:00 sq.), The radio table feature is demonstrated in this
4

Granthinm

-4/6-

27.04.2012

screencast here for an HTML document. 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.
5

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). Orgs 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.
6

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

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 isnt any error message when Emacs starts up it all runs properly. But much more convenient is of course to get them via el-get.
8

Of course its 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.
9

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 g i t c l o n e 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/) thats the way we like it!
10

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.
11

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.
12

This entry was posted on Monday, February 27th, 2012 at 1:00 am and is filed under
Granthinm -5/627.04.2012

Editing You can follow any responses to this entry through the Comments (RSS) feed. You can leave a response, or trackback from your own site.

Granthinm

-6/6-

27.04.2012