[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15. Miscellaneous

comment(none) to "org/Miscellaneous"

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.1 Completion

comment(none) to "org/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.

Complete word at point

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.2 Speed keys

comment(none) to "org/Speedkeys"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.3 Code evaluation and security issues

comment(none) to "org/Codeevaluationandsecurityissues"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.4 Customization

comment(none) to "org/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).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.5 Summary of in-buffer settings

comment(none) to "org/Summaryofin-buffersettings"

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.
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.
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 '.
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.
This line contains the formulas for the table directly above the line.
These lines provide settings for exporting files. For more details see 12.2 Export options.
These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is org-todo-keywords.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.6 The very busy C-c C-c key

comment(none) to "org/TheverybusyC-cC-ckey"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.7 A cleaner outline view

comment(none) to "org/Acleaneroutlineview"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.8 Using Org on a tty

comment(none) to "org/UsingOrgonatty"

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.

Default Alternative 1 Speed key Alternative 2
M-left C-c C-x l l Esc left
M-S-left C-c C-x L L
M-right C-c C-x r r Esc right
M-S-right C-c C-x R R
M-up C-c C-x u Esc up
M-S-up C-c C-x U U
M-down C-c C-x d Esc down
M-S-down C-c C-x D D
S-RET C-c C-x c
M-RET C-c C-x m Esc RET
M-S-RET C-c C-x M
S-left C-c left
S-right C-c right
S-up C-c up
S-down C-c down
C-S-left C-c C-x left
C-S-right C-c C-x right

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.9 Interaction with other packages

comment(none) to "org/Interactionwithotherpackages"
Org lives in the world of GNU Emacs and interacts in various ways with other code out there.

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.9.1 Packages that Org cooperates with

comment(none) to "org/PackagesthatOrgcooperateswith"

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

15.9.2 Packages that lead to conflicts with Org-mode

comment(none) to "org/PackagesthatleadtoconflictswithOrg-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.

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)

[ << ] [ >> ]           [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]