org-faq.org 17 KB

General

How do I keep current with Org mode development?

Org mode is developed in Git. You can keep up-to-date with Org mode developement by cloning Org mode repository and refreshing your copy with latest changes whenever you wish. You only need to use two Git commands (clone and pull.) Here are the steps in brief (please customize locations to suit your setup):

  1. Select a location to house the Org mode repository (approx. 115
  2. MB; includes documentation, compiled elisp files and history going all the way back to v4.12a)

$ mkdir $HOME/elisp && cd $HOME/elisp

  1. Clone the Org mode Git repository.

Recommended approach:

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

Alternate approach if you are behind a firewall that allows only HTTP (can be quite slow):

$ git clone http://repo.or.cz/r/org-mode.git org-mode.git

  1. Compile and install Org mode and build documentation.

$ cd org-mode.git && make && make doc && make install

Please note that you can choose to not compile at all and run using source =.el= files only. Compiled files speed things up.

  1. This is where you configure Org mode with Emacs. Please refer
  2. to [[./org-tutorials/index.org][Org tutorials]].
  1. Keeping up-to-date.

Cloning the repository is a one time activity. From this point onwards you only need to pull the latest changes.

$ cd $HOME/elisp/org-mode.git

and then

$ git pull && make clean && make && make doc && make install

  1. You should restart org mode to have the changes take effect (if
  2. you are not rebooting Emacs.) Also since the intention is to "keep up" with Org mode, you should visit ChangeLog and updated sections of documentation for latest updates (use =git log=.)

What is the difference between Org and TaskPaper?

There is really no difference. Org is as simple as TaskPaper. It is just that, when using Org within Emacs, it lets you do many things that you wouldn't be able to do with TaskPaper. Yes, TaskPaper is fiddle-proof and people using Emacs tends to like fiddling (which is orthogonal to the idea of using todo-list efficiently), but this is just a matter of discipline and common sense, not one of Org's design.

Read Carsten's enlightening statement on this.

Can I use editing features of org-mode in other modes?

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.

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 nnd also provides promotion and demotion functionality. outline-magic.el is available at Outline Magic.

How can I keep track of changes in my Org files?

Use git to track the history of the files, use a cronjob to check in changes regularly. Such a setup is described by Bernt Bernt Hansen in this message on emacs-orgmode.

Can I use the remember buffer to clock a customer phone call?

Yes, you can. Take a look at the setup described by Bernt Hansen and check out (in the same thread) what Nick Docos had to fix to make Bernt's set-up work for him.

Can I implement a GTD workflow with Org-mode?

Yes, you can. Check for discussions and pointers here.

How can I cycle through the TODO keyword of an entry?

C-c C-t or S-<left/right> is what you need.

How can I quickly set the tag of an entry?

Use C-c C-c on the headline.

Can I select the TODO keywords with a tag-like interface?

Yes. Use (setq org-use-fast-todo-selection t)

M-x visible-mode will display the full link, making them searchable.

C-k is killing whole subtrees! I lost my work!

(setq org-special-ctrl-k t) before losing your work.

How can I set up automatic reminders based on Org information?

See this post by N. Dokos on the list.

I want to add my Org scheduled/deadlined entries in my diary!

Put this in your ~/.diary:

:&%%(org-diary :scheduled :timestamp :deadline)

How do I track state changes for tasks in Org?

Take a look at the post by Bernt Hansen for setting up TODO keyword states and logging timestamps for task state changes.

Errors

When I try to use Org-mode, I always get the error message (wrong-type-argument keymapp nil)

This is a conflict with an outdated version of the allout.el, see the Conflicts section in the manual

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.

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

Yes, see the Conflicts section of the manual.

Is there a good way to create a description list?

Yes, these are now built-in:


- item1 :: Description of this item 1
- item2 :: Description of this item 2
- item1 :: Description of this item 3
      also in multiple lines

Setup and Structure

Can I use Org-mode as the default mode for all README files?

Add the following to your .emacs file:

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

You can even make it the default mode for any files with unspecified mode using

