swflint
/
org-mode-mirror


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
lang="en" xml:lang="en">
<head>
<title>Org-mode Frequently Asked Questions</title>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
<meta name="generator" content="Org-mode"/>
<meta name="generated" content="2008/02/12 12:28:14"/>
<meta name="author" content="Carsten Dominik"/>
<link rel=stylesheet href="freeshell2.css" type="text/css">
</head><body>
<h1 class="title">Org-mode Frequently Asked Questions</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<ul>
<li><a href="#sec-1">1 General</a>
<ul>
<li><a href="#sec-2">1.1 Use features in other modes</a></li>
<li><a href="#sec-3">1.2 Visibility cycling in Outline-mode and Outline-minor-mode</a></li>
</ul>
</li>
<li><a href="#sec-4">2 Errors</a>
<ul>
<li><a href="#sec-5">2.1 <code>(wrong-type-argument keymapp nil)</code></a></li>
<li><a href="#sec-6">2.2 CUA mode does not work with Org-mode</a></li>
<li><a href="#sec-7">2.3 <code>winddmove.el</code> does not work with Org-mode.</a></li>
</ul>
</li>
<li><a href="#sec-8">3 Setup and Structure</a>
<ul>
<li><a href="#sec-9">3.1 Org-mode as default mode</a></li>
<li><a href="#sec-10">3.2 Get rid of extra stars in outline</a></li>
<li><a href="#sec-11">3.3 Two windows on same Org-mode file</a></li>
<li><a href="#sec-12">3.4 Insert empty lines before new headings and plain list items</a></li>
<li><a href="#sec-13">3.5 Amount of context in sparse trees</a></li>
<li><a href="#sec-14">3.6 Stacking calls to org-occur</a></li>
</ul>
</li>
<li><a href="#sec-15">4 Hyperlinks</a>
<ul>
<li><a href="#sec-16">4.1 Confirmation for shell and elisp links</a></li>
<li><a href="#sec-17">4.2 Use RET or TAB to follow a link</a></li>
<li><a href="#sec-18">4.3 Clicking on a link without activating it</a></li>
</ul>
</li>
<li><a href="#sec-19">5 Remember</a></li>
<li><a href="#sec-20">6 Export</a>
<ul>
<li><a href="#sec-21">6.1 Make TODO entries items, not headlines in HTML export</a></li>
<li><a href="#sec-22">6.2 Export only a subtree</a></li>
<li><a href="#sec-23">6.3 How to import org-mode calendar data into Mac OSX ical</a></li>
</ul>
</li>
<li><a href="#sec-24">7 Tables</a>
<ul>
<li><a href="#sec-25">7.1 #ERROR fields in tables</a></li>
<li><a href="#sec-26">7.2 Unwanted new lines in table</a></li>
<li><a href="#sec-27">7.3 Automatic detection of formulas</a></li>
<li><a href="#sec-28">7.4 Change indentation of a table</a></li>
<li><a href="#sec-29">7.5 Performance issues with table alignment</a></li>
<li><a href="#sec-30">7.6 Performance issues with table calculation</a></li>
<li><a href="#sec-31">7.7 Incrementing numbers</a></li>
</ul>
</li>
<li><a href="#sec-32">8 Agenda</a>
<ul>
<li><a href="#sec-33">8.1 Include Org-mode agenda into Emacs diary</a></li>
</ul>
</li>
</ul>
</div>

<div class="outline-2">
<h2 id="sec-1">1 General</h2>


<div class="outline-3">
<h3 id="sec-2">1.1 Use features in other modes</h3>

<p><b>I would like to use editing features of org-mode in other modes, is  this possible?</b> 
</p>
<p>
Not really.  For tables there is <code>orgtbl-mode</code> 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.
</p>

</div>

<div class="outline-3">
<h3 id="sec-3">1.2 Visibility cycling in Outline-mode and Outline-minor-mode</h3>


<p>
<b>Can I get the visibility-cycling features in outline-mode and outline-minor-mode?</b> 
</p>
<p>
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 <code>TAB</code> and <code>S-TAB</code>.  For
outline-minor-mode, we use <code>C-TAB</code> instead of <code>TAB</code>,
because <code>TAB</code> usually has mode-specific tasks.
</p>
<p>
<pre>
(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)))
</pre>
</p>
<p>
Or check out <i>outline-magic.el</i>, which does this and also provides
promotion and demotion functionality.  <i>outline-magic.el</i> is
available at <a href="http://www.astro.uva.nl/~dominik/Tools/OutlineMagic">Outline Magic</a>.
</p>
</div>
</div>

