|The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
RRP £9.95 ($14.95)
Sales of this book support the Org project! Get a printed copy>>>
Org Mode 7 Reference Manual
Organize your life with GNU Emacs
Release 7.3by Carsten Dominik
(1) Please consider subscribing to the mailing list, in order to minimize the work the mailing list moderators have to do.
See the variables
org-ctrl-k-protect-subtree to configure special behavior of C-a,
C-e, and C-k in headlines.
(5) The indirect buffer (see section `Indirect Buffers' in GNU Emacs Manual) will contain the entire buffer, but will be narrowed to the current tree. Editing the indirect buffer will also change the original buffer, but without affecting visibility in that buffer.
If you do not want the line to be split,
customize the variable
(7) Docstrings for commands can be displayed with M-x describe-function or C-h f.
See also the
org-show-entry-below for detailed
control on how much context is shown around each match.
This depends on the option
(10) This does not work under XEmacs, because XEmacs uses selective display for outlining, not text properties.
(11) When using ‘*’ as a bullet, lines must be indented or they will be seen as top-level headlines. Also, when you are hiding leading stars to get a clean outline view, plain list items starting with a star are visually indistinguishable from true headlines. In short: even though ‘*’ is supported, it may be better to not use it for plain list items.
You can filter out any of them by configuring
(13) If there's a checkbox in the item, the cookie must be put before the checkbox.
To disable either of them, configure
(16) So you cannot have a sublist, some text and then another sublist while still in the same top-level list item. This used to be possible, but it was only supported in the HTML exporter and difficult to manage with automatic indentation.
Org only changes the filling settings for Emacs. For
XEmacs, you should use Kyle E. Jones' ‘filladapt.el’. To turn this on,
put into ‘.emacs’:
If you do not want the line to be split, customize the variable
bullet rule in
org-list-automatic-rules for more information.
You can define drawers on a per-file basis
with a line like
#+DRAWERS: HIDDEN PROPERTIES STATE
(21) Docstrings for variables can be displayed with M-x describe-variable or C-h v.
The corresponding in-buffer
#+STARTUP: fninline or
corresponding in-buffer options are
(24) This feature does not work on XEmacs.
(25) Centering does not work inside Emacs, but it does have an effect when exporting to HTML.
(26) Note that text before the first headline is usually not exported, so the first such target should be after the first headline, or in the line directly before the first headline.
(27) To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press M-TAB. All headlines in the current buffer will be offered as completions.
(28) Note that you don't have to use this command to insert a link. Links in Org are plain text, and you can type or paste them straight into the buffer. By using this command, the links are automatically enclosed in double brackets, and you will be asked for the optional descriptive text.
After insertion of a stored link, the link will be
removed from the list of stored links. To keep it in the list later use, use
a triple C-u prefix argument to C-c C-l, or configure the option
This works by
calling a special function
(33) For backward compatibility, line numbers can also follow a single colon.
(34) Of course, you can make a document that contains only long lists of TODO items, but this is not required.
(35) Changing this variable only becomes effective after restarting Org-mode in a buffer.
(36) This is also true for the t command in the timeline and agenda buffers.
Check also the variable
org-fast-tag-selection-include-todo, it allows you to change the TODO
state through the tags interface (see section 6.2 Setting tags), in case you like to
mingle the two concepts. Note that this means you need to come up with
unique keys across both sets of keywords.
(38) Org-mode parses these lines only when Org-mode is activated after visiting a file. C-c C-c with the cursor in a line starting with ‘#+’ is simply restarting Org-mode for the current buffer.
in-buffer setting is:
corresponding in-buffer setting is:
See the variable
It is possible that Org-mode will record two timestamps
when you are using both
org-log-done and state change logging.
However, it will never prompt for two notes--if you have configured
both, the state change recording note will take precedence and cancel
the ‘Closing Note’.
See also the option
To keep subtasks out of the
global TODO list, see the
With the exception of description
lists. But you can allow it by modifying
Set the variable
org-hierarchical-checkbox-statistics if you want such cookies to
represent the all checkboxes below the cookie, not just the direct
(47) As with all these in-buffer settings, pressing C-c C-c activates any changes in the line.
(49) Keys will automatically be assigned to tags which have no configured keys.
(50) Please note that the COLUMNS definition must be on a single line--it is wrapped here only because of formatting constraints.
org-read-date-prefer-future. You may set that variable to
time to even make a time before now shift the date to
you don't need/want the calendar, configure the variable
If you find this distracting, turn the display of with
It will still
be listed on that date after it has been marked DONE. If you don't like
this, set the variable
In fact, the target
state is taken from, in this sequence, the
REPEAT_TO_STATE property or
org-todo-repeat-to-state. If neither of these is
specified, the target state defaults to the first state of the TODO state
You can change this using the option
org-log-repeat, or the
will also be prompted for a note.
To resume the clock under the assumption that you have worked
on this task while outside Emacs, use
(setq org-clock-persist t).
To add an effort estimate “on the fly”,
hook a function doing this to
as recorded by the
See also the variable
The corresponding in-buffer setting is:
(66) Note that all parameters must be specified in a single line--the lines are broken here only to fit them into the manual.
(67) On computers using Mac OS X, idleness is based on actual user idleness, not just Emacs' idle time. For X11, you can install a utility program ‘x11idle.c’, available in the UTILITIES directory of the Org git distribution, to get the same general treatment of idleness. On other systems, idle time refers to Emacs idle time only.
You may change the property being
used with the variable
(69) Please note that the PROPERTY definition must be on a single line--it is wrapped here only because of formatting constraints.
(70) Please note that the COLUMNS definition must be on a single line--it is wrapped here only because of formatting constraints.
(72) Please select your own key, C-c c is only a suggestion.
(73) If you need one of these sequences literally, escape the % with a backslash.
This will always be the other, not the user. See the variable
If you move entries or Org files from one
directory to another, you may want to configure
to contain an absolute path.
(78) For backward compatibility, the following also works: If there are several such lines in a file, each specifies the archive location for the text below it. The first such line also applies to any text before its definition. However, using this method is strongly deprecated as it is incompatible with the outline structure of the document. The correct method for setting multiple archive locations in a buffer is using properties.
(79) If the value of that variable is not a list, but a single file name, then the list of agenda files will be maintained in that external file.
When using the dispatcher, pressing
< before selecting a command will actually limit the command to
the current file, and ignore
org-agenda-files until the next
(81) For backward compatibility, you can also press 1 to restrict to the current buffer.
(82) For backward compatibility, you can also press 0 to restrict to the current region/subtree.
(83) For backward compatibility, the universal prefix C-u causes all TODO entries to be listed before the agenda. This feature is deprecated, use the dedicated TODO list, or a block agenda instead (see section 10.6.2 Block agenda).
Note that the order of the arguments (month, day, year) depends on the setting of
(86) For backward compatibility, the following also works: if there are several such lines in a file, each specifies the category for the text below it. The first category also applies to any text before the first CATEGORY line. However, using this method is strongly deprecated as it is incompatible with the outline structure of the document. The correct method for setting multiple categories in a buffer is using a property.
Custom commands can preset a filter by
binding the variable
org-agenda-filter-preset as an option. This
filter will then be applied to the view and persist as a basic filter through
refreshes and more secondary filtering. The filter is a global property of
the entire agenda view--in a block agenda, you should only set this in the
global options section, not in the section of an individual block.
This file is parsed for the agenda when
org-agenda-include-diary is set.
(89) You can provide a description for a prefix key by inserting a cons cell with the prefix and the description.
(90) You need to install Hrvoje Niksic's ‘htmlize.el’.
(91) To create PDF output, the ghostscript ‘ps2pdf’ utility must be installed on the system. Selecting a PDF file with also create the postscript file.
(92) If you want to store standard views like the weekly agenda or the global TODO list as well, you need to define custom commands for them in order to be able to specify file names.
(93) Quoting depends on the system you use, please check the FAQ for examples.
This works automatically for
the HTML backend (it requires version 1.34 of the ‘htmlize.el’ package,
which is distributed with Org). Fontified code chunks in LaTeX can be
achieved using either the listings or the
minted package. To use listings, turn
on the variable
org-export-latex-listings and ensure that the listings
package is included by the LaTeX header (e.g. by configuring
org-export-latex-packages-alist). See the listings documentation for
configuration options, including obtaining colored output. For minted it is
necessary to install the program pygments, in
addition to setting
org-export-latex-minted, ensuring that the minted
package is included by the LaTeX header, and ensuring that the
-shell-escape option is passed to ‘pdflatex’ (see
org-latex-to-pdf-process). See the documentation of the variables
-n -r will keep the
labels in the source code while using line numbers for the links, which might
be useful to explain those in an org-mode example code.
(96) Upon exit, lines starting with ‘*’ or ‘#’ will get a comma prepended, to keep them from being interpreted by Org as outline nodes or special comments. These commas will be stripped for editing with C-c ', and also for export.
You may select a different-mode with the
(98) LaTeX is a macro system based on Donald E. Knuth's TeX system. Many of the features described here as “LaTeX” are really from TeX, but for simplicity I am blurring this distinction.
You can turn this on by default by setting the
org-pretty-entities, or on a per-file base with the
(100) If you plan to use this regularly or on pages with significant page views, you should install ‘MathJax’ on your own server in order to limit the load of our server.
For this to work you need to be on a system with a working
LaTeX installation. You also need the ‘dvipng’ program, available at
http://sourceforge.net/projects/dvipng/. The LaTeX header that will
be used when processing a fragment can be configured with the variable
(102) When ‘MathJax’ is used, only the environment recognized by ‘MathJax’ will be processed. When ‘dvipng’ is used to create images, any LaTeX environments will be handled.
Org-mode has a method to test if the cursor is
inside such a fragment, see the documentation of the function
(104) If you want to configure many options this way, you can use several OPTIONS lines.
To make this behavior the default, customize
transient-mark-mode be turned on.
(107) To select the current subtree, use C-c @.
transient-mark-mode be turned on.
(109) To select the current subtree, use C-c @.
But see the variable
If the classes on TODO
keywords and tags lead to conflicts, use the variables
org-export-html-tag-class-prefix to make them unique.
This style is defined in the constant
org-export-html-style-default, which you should not modify. To turn
inclusion of these defaults off, customize
(113) Please note that the STYLE definition must be on a single line--it is wrapped here only because of formatting constraints.
The default LaTeX output is designed for
processing with pdftex or latex. It includes packages that are not
compatible with xetex and possibly luatex. See the variables
transient-mark-mode be turned on.
(116) To select the current subtree, use C-c @.
Into which the values of
org-export-latex-packages-alist are spliced.
(118) Please note that the ATTR_LaTeX definition must be on a single line--it is wrapped here only because of formatting constraints.
(119) Please note that the COLUMNS definition must be on a single line--it is wrapped here only because of formatting constraints.
transient-mark-mode to be turned on
(121) To select the current subtree, use C-c @.
See the variables
To add inherited tags or the TODO state,
configure the variable
property can be inherited from higher in the hierarchy if you configure
‘file-source.org’ and ‘file-source.org.html’ if
source and publishing directories are equal. Note that with this kind of
setup, you need to add
:exclude "-source\\.org" to the project
org-publish-project-alist to prevent the published source files from being considered as new org files the next time the project is
(127) Whenever code is evaluated there is a potential for that code to do harm. Org-mode provides a number of safeguards to ensure that it only evaluates code with explicit confirmation from the user. For information on these safeguards (and on how to disable them) see section 16.4 Code evaluation and security issues.
org-babel-no-eval-on-ctrl-c-ctrl-c variable can be used to remove code
evaluation from the C-c C-c key binding.
(129) Note that only hlines are counted that separate table lines. If the table starts with a hline above the header, it does not count.
(130) The computation time scales as O(N^2) because table FOO is parsed for each field to be copied.
supply the values of constants in two different unit systems,
cgs. Which one is used depends on the value of the variable
constants-unit-system. You can use the
constcgs to set this value for the current
printf reformatting is limited in precision
because the value passed to it is converted into an
integer is limited in size by truncating the
signed value to 32 bits. The
double is limited in precision to 64
bits overall which leaves approximately 16 significant decimal digits.
(135) Please note that the PLOT definition must be on a single line--it is wrapped here only because of formatting constraints.
(136) Emacs 23 and Org-mode 6.29 are required
Emacs 23.1 can actually crash
org-indent-mode also sets the
property, such that
visual-line-mode (or purely setting
word-wrap) wraps long lines (including headlines) correctly indented.
See the variable
See also the variable
(142) When you need to specify a level for a property search or refile targets, ‘LEVEL=2’ will correspond to 3 stars, etc.
default this works only for LaTeX, HTML, and Texinfo. Configure the
orgtbl-radio-tables to install templates for other
the ‘#+TBLFM’ line contains an odd number of dollar characters,
this may cause problems with font-lock in LaTeX mode. As shown in the
example you can fix this by adding an extra line inside the
comment environment that is used to balance the dollar
expressions. If you are using AUCTeX with the font-latex library, a
much better solution is to add the
comment environment to the
(147) The HTML translator uses the same code that produces tables during HTML export.
Note that, when using
level number corresponds to order in the hierarchy, not to the number of
If you can safely store the
password in your Emacs setup, you might also want to configure
org-mobile-encryption-password. Please read the docstring of that
variable. Note that encryption will apply only to the contents of the
‘.org’ files. The file names themselves will remain visible.
(150) If you cannot use Dropbox, or if your version of MobileOrg does not support it, you can use a webdav server. For more information, check out the documentation of MobileOrg and also this FAQ entry.
While creating the agendas, Org-mode will force ID properties
on all referenced entries, so that these entries can be uniquely identified
if MobileOrg flags them for further action. If you do not want to get
these properties in so many entries, you can set the variable
nil. Org mode will then
rely on outline paths, in the hope that these will be unique enough.
(152) stored automatically in the file ‘checksums.dat’
(153) ‘mobileorg.org’ will be empty after this operation.
(154) Note, however, that there is a subtle difference. The view created automatically by M-x org-mobile-pull RET is guaranteed to search all files that have been addressed by the last pull. This might include a file that is not currently in your list of agenda files. If you later use C-c a ? to regenerate the view, only the current agenda files will be searched.
This document was generated using the texi2html translator version 1.54.
|ISBN 9781906966089||The Org Mode 7 Reference Manual||See the print edition|