Org-mode Frequently Asked Questions

Table of Contents

1 General

1.1 Use features in other modes

I would like to use editing features of org-mode in other modes, is this possible?

Not really. For tables there is orgtbl-mode which implements the table editor as a minor mode. For other features you need to switch to Org-mode temporarily, or prepare text in a different buffer.

1.2 Visibility cycling in Outline-mode and Outline-minor-mode

%Can I get the visibility-cycling features in outline-mode and outline-minor-mode?%

Yes, these functions are written in a way that they are independent of the outline setup. The following setup provides standard Org-mode functionality in outline-mode on TAB and S-TAB. For outline-minor-mode, we use C-TAB instead of TAB, because TAB usually has mode-specific tasks.

(add-hook 'outline-minor-mode-hook
  (lambda ()
    (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
    (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
(add-hook 'outline-mode-hook
  (lambda ()
    (define-key outline-mode-map [(tab)] 'org-cycle)
    (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))

Or check out outline-magic.el, which does this and also provides promotion and demotion functionality. @file{outline-magic.el} is available at Outline Magic.

2 Errors

2.1 (wrong-type-argument keymapp nil)

When I try to use Org-mode, I always get the error message @code{(wrong-type-argument keymapp nil)} This is a conflict with an outdated version of the allout.el.

2.2 CUA mode does not work with Org-mode

%Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict?%

Yes, see the Conflicts section of the manual.

3 Setup and Structure

3.1 Org-mode as default mode

%Org-mode seems to be a useful default mode for the various README files I have scattered through my directories%. %How do I turn it on for all README files?%

Add the following to your .emacs file:

 (add-to-list 'auto-mode-alist '("README$" . org-mode))

3.2 Get rid of extra stars in outline

%All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines?%

See the section Clean outline view in the manual.

3.3 Two windows on same Org-mode file

%I would like to have two windows on the same Org-mode file, but with different outline visibility. Is that possible?%

In GNU Emacs, you may use indirect buffers which do exactly this. See the documentation on the command make-indirect-buffer. In XEmacs, this is currently not possible because of the different outline implementation.

4 Hyperlinks

4.1 Broken links after Org-mode 4.20

%Some of my links stopped working after I upgraded to a version 4.20 or later. Why is this, and how can I fix it?%

These must be links in plain text, containing white space, such as

 bbdb:Richard Stallman

You need to protect these links by putting double brackets around them, like

 [[bbdb:Richard Stallman][bbdb:Richard Stallman]]

4.2 Converting links to double-bracket format

%I see that Org-mode now creates links using the double bracket convention that hides the link part and the brackets, only showing the description part. How can I convert my old links to this new format?%

Execute once in each Org-mode file: M-x org-upgrade-old-links This replaces angular brackets with the new link format.

4.3 Angular bracket links preference

%I don't care if you find the new bracket links great, I am attached to the old style using angular brackets and no hiding of the link text. Please give them back to me, don't tell me it is not possible!%

Would I let you down like that? If you must, you can do this

 (setq org-link-style 'plain
       org-link-format "<%s>")

4.4 Confirmation for shell and elips links

%When I am executing shell/elisp links I always get a confirmation prompt and need to type yes RET, that's 4 key presses! Can I get rid of this?%

The confirmation is there to protect you from unwantingly execute potentially dangerous commands. For example, imagine a link

[[shell:rm -rf ~/*][ Google Search]]

In an Org-mode buffer, this command would look like Google Search, but really it would remove your home directory. If you wish, you can make it easier to respond to the query by setting org-confirm-shell-link-function and/or org-confirm-elisp-link-function to y-or-n-p. Then a single yc keypress will be enough to confirm those links. It is also possible to turn off this check entirely, but I do not recommend to do this. Be warned.

5 Export

5.1 Make TODO entries items, not headlines in HTML export

%When I export my TODO list, every TODO item becomes a separate section. How do I enforce these items to be exported as an itemized list?%

If you plan to use ASCII or HTML export, make sure things you want to be exported as item lists are level 4 at least, even if that does mean there is a level jump. For example:

 * Todays top priorities
 **** TODO write a letter to xyz
 **** TODO Finish the paper
 **** Pick up kids at the school

Alternatively, if you need a specific value for the heading/item transition in a particular file, use the #+OPTIONS line to configure the H switch.

 #+OPTIONS:   H:2; ...

5.2 Export only a subtree

%I would like to export only a subtree of my file to HTML. How?%

If you want to export a subtree, mark the subtree as region and then export. Marking can be done with C-c @@ C-x C-x, for example.

6 Tables

6.1 #ERROR fields in tables

%One of my table columns has started to fill up with #ERROR. What is going on?%

Org-mode tried to compute the column from other fields using a formula stored in the #+TBLFM: line just below the table, and the evaluation of the formula fails. Fix the fields used in the formula, or fix the formula, or remove it!

6.2 Unwanted new lines in table

%When I am in the last column of a table and just above a horizontal line in the table, pressing TAB creates a new table line before the horizontal line%. %How can I quickly move to the line below the horizontal line instead?%

Press down (to get on the separator line) and then TAB Or configure the variable org-table-tab-jumps-over-hlines.

6.3 Change indentation of a table

%How can I change the indentation of an entire table without fixing every line by hand?%

The indentation of a table is set by the first line. So just fix the indentation of the first line and realign with TAB.

7 Agenda

7.1 Include Org-mode agenda into Emacs diary

%Is it possible to include entries from org-mode files into my emacs diary?%

Since the org-mode agenda is much more powerful and can contain the diary, you should think twice before deciding to do this. Integrating Org-mode information into the diary is, however, possible. You need to turn on fancy diary display by setting in .emacs:

 (add-hook 'diary-display-hook 'fancy-diary-display)

Then include the following line into your ~/diary file, in order to get the entries from all files listed in the variable org-agenda-files

 &%%(org-diary)
You may also select specific files with

 &%%(org-diary) ~/path/to/some/org-file.org
 &%%(org-diary) ~/path/to/another/org-file.org

If you now launch the calendar and press d to display a diary, the headlines of entries containing a timestamp, date range, schedule, or deadline referring to the selected date will be listed. Just like Org-mode's agenda view, the diary for @emph{today} contains additional entries for overdue deadlines and scheduled items. See also the documentation of the @command{org-diary} function. Under XEmacs, it is not possible to jump back from the diary to the org, this works only in the agenda buffer.

Author: Carsten Dominik <carsten.dominik@gmail.com>

Date: 2007/12/20 07:18:18