<div class="outline-2">
<h2 id="sec-4">2 Errors</h2>


<div class="outline-3">
<h3 id="sec-5">2.1 <code>(wrong-type-argument keymapp nil)</code></h3>

<p><b>When I try to use Org-mode, I always get the error message @code{(wrong-type-argument keymapp nil)}</b>
</p>
<p>
This is a conflict with an outdated version of the <i>allout.el</i>, see
the <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section in the manual
</p>
</div>

<div class="outline-3">
<h3 id="sec-6">2.2 CUA mode does not work with Org-mode</h3>


<p>
<b>Org-mode takes over the S-cursor keys.  I also want to use CUA-mode, is there a way to fix this conflict?</b>
</p>
<p>
Yes, see the  <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section of the manual.
</p>
</div>

<div class="outline-3">
<h3 id="sec-7">2.3 <code>winddmove.el</code> does not work with Org-mode.</h3>


<p>
<b>Org-mode takes over the S-cursor keys.  I also want to use windmove.el, is there a way to fix this conflict?</b>
</p>
<p>
Yes, see the <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section of the manual.
</p>
</div>
</div>

<div class="outline-2">
<h2 id="sec-8">3 Setup and Structure</h2>


<div class="outline-3">
<h3 id="sec-9">3.1 Org-mode as default mode</h3>


<p>
<b>Org-mode seems to be a useful default mode for the various README files I have scattered through my directories</b>.  <b>How do I turn it on for all README files?</b>
</p>
<p>
Add the following to your .emacs file:
</p>
<p>
<pre>
 (add-to-list 'auto-mode-alist '("README$" . org-mode))
