29 March 2013

Using Emacs org-mode to edit text files (as opposed to its intended purpose as a task organizer) makes for very civilized files.

First, they are text files and can be emailed, read on any computer without much software, grep'd, sed'd, included in a source code revision control system (RCS, Hg, Git, SVN, etc.), and compressed a lot.

Second, org-mode has excellent support for output formats, dealing especially well with HTML and LaTeX.

Third, the markup for basic editing can be learned very quickly; that's what we'll do here.

1 Getting Org

1.1 Emacs

Org is an Emacs mode, so you need Emacs and the Org package.

get emacs from ftp.gnu.org/gnu/emacs/windows/
Use Mac Ports (macports.org) (port install emacs)
get emacs via your favorite package manager

1.2 Org-mode

The Org-mode files come with the Emacs installation from ftp.gnu.org
Use Mac Ports and install the org-mode package (port install org-mode)
Either the Org-mode files will come with the Emacs you install, or you can get them from the package manager

1.3 Useful configurations

It's all emacs, so configuration is done in your ~/.emacs file.

(add-to-list 'auto-mode-alist '("\\.\\(org\\|txt\\)$" . org-mode))
(add-hook 'org-mode-hook 'turn-on-auto-fill)
(require 'org-latex)

Those three lines will:

  • enter org-mode when you open a file ending in .org or .txt
  • turn auto-fill-mode on in Emacs when you're in org-mode
  • import org-latex

You can also enter org-mode by typing Esc-x or Meta-x followed by typing org-mode.

When typing in emacs, you can re-wrap lines of text with Esc-q or Meta-q.

2 Sections, Subsections, Lists, and Formatting

2.1 Sections and Lists

  • It is plain text, so a section is set up with an asterisk * at the start of a line, a subsection is two asterisks ** at the start of a line, etc.
  • A bulleted list is started with any of a dash -, a plus +, and sublists are just indented.
  • A numbered list is started with numbers. Sub-lists with numbers are intented one or more spaces.

2.2 Example

* Section Title

  Some text that I would like to add.

  The second paragraph of the text I'd like to add.
  # this is a comment
  Here is a list
   - item one
   - item two
     - subitem one

  ** Sub-Section Title
   1. item one
   2. item two
     1. item two-sub-one

2.3 Formatting

Format What to Type
Bold * Bold *
Italic / Italic /
Fixed = Fixed =
underlined \_ underlined \_

3 Tables

3.1 Tables

| Car Make           | Cost    | City | X-factor |
| and Model          |         | MPG  |          |
| Fiat 500           | $19,000 |   30 |        6 |
| VW Bug             | $26,390 |   20 |        7 |
| Volvo C70          | $39,950 |   20 |        5 |
| Audi A5 Cabrio     | $42,000 |   22 |        9 |
Car Make Cost City X-factor
and Model   MPG  
Fiat 500 $19,000 30 6
VW Bug $26,390 20 7
Volvo C70 $39,950 20 5
Audi A5 Cabrio $42,000 22 9

4 Exports

4.1 Export Template

Move to the top of your files and type Ctrl-c, Ctrl-e then press t to insert an export template that you can edit to create a title, author, and set some export options.

The export template for the slide version of this document is these lines (plus the default lines in the export template):

#+TITLE:     Org in 4 Sections (plus a demo)
#+AUTHOR:    Andrew Caird
#+startup: beamer
#+LaTeX_CLASS: beamer
#+latex_header: \mode<beamer>{\usetheme{Frankfurt}}

4.2 PDF

Generating PDF requires a LaTeX installation.

your favorite package manager

4.3 HTML

Type Ctrl-c Ctrl-e to see the export menu and choose from one of these options:

[h] export as HTML  [H] to temporary buffer
[R] export region   [b] export as HTML and open in browser


Type Ctrl-c Ctrl-e to see the export menu and choose from one of these options:

[a/n/u] export as ASCII/Latin-1/UTF-8
[A/N/U] to temporary buffer

4.5 Pandoc

Pandoc isn't an Emacs or Org-mode tool, but it is a file conversion tool that is aware of Org-mode and can convert to and from many, many formats.

For more information, see johnmacfarlane.net/pandoc/.

From To
markdown HTML formats
reStructuredText ODT, DOCX
textile LaTeX
LaTeX Markdown, RST, AsciiDoc
etc. etc.

5 Demo and Resources

5.1 Keystrokes

esc-enter make another entry at the same level
tab open or close a section
esc-arrows indent or outdent a section
Ctrl-c Ctrl-e export the current file to another format
Ctrl-g cancel the current command
Ctrl-x Ctrl-f open a file
Ctrl-x Ctrl-s save the file
Ctrl-x Ctrl-c quit Emacs

5.2 Resources

The best resource is orgmode.org, and from there the most useful document is the 39-page document The compact Org-mode Guide, and you likely won't need all 39-pages. The full Org-mode manual is also there, but it can be quite dense.