frequal.com

Emacs Org Mode for Documentation

I've heard people raving about Org Mode in emacs circles for years now. Finally I had a reason to try it lately and it absolutely lives up to the hype!

I have been using it to write documentation, specifically a book about the Flavour framework for Java-based SPAs. It easily handles the key things I want from a technical documentation authoring tool:

Good emacs integration and convenient keybindings
Chapters and Sections
Text format for easy diffs and version control
Syntax highlighting for embedded code samples
Easy publishing to HTML and PDF

Read on for tips on using Org Mode for documentation

Fundamental Organization

For a book, I wanted a main file listing the chapters, with a separate file for each chapter. In Org Mode this is easily handled with includes. Here is the code in the main file to include the first chapter:

* Introduction
#+include: "Introduction.org"

To create a heading, use M-enter.

Embedded Code Samples

To start a code sample, type C-c C-, s. Then type the kind of code (java, html, xml, etc.). Then your sample goes between the begin and end tags.

#+begin_src html
<html:text value="username" />
#+end_src

For method names or other code referenced inline, surround the code with tildes:

It launches the ~main()~ method

Easy publishing to HTML

To export to a single HTML file, type C-c C-e h h. You'll get one HTML file containing all included .org files.

For syntax highlighting in code samples to work, I had to add this at the top of my main document:

# -*- org-export-allow-bind-keywords: t -*-

Easy publishing to PDF

For a PDF file, type C-c C-e l p.

You'll need to have LaTeX installed. For me, installing LaTeX was straightforward:

sudo apt install texlive-latex-extra

Last modified on 10 Dec 2023 by AO