15. Miscellaneous

15.1 Completion

Emacs would not be Emacs without completion, and Org-mode uses it whenever it makes sense. If you prefer an iswitchb- or ido-like interface for some of the completion prompts, you can specify your preference by setting at most one of the variables org-completion-use-iswitchb org-completion-use-ido.

Org supports in-buffer completion. This type of completion does not make use of the minibuffer. You simply type a few letters into the buffer and use the key to complete text right there.

M-TAB

Complete word at point

• At the beginning of a headline, complete TODO keywords.
• After `\', complete TeX symbols supported by the exporter.
• After `*', complete headlines in the current buffer so that they can be used in search links like `[[*find this headline]]'.
• After `:' in a headline, complete tags. The list of tags is taken from the variable org-tag-alist (possibly set through the `#+TAGS' in-buffer option, see section 6.2 Setting tags), or it is created dynamically from all tags used in the current buffer.
• After `:' and not in a headline, complete property keys. The list of keys is constructed dynamically from all keys used in the current buffer.
• After `[', complete link abbreviations (see section 4.6 Link abbreviations).
• After `#+', complete the special keywords like `TYP_TODO' or `OPTIONS' which set file-specific options for Org-mode. When the option keyword is already complete, pressing M-TAB again will insert example settings for this keyword.
• In the line after `#+STARTUP: ', complete startup keywords, i.e. valid keys for this line.
• Elsewhere, complete dictionary words using Ispell.

15.2 Speed keys

Single keys can be made to execute commands when the cursor is at the beginning of a headline, i.e. before the first star. Configure the variable org-use-speed-commands to activate this feature. There is a pre-defined list of commands, and you can add more such commands using the variable org-speed-commands-user. Speed keys do not only speed up navigation and other commands, but they also provide an alternative way to execute commands bound to keys that are not or not easily available on a tty, or on a small mobile device with a limited keyboard.

To see which commands are available, activate the feature and press ? with the cursor at the beginning of a headline.

15.3 Code evaluation and security issues

Org provides tools to work with the code snippets, including evaluating them.

Running code on your machine always comes with a security risk. Badly written or malicious code can be executed on purpose or by accident. Org has default settings which will only evaluate such code if you give explicit permission to do so, and as a casual user of these features you should leave these precautions intact.

For people who regularly work with such code, the confirmation prompts can become annoying, and you might want to turn them off. This can be done, but you must be aware of the risks that are involved.

Code evaluation can happen under the following circumstances:

Source code blocks

Source code blocks can be evaluated during export, or when pressing C-c C-c in the block. The most important thing to realize here is that Org mode files which contain code snippets are, in a certain sense, like executable files. So you should accept them and load them into Emacs only from trusted sources - just like you would do with a program you install on your computer.

Make sure you know what you are doing before customizing the variables which take off the default security brakes.

User Option: org-confirm-babel-evaluate

When set to t user is queried before code block evaluation

Following shell and elisp links

Org has two link types that can directly evaluate code (see section 4.3 External links). These links can be problematic because the code to be evaluated is not visible.

User Option: org-confirm-shell-link-function

Function to queries user about shell link execution.

User Option: org-confirm-elisp-link-function

Functions to query user for Emacs Lisp link execution.

Formulas in tables

Formulas in tables (see section 3.5 The spreadsheet) are code that is evaluated either by the calc interpreter, or by the Emacs Lisp interpreter.

15.4 Customization

There are more than 180 variables that can be used to customize Org. For the sake of compactness of the manual, I am not describing the variables here. A structured overview of customization variables is available with M-x org-customize. Or select Browse Org Group from the Org->Customization menu. Many settings can also be activated on a per-file basis, by putting special lines into the buffer (see section 15.5 Summary of in-buffer settings).

15.5 Summary of in-buffer settings

Org-mode uses special lines in the buffer to define settings on a per-file basis. These lines start with a `#+' followed by a keyword, a colon, and then individual words defining a setting. Several setting words can be in the same line, but you can also have multiple lines for the keyword. While these settings are described throughout the manual, here is a summary. After changing any of those lines in the buffer, press C-c C-c with the cursor still in the line to activate the changes immediately. Otherwise they become effective only when the file is visited again in a new Emacs session.

#+ARCHIVE: %s_done::

This line sets the archive location for the agenda file. It applies for all subsequent lines until the next `#+ARCHIVE' line, or the end of the file. The first such line also applies to any entries before it. The corresponding variable is org-archive-location.

#+CATEGORY:

This line sets the category for the agenda file. The category applies for all subsequent lines until the next `#+CATEGORY' line, or the end of the file. The first such line also applies to any entries before it.

#+COLUMNS: %25ITEM .....

Set the default format for columns view. This format applies when columns view is invoked in locations where no COLUMNS property applies.

#+CONSTANTS: name1=value1 ...

Set file-local values for constants to be used in table formulas. This line set the local variable org-table-formula-constants-local. The global version of this variable is org-table-formula-constants.

#+FILETAGS: :tag1:tag2:tag3:

Set tags that can be inherited by any entry in the file, including the top-level entries.

#+DRAWERS: NAME1 .....

Set the file-local set of drawers. The corresponding global variable is org-drawers.

#+LINK: linkword replace

These lines (several are allowed) specify link abbreviations. See section 4.6 Link abbreviations. The corresponding variable is org-link-abbrev-alist.

#+PRIORITIES: highest lowest default

This line sets the limits and the default for the priorities. All three must be either letters A-Z or numbers 0-9. The highest priority must have a lower ASCII number that the lowest priority.

#+PROPERTY: Property_Name Value

This line sets a default inheritance value for entries in the current buffer, most useful for specifying the allowed values of a property.

#+SETUPFILE: file

This line defines a file that holds more in-buffer setup. Normally this is entirely ignored. Only when the buffer is parsed for option-setting lines (i.e. when starting Org-mode for a file, when pressing C-c C-c in a settings line, or when exporting), then the contents of this file are parsed as if they had been included in the buffer. In particular, the file can be any other Org-mode file with internal setup. You can visit the file the cursor is in the line with C-c '.

#+STARTUP:

This line sets options to be used at startup of Org-mode, when an Org file is being visited.

The first set of options deals with the initial visibility of the outline tree. The corresponding variable for global default settings is org-startup-folded, with a default value t, which means overview.

overview top-level headlines only content all headlines showall no folding of any entries showeverything show even drawer contents

Dynamic virtual indentation is controlled by the variable org-startup-indented(114)

indent start with org-indent-mode turned on noindent start with org-indent-mode turned off

Then there are options for aligning tables upon visiting a file. This is useful in files containing narrowed table columns. The corresponding variable is org-startup-align-all-tables, with a default value nil.

align align all tables noalign don't align tables on startup

Logging the closing and reopening of TODO items and clock intervals can be configured using these options (see variables org-log-done, org-log-note-clock-out and org-log-repeat)

logdone record a timestamp when an item is marked DONE lognotedone record timestamp and a note when DONE nologdone don't record when items are marked DONE logrepeat record a time when reinstating a repeating item lognoterepeat record a note when reinstating a repeating item nologrepeat do not record when reinstating repeating item lognoteclock-out record a note when clocking out nolognoteclock-out don't record a note when clocking out logreschedule record a timestamp when scheduling time changes lognotereschedule record a note when scheduling time changes nologreschedule do not record when a scheduling date changes logredeadline record a timestamp when deadline changes lognoteredeadline record a note when deadline changes nologredeadline do not record when a deadline date changes logrefile record a timestamp when refiling lognoterefile record a note when refiling nologrefile do not record when refiling

Here are the options for hiding leading stars in outline headings, and for indenting outlines. The corresponding variables are org-hide-leading-stars and org-odd-levels-only, both with a default setting nil (meaning showstars and oddeven).

hidestars make all but one of the stars starting a headline invisible. showstars show all stars starting a headline indent virtual indentation according to outline level noindent no virtual indentation according to outline level odd allow only odd outline levels (1,3,...) oddeven allow all outline levels

To turn on custom format overlays over timestamps (variables org-put-time-stamp-overlays and org-time-stamp-overlay-formats), use

customtime overlay custom time format

The following options influence the table spreadsheet (variable constants-unit-system).

constcgs `constants.el' should use the c-g-s unit system constSI `constants.el' should use the SI unit system

To influence footnote settings, use the following keywords. The corresponding variables are org-footnote-define-inline, org-footnote-auto-label, and org-footnote-auto-adjust.

fninline define footnotes inline fnnoinline define footnotes in separate section fnlocal define footnotes near first reference, but not inline fnprompt prompt for footnote labels fnauto create [fn:1]-like labels automatically (default) fnconfirm offer automatic label for editing or confirmation fnplain create [1]-like labels automatically fnadjust automatically renumber and sort footnotes nofnadjust do not renumber and sort automatically

To hide blocks on startup, use these keywords. The corresponding variable is org-hide-block-startup.

hideblocks Hide all begin/end blocks on startup nohideblocks Do not hide blocks on startup

The the display of entities as UTF8 characters is governed by the variable org-pretty-entities and the keywords

entitiespretty Show entities as UTF8 characters where possible entitiesplain Leave entities plain

#+TAGS: TAG1(c1) TAG2(c2)

These lines (several such lines are allowed) specify the valid tags in this file, and (potentially) the corresponding fast tag selection keys. The corresponding variable is org-tag-alist.

#+TBLFM:

This line contains the formulas for the table directly above the line.

#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,

#+OPTIONS:, #+BIND:, #+XSLT:,

#+DESCRIPTION:, #+KEYWORDS:,

#+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,

#+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:

These lines provide settings for exporting files. For more details see 12.2 Export options.

#+TODO: #+SEQ_TODO: #+TYP_TODO:

These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is org-todo-keywords.

15.6 The very busy C-c C-c key

The key C-c C-c has many purposes in Org, which are all mentioned scattered throughout this manual. One specific function of this key is to add tags to a headline (see section 6. Tags). In many other circumstances it means something like "Hey Org, look here and update according to what you see here". Here is a summary of what this means in different contexts.

• If there are highlights in the buffer from the creation of a sparse tree, or from clock display, remove these highlights.
• If the cursor is in one of the special #+KEYWORD lines, this triggers scanning the buffer for these lines and updating the information.
• If the cursor is inside a table, realign the table. This command works even if the automatic table editor has been turned off.
• If the cursor is on a #+TBLFM line, re-apply the formulas to the entire table.
• If the current buffer is a capture buffer, close the note and file it. With a prefix argument, file it, without further interaction, to the default location.
• If the cursor is on a <<>>, update radio targets and corresponding links in this buffer.
• If the cursor is in a property line or at the start or end of a property drawer, offer property commands.
• If the cursor is at a footnote reference, go to the corresponding definition, and vice versa.
• If the cursor is on a statistics cookie, update it.
• If the cursor is in a plain list item with a checkbox, toggle the status of the checkbox.
• If the cursor is on a numbered item in a plain list, renumber the ordered list.
• If the cursor is on the #+BEGIN line of a dynamic block, the block is updated.

15.7 A cleaner outline view

Some people find it noisy and distracting that the Org headlines start with a potentially large number of stars, and that text below the headlines is not indented. While this is no problem when writing a book-like document where the outline headings are really section headings, in a more list-oriented outline, indented structure is a lot cleaner:

* Top level headline             |    * Top level headline
** Second level                  |      * Second level
*** 3rd level                    |        * 3rd level
some text                        |          some text
*** 3rd level                    |        * 3rd level
more text                        |          more text
* Another top level headline     |    * Another top level headline

If you are using at least Emacs 23.2(115) and version 6.29 of Org, this kind of view can be achieved dynamically at display time using org-indent-mode. In this minor mode, all lines are prefixed for display with the necessary amount of space(116). Also headlines are prefixed with additional stars, so that the amount of indentation shifts by two(117) spaces per level. All headline stars but the last one are made invisible using the org-hide face(118) - see below under `2.' for more information on how this works. You can turn on org-indent-mode for all files by customizing the variable org-startup-indented, or you can turn it on for individual files using

#+STARTUP: indent

If you want a similar effect in earlier version of Emacs and/or Org, or if you want the indentation to be hard space characters so that the plain text file looks as similar as possible to the Emacs display, Org supports you in the following way:

1. Indentation of text below headlines
   You may indent text below each headline to make the left boundary line up with the headline, like

   *** 3rd level more text, now indented

   Org supports this with paragraph filling, line wrapping, and structure editing(119), preserving or adapting the indentation as appropriate.

2. Hiding leading stars
   You can modify the display in such a way that all leading stars become invisible. To do this in a global way, configure the variable org-hide-leading-stars or change this on a per-file basis with

   #+STARTUP: hidestars #+STARTUP: showstars

   With hidden stars, the tree becomes:

   * Top level headline * Second level * 3rd level ...

   The leading stars are not truly replaced by whitespace, they are only fontified with the face org-hide that uses the background color as font color. If you are not using either white or black background, you may have to customize this face to get the wanted effect. Another possibility is to set this font such that the extra stars are almost invisible, for example using the color grey90 on a white background.

3. Things become cleaner still if you skip all the even levels and use only odd levels 1, 3, 5..., effectively adding two stars to go from one outline level to the next(120). In this way we get the outline view shown at the beginning of this section. In order to make the structure editing and export commands handle this convention correctly, configure the variable org-odd-levels-only, or set this on a per-file basis with one of the following lines:

   #+STARTUP: odd #+STARTUP: oddeven

   You can convert an Org file from single-star-per-level to the double-star-per-level convention with M-x org-convert-to-odd-levels RET in that file. The reverse operation is M-x org-convert-to-oddeven-levels.

15.8 Using Org on a tty

Because Org contains a large number of commands, by default many of Org's core commands are bound to keys that are generally not accessible on a tty, such as the cursor keys (left, right, up, down), TAB and RET, in particular when used together with modifiers like Meta and/or Shift. To access these commands on a tty when special keys are unavailable, the following alternative bindings can be used. The tty bindings below will likely be more cumbersome; you may find for some of the bindings below that a customized workaround suits you better. For example, changing a timestamp is really only fun with S-cursor keys, whereas on a tty you would rather use C-c . to re-insert the timestamp.

15.9 Interaction with other packages

15.9.1 Packages that Org cooperates with		Packages Org cooperates with
15.9.2 Packages that lead to conflicts with Org-mode		Packages that lead to conflicts

15.9.1 Packages that Org cooperates with

`calc.el' by Dave Gillespie

Org uses the Calc package for implementing spreadsheet functionality in its tables (see section 3.5 The spreadsheet). Org checks for the availability of Calc by looking for the function calc-eval which will have been autoloaded during setup if Calc has been installed properly. As of Emacs 22, Calc is part of the Emacs distribution. Another possibility for interaction between the two packages is using Calc for embedded calculations. See section `Embedded Mode' in

GNU Emacs Calc Manual

.

`constants.el' by Carsten Dominik

In a table formula (see section 3.5 The spreadsheet), it is possible to use names for natural constants or units. Instead of defining your own constants in the variable org-table-formula-constants, install the `constants' package which defines a large number of constants and units, and lets you use unit prefixes like `M' for `Mega', etc. You will need version 2.0 of this package, available at http://www.astro.uva.nl/~dominik/Tools. Org checks for the function constants-get, which has to be autoloaded in your setup. See the installation instructions in the file `constants.el'.

`cdlatex.el' by Carsten Dominik

Org-mode can make use of the CDLaTeX package to efficiently enter LaTeX fragments into Org files. See 11.7.5 Using CDLaTeX to enter math.

`imenu.el' by Ake Stenhoff and Lars Lindberg

Imenu allows menu access to an index of items in a file. Org-mode supports Imenu--all you need to do to get the index is the following:

(add-hook 'org-mode-hook (lambda () (imenu-add-to-menubar "Imenu")))

By default the index is two levels deep--you can modify the depth using the option org-imenu-depth.

`remember.el' by John Wiegley

Org used to use this package for capture, but no longer does.

`speedbar.el' by Eric M. Ludlam

Speedbar is a package that creates a special frame displaying files and index items in files. Org-mode supports Speedbar and allows you to drill into Org files directly from the Speedbar. It also allows you to restrict the scope of agenda commands to a file or a subtree by using the command < in the Speedbar frame.

`table.el' by Takaaki Ota

Complex ASCII tables with automatic line wrapping, column- and row-spanning, and alignment can be created using the Emacs table package by Takaaki Ota (http://sourceforge.net/projects/table, and also part of Emacs 22). Org-mode will recognize these tables and export them properly. Because of interference with other Org-mode functionality, you unfortunately cannot edit these tables directly in the buffer. Instead, you need to use the command C-c ' to edit them, similar to source code snippets.

C-c '

Edit a `table.el' table. Works when the cursor is in a table.el table.

C-c ~

Insert a `table.el' table. If there is already a table at point, this command converts it between the `table.el' format and the Org-mode format. See the documentation string of the command org-convert-table for the restrictions under which this is possible.

`table.el' is part of Emacs since Emacs 22.

`footnote.el' by Steven L. Baur

Org-mode recognizes numerical footnotes as provided by this package. However, Org-mode also has its own footnote support (see section 2.10 Footnotes), which makes using `footnote.el' unnecessary.

15.9.2 Packages that lead to conflicts with Org-mode

In Emacs 23, shift-selection-mode is on by default, meaning that cursor motions combined with the shift key should start or enlarge regions. This conflicts with the use of S-cursor commands in Org to change timestamps, TODO keywords, priorities, and item bullet types if the cursor is at such a location. By default, S-cursor commands outside special contexts don't do anything, but you can customize the variable org-support-shift-select. Org-mode then tries to accommodate shift selection by (i) using it outside of the special contexts where special commands apply, and by (ii) extending an existing active region even if the cursor moves across a special context.

`CUA.el' by Kim. F. Storm

Key bindings in Org conflict with the S- keys used by CUA mode (as well as pc-select-mode and s-region-mode) to select and extend the region. In fact, Emacs 23 has this built-in in the form of shift-selection-mode, see previous paragraph. If you are using Emacs 23, you probably don't want to use another package for this purpose. However, if you prefer to leave these keys to a different package while working in Org-mode, configure the variable org-replace-disputed-keys. When set, Org will move the following key bindings in Org files, and in the agenda buffer (but not during date selection).

S-UP -> M-p S-DOWN -> M-n S-LEFT -> M-- S-RIGHT -> M-+ C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+

Yes, these are unfortunately more difficult to remember. If you want to have other replacement keys, look at the variable org-disputed-keys.

`yasnippet.el'

The way Org-mode binds the TAB key (binding to [tab] instead of "\t") overrules yasnippets' access to this key. The following code fixed this problem:

(add-hook 'org-mode-hook (lambda () (org-set-local 'yas/trigger-key [tab]) (define-key yas/keymap [tab] 'yas/next-field-group)))

`windmove.el' by Hovav Shacham

This package also uses the S- keys, so everything written in the paragraph above about CUA mode also applies here. If you want make the windmove function active in locations where Org-mode does not have special functionality on S-cursor, add this to your configuration:

;; Make windmove work in org-mode: (add-hook 'org-shiftup-final-hook 'windmove-up) (add-hook 'org-shiftleft-final-hook 'windmove-left) (add-hook 'org-shiftdown-final-hook 'windmove-down) (add-hook 'org-shiftright-final-hook 'windmove-right)

`viper.el' by Michael Kifer

Viper uses C-c / and therefore makes this key not access the corresponding Org-mode command org-sparse-tree. You need to find another key for this command, or override the key in viper-vi-global-user-map with

(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)

mail: