Org-mode with the `ox-twbs` package

How I use org-mode for notes and document creation

Intro

Rationale

Over the years I've developed a small passion for improving my workflow for document and note creation. Moving back to Emacs several years ago renewed my interest in org-mode, and I've enjoyed both the in editor experience, along with the quality export options so that you communicate your ideas with others.

Audience

Anyone mildly familiar with using Emacs and org-mode, who is interested in improving their workflow and quality of published documents. Experienced org-mode users are likely to not learn anything new. Those unfamiliar with Emacs might want to first engage in other exercises which help you get aquainted with the editor.

Pre-requisites

If you'd like to follow along with steps in this how-to, you'll need a working version of Emacs along with the package ox-twbs (which I wrote) that attempts to improve the quality of HTML export for org-mode.

Goal

We will create a document step-by-step, and at each step, I'll provide the org-mode source, along with a screenshot of the exported HTML. The subject of the document we create isn't important, but as opposed to lorem-ipsum type content, I've somewhat randomly chosen the subject to be a computer science paper written by Phil Bagwell on Fast and Space Efficient Trie Searches. Let's assume we were taking notes on this paper with the understanding we might want to eventually share our work.

Create an Outline

Preface

Let's go through my process for creating a basic document or note that we might intend to share. Throughout the process we'll examine the exported output in HTML, and I'll include screenshots if you're not following along with your own document.

Add a Title

First create a new org-mode document with bagwell.org as the filename. I always want to give my document a title first, and maybe a brief outline, so add something like the following example to your org-mode file, then export the document and open it in your browser. The results should look like the figure below.

#+TITLE: Efficient Trie Searches

* Summary

* Links

TOC and Footer

We've got our title and headings, but what is that other stuff? By default the table-of-contents and footer are included. You can disable these on at a global, project or a per document level. Below is an example of disabling the toc and footer at the document level. Consult the org-mode docs for more info about general and HTML specific export settings.

#+TITLE: Efficient Trie Searches
#+OPTIONS: html-postamble:nil toc:nil

* Summary

* Links

Figure 2: Without table of contents and footer.

Add Text and List

Next we'll fill in the sections a bit. I'll include some examples of italics, links and lists.

#+TITLE: Efficient Trie Searches

* Summary

It's my understanding Bagwell's work was important in the development
of the so called /persistent data structures/ popularized by the
Clojure programming language. I hope to learn a bit more about this
history by reading the paper Fast and Space Efficient Trie Searches.

* Links

- https://en.wikipedia.org/wiki/Persistent_data_structure
- https://en.wikipedia.org/wiki/Hash_array_mapped_trie

Figure 3: Our document with a bit of meat on the bones.

Add Notes

Let's add a notes section, and I'll include some inline LaTeX, a quote block and a source code block. Since adding blocks is common, check out these shortcuts for quickly adding blocks.

Please note, in example below, I had trouble escaping the code block, so replace #+ END_SRC with #+END_SRC.

* Notes

Interesting quote in the intro:

#+BEGIN_QUOTE
These algorithms were originally conceived as the basis for fast
scanners in language parsers where the essence of lexicon recognition
is to associate a sequence of symbols with a desired semantic.
#+END_QUOTE

Points out the space inefficiencies of a naive / directly indexed
m-way trie, where you take the ordinal value of each letter in the
key. Space is proportial to $s^p$ where $s$ is alphabet cardinality,
and $p$ is length of the keys.

Bagwell describes a simple search function which starts at the root
node and proceeds through each sub-trie until it fails or reaches the
value.

#+BEGIN_SRC c
  // Generic Key Search in a trie based Dictionary
  int Find(char *Key) {
      TNode *P,*C;
      P=Root;
      while (C=Next(P,*Key)) { Key++; P=C; }
      if (*Key==0) return P->Value;
      return 0;
  }
#+ END_SRC

This isolates the area which we want to make more efficient to the
=Next(node, key)= function which is responsible for finding the /next/
sub-trie.

Figure 4: Our document with a quote, code block and LaTeX.

A Final Trick

At this point I'm realizing there is so much more I'd like to say, I'll reserve that to a "part two" blog. But I'll end this with one of my new favorite org-mode tricks.

You can execute source code within Org-mode via Babel, and have the results of evaluation included in the document. This extends to my favorite graph / diagram language, dot. Let's add a very simple digraph to our document.

* Quick Graph to Show Off

#+BEGIN_SRC dot :file img/bagwell-digraph.png :cmdline -Kdot -Tpng
  digraph {
          a -> b
  }
#+ END_SRC

#+RESULTS:
file:img/bagwell-digraph.png

Figure 5: Our document with a dot-lang digraph.

Conclusion

I hope this was helpful and look forward to writing a second part with some more examples of how I work with org-mode. And here is a link to our finished document.

Org-mode with the ox-twbs package