Using Emacs Org-mode to Draft Papers

Scientific papers are mostly written in LaTeX, a markup language for typesetting. With LaTeX, a document is programmed rather than edited in a WYSIWYG-way. There is a great deal of specialized editors or editor modes (e.g. AucTeX) simplifying the creation of LaTeX documents. In many cases, however, you just want to quickly write down what’s in your head instead of getting stuck in the details of LaTeX markup. I found that Emacs org-mode is very well suited to fill that gap. You can efficiently draft a scientific document that can directly be converted into LaTeX code which you can beautify later on. I’ll show you here how.

Installation

First, you have to install org-mode for Emacs as described here. Org-mode is included in Emacs since version 22.1 and the latest version can be obtained from the a git repository via

git clone git://repo.or.cz/org-mode.git

Be sure to use the latest version for this tutorial as there really is some active development going on and some of the features I use were included just recently.

The First Document

Begin by opening a new files with a “.org” extension. Paste the following lines into that document

The Impact of Beer Consumption on Scientific Collaboration
#+AUTHOR: Mario Fasold
* Introduction
** Previous Work
Some studies relating scientific output and beer have previously been done.
#+BEGIN_QUOTE
In Europe, most alcohol is consumed as beer and, based on well known negative effects of alcohol consumption on cognitive performance, I predicted negative correlations between beer consumption and several measures of scientific performance.
#+END_QUOTE
([[www.zoologie.upol.cz/osoby/Grim/Grim_Oikos_2008_on-line.pdf]])
* Results
** What beer should you drink
+ Becks
+ Czech Budweiser
+ Duff

The first line contains the title of your document. It will be used by each of the exporters, e.g. LaTeX or HTML. Note that there was a bug in the latex exporter, leading to duplicated text after the table-of-contents if the first line of the document was a headline. Leaving the fist line empty is the suggested workaround here.

The export can be controlled by various parameters that can be set anywhere in the org-document. The syntax is “#+OPTIONS: toc:nil”, for example (available options). Some export options that might be useful to create a paper draft include

  • #+AUTHOR: the author (default taken from user-full-name)
  • #+DATE: A date, fixed, of a format string for format-time-string
  • #+EMAIL: his/her email address (default from user-mail-address)

Using the very simple org-mode markup, the document then defines some sections, subsections, textblocks and formulas. Note that only the first three outline levels (* – ***) are used for headlines by default. Using the markup you can easily define lists, include other files, enter footnotes, define literal and source code blocks (and even use Emacs font-lock for those areas) and more. For example, a text literal is inserted via

#+BEGIN_EXAMPLE
Some example from a text file.
#+END_EXAMPLE

and the following passes code directly into latex

#+BEGIN_LaTeX
All lines between these markers are exported literally
#+END_LaTeX

Another honored mention be the org-tables mode which lets you create and edit and tables in a dead-easy manner (try to swap a table column in AucTeX…).

Figures

Papers and their drafts can’t live without images in most cases. The following syntax allows since december to insert one

#+CAPTION: Degradation Plot
#+ATTR_LaTeX: scale=0.75
#+LABEL: fig:degradation
[[./images/DegradationPlot.png]]

It’s a little buggy still, for example, no underscores seem to be allowed within filenames for now. For more complex cases, you can just write the LaTeX-code (org-mode will recognize many identifiers):

\begin{figure}[!tpb]
\centerline{
\includegraphics[scale=0.3]{images/BeerPlot}
}\caption{This is plot looks like a beer.}\label{fig:Beer}
\end{figure}

References

You may also want to include references while drafting the paper. Luckily, you can use RefTex-Mode (included in Emacs) to scan your BibTeX-file (containing the bibliographies) and easily insert a reference to an entry of that file. First, activate RefTex in org-mode by inserting the following lines into .emacs:

(defun org-mode-reftex-setup ()
(load-library "reftex")
(and (buffer-file-name)
(file-exists-p (buffer-file-name))
(reftex-parse-all))
(define-key org-mode-map (kbd "C-c )") 'reftex-citation)
)
(add-hook 'org-mode-hook 'org-mode-reftex-setup)

Second, include the BibTeX-file by inserting

\bibliographystyle{plain}
\bibliography{ProbePosition}

at the end of your org-document. When you want to insert the reference just invoke “C-c )”, enter a search term (e.g. auther name) and select the right one from the search results. Note: When first opening the org document, RefTeX will ask you to give him the name of the “master” which is the .tex-file corresponding to your org-file.