</pre>
</p>
<p>
You can even make it the default mode for any files with unspecified
mode using
</p>
<p>
<pre>
 (setq default-major-mode 'org-mode)
</pre>
</p>
</div>

<div class="outline-3">
<h3 id="sec-10">3.2 Get rid of extra stars in outline</h3>


<p>
*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?* 
</p>
<p>
See the section  <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Clean%20outline%20view">Clean outline view</a> in the manual.
</p>
</div>

<div class="outline-3">
<h3 id="sec-11">3.3 Two windows on same Org-mode file</h3>

<p><b>I would like to have two windows on the same Org-mode file, but with different outline visibility.  Is that possible?</b> 
</p>
<p>
You may use <i>indirect buffers</i> which do exactly this.  See the
documentation on the command <code>make-indirect-buffer</code>.
</p>
</div>

<div class="outline-3">
<h3 id="sec-12">3.4 Insert empty lines before new headings and plain list items</h3>


<p>
<b>I would like to have an empty line before each newly inserted headline, but not before each newly inserted plain-list item</b>.
</p>
<p>
<pre>
 (setq org-blank-before-new-entry
       '((heading . t) (plain-list-item . nil))
</pre>
</p>

</div>

<div class="outline-3">
<h3 id="sec-13">3.5 Amount of context in sparse trees</h3>


<p>
*Sparse tree show the headline hierarchy above each match, and also
the headline following a match.  I'd like to construct more compact
trees, with less context.*
</p>
<p>
Take a look at the variables <code>org-show-hierarchy-above</code> and
<code>org-show-following-headline</code>.
</p>
</div>

<div class="outline-3">
<h3 id="sec-14">3.6 Stacking calls to org-occur</h3>


<p>
*Each call to org-occur starts again from OVERVIEW and exposes only
the matches of the current call.  I'd like to combine the effect of
several calls*.
</p>
<p>
You can construct a regular expression that matches all targets you
want.  Alternatively, use a <code>C-u</code> prefix with the second and any
further calls to <code>org-occur</code> to keep the current visibility and
highlighting in addition to the new ones.
</p>
</div>
</div>

<div class="outline-2">
<h2 id="sec-15">4 Hyperlinks</h2>


<div class="outline-3">
<h3 id="sec-16">4.1 Confirmation for shell and elisp links</h3>


<p>
*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?* 
</p>
<p>
The confirmation is there to protect you from unwantingly execute
potentially dangerous commands.  For example, imagine a link
<pre>
[[shell:rm -rf ~/*][ Google Search]]
</pre>
</p>
<p>
In an Org-mode buffer, this command would look like <i>Google Search</i>,
but really it would remove your home directory.  If you wish, you can
make it easier to respond to the query by setting
</p>
<p>
<pre>
 (setq org-confirm-shell-link-function 'y-or-n-p
       org-confirm-elisp-link-function 'y-or-n-p).
</pre>
</p>
<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.
</p>
</div>

<div class="outline-3">
<h3 id="sec-17">4.2 Use RET or TAB to follow a link</h3>


<p>
<b>From other packages like Emacs-wiki, I am used to follow links with  =RET= when the cursor is on the link.  Is this also possible in org-mode?</b>
</p>
<p>
Yes, and you may also use TAB.
</p>
<p>
<pre>
 (setq org-return-follows-link t)
 (setq org-tab-follows-link t)
</pre>
</p>
</div>

<div class="outline-3">
<h3 id="sec-18">4.3 Clicking on a link without activating it</h3>


<p>
<b>Each time I click inside a link in order to set point to this  location, Org-mode actually follows the link</b>
</p>
<p>
Activating links with <code>mouse-1</code> 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 <code>mouse-2</code> to follow links and turn off
link activation for <code>mouse-1</code> with
</p>
<p>
<pre>
 (setq org-mouse-1-follows-link nil)
</pre>
</p>
</div>
</div>

<div class="outline-2">
<h2 id="sec-19">5 Remember</h2>


<p>
<b>Can I automatically start the clock when opening a remember template?</b>
</p>
<p>
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' <i>after</i> `org-remember-apply-template'.
</p>
<p>
<pre>
 (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))))
</pre>
</p>
<p>
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.
</p>
</div>

<div class="outline-2">
<h2 id="sec-20">6 Export</h2>


<div class="outline-3">
<h3 id="sec-21">6.1 Make TODO entries items, not headlines in HTML export</h3>


<p>
*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?* 
</p>
<p>
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:
</p>
<p>
<pre>
 * Todays top priorities
 **** TODO write a letter to xyz
 **** TODO Finish the paper
 **** Pick up kids at the school
</pre>
</p>
<p>
Alternatively, if you need a specific value for the heading/item
transition in a particular file, use the <code>#+OPTIONS</code> line to
configure the H switch.
</p>
<p>
<pre>
 #+OPTIONS:   H:2; ...
</pre>
</p>
</div>

<div class="outline-3">
<h3 id="sec-22">6.2 Export only a subtree</h3>


<p>
<b>I would like to export only a subtree of my file to HTML. How?</b>
</p>
<p>
If you want to export a subtree, mark the subtree as region and then
export.  Marking can be done with <code>C-c @ C-x C-x</code>, for example.
</p>
</div>

<div class="outline-3">
<h3 id="sec-23">6.3 How to import org-mode calendar data into Mac OSX ical</h3>


<p>
<b>I would like my iCal program on Mac OSX to import the iCalendar file   produced by Org-mode. How?</b>
</p>
<p>
<i>This is for OSX 10.3, see below for 10.4:</i> When using iCal under
Apple MacOS X, you can create a new calendar <i>OrgMode</i> (the default
name for the calendar created by <code>C-c C-e c</code>, see the variables
<code>org-icalendar-combined-name</code> and
<code>org-combined-agenda-icalendar-file</code>).  Then set Org-mode to overwrite
the corresponding file <i>~/Library/Calendars/OrgMode.ics</i>.  You may
even use AppleScript to make iCal re-read the calendar files each time
a new version of <i>OrgMode.ics</i> is produced.  Here is the setup needed
for this:
</p>
<p>
<pre>
 (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'")))
</pre>
</p>

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

<div class="outline-2">
<h2 id="sec-24">7 Tables</h2>


<div class="outline-3">
<h3 id="sec-25">7.1 #ERROR fields in tables</h3>


<p>
<b>One of my table columns has started to fill up with =#ERROR=.  What is going on?</b>
</p>
<p>
Org-mode tried to compute the column from other fields using a
formula stored in the <code>#+TBLFM:</code> 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!
</p>
</div>

<div class="outline-3">
<h3 id="sec-26">7.2 Unwanted new lines in table</h3>


<p>
*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*.  <b>How can I quickly move to the line below the horizontal line instead?</b> 
</p>
<p>
Press <code>down</code> (to get on the separator line) and then <code>TAB</code>.
Or configure the variable
</p>
<p>
<pre>
 (setq org-table-tab-jumps-over-hlines t)
</pre>
</p>
</div>

<div class="outline-3">
<h3 id="sec-27">7.3 Automatic detection of formulas</h3>

<p><b>I need to use fields in my table that start with "=", and each time  I enter such a field, Org-mode thinks this is a formula</b>.
</p>
<p>
With the setting
</p>
<p>
<pre>
 (setq org-table-formula-evaluate-inline nil)
</pre>
</p>
<p>
this will no longer happen.  You can still use formulas using the
commands <tt>C-c =</tt> and <tt>C-u C-c =</tt>
</p>

</div>

<div class="outline-3">
<h3 id="sec-28">7.4 Change indentation of a table</h3>

<p><b>How can I change the indentation of an entire table without fixing every line by hand?</b>
</p>
<p>
The indentation of a table is set by the first line.  So just fix the
indentation of the first line and realign with <code>TAB</code>.
</p>
</div>

<div class="outline-3">
<h3 id="sec-29">7.5 Performance issues with table alignment</h3>

<p><b>I have a huge table in a file, and the automatic realign of tables  is just taking too long.  What can I do?</b>
</p>
<p>
Either split the table into several by inserting an empty line every
100 lines or so.  Or turn off the automatic re-align with
</p>
<p>
<pre>
 (setq org-table-automatic-realign nil)
</pre>
</p>
<p>
After this the only way to realign a table is to press <code>C-c C-c</code>.  It
will no longer happen automatically, removing the corresponding delays
during editing.
</p>
</div>

<div class="outline-3">
<h3 id="sec-30">7.6 Performance issues with table calculation</h3>

<p><b>I have a complex table with lots of formulas, and recomputing the  table takes rather long.  What can I do?</b>
</p>
<p>
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.
</p>
<p>
So for really complex tables, moving to a "real" spreadsheet may still
be the best option.
</p>
<p>
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.
</p>
</div>

<div class="outline-3">
<h3 id="sec-31">7.7 Incrementing numbers</h3>

<p>*When I press <code>S-RET</code> in a table field to copy its value down, the
content is not copied as is, but it is increased by one.
Is that a bug or a feature*
</p>
<p>
Well, it is <i>supposed</i> 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
</p>
<p>
<pre>
 (setq org-org-table-copy-increment nil)
</pre>
</p>
</div>
</div>

<div class="outline-2">
<h2 id="sec-32">8 Agenda</h2>


<div class="outline-3">
<h3 id="sec-33">8.1 Include Org-mode agenda into Emacs diary</h3>

<p><b>Is it possible to include entries from org-mode files into my emacs diary?</b> 
</p>
<p>
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 <i>fancy diary display</i> by setting in
.emacs:
</p>
<p>
<pre>
 (add-hook 'diary-display-hook 'fancy-diary-display)
</pre>
</p>
<p>
Then include the following line into your ~/diary file, in
order to get the entries from all files listed in the variable
<code>org-agenda-files</code>
</p>
<p>
<pre>
 &amp;%%(org-diary)
</pre>
You may also select specific files with
</p>
<p>
<pre>
 &amp;%%(org-diary) ~/path/to/some/org-file.org
 &amp;%%(org-diary) ~/path/to/another/org-file.org
</pre>
</p>
<p>
If you now launch the calendar and press <tt>d</tt> 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 <i>today</i> contains additional
entries for overdue deadlines and scheduled items.  See also the
documentation of the <code>org-diary</code> function.  Under XEmacs, it is
not possible to jump back from the diary to the org, this works only in
the agenda buffer.
</p>

</div>
</div>
<div id="postamble"><p class="author"> Author: Carsten Dominik
<a href="mailto:carsten.dominik@gmail.com">&lt;carsten.dominik@gmail.com&gt;</a>
</p>
<p class="date"> Date: 2008/02/12 12:28:14</p>
</div></body>
</html>