(setq default-major-mode 'org-mode)

Emacs outlines are unreadable. Can I get rid of all those stars?

See the section Clean outline view in the manual.

Can I have two windows on the same Org-mode file, with different outline visibilities?

You may use indirect buffers which do exactly this. See the documentation on the command make-indirect-buffer.

How can I insert an empty line before each newly inserted headline, but not before each newly inserted plain-list item?

(setq org-blank-before-new-entry
      '((heading . t) (plain-list-item . nil))

How can I reduce the amount of context shown is sparse trees?

Take a look at the variables org-show-hierarchy-above and org-show-following-headline.

How can I combine the results of two calls to org-occur?

You can construct a regular expression that matches all targets you want. Alternatively, use a C-u prefix with the second and any further calls to org-occur to keep the current visibility and highlighting in addition to the new ones.

Hyperlinks

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

: 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

(setq org-confirm-shell-link-function 'y-or-n-p
      org-confirm-elisp-link-function 'y-or-n-p).

Then a single keypress will be enough to confirm those links. It is also possible to turn off this check entirely, but I strongly recommend against this. Be warned.

Yes, this is how:

(setq org-return-follows-link t)
(setq org-tab-follows-link t)

Activating links with mouse-1 is a new feature in Emacs 22, to make link behavior similar to other applications like web browsers. If you hold the mouse button down a bit longer, the cursor will be set without following the link. If you cannot get used to this behavior, you can (as in Emacs 21) use mouse-2 to follow links and turn off link activation for mouse-1 with

(setq org-mouse-1-follows-link nil)

Remember

Can I automatically start the clock when opening a remember template?

Yes, this is possible. Use the following code and make sure that after executing it, `my-start-clock-if-needed' is in `remember-mode-hook' after `org-remember-apply-template'.

(add-hook 'remember-mode-hook 'my-start-clock-if-needed 'append)
(defun my-start-clock-if-needed ()
  (save-excursion
    (goto-char (point-min))
    (when (re-search-forward " *CLOCK-IN *" nil t)
      (replace-match "")
      (org-clock-in))))

Then, when a template contains the key string CLOCK-IN, the clock will be started. Starting with Org-mode version 5.20, the clock will automatically be stopped when storing the remember buffer.

Export

Can I get TODO items exported to HTML as lists, rather than as headlines?

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; ...

Can I export only a single subtree?

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.

How can I get Mac OSX 10.3 iCal to import my Org-exported .ics files?

When using iCal under Apple MacOS X Tiger, you can create a new calendar OrgMode (the default name for the calendar created by C-c C-e c, see the variables org-icalendar-combined-name and org-combined-agenda-icalendar-file). Then set Org-mode to overwrite the corresponding file ~/Library/Calendars/OrgMode.ics. You may even use AppleScript to make iCal re-read the calendar files each time a new version of OrgMode.ics is produced. Here is the setup needed for this:

(setq org-combined-agenda-icalendar-file
    "~/Library/Calendars/OrgMode.ics")
(add-hook 'org-after-save-iCalendar-file-hook
 (lambda ()
  (shell-command
   "osascript -e 'tell application \"iCal\" to reload calendars'")))

How can I get Mac OSX 10.4 or later iCal to import my Org-exported .ics files?

For Mac OS X 10.4, you need to write the ics file to /Library/WebServer/Documents/ and then subscribe iCalendar to http: //localhost/orgmode.ics

Tables

Can I plot data from a table?

Yes, you can, using a combination of export and gnuplot. James TD Smith explains how in this post.

Why does my table column get filled with #ERROR?

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!

How can I stop the table editor from creating new lines?

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. To move to the line below the horizbntal line instead, do this:

Press down (to get on the separator line) and then TAB. Or configure the variable

(setq org-table-tab-jumps-over-hlines t)

How can I get tabe fields starting with "="?

With the setting

(setq org-table-formula-evaluate-inline nil)

this will no longer happen. You can still use formulas using the commands @C-c =@ and @C-u C-c =@

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.

In my huge table the realigning after each TAB takes too long. What can I do?

Either split the table into several by inserting an empty line every 100 lines or so. Or turn off the automatic re-align with

(setq org-table-automatic-realign nil)

After this the only way to realign a table is to press C-c C-c. It will no longer happen automatically, removing the corresponding delays during editing.

Recalculation of my table takes too long. What can I do?

Nothing, really. The spreadsheet in org is mostly done to make calculations possible, not so much to make them fast. Since Org-mode is firmly committed to the ASCII format, nothing is stopping you from editing the table by hand. Therefore, there is no internal representation of the data. Each time Org-mode starts a computation, it must scan the table for special lines, find the fields etc. This is slow. Furthermore, Calc is slow compared to hardware computations. To make this work with normal editing, recalculation is not happening automatically, or only for the current line, so that the long wait for a full table iteration only happens when you ask for it.

So for really complex tables, moving to a "real" spreadsheet may still be the best option.

That said, there are some ways to optimize things in Org-mode, and I have been thinking about moving a bit further down this line. However, for my applications this has so far not been an issue at all. If you have a good case, you could try to convince me.

S-RET in a table keeps increasing the copied numbers. How can I stop this?

Well, it is supposed to be a feature, to make it easy to create a column with increasing numbers. If this gets into your way, turn it off with

(setq org-org-table-copy-increment nil)

Agenda

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. If you insist, however, integrating Org-mode information into the diary is 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 today contains additional entries for overdue deadlines and scheduled items. See also the documentation of the 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.

How can I make appt notice my Org appointments?

:M-x org-agenda-to-appt RET

Can I send myself an email containing tasks or other agenda info?

Yes. See this thread on the list.

COMMENT HTML style specifications