- publishing free software manuals
The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
ISBN 9781906966089
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.3

by Carsten Dominik

(1) Please consider subscribing to the mailing list, in order to minimize the work the mailing list moderators have to do.

(2) See the variables org-special-ctrl-a/e, org-special-ctrl-k, and org-ctrl-k-protect-subtree to configure special behavior of C-a, C-e, and C-k in headlines.

(3) see, however, the option org-cycle-emulate-tab.

(4) see the option org-cycle-global-at-bob.

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

(6) If you do not want the line to be split, customize the variable org-M-RET-may-split-line.

(7) Docstrings for commands can be displayed with M-x describe-function or C-h f.

(8) See also the variables org-show-hierarchy-above, org-show-following-heading, org-show-siblings, and org-show-entry-below for detailed control on how much context is shown around each match.

(9) This depends on the option org-remove-highlights-with-change

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

(12) You can filter out any of them by configuring org-plain-list-ordered-item-terminator.

(13) If there's a checkbox in the item, the cookie must be put before the checkbox.

(14) To disable either of them, configure org-list-ending-method.

(15) See also org-empty-line-terminates-plain-lists.

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

(17) 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’: (require 'filladapt)

(18) If you do not want the line to be split, customize the variable org-M-RET-may-split-line.

(19) See bullet rule in org-list-automatic-rules for more information.

(20) 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.

(22) The corresponding in-buffer setting is: #+STARTUP: fninline or #+STARTUP: nofninline

(23) the corresponding in-buffer options are fnadjust and nofnadjust.

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

(29) 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 org-keep-stored-link-after-insertion.

(30) This works by calling a special function org-PREFIX-complete-link.

(31) See the variable org-display-internal-link-with-indirect-buffer

(32) with corresponding #+STARTUP keywords inlineimages and inlineimages

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

(37) 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.

(39) The corresponding in-buffer setting is: #+STARTUP: logdone

(40) The corresponding in-buffer setting is: #+STARTUP: lognotedone

(41) See the variable org-log-states-order-reversed

(42) 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’.

(43) See also the option org-priority-start-cycle-with-default.

(44) To keep subtasks out of the global TODO list, see the org-agenda-todo-list-sublevels.

(45) With the exception of description lists. But you can allow it by modifying org-list-automatic-rules accordingly.

(46) Set the variable org-hierarchical-checkbox-statistics if you want such cookies to represent the all checkboxes below the cookie, not just the direct children.

(47) As with all these in-buffer settings, pressing C-c C-c activates any changes in the line.

(48) This is only true if the search does not involve more complex tests including properties (see section 7.3 Property searches).

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

(51) Contributed packages are not part of Emacs, but are distributed with the main distribution of Org (visit http://orgmode.org).

(52) This is inspired by the standard ISO 8601 date/time format. To use an alternative format, see section 8.2.2 Custom time format.

(53) See the variable org-read-date-prefer-future. You may set that variable to the symbol time to even make a time before now shift the date to tomorrow.

(54) If you don't need/want the calendar, configure the variable org-popup-calendar-for-date-prompt.

(55) If you find this distracting, turn the display of with org-read-date-display-live.

(56) It will still be listed on that date after it has been marked DONE. If you don't like this, set the variable org-agenda-skip-scheduled-if-done.

(57) with corresponding #+STARTUP keywords logredeadline, lognoteredeadline, and nologredeadline

(58) with corresponding #+STARTUP keywords logredeadline, lognoteredeadline, and nologredeadline

(59) In fact, the target state is taken from, in this sequence, the REPEAT_TO_STATE property or the variable org-todo-repeat-to-state. If neither of these is specified, the target state defaults to the first state of the TODO state sequence.

(60) You can change this using the option org-log-repeat, or the #+STARTUP options logrepeat, lognoterepeat, and nologrepeat. With lognoterepeat, you will also be prompted for a note.

(61) To resume the clock under the assumption that you have worked on this task while outside Emacs, use (setq org-clock-persist t).

(62) To add an effort estimate “on the fly”, hook a function doing this to org-clock-in-prepare-hook.

(63) as recorded by the LAST_REPEAT property

(64) See also the variable org-clock-modeline-total.

(65) The corresponding in-buffer setting is: #+STARTUP: lognoteclock-out

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

(68) You may change the property being used with the variable org-effort-property.

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

(71) Please note the pitfalls of summing hierarchical data in a flat list (see section 10.8 Using column view in the agenda).

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

(74) If you define your own link types (see section 16.13 Adding hyperlink types), any property you store with org-store-link-props can be accessed in capture templates in a similar way.

(75) This will always be the other, not the user. See the variable org-from-is-user-regexp.

(76) If you move entries or Org files from one directory to another, you may want to configure org-attach-directory to contain an absolute path.

(77) with corresponding #+STARTUP keywords logrefile, lognoterefile, and nologrefile

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

(80) 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 dispatcher command.

(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).

(84) Note that the order of the arguments (month, day, year) depends on the setting of calendar-date-style.

(85) See section 6.3 Tag searches.

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

(87) 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.

(88) 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.

(94) 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 org-export-latex-listings and org-export-latex-minted for further details.

(95) Adding -k to -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.

(97) You may select a different-mode with the variable org-edit-fixed-width-region-mode.

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

(99) You can turn this on by default by setting the variable org-pretty-entities, or on a per-file base with the #+STARTUP option entitiespretty.

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

(101) 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 org-format-latex-header.

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

(103) Org-mode has a method to test if the cursor is inside such a fragment, see the documentation of the function org-inside-LaTeX-fragment-p.

(104) If you want to configure many options this way, you can use several OPTIONS lines.

(105) To make this behavior the default, customize the variable org-export-run-in-background.

(106) This requires transient-mark-mode be turned on.

(107) To select the current subtree, use C-c @.

(108) This requires transient-mark-mode be turned on.

(109) To select the current subtree, use C-c @.

(110) But see the variable org-export-html-inline-images.

(111) If the classes on TODO keywords and tags lead to conflicts, use the variables org-export-html-todo-kwd-class-prefix and org-export-html-tag-class-prefix to make them unique.

(112) 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 org-export-html-style-include-default

(113) Please note that the STYLE definition must be on a single line--it is wrapped here only because of formatting constraints.

(114) 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 org-export-latex-default-packages-alist and org-export-latex-packages-alist.

(115) This requires transient-mark-mode be turned on.

(116) To select the current subtree, use C-c @.

(117) Into which the values of org-export-latex-default-packages-alist and 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.

(120) This requires transient-mark-mode to be turned on

(121) To select the current subtree, use C-c @.

(122) http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.

(123) See the variables org-icalendar-use-deadline and org-icalendar-use-scheduled.

(124) To add inherited tags or the TODO state, configure the variable org-icalendar-categories.

(125) The LOCATION property can be inherited from higher in the hierarchy if you configure org-use-property-inheritance accordingly.

(126) ‘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 definition in org-publish-project-alist to prevent the published source files from being considered as new org files the next time the project is published.

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

(128) The 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.

(131) ‘constants.el’ can supply the values of constants in two different unit systems, SI and cgs. Which one is used depends on the value of the variable constants-unit-system. You can use the #+STARTUP options constSI and constcgs to set this value for the current buffer.

(132) The printf reformatting is limited in precision because the value passed to it is converted into an integer or double. The 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.

(133) http://www.gnuplot.info/

(134) http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html

(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

(137) Emacs 23.1 can actually crash with org-indent-mode

(138) org-indent-mode also sets the wrap-prefix property, such that visual-line-mode (or purely setting word-wrap) wraps long lines (including headlines) correctly indented.

(139) See the variable org-indent-indentation-per-level.

(140) Turning on org-indent-mode sets org-hide-leading-stars to t and org-adapt-indentation to nil.

(141) See also the variable org-adapt-indentation.

(142) When you need to specify a level for a property search or refile targets, ‘LEVEL=2’ will correspond to 3 stars, etc.

(143) http://orgmode.org/worg/org-configs/org-hooks.php

(144) ‘org-R.el’ has been replaced by the org-mode functionality described in section 14 Working with source code and is now obsolete.

(145) By default this works only for LaTeX, HTML, and Texinfo. Configure the variable orgtbl-radio-tables to install templates for other modes.

(146) If 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 variable LaTeX-verbatim-environments.

(147) The HTML translator uses the same code that produces tables during HTML export.

(148) Note that, when using org-odd-levels-only, a level number corresponds to order in the hierarchy, not to the number of stars.

(149) 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.

(151) 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 org-mobile-force-id-on-agenda-items to 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 9781906966089The Org Mode 7 Reference ManualSee the print edition