You can also use org-mode to collect notes about all the publications you are reading. Stick to this description to find out how you could manage bibliographies and PDF-documents in a nice way.

Outlook

Org-mode is a very versatile and extensible mode for Emacs. If Emacs is considered an Operating System, consider Org-mode as the Emacs for that system! I find org-mode particularly handy to draft papers. Include images, formulas, tables and references with ease, without the hassle of dealing with LaTeX markup.

Additionaly, you might use org-mode to organize related links, documents and data. With org-R you can even do any computations (e.g.statistics) and plots in-line using R – no need to fragment your information! Also, expect to see nice features appearing for org-mode frequently. I would be glad to hear how you use org-mode to collect information and do science!

Ps. Someone even wrote his complete diploma thesis with org-mode. He describes his experience here (his org-file is a good example, too).

24 Responses to “Using Emacs Org-mode to Draft Papers”

  1. I use org-mode for writing papers and my master’s thesis, haven’t used reftex-mode much yet, but it looks very useful. I do use bib-cite-minor-mode though, which works very well in org-mode (when \cite{foo} is selected, the minibuffer shows citation info).

    Two questions:
    - why use load-library instead of just (reftex-mode t)?
    - why redefine the key of reftex-reference (`C-c )’) to
    reftex-citation, which is already bound to `C-c [’ ?

  2. By the way, since I open a lot of org-agenda-files on emacs startup and don’t want those complicated LaTeX-modes in all of them, I use the following little hack:

    (add-hook ‘org-mode-hook
    (lambda ()
    (if (member “WRITE” org-todo-keywords-1)
    (org-mode-article-modes))))

    where

    (defun org-mode-article-modes ()
    (reftex-mode t)
    (bib-cite-minor-mode t)
    (and (buffer-file-name)
    (file-exists-p (buffer-file-name))
    (reftex-parse-all)))

    org-todo-keywords-1 is the buffer-local list of todo-keywords, so only files with “WRITE” as a todo-keyword get article modes.

  3. Hi Kevin,

    I’ using load-library instead of (reftex-mode t) (or (turn-on-reftex)) as i don’t really want to activate the reftex minor mode within org-mode. Doing so, would overwrite various keybindings of org-mode, for example C-c ]. Which also answers your second question: C-c ] is already bound to org-remove-file but C-c ) isn’t.

    So what i essentially do is to enable the reftex-citation function in org-mode, while you activate the reftex minor mode. Hence i there is no need for the little hack for me. However, I would say it’s a matter of taste which version to use.

    Ps. Sorry for the late response but i migrated the webserver today.

  4. [...] fancy plot? But chill, there is a way to avoid the joyless seeking and re-finding. At least if you draft your papers in org-mode, as i described in a recent [...]

  5. [...] http://www.mfasold.net/blog/2009/02/using-emacs-org-mode-to-draft-papers/ a few seconds ago from xmpp [...]

  6. Het there, I think you’ll call me god when you’ll see this create a free flash website

  7. Works like a charm! I’m getting tired of keeping my notes in org-mode, then going and composing a separate LaTeX document to summarize my findings. I think I’m going to use this for the bulk of writing my dissertation.

  8. Wassup I appreciate the last cool entry. It sure was really interesting.

  9. Thanks for the writeup. I’m using org-mode now to write my dissertation!

  10. [...] 这个方法是 Marios Braindump 的博客里介绍的,具体方法如下: [...]

  11. Hello, could you just show what’s the Org source with some citations? I can’t get this working. Failing with messages such as “tex-main-file: Wrong type argument: stringp, nil” while everything should be there, as described here and in the link to “this description”. BTW, Emacs never asks me about the master file. Maybe that’s the clue, but…???

  12. The code for using the BibTeX bibliography is shown in the blog post and inserting a reference via C-c ) produces something like “\cite{Fasold2010}”. Unfortunately, I cannot see what might lead the error you are having. But you are right, as long as Emacs does not ask for the TeX Master, the org-mode hook is not working correctly. Check if oy see “Loading reftex…done” in your messages buffer.
    And if problems persist, you might want to consider one of the alternative approaches described here.

  13. [...] a good starting point, Mario shares some nice ideas on how to integrate RefTeX and org-mode in order to create a scientific word [...]

  14. [...] followed a few guides on how other people used org-mode and reftex to do so. Specifically this post, and this email. My hope with this initial post is to pull the bits together, show what I built on [...]

  15. [...] a cite{Key} LaTeX command instead of an org-mode command [[cite][key]]. However, by adapting Mario’s code for RefTeX integration with Org, I came up with this simple piece of elisp that fixes this issue [...]

  16. Hello there Mario (and others),

    Mario; excellent blog. I want to get the same functionality working, but am stuck.
    I’ve only just discovered org-mode in the last few weeks and am now drafting my first paper using org-mode and the export to tex feature, but I can’t get this org-mode reftex integration to work. I have a similar problem to Fabrice.
    reftex is working fine in tex mode, I have the following in my .emacs

    (require ‘tex-mode)
    ;;; Toggle auto-fill-function on
    (toggle-text-mode-auto-fill)
    ;;; switches on reftex when entering tex-mode.
    (add-hook ‘tex-mode-hook ‘reftex-mode)
    ;; master bibliography
    (setq reftex-default-bibliography ‘(”/home/rob/phd/library/biblio”))

    and org mode is successfully exporting to latex but when I open the org file using your code snippet in my .emacs file
    (defun org-mode-reftex-setup ()
    (load-library “reftex”)
    (and (buffer-file-name)
    (file-exists-p (buffer-file-name))
    (reftex-parse-all))
    (define-key org-mode-map (kbd “C-c )”) ‘reftex-citation)
    )
    (add-hook ‘org-mode-hook ‘org-mode-reftex-setup)

    I always get the File mode specification error: (wrong-type-argument stringp nil) error. My *messages* buffer reports,

    Loading reftex…done
    File mode specification error: (wrong-type-argument stringp nil)

    I’ve tried exporting to latex then re-opening the .org file but I still get the same error. I’ve tried all the different variants mentioned in the links but always end up with the same error. Has anyone any ideas what’s going on? Can anyone help?

    Regards

    Rob

  17. I was doing some more poking around last night (I really want this to work) and I have a workaround. But I don’t think it’s normal behaviour.

    When I first open the org file I get the
    File mode specification error: (wrong-type-argument stringp nil)
    error and “C-c )” is described as undefined. If I then export to latex “C-c C-e l”, I can then use the reftex functionality within the org file. Excellent.

    But if I close down the org file and reopen the C-c ) fails again until I re-export to latex.

    So I can get the functionality but I feel this is not correct behaviour.

    Regards

    Rob

  18. Interesting, for me it works under different tested emacs versions. My first guess is that this problem is related in the way you instantiate org-mode. I run the follwing lines in my .emacs before defining the hook


    (add-to-list 'load-path "~/site-lisp/org-mode/lisp")
    (require 'org-install)
    (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))

  19. Thanks for the response Mario.

    I have the same, except for the first line. I don’t have that directory and when I try and > locate “org-mode/lisp” I get no hits. I’ve tried the same setup on my laptop (ubuntu) as opposed to my work machine (fedora ) and I get the same problem. Stange.

    Not to worry, I’m happy enough cause I can just refresh the .tex file and all is good. Often my emacs session will stay open for days anyway.

    Regards and once again thanks for your time,

    Rob

  20. [...] notes. You can preview them on the fly, too. And this way Org-Mode also becomes the best tool for drafting papers, [...]

  21. You can also use the #+title: header ;)

  22. Here http://tex.stackexchange.com/a/54211/5701 are some further notes on drafting with Org-mode.

  23. Thanks for this indeed useful collection of hints.

  24. Marios Braindump » Using Emacs Org-mode to Draft Papers I was suggested this blog by my cousin. I’m not sure whether this post is written by him as nobody else know such detailed about my trouble. You’re amazing! Thanks! your article about Marios Braindump » Using Emacs Org-mode to Draft PapersBest Regards Yoder