summaryrefslogtreecommitdiff
path: root/contrib/orgmanual.org
diff options
context:
space:
mode:
authorS├ębastien Delafond <sdelafond@gmail.com>2016-11-07 10:41:54 +0100
committerS├ębastien Delafond <sdelafond@gmail.com>2016-11-07 10:41:54 +0100
commit1a7cd65ca362047cd97d4127d49108994baebc6c (patch)
treef18735f3b77120ef2e91043f2f662b03e47ccbb0 /contrib/orgmanual.org
parent55074078ca876273e3fa58ee6838cba90d2b6100 (diff)
parentec84430cf4e09ba25ec675debdf802bc28111e06 (diff)
Merge tag 'upstream/9.0'
Upstream version 9.0
Diffstat (limited to 'contrib/orgmanual.org')
-rw-r--r--contrib/orgmanual.org19743
1 files changed, 19743 insertions, 0 deletions
diff --git a/contrib/orgmanual.org b/contrib/orgmanual.org
new file mode 100644
index 0000000..8b8ae1e
--- /dev/null
+++ b/contrib/orgmanual.org
@@ -0,0 +1,19743 @@
+#+TITLE: Org Mode
+#+AUTHOR: Carsten Dominik
+#+EMAIL: tsd@tsdye.com
+#+DATE: {{{modification-time}}}
+#+SUBTITLE: Release {{{version}}}
+#+SUBAUTHOR: with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K.
+
+#+LANGUAGE: en
+#+OPTIONS: H:4 num:t toc:t \n:nil ::t |:t ^:nil -:t f:t *:t <:t
+#+OPTIONS: d:nil todo:nil pri:nil tags:not-in-toc
+#+SELECT_TAGS: export
+#+EXCLUDE_TAGS: noexport
+
+#+TEXINFO_DIR_CATEGORY: Emacs editing modes
+#+TEXINFO_DIR_TITLE: Org Mode: (org)
+#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
+
+# Use proper quote and backtick for code sections in PDF output
+# Cf. Texinfo manual 14.2
+#+TEXINFO_HEADER: @set txicodequoteundirected
+#+TEXINFO_HEADER: @set txicodequotebacktick
+
+# Contact Info
+#+TEXINFO_HEADER: @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
+#+TEXINFO_HEADER: @set MAINTAINER Carsten Dominik
+#+TEXINFO_HEADER: @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
+#+TEXINFO_HEADER: @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
+
+#+STARTUP: overview
+#+TODO: FIXME | FIXED
+
+* Introduction
+ :PROPERTIES:
+ :TITLE: Introduction
+ :DESCRIPTION: Getting started
+ :END:
+#+cindex: introduction
+
+** Summary
+ :PROPERTIES:
+ :DESCRIPTION: Brief summary of what Org-mode does
+ :END:
+#+cindex: summary
+
+Org is a mode for keeping notes, maintaining TODO lists, and doing
+project planning with a fast and effective plain-text system.
+
+Org develops organizational tasks around NOTES files that contain
+lists or information about projects as plain text. Org is implemented
+on top of Outline mode, which makes it possible to keep the content of
+large files well structured. Visibility cycling and structure editing
+help to work with the tree. Tables are easily created with a built-in
+table editor. Org supports TODO items, deadlines, timestamps, and
+scheduling. It dynamically compiles entries into an agenda that
+utilizes and smoothly integrates much of the Emacs calendar and diary.
+Plain text URL-like links connect to websites, emails, Usenet
+messages, BBDB entries, and any files related to the projects. For
+printing and sharing of notes, an Org file can be exported as a
+structured ASCII file, as HTML, or as an iCalendar file.[fn:1] It can
+also serve as a publishing tool for a set of linked web pages.
+
+As a project planning environment, Org works by adding metadata to
+outline nodes. Based on this data, specific entries can be extracted
+in queries and create dynamic /agenda views/.
+
+Org mode contains the Org Babel environment which allows you to work
+with embedded source code blocks in a file, to facilitate code
+evaluation, documentation, and literate programming techniques.
+
+Org's automatic, context-sensitive table editor with spreadsheet
+capabilities can be integrated into any major mode by activating the
+minor Orgtbl mode. Using a translation step, it can be used to
+maintain tables in arbitrary file types, for example in LaTeX. The
+structure editing and list creation capabilities can be used outside
+Org with the minor Orgstruct mode.
+
+Org keeps simple things simple. When first fired up, it should feel
+like a straightforward, easy to use outliner. Complexity is not
+imposed, but a large amount of functionality is available when you
+need it. Org is a toolbox and can be used in different ways and for
+different ends, for example:
+
+ - an outline extension with visibility cycling and structure editing
+ - an ASCII system and table editor for taking structured notes
+ - a TODO list editor
+ - a full agenda and planner with deadlines and work scheduling
+ #+pindex: GTD, Getting Things Done
+ - an environment in which to implement David Allen's GTD system
+ - a simple hypertext system, with HTML and LaTeX export
+ - a publishing tool to create a set of interlinked web pages
+ - an environment for literate programming
+
+#+cindex: FAQ
+
+There is a [[http://orgmode.org][website for Org]] that provides links to the newest version
+of Org, as well as additional information, frequently asked questions
+(FAQ), links to tutorials, etc.
+
+#+cindex: print edition
+
+Version 7.3 of this manual is available as a [[http://www.network-theory.co.uk/org/manual/][paperback book from
+Network Theory Ltd.]]
+
+{{{page}}}
+
+** Installation
+ :PROPERTIES:
+ :DESCRIPTION: How to install a downloaded version of Org-mode
+ :END:
+
+#+cindex: installation
+#+cindex: XEmacs
+
+*Important:* If you have the version of Org that comes with Emacs or
+as a XEmacs package, please skip this section and go directly to
+[[Activation]]. If you downloaded Org as an ELPA package, please read the
+instructions on the [[http://orgmode.org/elpa.html][Org ELPA page]]. To see what version of Org (if any)
+is part of your Emacs distribution, type {{{kbd(M-x org-version)}}}.[fn:2]
+
+Installation of Org mode uses a build system, which is described in more
+detail on [[http://orgmode.org/worg/dev/org-build-system.html][Worg]].
+
+If you have downloaded Org from the Web as a distribution {{{file(.zip)}}} or
+{{{file(.tar.gz)}}} archive, take the following steps to install it:
+
+ - Unpack the distribution archive
+ - Change into (~cd~) the Org directory
+ - Run ~make help config~ and then check and edit the file
+ {{{file(local.mk)}}} if the default configuration does not match
+ your system
+
+ - Set the name of the Emacs binary (likely either
+ {{{file(emacs)}}} or {{{file(xemacs)}}}), and the paths to the
+ directories where local Lisp and Info files will be installed
+ - If the Emacs binary is not in your path, give the full path to
+ the executable
+ - Avoid spaces in any path names
+
+ - Run ~make config~ again to check the configuration
+ - Run ~make install~ or ~sudo make install~ to build and install Org
+ mode on your system
+
+If you use a cloned Git repository, then the procedure is slightly
+different. The following description assumes that you are using the
+~master~ branch.[fn:3] You could also use the ~maint~ branch instead,
+where the release versions are published, just replace ~master~ with
+~maint~ in the description below.
+
+ - Change into (~cd~) the Org repository
+ - Run ~git checkout master~ to switch to the ~master~ branch of the
+ Org repository
+ - Run ~make help~ and then check and edit the file {{{file(local.mk)}}}
+
+ - You must set the name of the Emacs binary
+ (likely either {{{file(emacs)}}} or {{{file(xemacs)}}}), and the
+ paths to the directories where local Lisp and Info files will be
+ installed
+ - If the Emacs binary is not in your path, you must give
+ the full path to the executable
+ - Avoid spaces in any path names
+
+ - Run ~make config~ to check the configuration
+ - Optionally run ~make test~ to build Org mode and then run the full
+ test suite
+ - Run ~make update2~ or ~make up2~ to update the Git repository and
+ build and install Org mode. The latter invocation runs the
+ complete test suite before installation and installs only if the
+ build passes all tests
+
+If you don't have access to the system-wide directories and you don't
+want to install somewhere into your home directory, you can run Org
+directly from the distribution directory or Org repository by
+compiling Org mode in place:
+
+ - Change into (~cd~) the Org repository
+ - Run ~git checkout master~ to switch to the ~master~ branch of the
+ Org repository
+ - Run ~make compile~
+
+Last but not least you can also run Org mode directly from an Org repository
+without any compilation. Simply replace the last step in the recipe above
+with ~make uncompiled~.
+
+Then add the following line to {{{file(.emacs)}}}:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(add-to-list 'load-path "~/path/to/orgdir/lisp")
+#+end_src
+
+{{{noindent}}}
+If you plan to use code files from the {{{file(contrib)}}} subdirectory without
+compiling them, do a similar step for this directory:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
+#+end_src
+
+If you want to include those files with the build and install, please
+customize the variable ~ORG_ADD_CONTRIB~ instead in your
+~local.mk~ file. For more details please see this
+[[http://orgmode.org/worg/dev/org-build-system.html#sec-4-1-2][description on Worg]].
+
+Installing Info files is system dependent, because of differences in
+the {{{file(install-info)}}} program. The Info documentation is
+installed together with the rest of Org mode. If you don't install Org
+mode, it is possible to install the Info documentation separately if you
+have install-info on your system.[fn:4]
+
+The command to do this is:
+
+#+begin_example
+ make install-info
+#+end_example
+
+Do not forget to activate Org as described in the following section.
+{{{page}}}
+
+** Activation
+ :PROPERTIES:
+ :DESCRIPTION: How to activate Org-mode for certain buffers
+ :END:
+#+cindex: activation
+#+cindex: autoload
+#+cindex: ELPA
+#+cindex: global key bindings
+#+cindex: key bindings, global
+#+findex: org-agenda
+#+findex: org-capture
+#+findex: org-store-link
+#+findex: org-iswitchb
+
+Since Emacs 22.2, files with the {{{file(.org)}}} extension use Org mode by
+default. If you are using an earlier version of Emacs, add this line to your
+{{{file(.emacs)}}} file:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
+#+end_src
+
+Org mode buffers need font-lock to be turned on - this is the default in
+Emacs.[fn:5]
+
+There are compatibility issues between Org mode and some other Elisp
+packages, please take the time to check the list (see [[Conflicts]]).
+
+The four Org commands {{{command(org-store-link)}}},
+{{{command(org-capture)}}}, {{{command(org-agenda)}}}, and
+{{{command(org-iswitchb)}}} should be accessible through global keys
+(i.e., anywhere in Emacs, not just in Org buffers). Here are
+suggested bindings for these keys, please modify the keys to your own
+liking.
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(global-set-key "\C-cl" 'org-store-link)
+(global-set-key "\C-cc" 'org-capture)
+(global-set-key "\C-ca" 'org-agenda)
+(global-set-key "\C-cb" 'org-iswitchb)
+#+end_src
+
+#+cindex: Org mode, turning on
+With this setup, all files with extension {{{samp(.org)}}} will be put
+into Org mode. As an alternative, make the first line of a file look
+like this:
+
+#+begin_example
+ MY PROJECTS -*- mode: org; -*-
+#+end_example
+
+#+vindex: org-insert-mode-line-in-empty-file
+{{{noindent}}}
+which will select Org mode for this buffer no matter what the file's
+name is. See also the variable
+~org-insert-mode-line-in-empty-file~.
+
+Many commands in Org work on the region if the region is /active/. To
+make use of this, you need to have ~transient-mark-mode~
+(~zmacs-regions~ in XEmacs) turned on. In Emacs 23 this is the
+default, in Emacs 22 you need to do this yourself with
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(transient-mark-mode 1)
+#+end_src
+
+{{{noindent}}} If you do not like ~transient-mark-mode~, you can
+create an active region by using the mouse to select a region, or
+pressing {{{kbdkey(C-,SPC)}}} twice before moving the cursor.
+
+** Feedback
+ :PROPERTIES:
+ :DESCRIPTION: Bug reports, ideas, patches, etc.
+ :END:
+#+cindex: feedback
+#+cindex: bug reports
+#+cindex: maintainer
+#+cindex: author
+
+If you find problems with Org, or if you have questions, remarks, or
+ideas about it, please mail to the Org mailing list
+[[mailto:emacs-orgmode@gnu.org]]. If you are not a member of
+the mailing list, your mail will be passed to the list after a
+moderator has approved it.[fn:6]
+
+For bug reports, please first try to reproduce the bug with the latest
+version of Org available---if you are running an outdated version, it
+is quite possible that the bug has been fixed already. If the bug
+persists, prepare a report and provide as much information as
+possible, including the version information of Emacs ({{{kbdspckey(M-x
+emacs-version,RET)}}}) and Org ({{{kbdspckey(M-x org-version,RET)}}}),
+as well as the Org related setup in {{{file(.emacs)}}}. The easiest
+way to do this is to use the command {{{kbd(M-x
+org-submit-bug-report)}}}, which will put all this information into an
+Emacs mail buffer so that you only need to add your description. If
+you are not sending the Email from within Emacs, please copy and paste
+the content into your Email program.
+
+Sometimes you might face a problem due to an error in your Emacs or
+Org mode setup. Before reporting a bug, it is very helpful to start
+Emacs with minimal customizations and reproduce the problem. Doing so
+often helps you determine if the problem is with your customization or
+with Org mode itself. You can start a typical minimal session with a
+command like the example below.
+
+#+begin_src sh :exports code
+$ emacs -Q -l /path/to/minimal-org.el
+#+end_src
+
+However if you are using Org mode distributed with Emacs, a minimal
+setup is not necessary. In that case it is sufficient to start Emacs
+as ~emacs -Q~. The ~minimal-org.el~ setup
+file can have contents as shown below.
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+;;; Minimal setup to load latest `org-mode'
+
+;; activate debugging
+(setq debug-on-error t
+ debug-on-signal nil
+ debug-on-quit nil)
+
+;; add latest org-mode to load path
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
+#+end_src
+
+If an error occurs, a backtrace can be very useful (see [[How to
+create a useful backtrace]]). Often a small example file helps, along
+with clear information about:
+
+ 1. What exactly did you do?
+ 2. What did you expect to happen?
+ 3. What happened instead?
+
+{{{noindent}}} Thank you for helping to improve this program.
+
+** How to create a useful backtrace
+ :PROPERTIES:
+ :DESCRIPTION: The best way to report an error
+ :END:
+
+#+cindex: backtrace of an error
+
+If working with Org produces an error with a message you don't
+understand, you may have hit a bug. The best way to report this is by
+providing, in addition to what was mentioned above, a /backtrace/.
+This is information from the built-in debugger about where and how the
+error occurred. Here is how to produce a useful backtrace:
+
+ 1. Reload uncompiled versions of all Org mode Lisp files. The
+ backtrace contains much more information if it is produced with
+ uncompiled code. To do this, use
+ {{{kbdspckey(C-u M-x org-reload,RET)}}} or select
+ ~Org -> Refresh/Reload -> Reload Org uncompiled~ from the menu.
+
+ 2. Go to the ~Options~ menu and select ~Enter Debugger on Error~
+ (XEmacs has this option in the ~Troubleshooting~ sub-menu).
+
+ 3. Do whatever you have to do to hit the error. Don't forget to
+ document the steps you take.
+
+ 4. When you hit the error, a {{{file(*Backtrace*)}}} buffer will
+ appear on the screen. Save this buffer to a file (for example
+ using {{{kbd(C-x C-w)}}}) and attach it to your bug report.
+
+** Conventions
+ :PROPERTIES:
+ :DESCRIPTION: Typesetting conventions in the manual
+ :END:
+
+Conventions for typesetting keywords, keybindings, and commands in
+this manual are described.
+
+*** Three types of keywords
+ :PROPERTIES:
+ :DESCRIPTION: TODO, tags, and properties
+ :END:
+
+Org mainly uses three types of keywords: TODO keywords, tags and property
+names. In this manual we use the following conventions:
+
+ - TODO, WAITING :: TODO keywords are written with all capitals, even if they
+ are user-defined.
+ - boss, ARCHIVE :: User-defined tags are written in lowercase; built-in
+ tags with special meaning are written with all capitals.
+ - Release, PRIORITY :: User-defined properties are capitalized; built-in
+ properties with special meaning are written with all capitals.
+
+Moreover, Org uses /option keywords/ (like ~#+TITLE~ to set the title)
+and /environment keywords/ (like ~#+BEGIN_HTML~ to start a ~HTML~
+environment). They are written in uppercase in the manual to enhance
+its readability, but you can use lowercase in your Org files.[fn:7]
+
+*** Keybindings and commands
+ :PROPERTIES:
+ :DESCRIPTION: Bind useful commands to keys
+ :END:
+
+#+kindex: C-c a
+#+findex: org-agenda
+#+kindex: C-c c
+#+findex: org-capture
+
+The manual suggests two global keybindings: {{{kbd(C-c a)}}} for
+~org-agenda~ and {{{kbd(C-c c)}}} for ~org-capture~. These are only
+suggestions, but the rest of the manual assumes that you are using
+these keybindings.
+
+Also, the manual lists both the keys and the corresponding commands
+for accessing a functionality. Org mode often uses the same key for
+different functions, depending on context. The command that is bound
+to such keys has a generic name, like ~org-metaright~. In the manual
+we will, wherever possible, give the function that is internally
+called by the generic command. For example, in the chapter on document
+structure, {{{kbdkey(M-,right)}}} will be listed to call
+~org-do-demote~, while in the chapter on tables, it will be listed to
+call ~org-table-move-column-right~.
+
+# If you prefer, you can compile the manual without the command names by unsetting the flag ~cmdnames~ in {{{file(org.texi)}}}.
+
+* Document structure
+ :PROPERTIES:
+ :DESCRIPTION: A tree works like your brain
+ :ALT_TITLE: Document Structure
+ :END:
+#+cindex: document structure
+#+cindex: structure of document
+
+Org is based on Outline mode and provides flexible commands to
+edit the structure of the document.
+
+** Outlines
+ :PROPERTIES:
+ :DESCRIPTION: Org mode is based on Outline mode
+ :END:
+#+cindex: outlines
+#+cindex: Outline mode
+
+Org is implemented on top of Outline mode. Outlines allow a document
+to be organized in a hierarchical structure, which (at least for me)
+is the best representation of notes and thoughts. An overview of this
+structure is achieved by folding (hiding) large parts of the document
+to show only the general document structure and the parts currently
+being worked on. Org greatly simplifies the use of outlines by
+compressing the entire show/hide functionality into a single command,
+{{{command(org-cycle)}}}, which is bound to the {{{key(TAB)}}} key.
+
+** Headlines
+ :PROPERTIES:
+ :DESCRIPTION: How to typeset Org tree headlines
+ :END:
+#+cindex: headlines
+#+cindex: outline tree
+#+vindex: org-special-ctrl-a/e
+#+vindex: org-special-ctrl-k
+#+vindex: org-ctrl-k-protect-subtree
+
+Headlines define the structure of an outline tree. The headlines in Org
+start with one or more stars, on the left margin.[fn:8] For example:
+
+#+begin_src org
+ ,* Top level headline
+ ,** Second level
+ ,*** Third level
+ some text
+ ,*** Third level
+ more text
+ ,* Another top level headline
+#+end_src
+
+{{{noindent}}} Some people find the many stars too noisy and would
+prefer an outline that has whitespace followed by a single star as
+headline starters. A setup to realize this is described in the
+section, [[Clean view]].
+
+#+vindex: org-cycle-separator-lines
+An empty line after the end of a subtree is considered part of it and
+will be hidden when the subtree is folded. However, if you leave at
+least two empty lines, one empty line will remain visible after folding
+the subtree, in order to structure the collapsed view. See the
+variable ~org-cycle-separator-lines~ to modify this behavior.
+
+** Visibility cycling
+ :PROPERTIES:
+ :DESCRIPTION: Show and hide, much simplified
+ :ALT_TITLE: Visibility cycling
+ :END:
+#+cindex: cycling, visibility
+#+cindex: visibility cycling
+#+cindex: trees, visibility
+#+cindex: show hidden text
+#+cindex: hide text
+
+Outlines make it possible to hide parts of the text in the buffer.
+Org uses just two commands, bound to {{{key(TAB)}}} and
+{{{kbdkey(S-,TAB)}}} to change the visibility in the buffer.
+
+#+cindex: subtree visibility states
+#+cindex: subtree cycling
+#+cindex: folded, subtree visibility state
+#+cindex: children, subtree visibility state
+#+cindex: subtree, subtree visibility state
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{key(TAB)}}}, ~org-cycle~ :: Subtrees can be cycled through three
+ states:
+ #+kindex: TAB
+ #+findex: org-cycle
+
+ #+begin_src example
+ ,-> FOLDED -> CHILDREN -> SUBTREE --.
+ '-----------------------------------'
+ #+end_src
+
+ #+vindex: org-cycle-emulate-tab
+ #+vindex: org-cycle-global-at-bob
+
+ By default, the cursor must be on a headline for this to work,
+ but this behavior can be modified with the
+ ~org-cycle-emulate-tab~ option. When the cursor is at the
+ beginning of the buffer and the first line is not a headline,
+ then {{{key(TAB)}}} actually runs global cycling (see
+ below).[fn:9] Also, when called with a prefix argument
+ ({{{kbdspckey(C-u,TAB)}}}), global cycling is invoked.
+
+- {{{kbdkey(S-,TAB)}}} or {{{kbdspckey(C-u,TAB)}}}, ~org-global-cycle~ ::
+ Global cycling: Rotate the entire buffer among the states
+
+ #+cindex: global visibility states
+ #+cindex: global cycling
+ #+cindex: overview, global visibility state
+ #+cindex: contents, global visibility state
+ #+cindex: show all, global visibility state
+ #+kindex: C-u TAB
+ #+kindex: S-TAB
+ #+findex: org-global-cycle
+
+ #+begin_example
+ ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
+ '--------------------------------------'
+ #+end_example
+
+ When {{{kbdkey(S-,TAB)}}} is called with a numeric prefix
+ argument, ~N~, the CONTENTS view up to headlines of level N will
+ be shown. Note that inside tables, {{{kbdkey(S-,TAB)}}} jumps
+ to the previous field.
+
+- {{{kbdspckey(C-u C-u C-u,TAB)}}}, ~show-all~ :: Show all, including
+ drawers.
+
+ #+kindex: C-u C-u C-u TAB
+ #+findex: show-all
+ #+cindex: show all, command
+- {{{kbd(C-c C-r)}}}, ~org-reveal~ :: Reveal context around point,
+ showing the current entry, the following heading and the
+ hierarchy above. Useful for working near a location that has
+ been exposed by a sparse tree command (see [[Sparse trees]]) or an
+ agenda command (see [[Agenda commands]]). With a prefix argument
+ show, on each level, all sibling headings. With a double prefix
+ argument, also show the entire subtree of the parent.
+
+ #+cindex: revealing context
+ #+kindex: C-c C-r
+ #+findex: org-reveal
+- {{{kbd(C-c C-k)}}}, ~show-branches~ :: Expose all the headings of
+ the subtree, CONTENT view for just one subtree.
+
+ #+kindex: C-c C-k
+ #+findex: show-branches
+ #+cindex: show branches, command
+- {{{kbdspckey(C-c,TAB)}}}, ~show-children~ :: Expose all direct
+ children of the subtree. With a numeric prefix argument, ~N~,
+ expose all children down to level N.
+
+ #+kindex: C-c TAB
+ #+findex: show-children
+ #+cindex: show children, command
+- {{{kbd(C-c C-x b)}}}, ~org-tree-to-indirect-buffer~ :: Show the
+ current subtree in an indirect buffer.[fn:10] With a numeric
+ prefix argument, ~N~, go up to level N and then take that tree.
+ If N is negative then go up that many levels. With a
+ {{{kbd(C-u)}}} prefix, do not remove the previously used indirect
+ buffer.
+
+ #+kindex: C-c C-x b
+ #+findex: org-tree-to-indirect-buffer
+- {{{kbd(C-c C-x v)}}}, ~org-copy-visible~ :: Copy the /visible/ text
+ in the region into the kill ring.
+
+#+vindex: org-startup-folded
+#+cindex: ~overview~, STARTUP keyword
+#+cindex: ~content~, STARTUP keyword
+#+cindex: ~showall~, STARTUP keyword
+#+cindex: ~showeverything~, STARTUP keyword
+
+When Emacs first visits an Org file, the global state is set to
+OVERVIEW, i.e., only the top level headlines are visible. This can be
+configured through the variable ~org-startup-folded~, or on a
+per-file basis by adding one of the following lines anywhere in the
+buffer:
+
+#+begin_src org
+ ,#+STARTUP: overview
+ ,#+STARTUP: content
+ ,#+STARTUP: showall
+ ,#+STARTUP: showeverything
+#+end_src
+
+#+cindex: property, VISIBILITY
+
+{{{noindent}}} Furthermore, any entries with a {{{samp(VISIBILITY)}}}
+property (see [[Properties and columns]]) will get their visibility
+adapted accordingly. Allowed values for this property are ~folded~,
+~children~, ~content~, and ~all~.
+
+#+attr_texinfo: :indic @asis
+- {{{kbdspckey(C-u C-u,TAB)}}}, ~org-set-startup-visibility~ :: Switch
+ back to the startup visibility of the buffer, i.e., whatever is
+ requested by startup options and {{{samp(VISIBILITY)}}}
+ properties in individual entries.
+
+** Motion
+ :PROPERTIES:
+ :DESCRIPTION: Jumping to other headlines
+ :END:
+#+cindex: motion, between headlines
+#+cindex: jumping, to headlines
+#+cindex: headline navigation
+The following commands jump to other headlines in the buffer.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c C-n)}}}, ~outline-next-visible-heading~ :: Next heading.
+ #+kindex: C-c C-n
+ #+findex: outline-next-visible-heading
+ - {{{kbd(C-c C-p)}}}, ~outline-previous-visible-heading~ :: Previous heading.
+ #+kindex: C-c C-p
+ #+findex: outline-previous-visible-heading
+ - {{{kbd(C-c C-f)}}}, ~org-forward-same-level~ :: Next heading same level.
+ #+kindex: C-c C-f
+ #+findex: org-forward-same-level
+ - {{{kbd(C-c C-b)}}}, ~org-backward-same-level~ :: Previous heading same level.
+ #+kindex: C-c C-b
+ #+findex: org-backward-same-level
+ - {{{kbd(C-c C-u)}}}, ~outline-up-heading~ :: Backward to higher level heading.
+ #+kindex: C-c C-u
+ #+findex: outline-up-heading
+ - {{{kbd(C-c C-j)}}}, ~org-goto~ :: Jump to a different place without
+ changing the current outline visibility. Shows the document
+ structure in a temporary buffer, where you can use the
+ following keys to find your destination:
+
+ #+kindex: C-c C-j
+ #+findex: org-goto
+ #+vindex: org-goto-auto-isearch
+ - {{{key(TAB)}}} :: Cycle visibility.
+ - {{{key(down)}}} / {{{key(up)}}} :: Next/previous visible headline.
+ - {{{key(RET)}}} :: Select this location.
+ - {{{kbd(/)}}} :: Do a Sparse-tree search
+ The following keys work if you turn off ~org-goto-auto-isearch~
+ - n / p :: Next/previous visible headline.
+ - f / b :: Next/previous headline same level.
+ - u :: One level up.
+ - 0--9 :: Digit argument.
+ - q :: Quit.
+
+#+vindex: org-goto-interface
+{{{noindent}}} See also the variable ~org-goto-interface~.
+
+** Structure editing
+ :PROPERTIES:
+ :DESCRIPTION: Changing sequence and level of headlines
+ :ALT_TITLE: Structure editing
+ :END:
+#+cindex: structure editing
+#+cindex: headline, promotion and demotion
+#+cindex: promotion, of subtrees
+#+cindex: demotion, of subtrees
+#+cindex: subtree, cut and paste
+#+cindex: pasting, of subtrees
+#+cindex: cutting, of subtrees
+#+cindex: copying, of subtrees
+#+cindex: sorting, of subtrees
+#+cindex: subtrees, cut and paste
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ :: Insert new heading
+ with same level as current. If the cursor is in a plain list
+ item, a new item is created (see [[Plain lists]]). To force
+ creation of a new headline, use a prefix argument. When this
+ command is used in the middle of a line, the line is split and
+ the rest of the line becomes the new headline.[fn:11] If the
+ command is used at the beginning of a headline, the new
+ headline is created before the current line. If at the
+ beginning of any other line, the content of that line is made
+ the new heading. If the command is used at the end of a folded
+ subtree (i.e., behind the ellipses at the end of a headline),
+ then a headline like the current one will be inserted after the
+ end of the subtree.
+
+ #+kindex: M-RET
+ #+findex: org-insert-heading
+ #+vindex: org-M-RET-may-split-line
+ - {{{kbdkey(C-,RET)}}}, ~org-insert-heading-respect-content~ :: Just
+ like {{{kbdkey(M-,RET)}}}, except when adding a new heading
+ below the current heading, the new heading is placed after the
+ body instead of before it. This command works from anywhere in
+ the entry.
+
+ #+kindex: C-RET
+ #+findex: org-insert-heading-respect-content
+ - {{{kbdkey(M-S-,RET)}}}, ~org-insert-todo-heading~ :: Insert new
+ TODO entry with same level as current heading. See also the
+ variable ~org-treat-insert-todo-heading-as-state-change~.
+
+ #+kindex: M-S-RET
+ #+findex: org-insert-todo-heading
+ #+vindex: org-treat-insert-todo-heading-as-state-change
+ - {{{kbdkey(C-S-,RET)}}}, ~org-insert-todo-heading-respect-content~ :: Insert
+ new TODO entry with same level as current heading. Like
+ {{{kbdkey(C-,RET)}}}, the new headline will be inserted after
+ the current subtree.
+
+ #+kindex: C-S-RET
+ #+findex: org-insert-todo-heading-respect-content
+ - {{{key(TAB)}}}, ~org-cycle~ :: In a new entry with no text
+ yet, the first {{{key(TAB)}}} demotes the entry to become a
+ child of the previous one. The next {{{key(TAB)}}} makes it a
+ parent, and so on, all the way to top level. Yet another
+ {{{key(TAB)}}}, and you are back to the initial level.
+
+ #+kindex: @key{TAB}
+ #+findex: org-cycle
+ - {{{kbdkey(M-,left)}}}, ~org-do-promote~ :: Promote current heading
+ by one level.
+
+ #+kindex: M-left
+ #+findex: org-do-promote
+ - {{{kbdkey(M-,right)}}}, ~org-do-demote~ :: Demote current heading
+ by one level.
+
+ #+kindex: M-right
+ #+findex: org-do-demote
+ - {{{kbdkey(M-S-,left)}}}, ~org-promote-subtree~ :: Promote the
+ current subtree by one level.
+
+ #+kindex: M-S-left
+ #+findex: org-promote-subtree
+ - {{{kbdkey(M-S-,right)}}}, ~org-demote-subtree~ :: Demote the
+ current subtree by one level.
+
+ #+kindex: M-S-right
+ #+findex: org-demote-subtree
+ - {{{kbdkey(M-S-,up)}}}, ~org-move-subtree-up~ :: Move subtree up
+ (swap with previous subtree of same level).
+
+ #+kindex: M-S-up
+ #+findex: org-move-subtree-up
+ - {{{kbdkey(M-S-,down)}}}, ~org-move-subtree-down~ :: Move subtree
+ down (swap with next subtree of same level).
+
+ #+kindex: M-S-,down
+ #+findex: org-move-subtree-down
+ - {{{kbd(C-c C-x C-w)}}}, ~org-cut-subtree~ :: Kill subtree, i.e.,
+ remove it from buffer but save in kill ring. With a numeric
+ prefix argument N, kill N sequential subtrees.
+
+ #+kindex: C-c C-x C-w
+ #+findex: org-cut-subtree
+ - {{{kbd(C-c C-x M-w)}}}, ~org-copy-subtree~ :: Copy subtree to kill
+ ring. With a numeric prefix argument N, copy the N sequential
+ subtrees.
+
+ #+kindex: C-c C-x M-w
+ #+findex: org-copy-subtree
+ - {{{kbd(C-c C-x C-y)}}}, ~org-paste-subtree~ :: Yank subtree from
+ kill ring. This does modify the level of the subtree to make
+ sure the tree fits in nicely at the yank position. The yank
+ level can also be specified with a numeric prefix argument, or
+ by yanking after a headline marker like {{{samp(****)}}}.
+
+ #+kindex: C-c C-x C-y
+ #+findex: org-paste-subtree
+ - {{{kbd(C-y)}}}, ~org-yank~ :: Depending on the variables
+ ~org-yank-adjusted-subtrees~ and ~org-yank-folded-subtrees~,
+ Org's internal ~yank~ command will paste subtrees folded and in
+ a clever way, using the same command as {{{kbd(C-c C-x C-y)}}}.
+ With the default settings, no level adjustment will take place,
+ but the yanked tree will be folded unless doing so would
+ swallow text previously visible. Any prefix argument to this
+ command will force a normal ~yank~ to be executed, with the
+ prefix passed along. A good way to force a normal yank is
+ {{{kbd(C-u C-y)}}}. If you use ~yank-pop~ after a yank, it
+ will yank previous kill items plainly, without adjustment and
+ folding.
+
+ #+kindex: C-y
+ #+findex: org-yank
+ #+vindex: org-yank-adjusted-subtrees
+ #+vindex: org-yank-folded-subtrees
+ - {{{kbd(C-c C-x c)}}}, ~org-clone-subtree-with-time-shift~ :: Clone
+ a subtree by making a number of sibling copies of it. You will
+ be prompted for the number of copies to make, and you can also
+ specify if any timestamps in the entry should be shifted. This
+ can be useful, for example, to create a number of tasks related
+ to a series of lectures to prepare. For more details, see the
+ docstring of the command ~org-clone-subtree-with-time-shift~.
+
+ #+kindex: C-c C-x c
+ #+findex: org-clone-subtree-with-time-shift
+ - {{{kbd(C-c C-w)}}}, ~org-refile~ :: Refile entry or region to a
+ different location. See [[Refile and copy]].
+
+ #+kindex: C-c C-w
+ #+findex: org-refile
+ - {{{kbd(C-c ^)}}}, ~org-sort~ :: Sort same-level entries. When
+ there is an active region, all entries in the region will be
+ sorted. Otherwise the children of the current headline are
+ sorted. The command prompts for the sorting method, which can
+ be alphabetically, numerically, by time (first timestamp with
+ active preferred, creation time, scheduled time, deadline
+ time), by priority, by TODO keyword (in the sequence the
+ keywords have been defined in the setup) or by the value of a
+ property. Reverse sorting is possible as well. You can also
+ supply your own function to extract the sorting key. With a
+ {{{kbd(C-u)}}} prefix, sorting will be case-sensitive.
+
+ #+kindex: C-c ^
+ #+findex: org-sort
+ - {{{kbd(C-x n s)}}}, ~org-narrow-to-subtree~ :: Narrow buffer to
+ current subtree.
+
+ #+kindex: C-x n s
+ #+findex: org-narrow-to-subtree
+ - {{{kbd(C-x n b)}}}, ~org-narrow-to-block~ :: Narrow buffer to
+ current block.
+
+ #+kindex: C-x n b
+ #+findex: org-narrow-to-block
+ - {{{kbd(C-x n w)}}}, ~widen~ :: Widen buffer to remove narrowing.
+
+ #+kindex: C-x n w
+ #+findex: widen
+ - {{{kbd(C-c *)}}}, ~org-toggle-heading~ :: Turn a normal line or
+ plain list item into a headline (so that it becomes a
+ subheading at its location). Also turn a headline into a normal
+ line by removing the stars. If there is an active region, turn
+ all lines in the region into headlines. If the first line in
+ the region was an item, turn only the item lines into
+ headlines. Finally, if the first line is a headline, remove the
+ stars from all headlines in the region.
+
+ #+kindex: C-c *
+ #+findex: org-toggle-heading
+
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient mark mode
+
+When there is an active region (Transient Mark mode), promotion and
+demotion work on all headlines in the region. To select a region of
+headlines, it is best to place both point and mark at the beginning of
+a line, mark at the beginning of the first headline, and point at the
+line just after the last headline to change. Note that when the
+cursor is inside a table (see [[Tables]]), the Meta-Cursor keys have
+different functionality.
+
+** Sparse trees
+ :PROPERTIES:
+ :DESCRIPTION: Matches embedded in context
+ :ALT_TITLE: Sparse trees
+ :END:
+#+cindex: sparse trees
+#+cindex: trees, sparse
+#+cindex: folding, sparse trees
+#+cindex: occur, command
+#+vindex: org-show-hierarchy-above
+#+vindex: org-show-following-heading
+#+vindex: org-show-siblings
+#+vindex: org-show-entry-below
+
+An important feature of Org mode is the ability to construct /sparse
+trees/ for selected information in an outline tree, so that the entire
+document is folded as much as possible, but the selected information
+is made visible along with the headline structure above it.[fn:12]
+Just try it out and you will see immediately how it works.
+
+Org mode contains several commands creating such trees, all these
+commands can be accessed through a dispatcher:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c /)}}}, ~org-sparse-tree~ :: This prompts for an extra
+ key to select a sparse-tree creating command.
+
+ #+kindex: C-c /
+ #+findex: org-sparse-tree
+ - {{{kbd(C-c / r)}}}, ~org-occur~ :: Prompts for a regexp and shows a
+ sparse tree with all matches. If the match is in a headline,
+ the headline is made visible. If the match is in the body of an
+ entry, headline and body are made visible. In order to provide
+ minimal context, also the full hierarchy of headlines above the
+ match is shown, as well as the headline following the
+ match. Each match is also highlighted; the highlights disappear
+ when the buffer is changed by an editing command, or by
+ pressing {{{kbd(C-c C-c)}}}.[fn:13] When called with a {{{kbd(C-u)}}}
+ prefix argument, previous highlights are kept, so several calls
+ to this command can be stacked.
+
+ #+kindex: C-c / r
+ #+findex: org-occur
+ #+vindex: org-remove-highlights-with-change
+ - {{{kbd(M-g n)}}}, ~next-error~ ::
+ @@info:@itemx@@ {{{kbd(M-g M-n)}}}
+
+ Jump to the next sparse tree match in this buffer.
+
+ #+kindex: M-g n
+ #+kindex: M-g M-n
+ #+findex: next-error
+ - {{{kbd(M-g p)}}}, ~previous-error~ ::
+ @@info:@itemx@@ {{{kbd(M-g M-p)}}}
+
+ Jump to the previous sparse tree match in this buffer.
+
+ #+kindex: M-g p
+ #+kindex: M-g M-p
+ #+findex: previous-error
+#+vindex: org-agenda-custom-commands
+
+{{{noindent}}} For frequently used sparse trees of specific search
+strings, you can use the variable ~org-agenda-custom-commands~ to
+define fast keyboard access to specific sparse trees. These commands
+will then be accessible through the agenda dispatcher
+(see [[Agenda dispatcher]]). For example:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ (setq org-agenda-custom-commands
+ '(("f" occur-tree "FIXME")))
+#+end_src
+
+{{{noindent}}} will define the key {{{kbd(C-c a f)}}} as a
+shortcut for creating a sparse tree matching the string
+{{{samp(FIXME)}}}.
+
+The other sparse tree commands select headings based on TODO keywords,
+tags, or properties and will be discussed later in this manual.
+
+#+kindex: C-c C-e v
+#+cindex: printing sparse trees
+#+cindex: visible text, printing
+
+To print a sparse tree, you can use the Emacs command
+~ps-print-buffer-with-faces~ which does not print
+invisible parts of the document.[fn:14] Or you can use the command
+{{{kbd(C-c C-e v)}}} to export only the visible part of the
+document and print the resulting file.
+
+** Plain lists
+ :PROPERTIES:
+ :DESCRIPTION: Additional structure within an entry
+ :ALT_TITLE: Plain lists
+ :END:
+#+cindex: plain lists
+#+cindex: lists, plain
+#+cindex: lists, ordered
+#+cindex: ordered lists
+
+Within an entry of the outline tree, hand-formatted lists can provide
+additional structure. They also provide a way to create lists of
+checkboxes (see [[Checkboxes]]). Org supports editing
+such lists, and every exporter (see [[Exporting]])
+can parse and format them.
+
+Org knows ordered lists, unordered lists, and description lists.
+
+#+attr_texinfo: :table-type table :indic @bullet
+ - /Unordered/ list items start with ~-~, ~+~, or ~*~ as bullets.[fn:15]
+
+ - /Ordered/ list items start with a numeral followed by either a
+ period or a right parenthesis,[fn:16] such as
+ ~1.~ or ~1~.[fn:170] If you want a list to
+ start with a different value (e.g., 20), start the text of the
+ item with ~[@20]~.[fn:17] Those constructs can be used
+ in any item of the list in order to enforce a particular
+ numbering.
+ #+vindex: org-plain-list-ordered-item-terminator
+ #+vindex: org-alphabetical-lists
+
+ - /Description/ list items are unordered list items, and contain the
+ separator {{{samp( :: )}}} to distinguish the description
+ /term/ from the description.
+
+
+Items belonging to the same list must have the same indentation on the
+first line. In particular, if an ordered list reaches number
+{{{samp(10.)}}}, then the 2--digit numbers must be written
+left-aligned with the other numbers in the list. An item ends before
+the next line that is less or equally indented than its bullet/number.
+
+#+vindex: org-empty-line-terminates-plain-lists
+A list ends whenever every item has ended, which means before any line less
+or equally indented than items at top level. It also ends before two blank
+lines.[fn:171] In that case, all items are closed. Here is an example:
+
+#+begin_src texinfo
+ ,** Lord of the Rings
+ My favorite scenes are (in this order)
+ 1. The attack of the Rohirrim
+ 2. Eowyn's fight with the witch king
+ + this was already my favorite scene in the book
+ + I really like Miranda Otto.
+ 3. Peter Jackson being shot by Legolas
+ - on DVD only
+ He makes a really funny face when it happens.
+ But in the end, no individual scenes matter but the film as a whole.
+ Important actors in this film are:
+ - @b{Elijah Wood} :: He plays Frodo
+ - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember
+ him very well from his role as Mikey Walsh in @i{The Goonies}.
+#+end_src
+
+Org supports these lists by tuning filling and wrapping commands to
+deal with them correctly.[fn:18] To turn this on, put into
+{{{file(.emacs)}}}: ~(require 'filladapt)~}, and by exporting them
+properly (see [[Exporting]]). Since indentation is
+what governs the structure of these lists, many structural constructs
+like ~#+BEGIN_ ...~ blocks can be indented to signal that they belong
+to a particular item.
+
+#+vindex: org-list-demote-modify-bullet
+#+vindex: org-list-indent-offset
+If you find that using a different bullet for a sub-list (than that used for
+the current list-level) improves readability, customize the variable
+~org-list-demote-modify-bullet~. To get a greater difference of
+indentation between items and theirs sub-items, customize
+~org-list-indent-offset~.
+
+#+vindex: org-list-automatic-rules
+The following commands act on items when the cursor is in the first line of
+an item (the line with the bullet or number). Some of them imply the
+application of automatic rules to keep list structure intact. If some of
+these actions get in your way, configure ~org-list-automatic-rules~
+to disable them individually.
+
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{key(TAB)}}}, ~org-cycle~ ::
+ #+cindex: cycling, in plain lists
+ #+kindex: TAB
+ #+findex: org-cycle
+ #+vindex: org-cycle-include-plain-lists
+
+ Items can be folded just like headline levels. Normally this
+ works only if the cursor is on a plain list item. For more
+ details, see the variable ~org-cycle-include-plain-lists~. If
+ this variable is set to ~integrate~, plain list items will be
+ treated like low-level headlines. The level of an item is then
+ given by the indentation of the bullet/number. Items are always
+ subordinate to real headlines, however; the hierarchies remain
+ completely separated. In a new item with no text yet, the first
+ {{{key(TAB)}}} demotes the item to become a child of the
+ previous one. Subsequent {{{key(TAB)}}}s move the item to
+ meaningful levels in the list and eventually get it back to its
+ initial position.
+
+ - {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ ::
+ #+kindex: M-RET
+ #+findex: org-insert-heading
+ #+vindex: org-M-RET-may-split-line
+ #+vindex: org-list-automatic-rules
+
+ Insert new item at current level. With a prefix argument, force
+ a new heading (see [[Structure editing]]). If this command is used
+ in the middle of an item, that item is /split/ in two, and the
+ second part becomes the new item.[fn:19] If this command is
+ executed /before item's body/, the new item is created /before/
+ the current one.
+
+ - {{{kbdkey(M-S-,RET)}}} ::
+ #+kindex: M-S-RET
+
+ Insert a new item with a checkbox (see [[Checkboxes]]).
+
+ - {{{kbdkey(S-,up)}}} ::
+ @@info:@itemx@@ {{{kbdkey(S-,down)}}}
+
+ Jump to the previous/next item in the current list, but
+ only if ~org-support-shift-select~ is off.[fn:20] If not, you can
+ still use paragraph jumping commands like {{{kbdkey(C-,up)}}}
+ and {{{kbdkey(C-,down)}}} to quite similar effect.
+
+ #+kindex: S-up
+ #+kindex: S-down
+ #+cindex: shift-selection-mode
+ #+vindex: org-support-shift-select
+ #+vindex: org-list-use-circular-motion
+ - {{{kbdkey(M-,up)}}} ::
+ @@info:@itemx@@ {{{kbdkey(M-,down)}}}
+
+ Move the item including subitems up/down (swap with
+ previous/next item of same indentation).[fn:21] If the list is
+ ordered, renumbering is automatic.
+
+ #+kindex: M-up
+ #+kindex: M-down
+ - {{{kbdkey(M-,left)}}} ::
+ @@info:@itemx@@ {{{kbdkey(M-,right)}}}
+
+ Decrease/increase the indentation of an item, leaving children
+ alone.
+
+ #+kindex: M-left
+ #+kindex: M-right
+ - {{{kbdkey(M-S-,left)}}} ::
+ @@info:@itemx@@ {{{kbdkey(M-S-,right)}}}
+
+ Decrease/increase the indentation of the item, including
+ subitems. Initially, the item tree is selected based on
+ current indentation. When these commands are executed several
+ times in direct succession, the initially selected region is
+ used, even if the new indentation would imply a different
+ hierarchy. To use the new hierarchy, break the command chain
+ with a cursor motion or so.
+
+ #+kindex: M-S-left
+ #+kindex: M-S-right
+
+ As a special case, using this command on the very first item of
+ a list will move the whole list. This behavior can be disabled
+ by configuring ~org-list-automatic-rules~. The global
+ indentation of a list has no influence on the text /after/ the
+ list.
+ - {{{kbd(C-c C-c)}}} :: If there is a checkbox (see [[Checkboxes]]) in
+ the item line, toggle the state of the checkbox. In any case,
+ verify bullets and indentation consistency in the whole list.
+
+ #+kindex: C-c C-c
+ - {{{kbd(C-c -)}}} :: Cycle the entire list level through the
+ different itemize/enumerate bullets ({{{samp(-)}}},
+ {{{samp(+)}}}, {{{samp(*)}}}, {{{samp(1.)}}}, {{{samp(1))}}})
+ or a subset of them, depending on
+ ~org-plain-list-ordered-item-terminator~, the type of list, and
+ its indentation. With a numeric prefix argument N, select the
+ Nth bullet from this list. If there is an active region when
+ calling this, selected text will be changed into an item. With
+ a prefix argument, all lines will be converted to list items.
+ If the first line already was a list item, any item marker will
+ be removed from the list. Finally, even without an active
+ region, a normal line will be converted into a list item.
+
+ #+kindex: C-c -
+ #+vindex: org-plain-list-ordered-item-terminator
+ - {{{kbd(C-c *)}}} :: Turn a plain list item into a headline (so
+ that it becomes a subheading at its location). See
+ [[Structure editing]], for a detailed explanation.
+
+ #+kindex: C-c *
+ - {{{kbd(C-c C-*)}}} :: Turn the whole plain list into a subtree of
+ the current heading. Checkboxes (see [[Checkboxes]]) will become
+ TODO (resp. DONE) keywords when unchecked (resp. checked).
+
+ #+kindex: C-c C-*
+ - {{{kbd(S-left/right)}}} :: This command also cycles bullet styles
+ when the cursor in on the bullet or anywhere in an item line,
+ details depending on ~org-support-shift-select~.
+
+ #+vindex: org-support-shift-select
+ #+kindex: S-left
+ #+kindex: S-right
+ - {{{kbd(C-c ^)}}} :: Sort the plain list. You will be prompted for
+ the sorting method: numerically, alphabetically, by time, or by
+ custom function.
+
+ #+kindex: C-c ^
+
+** Drawers
+ :PROPERTIES:
+ :DESCRIPTION: Tucking stuff away
+ :END:
+#+cindex: drawers
+#+cindex: #+DRAWERS
+#+cindex: visibility cycling, drawers
+
+#+vindex: org-drawers
+#+cindex: org-insert-drawer
+#+kindex: C-c C-x d
+Sometimes you want to keep information associated with an entry, but you
+normally don't want to see it. For this, Org mode has /drawers/.
+Drawers need to be configured with the variable
+~org-drawers~.[fn:172] Drawers
+look like this:
+
+#+begin_src org
+ ,** This is a headline
+ Still outside the drawer
+ :DRAWERNAME:
+ This is inside the drawer.
+ :END:
+ After the drawer.
+#+end_src
+
+
+You can interactively insert drawers at point by calling
+~org-insert-drawer~, which is bound to {{{kbd(C-c C-x d)}}}.
+With an active region, this command will put the region inside the
+drawer. With a prefix argument, this command calls
+~org-insert-property-drawer~ and add a property drawer right
+below the current headline. Completion over drawer keywords is also
+possible using {{{key(M-TAB)}}}.
+
+Visibility cycling (see [[Visibility cycling]]) on the headline
+will hide and show the entry, but keep the drawer collapsed to a
+single line. In order to look inside the drawer, you need to move the
+cursor to the drawer line and press {{{key(TAB)}}} there. Org mode
+uses the ~PROPERTIES~ drawer for storing properties
+(see [[Properties and columns]]), and you can also arrange for
+state change notes (see [[Tracking TODO state changes]) and
+clock times (see [[Clocking work time]) to be stored in a drawer
+~LOGBOOK~. If you want to store a quick note in the LOGBOOK
+drawer, in a similar way to state changes, use
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c C-z)}}} :: Add a time-stamped note to the LOGBOOK
+ drawer.
+
+ #+kindex: C-c C-z
+
+** Blocks
+ :PROPERTIES:
+ :DESCRIPTION: Folding blocks
+ :END:
+#+vindex: org-hide-block-startup
+#+cindex: blocks, folding
+
+Org mode uses ~begin~ ... ~end~ blocks for various purposes from including
+source code examples (see [[Literal examples]]) to capturing time logging
+information (see [[Clocking work time]]). These blocks can be folded
+and unfolded by pressing TAB in the begin line. You can also get all
+blocks folded at startup by configuring the variable
+~org-hide-block-startup~ or on a per-file basis by using
+
+#+cindex: @code{hideblocks}, STARTUP keyword
+#+cindex: @code{nohideblocks}, STARTUP keyword
+#+begin_src org
+ ,#+STARTUP: hideblocks
+ ,#+STARTUP: nohideblocks
+#+end_src
+
+** Creating footnotes
+ :PROPERTIES:
+ :DESCRIPTION: Define footnotes in Org syntax
+ :END:
+#+cindex: footnotes
+
+Org mode supports the creation of footnotes. In contrast to the
+{{{file(footnote.el)}}} package, Org mode's footnotes are designed for
+work on a larger document, not only for one-off documents like emails.
+The basic syntax is similar to the one used by
+{{{file(footnote.el)}}}, i.e., a footnote is defined in a paragraph
+that is started by a footnote marker in square brackets in column 0,
+no indentation allowed. If you need a paragraph break inside a
+footnote, use the LaTeX idiom ~\par~. The footnote reference is simply
+the marker in square brackets, inside text. For example:
+
+#+begin_example
+ The Org homepage[fn:1] now looks a lot better than it used to.
+ ...
+ [fn:1] The link is: http://orgmode.org
+#+end_example
+
+Org mode extends the number-based syntax to /named/ footnotes and
+optional inline definition. Using plain numbers as markers (as
+{{{file(footnote.el)}}} does) is supported for backward compatibility,
+but not encouraged because of possible conflicts with LaTeX
+snippets (see [[Embedded LaTeX]]). Here are
+the valid references:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - ~[1]~ :: A plain numeric footnote marker. Compatible with
+ {{{file(footnote.el)}}}, but not recommended because
+ something like ~[1]~ could easily be part of a
+ code snippet.
+
+ - ~[fn:name]~ :: A named footnote reference, where ~name~ is
+ a unique label word, or, for simplicity of automatic
+ creation, a number.
+ - ~[fn:: This is the inline definition of this footnote]~ :: A
+ LaTeX-like anonymous footnote where the definition
+ is given directly at the reference point.
+ - ~[fn:name: a definition]~ :: An inline definition of a footnote,
+ which also specifies a name for the note. Since Org allows
+ multiple references to the same note, you can then use
+ ~[fn:name]~ to create additional references.
+
+
+#+vindex: org-footnote-auto-label
+Footnote labels can be created automatically, or you can create names
+yourself. This is handled by the variable
+~org-footnote-auto-label~ and its corresponding
+~#+STARTUP~ keywords. See the docstring of that variable for
+details.
+
+{{{noindent}}} The following command handles footnotes:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c C-x f)}}} :: The footnote action command.
+ #+kindex: C-c C-x f
+
+ When the cursor is on a footnote reference, jump to the
+ definition. When it is at a definition, jump to the
+ (first) reference.
+
+ #+vindex: org-footnote-define-inline
+ #+vindex: org-footnote-section
+ #+vindex: org-footnote-auto-adjust
+
+ Otherwise, create a new footnote. Depending on the
+ variable ~org-footnote-define-inline~, the
+ definition will be placed right into the text as part
+ of the reference, or separately into the location
+ determined by the variable ~org-footnote-section~.[fn:173]
+
+ When this command is called with a prefix argument, a
+ menu of additional options is offered:
+
+ - {{{kbd(s)}}} :: Sort the footnote definitions by reference sequence.
+ During editing, Org makes no effort to sort footnote
+ definitions into a particular sequence. If you want them
+ sorted, use this command, which will also move entries
+ according to ~org-footnote-section~. Automatic sorting
+ after each insertion/deletion can be configured using the
+ variable ~org-footnote-auto-adjust~.
+ - {{{kbd(r)}}} :: Renumber the simple ~fn:N~ footnotes. Automatic
+ renumbering after each insertion/deletion can be
+ configured using the variable ~org-footnote-auto-adjust~.
+ - {{{kbd(S)}}} :: Short for first ~r~, then ~s~ action.
+ - {{{kbd(n)}}} :: Normalize the footnotes by collecting all definitions
+ (including inline definitions) into a special section, and
+ then numbering them in sequence. The references will then
+ also be numbers. This is meant to be the final step
+ before finishing a document (e.g., sending off an email).
+ The exporters do this automatically, and so could
+ something like ~message-send-hook~.
+ - {{{kbd(d)}}} :: Delete the footnote at point, and all definitions of and
+ references to it.
+
+ Depending on the variable ~org-footnote-auto-adjust~, renumbering
+ and sorting footnotes can be automatic after each insertion or
+ deletion.[fn:174]
+
+ - {{{kbd(C-c C-c)}}} :: If the cursor is on a footnote reference, jump to the
+ definition. If it is a the definition, jump back to
+ the reference. When called at a footnote location with
+ a prefix argument, offer the same menu as {{{kbd(C-c C-x f)}}}.
+
+ #+kindex: C-c C-c
+
+ - {{{kbd(C-c C-o)}}} or {{{kbd(mouse-1/2)}}} :: Footnote labels are also
+ links to the corresponding definition/reference, and you can
+ use the usual commands to follow these links.
+
+ #+kindex: C-c C-o
+ #+kindex: mouse-1
+ #+kindex: mouse-2
+
+** Orgstruct mode
+ :PROPERTIES:
+ :DESCRIPTION: Structure editing outside Org
+ :ALT_TITLE: Orgstruct mode
+ :END:
+#+cindex: Orgstruct mode
+#+cindex: minor mode for structure editing
+
+If you like the intuitive way the Org mode structure editing and list
+formatting works, you might want to use these commands in other modes
+like Text mode or Mail mode as well. The minor mode ~orgstruct-mode~
+makes this possible. Toggle the mode with {{{kbd(M-x orgstruct-mode)}}}, or turn it on by default, for example in Message
+mode, with one of:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ (add-hook 'message-mode-hook 'turn-on-orgstruct)
+ (add-hook 'message-mode-hook 'turn-on-orgstruct++)
+#+end_src
+
+When this mode is active and the cursor is on a line that looks to Org
+like a headline or the first line of a list item, most structure
+editing commands will work, even if the same keys normally have
+different functionality in the major mode you are using. If the
+cursor is not in one of those special lines, Orgstruct mode lurks
+silently in the shadows. When you use ~orgstruct++-mode~, Org will
+also export indentation and autofill settings into that mode, and
+detect item context after the first line of an item.
+
+* Tables
+ :PROPERTIES:
+ :DESCRIPTION: Pure magic for quick formatting
+ :END:
+#+cindex: tables
+#+cindex: editing tables
+
+Org comes with a fast and intuitive table editor. Spreadsheet-like
+calculations are supported using the Emacs {{{file(calc)}}} package
+([[info:calc]]).
+
+** Built-in table editor
+ :PROPERTIES:
+ :DESCRIPTION: Simple tables
+ :END:
+#+cindex: table editor, built-in
+
+Org makes it easy to format tables in plain ASCII. Any line with
+{{{samp(|)}}} as the first non-whitespace character is considered part
+of a table. {{{samp(|)}}} is also the column separator.[fn:22] A table
+might look like this:
+
+#+begin_src org
+ | Name | Phone | Age |
+ |-------+-------+-----|
+ | Peter | 1234 | 17 |
+ | Anna | 4321 | 25 |
+#+end_src
+
+
+A table is re-aligned automatically each time you press {{{key(TAB)}}}
+or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} inside the table.
+{{{key(TAB)}}} also moves to the next field ({{{key(RET)}}} to the
+next row) and creates new table rows at the end of the table or before
+horizontal lines. The indentation of the table is set by the first
+line. Any line starting with {{{samp(|-)}}} is considered as a
+horizontal separator line and will be expanded on the next re-align to
+span the whole table width. So, to create the above table, you would
+only type
+
+#+begin_src org
+ |Name|Phone|Age|
+ |-
+#+end_src
+
+
+{{{noindent}}} and then press {{{key(TAB)}}} to align the table and
+start filling in fields. Even faster would be to type
+~|Name|Phone|Age~ followed by {{{kbdspckey(C-c,RET)}}}.
+
+#+vindex: org-enable-table-editor
+#+vindex: org-table-auto-blank-field
+
+When typing text into a field, Org treats {{{key(DEL)}}},
+{{{key(Backspace)}}}, and all character keys in a special way, so that
+inserting and deleting avoids shifting other fields. Also, when
+typing /immediately/ after the cursor was moved into a new field with
+{{{key(TAB)}}}, {{{kbdkey(S-,TAB)}}} or {{{key(RET)}}}, the field is
+automatically made blank. If this behavior is too unpredictable for
+you, configure the variables ~org-enable-table-editor~ and
+~org-table-auto-blank-field~.
+*** Creation and conversion
+ :PROPERTIES:
+ :DESCRIPTION: Creating tabular data in Org
+ :END:
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c |)}}}, ~org-table-create-or-convert-from-region~ :: Convert
+ the active region to table. If every line contains at least one
+ {{{key(TAB)}}} character, the function assumes that the material
+ is tab separated. If every line contains a comma, comma-separated
+ values (CSV) are assumed. If not, lines are split at whitespace
+ into fields. You can use a prefix argument to force a specific
+ separator: {{{kbd(C-u)}}} forces CSV, {{{kbd(C-u C-u)}}} forces
+ {{{key(TAB)}}}, and a numeric argument ~N~ indicates that at
+ least N consecutive spaces, or alternatively a {{{key(TAB)}}}
+ will be the separator. If there is no active region, this command
+ creates an empty Org table. But it is easier just to start
+ typing, like {{{kbdspckey(|Name|Phone|Age,RET)}}} {{{kbdkey(|-
+ ,TAB)}}}.
+
+ #+kindex: C-c |
+ #+findex: org-table-create-or-convert-from-region
+
+*** Re-aligning and field motion
+ :PROPERTIES:
+ :DESCRIPTION: Navigating and tidying
+ :END:
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-c)}}}, ~org-table-align~ :: Re-align the table without
+ moving the cursor.
+
+ #+kindex: C-c C-c
+ #+findex: org-table-align
+- {{{kbd(<TAB>)}}}, ~org-table-next-field~ :: Re-align the table, move
+ to the next field. Creates a new row if necessary.
+
+ #+kindex: <TAB>
+ #+findex: org-table-next-field
+- {{{kbdkey(S-,TAB)}}}, ~org-table-previous-field~ :: Re-align, move to
+ previous field.
+
+ #+kindex: S-TAB
+ #+findex: org-table-previous-field
+- {{{key(RET)}}}, ~org-table-next-row~ :: Re-align the table and move
+ down to next row. Creates a new row if necessary. At the
+ beginning or end of a line, {{{key(RET)}}} still does NEWLINE, so
+ it can be used to split a table.
+
+ #+kindex: RET
+ #+findex: org-table-next-row
+- {{{kbd(M-a)}}}, ~org-table-beginning-of-field~ :: Move to beginning
+ of the current table field, or on to the previous field.
+
+ #+kindex: M-a
+ #+findex: org-table-beginning-of-field
+- {{{kbd(M-e)}}}, ~org-table-end-of-field~ :: Move to end of the
+ current table field, or on to the next field.
+
+ #+kindex: M-e
+ #+findex: org-table-end-of-field
+
+*** Column and row editing
+ :PROPERTIES:
+ :DESCRIPTION: Insert, kill, or move
+ :END:
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbdkey(M-,left)}}}, ~org-table-move-column-left~ ::
+ #+kindex: M-left
+ #+findex: org-table-move-column-left
+
+ Move the current column left.
+
+- {{{kbdkey(M-,right)}}}, ~org-table-move-column-right~ ::
+ #+kindex: M-right
+ #+findex: org-table-move-column-right
+
+ Move the current column right.
+
+- {{{kbdkey(M-S-,left)}}}, ~org-table-delete-column~ ::
+ #+kindex: M-S-left
+ #+findex: org-table-delete-column
+
+ Kill the current column.
+
+- {{{kbdkey(M-S-,right)}}}, ~org-table-insert-column~ ::
+ #+kindex: M-S-right
+ #+findex: org-table-insert-column
+
+ Insert a new column to the left of the cursor position.
+
+- {{{kbdkey(M-,up)}}}, ~org-table-move-row-up~ ::
+ #+kindex: M-up
+ #+findex: org-table-move-row-up
+
+ Move the current row up.
+
+- {{{kbdkey(M-,down)}}}, ~org-table-move-row-down~ ::
+ #+kindex: M-down
+ #+findex: org-table-move-row-down
+
+ Move the current row down.
+
+- {{{kbdkey(M-S-,up)}}}, ~org-table-kill-row~ :: Kill the current row
+ or horizontal line.
+
+ #+kindex: M-S-up
+ #+findex: org-table-kill-row
+
+- {{{kbdkey(M-S-,down)}}}, ~org-table-insert-row~ :: Insert a new row
+ above the current row. With a prefix argument, the line is
+ created below the current one.
+
+ #+kindex: M-S-down
+ #+findex: org-table-insert-row
+
+- {{{kbd(C-c -)}}}, ~org-table-insert-hline~ :: Insert a horizontal
+ line below current row. With a prefix argument, the line is
+ created above the current line.
+
+ #+kindex: C-c -
+ #+findex: org-table-insert-hline
+
+- {{{kbdspckey(C-c,RET)}}}, ~org-table-hline-and-move~ :: Insert a
+ horizontal line below current row, and move the cursor into the
+ row below that line.
+
+ #+kindex: C-c RET
+ #+findex: org-table-hline-and-move
+
+- {{{kbd(C-c ^)}}}, ~org-table-sort-lines~ :: Sort the table lines in
+ the region. The position of point indicates the column to be
+ used for sorting, and the range of lines is the range between the
+ nearest horizontal separator lines, or the entire table. If
+ point is before the first column, you will be prompted for the
+ sorting column. If there is an active region, the mark specifies
+ the first line and the sorting column, while point should be in
+ the last line to be included into the sorting. The command
+ prompts for the sorting type (alphabetically, numerically, or by
+ time). When called with a prefix argument, alphabetic sorting
+ will be case-sensitive.
+
+ #+kindex: C-c ^
+ #+findex: org-table-sort-lines
+*** Regions
+ :PROPERTIES:
+ :DESCRIPTION: Manipulate parts of a table
+ :END:
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x M-w)}}}, ~org-table-copy-region~ :: Copy a rectangular
+ region from a table to a special clipboard. Point and mark
+ determine edge fields of the rectangle. If there is no active
+ region, copy just the current field. The process ignores
+ horizontal separator lines.
+
+ #+kindex: C-c C-x M-w
+ #+findex: org-table-copy-region
+- {{{kbd(C-c C-x C-w)}}}, ~org-table-cut-region~ :: Copy a rectangular
+ region from a table to a special clipboard, and blank all fields
+ in the rectangle. So this is the ``cut'' operation.
+
+ #+kindex: C-c C-x C-w
+ #+findex: org-table-cut-region
+- {{{kbd(C-c C-x C-y)}}}, ~org-table-paste-rectangle~ :: Paste a
+ rectangular region into a table. The upper left corner ends up
+ in the current field. All involved fields will be overwritten.
+ If the rectangle does not fit into the present table, the table
+ is enlarged as needed. The process ignores horizontal separator
+ lines.
+
+ #+kindex: C-c C-x C-y
+ #+findex: org-table-paste-rectangle
+- {{{kbdkey(M-,RET)}}}, ~org-table-wrap-region~ :: Split the current
+ field at the cursor position and move the rest to the line below.
+ If there is an active region, and both point and mark are in the
+ same column, the text in the column is wrapped to minimum width
+ for the given number of lines. A numeric prefix argument may be
+ used to change the number of desired lines. If there is no
+ region, but you specify a prefix argument, the current field is
+ made blank, and the content is appended to the field above.
+
+ #+kindex: M-RET
+ #+findex: org-table-wrap-region
+*** Calculations
+ :PROPERTIES:
+ :DESCRIPTION: Sum and copy
+ :END:
+#+cindex: formula, in tables
+#+cindex: calculations, in tables
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient mark mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c +)}}}, ~org-table-sum~ :: Sum the numbers in the current
+ column, or in the rectangle defined by the active region. The
+ result is shown in the echo area and can be inserted with
+ {{{kbd(C-y)}}}.
+
+ #+kindex: C-c +
+ #+findex: org-table-sum
+- {{{kbdkey(S-,RET)}}}, ~org-table-copy-down~ :: When current field is
+ empty, copy from first non-empty field above. When not empty,
+ copy current field down to next row and move cursor along with
+ it. Depending on the variable ~org-table-copy-increment~,
+ integer field values will be incremented during copy. Integers
+ that are too large will not be incremented. Also, a ~0~ prefix
+ argument temporarily disables the increment. This key is also
+ used by shift-selection and related modes (see [[Conflicts]]).
+
+ #+kindex: S-RET
+ #+findex: org-table-copy-down
+ #+vindex: org-table-copy-increment
+
+*** Misc
+ :PROPERTIES:
+ :DESCRIPTION: Some other useful operations
+ :END:
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c `)}}}, ~org-table-edit-field~ :: Edit the current field in
+ a separate window. This is useful for fields that are not fully
+ visible (see [[Column width and alignment]]). When called with a
+ {{{kbd(C-u)}}} prefix, just make the full field visible, so that
+ it can be edited in place. When called with two {{{kbd(C-u)}}}
+ prefixes, make the editor window follow the cursor through the
+ table and always show the current field. The follow mode exits
+ automatically when the cursor leaves the table, or when you
+ repeat this command with {{{kbd(C-u C-u C-c `)}}}.
+
+ #+kindex: C-c `
+ #+findex: org-table-edit-field
+- {{{kbd(M-x org-table-import)}}} :: Import a file as a table. The
+ table should be TAB or whitespace separated. Use, for example,
+ to import a spreadsheet table or data from a database, because
+ these programs generally can write TAB-separated text files.
+ This command works by inserting the file into the buffer and then
+ converting the region to a table. Any prefix argument is passed
+ on to the converter, which uses it to determine the separator.
+
+- {{{kbd(C-c |)}}}, ~org-table-create-or-convert-from-region~ :: Tables
+ can also be imported by pasting tabular text into the Org buffer,
+ selecting the pasted text with {{{kbd(C-x C-x)}}} and then using
+ the {{{kbd(C-c |)}}} command (see [[Creation and conversion]]).
+
+ #+kindex: C-c |
+ #+findex: org-table-create-or-convert-from-region
+- {{{kbd(M-x org-table-export)}}} :: Export the table, by default as a
+ TAB-separated file. Use for data exchange with, for example,
+ spreadsheet or database programs. The format used to export the
+ file can be configured in the variable
+ ~org-table-export-default-format~. You may also use properties
+ ~TABLE_EXPORT_FILE~ and ~TABLE_EXPORT_FORMAT~ to specify the file
+ name and the format for table export in a subtree. Org supports
+ quite general formats for exported tables. The exporter format
+ is the same as the format used by Orgtbl radio tables, see
+ [[Translator functions], for a detailed description.
+
+ #+findex: org-table-export
+ #+vindex: org-table-export-default-format
+
+If you don't like the automatic table editor because it gets in your
+way on lines which you would like to start with {{{samp(|)}}}, you can
+turn it off with
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-enable-table-editor nil)
+#+end_src
+
+
+{{{noindent}}} Then the only table command that still works is
+{{{kbd(C-c C-c)}}} to do a manual re-align.
+
+** Column width and alignment
+ :PROPERTIES:
+ :DESCRIPTION: Overrule the automatic settings
+ :END:
+#+cindex: narrow columns in tables
+#+cindex: alignment in tables
+
+The width of columns is automatically determined by the table editor.
+And also the alignment of a column is determined automatically from
+the fraction of number-like versus non-number fields in the column.
+
+Sometimes a single field or a few fields need to carry more text,
+leading to inconveniently wide columns. Or maybe you want to make a
+table with several columns having a fixed width, regardless of
+content. To set the width of a column, one field anywhere in the
+column may contain just the string ~<N>~ where ~N~
+is an integer specifying the width of the column in characters.[fn:23]
+The next re-align will then set the width of this column to this
+value.
+
+#+begin_example
+ |---+------------------------------| |---+--------|
+ | | | | | <6> |
+ | 1 | one | | 1 | one |
+ | 2 | two | ----\ | 2 | two |
+ | 3 | This is a long chunk of text | ----/ | 3 | This=> |
+ | 4 | four | | 4 | four |
+ |---+------------------------------| |---+--------|
+#+end_example
+
+{{{noindent}}} Fields that are wider become clipped and end in the
+string {{{samp(=>)}}}. Note that the full text is still in the buffer
+but is hidden. To see the full text, hold the mouse over the
+field---a tool-tip window will show the full content. To edit such a
+field, use the command {{{kbd(C-c `)}}} (that is {{{kbd(C-c)}}}
+followed by the backquote). This will open a new window with the full
+field. Edit it and finish with {{{kbd(C-c C-c)}}}.
+
+#+vindex: org-startup-align-all-tables
+
+When visiting a file containing a table with narrowed columns, the
+necessary character hiding has not yet happened, and the table needs
+to be aligned before it looks nice. Setting the option
+~org-startup-align-all-tables~ will realign all tables in a file upon
+visiting, but also slow down startup. You can also set this option on
+a per-file basis with:
+
+#+begin_src org
+ ,#+STARTUP: align
+ ,#+STARTUP: noalign
+#+end_src
+
+If you would like to overrule the automatic alignment of number-rich
+columns to the right and of string-rich columns to the left, you can
+use ~<r>~, ~<c>~ or ~<l>~ in a similar fashion.[fn:24] You may also
+combine alignment and field width like this: ~<l10>~.
+
+A line that only contains these formatting cookies will be removed
+automatically when exporting the document.
+
+** Column groups
+ :PROPERTIES:
+ :DESCRIPTION: Grouping to trigger vertical lines
+ :END:
+#+cindex: grouping columns in tables
+
+When Org exports tables, it does so by default without vertical lines
+because that is visually more satisfying in general. Occasionally
+however, vertical lines can be useful to structure a table into groups
+of columns, much like horizontal lines can do for groups of rows. In
+order to specify column groups, you can use a special row where the
+first field contains only {{{samp(/)}}}. The further fields can either
+contain ~<~ to indicate that this column should start a group,
+~>~ to indicate the end of a column, or ~<>~ (no space
+between ~<~ and ~>~) to make a column a group of its own. Boundaries
+between column groups will upon export be marked with vertical lines.
+Here is an example:
+
+#+begin_src org
+ | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
+ |---+-----+-----+-----+---------+------------|
+ | / | < | | > | < | > |
+ | 1 | 1 | 1 | 1 | 1 | 1 |
+ | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
+ | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
+ |---+-----+-----+-----+---------+------------|
+ ,#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
+#+end_src
+
+It is also sufficient to just insert the column group starters after
+every vertical line you would like to have:
+
+#+begin_src org
+ | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
+ |----+-----+-----+-----+---------+------------|
+ | / | < | | | < | |
+#+end_src
+
+** The Orgtbl mode minor mode
+ :PROPERTIES:
+ :DESCRIPTION: The table editor as minor mode
+ :ALT_TITLE: Ogtbl mode
+ :END:
+#+cindex: Orgtbl mode
+#+cindex: minor mode for tables
+
+If you like the intuitive way the Org table editor works, you might
+also want to use it in other modes like Text mode or Mail mode. The
+minor mode Orgtbl mode makes this possible. You can always toggle the
+mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for
+example in Message mode, use
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(add-hook 'message-mode-hook 'turn-on-orgtbl)
+#+end_src
+
+Furthermore, with some special setup, it is possible to maintain
+tables in arbitrary syntax with Orgtbl mode. For example, it is
+possible to construct LaTeX tables with the underlying ease and
+power of Orgtbl mode, including spreadsheet capabilities. For
+details, see [[Tables in arbitrary syntax]].
+
+** The spreadsheet
+ :PROPERTIES:
+ :DESCRIPTION: The table editor has spreadsheet capabilities
+ :END:
+#+cindex: calculations, in tables
+#+cindex: spreadsheet capabilities
+#+cindex: @file{calc} package
+
+The table editor makes use of the Emacs {{{file(calc)}}} package to
+implement spreadsheet-like capabilities. It can also evaluate Emacs
+Lisp forms to derive fields from other fields. While fully featured,
+Org's implementation is not identical to other spreadsheets. For
+example, Org knows the concept of a /column formula/ that will be
+applied to all non-header fields in a column without having to copy
+the formula to each relevant field. There is also a formula debugger,
+and a formula editor with features for highlighting fields in the
+table corresponding to the references at the point in the formula,
+moving these references by arrow keys
+
+*** References
+ :PROPERTIES:
+ :DESCRIPTION: How to refer to another field or range
+ :END:
+#+cindex: references
+
+To compute fields in the table from other fields, formulas must
+reference other fields or ranges. In Org, fields can be referenced by
+name, by absolute coordinates, and by relative coordinates. To find
+out what the coordinates of a field are, press {{{kbd(C-c ?)}}} in
+that field, or press {{{kbd(C-c })}}} to toggle the display of a
+grid.
+
+**** Field references
+ :PROPERTIES:
+ :DESCRIPTION: Refer to a particular field
+ :END:
+#+cindex: field references
+#+cindex: references, to fields
+
+Formulas can reference the value of another field in two ways. Like
+in any other spreadsheet, you may reference fields with a
+letter/number combination like ~B3~, meaning the 2nd field in the 3rd
+row.
+
+#+vindex: org-table-use-standard-references
+However, Org prefers to use another, more general representation that
+looks like this:[fn:25]
+
+#+begin_example
+ @ROW$COLUMN
+#+end_example
+
+Column specifications can be absolute like ~$1~, ~$2~, ..., ~$N~, or
+relative to the current column (i.e., the column of the field which is
+being computed) like ~$+1~ or ~$-2~. ~$<~ and ~$>~ are immutable
+references to the first and last column, respectively, and you can use
+~$>>>~ to indicate the third column from the right.
+
+The row specification only counts data lines and ignores horizontal
+separator lines (hlines). Like with columns, you can use absolute row
+numbers ~@1~, ~@2~, ..., ~@N~, and row numbers relative to the current
+row like ~@+3~ or ~@-1~. ~@<~ and ~@>~ are immutable references the
+first and last row in the table, respectively.[fn:26] You may also
+specify the row relative to one of the hlines: ~@I~ refers to the
+first hline, ~@II~ to the second, etc. ~@-I~ refers to the first such
+line above the current line, ~@+I~ to the first such line below the
+current line. You can also write ~@III+2~ which is the second data
+line after the third hline in the table.
+
+~@0~ and ~$0~ refer to the current row and column, respectively, i.e.,
+to the row/column for the field being computed. Also, if you omit
+either the column or the row part of the reference, the current
+row/column is implied.
+
+Org's references with /unsigned/ numbers are fixed references in the
+sense that if you use the same reference in the formula for two
+different fields, the same field will be referenced each time. Org's
+references with /signed/ numbers are floating references because the
+same reference operator can reference different fields depending on
+the field being calculated by the formula.
+
+Here are a few examples:
+
+#+attr_texinfo: :table-type table :indic @code
+ - @2$3 :: 2nd row, 3rd column (same as ~C2~)
+ - $5 :: column 5 in the current row (same as ~E&~)
+ - @2 :: current column, row 2
+ - @-1$-3 :: the field one row up, three columns to the left
+ - @-I$2 :: field just under hline above current row, column 2
+ - @>$5 :: field in the last row, in column 5
+
+**** Range references
+ :PROPERTIES:
+ :DESCRIPTION: Refer to a range of fields
+ :END:
+#+cindex: range references
+#+cindex: references, to ranges
+
+You may reference a rectangular range of fields by specifying two
+field references connected by two dots ~..~. If both fields are in
+the current row, you may simply use ~$2..$7~, but if at least one
+field is in a different row, you need to use the general ~@row$column~
+format at least for the first field (i.e., the reference must start
+with ~@~ in order to be interpreted correctly). Examples:
+
+#+attr_texinfo: :table-type table :indic @code
+ - $1..$3 :: first three fields in the current row
+ - $P..$Q :: range, using column names (see under Advanced)
+ - $<<<..$>> :: start in third column, continue to the one but last
+ - @2$1..@4$3 :: six fields between these two fields (same as
+ ~A2..C4~)
+ - @-1$-2..@-1 :: three numbers from the column to the left, 2 up to
+ current row
+ - @I..II :: between first and second hline, short for ~@I..@II~
+
+
+{{{noindent}}} Range references return a vector of values that can be
+fed into Calc vector functions. Empty fields in ranges are normally
+suppressed, so that the vector contains only the non-empty fields (but
+see the ~E~ mode switch below). If there are no non-empty fields,
+~[0]~ is returned to avoid syntax errors in formulas.
+
+**** Field coordinates in formulas
+ :PROPERTIES:
+ :DESCRIPTION: Refer to fields in Lisp or Calc
+ :END:
+#+cindex: field coordinates
+#+cindex: coordinates, of field
+#+cindex: row, of field coordinates
+#+cindex: column, of field coordinates
+
+For Calc formulas and Lisp formulas ~@#~ and ~$#~ can be used to get
+the row or column number of the field where the formula result goes.
+The traditional Lisp formula equivalents are ~org-table-current-dline~
+and ~org-table-current-column~. Examples:
+
+#+attr_texinfo: :table-type table :indic @code
+ - if(@# % 2, $#, string("")) :: column number on odd lines only
+ - $3 = remote(FOO, @#$2) :: copy column 2 from table FOO into
+ column 3 of the current table
+
+{{{noindent}}} For the second example, table FOO must have at least as
+many rows as the current table. Note that this is inefficient for
+large number of rows.[fn:27]
+
+**** Named references
+ :PROPERTIES:
+ :DESCRIPTION: Name columns or constants
+ :END:
+#+cindex: named references
+#+cindex: references, named
+#+cindex: name, of column or field
+#+cindex: constants, in calculations
+#+cindex: #+CONSTANTS
+#+vindex: org-table-formula-constants
+
+{{{samp($name)}}} is interpreted as the name of a column, parameter or
+constant. Constants are defined globally through the variable
+~org-table-formula-constants~, and locally (for the file) through a
+line like this example:
+
+#+begin_src org
+ ,#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
+#+end_src
+
+{{{noindent}}}
+#+vindex: constants-unit-system
+#+pindex: constants.el
+
+Also, properties (see [[Properties and columns]]) can be used as constants
+in table formulas: for a property ~:Xyz:~ use the name ~$PROP_Xyz~,
+and the property will be searched in the current outline entry and in
+the hierarchy above it. If you have the {{{file(constants.el)}}}
+package, it will also be used to resolve constants, including natural
+constants like ~$h~ for Planck's constant, and units like ~$km~ for
+kilometers. Column names and parameters can be specified in special
+table lines. These are described in the section, [[Advanced features]].
+All names must start with a letter, and further consist of letters and
+numbers.[fn:175]
+
+**** Remote references
+ :PROPERTIES:
+ :DESCRIPTION: Refer to information in other tables
+ :END:
+#+cindex: remote references
+#+cindex: references, remote
+#+cindex: references, to a different table
+#+cindex: name, of column or field
+#+cindex: constants, in calculations
+#+cindex: #+TBLNAME
+
+You may also reference constants, fields and ranges from a different
+table, either in the current file or even in a different file. The
+syntax is
+
+#+begin_example
+ remote(NAME-OR-ID,REF)
+#+end_example
+
+{{{noindent}}} where NAME can be the name of a table in the current
+file as set by a ~#+TBLNAME: NAME~ line before the table. It can also
+be the ID of an entry, even in a different file, and the reference
+then refers to the first table in that entry. REF is an absolute field
+or range reference as described above for example ~@3$3~ or
+~$somename~, valid in the referenced table.
+
+*** Formula syntax for Calc
+ :PROPERTIES:
+ :DESCRIPTION: Using Calc to compute stuff
+ :END:
+#+cindex: formula syntax, Calc
+#+cindex: syntax, of formulas
+
+A formula can be any algebraic expression understood by the Emacs
+{{{file(Calc)}}} package.[fn:28] Before evaluation by ~calc-eval~ (see
+[[info:calc#Calling Calc from Your Programs][Calling Calc from Your Lisp Programs]]), variable substitution takes
+place according to the rules described above.
+
+#+cindex: vectors, in table calculations
+The range vectors can be directly fed into the Calc vector functions
+like ~vmean~ and ~vsum~.
+
+#+cindex: format specifier
+#+cindex: mode, for @file{calc}
+#+vindex: org-calc-default-modes
+
+A formula can contain an optional mode string after a semicolon. This
+string consists of flags to influence Calc and other modes during
+execution. By default, Org uses the standard Calc modes (precision
+12, angular units degrees, fraction and symbolic modes off). The
+display format, however, has been changed to ~(float 8)~ to keep
+tables compact. The default settings can be configured using the
+variable ~org-calc-default-modes~.
+
+#+attr_texinfo: :table-type table :indic @code
+ - p20 :: set the internal Calc calculation precision to 20 digits
+ - n3 s3 e2 f4 :: normal, scientific, engineering, or fixed format of
+ the result of Calc passed back to Org. Calc
+ formatting is unlimited in precision as long as the
+ Calc calculation precision is greater.
+ - D R :: angle modes: degrees, radians
+ - F S :: fraction and symbolic modes
+ - N :: interpret all fields as numbers, use 0 for non-numbers
+ - E :: keep empty fields in ranges
+ - L :: literal
+
+{{{noindent}}} Unless you use large integer numbers or
+high-precision-calculation and -display for floating point numbers you
+may alternatively provide a ~printf~ format specifier to reformat the
+Calc result after it has been passed back to Org instead of letting
+Calc already do the formatting.[fn:29] A few examples:
+
+#+attr_texinfo: :table-type table :indic @code
+ - $1+$2 :: Sum of first and second field
+ - $1+$2;%.2f :: Same, format result to two decimals
+ - exp($2)+exp($1) :: Math functions can be used
+ - $0;%.1f :: Reformat current cell to 1 decimal
+ - ($3-32)*5/9 :: Degrees F -> C conversion
+ - $c/$1/$cm :: Hz -> cm conversion, using
+ {{{file(constants.el)}}}
+ - tan($1);Dp3s1 :: Compute in degrees, precision 3, display SCI 1
+ - sin($1);Dp3%.1e :: Same, but use ~printf~ specifier for display
+ - vmean($2..$7) :: Compute column range mean, using vector
+ function
+ - vmean($2..$7);EN :: Same, but treat empty fields as 0
+ - taylor($3,x=7,2) :: Taylor series of $3, at x=7, second degree
+
+Calc also contains a complete set of logical operations. For example
+
+#+attr_texinfo: :table-type table :indic @code
+ - if($1<20,teen,string("")) :: "teen" if age $1 less than 20, else empty
+
+
+Note that you can also use two org-specific flags ~T~ and ~t~ for
+durations computations [[Duration and time values]].
+
+You can add your own Calc functions defined in Emacs Lisp with
+~defmath~ and use them in formula syntax for Calc.
+
+*** Emacs Lisp forms as formulas
+ :PROPERTIES:
+ :DESCRIPTION: Writing formulas in Emacs Lisp
+ :ALT_TITLE: Formula syntax for Lisp
+ :END:
+#+cindex: Lisp forms, as table formulas
+
+It is also possible to write a formula in Emacs Lisp. This can be
+useful for string manipulation and control structures, if Calc's
+functionality is not enough.
+
+If a formula starts with a single-quote followed by an opening
+parenthesis, then it is evaluated as a Lisp form. The evaluation
+should return either a string or a number. Just as with
+{{{file(calc)}}} formulas, you can specify modes and a printf format
+after a semicolon.
+
+With Emacs Lisp forms, you need to be conscious about the way field
+references are interpolated into the form. By default, a reference
+will be interpolated as a Lisp string (in double-quotes) containing
+the field. If you provide the {{{samp(N)}}} mode switch, all
+referenced elements will be numbers (non-number fields will be zero)
+and interpolated as Lisp numbers, without quotes. If you provide the
+{{{samp(L)}}} flag, all fields will be interpolated literally, without
+quotes. I.e., if you want a reference to be interpreted as a string by
+the Lisp form, enclose the reference operator itself in double-quotes,
+like ~"$3"~. Ranges are inserted as space-separated fields, so you can
+embed them in list or vector syntax.
+
+Here are a few examples---note how the {{{samp(N)}}} mode is used when
+we do computations in Lisp.
+
+Swap the first two characters of the content of column 1:
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
+#+end_src
+
+Add columns 1 and 2, equivalent to Calc's ~$1+$2~:
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ '(+ $1 $2);N
+#+end_src
+
+Compute the sum of columns 1-4, like Calc's ~vsum($1..$4)~}:
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ '(apply '+ '($1..$4));N
+#+end_src
+
+*** Duration and time values
+ :PROPERTIES:
+ :DESCRIPTION: How to compute duration and time values
+ :END:
+#+cindex: Duration, computing
+#+cindex: Time, computing
+#+vindex: org-table-duration-custom-format
+
+If you want to compute time values use the ~T~ flag, either in Calc
+formulas or Elisp formulas:
+
+#+begin_example
+ | Task 1 | Task 2 | Total |
+ |---------+----------+----------|
+ | 2:12 | 1:47 | 03:59:00 |
+ | 3:02:20 | -2:07:00 | 0.92 |
+ #+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;t
+#+end_example
+
+Input duration values must be of the form ~[HH:MM[:SS]~, where seconds
+are optional. With the ~T~ flag, computed durations will be displayed
+as ~HH:MM:SS~ (see the first formula above). With the ~t~ flag,
+computed durations will be displayed according to the value of the
+variable ~org-table-duration-custom-format~, which defaults to
+~'hours~ and will display the result as a fraction of hours (see the
+second formula in the example above).
+
+Negative duration values can be manipulated as well, and integers will
+be considered as seconds in addition and subtraction.
+
+*** Field and range formulas
+ :PROPERTIES:
+ :DESCRIPTION: Formulas for specific (ranges of) fields
+ :END:
+#+cindex: field formula
+#+cindex: range formula
+#+cindex: formula, for individual table field
+#+cindex: formula, for range of fields
+
+To assign a formula to a particular field, type it directly into the
+field, preceded by ~:=~, for example ~vsum(@II..III)~. When you press
+{{{key(TAB)}}} or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} with the cursor
+still in the field, the formula will be stored as the formula for this
+field, evaluated, and the current field will be replaced with the
+result.
+
+#+cindex: #+TBLFM
+Formulas are stored in a special line starting with ~#+TBLFM:~
+directly below the table. If you type the equation in the fourth field
+of the third data line in the table, the formula will look like
+~@3$4=$1+$2~. When inserting/deleting/swapping column and rows with
+the appropriate commands, /absolute references/ (but not relative
+ones) in stored formulas are modified in order to still reference the
+same field. To avoid this from happening, in particular in range
+references, anchor ranges at the table borders (using ~@<~, ~@>~,
+~$<~, ~$>~), or at hlines using the ~@I~ notation. Automatic
+adaptation of field references does of course not happen if you edit
+the table structure with normal editing commands---then you must fix
+the equations yourself.
+
+Instead of typing an equation into the field, you may also use the
+following command
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-u C-c =)}}}, ~org-table-eval-formula~ :: Install a new
+ formula for the current field. The command prompts for a
+ formula with default taken from the {{{samp(#+TBLFM:)}}} line,
+ applies it to the current field, and stores it.
+
+ #+kindex: C-u C-c =
+ #+findex: org-table-eval-formula
+The left-hand side of a formula can also be a special expression in
+order to assign the formula to a number of different fields. There is
+no keyboard shortcut to enter such range formulas. To add them, use
+the formula editor (see [[Editing and debugging formulas]]) or edit the
+~#+TBLFM:~ line directly.
+
+#+attr_texinfo: :table-type table :indic @code
+ - $2= :: Column formula, valid for the entire column. This is so
+ common that Org treats these formulas in a special way, see
+ [[Column formulas]].
+ - @3= :: Row formula, applies to all fields in the specified row.
+ ~@@>=~ means the last row.
+ - @1$2..@4$3= :: Range formula, applies to all fields in the given
+ rectangular range. This can also be used to
+ assign a formula to some but not all fields in a
+ row.
+ - $name= :: Named field, see [[Advanced features]].
+
+*** Column formulas
+ :PROPERTIES:
+ :DESCRIPTION: Formulas valid for an entire column
+ :END:
+#+cindex: column formula
+#+cindex: formula, for table column
+
+When you assign a formula to a simple column reference like ~$3=~, the
+same formula will be used in all fields of that column, with the
+following very convenient exceptions:
+
+ - If the table contains horizontal separator hlines with rows above
+ and below, everything before the first such hline is considered
+ part of the table /header/ and will not be modified by column
+ formulas. Therefore a header is mandatory when you use column
+ formulas and want to add hlines to group rows, like for example
+ to separate a total row at the bottom from the summand rows
+ above.
+
+ - Fields that already get a value from a field/range formula will
+ be left alone by column formulas. These conditions make column
+ formulas very easy to use.
+
+To assign a formula to a column, type it directly into any field in
+the column, preceded by an equal sign, like {{{samp(=$1+$2)}}}. When
+you press {{{key(TAB)}}} or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} with
+the cursor still in the field, the formula will be stored as the
+formula for the current column, evaluated and the current field
+replaced with the result. If the field contains only {{{samp(=)}}},
+the previously stored formula for this column is used. For each
+column, Org will only remember the most recently used formula. In the
+{{{samp(#+TBLFM:)}}} line, column formulas will look like
+{{{samp($4=$1+$2)}}}. The left-hand side of a column formula can not
+be the name of column, it must be the numeric column reference or
+~$>~.
+
+Instead of typing an equation into the field, you may also use the
+following command:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c =)}}}, ~org-table-eval-formula~ :: Install a new formula
+ for the current column and replace current field with the
+ result of the formula. The command prompts for a formula, with
+ default taken from the {{{samp(#+TBLFM)}}} line, applies it to
+ the current field and stores it. With a numeric prefix
+ argument(e.g., {{{kbd(C-5 C-c =)}}}) the command will apply it
+ to that many consecutive fields in the current column.
+
+ #+kindex: C-c =
+ #+findex: org-table-eval-formula
+*** Lookup functions
+ :PROPERTIES:
+ :DESCRIPTION: Lookup functions for searching tables
+ :END:
+#+cindex: lookup functions in tables
+#+cindex: table lookup functions
+
+Org has three predefined Emacs Lisp functions for lookups in tables.
+
+#+attr_texinfo: :table-type table :indic @code
+ - (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE) :: Searches
+ for the first element ~S~ in list ~S-LIST~ for which
+
+ #+findex: org-lookup-first
+
+ #+header: :exports code
+ #+header: :eval no
+ #+begin_src emacs-lisp
+ (PREDICATE VAL S)
+ #+end_src
+ is ~t~; returns the value from the corresponding position in
+ list ~R-LIST~. The default ~PREDICATE~ is ~equal~. Note that
+ the parameters ~VAL~ and ~S~ are passed to ~PREDICATE~ in the
+ same order as the correspoding parameters are in the call to
+ ~org-lookup-first~, where ~VAL~ precedes ~S-LIST~. If ~R-LIST~
+ is ~nil~, the matching element ~S~ of ~S-LIST~ is returned.
+ - (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE) :: Similar
+ to ~org-lookup-first~ above, but searches for the /last/
+ element for which ~PREDICATE~ is ~t~.
+
+ #+findex: org-lookup-last
+ - (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE) :: Similar
+ to ~org-lookup-first~, but searches for /all/ elements for
+ which ~PREDICATE~ is ~t~, and returns /all/ corresponding
+ values. This function can not be used by itself in a formula,
+ because it returns a list of values. However, powerful lookups
+ can be built when this function is combined with other Emacs
+ Lisp functions.
+
+ #+findex: org-lookup-all
+
+If the ranges used in these functions contain empty fields, the ~E~
+mode for the formula should usually be specified: otherwise empty
+fields will not be included in ~S-LIST~ and/or ~R-LIST~ which can, for
+example, result in an incorrect mapping from an element of ~S-LIST~ to
+the corresponding element of ~R-LIST~.
+
+These three functions can be used to implement associative arrays,
+count matching cells, rank results, group data, etc. For practical
+examples see [[http://orgmode.org/worg/org-tutorials/org-lookups.html][this tutorial on Worg]].
+
+*** Editing and debugging formulas
+ :PROPERTIES:
+ :DESCRIPTION: Fixing formulas
+ :END:
+#+cindex: formula editing
+#+cindex: editing, of table formulas
+
+#+vindex: org-table-use-standard-references You can edit
+individual formulas in the minibuffer or directly in the field. Org
+can also prepare a special buffer with all active formulas of a table.
+When offering a formula for editing, Org converts references to the
+standard format (like ~B3~ or ~D&~) if possible. If you prefer to
+only work with the internal format (like ~@3$2~ or ~$4~), configure
+the variable ~org-table-use-standard-references~.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c =)}}} or {{{kbd(C-u C-c =)}}}, ~org-table-eval-formula~ ::
+
+ Edit the formula associated with the current column/field in the
+ minibuffer. See [[Column formulas]], and [[Field and range formulas]].
+
+ #+kindex: C-c =
+ #+kindex: C-u C-c =
+ #+findex: org-table-eval-formula
+ - {{{kbd(C-u C-u C-c =)}}}, ~org-table-eval-formula~ :: Re-insert the
+ active formula (either a field formula, or a column formula)
+ into the current field, so that you can edit it directly in the
+ field. The advantage over editing in the minibuffer is that
+ you can use the command {{{kbd(C-c ?)}}}.
+
+ #+kindex: C-u C-u C-c =
+ #+findex: org-table-eval-formula
+
+ - {{{kbd(C-c ?)}}}, ~org-table-field-info~ :: While editing a formula
+ in a table field, highlight the field(s) referenced by the
+ reference at the cursor position in the formula.
+
+ #+kindex: C-c ?
+ #+findex: org-table-field-info
+
+ - {{{kbd(C-c })}}}, ~org-table-toggle-coordinate-overlays~ :: Toggle
+ the display of row and column numbers for a table, using
+ overlays ({{{command(org-table-toggle-coordinate-overlays)}}}).
+ These are updated each time the table is aligned; you can force
+ it with {{{kbd(C-c C-c)}}}.
+
+ #+kindex: C-c @}
+ #+findex: org-table-toggle-coordinate-overlays
+
+ - {{{kbd(C-c {)}}}, ~org-table-toggle-formula-debugger~ :: Toggle
+ the formula debugger on and off. See below.
+
+ #+kindex: C-c @{
+ #+findex: org-table-toggle-formula-debugger
+
+ - {{{kbd(C-c ')}}}, ~org-table-edit-formulas~ :: Edit all formulas
+ for the current table in a special buffer, where the formulas
+ will be displayed one per line. If the current field has an
+ active formula, the cursor in the formula editor will mark it.
+ While inside the special buffer, Org will automatically
+ highlight any field or range reference at the cursor position.
+ You may edit, remove and add formulas, and use the following
+ commands:
+
+ #+kindex: C-c '
+ #+findex: org-table-edit-formulas
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c C-c)}}} or {{{kbd(C-x C-s)}}}, ~org-table-fedit-finish~ ::
+
+ Exit the formula editor and store the modified formulas. With
+ {{{kbd(C-u)}}} prefix, also apply the new formulas to the
+ entire table.
+
+ #+kindex: C-x C-s
+ #+kindex: C-c C-c
+ #+findex: org-table-fedit-finish
+ - {{{kbd(C-c C-q)}}}, ~org-table-fedit-abort~ :: Exit the formula
+ editor without installing changes.
+
+ #+kindex: C-c C-q
+ #+findex: org-table-fedit-abort
+ - {{{kbd(C-c C-r)}}}, ~org-table-fedit-toggle-ref-type~ :: Toggle all
+ references in the formula editor between standard (like ~B3~)
+ and internal (like ~@3$2~).
+
+ #+kindex: C-c C-r
+ #+findex: org-table-fedit-toggle-ref-type
+ - {{{key(TAB)}}}, ~org-table-fedit-lisp-indent~ :: Pretty-print or
+ indent Lisp formula at point. When in a line containing a Lisp
+ formula, format the formula according to Emacs Lisp rules.
+ Another {{{key(TAB)}}} collapses the formula back again. In
+ the open formula, {{{key(TAB)}}} re-indents just like in Emacs
+ Lisp mode.
+
+ #+kindex: TAB
+ #+findex: org-table-fedit-lisp-indent
+ - {{{kbdkey(M-,TAB)}}}, ~lisp-complete-symbol~ :: Complete Lisp
+ symbols, just like in Emacs Lisp mode.
+
+ #+kindex: M-TAB
+ #+findex: lisp-complete-symbol
+ - {{{kbdkey(S-,up)}}}/{{{key(down)}}}/{{{key(left)}}}/{{{key(right)}}} :: Shift
+ the reference at point. For example, if the reference is ~B3~
+ and you press {{{kbdkey(S-,right)}}}, it will become ~C3~.
+ This also works for relative references and for hline
+ references.
+
+ #+kindex: S-up
+ #+kindex: S-down
+ #+kindex: S-left
+ #+kindex: S-right
+ #+findex: org-table-fedit-ref-up
+ #+findex: org-table-fedit-ref-down
+ #+findex: org-table-fedit-ref-left
+ #+findex: org-table-fedit-ref-right
+ - {{{kbdkey(M-S-,up)}}}, ~org-table-fedit-line-up~ ::
+
+ Move the test line for column formulas up in the Org buffer.
+
+ #+kindex: M-S-up
+ #+findex: org-table-fedit-line-up
+
+ - {{{kbdkey(M-S-,down)}}}, ~org-table-fedit-line-down~ ::
+
+ Move the test line for column formulas down in the Org buffer.
+
+ #+kindex: M-S-down
+ #+findex: org-table-fedit-line-down
+
+ - {{{kbdkey(M-,up)}}}, ~org-table-fedit-scroll-up~ ::
+
+ Scroll up the window displaying the table.
+
+ #+kindex: M-up
+ #+findex: org-table-fedit-scroll-up
+
+ - {{{kbdkey(M-,down)}}}, ~org-table-fedit-scroll-down~ ::
+
+ Scroll down the window displaying the table.
+
+ #+kindex: M-down
+ #+findex: org-table-fedit-scroll-down
+
+ - {{{kbd(C-c })}}} :: Turn the coordinate grid in the table on and
+ off.
+
+ #+kindex: C-c @@
+ #+findex: org-table-toggle-coordinate-overlays
+
+Making a table field blank does not remove the formula associated with
+the field, because that is stored in a different line (the
+{{{samp(#+TBLFM)}}} line)---during the next recalculation the field
+will be filled again. To remove a formula from a field, you have to
+give an empty reply when prompted for the formula, or to edit the
+{{{samp(#+TBLFM)}}} line.
+
+#+kindex: C-c C-c
+You may edit the {{{samp(#+TBLFM)}}} directly and re-apply the changed
+equations with {{{kbd(C-c C-c)}}} in that line or with the normal
+recalculation commands in the table.
+
+*** Debugging formulas
+ :PROPERTIES:
+ :DESCRIPTION: Help fixing formulas
+ :END:
+
+#+cindex: formula debugging
+#+cindex: debugging, of table formulas
+
+When the evaluation of a formula leads to an error, the field content
+becomes the string {{{samp(#ERROR)}}}. If you would like see what is
+going on during variable substitution and calculation in order to find
+a bug, turn on formula debugging in the ~Tbl~ menu and repeat the
+calculation, for example by pressing {{{kbdspckey(C-u C-u C-c =,RET)}}}
+in a field. Detailed information will be displayed.
+
+*** Updating the table
+ :PROPERTIES:
+ :DESCRIPTION: Recomputing all dependent fields
+ :END:
+#+cindex: recomputing table fields
+#+cindex: updating, table
+
+Recalculation of a table is normally not automatic, but needs to be
+triggered by a command. See [[Advanced features]], for a way to make
+recalculation at least semi-automatic.
+
+In order to recalculate a line of a table or the entire table, use the
+following commands:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c *)}}}, ~org-table-recalculate~ :: Recalculate the
+ current row by first applying the stored column formulas from
+ left to right, and all field/range formulas in the current row.
+
+ #+kindex: C-c *
+ #+findex: org-table-recalculate
+ - {{{kbd(C-u C-c *)}}} or {{{kbd(C-u C-c C-c)}}} :: Recompute the
+ entire table, line by line. Any lines before the first hline
+ are left alone, assuming that these are part of the table
+ header.
+
+ #+kindex: C-u C-c *
+ #+kindex: C-u C-c C-c
+ - {{{kbd(C-u C-u C-c *)}}} or {{{kbd(C-u C-u C-c C-c)}}}, ~org-table-iterate~ ::
+
+ Iterate the table by recomputing it until no further changes
+ occur. This may be necessary if some computed fields use the
+ value of other fields that are computed /later/ in the
+ calculation sequence.
+
+ #+kindex: C-u C-u C-c *
+ #+kindex: C-u C-u C-c C-c
+ #+findex: org-table-iterate
+ - {{{kbd(M-x org-table-recalculate-buffer-tables)}}} :: Recompute
+ all tables in the current buffer.
+
+ #+findex: org-table-recalculate-buffer-tables
+ - {{{kbd(M-x org-table-iterate-buffer-tables)}}} :: Iterate all
+ tables in the current buffer, in order to converge
+ table-to-table dependencies.
+
+ #+findex: org-table-iterate-buffer-tables
+*** Advanced features
+ :PROPERTIES:
+ :DESCRIPTION: Field and column names, parameters, and automatic recalc
+ :END:
+If you want the recalculation of fields to happen automatically, or if
+you want to be able to assign /names/ to fields and columns,
+you need to reserve the first column of the table for special marking
+characters.[fn:30]
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-#)}}}, ~org-table-rotate-recalc-marks~ :: Rotate the
+ calculation mark in first column through the states {{{samp( )}}}, {{{samp(#)}}}, {{{samp(*)}}}, {{{samp(!)}}},
+ {{{samp($)}}}. When there is an active region, change all
+ marks in the region.
+
+ #+kindex: C-#
+ #+findex: org-table-rotate-recalc-marks
+Here is an example of a table that collects exam results of students
+and makes use of these features:
+
+#+begin_src org
+ |---+---------+--------+--------+--------+-------+------|
+ | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
+ |---+---------+--------+--------+--------+-------+------|
+ | ! | | P1 | P2 | P3 | Tot | |
+ | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
+ | ^ | | m1 | m2 | m3 | mt | |
+ |---+---------+--------+--------+--------+-------+------|
+ | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
+ | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
+ |---+---------+--------+--------+--------+-------+------|
+ | | Average | | | | 25.0 | |
+ | ^ | | | | | at | |
+ | $ | max=50 | | | | | |
+ |---+---------+--------+--------+--------+-------+------|
+ ,#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
+#+end_src
+
+{{{noindent}}} Important: please note that for these special tables,
+recalculating the table with {{{kbd(C-u C-c *)}}} will only affect
+rows that are marked ~#~ or ~*~, and fields that
+have a formula assigned to the field itself. The column formulas are
+not applied in rows with empty first field.
+
+#+cindex: marking characters, tables
+The marking characters have the following meaning:
+#+attr_texinfo: :table-type table :indic @samp
+ - ! :: The fields in this line define names for the columns, so that
+ you may refer to a column as {{{samp($Tot)}}} instead of
+ {{{samp($6)}}}.
+ - ^ :: This row defines names for the fields @emph{above} the row.
+ With such a definition, any formula in the table may use
+ {{{samp($m1)}}} to refer to the value {{{samp(10)}}}. Also,
+ if you assign a formula to a names field, it will be stored
+ as ~$name= ...~.
+ - _ :: Similar to {{{samp(^)}}}, but defines names for the fields in
+ the row /below/.
+ - $ :: Fields in this row can define /parameters/ for formulas. For
+ example, if a field in a {{{samp($)}}} row contains
+ {{{samp(max=50)}}}, then formulas in this table can refer to
+ the value 50 using {{{samp($max)}}}. Parameters work exactly
+ like constants, only that they can be defined on a per-table
+ basis.
+ - # :: Fields in this row are automatically recalculated when
+ pressing {{{key(TAB)}}} or {{{key(RET)}}} or
+ {{{kbdkey(S-,TAB)}}} in this row. Also, this row is selected
+ for a global recalculation with {{{kbd(C-u C-c *)}}}.
+ Unmarked lines will be left alone by this command.
+ - * :: Selects this line for global recalculation with {{{kbd(C-u C-c *)}}}, but not for automatic recalculation. Use this
+ when automatic recalculation slows down editing too much.
+ - \nbsp :: Unmarked lines are exempt from recalculation with {{{kbd(C-u C-c *)}}}. All lines that should be recalculated should be
+ marked with ~#~ or ~*~.
+ - / :: Do not export this line. Useful for lines that contain the
+ narrowing ~<N>~ markers or column group markers.
+
+
+Finally, just to whet your appetite for what can be done with the
+fantastic {{{file(calc.el)}}} package, here is a table that computes
+the Taylor series of degree ~n~ at location ~x~ for a couple of
+functions.
+
+#+begin_src org
+ |---+-------------+---+-----+--------------------------------------|
+ | | Func | n | x | Result |
+ |---+-------------+---+-----+--------------------------------------|
+ | # | exp(x) | 1 | x | 1 + x |
+ | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
+ | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
+ | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
+ | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
+ | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
+ |---+-------------+---+-----+--------------------------------------|
+ ,#+TBLFM: $5=taylor($2,$4,$3);n3
+#+end_src
+
+** Org-Plot
+ :PROPERTIES:
+ :DESCRIPTION: Plotting from Org tables
+ :END:
+#+cindex: graph, in tables
+#+cindex: plot tables using Gnuplot
+#+cindex: #+PLOT
+
+Org-Plot can produce 2D and 3D graphs of information stored in org
+tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]]. To see this in action, ensure
+that you have both Gnuplot and Gnuplot-mode installed on your system,
+then call ~org-plot/gnuplot~ on the following table.
+
+#+begin_src org
+ ,#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
+ | Sede | Max cites | H-index |
+ |-----------+-----------+---------|
+ | Chile | 257.72 | 21.39 |
+ | Leeds | 165.77 | 19.68 |
+ | Sao Paolo | 71.00 | 11.50 |
+ | Stockholm | 134.19 | 14.33 |
+ | Morels | 257.56 | 17.67 |
+#+end_src
+
+Notice that Org Plot is smart enough to apply the table's headers as
+labels. Further control over the labels, type, content, and appearance
+of plots can be exercised through the ~#+PLOT:~ lines preceding a
+table. See below for a complete list of Org-plot options. For more
+information and examples see the [[http://orgmode.org/worg/org-tutorials/org-plot.html][Org-plot tutorial]].
+
+Org-Plot recognizes the following options:
+
+#+attr_texinfo: :table-type table :indic @code
+ - set :: Specify any {{{command(gnuplot)}}} option to be set when
+ graphing.
+ - title :: Specify the title of the plot.
+ - ind :: Specify which column of the table to use as the ~x~ axis.
+ - deps :: Specify the columns to graph as a Lisp style list,
+ surrounded by parentheses and separated by spaces for
+ example ~dep:(3 4)~ to graph the third and fourth columns
+ (defaults to graphing all other columns aside from the
+ ~ind~ column).
+ - type :: Specify whether the plot will be ~2d~, ~3d~, or ~grid~.
+ - with :: Specify a ~with~ option to be inserted for every col being
+ plotted (e.g., ~lines~, ~points~, ~boxes~, ~impulses~,
+ etc.). Defaults to ~lines~.
+ - file :: If you want to plot to a file, specify
+ ~"{path/to/desired/output-file}"~.
+ - labels :: List of labels to be used for the ~deps~ (defaults to
+ the column headers if they exist).
+ - line :: Specify an entire line to be inserted in the Gnuplot
+ script.
+ - map :: When plotting ~3d~ or ~grid~ types, set this to ~t~ to
+ graph a flat mapping rather than a ~3d~ slope.
+ - timefmt :: Specify format of Org mode timestamps as they will be
+ parsed by Gnuplot. Defaults to
+ {{{samp(%Y-%m-%d-%H:%M:%S)}}}.
+ - script :: If you want total control, you can specify a script file
+ (place the file name between double-quotes) which will
+ be used to plot. Before plotting, every instance of
+ ~$datafile~ in the specified script will be replaced
+ with the path to the generated data file. Note: even if
+ you set this option, you may still want to specify the
+ plot type, as that can impact the content of the data
+ file.
+
+* Hyperlinks
+ :PROPERTIES:
+ :DESCRIPTION: Notes in context
+ :ORDERED: t
+ :END:
+#+cindex: hyperlinks
+
+Like HTML, Org provides links inside a file, external links to
+other files, Usenet articles, emails, and much more.
+
+** Link format
+ :PROPERTIES:
+ :DESCRIPTION: How links in Org are formatted
+ :END:
+#+cindex: link format
+#+cindex: format, of links
+
+Org will recognize plain URL-like links and activate them as clickable
+links. The general link format, however, looks like this:
+
+#+begin_src org
+ [[link][description]] or [[link]]
+#+end_src
+
+
+{{{noindent}}} Once a link in the buffer is complete (all brackets
+present), Org will change the display so that {{{samp(description)}}}
+is displayed instead of ~[[link][description]]~ and {{{samp(link)}}}
+is displayed instead of ~[[link]]~. Links will be highlighted
+in the face ~org-link~, which by default is an underlined face. You
+can directly edit the visible part of a link. Note that this can be
+either the {{{samp(link)}}} part (if there is no description) or the
+{{{samp(description)}}} part. To edit also the invisible
+{{{samp(link)}}} part, use {{{kbd(C-c C-l)}}} with the cursor on the
+link.
+
+If you place the cursor at the beginning or just behind the end of the
+displayed text and press {{{key(BACKSPACE)}}}, you will remove the
+(invisible) bracket at that location. This makes the link incomplete
+and the internals are again displayed as plain text. Inserting the
+missing bracket hides the link internals again. To show the internal
+structure of all links, use the menu entry ~Org->Hyperlinks->Literal
+links~.
+
+** Internal links
+ :PROPERTIES:
+ :DESCRIPTION: Links to other places in the current file
+ :END:
+#+cindex: internal links
+#+cindex: links, internal
+#+cindex: targets, for links
+#+cindex: property, CUSTOM_ID
+
+If the link does not look like a URL, it is considered to be internal
+in the current file. The most important case is a link like
+~[[#my-custom-id]]~ which will link to the entry with the
+~CUSTOM_ID~ property {{{samp(my-custom-id)}}}. Such custom IDs are
+very good for HTML export (see [[HTML export]]) where they produce pretty
+section links. You are responsible yourself to make sure these custom
+IDs are unique in a file.
+
+Links such as the two in the following example:
+
+#+begin_example
+ [[My Target]] or [[My Target][Find my target]]
+#+end_example
+
+{{{noindent}}} lead to a text search in the current file.
+
+The link can be followed with {{{kbd(C-c C-o)}}} when the cursor is on
+the link, or with a mouse click (see [[Handling links]]). Links to custom
+IDs will point to the corresponding headline. The preferred match for
+a text link is a /dedicated target/: the same string in double angular
+brackets. Targets may be located anywhere; sometimes it is convenient
+to put them into a comment line. For example
+
+#+begin_src org
+ # <<My Target>>
+#+end_src
+
+{{{noindent}}} In HTML export (see [[HTML export]]), such targets will
+become named anchors for direct access through {{{samp(http)}}}
+links.[fn:31]
+
+If no dedicated target exists, Org will search for a headline that is
+exactly the link text but may also include a TODO keyword and
+tags.[fn:32] In non-Org files, the search will look for the words in
+the link text. In the above example the search would be for ~my target~.
+
+Following a link pushes a mark onto Org's own mark ring. You can
+return to the previous position with {{{kbd(C-c &)}}}. Using this
+command several times in direct succession goes back to positions
+recorded earlier.
+
+** Radio targets
+ :PROPERTIES:
+ :DESCRIPTION: Automatically create internal links
+ :END:
+#+cindex: radio targets
+#+cindex: targets, radio
+#+cindex: links, radio targets
+
+Org can automatically turn any occurrences of certain target names in
+normal text into a link. So without explicitly creating a link, the
+text connects to the target radioing its position. Radio targets are
+enclosed by triple angular brackets. For example, a target
+~<<<My Target>>>~ causes each occurrence of ~my target~ in
+normal text to become activated as a link. The Org file is scanned
+automatically for radio targets only when the file is first loaded
+into Emacs. To update the target list during editing, press
+{{{kbd(C-c C-c)}}} with the cursor on or at a target.
+
+** External links
+ :PROPERTIES:
+ :DESCRIPTION: URL-like links to the world
+ :END:
+#+cindex: links, external
+#+cindex: external links
+#+cindex: links, external
+#+cindex: Gnus links
+#+cindex: BBDB links
+#+cindex: IRC links
+#+cindex: URL links
+#+cindex: file links
+#+cindex: VM links
+#+cindex: RMAIL links
+#+cindex: WANDERLUST links
+#+cindex: MH-E links
+#+cindex: USENET links
+#+cindex: SHELL links
+#+cindex: Info links
+#+cindex: Elisp links
+
+Org supports links to files, websites, Usenet and email messages, BBDB
+database entries and links to both IRC conversations and their logs.
+External links are URL-like locators. They start with a short
+identifying string followed by a colon. There can be no space after
+the colon. The following list shows examples for each link type.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - ~http://www.astro.uva.nl/~dominik~ :: on the web
+ - ~doi:10.1000/182~ :: DOI for an electronic resource
+ - ~file:/home/dominik/images/jupiter.jpg~ :: file, absolute path
+ - ~/home/dominik/images/jupiter.jpg~ :: same as above
+ - ~file:papers/last.pdf~ :: file, relative path
+ - ~./papers/last.pdf~ :: same as above
+ - ~file:/myself@some.where:papers/last.pdf~ :: file, path on remote machine
+ - ~/myself@some.where:papers/last.pdf~ :: same as above
+ - ~file:sometextfile::NNN~ :: file, jump to line number
+ - ~file:projects.org~ :: another Org file
+ - ~file:projects.org::some words~ :: text search in Org file[fn:33]
+ - ~file:projects.org::*task title~ :: heading search in Org file
+ - ~file+sys:/path/to/file~ :: open via OS, like double-click
+ - ~file+emacs:/path/to/file~ :: force opening by Emacs
+ - ~docview:papers/last.pdf::NNN~ :: open in doc-view mode at page
+ - ~id:B7423F4D-2E8A-471B-8810-C40F074717E9~ :: Link to heading by ID
+ - ~news:comp.emacs~ :: Usenet link
+ - ~mailto:adent@galaxy.net~ :: Mail link
+ - ~vm:folder~ :: VM folder link
+ - ~vm:folder#id~ :: VM message link
+ - ~vm://myself@some.where.org/folder#id~ :: VM on remote machine
+ - ~vm-imap:account:folder~ :: VM IMAP folder link
+ - ~vm-imap:account:folder#id~ :: VM IMAP message link
+ - ~wl:folder~ :: WANDERLUST folder link
+ - ~wl:folder#id~ :: WANDERLUST message link
+ - ~mhe:folder~ :: MH-E folder link
+ - ~mhe:folder#id~ :: MH-E message link
+ - ~rmail:folder~ :: RMAIL folder link
+ - ~rmail:folder#id~ :: RMAIL message link
+ - ~gnus:group~ :: Gnus group link
+ - ~gnus:group#id~ :: Gnus article link
+ - ~bbdb:R.*Stallman~ :: BBDB link (with regexp)
+ - ~irc:/irc.com/#emacs/bob~ :: IRC link
+ - ~info:org#External links~ :: Info node link
+ - ~shell:ls *.org~ :: A shell command
+ - ~elisp:org-agenda~ :: Interactive Elisp command
+ - ~elisp:(find-file-other-frame "Elisp.org")~ :: Elisp form to evaluate
+
+
+For customizing Org to add new link types [[Adding hyperlink types]].
+
+A link should be enclosed in double brackets and may contain a
+descriptive text to be displayed instead of the URL (see [[Link format]]),
+for example:
+
+#+begin_src org
+ [[http://www.gnu.org/software/emacs/][GNU Emacs]]
+#+end_src
+
+{{{noindent}}} If the description is a file name or URL that points to
+an image, HTML export (see [[HTML export]]) will inline the image as a
+clickable button. If there is no description at all and the link
+points to an image, that image will be inlined into the exported HTML
+file.
+
+#+cindex: square brackets, around links
+#+cindex: plain text external links
+
+Org also finds external links in the normal text and activates them as
+links. If spaces must be part of the link (for example in
+{{{samp(bbdb:Richard Stallman)}}}), or if you need to remove
+ambiguities about the end of the link, enclose them in square
+brackets.
+
+** Handling links
+ :PROPERTIES:
+ :DESCRIPTION: URL-like links to the world
+ :END:
+#+cindex: links, handling
+
+Org provides methods to create a link in the correct syntax, to
+insert it into an Org file, and to follow the link.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c l)}}}, ~org-store-link~ :: Store a link to the current
+ location. This is a /global/ command (you must create the key
+ binding yourself) which can be used in any buffer to create a
+ link. The link will be stored for later insertion into an Org
+ buffer (see below). What kind of link will be created depends
+ on the current buffer:
+
+ #+cindex: storing links
+ #+kindex: C-c l
+ #+findex: org-store-link
+ - Org mode buffers :: For Org files, if there is a
+ ~<<target>>~ at the cursor, the link points to the
+ target. Otherwise it points to the current headline, which
+ will also be the description.[fn:34]
+
+ #+vindex: org-link-to-org-use-id
+ #+cindex: property, CUSTOM_ID
+ #+cindex: property, ID
+
+ If the headline has a ~CUSTOM_ID~ property, a link to this
+ custom ID will be stored. In addition or alternatively
+ (depending on the value of ~org-link-to-org-use-id~), a
+ globally unique ~ID~ property will be created and/or used to
+ construct a link.[fn:176] So using this command in Org buffers will
+ potentially create two links: a human-readable link from the
+ custom ID, and one that is globally unique and works even if
+ the entry is moved from file to file. Later, when inserting
+ the link, you need to decide which one to use.
+
+ - Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus :: Pretty
+ much all Emacs mail clients are supported. The link will
+ point to the current article, or, in some GNUS buffers, to
+ the group. The description is constructed from the author
+ and the subject.
+
+ - Web browsers: W3 and W3M :: Here the link will be the current
+ URL, with the page title as description.
+
+ - Contacts: BBDB :: Links created in a BBDB buffer will point to
+ the current entry.
+ - Chat: IRC :: For IRC links, if you set the variable
+ ~org-irc-link-to-logs~ to ~t~, a ~file:~
+ style link to the relevant point in the logs for
+ the current conversation is created. Otherwise an
+ ~irc:/~ style link to the
+ user/channel/server under the point will be stored.
+
+ #+vindex: org-irc-link-to-logs
+
+ - Other files :: For any other files, the link will point to the
+ file, with a search string (see [[Search options]])
+ pointing to the contents of the current line. If
+ there is an active region, the selected words
+ will form the basis of the search string. If the
+ automatically created link is not working
+ correctly or accurately enough, you can write
+ custom functions to select the search string and
+ to do the search for particular file types---see
+ [[Custom searches]]. The key binding {{{kbd(C-c l)}}}
+ is only a suggestion---see [[Installation]].
+
+ - Agenda view :: When the cursor is in an agenda view, the created
+ link points to the entry referenced by the
+ current line.
+
+ - {{{kbd(C-c C-l)}}}, ~org-insert-link~ :: Insert a link.[fn:35] This
+ prompts for a link to be inserted into the buffer. You can just
+ type a link, using text for an internal link, or one of the
+ link type prefixes mentioned in the examples above. The link
+ will be inserted into the buffer, along with a
+ descriptive text.[fn:36] If some text was selected when this command
+ is called, the selected text becomes the default description.
+
+ #+cindex: link completion
+ #+cindex: completion, of links
+ #+cindex: inserting links
+ #+vindex: org-keep-stored-link-after-insertion
+ #+kindex: C-c C-l
+ #+findex: org-insert-link
+ - Inserting stored links :: All links stored during the current
+ session are part of the history for this prompt, so you can
+ access them with {{{key(up)}}} and {{{key(down)}}} (or
+ {{{kbd(M-p/n)}}}).
+
+ - Completion support :: Completion with {{{key(TAB)}}} will help
+ you to insert valid link prefixes like ~http:~ or
+ ~ftp:~, including the prefixes defined through link
+ abbreviations (see [[Link abbreviations]]). If you press
+ {{{key(RET)}}} after inserting only the
+ {{{var(prefix)}}}, Org will offer specific completion
+ support for some link types.[fn:37] For example, if you type
+ {{{kbdspckey(file,RET)}}}, file name completion (alternative
+ access: {{{kbd(C-u C-c C-l)}}}, see below) will be offered,
+ and after {{{kbdspckey(bbdb,RET)}}} you can complete contact
+ names.
+
+ - {{{kbd(C-u C-c C-l)}}} :: When {{{kbd(C-c C-l)}}} is called with a
+ {{{kbd(C-u)}}} prefix argument, a link to a file will be
+ inserted and you may use file name completion to select the
+ name of the file. The path to the file is inserted relative to
+ the directory of the current Org file, if the linked file is in
+ the current directory or in a sub-directory of it, or if the
+ path is written relative to the current directory using
+ {{{samp(../)}}}. Otherwise an absolute path is used, if
+ possible with {{{samp(~/)}}} for your home directory. You can
+ force an absolute path with two {{{kbd(C-u)}}} prefixes.
+
+ #+cindex: file name completion
+ #+cindex: completion, of file names
+ #+kindex: C-u C-c C-l
+
+ - {{{kbd(C-c C-l)}}} (with cursor on existing link) :: When the
+ cursor is on an existing link, {{{kbd(C-c C-l)}}} allows you to
+ edit the link and description parts of the link.
+
+ #+cindex: following links
+
+ - {{{kbd(C-c C-o)}}}, ~org-open-at-point~ :: Open link at
+ point. This will launch a web browser for URLs (using
+ {{{command(browse-url-at-point)}}}), run
+ VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for the corresponding
+ links, and execute the command in a shell link. When the
+ cursor is on an internal link, this command runs the
+ corresponding search. When the cursor is on a TAG list in a
+ headline, it creates the corresponding TAGS view. If the
+ cursor is on a timestamp, it compiles the agenda for that
+ date. Furthermore, it will visit text and remote files in
+ ~file:~ links with Emacs and select a suitable
+ application for local non-text files. Classification of files
+ is based on file extension only. See option ~org-file-apps~.
+ If you want to override the default application and visit the
+ file with Emacs, use a {{{kbd(C-u)}}} prefix. If you want to
+ avoid opening in Emacs, use a {{{kbd(C-u C-u)}}} prefix. If
+ the cursor is on a headline, but not on a link, offer all
+ links in the headline and entry text. If you want to setup
+ the frame configuration for following links, customize
+ ~org-link-frame-setup~.
+
+ #+vindex: org-file-apps
+ #+vindex: org-link-frame-setup
+ #+kindex: C-c C-o
+ #+findex: org-open-at-point
+ - {{{key(RET)}}} :: When ~org-return-follows-link~ is set,
+ {{{key(RET)}}} will also follow the link at
+ point.
+
+ #+vindex: org-return-follows-link
+ #+kindex: RET
+ - {{{key(mouse-2)}}} or {{{key(mouse-1)}}} :: On links,
+ {{{kbd(mouse-2)}}} will open the link just as {{{kbd(C-c C-o)}}} would. Under Emacs 22 and later, {{{kbd(mouse-1)}}}
+ will also follow a link.
+
+ #+kindex: mouse-2
+ #+kindex: mouse-1
+ - {{{key(mouse-3)}}} :: Like {{{kbd(mouse-2)}}}, but force file
+ links to be opened with Emacs, and internal links to be
+ displayed in another window.[fn:38]
+
+ #+vindex: org-display-internal-link-with-indirect-buffer
+ #+kindex: mouse-3
+ - {{{kbd(C-c C-x C-v)}}}, ~org-toggle-inline-images~ ::
+ #+cindex: inlining images
+ #+cindex: images, inlining
+ #+vindex: org-startup-with-inline-images
+ #+cindex: ~inlineimages~, STARTUP keyword
+ #+cindex: ~noinlineimages~, STARTUP keyword
+ #+kindex: C-c C-x C-v
+ #+findex: org-toggle-inline-images
+
+ Toggle the inline display of linked images. Normally this
+ will only inline images that have no description part in the
+ link, i.e., images that will also be inlined during export.
+ When called with a prefix argument, also display images that
+ do have a link description. You can ask for inline images to
+ be displayed at startup by configuring the variable
+ ~org-startup-with-inline-images~.[fn:177]
+
+ - {{{kbd(C-c %)}}}, ~org-mark-ring-push~ ::
+ #+kindex: C-c %
+ #+findex: org-mark-ring-push
+ #+cindex: mark ring
+
+ Push the current position onto the mark ring, to be able to
+ return easily. Commands following an internal link do this
+ automatically.
+
+ - {{{kbd(C-c &)}}}, ~org-mark-ring-goto~ ::
+ #+kindex: C-c &
+ #+findex: org-mark-ring-goto
+ #+cindex: links, returning to
+
+ Jump back to a recorded position. A position is recorded by
+ the commands following internal links, and by {{{kbd(C-c %)}}}. Using this command several times in direct succession
+ moves through a ring of previously recorded positions.
+
+ - {{{kbd(C-c C-x C-n)}}}, ~org-next-link~ ::
+ @@info:@itemx@@ {{{kbd(C-c C-x C-p)}}}, ~org-previous-link~
+ #+cindex: links, finding next/previous
+
+ #+kindex: C-c C-x C-p
+ #+findex: org-previous-link
+ #+kindex: C-c C-x C-n
+ #+findex: org-next-link
+
+ Move forward/backward to the next link in the buffer. At the
+ limit of the buffer, the search fails once, and then wraps
+ around. The key bindings for this are really too long; you
+ might want to bind this also to {{{kbd(C-n)}}} and
+ {{{kbd(C-p)}}}
+
+ #+header: :exports code
+ #+header: :eval no
+ #+begin_src emacs-lisp
+ (add-hook 'org-load-hook
+ (lambda ()
+ (define-key org-mode-map "\C-n" 'org-next-link)
+ (define-key org-mode-map "\C-p" 'org-previous-link)))
+ #+end_src
+
+** Using links outside Org
+ :PROPERTIES:
+ :DESCRIPTION: Linking from my C source code?
+ :END:
+
+You can insert and follow links that have Org syntax not only in Org,
+but in any Emacs buffer. For this, you should create two global
+commands, like this (please select suitable global keys yourself):
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ (global-set-key "\C-c L" 'org-insert-link-global)
+ (global-set-key "\C-c o" 'org-open-at-point-global)
+#+end_src
+
+** Link abbreviations
+ :PROPERTIES:
+ :DESCRIPTION: Shortcuts for writing complex links
+ :END:
+#+cindex: link abbreviations
+#+cindex: abbreviation, links
+
+Long URLs can be cumbersome to type, and often many similar links are
+needed in a document. For this you can use link abbreviations. An
+abbreviated link looks like this
+
+#+begin_src org
+[[linkword:tag][description]]
+#+end_src
+
+#+vindex: org-link-abbrev-alist
+
+{{{noindent}}} where the tag is optional. The /linkword/ must be a
+word, starting with a letter, followed by letters, numbers,
+{{{samp(-)}}}, and {{{samp(_)}}}. Abbreviations are resolved
+according to the information in the variable ~org-link-abbrev-alist~
+that relates the linkwords to replacement text. Here is an example:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+ (setq org-link-abbrev-alist
+ '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
+ ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
+ ("google" . "http://www.google.com/search?q=")
+ ("gmap" . "http://maps.google.com/maps?q=%s")
+ ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
+ ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
+#+end_src
+
+If the replacement text contains the string {{{samp(%s)}}}, it will be
+replaced with the tag. Using {{{samp(%h)}}} instead of {{{samp(%s)}}}
+will url-encode the tag (see the example above, where we need to
+encode the URL parameter.) Using {{{samp(%(my-function))}}} will pass
+the tag to a custom function, and replace it by the resulting string.
+
+If the replacement text don't contain any specifier, it will simply be
+appended to the string in order to create the link.
+
+Instead of a string, you may also specify a function that will be
+called with the tag as the only argument to create the link.
+
+With the above setting, you could link to a specific bug with
+~[[bugzilla:129]]~, search the web for {{{samp(OrgMode)}}} with
+~[[google:OrgMode]]~, show the map location of the Free Software
+Foundation ~[[gmap:51 Franklin Street, Boston]]~ or of Carsten office
+~[[omap:Science Park 904, Amsterdam, The Netherlands]]~ and find out what
+the Org author is doing besides Emacs hacking with ~[[ads:Dominik,C]]~.
+
+If you need special abbreviations just for a single Org buffer, you
+can define them in the file with
+
+#+cindex: #+LINK
+#+begin_src org
+ ,#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
+ ,#+LINK: google http://www.google.com/search?q=%s
+#+end_src
+
+{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
+after {{{samp([)}}} to complete link abbreviations. You may also
+define a function that implements special (e.g., completion) support
+for inserting such a link with {{{kbd(C-c C-l)}}}. Such a function
+should not accept any arguments, and return the full link with
+prefix. You can set the link completion function like this:
+
+#+BEGIN_SRC emacs-lisp
+(org-link-set-parameter "type" :complete #'some-completion-function)
+#+END_SRC
+
+** Search options
+ :PROPERTIES:
+ :DESCRIPTION: Linking to a specific location
+ :END:
+#+cindex: search option in file links
+#+cindex: file links, searching
+
+File links can contain additional information to make Emacs jump to a
+particular location in the file when following a link. This can be a
+line number or a search option after a double colon.[fn:39]
+For example, when the command {{{kbd(C-c l)}}} creates a link (see
+[[Handling links]]) to a file, it encodes the words in the current line as
+a search string that can be used to find this line back later when
+following the link with {{{kbd(C-c C-o)}}}.
+
+Here is the syntax of the different ways to attach a search to a file
+link, together with an explanation:
+
+#+begin_src org
+ [[file:~/code/main.c::255]]
+ [[file:~/xx.org::My Target]]
+ [[file:~/xx.org::*My Target]]
+ [[file:~/xx.org::#my-custom-id]]
+ [[file:~/xx.org::/regexp/]]
+#+end_src
+
+#+attr_texinfo: :indic @code
+- 255 :: Jump to line 255.
+- My Target :: Search for a link target ~<<My Target>>~, or do a text search for {{{samp(my target)}}},
+ similar to the search in internal links, see [[Internal links]].
+ In HTML export (see [[HTML export]]), such a file link will
+ become a HTML reference to the corresponding named anchor in the
+ linked file.
+- *My Target :: In an Org file, restrict search to headlines.
+- #my-custom-id :: Link to a heading with a ~CUSTOM_ID~ property
+- /regexp/ :: Do a regular expression search for ~regexp~. This
+ uses the Emacs command ~occur~ to list all matches
+ in a separate window. If the target file is in
+ Org mode, ~org-occur~ is used to create a sparse
+ tree with the matches. @c If the target file is a
+ directory, @c ~grep~ will be used to search all
+ files in the directory.
+
+As a degenerate case, a file link with an empty file name can be used
+to search the current file. For example, ~[[file:::find me]]~ does a
+search for ~find me~ in the current file, just as
+~[[find me]]~ would.
+
+** Custom searches
+ :PROPERTIES:
+ :DESCRIPTION: When the default search is not enough
+ :END:
+#+cindex: custom search strings
+#+cindex: search strings, custom
+
+The default mechanism for creating search strings and for doing the
+actual search related to a file link may not work correctly in all
+cases. For example, BibTeX database files have many entries like
+{{{samp(year="1993")}}} which would not result in good search strings,
+because the only unique identification for a BibTeX entry is the
+citation key.
+
+#+vindex: org-create-file-search-functions
+#+vindex: org-execute-file-search-functions
+
+If you come across such a problem, you can write custom functions to
+set the right search string for a particular file type, and to do the
+search for the string in the file. Using ~add-hook~, these functions
+need to be added to the hook variables
+~org-create-file-search-functions~ and
+~org-execute-file-search-functions~. See the docstring for these
+variables for more information. Org actually uses this mechanism for
+BibTeX database files, and you can use the corresponding code as an
+implementation example. See the file {{{file(org-bibtex.el)}}}.
+
+* TODO items
+ :PROPERTIES:
+ :DESCRIPTION: Every tree branch can be a TODO item
+ :ALT_TITLE: TODO Items
+ :END:
+#+cindex: TODO items
+
+Org mode does not maintain TODO lists as separate documents.[fn:40]
+Instead, TODO items are an integral part of the notes file, because
+TODO items usually come up while taking notes! With Org mode, simply
+mark any entry in a tree as being a TODO item. In this way,
+information is not duplicated, and the entire context from which the
+TODO item emerged is always present.
+
+Of course, this technique for managing TODO items scatters them
+throughout your notes file. Org mode compensates for this by providing
+methods to give you an overview of all the things that you have to do.
+
+** TODO basics
+ :PROPERTIES:
+ :DESCRIPTION: Marking and displaying TODO entries
+ :TITLE: Basic TODO functionality
+ :END:
+
+Any headline becomes a TODO item when it starts with the word
+{{{samp(TODO)}}}, for example:
+
+#+begin_src org
+ ,*** TODO Write letter to Sam Fortune
+#+end_src
+
+{{{noindent}}} The most important commands to work with TODO entries
+are:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-t)}}}, ~org-todo~ ::
+ #+kindex: C-c C-t
+ #+cindex: cycling, of TODO states
+
+ Rotate the TODO state of the current item among
+
+ #+begin_example
+ ,-> (unmarked) -> TODO -> DONE --.
+ '--------------------------------'
+ #+end_example
+
+ The same rotation can also be done ``remotely'' from the timeline and
+ agenda buffers with the {{{kbd(t)}}} command key (see [[Agenda commands]]).
+
+- {{{kbd(C-u C-c C-t)}}} ::
+ #+kindex: C-u C-c C-t
+
+ Select a specific keyword using completion or (if it has been set up)
+ the fast selection interface. For the latter, you need to assign keys
+ to TODO states, see [[Per-file keywords]], and [[Setting tags]], for
+ more information.
+
+ #+kindex: S-@key{right}
+ #+kindex: S-@key{left}
+
+- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}} ::
+
+ #+vindex: org-treat-S-cursor-todo-selection-as-state-change
+
+ Select the following/preceding TODO state, similar to cycling.
+ Useful mostly if more than two TODO states are possible
+ (see [[TODO extensions]]). See also [[Conflicts]], for a discussion of the
+ interaction with ~shift-selection-mode~. See also the variable
+ ~org-treat-S-cursor-todo-selection-as-state-change~.
+
+- {{{kbd(C-c / t)}}}, ~org-show-todo-tree~ ::
+ #+kindex: C-c / t
+
+ #+cindex: sparse tree, for TODO
+ #+vindex: org-todo-keywords
+
+ View TODO items in a /sparse tree/ (see [[Sparse trees]]). Folds the entire
+ buffer, but shows all TODO items (with not-DONE state) and the
+ headings hierarchy above them. With a prefix argument (or by using
+ {{{kbd(C-c / T)}}}), search for a specific TODO. You will be
+ prompted for the keyword, and you can also give a list of keywords
+ like ~KWD1|KWD2|...~ to list entries that match any one of these
+ keywords. With a numeric prefix argument N, show the tree for the
+ Nth keyword in the variable ~org-todo-keywords~. With two prefix
+ arguments, find all TODO states, both un-done and done.
+
+- {{{kbd(C-c a t)}}}, ~org-todo-list~ ::
+ #+kindex: C-c a t
+
+ Show the global TODO list. Collects the TODO items (with not-DONE states)
+ from all agenda files (see [[Agenda views]]) into a single buffer. The new
+ buffer will be in ~agenda-mode~, which provides commands to examine and
+ manipulate the TODO entries from the new buffer (see [[Agenda commands]]).
+ See [[Global TODO list]], for more information.
+
+- {{{kbdkey(S-M-,RET)}}}, ~org-insert-todo-heading~ ::
+ #+kindex: S-M-@key{RET}
+
+ Insert a new TODO entry below the current one.
+
+
+{{{noindent}}}
+#+vindex: org-todo-state-tags-triggers
+Changing a TODO state can also trigger tag changes. See the docstring of the
+option ~org-todo-state-tags-triggers~ for details.
+
+** TODO extensions
+ :PROPERTIES:
+ :DESCRIPTION: Work flow and assignments
+ :TITLE: Extended use of TODO keywords
+ :END:
+
+#+cindex: extended TODO keywords
+
+#+vindex: org-todo-keywords
+
+By default, marked TODO entries have one of only two states: TODO and
+DONE. Org mode allows you to classify TODO items in more complex ways
+with /TODO keywords/ (stored in ~org-todo-keywords~). With special
+setup, the TODO keyword system can work differently in different
+files.
+
+Note that /tags/ are another way to classify headlines in general and
+TODO items in particular (see [[Tags]]).
+
+*** Workflow states
+ :PROPERTIES:
+ :DESCRIPTION: From TODO to DONE in steps
+ :TITLE: TODO keywords as workflow states
+ :END:
+#+cindex: TODO workflow
+#+cindex: workflow states as TODO keywords
+
+You can use TODO keywords to indicate different /sequential/ states
+in the process of working on an item, for example:[fn:41]
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keywords
+ '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
+#+end_src
+
+The vertical bar separates the TODO keywords (states that /need
+action/) from the DONE states (which need /no further action/). If
+you don't provide the separator bar, the last state is used as the DONE
+state.
+
+#+cindex: completion, of TODO keywords
+
+With this setup, the command {{{kbd(C-c C-t)}}} will cycle an entry
+from TODO to FEEDBACK, then to VERIFY, and finally to DONE and
+DELEGATED. You may also use a numeric prefix argument to quickly
+select a specific state. For example {{{kbd(C-3 C-c C-t)}}} will
+change the state immediately to VERIFY. Or you can use
+{{{kbdkey(S-,left)}}} to go backward through the sequence. If you
+define many keywords, you can use in-buffer completion (see [[Completion]]) or
+even a special one-key selection scheme (see [[Fast access to TODO states]])
+to insert these words into the buffer. Changing a TODO state can be
+logged with a timestamp, see [[Tracking TODO state changes]], for
+more information.
+
+*** TODO types
+ :PROPERTIES:
+ :DESCRIPTION: I do this, Fred does the rest
+ :TITLE: TODO keywords as types
+ :END:
+#+cindex: TODO types
+#+cindex: names as TODO keywords
+#+cindex: types as TODO keywords
+
+The second possibility is to use TODO keywords to indicate different
+/types/ of action items. For example, you might want to indicate
+that items are for ``work'' or ``home''. Or, when you work with several
+people on a single project, you might want to assign action items
+directly to persons, by using their names as TODO keywords. This would
+be set up like this:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
+#+end_src
+
+In this case, different keywords do not indicate a sequence, but rather
+different types. So the normal work flow would be to assign a task to a
+person, and later to mark it DONE. Org mode supports this style by adapting
+the workings of the command {{{kbd(C-c C-t)}}}.[fn:42] When used several
+times in succession, it will still cycle through all names, in order to first
+select the right type for a task. But when you return to the item after some
+time and execute {{{kbd(C-c C-t)}}} again, it will switch from any name directly
+to DONE. Use prefix arguments or completion to quickly select a specific
+name. You can also review the items of a specific TODO type in a sparse tree
+by using a numeric prefix to {{{kbd(C-c / t)}}}. For example, to see all things
+Lucy has to do, you would use {{{kbd(C-3 C-c / t)}}}. To collect Lucy's items
+from all agenda files into a single buffer, you would use the numeric prefix
+argument as well when creating the global TODO list: {{{kbd(C-3 C-c a t)}}}.
+
+*** Multiple sets in one file
+ :PROPERTIES:
+ :DESCRIPTION: Mixing it all, and still finding your way
+ :TITLE: Multiple keyword sets in one file
+ :END:
+#+cindex: TODO keyword sets
+
+Sometimes you may want to use different sets of TODO keywords in
+parallel. For example, you may want to have the basic
+~TODO~ / ~DONE~, but also a workflow for bug fixing, and a
+separate state indicating that an item has been canceled (so it is not
+DONE, but also does not require action). Your setup would then look
+like this:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keywords
+ '((sequence "TODO" "|" "DONE")
+ (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
+ (sequence "|" "CANCELED")))
+#+end_src
+
+The keywords should all be different, this helps Org mode to keep track
+of which subsequence should be used for a given entry. In this setup,
+{{{kbd(C-c C-t)}}} only operates within a subsequence, so it switches from
+~DONE~ to (nothing) to ~TODO~, and from ~FIXED~ to
+(nothing) to ~REPORT~. Therefore you need a mechanism to initially
+select the correct sequence. Besides the obvious ways like typing a
+keyword or using completion, you may also apply the following commands:
+
+#+kindex: C-S-@key{right}
+#+kindex: C-S-@key{left}
+#+kindex: C-u C-u C-c C-t
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-u C-u C-c C-t)}}} {{{kbdkey(C-S-,right)}}} {{{kbdkey(C-S-,left)}}} ::
+
+ These keys jump from one TODO subset to the next. In the above
+ example, {{{kbd(C-u C-u C-c C-t)}}} or {{{kbdkey(C-S-,right)}}}
+ would jump from ~TODO~ or ~DONE~ to ~REPORT~, and any of the
+ words in the second row to ~CANCELED~. Note that the
+ {{{kbd(C-S-)}}} key binding conflict with ~shift-selection-mode~
+ (see [[Conflicts]]).
+
+- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}} ::
+ #+kindex: S-@key{right}
+ #+kindex: S-@key{left}
+
+ {{{kbdkey(S-,left)}}} and {{{kbdkey(S-,right)}}} walk through /all/
+ keywords from all sets, so for example {{{kbdkey(S-,right)}}} would switch
+ from ~DONE~ to ~REPORT~ in the example above. See also
+ [[Conflicts]], for a discussion of the interaction with
+ ~shift-selection-mode~.
+
+*** Fast access to TODO states
+ :PROPERTIES:
+ :DESCRIPTION: Single letter selection of state
+ :END:
+If you would like to quickly change an entry to an arbitrary TODO state
+instead of cycling through the states, you can set up keys for single-letter
+access to the states. This is done by adding the selection character after
+each keyword, in parentheses.[fn:43] For example:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keywords
+ '((sequence "TODO(t)" "|" "DONE(d)")
+ (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
+ (sequence "|" "CANCELED(c)")))
+#+end_src
+
+#+vindex: org-fast-tag-selection-include-todo
+
+If you then press {{{kbd(C-c C-t)}}} followed by the selection key,
+the entry will be switched to this state. {{{kbd(SPC)}}} can be used
+to remove any TODO keyword from an entry.[fn:44]
+
+*** Per-file keywords
+ :PROPERTIES:
+ :DESCRIPTION: Different files, different requirements
+ :TITLE: Setting up keywords for individual files
+ :END:
+#+cindex: keyword options
+#+cindex: per-file keywords
+#+cindex: #+TODO
+#+cindex: #+TYP_TODO
+#+cindex: #+SEQ_TODO
+
+It can be very useful to use different aspects of the TODO mechanism in
+different files. For file-local settings, you need to add special lines
+to the file which set the keywords and interpretation for that file
+only. For example, to set one of the two examples discussed above, you
+need one of the following lines, starting in column zero anywhere in the
+file:
+
+#+begin_example
+ ,#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
+#+end_example
+
+{{{noindent}}} (you may also write ~#+SEQ_TODO~ to be explicit about the
+interpretation, but it means the same as ~#+TODO~), or
+
+#+begin_example
+ ,#+TYP_TODO: Fred Sara Lucy Mike | DONE
+#+end_example
+
+A setup for using several sets in parallel would be:
+
+#+begin_example
+ ,#+TODO: TODO | DONE
+ ,#+TODO: REPORT BUG KNOWNCAUSE | FIXED
+ ,#+TODO: | CANCELED
+#+end_example
+
+#+cindex: completion, of option keywords
+#+kindex: M-@key{TAB}
+{{{noindent}}} To make sure you are using the correct keyword, type
+{{{samp(#+)}}} into the buffer and then use {{{kbdkey(M-,TAB)}}} completion.
+
+#+cindex: DONE, final TODO keyword
+Remember that the keywords after the vertical bar (or the last keyword
+if no bar is there) must always mean that the item is DONE (although you
+may use a different word). After changing one of these lines, use
+{{{kbd(C-c C-c)}}} with the cursor still in the line to make the changes
+known to Org mode.[fn:45]
+
+*** Faces for TODO keywords
+ :PROPERTIES:
+ :DESCRIPTION: Highlighting states
+ :END:
+#+cindex: faces, for TODO keywords
+#+vindex: org-todo @r{(face)}
+#+vindex: org-done @r{(face)}
+#+vindex: org-todo-keyword-faces
+
+Org mode highlights TODO keywords with special faces: ~org-todo~
+for keywords indicating that an item still has to be acted upon, and
+~org-done~ for keywords indicating that an item is finished. If
+you are using more than 2 different states, you might want to use
+special faces for some of them. This can be done using the variable
+~org-todo-keyword-faces~. For example:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keyword-faces
+ '(("TODO" . org-warning) ("STARTED" . "yellow")
+ ("CANCELED" . (:foreground "blue" :weight bold))))
+#+end_src
+
+While using a list with face properties as shown for CANCELED /should/
+work, this does not always seem to be the case. If necessary, define a
+special face and use that. A string is interpreted as a color. The variable
+~org-faces-easy-properties~ determines if that color is interpreted as a
+foreground or a background color.
+
+*** TODO dependencies
+ :PROPERTIES:
+ :DESCRIPTION: When one task needs to wait for others
+ :END:
+#+cindex: TODO dependencies
+#+cindex: dependencies, of TODO states
+#+vindex: org-enforce-todo-dependencies
+#+cindex: property, ORDERED
+
+The structure of Org files (hierarchy and lists) makes it easy to define TODO
+dependencies. Usually, a parent TODO task should not be marked DONE until
+all subtasks (defined as children tasks) are marked as DONE. And sometimes
+there is a logical sequence to a number of (sub)tasks, so that one task
+cannot be acted upon before all siblings above it are done. If you customize
+the variable ~org-enforce-todo-dependencies~, Org will block entries
+from changing state to DONE while they have children that are not DONE.
+Furthermore, if an entry has a property ~ORDERED~, each of its children
+will be blocked until all earlier siblings are marked DONE. Here is an
+example:
+
+#+begin_src org
+ ,* TODO Blocked until (two) is done
+ ,** DONE one
+ ,** TODO two
+
+ ,* Parent
+ :PROPERTIES:
+ :ORDERED: t
+ :END:
+ ,** TODO a
+ ,** TODO b, needs to wait for (a)
+ ,** TODO c, needs to wait for (a) and (b)
+#+end_src
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x o)}}}, ~org-toggle-ordered-property~ ::
+ #+kindex: C-c C-x o
+ #+vindex: org-track-ordered-property-with-tag
+ #+cindex: property, ORDERED
+
+ Toggle the ~ORDERED~ property of the current entry. A property is used
+ for this behavior because this should be local to the current entry, not
+ inherited like a tag. However, if you would like to /track/ the value of
+ this property with a tag for better visibility, customize the variable
+ ~org-track-ordered-property-with-tag~.
+- {{{kbd(C-u C-u C-u C-c C-t)}}} ::
+ #+kindex: C-u C-u C-u C-c C-t
+
+ Change TODO state, circumventing any state blocking.
+
+
+#+vindex: org-agenda-dim-blocked-tasks
+
+If you set the variable ~org-agenda-dim-blocked-tasks~, TODO entries
+that cannot be closed because of such dependencies will be shown in a dimmed
+font or even made invisible in agenda views (see [[Agenda views]]).
+
+#+cindex: checkboxes and TODO dependencies
+#+vindex: org-enforce-todo-dependencies
+
+You can also block changes of TODO states by looking at checkboxes
+(see [[Checkboxes]]). If you set the variable
+~org-enforce-todo-checkbox-dependencies~, an entry that has unchecked
+checkboxes will be blocked from switching to DONE.
+
+If you need more complex dependency structures, for example dependencies
+between entries in different trees or files, check out the contributed
+module {{{file(org-depend.el)}}}.
+
+{{{page}}}
+
+** Progress logging
+ :PROPERTIES:
+ :DESCRIPTION: Dates and notes for progress
+ :END:
+#+cindex: progress logging
+#+cindex: logging, of progress
+
+Org mode can automatically record a timestamp and possibly a note when
+you mark a TODO item as DONE, or even each time you change the state of
+a TODO item. This system is highly configurable, settings can be on a
+per-keyword basis and can be localized to a file or even a subtree. For
+information on how to clock working time for a task, see [[Clocking work time]].
+
+*** Closing items
+ :PROPERTIES:
+ :DESCRIPTION: When was this entry marked DONE?
+ :END:
+
+The most basic logging is to keep track of /when/ a certain TODO
+item was finished. This is achieved with:[fn:46]
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-log-done 'time)
+#+end_src
+
+{{{noindent}}} Then each time you turn an entry from a TODO (not-done)
+state into any of the DONE states, a line {{{samp(CLOSED: [timestamp])}}} will be inserted just after the headline. If you turn
+the entry back into a TODO item through further state cycling, that
+line will be removed again. If you want to record a note along with
+the timestamp, use:[fn:47]
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-log-done 'note)
+#+end_src
+
+{{{noindent}}} You will then be prompted for a note, and that note
+will be stored below the entry with a {{{samp(Closing Note)}}}
+heading.
+
+In the timeline (see [[Timeline for a single file]]) and in the agenda
+(see [[Weekly/daily agenda]]), you can then use the {{{kbd(l)}}} key to
+display the TODO items with a {{{samp(CLOSED)}}} timestamp on each
+day, giving you an overview of what has been done.
+
+*** Tracking TODO state changes
+ :PROPERTIES:
+ :DESCRIPTION: When did the status change?
+ :END:
+#+cindex: drawer, for state change recording
+#+vindex: org-log-states-order-reversed
+#+vindex: org-log-into-drawer
+#+cindex: property, LOG_INTO_DRAWER
+
+When TODO keywords are used as workflow states (see [[Workflow
+states]]), you might want to keep track of when a state change occurred
+and maybe take a note about this change. You can either record just a
+timestamp, or a time-stamped note for a change. These records will be
+inserted after the headline as an itemized list, newest first.[fn:48]
+When taking a lot of notes, you might want to get the notes out of the
+way into a drawer (see [[Drawers]]). Customize the variable
+~org-log-into-drawer~ to get this behavior---the recommended drawer
+for this is called ~LOGBOOK~.[fn:178] You can also overrule the setting
+of this variable for a subtree by setting a ~LOG_INTO_DRAWER~
+property.
+
+Since it is normally too much to record a note for every state, Org
+mode expects configuration on a per-keyword basis for this. This is
+achieved by adding special markers {{{samp(!)}}} (for a timestamp) or
+{{{samp(@)}}} (for a note with timestamp) in parentheses after each
+keyword. For example, with the setting:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(setq org-todo-keywords
+ '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
+#+end_src
+
+{{{noindent}}}
+#+vindex: org-log-done
+
+you not only define global TODO keywords and fast access keys, but
+also request that a time is recorded when the entry is set to
+DONE, and that a note is recorded when switching to WAIT or
+CANCELED.[fn:49] The setting for WAIT is even more special: the {{{samp(!)}}}
+after the slash means that in addition to the note taken when entering
+the state, a timestamp should be recorded when /leaving/ the WAIT
+state, if and only if the /target/ state does not configure logging
+for entering it. So it has no effect when switching from WAIT to DONE,
+because DONE is configured to record a timestamp only. But when
+switching from WAIT back to TODO, the {{{samp(/!)}}} in the WAIT
+setting now triggers a timestamp even though TODO has no logging
+configured.
+
+To record a timestamp without a note for TODO keywords configured with
+{{{samp(@)}}}, just type {{{kbd(C-c C-c)}}} to enter a blank note
+when prompted.
+
+You can use the exact same syntax for setting logging preferences local
+to a buffer:
+
+#+begin_example
+ ,#+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)
+#+end_example
+
+#+cindex: property, LOGGING
+
+In order to define logging settings that are local to a subtree or a
+single item, define a LOGGING property in this entry. Any non-empty
+LOGGING property resets all logging settings to nil. You may then turn
+on logging for this specific tree using STARTUP keywords like
+~lognotedone~ or ~logrepeat~, as well as adding state specific
+settings like ~TODO(!)~. For example:
+
+#+begin_example
+ ,* TODO Log each state with only a time
+ :PROPERTIES:
+ :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
+ :END:
+ ,* TODO Only log when switching to WAIT, and when repeating
+ :PROPERTIES:
+ :LOGGING: WAIT(@) logrepeat
+ :END:
+ ,* TODO No logging at all
+ :PROPERTIES:
+ :LOGGING: nil
+ :END:
+#+end_example
+
+*** Tracking your habits
+ :PROPERTIES:
+ :DESCRIPTION: How consistent have you been?
+ :END:
+ :LOGBOOK:
+ - State "DONE" from "DONE" [2013-01-07 Mon 14:10]
+ - State "DONE" from "" [2013-01-07 Mon 14:10]
+ :END:
+#+cindex: habits
+
+Org has the ability to track the consistency of a special category of TODOs,
+called "habits." A habit has the following properties:
+
+ 1. You have enabled the ~habits~ module by customizing the variable
+ ~org-modules~.
+
+ 2. The habit is a TODO item, with a TODO keyword representing an
+ open state.
+
+ 3. The property ~STYLE~ is set to the value ~habit~.
+
+ 4. The TODO has a scheduled date, usually with a ~.+~ style repeat
+ interval. A ~++~ style may be appropriate for habits with time
+ constraints, e.g., must be done on weekends, or a ~+~ style for
+ an unusual habit that can have a backlog, e.g., weekly reports.
+
+ 5. The TODO may also have minimum and maximum ranges specified by
+ using the syntax {{{samp(.+2d/3d)}}}, which says that you want to
+ do the task at least every three days, but at most every two
+ days.
+
+ 6. You must also have state logging for the ~DONE~ state enabled
+ (see [[Tracking TODO state changes]]), in order for historical
+ data to be represented in the consistency graph. If it is not
+ enabled it is not an error, but the consistency graphs will be
+ largely meaningless.
+
+
+To give you an idea of what the above rules look like in action, here's an
+actual habit with some history:
+
+#+begin_example
+ ,** TODO Shave
+ SCHEDULED: <2009-10-17 Sat .+2d/4d>
+ - State "DONE" from "TODO" [2009-10-15 Thu]
+ - State "DONE" from "TODO" [2009-10-12 Mon]
+ - State "DONE" from "TODO" [2009-10-10 Sat]
+ - State "DONE" from "TODO" [2009-10-04 Sun]
+ - State "DONE" from "TODO" [2009-10-02 Fri]
+ - State "DONE" from "TODO" [2009-09-29 Tue]
+ - State "DONE" from "TODO" [2009-09-25 Fri]
+ - State "DONE" from "TODO" [2009-09-19 Sat]
+ - State "DONE" from "TODO" [2009-09-16 Wed]
+ - State "DONE" from "TODO" [2009-09-12 Sat]
+ :PROPERTIES:
+ :STYLE: habit
+ :LAST_REPEAT: [2009-10-19 Mon 00:36]
+ :END:
+#+end_example
+
+What this habit says is: I want to shave at most every 2 days (given
+by the ~SCHEDULED~ date and repeat interval) and at least every 4
+days. If today is the 15th, then the habit first appears in the agenda
+on Oct 17, after the minimum of 2 days has elapsed, and will appear
+overdue on Oct 19, after four days have elapsed.
+
+What's really useful about habits is that they are displayed along
+with a consistency graph, to show how consistent you've been at
+getting that task done in the past. This graph shows every day that
+the task was done over the past three weeks, with colors for each day.
+The colors used are:
+
+#+attr_texinfo: :table-type table :indic @asis
+ - ~Blue~ :: If the task wasn't to be done yet on that day.
+ - ~Green~ :: If the task could have been done on that day.
+ - ~Yellow~ :: If the task was going to be overdue the next day.
+ - ~Red~ :: If the task was overdue on that day.
+
+
+In addition to coloring each day, the day is also marked with an
+asterisk if the task was actually done that day, and an exclamation
+mark to show where the current day falls in the graph.
+
+There are several configuration variables that can be used to change
+the way habits are displayed in the agenda.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - ~org-habit-graph-column~ :: The buffer column at which the
+ consistency graph should be drawn. This will overwrite any text
+ in that column, so it is a good idea to keep your habits'
+ titles brief and to the point.
+
+ - ~org-habit-preceding-days~ :: The amount of history, in days before
+ today, to appear in consistency graphs.
+
+ - ~org-habit-following-days~ :: The number of days after today that
+ will appear in consistency graphs.
+
+ - ~org-habit-show-habits-only-for-today~ :: If non-nil, only show
+ habits in today's agenda view. This is set to true by default.
+
+
+Lastly, pressing {{{kbd(K)}}} in the agenda buffer will cause habits
+to temporarily be disabled and they won't appear at all. Press
+{{{kbd(K)}}} again to bring them back. They are also subject to tag
+filtering, if you have habits which should only be done in certain
+contexts, for example.
+
+** FIXME Priorities
+ :PROPERTIES:
+ :DESCRIPTION: Some things are more important than others
+ :END:
+#+cindex: priorities
+
+If you use Org mode extensively, you may end up with enough TODO items that
+it starts to make sense to prioritize them. Prioritizing can be done by
+placing a /priority cookie/ into the headline of a TODO item, like this:
+
+#+begin_example
+ ,*** TODO [#A] Write letter to Sam Fortune
+#+end_example
+
+#+vindex: org-priority-faces
+
+{{{noindent}}} By default, Org mode supports three priorities: {{{samp(A)}}},
+{{{samp(B)}}}, and {{{samp(C)}}}. {{{samp(A)}}} is the highest
+priority. An entry without a cookie is treated just like priority
+{{{samp(B)}}}. Priorities make a difference only for sorting in the
+agenda (see [[Weekly/daily agenda]]); outside the agenda, they have no
+inherent meaning to Org mode. The cookies can be highlighted with
+special faces by customizing the variable ~org-priority-faces~.
+
+Priorities can be attached to any outline node; they do not need to be TODO
+items.
+
+#+attr_texinfo: :table-type table :indic @asis
+ - {{{kbd(C-c XXX)}}} ::
+ #+kindex: C-c ,
+ # #+kindex: @key{C-c ,}
+ # Preceding line won't export to pdf
+ #+findex: org-priority
+ # Should be C-c ,
+ Set the priority of the current headline (~org-priority~). The
+ command prompts for a priority character {{{samp(A)}}}, {{{samp(B)}}}
+ or {{{samp(C)}}}. When you press {{{key(SPC)}}}} instead, the priority
+ cookie is removed from the headline. The priorities can also be
+ changed ``remotely'' from the timeline and agenda buffer with the
+ {{{kbd(\,)}}} command (see [[Agenda commands]]).
+
+ - {{{kbdkey(S-,up)}}}, {{{kbdkey(S-,down)}}}, {{{command(org-priority-up)}}}, {{{command(org-priority-down)}}} ::
+ #+vindex: org-priority-start-cycle-with-default
+
+ Increase/decrease priority of current headline.[fn:50] Note
+ that these keys are also used to modify timestamps
+ (see [[Creating timestamps]]). See also [[Conflicts]], for a
+ discussion of the interaction with ~shift-selection-mode~.
+
+
+#+vindex: org-highest-priority
+#+vindex: org-lowest-priority
+#+vindex: org-default-priority
+
+You can change the range of allowed priorities by setting the
+variables ~org-highest-priority~, ~org-lowest-priority~, and
+~org-default-priority~. For an individual buffer, you may set these
+values (highest, lowest, default) like this (please make sure that the
+highest priority is earlier in the alphabet than the lowest priority):
+
+#+cindex: #+PRIORITIES
+
+#+begin_example
+ ,#+PRIORITIES: A C B
+#+end_example
+
+** Breaking down tasks
+ :PROPERTIES:
+ :DESCRIPTION: Splitting a task into manageable pieces
+ :END:
+#+cindex: tasks, breaking down
+#+cindex: statistics, for TODO items
+#+vindex: org-agenda-todo-list-sublevels
+
+It is often advisable to break down large tasks into smaller,
+manageable subtasks. You can do this by creating an outline tree below
+a TODO item, with detailed subtasks on the tree.[fn:51] To keep the
+overview over the fraction of subtasks that are already completed,
+insert either {{{samp([/])}}} or {{{samp([%])}}} anywhere in the
+headline. These cookies will be updated each time the TODO status of a
+child changes, or when pressing {{{kbd(C-c C-c)}}} on the cookie. For
+example:
+
+#+begin_example
+ ,* Organize Party [33%]
+ ,** TODO Call people [1/2]
+ ,*** TODO Peter
+ ,*** DONE Sarah
+ ,** TODO Buy food
+ ,** DONE Talk to neighbor
+#+end_example
+
+#+cindex: property, COOKIE_DATA
+
+If a heading has both checkboxes and TODO children below it, the
+meaning of the statistics cookie become ambiguous. Set the property
+~COOKIE_DATA~ to either {{{samp(checkbox)}}} or {{{samp(todo)}}} to
+resolve this issue.
+
+#+vindex: org-hierarchical-todo-statistics
+
+If you would like to have the statistics cookie count any TODO entries
+in the subtree (not just direct children), configure the variable
+~org-hierarchical-todo-statistics~. To do this for a single subtree,
+include the word {{{samp(recursive)}}} into the value of the
+~COOKIE_DATA~ property.
+
+#+begin_example
+ ,* Parent capturing statistics [2/20]
+ :PROPERTIES:
+ :COOKIE_DATA: todo recursive
+ :END:
+#+end_example
+
+If you would like a TODO entry to automatically change to DONE
+when all children are done, you can use the following setup:
+
+#+header: :exports code
+#+header: :eval no
+#+begin_src emacs-lisp
+(defun org-summary-todo (n-done n-not-done)
+ "Switch entry to DONE when all subentries are done, to TODO otherwise."
+ (let (org-log-done org-log-states) ; turn off logging
+ (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
+
+(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
+#+end_src
+
+Another possibility is the use of checkboxes to identify (a hierarchy
+of) a large number of subtasks (see [[Checkboxes]]).
+
+** Checkboxes
+ :PROPERTIES:
+ :DESCRIPTION: Tick-off lists
+ :END:
+
+#+cindex: checkboxes
+#+vindex: org-list-automatic-rules
+
+Every item in a plain list (see [[Plain lists]]) can be made into a
+checkbox by starting it with the string {{{samp([ ])}}}.[fn:52] This
+feature is similar to TODO items (see [[TODO items]]), but is more
+lightweight. Checkboxes are not included into the global TODO list, so
+they are often great to split a task into a number of simple steps. Or
+you can use them in a shopping list. To toggle a checkbox, use
+{{{kbd(C-c C-c)}}}, or use the mouse (thanks to Piotr Zielinski's
+{{{file(org-mouse.el)}}}).
+
+Here is an example of a checkbox list.
+
+#+begin_example
+ ,* TODO Organize party [2/4]
+ - [-] call people [1/3]
+ - [ ] Peter
+ - [X] Sarah
+ - [ ] Sam
+ - [X] order food
+ - [ ] think about what music to play
+ - [X] talk to the neighbors
+#+end_example
+
+Checkboxes work hierarchically, so if a checkbox item has children
+that are checkboxes, toggling one of the children checkboxes will make
+the parent checkbox reflect if none, some, or all of the children are
+checked.
+
+#+cindex: statistics, for checkboxes
+#+cindex: checkbox statistics
+#+cindex: property, COOKIE_DATA
+#+vindex: org-hierarchical-checkbox-statistics
+
+The {{{samp([2/4])}}} and {{{samp([1/3])}}} in the first and second
+line are cookies indicating how many checkboxes present in this entry
+have been checked off, and the total number of checkboxes present.
+This can give you an idea on how many checkboxes remain, even without
+opening a folded entry. The cookies can be placed into a headline or
+into (the first line of) a plain list item. Each cookie covers
+checkboxes of direct children structurally below the headline/item on
+which the cookie appears.[fn:53] You have to insert the cookie
+yourself by typing either {{{samp([/])}}} or {{{samp([%])}}}. With
+{{{samp([/])}}} you get an {{{samp(n out of m)}}} result, as in the
+examples above. With {{{samp([%])}}} you get information about the
+percentage of checkboxes checked (in the above example, this would be
+{{{samp([50%])}}} and {{{samp([33%])}}}, respectively). In a headline,
+a cookie can count either checkboxes below the heading or TODO states
+of children, and it will display whatever was changed last. Set the
+property ~COOKIE_DATA~ to either {{{samp(checkbox)}}} or
+{{{samp(todo)}}} to resolve this issue.
+
+#+cindex: blocking, of checkboxes
+#+cindex: checkbox blocking
+#+cindex: property, ORDERED
+
+If the current outline node has an ~ORDERED~ property, checkboxes must
+be checked off in sequence, and an error will be thrown if you try to
+check off a box while there are unchecked boxes above it.
+
+{{{noindent}}} The following commands work with checkboxes:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-c)}}}, ~org-toggle-checkbox~ :: Toggle checkbox status
+ or (with prefix arg) checkbox presence at point. With a single
+ prefix argument, add an empty checkbox or remove the current
+ one.[fn:54] With a double prefix argument, set it to
+ {{{samp([-])}}}, which is considered to be an intermediate state.
+
+- {{{kbd(C-c C-x C-b)}}}, ~org-toggle-checkbox~ :: Toggle checkbox
+ status or (with prefix arg) checkbox presence at point. With
+ double prefix argument, set it to {{{samp([-])}}}, which is
+ considered to be an intermediate state.
+
+ - If there is an active region, toggle the first checkbox in the region
+ and set all remaining boxes to the same status as the first. With a prefix
+ arg, add or remove the checkbox for all items in the region.
+
+ - If the cursor is in a headline, toggle checkboxes in the region
+ between this headline and the next (so /not/ the entire subtree).
+
+ - If there is no active region, just toggle the checkbox at point.
+
+
+- {{{kbdkey(M-S-,RET)}}}, ~org-insert-todo-heading~ :: Insert a new
+ item with a checkbox. This works only if the cursor is already in
+ a plain list item (see [[Plain lists]]).
+
+- {{{kbd(C-c C-x o)}}}, ~org-toggle-ordered-property~ ::
+ #+kindex: C-c C-x o
+ #+vindex: org-track-ordered-property-with-tag
+ #+cindex: property, ORDERED
+
+ Toggle the ~ORDERED~ property of the entry, to toggle if checkboxes
+ must be checked off in sequence. A property is used for this
+ behavior because this should be local to the current entry, not
+ inherited like a tag. However, if you would like to /track/ the
+ value of this property with a tag for better visibility,
+ customize the variable ~org-track-ordered-property-with-tag~.
+
+- {{{kbd(C-c #)}}}, ~org-update-statistics-cookies~ ::
+ #+kindex: C-c #
+
+ Update the statistics cookie in the current outline entry. When
+ called with a {{{kbd(C-u)}}} prefix, update the entire file.
+ Checkbox statistic cookies are updated automatically if you
+ toggle checkboxes with {{{kbd(C-c C-c)}}} and make new ones with
+ {{{kbdkey(M-S-,RET)}}}. TODO statistics cookies update when
+ changing TODO states. If you delete boxes/entries or add/change
+ them by hand, use this command to get things back into sync.
+
+* Tags
+ :PROPERTIES:
+ :DESCRIPTION: Tagging headlines and matching sets of tags
+ :END:
+#+cindex: tags
+#+cindex: headline tagging
+#+cindex: matching, tags
+#+cindex: sparse tree, tag based
+
+An excellent way to implement labels and contexts for
+cross-correlating information is to assign /tags/ to headlines. Org
+mode has extensive support for tags.
+
+#+vindex: org-tag-faces
+
+Every headline can contain a list of tags; they occur at the end of
+the headline. Tags are normal words containing letters, numbers,
+{{{samp(_)}}}, and {{{samp(@)}}}. Tags must be preceded and followed
+by a single colon, e.g., {{{samp(:work:)}}}. Several tags can be
+specified, as in {{{samp(:work:urgent:)}}}. Tags will by default be in
+bold face with the same color as the headline. You may specify special
+faces for specific tags using the variable ~org-tag-faces~, in much
+the same way as you can for TODO keywords (see [[Faces for TODO keywords]]).
+
+** Tag inheritance
+ :PROPERTIES:
+ :DESCRIPTION: Tags use the tree structure of an outline
+ :END:
+#+cindex: tag inheritance
+#+cindex: inheritance, of tags
+#+cindex: sublevels, inclusion into tags match
+
+/Tags/ make use of the hierarchical structure of outline trees. If a
+heading has a certain tag, all subheadings will inherit the tag as
+well. For example, in the list
+
+#+begin_example
+ ,* Meeting with the French group :work:
+ ,** Summary by Frank :boss:notes:
+ ,*** TODO Prepare slides for him :action:
+#+end_example
+
+{{{noindent}}} the final heading will have the tags
+{{{samp(:work:)}}}, {{{samp(:boss:)}}}, {{{samp(:notes:)}}}, and
+{{{samp(:action:)}}} even though the final heading is not explicitly
+marked with those tags. You can also set tags that all entries in a
+file should inherit just as if these tags were defined in a
+hypothetical level zero that surrounds the entire file. Use a line
+like this:[fn:55]
+
+#+cindex: #+FILETAGS
+#+begin_example
+ ,#+FILETAGS: :Peter:Boss:Secret:
+#+end_example
+
+#+vindex: org-use-tag-inheritance
+#+vindex: org-tags-exclude-from-inheritance
+
+{{{noindent}}} To limit tag inheritance to specific tags, or to turn
+it off entirely, use the variables ~org-use-tag-inheritance~ and
+~org-tags-exclude-from-inheritance~.
+
+#+vindex: org-tags-match-list-sublevels
+
+When a headline matches during a tags search while tag inheritance is
+turned on, all the sublevels in the same tree will (for a simple match
+form) match as well.[fn:56] The list of matches may then become very
+long. If you only want to see the first tags match in a subtree,
+configure the variable ~org-tags-match-list-sublevels~ (not
+recommended).
+
+** Setting tags
+ :PROPERTIES:
+ :DESCRIPTION: How to assign tags to a headline
+ :END:
+#+cindex: setting tags
+#+cindex: tags, setting
+#+kindex: M-@key{TAB}
+
+Tags can simply be typed into the buffer at the end of a headline.
+After a colon, {{{kbdkey(M-,TAB)}}} offers completion on tags. There is
+also a special command for inserting tags:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-q)}}}, ~org-set-tags-command~ ::
+ #+kindex: C-c C-q
+
+ #+cindex: completion, of tags
+ #+vindex: org-tags-column
+
+ Enter new tags for the current headline. Org mode will either offer
+ completion or a special single-key interface for setting tags, see
+ below. After pressing {{{key(RET)}}}, the tags will be inserted and aligned
+ to ~org-tags-column~. When called with a {{{kbd(C-u)}}} prefix, all
+ tags in the current buffer will be aligned to that column, just to make
+ things look nice. TAGS are automatically realigned after promotion,
+ demotion, and TODO state changes (see [[TODO basics]]).
+
+- {{{kbd(C-c C-c)}}}, ~org-set-tags-command~ ::
+ #+kindex: C-c C-c
+
+ When the cursor is in a headline, this does the same as {{{kbd(C-c C-q)}}}.
+
+
+#+vindex: org-tag-alist
+
+Org supports tag insertion based on a /list of tags/. By default this
+list is constructed dynamically, containing all tags currently used in
+the buffer. You may also globally specify a hard list of tags with the
+variable ~org-tag-alist~. Finally you can set the default tags for a
+given file with lines like
+
+#+cindex: #+TAGS
+#+begin_example
+ ,#+TAGS: @work @home @tennisclub
+ ,#+TAGS: laptop car pc sailboat
+#+end_example
+
+If you have globally defined your preferred set of tags using the
+variable ~org-tag-alist~, but would like to use a dynamic tag list
+in a specific file, add an empty TAGS option line to that file:
+
+#+begin_example
+ ,#+TAGS:
+#+end_example
+
+#+vindex: org-tag-persistent-alist
+
+If you have a preferred set of tags that you would like to use in
+every file, in addition to those defined on a per-file basis by TAGS
+option lines, then you may specify a list of tags with the variable
+~org-tag-persistent-alist~. You may turn this off on a per-file basis
+by adding a STARTUP option line to that file:
+
+#+begin_example
+ ,#+STARTUP: noptag
+#+end_example
+
+By default Org mode uses the standard minibuffer completion facilities
+for entering tags. However, it also implements another, quicker, tag
+selection method called /fast tag selection/. This allows you to
+select and deselect tags with just a single key press. For this to
+work well you should assign unique letters to most of your commonly
+used tags. You can do this globally by configuring the variable
+~org-tag-alist~ in your {{{file(.emacs)}}} file. For example, you may
+find the need to tag many items in different files with
+{{{samp(:@home:)}}}. In this case you can set something like:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
+#+end_src
+
+{{{noindent}}} If the tag is only relevant to the file you are working
+on, then you can instead set the TAGS option line as:
+
+#+begin_example
+ ,#+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p)
+#+end_example
+
+{{{noindent}}} The tags interface will show the available tags in a splash
+window. If you want to start a new line after a specific tag, insert
+~\n~ into the tag list, like this:
+
+#+begin_example
+ ,#+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p)
+#+end_example
+
+{{{noindent}}} or write them in two lines:
+
+#+begin_example
+ ,#+TAGS: @work(w) @home(h) @tennisclub(t)
+ ,#+TAGS: laptop(l) pc(p)
+#+end_example
+
+{{{noindent}}}
+You can also group together tags that are mutually exclusive by using
+braces, as in:
+
+#+begin_example
+ ,#+TAGS: { @work(w) @home(h) @tennisclub(t) } laptop(l) pc(p)
+#+end_example
+
+{{{noindent}}} you indicate that at most one of {{{samp(@work)}}},
+{{{samp(@home)}}}, and {{{samp(@tennisclub)}}} should be selected.
+Multiple such groups are allowed.
+
+{{{noindent}}} Don't forget to press {{{kbd(C-c C-c)}}} with the
+cursor in one of these lines to activate any changes.
+
+{{{noindent}}} To set these mutually exclusive groups in the variable
+~org-tags-alist~, you must use the dummy tags ~:startgroup~ and
+~:endgroup~ instead of the braces. Similarly, you can use ~:newline~
+to indicate a line break. The previous example would be set globally
+by the following configuration:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-tag-alist '((:startgroup . nil)
+ ("@@work" . ?w) ("@@home" . ?h)
+ ("@@tennisclub" . ?t)
+ (:endgroup . nil)
+ ("laptop" . ?l) ("pc" . ?p)))
+#+end_src
+
+If at least one tag has a selection key then pressing {{{kbd(C-c C-c)}}} will
+automatically present you with a special interface, listing inherited tags,
+the tags of the current headline, and a list of all valid tags with
+corresponding keys.[fn:57] In this interface, you can use the following
+keys:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(a-z...)}}} ::
+ #+kindex: a-z...
+
+ Pressing keys assigned to tags will add or remove them from the list of
+ tags in the current line. Selecting a tag in a group of mutually
+ exclusive tags will turn off any other tags from that group.
+
+- {{{key(TAB)}}} ::
+ #+kindex: @key{TAB}
+
+ Enter a tag in the minibuffer, even if the tag is not in the predefined
+ list. You will be able to complete on all tags present in the buffer.
+ You can also add several tags: just separate them with a comma.
+
+- {{{key(SPC)}}} ::
+ #+kindex: @key{SPC}
+
+ Clear all tags for this line.
+
+- {{{key(RET)}}} ::
+ #+kindex: @key{RET}
+
+ Accept the modified set.
+
+- C-g ::
+
+ Abort without installing changes.
+
+- q ::
+
+ If {{{kbd(q)}}} is not assigned to a tag, it aborts like {{{kbd(C-g)}}}.
+
+- ! ::
+
+ Turn off groups of mutually exclusive tags. Use this to (as an
+ exception) assign several tags from such a group.
+
+- C-c ::
+
+ Toggle auto-exit after the next change (see below).
+ If you are using expert mode, the first {{{kbd(C-c)}}} will display the
+ selection window.
+
+
+{{{noindent}}} This method lets you assign tags to a headline with
+very few keys. With the above setup, you could clear the current tags
+and set {{{samp(@home)}}}, {{{samp(laptop)}}} and {{{samp(pc)}}} tags
+with just the following keys: {{{ksksksk(C-c C-c,SPC,h l p,RET)}}}. Switching from {{{samp(@home)}}} to
+{{{samp(@work)}}} would be done with {{{kbdspckey(C-c C-c w,RET)}}} or
+alternatively with {{{kbd(C-c C-c C-c w)}}}. Adding the non-predefined
+tag {{{samp(Sarah)}}} could be done with
+{{{ksksksksk(C-c C-c,TAB,S a r a h,RET,RET)}}}.
+
+#+vindex: org-fast-tag-selection-single-key
+
+If you find that most of the time you need only a single key press to
+modify your list of tags, set the variable
+~org-fast-tag-selection-single-key~. Then you no longer have to press
+{{{key(RET)}}} to exit fast tag selection---it will immediately exit after
+the first change. If you then occasionally need more keys, press
+{{{kbd(C-c)}}} to turn off auto-exit for the current tag selection
+process (in effect: start selection with {{{kbd(C-c C-c C-c)}}}
+instead of {{{kbd(C-c C-c)}}}). If you set the variable to the value
+~expert~, the special window is not even shown for single-key tag
+selection, it comes up only when you press an extra {{{kbd(C-c)}}}.
+
+** Tag searches
+ :PROPERTIES:
+ :DESCRIPTION: Searching for combinations of tags
+ :END:
+#+cindex: tag searches
+#+cindex: searching for tags
+
+Once a system of tags has been set up, it can be used to collect related
+information into special lists.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c / m)}}}, ~C-c \~ ~org-match-sparse-tree~ ::
+
+ Create a sparse tree with all headlines matching a tags search. With a
+ {{{kbd(C-u)}}} prefix argument, ignore headlines that are not a TODO
+ line.
+
+- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
+ #+kindex: C-c a m
+
+ Create a global list of tag matches from all agenda files.
+ See [[Matching tags and properties]].
+
+- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
+ #+kindex: C-c a M
+ #+vindex: org-tags-match-list-sublevels
+
+ Create a global list of tag matches from all agenda files, but check
+ only TODO items and force checking subitems (see variable
+ ~org-tags-match-list-sublevels~).
+
+
+These commands all prompt for a match string which allows basic
+Boolean logic like {{{samp(+boss+urgent-project1)}}}, to find entries
+with tags {{{samp(boss)}}} and {{{samp(urgent)}}}, but not
+{{{samp(project1)}}}, or {{{samp(Kathy|Sally)}}} to find entries which
+are tagged, like {{{samp(Kathy)}}} or {{{samp(Sally)}}}. The full
+syntax of the search string is rich and allows also matching against
+TODO keywords, entry levels and properties. For a complete description
+with many examples, see [[Matching tags and properties]].
+
+* Properties and columns
+ :PROPERTIES:
+ :DESCRIPTION: Storing information about an entry
+ :ALT_TITLE: Properties and Columns
+ :END:
+#+cindex: properties
+
+A property is a key-value pair associated with an entry. Properties
+can be set so they are associated with a single entry, with every
+entry in a tree, or with every entry in an Org mode file.
+
+There are two main applications for properties in Org mode. First,
+properties are like tags, but with a value. Imagine maintaining a file
+where you document bugs and plan releases for a piece of software.
+Instead of using tags like ~:release_1:~, ~:release_2:~, you can use a
+property, say ~:Release:~, that in different subtrees has different
+values, such as ~1.0~ or ~2.0~. Second, you can use properties to
+implement (very basic) database capabilities in an Org buffer. Imagine
+keeping track of your music CDs, where properties could be things such
+as the album, artist, date of release, number of tracks, and so on.
+
+Properties can be conveniently edited and viewed in column view
+(see [[Column view]]).
+
+** Property syntax
+ :PROPERTIES:
+ :DESCRIPTION: How properties are spelled out
+ :END:
+#+cindex: property syntax
+#+cindex: drawer, for properties
+
+Properties are key-value pairs. When they are associated with a single
+entry or with a tree they need to be inserted into a special drawer
+(see [[Drawers]]) with the name ~PROPERTIES~. Each property is specified
+on a single line, with the key (surrounded by colons) first, and the
+value after it. Here is an example:
+
+#+begin_example
+ ,* CD collection
+ ,** Classic
+ ,*** Goldberg Variations
+ , :PROPERTIES:
+ , :Title: Goldberg Variations
+ , :Composer: J.S. Bach
+ , :Artist: Glen Gould
+ , :Publisher: Deutsche Grammophon
+ , :NDisks: 1
+ , :END:
+#+end_example
+
+Depending on the value of ~org-use-property-inheritance~, a property
+set this way will either be associated with a single entry, or the
+sub-tree defined by the entry, see [[Property inheritance]].
+
+You may define the allowed values for a particular property
+{{{samp(:Xyz:)}}} by setting a property {{{samp(:Xyz_ALL:)}}}. This
+special property is /inherited/, so if you set it in a level 1 entry,
+it will apply to the entire tree. When allowed values are defined,
+setting the corresponding property becomes easier and is less prone to
+typing errors. For the example with the CD collection, we can
+predefine publishers and the number of disks in a box like this:
+
+#+begin_example
+ ,* CD collection
+ , :PROPERTIES:
+ , :NDisks_ALL: 1 2 3 4
+ , :Publisher_ALL: "Deutsche Grammophon" Philips EMI
+ , :END:
+#+end_example
+
+If you want to set properties that can be inherited by any entry in a
+file, use a line like:
+
+#+cindex: property, _ALL
+#+cindex: #+PROPERTY
+#+begin_example
+ ,#+PROPERTY: NDisks_ALL 1 2 3 4
+#+end_example
+
+If you want to add to the value of an existing property, append a ~+~
+to the property name. The following results in the property ~var~
+having the value ``foo=1 bar=2''.
+
+#+cindex: property, +
+#+begin_example
+ ,#+PROPERTY: var foo=1
+ ,#+PROPERTY: var+ bar=2
+#+end_example
+
+It is also possible to add to the values of inherited properties. The
+following results in the ~genres~ property having the value ``Classic
+Baroque'' under the ~Goldberg Variations~ subtree.
+
+#+cindex: property, +
+#+begin_example
+ ,* CD collection
+ ,** Classic
+ , :PROPERTIES:
+ , :GENRES: Classic
+ , :END:
+ ,*** Goldberg Variations
+ , :PROPERTIES:
+ , :Title: Goldberg Variations
+ , :Composer: J.S. Bach
+ , :Artist: Glen Gould
+ , :Publisher: Deutsche Grammophon
+ , :NDisks: 1
+ , :GENRES+: Baroque
+ , :END:
+#+end_example
+Note that a property can only have one entry per Drawer.
+
+#+vindex: org-global-properties
+
+Property values set with the global variable ~org-global-properties~
+can be inherited by all entries in all Org files.
+
+{{{noindent}}}
+The following commands help to work with properties:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbdkey(M-,TAB)}}}, ~pcomplete~ ::
+ #+kindex: M-@key{TAB}
+
+ After an initial colon in a line, complete property keys. All keys
+ used in the current file will be offered as possible completions.
+
+- {{{kbd(C-c C-x p)}}}, ~org-set-property~ ::
+ #+kindex: C-c C-x p
+
+ Set a property. This prompts for a property name and a value. If
+ necessary, the property drawer is created as well.
+
+- C-u M-x org-insert-drawer RET ::
+ #+cindex: org-insert-drawer
+
+ Insert a property drawer into the current entry. The drawer will be
+ inserted early in the entry, but after the lines with planning
+ information like deadlines.
+
+- {{{kbd(C-c C-c)}}}, ~org-property-action~ ::
+ #+kindex: C-c C-c
+
+ With the cursor in a property drawer, this executes property commands.
+
+- {{{kbd(C-c C-c s)}}}, ~org-set-property~ ::
+ #+kindex: C-c C-c s
+
+ Set a property in the current entry. Both the property and the value
+ can be inserted using completion.
+
+- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}}, ~org-property-next-allowed-value~ ~org-property-previous-allowed-value~ ::
+ #+kindex: S-@key{right}
+
+ Switch property at point to the next/previous allowed value.
+
+- {{{kbd(C-c C-c d)}}}, ~org-delete-property~ ::
+ #+kindex: C-c C-c d
+
+ Remove a property from the current entry.
+
+- {{{kbd(C-c C-c D)}}}, ~org-delete-property-globally~ ::
+ #+kindex: C-c C-c D
+
+ Globally remove a property, from all entries in the current file.
+
+- {{{kbd(C-c C-c c)}}}, ~org-compute-property-at-point~ ::
+ #+kindex: C-c C-c c
+
+ Compute the property at point, using the operator and scope from the
+ nearest column format definition.
+
+** Special properties
+ :PROPERTIES:
+ :DESCRIPTION: Access to other Org mode features
+ :END:
+#+cindex: properties, special
+
+Special properties provide an alternative access method to Org mode
+features, like the TODO state or the priority of an entry, discussed
+in the previous chapters. This interface exists so that you can
+include these states in a column view (see [[Column view]]), or to use
+them in queries. The following property names are special and (except
+for ~:CATEGORY:~) should not be used as keys in the properties drawer:
+
+#+cindex: property, special, ID
+#+cindex: property, special, TODO
+#+cindex: property, special, TAGS
+#+cindex: property, special, ALLTAGS
+#+cindex: property, special, CATEGORY
+#+cindex: property, special, PRIORITY
+#+cindex: property, special, DEADLINE
+#+cindex: property, special, SCHEDULED
+#+cindex: property, special, CLOSED
+#+cindex: property, special, TIMESTAMP
+#+cindex: property, special, TIMESTAMP_IA
+#+cindex: property, special, CLOCKSUM
+#+cindex: property, special, CLOCKSUM_T
+#+cindex: property, special, BLOCKED
+# guessing that ITEM is needed in this area; also, should this list be sorted?
+#+cindex: property, special, ITEM
+#+cindex: property, special, FILE
+
+#+attr_texinfo: :columns 0.3 0.7
+| ID | A globally unique ID used for synchronization during |
+| | iCalendar or MobileOrg export. |
+| TODO | The TODO keyword of the entry. |
+| TAGS | The tags defined directly in the headline. |
+| ALLTAGS | All tags, including inherited ones. |
+| CATEGORY | The category of an entry. |
+| PRIORITY | The priority of the entry, a string with a single letter. |
+| DEADLINE | The deadline time string, without the angular brackets. |
+| SCHEDULED | The scheduling timestamp, without the angular brackets. |
+| CLOSED | When was this entry closed? |
+| TIMESTAMP | The first keyword-less timestamp in the entry. |
+| TIMESTAMP_IA | The first inactive timestamp in the entry. |
+| CLOCKSUM | The sum of CLOCK intervals in the subtree. ~org-clock-sum~ |
+| | must be run first to compute the values in the current buffer. |
+| CLOCKSUM_T | The sum of CLOCK intervals in the subtree for today. |
+| | ~org-clock-sum-today~ must be run first to compute the |
+| | values in the current buffer. |
+| BLOCKED | "t" if task is currently blocked by children or siblings |
+| ITEM | The headline of the entry. |
+| FILE | The filename the entry is located in. |
+
+** Property searches
+ :PROPERTIES:
+ :DESCRIPTION: Matching property values
+ :END:
+#+cindex: properties, searching
+#+cindex: searching, of properties
+
+To create sparse trees and special lists with selection based on properties,
+the same commands are used as for tag searches (see [[Tag searches]]).
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c / m)}}}, ~C-c \~ ~org-match-sparse-tree~ ::
+ #+kindex: C-c / m
+
+ Create a sparse tree with all matching entries. With a {{{kbd(C-u)}}}
+ prefix argument, ignore headlines that are not a TODO line.
+
+- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
+ #+kindex: C-c a m
+
+ Create a global list of tag/property matches from all agenda files.
+ See [[Matching tags and properties]].
+
+- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
+ #+kindex: C-c a M
+ #+vindex: org-tags-match-list-sublevels
+
+ Create a global list of tag matches from all agenda files, but check
+ only TODO items and force checking of subitems (see variable
+ ~org-tags-match-list-sublevels~).
+
+
+The syntax for the search string is described in [[Matching tags and
+properties]].
+
+There is also a special command for creating sparse trees based on a
+single property:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c / p)}}} ::
+ #+kindex: C-c / p
+
+ Create a sparse tree based on the value of a property. This first
+ prompts for the name of a property, and then for a value. A sparse
+ tree is created with all entries that define this property with the
+ given value. If you enclose the value in curly braces, it is
+ interpreted as a regular expression and matched against the property
+ values.
+
+** Property inheritance
+ :PROPERTIES:
+ :DESCRIPTION: Passing values down a tree
+ :END:
+#+cindex: properties, inheritance
+#+cindex: inheritance, of properties
+
+#+vindex: org-use-property-inheritance
+
+The outline structure of Org mode documents lends itself to an
+inheritance model of properties: if the parent in a tree has a certain
+property, the children can inherit this property. Org mode does not
+turn this on by default, because it can slow down property searches
+significantly and is often not needed. However, if you find
+inheritance useful, you can turn it on by setting the variable
+~org-use-property-inheritance~. It may be set to ~t~ to make all
+properties inherited from the parent, to a list of properties that
+should be inherited, or to a regular expression that matches inherited
+properties. If a property has the value {{{samp(nil)}}}, this is
+interpreted as an explicit undefine of the property, so that
+inheritance search will stop at this value and return ~nil~.
+
+Org mode has a few properties for which inheritance is hard-coded, at
+least for the special applications for which they are used:
+
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~COLUMNS~ ::
+ #+cindex: property, COLUMNS
+
+ The ~:COLUMNS:~ property defines the format of column view (see [[Column
+ view]]). It is inherited in the sense that the level where a ~:COLUMNS:~
+ property is defined is used as the starting point for a column view
+ table, independently of the location in the subtree from where columns
+ view is turned on.
+
+- ~CATEGORY~ ::
+ #+cindex: property, CATEGORY
+
+ For agenda view, a category set through a ~:CATEGORY:~ property
+ applies to the entire subtree.
+
+- ~ARCHIVE~ ::
+ #+cindex: property, ARCHIVE
+
+ For archiving, the ~:ARCHIVE:~ property may define the archive
+ location for the entire subtree (see [[Moving subtrees]]).
+
+- ~LOGGING~ ::
+ #+cindex: property, LOGGING
+
+ The LOGGING property may define logging settings for an entry or a
+ subtree (see [[Tracking TODO state changes]]).
+
+** Column view
+ :PROPERTIES:
+ :DESCRIPTION: Tabular viewing and editing
+ :END:
+
+A great way to view and edit properties in an outline tree is /column
+view/. In column view, each outline node is turned into a table row.
+Columns in this table provide access to properties of the entries. Org
+mode implements columns by overlaying a tabular structure over the
+headline of each item. While the headlines have been turned into a
+table row, you can still change the visibility of the outline tree.
+For example, you get a compact table by switching to CONTENTS view
+({{{kbdkey(S-,TAB)}}}} {{{kbdkey(S-,TAB)}}}), or simply {{{kbd(c)}}} while
+column view is active), but you can still open, read, and edit the
+entry below each headline. Or, you can switch to column view after
+executing a sparse tree command and in this way get a table only for
+the selected items. Column view also works in agenda buffers (see
+[[Agenda views]]) where queries have collected selected items, possibly
+from a number of files.
+
+*** Defining columns
+ :PROPERTIES:
+ :DESCRIPTION: The COLUMNS format property
+ :END:
+#+cindex: column view, for properties
+#+cindex: properties, column view
+
+Setting up a column view first requires defining the columns. This is
+done by defining a column format line.
+
+**** Scope of column definitions
+ :PROPERTIES:
+ :DESCRIPTION: Where defined, where valid?
+ :END:
+
+To define a column format for an entire file, use a line like:
+
+#+cindex: #+COLUMNS
+#+begin_example
+ ,#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
+#+end_example
+
+To specify a format that only applies to a specific tree, add a
+~:COLUMNS:~ property to the top node of that tree, for example:
+
+#+begin_example
+ ,** Top node for columns view
+ , :PROPERTIES:
+ , :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
+ , :END:
+#+end_example
+
+If a ~:COLUMNS:~ property is present in an entry, it defines columns
+for the entry itself, and for the entire subtree below it. Since the
+column definition is part of the hierarchical structure of the
+document, you can define columns on level 1 that are general enough
+for all sublevels, and more specific columns further down, when you
+edit a deeper part of the tree.
+
+**** Column attributes
+ :PROPERTIES:
+ :DESCRIPTION: Appearance and content of a column
+ :END:
+A column definition sets the attributes of a column. The general
+definition looks like this:
+
+ %[{{{var(width)}}}]{{{var(property)}}}[({{{var(title)}}})][{{{{var(summary-type)}}}}]
+
+{{{noindent}}} Except for the percent sign and the property name, all
+items are optional. The individual parts have the following meaning:
+
+#+attr_texinfo: :columns 0.2 0.8
+| Variable | Meaning |
+|-------------------------+--------------------------------------------------------------|
+| {{{var(width)}}} | An integer specifying the width of the column in characters. |
+| | If omitted, the width will be determined automatically. |
+| {{{var(property)}}} | The property that should be edited in this column. |
+| | Special properties representing meta data are allowed here |
+| | as well (see [[Special properties]]) |
+| {{{var(title)}}} | The header text for the column. If omitted, the property |
+| | name is used. |
+| {{{var(summary-type)}}} | The summary type. If specified, the column values for |
+| | parent nodes are computed from the children. |
+
+{{{noindent}}} Supported summary types are:
+
+#+attr_texinfo: :columns 0.2 0.8
+| Type | Meaning |
+|----------+-----------------------------------------------------------------------|
+| ~+~ | Sum numbers in this column. |
+| ~+;%.1f~ | Like ~+~, but format result with {{{samp(%.1f)}}}. |
+| ~$~ | Currency, short for {{{samp(+;%.2f)}}}. |
+| ~:~ | Sum times, HH:MM, plain numbers are hours. |
+| ~X~ | Checkbox status, {{{samp([X])}}} if all children are {{{samp([X])}}}. |
+| ~X/~ | Checkbox status, {{{samp([n/m])}}}. |
+| ~X%~ | Checkbox status, {{{samp([n%])}}}. |
+| ~min~ | Smallest number in column. |
+| ~max~ | Largest number. |
+| ~mean~ | Arithmetic mean of numbers. |
+| ~:min~ | Smallest time value in column. |
+| ~:max~ | Largest time value. |
+| ~:mean~ | Arithmetic mean of time values. |
+| ~@min~ | Minimum age (in days/hours/mins/seconds). |
+| ~@max~ | Maximum age (in days/hours/mins/seconds). |
+| ~@mean~ | Arithmetic mean of ages (in days/hours/mins/seconds). |
+| ~est+~ | Add low-high estimates. |
+
+
+{{{noindent}}} Be aware that you can only have one summary type for
+any property you include. Subsequent columns referencing the same
+property will all display the same summary information.
+
+The ~est+~ summary type requires further explanation. It is used for
+combining estimates, expressed as low-high ranges. For example,
+instead of estimating a particular task will take 5 days, you might
+estimate it as 5-6 days if you're fairly confident you know how much
+work is required, or 1-10 days if you don't really know what needs to
+be done. Both ranges average at 5.5 days, but the first represents a
+more predictable delivery.
+
+When combining a set of such estimates, simply adding the lows and
+highs produces an unrealistically wide result. Instead, ~est+~ adds
+the statistical mean and variance of the sub-tasks, generating a final
+estimate from the sum. For example, suppose you had ten tasks, each of
+which was estimated at 0.5 to 2 days of work. Straight addition
+produces an estimate of 5 to 20 days, representing what to expect if
+everything goes either extremely well or extremely poorly. In
+contrast, ~est+~ estimates the full job more realistically, at 10-15
+days.
+
+Here is an example for a complete columns definition, along with allowed
+values.[fn:58]
+
+#+begin_example
+ :COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \
+ %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
+ :Owner_ALL: Tammy Mark Karl Lisa Don
+ :Status_ALL: "In progress" "Not started yet" "Finished" ""
+ :Approved_ALL: "[ ]" "[X]"
+#+end_example
+
+{{{noindent}}} The first column, {{{samp(%25ITEM)}}}, means the first
+25 characters of the item itself, i.e., of the headline. You probably
+always should start the column definition with the {{{samp(ITEM)}}}
+specifier. The other specifiers create columns {{{samp(Owner)}}} with
+a list of names as allowed values, for {{{samp(Status)}}} with four
+different possible values, and for a checkbox field
+{{{samp(Approved)}}}. When no width is given after the {{{samp(%)}}}
+character, the column will be exactly as wide as it needs to be in
+order to fully display all values. The {{{samp(Approved)}}} column
+does have a modified title ({{{samp(Approved?)}}}, with a question
+mark). Summaries will be created for the {{{samp(Time_Estimate)}}}
+column by adding time duration expressions like HH:MM, and for the
+{{{samp(Approved)}}} column, by providing an {{{samp([X])}}} status if
+all children have been checked. The {{{samp(CLOCKSUM)}}} and
+{{{samp(CLOCKSUM_T)}}} columns are special, they lists the sums of
+CLOCK intervals in the subtree, either for all clocks or just for
+today.
+
+*** Using column view
+ :PROPERTIES:
+ :DESCRIPTION: How to create and use column view
+ :END:
+
+The following commands turn column view on or off:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-c)}}}, ~org-columns~ ::
+ #+kindex: C-c C-x C-c
+ #+vindex: org-columns-default-format
+
+ Turn on column view. If the cursor is before the first headline in the
+ file, column view is turned on for the entire file, using the
+ ~#+COLUMNS~ definition. If the cursor is somewhere inside the outline,
+ this command searches the hierarchy, up from point, for a ~:COLUMNS:~
+ property that defines a format. When one is found, the column view
+ table is established for the tree starting at the entry that contains
+ the ~:COLUMNS:~ property. If no such property is found, the format is
+ taken from the ~#+COLUMNS~ line or from the variable
+ ~org-columns-default-format~, and column view is established for the
+ current entry and its subtree.
+
+- {{{kbd(r)}}}, ~org-columns-redo~ ::
+ #+kindex: r
+
+ Recreate the column view, to include recent changes made in the
+ buffer.
+
+- {{{kbd(g)}}}, ~org-columns-redo~ ::
+ #+kindex: g
+
+ Same as {{{kbd(r)}}}.
+
+- {{{kbd(q)}}}, ~org-columns-quit~ ::
+ #+kindex: q
+
+ Exit column view.
+
+The following commands let you edit information in column view:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{key(left)}}} {{{key(right)}}} {{{key(up)}}} {{{key(down)}}} ::
+
+ Move through the column view from field to field.
+
+- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}} ::
+ #+kindex: S-@key{left}
+ #+kindex: S-@key{right}
+
+ Switch to the next/previous allowed value of the field. For this, you
+ have to have specified allowed values for a property.
+
+- {{{kbd(1..9\,0)}}} ::
+ #+kindex: 1..9,0
+
+ Directly select the Nth allowed value, {{{kbd(0)}}} selects the 10th
+ value.
+
+- {{{kbd(n)}}} {{{kbd(p)}}}, ~org-columns-next-allowed-value~ ~org-columns-previous-allowed-value~ ::
+ #+kindex: n
+
+ Same as {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}
+
+- {{{kbd(e)}}}, ~org-columns-edit-value~ ::
+ #+kindex: e
+
+ Edit the property at point. For the special properties, this will
+ invoke the same interface that you normally use to change that
+ property. For example, when editing a TAGS property, the tag
+ completion or fast selection interface will pop up.
+
+- {{{kbd(C-c C-c)}}}, ~org-columns-set-tags-or-toggle~ ::
+ #+kindex: C-c C-c
+
+ When there is a checkbox at point, toggle it.
+
+- {{{kbd(v)}}}, ~org-columns-show-value~ ::
+ #+kindex: v
+
+ View the full value of this property. This is useful if the width of
+ the column is smaller than that of the value.
+
+- {{{kbd(a)}}}, ~org-columns-edit-allowed~ ::
+ #+kindex: a
+
+ Edit the list of allowed values for this property. If the list is found
+ in the hierarchy, the modified values is stored there. If no list is
+ found, the new value is stored in the first entry that is part of the
+ current column view.
+
+
+The following commands modify column view on-the-fly:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(<)}}} {{{kbd(>)}}}, ~org-columns-narrow~ ~org-columns-widen~ ::
+ #+kindex: <
+
+ Make the column narrower/wider by one character.
+
+- {{{kbdkey(S-M-,right)}}}, ~org-columns-new~ ::
+ #+kindex: S-M-@key{right}
+
+ Insert a new column, to the left of the current column.
+
+- {{{kbdkey(S-M-,left)}}}, ~org-columns-delete~ ::
+ #+kindex: S-M-@key{left}
+
+ Delete the current column.
+
+*** Capturing column view
+ :PROPERTIES:
+ :DESCRIPTION: A dynamic block for column view
+ :END:
+
+Since column view is just an overlay over a buffer, it cannot be
+exported or printed directly. If you want to capture a column view,
+use a ~columnview~ dynamic block (see [[Dynamic blocks]]). The frame of
+this block looks like this:
+
+#+cindex: #+BEGIN, columnview
+#+begin_example
+ ,* The column view
+ ,#+BEGIN: columnview :hlines 1 :id "label"
+
+ ,#+END:
+#+end_example
+
+{{{noindent}}} This dynamic block has the following parameters:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:id~ ::
+
+ This is the most important parameter. Column view is a feature that is
+ often localized to a certain (sub)tree, and the capture block might be
+ at a different location in the file. To identify the tree whose view
+ to capture, you can use 4 values:
+
+ #+cindex: property, ID
+ #+attr_texinfo: :columns 0.35 0.65
+ | Value | Meaning |
+ |---------------------+---------------------------------------------------------------|
+ | local | Use the tree in which the capture block is located. |
+ | global | Make a global view, including all headings in the file. |
+ | =file:PATH-TO-FILE= | Run column view at the top of this file. |
+ | ID | Call column view in the tree that has an ~:ID:~ |
+ | | property with the value /label/. You can use |
+ | | {{{kbd(M-x org-id-copy)}}} to create a globally unique ID for |
+ | | the current entry and copy it to the kill-ring. |
+
+ - local ::
+
+ Use the tree in which the capture block is located.
+
+ - global ::
+
+ Make a global view, including all headings in the file.
+
+ - =file:PATH-TO-FILE= ::
+
+ Run column view at the top of this file.
+
+ - ID ::
+
+ Call column view in the tree that has an ~:ID:~ property with the
+ value /label/. You can use {{{kbd(M-x org-id-copy)}}} to
+ create a globally unique ID for the current entry and copy
+ it to the kill-ring.
+
+- ~:hlines~ ::
+
+ When ~t~, insert an hline after every line. When a number ~N~,
+ insert an hline before each headline with level ~<=~
+ {{{var(N)}}}.
+
+- ~:vlines~ ::
+
+ When set to ~t~, force column groups to get vertical lines.
+
+- ~:maxlevel~ ::
+
+ When set to a number, don't capture entries below this level.
+
+- ~:skip-empty-rows~ ::
+
+ When set to ~t~, skip rows where the only non-empty specifier of the
+ column view is ~ITEM~.
+
+
+
+{{{noindent}}} The following commands insert or update the dynamic
+block:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x i)}}}, ~org-insert-columns-dblock~ ::
+ #+kindex: C-c C-x i
+
+ Insert a dynamic block capturing a column view. You will be prompted
+ for the scope or ID of the view.
+
+- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ ::
+ #+kindex: C-c C-c
+
+ Update dynamic block at point. The cursor needs to be in the ~#+BEGIN~
+ line of the dynamic block.
+
+- {{{kbd(C-u C-c C-x C-u)}}}, ~org-update-all-dblocks~ ::
+ #+kindex: C-u C-c C-x C-u
+
+ Update all dynamic blocks (see [[Dynamic blocks]]). This is useful if you
+ have several clock table blocks, column-capturing blocks or other
+ dynamic blocks in a buffer.
+
+
+You can add formulas to the column view table and you may add plotting
+instructions in front of the table---these will survive an update of the
+block. If there is a ~#+TBLFM:~ after the table, the table will
+actually be recalculated automatically after an update.
+
+An alternative way to capture and process property values into a table
+is provided by Eric Schulte's {{{file(org-collector.el)}}} which is a
+contributed package.[fn:59] It provides a general API to collect
+properties from entries in a certain scope, and arbitrary Lisp
+expressions to process these values before inserting them into a table
+or a dynamic block.
+
+** Property API
+ :PROPERTIES:
+ :DESCRIPTION: Properties for Lisp programmers
+ :END:
+#+cindex: properties, API
+#+cindex: API, for properties
+
+There is a full API for accessing and changing properties. This API
+can be used by Emacs Lisp programs to work with properties and to
+implement features based on them. For more information see [[Using the
+property API]].
+
+* Dates and times
+ :PROPERTIES:
+ :DESCRIPTION: Making items useful for planning
+ :ALT_TITLE: Dates and Times
+ :END:
+#+cindex: dates
+#+cindex: times
+#+cindex: timestamp
+#+cindex: date stamp
+
+To assist project planning, TODO items can be labeled with a date and/or
+a time. The specially formatted string carrying the date and time
+information is called a /timestamp/ in Org mode. This may be a
+little confusing because timestamp is often used as indicating when
+something was created or last changed. However, in Org mode this term
+is used in a much wider sense.
+
+** Timestamps
+ :PROPERTIES:
+ :DESCRIPTION: Assigning a time to a tree entry
+ :TITLE: Timestamps, deadlines, and scheduling
+ :END:
+#+cindex: timestamps
+#+cindex: ranges, time
+#+cindex: date stamps
+#+cindex: deadlines
+#+cindex: scheduling
+
+A timestamp is a specification of a date (possibly with a time or a
+range of times) in a special format, either ~<2003-09-16 Tue>~ or
+~<2003-09-16 Tue 09:39>~ or ~<2003-09-16 Tue 12:00-12:30>~.[fn:60] A
+timestamp can appear anywhere in the headline or body of an Org tree
+entry. Its presence causes entries to be shown on specific dates in
+the agenda (see [[Weekly/daily agenda]]). We distinguish:
+
+#+attr_texinfo: :table-type table :indic @asis
+- Plain timestamp; Event; Appointment ::
+ #+cindex: timestamp
+ #+cindex: appointment
+
+ A simple timestamp just assigns a date/time to an item. This is just
+ like writing down an appointment or event in a paper agenda. In the
+ timeline and agenda displays, the headline of an entry associated with
+ a plain timestamp will be shown exactly on that date.
+
+ #+begin_example
+ ,* Meet Peter at the movies
+ <2006-11-01 Wed 19:15>
+ ,* Discussion on climate change
+ <2006-11-02 Thu 20:00-22:00>
+ #+end_example
+
+- Timestamp with repeater interval ::
+ #+cindex: timestamp, with repeater interval
+
+ A timestamp may contain a /repeater interval/, indicating that it
+ applies not only on the given date, but again and again after a
+ certain interval of N days (d), weeks (w), months (m), or years (y).
+ The following will show up in the agenda every Wednesday:
+
+ #+begin_example
+ ,* Pick up Sam at school
+ <2007-05-16 Wed 12:30 +1w>
+ #+end_example
+
+- Diary-style sexp entries ::
+
+ For more complex date specifications, Org mode supports using the
+ special sexp diary entries implemented in the Emacs calendar/diary
+ package.[fn:61] For example, with optional time:
+
+ #+begin_example
+ ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
+ <%%(org-float t 4 2)>
+ #+end_example
+
+- Time/Date range ::
+ #+cindex: timerange
+ #+cindex: date range
+
+ Two timestamps connected by {{{samp(--)}}} denote a range. The headline
+ will be shown on the first and last day of the range, and on any dates
+ that are displayed and fall in the range. Here is an example:
+
+ #+begin_example
+ ,** Meeting in Amsterdam
+ <2004-08-23 Mon>--<2004-08-26 Thu>
+ #+end_example
+
+- Inactive timestamp ::
+ #+cindex: timestamp, inactive
+ #+cindex: inactive timestamp
+
+ Just like a plain timestamp, but with square brackets instead of
+ angular ones. These timestamps are inactive in the sense that they do
+ /not/ trigger an entry to show up in the agenda.
+
+ #+begin_example
+ ,* Gillian comes late for the fifth time
+ [2006-11-01 Wed]
+ #+end_example
+
+** Creating timestamps
+ :PROPERTIES:
+ :DESCRIPTION: Commands to insert timestamps
+ :END:
+For Org mode to recognize timestamps, they need to be in the specific
+format. All commands listed below produce timestamps in the correct
+format.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c .)}}}, ~org-time-stamp~ ::
+ #+kindex: C-c .
+
+ Prompt for a date and insert a corresponding timestamp. When the
+ cursor is at an existing timestamp in the buffer, the command is used
+ to modify this timestamp instead of inserting a new one. When this
+ command is used twice in succession, a time range is inserted.
+
+- {{{kbd(C-c !)}}}, ~org-time-stamp-inactive~ ::
+ #+kindex: C-c !
+
+ Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that will not
+ cause an agenda entry.
+
+- {{{kbd(C-u C-c .)}}} {{{kbd(C-u C-c !)}}} ::
+ #+kindex: C-u C-c .
+ #+kindex: C-u C-c .
+ #+kindex: C-u C-c !
+ #+vindex: org-time-stamp-rounding-minutes
+
+ Like {{{kbd(C-c .)}}} and {{{kbd(C-c !)}}}, but use the alternative
+ format which contains date and time. The default time can be rounded
+ to multiples of 5 minutes, see the option
+ ~org-time-stamp-rounding-minutes~.
+
+- {{{kbd(C-c C-c)}}} ::
+ #+kindex: C-c C-c
+
+ Normalize timestamp, insert/fix day name if missing or wrong.
+
+- {{{kbd(C-c <)}}}, ~org-date-from-calendar~ ::
+ #+kindex: C-c <
+
+ Insert a timestamp corresponding to the cursor date in the Calendar.
+
+- {{{kbd(C-c >)}}}, ~org-goto-calendar~ ::
+ #+kindex: C-c >
+
+ Access the Emacs calendar for the current date. If there is a
+ timestamp in the current line, go to the corresponding date instead.
+
+- {{{kbd(C-c C-o)}}}, ~org-open-at-point~ ::
+ #+kindex: C-c C-o
+
+ Access the agenda for the date given by the timestamp or -range at
+ point (see [[Weekly/daily agenda]]).
+
+- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}, ~org-timestamp-down-day~ ~org-timestamp-up-day~ ::
+ #+kindex: S-@key{left}
+
+ Change date at cursor by one day. These key bindings conflict with
+ shift-selection and related modes (see [[Conflicts]]).
+
+- {{{kbdkey(S-,up)}}} {{{kbdkey(S-,down)}}}, ~org-timestamp-up~ ~org-timestamp-down-down~ ::
+ #+kindex: S-@key{up}
+
+ Change the item under the cursor in a timestamp. The cursor can be on
+ a year, month, day, hour or minute. When the timestamp contains a time
+ range like {{{samp(15:30-16:30)}}}, modifying the first time will also
+ shift the second, shifting the time block with constant length. To
+ change the length, modify the second time. Note that if the cursor is
+ in a headline and not at a timestamp, these same keys modify the
+ priority of an item. (see [[Priorities]]). The key bindings also conflict
+ with shift-selection and related modes (see [[Conflicts]]).
+
+- {{{kbd(C-c C-y)}}}, ~org-evaluate-time-range~ ::
+ #+kindex: C-c C-y
+ #+cindex: evaluate time range
+
+ Evaluate a time range by computing the difference between start and
+ end. With a prefix argument, insert result after the time range (in a
+ table: into the following column).
+
+*** The date/time prompt
+ :PROPERTIES:
+ :DESCRIPTION: How Org mode helps you enter dates and times
+ :END:
+#+cindex: date, reading in minibuffer
+#+cindex: time, reading in minibuffer
+
+#+vindex: org-read-date-prefer-future
+
+When Org mode prompts for a date/time, the default is shown in default
+date/time format, and the prompt therefore seems to ask for a specific
+format. But it will in fact accept date/time information in a variety
+of formats. Generally, the information should start at the beginning
+of the string. Org mode will find whatever information is in there and
+derive anything you have not specified from the /default date and
+time/. The default is usually the current date and time, but when
+modifying an existing timestamp, or when entering the second stamp of
+a range, it is taken from the stamp in the buffer. When filling in
+information, Org mode assumes that most of the time you will want to
+enter a date in the future: if you omit the month/year and the given
+day/month is /before/ today, it will assume that you mean a future
+date.[fn:62] If the date has been automatically shifted into the
+future, the time prompt will show this with {{{samp((=>F))}}}.
+
+For example, let's assume that today is *June 13, 2006*. Here is how
+various inputs will be interpreted, the items filled in by Org mode
+are in *bold*.
+
+| Input | Interpretation |
+|--------------+------------------------------------------------------|
+| 3-2-5 | {{{result}}} 2003-02-05 |
+| 2/5/3 | {{{result}}} 2003-02-05 |
+| 14 | {{{result}}} *2006*-*06*-14 |
+| 12 | {{{result}}} *2006*-*07*-12 |
+| 2/5 | {{{result}}} *2007*-02-05 |
+| Fri | {{{result}}} nearest Friday (default date or later) |
+| sep 15 | {{{result}}} *2006*-09-15 |
+| feb 15 | {{{result}}} *2007*-02-15 |
+| sep 12 9 | {{{result}}} 2009-09-12 |
+| 12:45 | {{{result}}} *2006*-*06*-*13* 12:45 |
+| 22 sept 0:34 | {{{result}}} *2006*-09-22 0:34 |
+| w4 | {{{result}}} ISO week for of the current year *2006* |
+| 2012 w4 fri | {{{result}}} Friday of ISO week 4 in 2012 |
+| 2012-w04-5 | {{{result}}} Same as above |
+
+
+Furthermore you can specify a relative date by giving, as the /first/
+thing in the input: a plus/minus sign, a number and a letter ([dwmy])
+to indicate change in days, weeks, months, or years. With a single
+plus or minus, the date is always relative to today. With a double
+plus or minus, it is relative to the default date. If instead of a
+single letter, you use the abbreviation of day name, the date will be
+the Nth such day, e.g.:
+
+| Input | Interpretation |
+|-------+------------------------------------------|
+| +0 | {{{result}}} today |
+| . | {{{result}}} today |
+| +4d | {{{result}}} four days from today |
+| +4 | {{{result}}} same as +4d |
+| +2w | {{{result}}} two weeks from today |
+| ++5 | {{{result}}} five days from default date |
+| +2tue | {{{result}}} second Tuesday from now |
+
+
+#+vindex: parse-time-months
+#+vindex: parse-time-weekdays
+
+The function understands English month and weekday abbreviations. If
+you want to use unabbreviated names and/or other languages, configure
+the variables ~parse-time-months~ and ~parse-time-weekdays~.
+
+#+vindex: org-read-date-force-compatible-dates
+
+Not all dates can be represented in a given Emacs implementation. By
+default Org mode forces dates into the compatibility range 1970--2037
+which works on all Emacs implementations. If you want to use dates
+outside of this range, read the docstring of the variable
+~org-read-date-force-compatible-dates~.
+
+You can specify a time range by giving start and end times or by
+giving a start time and a duration (in HH:MM format). Use one or two
+dash(es) as the separator in the former case and use '+' as the
+separator in the latter case, e.g.:
+
+| Range | Result |
+|--------------+----------------------------|
+| 11am-1:15pm | {{{result}}} 11:00-13:15 |
+| 11am--1:15pm | {{{result}}} same as above |
+| 11am+2:15 | {{{result}}} same as above |
+
+#+cindex: calendar, for selecting date
+#+vindex: org-popup-calendar-for-date-prompt
+
+Parallel to the minibuffer prompt, a calendar is popped up.[fn:63]
+When you exit the date prompt, either by clicking on a date in the
+calendar, or by pressing {{{key(RET)}}}, the date selected in the
+calendar will be combined with the information entered at the prompt.
+You can control the calendar fully from the minibuffer:
+
+#+kindex: <
+#+kindex: >
+#+kindex: M-v
+#+kindex: C-v
+#+kindex: mouse-1
+#+kindex: S-@key{right}
+#+kindex: S-@key{left}
+#+kindex: S-@key{down}
+#+kindex: S-@key{up}
+#+kindex: M-S-@key{right}
+#+kindex: M-S-@key{left}
+#+kindex: @key{RET}
+
+#+attr_texinfo: :columns 0.3 0.7
+| Key binding | Meaning |
+|---------------------------+----------------------------------------|
+| {{{key(RET)}}} | Choose date at cursor in calendar. |
+| {{{key(mouse-1)}}} | Select date by clicking on it. |
+| {{{kbdkey(S-,right)}}} | One day forward. |
+| {{{kbdkey(S-,left)}}} | One day backward. |
+| {{{kbdkey(S-,down)}}} | One week forward. |
+| {{{kbdkey(S-,up)}}} | One week backward. |
+| {{{kbdkey(M-S-,right)}}} | One month forward. |
+| {{{kbdkey(M-S-,left)}}} | One month backward. |
+| {{{kbd(>)}}} | Scroll calendar forward by one month. |
+| {{{kbd(<)}}} | Scroll calendar backward by one month. |
+| {{{kbd(M-v)}}} | Scroll calendar forward by 3 months. |
+| {{{kbd(C-v)}}} | Scroll calendar backward by 3 months. |
+
+
+#+vindex: org-read-date-display-live
+
+The actions of the date/time prompt may seem complex, but I assure you they
+will grow on you, and you will start getting annoyed by pretty much any other
+way of entering a date/time out there. To help you understand what is going
+on, the current interpretation of your input will be displayed live in the
+minibuffer.[fn:64]
+
+*** Custom time format
+ :PROPERTIES:
+ :DESCRIPTION: Making dates look different
+ :END:
+#+cindex: custom date/time format
+#+cindex: time format, custom
+#+cindex: date format, custom
+
+#+vindex: org-display-custom-times
+#+vindex: org-time-stamp-custom-formats
+
+Org mode uses the standard ISO notation for dates and times as it is
+defined in ISO 8601. If you cannot get used to this and require
+another representation of date and time to keep you happy, you can get
+it by customizing the variables ~org-display-custom-times~ and
+~org-time-stamp-custom-formats~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-t)}}}, ~org-toggle-time-stamp-overlays~ ::
+ #+kindex: C-c C-x C-t
+
+ Toggle the display of custom formats for dates and times.
+
+
+{{{noindent}}}
+Org mode needs the default format for scanning, so the custom date/time
+format does not /replace/ the default format---instead it is put
+/over/ the default format using text properties. This has the
+following consequences:
+
+
+- You cannot place the cursor onto a timestamp anymore, only before or
+ after.
+
+- The {{{kbdkey(S-,up)}}} {{{kbdkey(S-,down)}}} keys can no longer be
+ used to adjust each component of a timestamp. If the cursor is at
+ the beginning of the stamp, {{{kbdkey(S-,up)}}}
+ {{{kbdkey(S-,down)}}} will change the stamp by one day, just like
+ {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}. At the end of the
+ stamp, the time will be changed by one minute.
+
+- If the timestamp contains a range of clock times or a repeater,
+ these will not be overlaid, but remain in the buffer as they were.
+
+- When you delete a timestamp character-by-character, it will only
+ disappear from the buffer after /all/ (invisible) characters
+ belonging to the ISO timestamp have been removed.
+
+- If the custom timestamp format is longer than the default and you
+ are using dates in tables, table alignment will be messed up. If
+ the custom format is shorter, things do work as expected.
+
+** Deadlines and scheduling
+ :PROPERTIES:
+ :DESCRIPTION: Planning your work
+ :END:
+
+A timestamp may be preceded by special keywords to facilitate planning:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~DEADLINE~ ::
+ #+cindex: DEADLINE keyword
+
+ Meaning: the task (most likely a TODO item, though not necessarily) is
+ supposed to be finished on that date.
+
+ #+vindex: org-deadline-warning-days
+
+ On the deadline date, the task will be listed in the agenda. In
+ addition, the agenda for /today/ will carry a warning about the
+ approaching or missed deadline, starting ~org-deadline-warning-days~
+ before the due date, and continuing until the entry is marked DONE. An
+ example:
+
+ #+begin_example
+ ,*** TODO write article about the Earth for the Guide
+ DEADLINE: <2004-02-29 Sun>
+ The editor in charge is [[bbdb:Ford Prefect]]
+ #+end_example
+
+ You can specify a different lead time for warnings for a specific
+ deadlines using the following syntax. Here is an example with a
+ warning period of 5 days ~DEADLINE: <2004-02-29 Sun -5d>~.
+
+- ~SCHEDULED~ ::
+ #+cindex: SCHEDULED keyword
+
+ Meaning: you are planning to start working on that task on the given
+ date.
+
+ #+vindex: org-agenda-skip-scheduled-if-done
+
+ The headline will be listed under the given date.[fn:65] In addition,
+ a reminder that the scheduled date has passed will be present in the
+ compilation for /today/, until the entry is marked DONE, i.e., the
+ task will automatically be forwarded until completed.
+
+ #+begin_example
+ ,*** TODO Call Trillian for a date on New Years Eve.
+ SCHEDULED: <2004-12-25 Sat>
+ #+end_example
+
+ {{{noindent}}}
+ *Important:* Scheduling an item in Org mode should /not/ be
+ understood in the same way that we understand /scheduling a meeting/.
+ Setting a date for a meeting is just a simple appointment, you should
+ mark this entry with a simple plain timestamp, to get this item shown
+ on the date where it applies. This is a frequent misunderstanding by
+ Org users. In Org mode, /scheduling/ means setting a date when you
+ want to start working on an action item.
+
+
+You may use timestamps with repeaters in scheduling and deadline
+entries. Org mode will issue early and late warnings based on the
+assumption that the timestamp represents the /nearest instance/ of
+the repeater. However, the use of diary sexp entries like
+
+~<%%(org-float t 42)>~
+
+in scheduling and deadline timestamps is limited. Org mode does not
+know enough about the internals of each sexp function to issue early and
+late warnings. However, it will show the item on each day where the
+sexp entry matches.
+
+*** Inserting deadline/schedule
+ :PROPERTIES:
+ :DESCRIPTION: Planning items
+ :TITLE: Inserting deadlines or schedules
+ :END:
+
+The following commands allow you to quickly insert a deadline or to schedule
+an item:[fn:66]
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-d)}}}, ~org-deadline~ ::
+ #+kindex: C-c C-d
+
+ Insert {{{samp(DEADLINE)}}} keyword along with a stamp. The insertion
+ will happen in the line directly following the headline. Any CLOSED
+ timestamp will be removed. When called with a prefix arg, an existing
+ deadline will be removed from the entry. Depending on the variable
+ ~org-log-redeadline~, a note will be taken when changing an existing
+ deadline.[fn:67]
+
+- {{{kbd(C-c C-s)}}}, ~org-schedule~ ::
+ #+kindex: C-c C-s
+
+ Insert {{{samp(SCHEDULED)}}} keyword along with a stamp. The insertion
+ will happen in the line directly following the headline. Any
+ {{{samp(CLOSED)}}} timestamp will be removed. When called with a
+ prefix argument, remove the scheduling date from the entry. Depending
+ on the variable ~org-log-reschedule~, a note will be taken when
+ changing an existing scheduling time.[fn:68]
+
+- {{{kbd(C-c C-x C-k)}}}, ~org-mark-entry-for-agenda-action~ ::
+ #+kindex: C-c C-x C-k
+ #+kindex: k a
+ #+kindex: k s
+
+ Mark the current entry for agenda action. After you have marked the
+ entry like this, you can open the agenda or the calendar to find an
+ appropriate date. With the cursor on the selected date, press
+ {{{kbd(k s)}}} or {{{kbd(k d)}}} to schedule the marked item.
+
+- {{{kbd(C-c / d)}}}, ~org-check-deadlines~ ::
+ #+kindex: C-c / d
+ #+cindex: sparse tree, for deadlines
+ #+vindex: org-deadline-warning-days
+
+ Create a sparse tree with all deadlines that are either past-due, or
+ which will become due within ~org-deadline-warning-days~. With
+ {{{kbd(C-u)}}} prefix, show all deadlines in the file. With a numeric
+ prefix, check that many days. For example, {{{kbd(C-1 C-c / d)}}}
+ shows all deadlines due tomorrow.
+
+- {{{kbd(C-c / b)}}}, ~org-check-before-date~ ::
+ #+kindex: C-c / b
+
+ Sparse tree for deadlines and scheduled items before a given date.
+
+- {{{kbd(C-c / a)}}}, ~org-check-after-date~ ::
+ #+kindex: C-c / a
+
+ Sparse tree for deadlines and scheduled items after a given date.
+
+
+Note that ~org-schedule~ and ~org-deadline~ supports setting the date
+by indicating a relative time: e.g. +1d will set the date to the next
+day after today, and --1w will set the date to the previous week
+before any current timestamp.
+
+*** Repeated tasks
+ :PROPERTIES:
+ :DESCRIPTION: Items that show up again and again
+ :END:
+#+cindex: tasks, repeated
+#+cindex: repeated tasks
+
+Some tasks need to be repeated again and again. Org mode helps to
+organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
+or plain timestamp. In the following example:
+
+#+begin_example
+ ,** TODO Pay the rent
+ DEADLINE: <2005-10-01 Sat +1m>
+#+end_example
+
+{{{noindent}}} the ~+1m~ is a repeater; the intended interpretation is
+that the task has a deadline on <2005-10-01> and repeats itself every
+(one) month starting from that time. You can use yearly, monthly,
+weekly, daily and hourly repeat cookies by using the ~y/w/m/d/h~
+letters. If you need both a repeater and a special warning period in a
+deadline entry, the repeater should come first and the warning period
+last: ~DEADLINE: <2005-10-01 Sat +1m -3d>~.
+
+#+vindex: org-todo-repeat-to-state
+
+Deadlines and scheduled items produce entries in the agenda when they
+are over-due, so it is important to be able to mark such an entry as
+completed once you have done so. When you mark a DEADLINE or a
+SCHEDULE with the TODO keyword DONE, it will no longer produce entries
+in the agenda. The problem with this is, however, that then also the
+/next/ instance of the repeated entry will not be active. Org mode
+deals with this in the following way: When you try to mark such an
+entry DONE (using {{{kbd(C-c C-t)}}}), it will shift the base date of
+the repeating timestamp by the repeater interval, and immediately set
+the entry state back to TODO.[fn:69] In the example above, setting the
+state to DONE would actually switch the date like this:
+
+#+begin_example
+ ,** TODO Pay the rent
+ DEADLINE: <2005-11-01 Tue +1m>
+#+end_example
+
+#+vindex: org-log-repeat
+
+A timestamp will be added under the deadline, to keep a record that
+you actually acted on the previous instance of this deadline.[fn:70]
+
+As a consequence of shifting the base date, this entry will no longer be
+visible in the agenda when checking past dates, but all future instances
+will be visible.
+
+With the {{{samp(+1m)}}} cookie, the date shift will always be exactly one
+month. So if you have not paid the rent for three months, marking this
+entry DONE will still keep it as an overdue deadline. Depending on the
+task, this may not be the best way to handle it. For example, if you
+forgot to call your father for 3 weeks, it does not make sense to call
+him 3 times in a single day to make up for it. Finally, there are tasks
+like changing batteries which should always repeat a certain time
+/after/ the last time you did it. For these tasks, Org mode has
+special repeaters {{{samp(++)}}} and {{{samp(.+)}}}. For example:
+
+#+begin_example
+ ,** TODO Call Father
+ DEADLINE: <2008-02-10 Sun ++1w>
+ Marking this DONE will shift the date by at least one week,
+ but also by as many weeks as it takes to get this date into
+ the future. However, it stays on a Sunday, even if you called
+ and marked it done on Saturday.
+ ,** TODO Check the batteries in the smoke detectors
+ DEADLINE: <2005-11-01 Tue .+1m>
+ Marking this DONE will shift the date to one month after
+ today.
+#+end_example
+
+You may have both scheduling and deadline information for a specific
+task---just make sure that the repeater intervals on both are the
+same.
+
+An alternative to using a repeater is to create a number of copies of
+a task subtree, with dates shifted in each copy. The command
+{{{kbd(C-c C-x c)}}} was created for this purpose, it is described in
+[[Structure editing]].
+
+** Clocking work time
+ :PROPERTIES:
+ :DESCRIPTION: Tracking how long you spend on a task
+ :END:
+#+cindex: clocking time
+#+cindex: time clocking
+
+Org mode allows you to clock the time you spend on specific tasks in a
+project. When you start working on an item, you can start the clock. When
+you stop working on that task, or when you mark the task done, the clock is
+stopped and the corresponding time interval is recorded. It also computes
+the total time spent on each subtree of a project.[fn:71] And it remembers a
+history or tasks recently clocked, to that you can jump quickly between a
+number of tasks absorbing your time.
+
+To save the clock history across Emacs sessions, use:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+ (setq org-clock-persist 'history)
+ (org-clock-persistence-insinuate)
+#+end_src
+
+When you clock into a new task after resuming Emacs, the incomplete
+clock will be found (see [[Resolving idle time]]) and you will be prompted
+about what to do with it.[fn:72]
+
+*** Clocking commands
+ :PROPERTIES:
+ :DESCRIPTION: Starting and stopping a clock
+ :END:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-i)}}}, ~org-clock-in~ ::
+ #+kindex: C-c C-x C-i
+ #+vindex: org-clock-into-drawer
+ #+vindex: org-clock-continuously
+ #+cindex: property, LOG_INTO_DRAWER
+
+ Start the clock on the current item (clock-in). This inserts the CLOCK
+ keyword together with a timestamp. If this is not the first clocking
+ of this item, the multiple CLOCK lines will be wrapped into a
+ ~:LOGBOOK:~ drawer (see also the variable ~org-clock-into-drawer~).
+ You can also overrule the setting of this variable for a subtree by
+ setting a ~CLOCK_INTO_DRAWER~ or ~LOG_INTO_DRAWER~ property. When
+ called with a {{{kbd(C-u)}}} prefix argument, select the task from a
+ list of recently clocked tasks. With two {{{kbd(C-u C-u)}}} prefixes,
+ clock into the task at point and mark it as the default task; the
+ default task will then always be available with letter {{{kbd(d)}}}
+ when selecting a clocking task. With three {{{kbd(C-u C-u C-u)}}}
+ prefixes, force continuous clocking by starting the clock when the
+ last clock stopped.@*
+
+ #+cindex: property: CLOCK_MODELINE_TOTAL
+ #+cindex: property: LAST_REPEAT
+ #+vindex: org-clock-modeline-total
+
+ While the clock is running, the current clocking time is shown in the
+ mode line, along with the title of the task. The clock time shown will
+ be all time ever clocked for this task and its children. If the task
+ has an effort estimate (see [[Effort estimates]]), the mode line displays
+ the current clocking time against it.[fn:73] If the task is a
+ repeating one (see [[Repeated tasks]]), only the time since the last reset
+ of the task will be shown.[fn:74] More control over what time is shown
+ can be exercised with the ~CLOCK_MODELINE_TOTAL~ property. It may have
+ the values ~current~ to show only the current clocking instance,
+ ~today~ to show all time clocked on this tasks today (see also the
+ variable ~org-extend-today-until~), ~all~ to include all time, or
+ ~auto~ which is the default.[fn:75] Clicking with {{{kbd(mouse-1)}}}
+ onto the mode line entry will pop up a menu with clocking options.
+
+- {{{kbd(C-c C-x C-o)}}}, ~org-clock-out~ ::
+ #+kindex: C-c C-x C-o
+ #+vindex: org-log-note-clock-out
+
+ Stop the clock (clock-out). This inserts another timestamp at the same
+ location where the clock was last started. It also directly computes
+ the resulting time in inserts it after the time range as
+ {{{samp(=>HH:MM)}}}. See the variable ~org-log-note-clock-out~ for the
+ possibility to record an additional note together with the clock-out
+ timestamp.[fn:76]
+
+- {{{kbd(C-c C-x C-x)}}}, ~org-clock-in-last~ ::
+ #+kindex: C-c C-x C-x
+ #+vindex: org-clock-continuously
+
+ Reclock the last clocked task. With one {{{kbd(C-u)}}} prefix
+ argument, select the task from the clock history. With two
+ {{{kbd(C-u)}}} prefixes, force continuous clocking by starting the
+ clock when the last clock stopped.
+
+- {{{kbd(C-c C-x C-e)}}}, ~org-clock-modify-effort-estimate~ ::
+ #+kindex: C-c C-x C-e
+
+ Update the effort estimate for the current clock task.
+- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-y)}}}, ~org-evaluate-time-range~ ::
+ #+kindex: C-c C-c
+ #+kindex: C-c C-y
+ #+kindex: C-c C-c
+
+ Recompute the time interval after changing one of the timestamps. This
+ is only necessary if you edit the timestamps directly. If you change
+ them with {{{kbdkey(S-,cursor)}}} keys, the update is automatic.
+
+- {{{kbdkey(C-S-,up)}}} {{{kbdkey(C-S-,down)}}}, ~org-clock-timestamps-up/down~ ::
+ #+kindex: C-S-@key{up/down}
+
+ On ~CLOCK~ log lines, increase/decrease both timestamps so that the
+ clock duration keeps the same.
+
+- {{{kbdkey(S-M-,up)}}} {{{kbdkey(S-M-,down)}}}, ~org-timestamp-up/down~ ::
+ #+kindex: S-M-@key{up/down}
+
+ On ~CLOCK~ log lines, increase/decrease the timestamp at point and the
+ one of the previous (or the next clock) timestamp by the same
+ duration. For example, if you hit {{{kbdkey(S-M-,up)}}} to increase a
+ clocked-out timestamp by five minutes, then the clocked-in timestamp
+ of the next clock will be increased by five minutes.
+
+- {{{kbd(C-c C-t)}}}, ~org-todo~ ::
+ #+kindex: C-c C-t
+
+ Changing the TODO state of an item to DONE automatically stops the
+ clock if it is running in this same item.
+
+- {{{kbd(C-c C-x C-q)}}}, ~org-clock-cancel~ ::
+ #+kindex: C-c C-x C-q
+
+ Cancel the current clock. This is useful if a clock was started by
+ mistake, or if you ended up working on something else.
+
+- {{{kbd(C-c C-x C-j)}}}, ~org-clock-goto~ ::
+ #+kindex: C-c C-x C-j
+
+ Jump to the headline of the currently clocked in task. With a
+ {{{kbd(C-u)}}} prefix arg, select the target task from a list of
+ recently clocked tasks.
+
+- {{{kbd(C-c C-x C-d)}}}, ~org-clock-display~ ::
+ #+kindex: C-c C-x C-d
+ #+vindex: org-remove-highlights-with-change
+
+ Display time summaries for each subtree in the current buffer. This
+ puts overlays at the end of each headline, showing the total time
+ recorded under that heading, including the time of any subheadings.
+ You can use visibility cycling to study the tree, but the overlays
+ disappear when you change the buffer (see variable
+ ~org-remove-highlights-with-change~) or press {{{kbd(C-c C-c)}}}.
+
+
+The {{{kbd(l)}}} key may be used in the timeline (see [[Timeline for a
+single file]]) and in the agenda (see [[Weekly/daily agenda]]) to show which
+tasks have been worked on or closed during a day.
+
+*Important:* note that both ~org-clock-out~ and ~org-clock-in-last~
+can have a global keybinding and will not modify the window
+disposition.
+
+*** The clock table
+ :PROPERTIES:
+ :DESCRIPTION: Detailed reports
+ :END:
+#+cindex: clocktable, dynamic block
+#+cindex: report, of clocked time
+
+Org mode can produce quite complex reports based on the time clocking
+information. Such a report is called a /clock table/, because it is
+formatted as one or several Org tables.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-r)}}}, ~org-clock-report~ ::
+ #+kindex: C-c C-x C-r
+
+ Insert a dynamic block (see [[Dynamic blocks]]) containing a clock report
+ as an Org mode table into the current file. When the cursor is at an
+ existing clock table, just update it. When called with a prefix
+ argument, jump to the first clock report in the current document and
+ update it. The clock table always includes also trees with ~:ARCHIVE:~
+ tag.
+
+- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ ::
+ #+kindex: C-c C-c
+
+ Update dynamic block at point. The cursor needs to be in the
+ ~#+BEGIN~ line of the dynamic block.
+
+- {{{kbd(C-u C-c C-x C-u)}}} ::
+ #+kindex: C-u C-c C-x C-u
+
+ Update all dynamic blocks (see [[Dynamic blocks]]). This is useful if you
+ have several clock table blocks in a buffer.
+
+- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}, ~org-clocktable-try-shift~ ::
+
+ Shift the current ~:block~ interval and update the table. The cursor
+ needs to be in the ~#+BEGIN: clocktable~ line for this command. If
+ ~:block~ is ~today~, it will be shifted to ~today-1~ etc.
+
+
+Here is an example of the frame for a clock table as it is inserted
+into the buffer with the {{{kbd(C-c C-x C-r)}}} command:
+
+#+cindex: #+BEGIN, clocktable
+#+begin_example
+ ,#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
+ ,#+END: clocktable
+#+end_example
+{{{noindent}}}
+#+vindex: org-clocktable-defaults
+The {{{samp(BEGIN)}}} line and specify a number of options to define the scope,
+structure, and formatting of the report. Defaults for all these options can
+be configured in the variable ~org-clocktable-defaults~.
+
+{{{noindent}}} First there are options that determine which clock entries are to
+be selected:
+
+#+attr_texinfo: :table-type table :indic @asis
+- :maxlevel ::
+
+ Maximum level depth to which times are listed in the table. Clocks at
+ deeper levels will be summed into the upper level.
+
+- :scope ::
+
+ The scope to consider. This can be any of the following:
+
+ - nil :: the current buffer or narrowed region
+ - file :: the full current buffer
+ - subtree :: the subtree where the clocktable is located
+ - tree {{{var(N)}}} :: the surrounding level {{{var(N)}}} tree, for example ~tree3~
+ - tree :: the surrounding level 1 tree
+ - agenda :: all agenda files
+ - ("file"..) :: scan these files
+ - file-with-archives :: current file and its archives
+ - agenda-with-archives :: all agenda files, including archives
+
+- :block ::
+
+ The time block to consider. This block is specified either absolute,
+ or relative to the current time and may be any of these formats:
+
+ - 2007-12-31 :: New year eve 2007
+ - 2007-12 :: December 2007
+ - 2007-W50 :: ISO-week 50 in 2007
+ - 2007-Q2 :: 2nd quarter in 2007
+ - 2007 :: the year 2007
+ - today, yesterday, today-{{{var(N)}}} :: a relative day
+ - thisweek, lastweek, thisweek-{{{var(N)}}} :: a relative week
+ - thismonth, lastmonth, thismonth-{{{var(N)}}} :: a relative month
+ - thisyear, lastyear, thisyear-{{{var(N)}}} :: a relative year
+
+ Use {{{kbdkey(S-,left)}}} or {{{kbdkey(S-,right)}}} to shift the
+ time interval.
+
+- :tstart ::
+
+ A time string specifying when to start considering times.
+
+- :tend ::
+
+ A time string specifying when to stop considering times.
+
+- :step ::
+
+ Set to ~week~ or ~day~ to split the table into chunks. To use this,
+ ~:block~ or ~:tstart~, ~:tend~ are needed.
+
+- :stepskip0 ::
+
+ Do not show steps that have zero time.
+
+- :fileskip0 ::
+
+ Do not show table sections from files which did not contribute.
+
+- :tags ::
+
+ A tags match to select entries that should contribute. See [[Matching
+ tags and properties]] for the match syntax.
+
+
+Then there are options which determine the formatting of the table. There
+options are interpreted by the function ~org-clocktable-write-default~,
+but you can specify your own function using the ~:formatter~ parameter.
+
+#+attr_texinfo: :table-type table :indic @asis
+- :emphasize ::
+
+ When ~t~, emphasize level one and level two items.
+
+- :lang ::
+
+ Language to use for descriptive cells like "Task".[fn:77]
+
+- :link ::
+
+ Link the item headlines in the table to their origins.
+
+- :narrow ::
+
+ An integer to limit the width of the headline column in the org table.
+ If you write it like {{{samp(50!)}}}, then the headline will also be
+ shortened in export.
+
+- :indent ::
+
+ Indent each headline field according to its level.
+
+- :tcolumns ::
+
+ Number of columns to be used for times. If this is smaller than
+ ~:maxlevel~, lower levels will be lumped into one column.
+
+- :level ::
+
+ Should a level number column be included?
+
+- :compact ::
+
+ Abbreviation for ~:level nil :indent t :narrow 40! :tcolumns 1~. All
+ are overwritten except if there is an explicit ~:narrow~.
+
+- :timestamp ::
+
+ A timestamp for the entry, when available. Look for SCHEDULED,
+ DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.
+
+- :properties ::
+
+ List of properties that should be shown in the table. Each property
+ will get its own column.
+
+- :inherit-props ::
+
+ When this flag is ~t~, the values for ~:properties~ will be inherited.
+
+- :formula ::
+
+ Content of a ~#+TBLFM~ line to be added and evaluated. As a special
+ case, {{{samp(:formula %)}}} adds a column with % time. If you do not
+ specify a formula here, any existing formula below the clock table
+ will survive updates and be evaluated.
+
+- :formatter ::
+
+ A function to format clock data and insert it into the buffer.
+
+
+To get a clock summary of the current level 1 tree, for the current
+day, you could write:
+
+#+begin_example
+ ,#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
+ ,#+END: clocktable
+#+end_example
+
+{{{noindent}}} To use a specific time range you could write:[fn:78]
+
+#+begin_example
+ ,#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
+ :tend "<2006-08-10 Thu 12:00>"
+ ,#+END: clocktable
+#+end_example
+
+A summary of the current subtree with % times would be:
+
+#+begin_example
+ ,#+BEGIN: clocktable :scope subtree :link t :formula %
+ ,#+END: clocktable
+#+end_example
+
+A horizontally compact representation of everything clocked during
+last week would be:
+
+#+begin_example
+ ,#+BEGIN: clocktable :scope agenda :block lastweek :compact t
+ ,#+END: clocktable
+#+end_example
+
+*** Resolving idle time
+ :PROPERTIES:
+ :DESCRIPTION: Resolving time when you've been idle
+ :TITLE: Resolving idle time and continuous clocking
+ :END:
+
+#+cindex: resolve idle time
+#+cindex: idle, resolve, dangling
+
+If you clock in on a work item, and then walk away from your
+computer---perhaps to take a phone call---you often need to
+``resolve'' the time you were away by either subtracting it from the
+current clock, or applying it to another one.
+
+#+vindex: org-clock-idle-time
+
+By customizing the variable ~org-clock-idle-time~ to some integer,
+such as 10 or 15, Emacs can alert you when you get back to your
+computer after being idle for that many minutes, and ask what you want
+to do with the idle time.[fn:79] There will be a question waiting for you
+when you get back, indicating how much idle time has passed
+(constantly updated with the current amount), as well as a set of
+choices to correct the discrepancy:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(k)}}} ::
+ #+kindex: k
+
+ To keep some or all of the minutes and stay clocked in, press
+ {{{kbd(k)}}}. Org will ask how many of the minutes to keep. Press
+ {{{key(RET)}}} to keep them all, effectively changing nothing, or
+ enter a number to keep that many minutes.
+
+- {{{kbd(K)}}} ::
+ #+kindex: K
+
+ If you use the shift key and press {{{kbd(K)}}}, it will keep however
+ many minutes you request and then immediately clock out of that task.
+ If you keep all of the minutes, this is the same as just clocking out
+ of the current task.
+
+- {{{kbd(s)}}} ::
+ #+kindex: s
+
+ To keep none of the minutes, use {{{kbd(s)}}} to subtract all the away
+ time from the clock, and then check back in from the moment you
+ returned.
+
+- {{{kbd(S)}}} ::
+ #+kindex: S
+
+ To keep none of the minutes and just clock out at the start of the
+ away time, use the shift key and press {{{kbd(S)}}}. Remember that
+ using shift will always leave you clocked out, no matter which option
+ you choose.
+
+- {{{kbd(C)}}} ::
+ #+kindex: C
+
+ To cancel the clock altogether, use {{{kbd(C)}}}. Note that if instead
+ of canceling you subtract the away time, and the resulting clock
+ amount is less than a minute, the clock will still be canceled rather
+ than clutter up the log with an empty entry.
+
+
+What if you subtracted those away minutes from the current clock, and
+now want to apply them to a new clock? Simply clock in to any task
+immediately after the subtraction. Org will notice that you have
+subtracted time ``on the books'', so to speak, and will ask if you
+want to apply those minutes to the next task you clock in on.
+
+There is one other instance when this clock resolution magic occurs.
+Say you were clocked in and hacking away, and suddenly your cat chased
+a mouse who scared a hamster that crashed into your UPS's power
+button! You suddenly lose all your buffers, but thanks to auto-save
+you still have your recent Org mode changes, including your last clock
+in.
+
+If you restart Emacs and clock into any task, Org will notice that you
+have a dangling clock which was never clocked out from your last
+session. Using that clock's starting time as the beginning of the
+unaccounted-for period, Org will ask how you want to resolve that
+time. The logic and behavior is identical to dealing with away time
+due to idleness; it is just happening due to a recovery event rather
+than a set amount of idle time.
+
+You can also check all the files visited by your Org agenda for
+dangling clocks at any time using {{{kbd(M-x org-resolve-clocks RET)}}}
+ (or {{{kbd(C-c C-x C-z)}}}).
+
+*** Continuous clocking
+#+cindex: continuous clocking
+#+vindex: org-clock-continuously
+
+You may want to start clocking from the time when you clocked out the
+previous task. To enable this systematically, set
+~org-clock-continuously~ to ~t~. Each time you clock in, Org retrieves
+the clock-out time of the last clocked entry for this session, and
+start the new clock from there.
+
+If you only want this from time to time, use three universal prefix
+arguments with ~org-clock-in~ and two {{{kbd(C-u C-u)}}} with
+~org-clock-in-last~.
+
+** Effort estimates
+ :PROPERTIES:
+ :DESCRIPTION: Planning work effort in advance
+ :END:
+#+cindex: effort estimates
+#+cindex: property, Effort
+#+vindex: org-effort-property
+
+If you want to plan your work in a very detailed way, or if you need
+to produce offers with quotations of the estimated work effort, you
+may want to assign effort estimates to entries. If you are also
+clocking your work, you may later want to compare the planned effort
+with the actual working time, a great way to improve planning
+estimates. Effort estimates are stored in a special property
+{{{samp(Effort)}}}.[fn:80] You can set the effort for an entry with
+the following commands:
+
+#+attr_texinfo: :table-type table :indic @kbd
+- {{{kbd(C-c C-x e)}}}, ~org-set-effort~ ::
+ #+kindex: C-c C-x e
+
+ Set the effort estimate for the current entry. With a numeric prefix
+ argument, set it to the Nth allowed value (see below). This command is
+ also accessible from the agenda with the {{{kbd(e)}}} key.
+
+- {{{kbd(C-c C-x C-e)}}}, ~org-clock-modify-effort-estimate~ ::
+ #+kindex: C-c C-x C-e
+
+ Modify the effort estimate of the item currently being clocked.
+
+
+Clearly the best way to work with effort estimates is through column
+view (see [[Column view]]). You should start by setting up discrete values
+for effort estimates, and a ~COLUMNS~ format that displays these
+values together with clock sums (if you want to clock your time). For
+a specific buffer you can use:
+
+#+begin_example
+ ,#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
+ ,#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort){:} %CLOCKSUM
+#+end_example
+
+#+vindex: org-global-properties
+#+vindex: org-columns-default-format
+
+{{{noindent}}} or, even better, you can set up these values globally
+by customizing the variables ~org-global-properties~ and
+~org-columns-default-format~. In particular if you want to use this
+setup also in the agenda, a global setup may be advised.
+
+The way to assign estimates to individual items is then to switch to
+column mode, and to use {{{kbdkey(S-,right)}}} and
+{{{kbdkey(S-,left)}}} to change the value. The values you enter will
+immediately be summed up in the hierarchy. In the column next to it,
+any clocked time will be displayed.
+
+#+vindex: org-agenda-columns-add-appointments-to-effort-sum
+
+If you switch to column view in the daily/weekly agenda, the effort column
+will summarize the estimated work effort for each day, and you can use this to find space in your schedule. To get
+an overview of the entire part of the day that is committed, you can set the
+option ~org-agenda-columns-add-appointments-to-effort-sum~.[fn:179] The
+appointments on a day that take place over a specified time interval will
+then also be added to the load estimate of the day.
+
+Effort estimates can be used in secondary agenda filtering that is
+triggered with the {{{kbd(/)}}} key in the agenda (see [[Agenda
+commands]]). If you have these estimates defined consistently, two or
+three key presses will narrow down the list to stuff that fits into an
+available time slot.
+
+** Relative timer
+ :PROPERTIES:
+ :DESCRIPTION: Notes with a running timer
+ :TITLE: Taking notes with a relative timer
+ :END:
+#+cindex: relative timer
+
+When taking notes during, for example, a meeting or a video viewing, it can
+be useful to have access to times relative to a starting time. Org provides
+such a relative timer and make it easy to create timed notes.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x .)}}}, ~org-timer~ ::
+ #+kindex: C-c C-x .
+
+ Insert a relative time into the buffer. The first time you use this, the
+ timer will be started. When called with a prefix argument, the timer is
+ restarted.
+
+- {{{kbd(C-c C-x -)}}}, ~org-timer-item~ ::
+ #+kindex: C-c C-x -
+
+ Insert a description list item with the current relative time. With a prefix
+ argument, first reset the timer to 0.
+
+- {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ ::
+ #+kindex: M-@key{RET}
+
+ Once the timer list is started, you can also use {{{kbdkey(M-,RET)}}}
+ to insert new timer items.
+
+- {{{kbd(C-c C-x \,)}}} ::
+ #+kindex: C-c C-x ,
+ #+kindex: C-c C-x ,
+
+ Pause the timer, or continue it if it is already paused
+ ({{{command(org-timer-pause-or-continue)}}}).
+
+- {{{kbd(C-u C-c C-x \,)}}} ::
+ #+kindex: C-u C-c C-x ,
+ #+kindex: C-u C-c C-x ,
+
+ Stop the timer. After this, you can only start a new timer, not
+ continue the old one. This command also removes the timer from the
+ mode line.
+
+- {{{kbd(C-c C-x 0)}}}, ~org-timer-start~ ::
+ #+kindex: C-c C-x 0
+
+ Reset the timer without inserting anything into the buffer. By
+ default, the timer is reset to 0. When called with a {{{kbd(C-u)}}}
+ prefix, reset the timer to specific starting offset. The user is
+ prompted for the offset, with a default taken from a timer string at
+ point, if any, So this can be used to restart taking notes after a
+ break in the process. When called with a double prefix argument
+ {{{kbd(C-u C-u)}}}, change all timer strings in the active region by a
+ certain amount. This can be used to fix timer strings if the timer was
+ not started at exactly the right moment.
+
+** Countdown timer
+ :PROPERTIES:
+ :DESCRIPTION: Starting a countdown timer for a task
+ :END:
+#+cindex: Countdown timer
+#+kindex: C-c C-x ;
+#+kindex: ;
+
+Calling ~org-timer-set-timer~ from an Org mode buffer runs a countdown
+timer. Use {{{kbd(;)}}} from agenda buffers, {{{key(C-c C-x ;)}}}
+everywhere else.
+
+~org-timer-set-timer~ prompts the user for a duration and displays a
+countdown timer in the modeline. ~org-timer-default-timer~ sets the
+default countdown value. Giving a prefix numeric argument overrides this
+default value.
+
+* Capture - Refile - Archive
+ :PROPERTIES:
+ :DESCRIPTION: The ins and outs for projects
+ :END:
+#+cindex: capture
+
+An important part of any organization system is the ability to quickly
+capture new ideas and tasks, and to associate reference material with
+them. Org does this using a process called /capture/. It also can
+store files related to a task (/attachments/) in a special directory.
+Once in the system, tasks and projects need to be moved around. Moving
+completed project trees to an archive file keeps the system compact
+and fast.
+
+** Capture
+ :PROPERTIES:
+ :DESCRIPTION: Capturing new stuff
+ :END:
+#+cindex: capture
+
+Org's method for capturing new items is heavily inspired by John
+Wiegley excellent remember package. Up to version 6.36 Org used a
+special setup for {{{file(remember.el)}}}. The file {{{file(org-remember.el)}}}
+is still part of Org mode for backward compatibility with existing
+setups. You can find the documentation for org-remember at
+[[http://orgmode.org/org-remember.pdf]].
+
+The new capturing setup described here is preferred and should be used by new
+users. To convert your ~org-remember-templates~, run the following command:
+{{{kbdspckey(M-x org-capture-import-remember-templates,RET)}}}
+
+{{{noindent}}} and then customize the new variable with
+{{{kbd(M-x customize-variable org-capture-templates)}}}, check the result, and
+save the customization. You can then use both remember and capture
+until you are familiar with the new mechanism.
+
+Capture lets you quickly store notes with little interruption of your work
+flow. The basic process of capturing is very similar to remember, but Org
+does enhance it with templates and more.
+
+*** Setting up capture
+ :PROPERTIES:
+ :DESCRIPTION: Where notes will be stored
+ :END:
+
+The following customization sets a default target file for notes, and defines
+a global key for capturing new material.[fn:81]
+
+#+vindex: org-default-notes-file
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-default-notes-file (concat org-directory "/notes.org"))
+(define-key global-map "\C-cc" 'org-capture)
+#+end_src
+
+*** Using capture
+ :PROPERTIES:
+ :DESCRIPTION: Commands to invoke and terminate capture
+ :END:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c c)}}}, ~org-capture~ ::
+ #+kindex: C-c c
+ #+cindex: date tree
+
+ Call the command ~org-capture~. Note that this keybinding is global
+ and not active by default - you need to install it. If you have
+ templates defined (see [[Capture templates]], it will offer these
+ templates for selection or use a new Org outline node as the default
+ template. It will insert the template into the target file and switch
+ to an indirect buffer narrowed to this new node. You may then insert
+ the information you want.
+
+- {{{kbd(C-c C-c)}}}, ~org-capture-finalize~ ::
+ #+kindex: C-c C-c
+
+ Once you have finished entering information into the capture buffer,
+ {{{kbd(C-c C-c)}}} will return you to the window configuration before
+ the capture process, so that you can resume your work without further
+ distraction. When called with a prefix argument, finalize and then
+ jump to the captured item.
+
+- {{{kbd(C-c C-w)}}}, ~org-capture-refile~ ::
+ #+kindex: C-c C-w
+
+ Finalize the capture process by refiling the note to a different place
+ (see [[Refile and copy]]). Please realize that this is a normal refiling
+ command that will be executed---so the cursor position at the moment
+ you run this command is important. If you have inserted a tree with a
+ parent and children, first move the cursor back to the parent. Any
+ prefix argument given to this command will be passed on to the
+ ~org-refile~ command.
+
+- {{{kbd(C-c C-k)}}}, ~org-capture-kill~ ::
+ #+kindex: C-c C-k
+
+ Abort the capture process and return to the previous state.
+
+
+You can also call ~org-capture~ in a special way from the agenda,
+using the {{{kbd(k c)}}} key combination. With this access, timestamps
+inserted by the selected capture template will default to the cursor
+date in the agenda, rather than to the current date.
+
+To find the locations of the last stored capture, use ~org-capture~ with
+prefix commands:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-u C-c c)}}} ::
+ #+kindex: C-u C-c c
+
+ Visit the target location of a capture template. You get to select the
+ template in the usual way.
+
+- {{{kbd(C-u C-u C-c c)}}} ::
+ #+kindex: C-u C-u C-c c
+
+ Visit the last stored capture item in its buffer.
+
+
+#+vindex: org-capture-bookmark
+#+cindex: org-capture-last-stored
+
+You can also jump to the bookmark ~org-capture-last-stored~, which
+will automatically be created unless you set ~org-capture-bookmark~ to
+~nil~.
+
+To insert the capture at point in an Org buffer, call ~org-capture~
+with a ~C-0~ prefix argument.
+
+*** Capture templates
+ :PROPERTIES:
+ :DESCRIPTION: Define the outline of different note types
+ :END:
+#+cindex: templates, for Capture
+
+You can use templates for different types of capture items, and for
+different target locations. The easiest way to create such templates
+is through the customize interface.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c c C)}}} ::
+ #+kindex: C-c c C
+
+ Customize the variable ~org-capture-templates~.
+
+
+Before we give the formal description of template definitions, let's
+look at an example. Say you would like to use one template to create
+general TODO entries, and you want to put these entries under the
+heading {{{samp(Tasks)}}} in your file {{{file(~/org/gtd.org)}}}.
+Also, a date tree in the file {{{file(journal.org)}}} should capture
+journal entries. A possible configuration would look like:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-capture-templates
+ '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
+ "* TODO %?\n %i\n %a")
+ ("j" "Journal" entry (file+datetree "~/org/journal.org")
+ "* %?\nEntered on %U\n %i\n %a")))
+#+end_src
+
+{{{noindent}}} If you then press {{{kbd(C-c c t)}}}, Org will prepare
+the template for you like this:
+
+#+begin_example
+ ,* TODO
+ [[file:link to where you initiated capture]]
+#+end_example
+
+{{{noindent}}} During expansion of the template, ~%a~ has been
+replaced by a link to the location from where you called the capture
+command. This can be extremely useful for deriving tasks from emails,
+for example. You fill in the task definition, press ~C-c C-c~ and Org
+returns you to the same place where you started the capture process.
+
+To define special keys to capture to a particular template without
+going through the interactive template selection, you can create your
+key binding like this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(define-key global-map "\C-cx"
+ (lambda () (interactive) (org-capture nil "x")))
+#+end_src
+
+**** Template elements
+ :PROPERTIES:
+ :DESCRIPTION: What is needed for a complete template entry
+ :END:
+
+Now lets look at the elements of a template definition. Each entry in
+~org-capture-templates~ is a list with the following items:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~keys~ ::
+
+ The keys that will select the template, as a string, characters
+ only, for example "a" for a template to be selected with a
+ single key, or "BTW" for selection with two keys. When using
+ several keys, keys using the same prefix key must be sequential
+ in the list and preceded by a 2-element entry explaining the
+ prefix key, for example:
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ ("b" "Templates for marking stuff to buy")
+ #+end_src
+
+ {{{noindent}}} If you do not define a template for the {{{kbd(C)}}}
+ key, this key will be used to open the customize buffer for this
+ complex variable.
+
+- ~description~ ::
+
+ A short string describing the template, which will be shown during
+ selection.
+
+- ~type~ ::
+
+ The type of entry, a symbol. Valid values are:
+
+ - ~entry~ ::
+
+ An Org mode node, with a headline. Will be filed as the child of the
+ target entry or as a top-level entry. The target file should be an Org
+ mode file.
+
+ - ~item~ ::
+
+ A plain list item, placed in the first plain list at the target
+ location. Again the target file should be an Org file.
+
+ - ~checkitem~ ::
+
+ A checkbox item. This only differs from the plain list item by the
+ default template.
+
+ - ~table-line~ ::
+
+ A new line in the first table at the target location. Where exactly
+ the line will be inserted depends on the properties ~:prepend~ and
+ ~:table-line-pos~ (see below).
+
+ - plain ::
+
+ Text to be inserted as it is.
+
+- target ::
+ #+vindex: org-default-notes-file
+
+ Specification of where the captured item should be placed. In Org mode
+ files, targets usually define a node. Entries will become children of this
+ node. Other types will be added to the table or list in the body of this
+ node. Most target specifications contain a file name. If that file name is
+ the empty string, it defaults to ~org-default-notes-file~. A file can
+ also be given as a variable, function, or Emacs Lisp form.
+
+ Valid values are:
+
+ - ~(file "path/to/file")~ ::
+
+ Text will be placed at the beginning or end of that file.
+
+ - ~(id "id of existing org entry")~ ::
+
+ Filing as child of this entry, or in the body of the entry.
+
+ - ~(file+headline "path/to/file" "node headline")~ ::
+
+ Fast configuration if the target heading is unique in the file.
+
+ - ~(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)~ ::
+
+ For non-unique headings, the full path is safer.
+
+ - ~(file+regexp "path/to/file" "regexp to find location")~ ::
+
+ Use a regular expression to position the cursor.
+
+ - ~(file+datetree "path/to/file")~ ::
+
+ Will create a heading in a date tree for today's date.
+
+ - ~(file+datetree+prompt "path/to/file")~ ::
+
+ Will create a heading in a date tree, but will prompt for the date.
+
+ - ~(file+function "path/to/file" function-finding-location)~ ::
+
+ A function to find the right location in the file.
+
+ - ~(clock)~ ::
+
+ File to the entry that is currently being clocked.
+
+ - ~(function function-finding-location)~ ::
+
+ Most general way, write your own function to find both
+ file and location.
+
+- ~template~ ::
+
+ The template for creating the capture item. If you leave this empty,
+ an appropriate default template will be used. Otherwise this is a
+ string with escape codes, which will be replaced depending on time and
+ context of the capture call. The string with escapes may be loaded
+ from a template file, using the special syntax
+ ~(file "path/to/template")~. See below for more details.
+
+- ~properties~ ::
+
+ The rest of the entry is a property list of additional options.
+ Recognized properties are:
+
+ - ~:prepend~ ::
+
+ Normally new captured information will be appended at the target
+ location (last child, last table line, last list item, ...). Setting
+ this property will change that.
+
+ - ~:immediate-finish~ ::
+
+ When set, do not offer to edit the information, just file it away
+ immediately. This makes sense if the template only needs information
+ that can be added automatically.
+
+ - ~:empty-lines~ ::
+
+ Set this to the number of lines to insert before and after the new
+ item. The default is 0, and the only other common value is 1.
+
+ - ~:clock-in~ ::
+
+ Start the clock in this item.
+
+ - ~:clock-keep~ ::
+
+ Keep the clock running when filing the captured entry.
+
+ - ~:clock-resume~ ::
+
+ If starting the capture interrupted a clock, restart that clock when
+ finished with the capture. Note that ~:clock-keep~ has precedence over
+ ~:clock-resume~. When setting both to ~t~, the current clock will run
+ and the previous one will not be resumed.
+
+ - ~:unnarrowed~ ::
+
+ Do not narrow the target buffer, simply show the full buffer. Default
+ is to narrow it so that you only see the new material.
+
+ - ~:table-line-pos~ ::
+
+ Specification of the location in the table where the new line should
+ be inserted. It should be a string like "II-3" meaning that the new
+ line should become the third line before the second horizontal
+ separator line.
+
+ - ~:kill-buffer~ ::
+
+ If the target file was not yet visited when capture was invoked, kill
+ the buffer again after capture is completed.
+
+**** Template expansion
+ :PROPERTIES:
+ :DESCRIPTION: Filling in information about time and context
+ :END:
+
+In the template itself, special {{{kbd(%)}}}-escapes allow dynamic
+insertion of content.[fn:82] The templates are expanded in the order given
+here:
+
+#+attr_texinfo: :table-type table :indic @asis
+- %[{{{var(file)}}}] ::
+
+ Insert the contents of the file given by {{{var(file)}}}.
+
+- %({{{var(sexp)}}}) ::
+
+ Evaluate Elisp {{{var(sexp)}}} and replace with the result. The
+ {{{var(sexp)}}} must return a string.
+
+- %<...> ::
+
+ The result of format-time-string on the ... format specification.
+
+- %t ::
+
+ Timestamp, date only.
+
+- %T ::
+
+ Timestamp, with date and time.
+
+- %u, %U ::
+
+ Like ~%t~, ~%T~ above, but inactive timestamps.
+
+- %i ::
+
+ Initial content, the region when capture is called while the region is
+ active. The entire text will be indented like ~%i~ itself.
+
+- %a ::
+
+ Annotation, normally the link created with ~org-store-link~.
+
+- %A ::
+
+ Like ~%a~, but prompt for the description part.
+
+- %l ::
+
+ Like ~%a~, but only insert the literal link.
+
+- %c ::
+
+ Current kill ring head.
+
+- %x ::
+
+ Content of the X clipboard.
+
+- %k ::
+
+ Title of the currently clocked task.
+
+- %K ::
+
+ Link to the currently clocked task.
+
+- %n ::
+
+ User name (taken from ~user-full-name~).
+
+- %f ::
+
+ File visited by current buffer when org-capture was called.
+
+- %F ::
+
+ Full path of the file or directory visited by current buffer.
+
+- %:keyword ::
+
+ Specific information for certain link types, see below.
+
+- %^g ::
+
+ Prompt for tags, with completion on tags in target file.
+
+- %^G ::
+
+ Prompt for tags, with completion all tags in all agenda files.
+
+- %^t ::
+
+ Like ~%t~, but prompt for date. Similarly ~%^T~, ~%^u~, ~%^U~. You may
+ define a prompt like ~%^{Birthday}t~.
+
+- %^C ::
+
+ Interactive selection of which kill or clip to use.
+
+- %^L ::
+
+ Like ~%^C~, but insert as link.
+
+- %^{PROP}p ::
+
+ Prompt the user for a value for property {{{var(prop)}}}.
+
+- %^{PROMPT} ::
+
+ Prompt the user for a string and replace this sequence with it. You
+ may specify a default value and a completion table with
+ ~%^{prompt|default|completion2|completion3...}~. The arrow keys access
+ a prompt-specific history.
+
+- %\n ::
+
+ Insert the text entered at the nth %^{PROMPT}, where ~n~ is
+ a number, starting from 1.
+
+- %? ::
+
+ After completing the template, position cursor here.
+
+
+{{{noindent}}} For specific link types, the following keywords will be
+defined:[fn:83]
+
+#+vindex: org-from-is-user-regexp
+
+
+#+attr_texinfo: :table-type table :indic @asis
+- bbdb :: ~%:name %:company~
+- irc :: ~%:server %:port %:nick~
+- vm vm-imap wl mh mew rmail ::
+ ~%:type %:subject %:message-id~
+ ~%:from %:fromname %:fromaddress~
+ ~%:to %:toname %:toaddress~
+ ~%:date~ (message date header field)
+ ~%:date-timestamp~ (date as active timestamp)
+ ~%:date-timestamp-inactive~ (date as inactive timestamp)
+ ~%:fromto~ (either "to NAME" or "from NAME")[fn:84]
+- gnus :: ~%:group~, for messages also all email fields
+- w3 w3m :: ~%:url~
+- info :: ~%:file %:node~
+- calendar :: ~%:date~
+
+{{{noindent}}} To place the cursor after template expansion use:
+
+#+begin_example
+ %? After completing the template, position cursor here.
+#+end_example
+
+**** Templates in contexts
+ :PROPERTIES:
+ :DESCRIPTION: Only show a template in a specific context
+ :END:
+
+#+vindex: org-capture-templates-contexts
+
+To control whether a capture template should be accessible from a
+specific context, you can customize ~org-capture-templates-contexts~.
+Let's say, for example, that you have a capture template "p" for
+storing Gnus emails containing patches. Then you would configure this
+option like this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-capture-templates-contexts
+ '(("p" (in-mode . "message-mode"))))
+#+end_src
+
+You can also tell that the command key "p" should refer to another
+template. In that case, add this command key like this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-capture-templates-contexts
+ '(("p" "q" (in-mode . "message-mode"))))
+#+end_src
+
+See the docstring of the variable ~org-capture-templates-contexts~ for
+more information.
+
+** Attachments
+ :PROPERTIES:
+ :DESCRIPTION: Add files to tasks
+ :END:
+#+cindex: attachments
+#+vindex: org-attach-directory
+
+It is often useful to associate reference material with an outline
+node/task. Small chunks of plain text can simply be stored in the
+subtree of a project. Hyperlinks (see [[Hyperlinks]]) can establish
+associations with files that live elsewhere on your computer or in the
+cloud, like emails or source code files belonging to a project.
+Another method is /attachments/, which are files located in a
+directory belonging to an outline node. Org uses directories named by
+the unique ID of each entry. These directories are located in the
+{{{file(data)}}} directory which lives in the same directory where
+your Org file lives.[fn:85] If you initialize this directory with
+~git init~, Org will automatically commit changes when it sees them.
+The attachment system has been contributed to Org by John Wiegley.
+
+In cases where it seems better to do so, you can also attach a
+directory of your choice to an entry. You can also make children
+inherit the attachment directory from a parent, so that an entire
+subtree uses the same attached directory.
+
+{{{noindent}}} The following commands deal with attachments:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-a)}}}, ~org-attach~ ::
+ #+kindex: C-c C-a
+
+ The dispatcher for commands related to the attachment system. After
+ these keys, a list of commands is displayed and you must press an
+ additional key to select a command:
+
+ - {{{kbd(a)}}}, ~org-attach-attach~ ::
+ #+kindex: C-c C-a a
+ #+vindex: org-attach-method
+
+ Select a file and move it into the task's attachment directory. The
+ file will be copied, moved, or linked, depending on
+ ~org-attach-method~. Note that hard links are not supported on all
+ systems.
+
+ - {{{kbd(c)}}}/{{{kbd(m)}}}/{{{kbd(l)}}} ::
+ #+kindex: C-c C-a c
+ #+kindex: C-c C-a m
+ #+kindex: C-c C-a l
+
+ Attach a file using the copy/move/link method. Note that hard links
+ are not supported on all systems.
+
+ - {{{kbd(n)}}}, ~org-attach-new~ ::
+ #+kindex: C-c C-a n
+
+ Create a new attachment as an Emacs buffer.
+
+ - {{{kbd(z)}}}, ~org-attach-sync~ ::
+ #+kindex: C-c C-a z
+
+ Synchronize the current task with its attachment directory, in case
+ you added attachments yourself.
+
+ - {{{kbd(o)}}}, ~org-attach-open~ ::
+ #+kindex: C-c C-a o
+ #+vindex: org-file-apps
+
+ Open current task's attachment. If there is more than one, prompt for
+ a file name first. Opening will follow the rules set by
+ ~org-file-apps~. For more details, see the information on following
+ hyperlinks (see [[Handling links]]).
+
+ - {{{kbd(O)}}}, ~org-attach-open-in-emacs~ ::
+ #+kindex: C-c C-a O
+
+ Also open the attachment, but force opening the file in Emacs.
+
+ - {{{kbd(f)}}}, ~org-attach-reveal~ ::
+ #+kindex: C-c C-a f
+
+ Open the current task's attachment directory.
+
+ - {{{kbd(F)}}}, ~org-attach-reveal-in-emacs~ ::
+ #+kindex: C-c C-a F
+
+ Also open the directory, but force using @command{dired} in Emacs.
+
+ - {{{kbd(d)}}}, ~org-attach-delete-one~ ::
+ #+kindex: C-c C-a d
+
+ Select and delete a single attachment.
+
+ - {{{kbd(D)}}}, ~org-attach-delete-all~ ::
+ #+kindex: C-c C-a D
+
+ Delete all of a task's attachments. A safer way is to open the
+ directory in {{{command(dired)}}} and delete from there.
+
+ - {{{kbd(s)}}}, ~org-attach-set-directory~ ::
+ #+kindex: C-c C-a s
+ #+cindex: property, ATTACH_DIR
+
+ Set a specific directory as the entry's attachment directory. This
+ works by putting the directory path into the ~ATTACH_DIR~ property.
+
+ - {{{kbd(i)}}}, ~org-attach-set-inherit~ ::
+ #+kindex: C-c C-a i
+ #+cindex: property, ATTACH_DIR_INHERIT
+
+ Set the ~ATTACH_DIR_INHERIT~ property, so that children will use the
+ same directory for attachments as the parent does.
+
+** RSS feeds
+ :PROPERTIES:
+ :DESCRIPTION: Getting input from RSS feeds
+ :END:
+#+cindex: RSS feeds
+#+cindex: Atom feeds
+
+Org can add and change entries based on information found in RSS feeds and
+Atom feeds. You could use this to make a task out of each new podcast in a
+podcast feed. Or you could use a phone-based note-creating service on the
+web to import tasks into Org. To access feeds, configure the variable
+~org-feed-alist~. The docstring of this variable has detailed
+information. Here is an example:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-feed-alist
+ '(("Slashdot"
+ "http://rss.slashdot.org/Slashdot/slashdot"
+ "~/txt/org/feeds.org" "Slashdot Entries")))
+#+end_src
+
+{{{noindent}}} will configure that new items from the feed provided by
+~rss.slashdot.org~ will result in new entries in the file
+{{{file(~/org/feeds.org)}}} under the heading ~Slashdot Entries~,
+whenever the following command is used:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x g)}}}, ~org-feed-update-all~ ::
+ #+kindex: C-c C-x g
+
+ Collect items from the feeds configured in ~org-feed-alist~ and act
+ upon them.
+
+- {{{kbd(C-c C-x G)}}}, ~org-feed-goto-inbox~ ::
+ #+kindex: C-c C-x G
+
+ Prompt for a feed name and go to the inbox configured for this feed.
+
+
+Under the same headline, Org will create a drawer
+{{{samp(FEEDSTATUS)}}} in which it will store information about the
+status of items in the feed, to avoid adding the same item several
+times. You should add {{{samp(FEEDSTATUS)}}} to the list of drawers in
+that file:
+
+#+begin_example
+ ,#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
+#+end_example
+
+For more information, including how to read atom feeds, see
+{{{file(org-feed.el)}}} and the docstring of ~org-feed-alist~.
+
+** Protocols
+ :PROPERTIES:
+ :DESCRIPTION: External (e.g., browser) access to Emacs and Org
+ :TITLE: Protocols for external access
+ :END:
+
+#+cindex: protocols, for external access
+#+cindex: emacsserver
+
+You can set up Org for handling protocol calls from outside
+applications that are passed to Emacs through the
+{{{file(emacsserver)}}}. For example, you can configure bookmarks in
+your web browser to send a link to the current page to Org and create
+a note from it using capture (see [[Capture]]). Or you could create a
+bookmark that will tell Emacs to open the local source file of a
+remote website you are looking at with the browser. See
+[[http://orgmode.org/worg/org-contrib/org-protocol.php]] for detailed
+documentation and setup instructions.
+
+** Refile and copy
+ :PROPERTIES:
+ :DESCRIPTION: Moving/copying a tree from one place to another
+ :END:
+#+cindex: refiling notes
+#+cindex: copying notes
+
+When reviewing the captured data, you may want to refile or to copy some of
+the entries into a different list, for example into a project. Cutting,
+finding the right location, and then pasting the note is cumbersome. To
+simplify this process, you can use the following special command:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c M-w)}}}, ~org-copy~ ::
+ #+kindex: C-c M-w
+ #+findex: org-copy
+
+ Copying works like refiling, except that the original note is not deleted.
+
+- {{{kbd(C-c C-w)}}}, ~org-refile~ ::
+ #+kindex: C-c C-w
+ #+findex: org-refile
+ #+vindex: org-reverse-note-order
+ #+vindex: org-refile-targets
+ #+vindex: org-refile-use-outline-path
+ #+vindex: org-outline-path-complete-in-steps
+ #+vindex: org-refile-allow-creating-parent-nodes
+ #+vindex: org-log-refile
+ #+vindex: org-refile-use-cache
+
+ Refile the entry or region at point. This command offers possible
+ locations for refiling the entry and lets you select one with
+ completion. The item (or all items in the region) is filed below the
+ target heading as a subitem. Depending on ~org-reverse-note-order~, it
+ will be either the first or last subitem.
+
+ By default, all level 1 headlines in the current buffer are considered
+ to be targets, but you can have more complex definitions across a
+ number of files. See the variable ~org-refile-targets~ for details. If
+ you would like to select a location via a file-path-like completion
+ along the outline path, see the variables
+ ~org-refile-use-outline-path~ and
+ ~org-outline-path-complete-in-steps~. If you would like to be able to
+ create new nodes as new parents for refiling on the fly, check the
+ variable ~org-refile-allow-creating-parent-nodes~. When the variable
+ ~org-log-refile~ is set, a timestamp or a note will be recorded when
+ an entry has been refiled.[fn:86]
+
+- {{{kbd(C-u C-c C-w)}}} ::
+ #+kindex: C-u C-c C-w
+
+ Use the refile interface to jump to a heading.
+
+- {{{kbd(C-u C-u C-c C-w)}}}, ~org-refile-goto-last-stored~ ::
+ #+kindex: C-u C-u C-c C-w
+
+ Jump to the location where ~org-refile~ last moved a tree to.
+
+- {{{kbd(C-2 C-c C-w)}}} ::
+ #+kindex: C-2 C-c C-w
+
+ Refile as the child of the item currently being clocked.
+
+- {{{kbd(C-0 C-c C-w)}}} or {{{kbd(C-u C-u C-u C-c C-w)}}}, ~org-refile-cache-clear~ ::
+ #+kindex: C-u C-u C-u C-c C-w
+ #+kindex: C-0 C-c C-w
+
+ Clear the target cache. Caching of refile targets can be turned on by
+ setting ~org-refile-use-cache~. To make the command see new possible
+ targets, you have to clear the cache with this command.
+
+** Archiving
+ :PROPERTIES:
+ :DESCRIPTION: What to do with finished products
+ :END:
+#+cindex: archiving
+
+When a project represented by a (sub)tree is finished, you may want to
+move the tree out of the way and to stop it from contributing to the
+agenda. Archiving is important to keep your working files compact and
+global searches like the construction of agenda views fast.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-a)}}}, ~org-archive-subtree-default~ ::
+ #+kindex: C-c C-x C-a
+ #+vindex: org-archive-default-command
+
+ Archive the current entry using the command specified in the variable
+ ~org-archive-default-command~.
+
+*** Moving subtrees
+ :PROPERTIES:
+ :DESCRIPTION: Moving a tree to an archive file
+ :TITLE: Moving a tree to an archive file
+ :END:
+#+cindex: external archiving
+
+The most common archiving action is to move a project tree to another file,
+the archive file.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}}, ~org-archive-subtree~ ::
+ #+kindex: C-c C-x C-s
+ #+kindex: C-c $
+ #+vindex: org-archive-location
+
+ Archive the subtree starting at the cursor position to the location
+ given by ~org-archive-location~.
+
+- {{{Kbd(C-u C-c C-x C-s)}}} ::
+ #+kindex: C-u C-c C-x C-s
+
+ Check if any direct children of the current headline could be moved to
+ the archive. To do this, each subtree is checked for open TODO
+ entries. If none are found, the command offers to move it to the
+ archive location. If the cursor is /not/ on a headline when this
+ command is invoked, the level 1 trees will be checked.
+
+
+#+cindex: archive locations
+
+The default archive location is a file in the same directory as the
+current file, with the name derived by appending {{{file(_archive)}}}
+to the current file name. You can also choose what heading to file
+archived items under, with the possibility to add them to a datetree
+in a file. For information and examples on how to specify the file and
+the heading, see the documentation string of the variable
+~org-archive-location~.
+
+There is also an in-buffer option for setting this variable, for
+example:[fn:87]
+
+#+cindex: #+ARCHIVE
+#+begin_example
+ ,#+ARCHIVE: %s_done::
+#+end_example
+
+#+cindex: property, ARCHIVE
+
+{{{noindent}}} If you would like to have a special ARCHIVE location
+for a single entry or a (sub)tree, give the entry an ~:ARCHIVE:~
+property with the location as the value (see [[Properties and columns]]).
+
+#+vindex: org-archive-save-context-info
+
+When a subtree is moved, it receives a number of special properties
+that record context information like the file from where the entry
+came, its outline path the archiving time etc. Configure the variable
+~org-archive-save-context-info~ to adjust the amount of information
+added.
+
+*** Internal archiving
+ :PROPERTIES:
+ :DESCRIPTION: Switch off a tree but keep it in the file
+ :END:
+
+If you want to just switch off (for agenda views) certain subtrees
+without moving them to a different file, you can use the ~ARCHIVE
+tag~.
+
+A headline that is marked with the ARCHIVE tag (see [[Tags]]) stays at
+its location in the outline tree, but behaves in the following way:
+
+- It does not open when you attempt to do so with a visibility cycling
+ command (see [[Visibility cycling]]). You can force cycling archived
+ subtrees with {{{kbdkey(C-,TAB)}}}, or by setting the option
+ ~org-cycle-open-archived-trees~. Also normal outline commands like
+ ~show-all~ will open archived subtrees.
+
+ #+vindex: org-cycle-open-archived-trees
+
+- During sparse tree construction (see [[Sparse trees]]), matches in
+ archived subtrees are not exposed, unless you configure the option
+ ~org-sparse-tree-open-archived-trees~.
+
+ #+vindex: org-sparse-tree-open-archived-trees
+
+- During agenda view construction (see [[Agenda views]]), the content of
+ archived trees is ignored unless you configure the option
+ ~org-agenda-skip-archived-trees~, in which case these trees will
+ always be included. In the agenda you can press {{{kbd(v a)}}} to
+ get archives temporarily included.
+
+ #+vindex: org-agenda-skip-archived-trees
+
+- Archived trees are not exported (see [[Exporting]]), only the headline
+ is. Configure the details using the variable
+ ~org-export-with-archived-trees~.
+
+ #+vindex: org-export-with-archived-trees
+
+- Archived trees are excluded from column view unless the variable
+ ~org-columns-skip-archived-trees~ is configured to ~nil~.
+
+ #+vindex: org-columns-skip-archived-trees
+
+
+The following commands help manage the ARCHIVE tag:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x a)}}}, ~org-toggle-archive-tag~ ::
+ #+kindex: C-c C-x a
+
+ Toggle the ARCHIVE tag for the current headline. When the tag is set,
+ the headline changes to a shadowed face, and the subtree below it is
+ hidden.
+
+- {{{kbd(C-u C-c C-x a)}}} ::
+ #+kindex: C-u C-c C-x a
+
+ Check if any direct children of the current headline should be
+ archived. To do this, each subtree is checked for open TODO entries.
+ If none are found, the command offers to set the ARCHIVE tag for the
+ child. If the cursor is /not/ on a headline when this command is
+ invoked, the level 1 trees will be checked.
+
+- {{{kbdkey(C-,TAB)}}}, ~org-force-cycle-archived~ ::
+
+ Cycle a tree even if it is tagged with ARCHIVE.
+
+- {{{kbd(C-c C-x A)}}}, ~org-archive-to-archive-sibling~ ::
+ #+kindex: C-c C-x A
+
+ Move the current entry to the /Archive Sibling/. This is a sibling of
+ the entry with the heading {{{samp(Archive)}}} and the tag
+ {{{samp(ARCHIVE)}}}. The entry becomes a child of that sibling and in
+ this way retains a lot of its original context, including inherited
+ tags and approximate position in the outline.
+
+* FIXME Agenda views
+ :PROPERTIES:
+ :DESCRIPTION: Collecting information into views
+ :ALT_TITLE: Agenda Views
+ :END:
+
+Due to the way Org works, TODO items, time-stamped items, and tagged
+headlines can be scattered throughout a file or even a number of
+files. To get an overview of open action items, or of events that are
+important for a particular date, this information must be collected,
+sorted and displayed in an organized way.
+
+Org can select items based on various criteria and display them
+in a separate buffer. Seven different view types are provided:
+
+- an /agenda/ that is like a calendar and shows information for
+ specific dates,
+
+- a /TODO list/ that covers all unfinished action items,
+
+- a /match view/, showings headlines based on the tags, properties,
+ and TODO state associated with them,
+
+- a /timeline view/ that shows all events in a single Org file, in
+ time-sorted view,
+
+- a /text search view/ that shows all entries from multiple files that
+ contain specified keywords,
+
+- a /stuck projects view/ showing projects that currently don't move
+ along, and
+
+- /custom views/ that are special searches and combinations of
+ different views.
+
+
+{{{noindent}}} The extracted information is displayed in a special
+/agenda buffer/. This buffer is read-only, but provides commands to
+visit the corresponding locations in the original Org files, and even
+to edit these files remotely.
+
+#+vindex: org-agenda-window-setup
+#+vindex: org-agenda-restore-windows-after-quit
+
+Two variables control how the agenda buffer is displayed and whether
+the window configuration is restored when the agenda exits:
+~org-agenda-window-setup~ and ~org-agenda-restore-windows-after-quit~.
+
+** Agenda files
+ :PROPERTIES:
+ :DESCRIPTION: Files being searched for agenda information
+ :END:
+#+cindex: agenda files
+#+cindex: files for agenda
+#+vindex: org-agenda-files
+
+The information to be shown is normally collected from all /agenda
+files/, the files listed in the variable ~org-agenda-files~.[fn:180] If
+a directory is part of this list, all files with the extension
+{{{file(.org)}}} in this directory will be part of the list.
+
+Thus, even if you only work with a single Org file, that file should
+be put into the list.[fn:88] You can customize ~org-agenda-files~, but
+the easiest way to maintain it is through the following commands
+
+#+cindex: files, adding to agenda list
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c [)}}}, ~org-agenda-file-to-front~ ::
+ #+kindex: C-c [
+
+ Add current file to the list of agenda files. The file is added to the
+ front of the list. If it was already in the list, it is moved to the
+ front. With a prefix argument, file is added/moved to the end.
+
+- {{{kbd(C-c ])}}}, ~org-remove-file~ ::
+ #+kindex: C-c ]
+
+ Remove current file from the list of agenda files.
+
+- {{{kbd(C-')}}} {{{kbd(C-)}}}, ~org-cycle-agenda-files~ ::
+ #+kindex: C-'
+ #+kindex: C-,
+ #+cindex: cycling, of agenda files
+
+ Cycle through agenda file list, visiting one file after the other.
+
+- {{{kbd(M-x org-iswitchb)}}} ::
+ #+findex: org-iswitchb
+
+ Command to use an ~iswitchb~-like interface to switch to and between
+ Org buffers.
+
+
+{{{noindent}}} The Org menu contains the current list of files and can
+be used to visit any of them.
+
+If you would like to focus the agenda temporarily on a file not in
+this list, or on just one file in the list, or even on only a subtree
+in a file, then this can be done in different ways. For a single
+agenda command, you may press {{{kbd(<)}}} once or several times in
+the dispatcher (see [[Agenda dispatcher]]). To restrict the agenda scope
+for an extended period, use the following commands:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x <)}}}, ~org-agenda-set-restriction-lock~ ::
+ #+kindex: C-c C-x <
+
+ Permanently restrict the agenda to the current subtree. When with a
+ prefix argument, or with the cursor before the first headline in a
+ file, the agenda scope is set to the entire file. This restriction
+ remains in effect until removed with {{{kbd(C-c C-x >)}}}, or by
+ typing either {{{kbd(<)}}} or {{{kbd(>)}}} in the agenda dispatcher.
+ If there is a window displaying an agenda view, the new restriction
+ takes effect immediately.
+
+- {{{kbd(C-c C-x >)}}}, ~org-agenda-remove-restriction-lock~ ::
+ #+kindex: C-c C-x >
+
+ Remove the permanent restriction created by {{{kbd(C-c C-x <)}}}.
+
+
+{{{noindent}}} When working with {{{file(speedbar.el)}}}, you can use
+the following commands in the Speedbar frame:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(<)}}} in the speedbar frame ~org-speedbar-set-agenda-restriction~ ::
+ #+kindex: <
+
+ Permanently restrict the agenda to the item---either an Org file or a
+ subtree in such a file---at the cursor in the Speedbar frame. If there
+ is a window displaying an agenda view, the new restriction takes
+ effect immediately.
+
+- {{{kbd(>)}}} in the speedbar frame ~org-agenda-remove-restriction-lock~ ::
+ #+kindex: >
+
+ Lift the restriction.
+
+** Agenda dispatcher
+ :PROPERTIES:
+ :DESCRIPTION: Keyboard access to agenda views
+ :TITLE: The agenda dispatcher
+ :END:
+#+cindex: agenda dispatcher
+#+cindex: dispatching agenda commands
+
+The views are created through a dispatcher, which should be bound to a
+global key---for example {{{kbd(C-c a)}}} (see [[Activation]]). In the
+following we will assume that {{{kbd(C-c a)}}} is indeed how the
+dispatcher is accessed and list keyboard access to commands
+accordingly. After pressing {{{kbd(C-c a)}}}, an additional letter is
+required to execute a command. The dispatcher offers the following
+default commands:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(a)}}} ::
+ #+kindex: C-c a a
+
+ Create the calendar-like agenda (see [[Weekly/daily agenda]]).
+
+- {{{kbd(t)}}} or {{{kbd(T)}}} ::
+ #+kindex: C-c a t
+ #+kindex: C-c a T
+
+ Create a list of all TODO items (see [[Global TODO list]]).
+
+- {{{kbd(m)}}} or {{{kbd(M)}}} ::
+ #+kindex: C-c a m
+ #+kindex: C-c a M
+
+ Create a list of headlines matching a TAGS expression (see [[Matching tags and properties]]).
+
+- {{{kbd(L)}}} ::
+ #+kindex: C-c a L
+
+ Create the timeline view for the current buffer
+ (see [[Timeline for a single file]]).
+
+- {{{kbd(s)}}} ::
+ #+kindex: C-c a s
+
+ Create a list of entries selected by a boolean expression of keywords
+ and/or regular expressions that must or must not occur in the entry.
+
+- {{{kbd(/)}}} ::
+ #+kindex: C-c a /
+ #+vindex: org-agenda-text-search-extra-files
+
+ Search for a regular expression in all agenda files and additionally
+ in the files listed in ~org-agenda-text-search-extra-files~. This uses
+ the Emacs command ~multi-occur~. A prefix argument can be used to
+ specify the number of context lines for each match, default is
+ 1.
+
+- {{{kbd(#)}}} or {{{kbd(!)}}} ::
+ #+kindex: C-c a #
+ #+kindex: C-c a !
+ Create a list of stuck projects (see [[Stuck projects]]).
+
+- {{{kbd(<)}}} ::
+ #+kindex: C-c a <
+
+ Restrict an agenda command to the current buffer.[fn:89] After
+ pressing {{{kbd(<)}}}, you still need to press the character selecting
+ the command.
+
+- {{{kbd(< <)}}} ::
+ #+kindex: C-c a < <
+
+ If there is an active region, restrict the following agenda command to
+ the region. Otherwise, restrict it to the current subtree.[fn:90]
+ After pressing {{{kbd(< <)}}}, you still need to press the character
+ selecting the command.
+
+- {{{kbd(*)}}} ::
+ #+kindex: C-c a *
+ #+vindex: org-agenda-sticky
+
+ Toggle sticky agenda views. By default, Org maintains only a single
+ agenda buffer and rebuilds it each time you change the view, to make
+ sure everything is always up to date. If you switch between views
+ often and the build time bothers you, you can turn on sticky agenda
+ buffers (make this the default by customizing the variable
+ ~org-agenda-sticky~). With sticky agendas, the dispatcher only
+ switches to the selected view, you need to update it by hand with
+ {{{kbd(r)}}} or {{{kbd(g)}}}. You can toggle sticky agenda view any
+ time with ~org-toggle-sticky-agenda~.
+
+
+You can also define custom commands that will be accessible through
+the dispatcher, just like the default commands. This includes the
+possibility to create extended agenda buffers that contain several
+blocks together, for example the weekly agenda, the global TODO list
+and a number of special tags matches. See [[Custom agenda views]].
+
+** Built-in agenda views
+ :PROPERTIES:
+ :DESCRIPTION: What is available out of the box?
+ :TITLE: The built-in agenda views
+ :END:
+In this section we describe the built-in views.
+
+*** FIXED Weekly/daily agenda
+ :PROPERTIES:
+ :DESCRIPTION: The calendar page with current tasks
+ :END:
+#+cindex: agenda
+#+cindex: weekly agenda
+#+cindex: daily agenda
+
+The purpose of the weekly/daily /agenda/ is to act like a page of a
+paper agenda, showing all the tasks for the current week or day.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a a)}}}, ~org-agenda-list~ ::
+ #+cindex: org-agenda, command
+
+ Compile an agenda for the current week from a list of Org files. The
+ agenda shows the entries for each day. With a numeric prefix (like
+ {{{kbd(C-u 2 1 C-c a a)}}}) you may set the number of days to be
+ displayed.[fn:91]
+
+
+#+vindex: org-agenda-span
+#+vindex: org-agenda-ndays
+The default number of days displayed in the agenda is set by the variable
+~org-agenda-span~ (or the obsolete ~org-agenda-ndays~). This
+variable can be set to any number of days you want to see by default in the
+agenda, or to a span name, such a ~day~, ~week~, ~month~ or
+~year~.
+
+Remote editing from the agenda buffer means, for example, that you can
+change the dates of deadlines and appointments from the agenda buffer.
+The commands available in the Agenda buffer are listed in [[Agenda
+commands]].
+
+**** FIXED Calendar/Diary integration
+ :PROPERTIES:
+ :DESCRIPTION: Integrate the Emacs diary with Org
+ :END:
+#+cindex: calendar integration
+#+cindex: diary integration
+#+cindex: Reingold, Edward M.
+
+Emacs contains the calendar and diary by Edward M. Reingold. The
+calendar displays a three-month calendar with holidays from different
+countries and cultures. The diary allows you to keep track of
+anniversaries, lunar phases, sunrise/set, recurrent appointments
+(weekly, monthly) and more. In this way, it is quite complementary to
+Org. It can be very useful to combine output from Org with
+the diary.
+
+In order to include entries from the Emacs diary into Org mode's
+agenda, you only need to customize the variable
+
+#+begin_src emacs-lisp
+ (setq org-agenda-include-diary t)
+#+end_src
+
+{{{noindent}}} After that, everything will happen automatically. All diary
+entries including holidays, anniversaries, etc., will be included in the
+agenda buffer created by Org mode. {{{key(SPC)}}}, {{{key(TAB)}}}, and
+{{{key(RET)}}} can be used from the agenda buffer to jump to the diary
+file in order to edit existing diary entries. The {{{kbd(i)}}} command to
+insert new entries for the current date works in the agenda buffer, as
+well as the commands {{{kbd(S)}}}, {{{kbd(M)}}}, and {{{kbd(C)}}} to display
+Sunrise/Sunset times, show lunar phases and to convert to other
+calendars, respectively. {{{kbd(c)}}} can be used to switch back and forth
+between calendar and agenda.
+
+If you are using the diary only for sexp entries and holidays, it is
+faster to not use the above setting, but instead to copy or even move
+the entries into an Org file. Org mode evaluates diary-style sexp
+entries, and does it faster because there is no overhead for first
+creating the diary display. Note that the sexp entries must start at
+the left margin, no whitespace is allowed before them. For example,
+the following segment of an Org file will be processed and entries
+will be made in the agenda:[fn:181]
+
+#+begin_example
+ ,* Birthdays and similar stuff
+ ,#+CATEGORY: Holiday
+ %%(org-calendar-holiday) ; special function for holiday names
+ ,#+CATEGORY: Ann
+ %%(org-anniversary 1956 5 14) Arthur Dent is %d years old
+ %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
+#+end_example
+
+**** FIXED Anniversaries from BBDB
+ :PROPERTIES:
+ :DESCRIPTION: Integrate Big Brother Database and Org
+ :END:
+
+#+cindex: BBDB, anniversaries
+#+cindex: anniversaries, from BBDB
+
+If you are using the Big Brothers Database to store your contacts, you will
+very likely prefer to store anniversaries in BBDB rather than in a
+separate Org or diary file. Org supports this and will show BBDB
+anniversaries as part of the agenda. All you need to do is to add the
+following to one of your agenda files:
+
+#+begin_example
+ ,* Anniversaries
+ , :PROPERTIES:
+ , :CATEGORY: Anniv
+ , :END:
+ ,%%(org-bbdb-anniversaries)
+#+end_example
+
+You can then go ahead and define anniversaries for a BBDB record.
+Basically, you need to press {{{kbdspckey(C-o anniversary,RET)}}} with
+the cursor in a BBDB record and then add the date in the format
+~YYYY-MM-DD~ or ~MM-DD~, followed by a space and the class of the
+anniversary ({{{samp(birthday)}}} or {{{samp(wedding)}}}, or a format
+string). If you omit the class, it will default to
+{{{samp(birthday)}}}. Here are a few examples, the header for the file
+{{{file(org-bbdb.el)}}} contains more detailed information.
+
+#+begin_example
+ 1973-06-22
+ 06-22
+ 1955-08-02 wedding
+ 2008-04-14 %s released version 6.01 of org mode, %d years ago
+#+end_example
+
+After a change to BBDB, or for the first agenda display during an
+Emacs session, the agenda display will suffer a short delay as Org
+updates its hash with anniversaries. However, from then on things will
+be very fast---much faster in fact than a long list of
+{{{samp(%%(diary-anniversary))}}} entries in an Org or Diary file.
+
+**** FIXED Appointment reminders
+ :PROPERTIES:
+ :DESCRIPTION: Integrate the Emacs appointment facility and Org
+ :END:
+#+cindex: @file{appt.el}
+#+cindex: appointment reminders
+#+cindex: appointment
+#+cindex: reminders
+
+Org can interact with Emacs appointments notification facility. To add the
+appointments of your agenda files, use the command ~org-agenda-to-appt~.
+This command lets you filter through the list of your appointments and add
+only those belonging to a specific category or matching a regular expression.
+It also reads a ~APPT_WARNTIME~ property which will then override the
+value of ~appt-message-warning-time~ for this appointment. See the
+docstring for details.
+
+*** FIXED Global TODO list
+ :PROPERTIES:
+ :DESCRIPTION: All unfinished action items
+ :END:
+#+cindex: global TODO list
+#+cindex: TODO list, global
+
+The global TODO list contains all unfinished TODO items formatted and
+collected into a single place.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a t)}}}, ~org-todo-list~ ::
+
+ Show the global TODO list. This collects the TODO items from all
+ agenda files (see [[Agenda views]]) into a single buffer. By default, this
+ lists items with a state the is not a DONE state. The buffer is in
+ ~agenda-mode~, so there are commands to examine and manipulate the
+ TODO entries directly from that buffer (see [[Agenda commands]]).
+
+- {{{kbd(C-c a T)}}}, ~org-todo-list~ ::
+
+ #+cindex: TODO keyword matching
+ #+vindex: org-todo-keywords
+
+ Like the above, but allows selection of a specific TODO keyword. You
+ can also do this by specifying a prefix argument to {{{kbd(C-c a
+ t)}}}. You are prompted for a keyword, and you may also specify
+ several keywords by separating them with {{{samp(|)}}} as the boolean
+ OR operator. With a numeric prefix, the Nth keyword in
+ ~org-todo-keywords~ is selected.
+
+ #+kindex: r
+
+ The {{{kbd(r)}}} key in the agenda buffer regenerates it, and you can give
+ a prefix argument to this command to change the selected TODO keyword,
+ for example {{{kbd(3 r)}}}. If you often need a search for a specific
+ keyword, define a custom command for it (see [[Agenda dispatcher]]).
+
+ Matching specific TODO keywords can also be done as part of a tags
+ search (see [[Tag searches]]).
+
+
+Remote editing of TODO items means that you can change the state of a
+TODO entry with a single key press. The commands available in the
+TODO list are described in [[Agenda commands]].
+
+#+cindex: sublevels, inclusion into TODO list
+
+Normally the global TODO list simply shows all headlines with TODO
+keywords. This list can become very long. There are two ways to keep
+it more compact:
+
+
+- Some people view a TODO item that has been /scheduled/ for execution
+ or have a /deadline/ (see [[Timestamps]]) as no longer /open/. Configure
+ the variables ~org-agenda-todo-ignore-scheduled~,
+ ~org-agenda-todo-ignore-deadlines~,
+ ~org-agenda-todo-ignore-timestamp~ and/or
+ ~org-agenda-todo-ignore-with-date~ to exclude such items from the
+ global TODO list.
+
+ #+vindex: org-agenda-todo-ignore-scheduled
+ #+vindex: org-agenda-todo-ignore-deadlines
+ #+vindex: org-agenda-todo-ignore-timestamp
+ #+vindex: org-agenda-todo-ignore-with-date
+
+- TODO items may have sublevels to break up the task into subtasks. In
+ such cases it may be enough to list only the highest level TODO
+ headline and omit the sublevels from the global list. Configure the
+ variable ~org-agenda-todo-list-sublevels~ to get this behavior.
+
+ #+vindex: org-agenda-todo-list-sublevels
+
+*** Matching tags and properties
+ :PROPERTIES:
+ :DESCRIPTION: Structured information with fine-tuned search
+ :END:
+#+cindex: matching, of tags
+#+cindex: matching, of properties
+#+cindex: tags view
+#+cindex: match view
+
+If headlines in the agenda files are marked with /tags/ (see [[Tags]]), or
+have properties (see [[Properties and columns]]), you can select headlines
+based on this metadata and collect them into an agenda buffer. The
+match syntax described here also applies when creating sparse trees
+with {{{kbd(C-c / m)}}}.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
+
+ Produce a list of all headlines that match a given set of tags. The
+ command prompts for a selection criterion, which is a boolean logic
+ expression with tags, like {{{samp(+work+urgent-withboss)}}} or
+ {{{samp(work|home)}}} (see [[Tags]]). If you often need a specific search,
+ define a custom command for it (see [[Agenda dispatcher]]).
+
+- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
+
+ #+vindex: org-tags-match-list-sublevels
+ #+vindex: org-agenda-tags-todo-honor-ignore-options
+
+ Like {{{kbd(C-c a m)}}}, but only select headlines that are also TODO
+ items in a not-DONE state and force checking subitems (see the variable
+ ~org-tags-match-list-sublevels~). To exclude scheduled/deadline items,
+ see the variable ~org-agenda-tags-todo-honor-ignore-options~. Matching
+ specific TODO keywords together with a tags match is also possible,
+ see [[Tag searches]].
+
+
+The commands available in the tags list are described in [[Agenda
+commands]].
+
+
+#+cindex: Boolean logic, for tag or property searches
+
+A search string can use Boolean operators {{{samp(&)}}} for AND and
+{{{samp(|)}}} for OR. {{{samp(&)}}} binds more strongly than
+{{{samp(|)}}}. Parentheses are currently not implemented. Each element
+in the search is either a tag, a regular expression matching tags, or
+an expression like ~PROPERTY OPERATOR VALUE~ with a comparison
+operator, accessing a property value. Each element may be preceded by
+{{{samp(-)}}}, to select against it, and {{{samp(+)}}} is syntactic
+sugar for positive selection. The AND operator {{{samp(&)}}} is
+optional when {{{samp(+)}}} or {{{samp(-)}}} is present. Here are some
+examples, using only tags.
+
+#+attr_texinfo: :table-type table :indic @samp
+- +work-boss ::
+
+ Select headlines tagged {{{samp(:work:)}}}, but discard those also
+ tagged {{{samp(:boss:)}}}.
+
+- work|laptop ::
+
+ Selects lines tagged {{{samp(:work:)}}} or {{{samp(:laptop:)}}}.
+
+- work|laptop+night ::
+
+ Like before, but require the {{{samp(:laptop:)}}} lines to be tagged
+ also {{{samp(:night:)}}}.
+
+
+#+cindex: regular expressions, with tags search
+
+Instead of a tag, you may also specify a regular expression enclosed
+in curly braces. For example, {{{samp(work+{^boss.*})}}} matches
+headlines that contain the tag {{{samp(:work:)}}} and any tag
+/starting/ with {{{samp(boss)}}}.
+
+#+cindex: TODO keyword matching, with tags search
+#+cindex: level, require for tags/property match
+#+cindex: category, require for tags/property match
+#+vindex: org-odd-levels-only
+
+You may also test for properties (see [[Properties and columns]]) at the
+same time as matching tags. The properties may be real properties, or
+special properties that represent other metadata (see [[Special
+properties]]). For example, the "property" ~TODO~ represents the TODO
+keyword of the entry. Or, the "property" ~LEVEL~ represents the
+level of an entry. So a search {{{samp(+LEVEL=3+boss-TODO="DONE")}}}
+lists all level three headlines that have the tag {{{samp(boss)}}} and
+are /not/ marked with the TODO keyword DONE. In buffers with
+~org-odd-levels-only~ set, {{{samp(LEVEL)}}} does not count the number
+of stars, but {{{samp(LEVEL=2)}}} will correspond to 3 stars etc. The
+ITEM special property cannot currently be used in tags/property
+searches.[fn:92]
+
+Here are more examples:
+
+#+attr_texinfo: :table-type table :indic @samp
+- work+TODO="WAITING" ::
+
+ Select {{{samp(:work:)}}}-tagged TODO lines with the specific TODO
+ keyword {{{samp(WAITING)}}}.
+
+- work+TODO="WAITING"|home+TODO="WAITING" ::
+
+ Waiting tasks both at work and at home.
+
+
+When matching properties, a number of different operators can be used to test
+the value of a property. Here is a complex example:
+
+#+begin_example
+ +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
+ +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>"
+#+end_example
+
+{{{noindent}}} The type of comparison will depend on how the
+comparison value is written:
+
+- If the comparison value is a plain number, a numerical comparison is
+ done, and the allowed operators are ~<~, ~=~, ~>~, ~<=~, ~>=~, and
+ ~<>~.
+
+- If the comparison value is enclosed in double-quotes, a string
+ comparison is done, and the same operators are allowed.
+
+- If the comparison value is enclosed in double-quotes /and/ angular
+ brackets (like {{{samp(DEADLINE<="<2008-12-24 18:30>")}}}), both
+ values are assumed to be date/time specifications in the standard
+ Org way, and the comparison will be done accordingly. Special values
+ that will be recognized are ~"<now>"~ for now (including time), and
+ ~"<today>"~, and ~"<tomorrow>"~ for these days at 0:00 hours, i.e.@:
+ without a time specification. Also strings like ~"<+5d>"~ or
+ ~"<-2m>"~ with units ~d~, ~w~, ~m~, and ~y~ for day, week, month,
+ and year, respectively, can be used.
+
+- If the comparison value is enclosed in curly braces, a regexp match
+ is performed, with {{{samp(=)}}} meaning that the regexp matches the
+ property value, and ~<>~ meaning that it does not match.
+
+
+So the search string in the example finds entries tagged
+{{{samp(:work:)}}} but not {{{samp(:boss:)}}}, which also have a
+priority value {{{samp(A)}}}, a {{{samp(:Coffee:)}}} property with the
+value {{{samp(unlimited)}}}, an {{{samp(Effort)}}} property that is
+numerically smaller than 2, a {{{samp(:With:)}}} property that is
+matched by the regular expression {{{samp(Sarah|Denny)}}}, and that
+are scheduled on or after October 11, 2008.
+
+Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing
+any other properties will slow down the search. However, once you have
+paid the price by accessing one property, testing additional
+properties is cheap again.
+
+You can configure Org mode to use property inheritance during a
+search, but beware that this can slow down searches considerably. See
+[[Property inheritance]], for details.
+
+For backward compatibility, and also for typing speed, there is also a
+different way to test TODO states in a search. For this, terminate the
+tags/property part of the search string (which may include several
+terms connected with {{{samp(|)}}}) with a {{{samp(/)}}} and then
+specify a Boolean expression just for TODO keywords. The syntax is
+then similar to that for tags, but should be applied with care: for
+example, a positive selection on several TODO keywords cannot
+meaningfully be combined with boolean AND. However, /negative
+selection/ combined with AND can be meaningful. To make sure that only
+lines are checked that actually have any TODO keyword (resulting in a
+speed-up), use {{{kbd(C-c a M)}}}, or equivalently start the TODO part
+after the slash with {{{samp(!)}}}. Using {{{kbd(C-c a M)}}} or
+{{{samp(/!)}}} will not match TODO keywords in a DONE state. Examples:
+
+#+attr_texinfo: :table-type table :indic @samp
+- work/WAITING ::
+
+ Same as {{{samp(work+TODO="WAITING")}}}
+
+- work/!-WAITING-NEXT ::
+
+ Select {{{samp(:work:)}}}-tagged TODO lines that are neither {{{samp(WAITING)}}}
+ nor {{{samp(NEXT)}}}
+
+- work/!+WAITING|+NEXT ::
+
+ Select {{{samp(:work:)}}}-tagged TODO lines that are either
+ {{{samp(WAITING)}}} or {{{samp(NEXT)}}}.
+
+*** FIXED Timeline for a single file
+ :PROPERTIES:
+ :DESCRIPTION: Time-sorted view for a single file
+ :ALT_TITLE: Timeline
+ :END:
+
+#+cindex: timeline, single file
+#+cindex: time-sorted view
+
+The timeline summarizes all time-stamped items from a single Org mode
+file in a /time-sorted view/. The main purpose of this command is
+to give an overview over events in a project.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a L)}}}, ~org-timeline~ ::
+
+ Show a time-sorted view of the Org file, with all time-stamped items.
+ When called with a {{{kbd(C-u)}}} prefix, all unfinished TODO entries
+ (scheduled or not) are also listed under the current date.
+
+
+{{{noindent}}} The commands available in the timeline buffer are
+listed in [[Agenda commands]].
+
+*** FIXED Search view
+ :PROPERTIES:
+ :DESCRIPTION: Find entries by searching for text
+ :END:
+#+cindex: search view
+#+cindex: text search
+#+cindex: searching, for text
+
+This agenda view is a general text search facility for Org mode entries.
+It is particularly useful to find notes.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a s)}}}, ~org-search-view~ ::
+
+ This is a special search that lets you select entries by matching a
+ substring or specific words using a boolean logic.
+
+
+For example, the search string {{{samp(computer equipment)}}} will
+find entries that contain {{{samp(computer equipment)}}} as a
+substring. If the two words are separated by more space or a line
+break, the search will still match. Search view can also search for
+specific keywords in the entry, using Boolean logic. The search string
+{{{samp(+computer +wifi -ethernet -{8.11[bg]})}}} will search for
+note entries that contain the keywords ~computer~ and ~wifi~, but not
+the keyword ~ethernet~, and which are also not matched by the regular
+expression ~8.11[bg]~, meaning to exclude both 8.11b and 8.11g. The
+first {{{samp(+)}}} is necessary to turn on word search, other
+{{{samp(+)}}} characters are optional. For more details, see the
+docstring of the command ~org-search-view~.
+
+#+vindex: org-agenda-text-search-extra-files
+
+Note that in addition to the agenda files, this command will also
+search the files listed in ~org-agenda-text-search-extra-files~.
+
+*** FIXED Stuck projects
+ :PROPERTIES:
+ :DESCRIPTION: Find projects you need to review
+ :END:
+#+pindex: GTD, Getting Things Done
+
+If you are following a system like David Allen's GTD to organize your
+work, one of the "duties" you have is a regular review to make sure
+that all projects move along. A /stuck/ project is a project that has
+no defined next actions, so it will never show up in the TODO lists
+Org mode produces. During the review, you need to identify such
+projects and define next actions for them.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a #)}}}, ~org-agenda-list-stuck-projects~ ::
+
+ List projects that are stuck.
+
+- {{{kbd(C-c a !)}}} ::
+
+ #+vindex: org-stuck-projects
+ #+kindex: C-c a !
+
+ Customize the variable ~org-stuck-projects~ to define what a stuck
+ project is and how to find it.
+
+
+You almost certainly will have to configure this view before it will
+work for you. The built-in default assumes that all your projects are
+level-2 headlines, and that a project is not stuck if it has at least
+one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
+
+Let's assume that you, in your own way of using Org mode, identify
+projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
+indicate a project that should not be considered yet. Let's further
+assume that the TODO keyword DONE marks finished projects, and that
+NEXT and TODO indicate next actions. The tag @SHOP indicates shopping
+and is a next action even without the NEXT tag. Finally, if the
+project contains the special word IGNORE anywhere, it should not be
+listed either. In this case you would start by identifying eligible
+projects with a tags/todo match (see [[Tag searches]]).
+{{{samp(+PROJECT/-MAYBE-DONE)}}}, and then check for TODO, NEXT,
+@SHOP, and IGNORE in the subtree to identify projects that are not
+stuck. The correct customization for this is:
+
+#+begin_src emacs-lisp
+(setq org-stuck-projects
+ '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
+ "\\<IGNORE\\>"))
+#+end_src
+
+Note that if a project is identified as non-stuck, the subtree of this entry
+will still be searched for stuck projects.
+
+** Presentation and sorting
+ :PROPERTIES:
+ :DESCRIPTION: How agenda items are prepared for display
+ :END:
+#+cindex: presentation, of agenda items
+#+vindex: org-agenda-prefix-format
+#+vindex: org-agenda-tags-column
+
+Before displaying items in an agenda view, Org mode visually prepares
+the items and sorts them. Each item occupies a single line. The line
+starts with a /prefix/ that contains the /category/ (see [[Categories]])
+of the item and other important information. You can customize in
+which column tags will be displayed through ~org-agenda-tags-column~.
+You can also customize the prefix using the option
+~org-agenda-prefix-format~. This prefix is followed by a cleaned-up
+version of the outline headline associated with the item.
+
+*** Categories
+ :PROPERTIES:
+ :DESCRIPTION: Not all tasks are equal
+ :END:
+
+#+cindex: category
+#+cindex: #+CATEGORY
+
+The category is a broad label assigned to each agenda item. By
+default, the category is simply derived from the file name, but you
+can also specify it with a special line in the buffer, like
+this:[fn:93]
+
+#+begin_example
+ ,#+CATEGORY: Thesis
+#+end_example
+
+{{{noindent}}}
+#+cindex: property, CATEGORY
+
+If you would like to have a special CATEGORY for a single entry or a
+(sub)tree, give the entry a ~:CATEGORY:~ property with the special
+category you want to apply as the value.
+
+{{{noindent}}} The display in the agenda buffer looks best if the
+category is not longer than 10 characters.
+
+{{{noindent}}} You can set up icons for category by customizing the
+~org-agenda-category-icon-alist~ variable.
+#+vindex: org-agenda-category-icon-alist
+
+*** Time-of-day specifications
+ :PROPERTIES:
+ :DESCRIPTION: How the agenda knows the time
+ :END:
+#+cindex: time-of-day specification
+
+Org mode checks each agenda item for a time-of-day specification. The
+time can be part of the timestamp that triggered inclusion into the
+agenda, for example as in ~<2005-05-10 Tue 19:00>~. Time
+ranges can be specified with two timestamps, like:
+
+ ~<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>~.
+
+In the headline of the entry itself, a time(range) may also appear as
+plain text (like {{{samp(12:45)}}} or a {{{samp(8:30-1pm)}}}). If the
+agenda integrates the Emacs diary (see [[Weekly/daily agenda]]), time
+specifications in diary entries are recognized as well.
+
+For agenda display, Org mode extracts the time and displays it in a
+standard 24 hour format as part of the prefix. The example times in
+the previous paragraphs would end up in the agenda like this:
+
+#+begin_example
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 19:00...... The Vogon reads his poem
+ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
+#+end_example
+
+#+cindex: time grid
+
+If the agenda is in single-day mode, or for the display of today, the
+timed entries are embedded in a time grid, like
+
+#+begin_example
+ 8:00...... ------------------
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 10:00...... ------------------
+ 12:00...... ------------------
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 14:00...... ------------------
+ 16:00...... ------------------
+ 18:00...... ------------------
+ 19:00...... The Vogon reads his poem
+ 20:00...... ------------------
+ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
+#+end_example
+
+#+vindex: org-agenda-use-time-grid
+#+vindex: org-agenda-time-grid
+
+The time grid can be turned on and off with the variable
+~org-agenda-use-time-grid~, and can be configured with
+~org-agenda-time-grid~.
+
+*** Sorting of agenda items
+ :PROPERTIES:
+ :DESCRIPTION: The order of things
+ :END:
+#+cindex: sorting, of agenda items
+#+cindex: priorities, of agenda items
+
+Before being inserted into a view, the items are sorted. How this is
+done depends on the type of view.
+
+- For the daily/weekly agenda, the items for each day are sorted. The
+ default order is to first collect all items containing an explicit
+ time-of-day specification. These entries will be shown at the
+ beginning of the list, as a /schedule/ for the day. After that,
+ items remain grouped in categories, in the sequence given by
+ ~org-agenda-files~. Within each category, items are sorted by
+ priority (see [[Priorities]]), which is composed of the base priority
+ (2000 for priority {{{samp(A)}}}, 1000 for {{{samp(B)}}}, and 0 for
+ {{{samp(C)}}}), plus additional increments for overdue scheduled or deadline items.
+
+ #+vindex: org-agenda-files
+
+- For the TODO list, items remain in the order of categories, but
+ within each category, sorting takes place according to priority (see
+ [[Priorities]]). The priority used for sorting derives from the
+ priority cookie, with additions depending on how close an item is to
+ its due or scheduled date.
+
+- For tags matches, items are not sorted at all, but just appear in
+ the sequence in which they are found in the agenda files.
+
+
+#+vindex: org-agenda-sorting-strategy
+
+Sorting can be customized using the variable
+~org-agenda-sorting-strategy~, and may also include criteria based on
+the estimated effort of an entry (see [[Effort estimates]]).
+
+** FIXME Agenda commands
+ :PROPERTIES:
+ :DESCRIPTION: Remote editing of Org trees
+ :TITLE: Commands in the agenda buffer
+ :END:
+#+cindex: commands, in agenda buffer
+
+Entries in the agenda buffer are linked back to the Org file or diary
+file where they originate. You are not allowed to edit the agenda
+buffer itself, but commands are provided to show and jump to the
+original entry location, and to edit the Org files ``remotely'' from
+the agenda buffer. In this way, all information is stored only once,
+removing the risk that your agenda and note files may diverge.
+
+Some commands can be executed with mouse clicks on agenda lines. For
+the other commands, the cursor needs to be in the desired line.
+
+*** FIXME Motion2
+#+cindex: motion commands in agenda
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(n)}}}, ~org-agenda-next-line~ ::
+ #+kindex: n
+
+ Next line (same as {{{key(down)}}} and {{{kbd(C-n)}}}).
+
+- {{{kbd(p)}}}, ~org-agenda-previous-line~ ::
+ #+kindex: p
+
+ Previous line (same as {{{key(up)}}} and {{{kbd(C-p)}}}).
+
+*** View/Go to Org file
+#+cindex: view file commands in agenda
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{key(SPC)}}} or {{{key(mouse-3)}}}, ~org-agenda-show-and-scroll-up~ ::
+ #+kindex: @key{SPC}
+ #+kindex: mouse-3
+
+ Display the original location of the item in another window. With
+ prefix arg, make sure that the entire entry is made visible in the
+ outline, not only the heading.
+
+- {{{kbd(L)}}}, ~org-agenda-recenter~ ::
+ #+kindex: L
+
+ Display original location and recenter that window.
+
+- {{{key(TAB)}}} or {{{key(mouse-2)}}}, ~org-agenda-goto~ ::
+ #+kindex: @key{TAB}
+ #+kindex: mouse-2
+
+ Go to the original location of the item in another window.
+
+- {{{key(RET)}}}, ~org-agenda-switch-to~ ::
+ #+kindex: @key{RET}
+
+ Go to the original location of the item and delete other windows.
+
+- {{{kbd(F)}}}, ~org-agenda-follow-mode~ ::
+ #+kindex: F
+ #+vindex: org-agenda-start-with-follow-mode
+
+ Toggle Follow mode. In Follow mode, as you move the cursor through the
+ agenda buffer, the other window always shows the corresponding
+ location in the Org file. The initial setting for this mode in new
+ agenda buffers can be set with the variable
+ ~org-agenda-start-with-follow-mode~.
+
+- {{{kbd(C-c C-x b)}}}, ~org-agenda-tree-to-indirect-buffer~ ::
+ #+kindex: C-c C-x b
+
+ Display the entire subtree of the current item in an indirect buffer.
+ With a numeric prefix argument N, go up to level N and then take that
+ tree. If N is negative, go up that many levels. With a {{{kbd(C-u)}}}
+ prefix, do not remove the previously used indirect buffer.
+
+- {{{kbd(C-c C-o)}}}, ~org-agenda-open-link~ ::
+ #+kindex: C-c C-o
+
+ Follow a link in the entry. This will offer a selection of any links
+ in the text belonging to the referenced Org node. If there is only one
+ link, it will be followed without a selection prompt.
+
+*** Change display
+#+cindex: change agenda display
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(A)}}} ::
+ #+kindex: A
+ #+cindex: display changing, in agenda
+
+ Interactively select another agenda view and append it to the current
+ view.
+
+- {{{kbd(o)}}} ::
+ #+kindex: o
+
+ Delete other windows.
+
+- {{{kbd(v d)}}} or short {{{kbd(d)}}}, ~org-agenda-day-view~ ::
+ #+kindex: v d
+ #+kindex: d
+ #+vindex: org-agenda-span
+
+ Switch to day view. When switching to day view, this setting becomes
+ the default for subsequent agenda refreshes. A numeric prefix argument
+ may be used to jump directly to a specific day of the year. For
+ example, {{{kbd(32 d)}}} jumps to February 1st. When setting day view,
+ a year may be encoded in the prefix argument as well. For example,
+ {{{kbd(200712 d)}}} will jump to January 12, 2007. If such a year
+ specification has only one or two digits, it will be mapped to the
+ interval 1938-2037.
+
+- {{{kbd(v w)}}} or short {{{kbd(w)}}}, ~org-agenda-week-view~ ::
+ #+kindex: v w
+ #+kindex: w
+ #+vindex: org-agenda-span
+
+ Switch to week view. When switching week view, this setting becomes
+ the default for subsequent agenda refreshes. A numeric prefix argument
+ may be used to jump directly to a specific day of the ISO week. For
+ example {{{kbd(9 w)}}} to ISO week number 9. When setting week view, a
+ year may be encoded in the prefix argument as well. For example,
+ {{{kbd(200712 w)}}} will jump to week 12 in 2007. If such a year
+ specification has only one or two digits, it will be mapped to the
+ interval 1938-2037.
+
+- {{{kbd(v m)}}}, ~org-agenda-month-view~ ::
+ #+kindex: v m
+ #+vindex: org-agenda-span
+
+ Switch to month view. Because month views are slow to create, they do
+ not become the default for subsequent agenda refreshes. A numeric
+ prefix argument may be used to jump directly to a specific day of the
+ month. When setting month view, a year may be encoded in the prefix
+ argument as well. For example, {{{kbd(200712 m)}}} will jump to
+ December, 2007. If such a year specification has only one or two
+ digits, it will be mapped to the interval 1938-2037.
+
+- {{{kbd(v y)}}}, ~org-agenda-year-view~ ::
+ #+kindex: v y
+ #+vindex: org-agenda-span
+
+ Switch to year view. Because year views are slow to create, they do
+ not become the default for subsequent agenda refreshes. A numeric
+ prefix argument may be used to jump directly to a specific day of the
+ year.
+
+- {{{kbdspckey(v,SPC)}}}, ~org-agenda-reset-view~ ::
+ #+kindex: v @key{SPC}
+ #+vindex: org-agenda-span
+
+ Reset ~org-agenda-span~ to the current span.
+
+- {{{kbd(f)}}}, ~org-agenda-later~ ::
+ #+kindex: f
+
+ Go forward in time to display the following ~org-agenda-current-span~
+ days. For example, if the display covers a week, switch to the
+ following week. With prefix arg, go forward that many times
+ ~org-agenda-current-span~ days.
+
+- {{{kbd(b)}}}, ~org-agenda-earlier~ ::
+ #+kindex: b
+
+ Go backward in time to display earlier dates.
+
+- {{{kbd(.)}}}, ~org-agenda-goto-today~ ::
+ #+kindex: .
+
+ Go to today.
+
+- {{{kbd(j)}}}, ~org-agenda-goto-date~ ::
+ #+kindex: j
+
+ Prompt for a date and go there.
+
+- {{{kbd(J)}}}, ~org-agenda-clock-goto~ ::
+ #+kindex: J
+
+ Go to the currently clocked-in task /in the agenda buffer/.
+
+- {{{kbd(D)}}}, ~org-agenda-toggle-diary~ ::
+ #+kindex: D
+
+ Toggle the inclusion of diary entries. See [[Weekly/daily agenda]].
+
+- {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}}, ~org-agenda-log-mode~ ::
+ #+kindex: v l
+ #+kindex: l
+ #+kindex: v L
+ #+vindex: org-log-done
+ #+vindex: org-agenda-log-mode-items
+
+ Toggle Logbook mode. In Logbook mode, entries that were marked DONE
+ while logging was on (see the variable ~org-log-done~) are shown in
+ the agenda, as are entries that have been clocked on that day. You can
+ configure the entry types that should be included in log mode using
+ the variable ~org-agenda-log-mode-items~. When called with a
+ {{{kbd(C-u)}}} prefix, show all possible logbook entries, including
+ state changes. When called with two prefix args {{{kbd(C-u C-u)}}},
+ show only logging information, nothing else. {{{kbd(v L)}}} is
+ equivalent to {{{kbd(C-u v l)}}}.
+
+- {{{kbd(v [)}}} or short {{{kbd([)}}}, ~org-agenda-manipulate-query-add~ ::
+ #+kindex: v [
+ #+kindex: [
+
+ Include inactive timestamps into the current view. Only for
+ weekly/daily agenda and timeline views.
+
+- {{{kbd(v a)}}}, ~org-agenda-archives-mode~ ::
+ #+kindex: v a
+
+ Toggle Archives mode. In Archives mode, trees that are marked
+ ~ARCHIVED~ are also scanned when producing the agenda. To exit
+ archives mode, press {{{kbd(v a)}}} again.
+
+- {{{kbd(v A)}}}, ~org-agenda-archives-mode 'files~ ::
+
+ Toggle Archives mode. In Archives mode, trees that are marked
+ ~ARCHIVED~ are also scanned when producing the agenda, including all
+ archive files. To exit archives mode, press {{{kbd(v a)}}}.
+
+- {{{kbd(v R)}}} or short {{{kbd(R)}}}, ~org-agenda-clockreport-mode~ ::
+ #+kindex: v R
+ #+kindex: R
+ #+vindex: org-agenda-start-with-clockreport-mode
+ #+vindex: org-clock-report-include-clocking-task
+
+ Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda
+ will always show a table with the clocked times for the timespan and
+ file scope covered by the current agenda view. The initial setting for
+ this mode in new agenda buffers can be set with the variable
+ ~org-agenda-start-with-clockreport-mode~. By using a prefix argument
+ when toggling this mode (i.e., {{{kbd(C-u R)}}}), the clock table will
+ not show contributions from entries that are hidden by agenda
+ filtering.[fn:94] See also the variable
+ ~org-clock-report-include-clocking-task~.
+
+- {{{kbd(v c)}}} ::
+ #+kindex: v c
+ #+vindex: org-agenda-clock-consistency-checks
+
+ Show overlapping clock entries, clocking gaps, and other clocking
+ problems in the current agenda range. You can then visit clocking
+ lines and fix them manually. See the variable
+ ~org-agenda-clock-consistency-checks~ for information on how to
+ customize the definition of what constituted a clocking problem. To
+ return to normal agenda display, press {{{kbd(l)}}} to exit Logbook
+ mode.
+
+- {{{kbd(v E)}}} or short {{{kbd(E)}}}, ~org-agenda-entry-text-mode~ ::
+ #+kindex: v E
+ #+kindex: E
+ #+vindex: org-agenda-start-with-entry-text-mode
+ #+vindex: org-agenda-entry-text-maxlines
+
+ Toggle entry text mode. In entry text mode, a number of lines from the
+ Org outline node referenced by an agenda line will be displayed below
+ the line. The maximum number of lines is given by the variable
+ ~org-agenda-entry-text-maxlines~. Calling this command with a numeric
+ prefix argument will temporarily modify that number to the prefix
+ value.
+
+- {{{kbd(G)}}}, ~org-agenda-toggle-time-grid~ ::
+ #+kindex: G
+ #+vindex: org-agenda-use-time-grid
+ #+vindex: org-agenda-time-grid
+
+ Toggle the time grid on and off. See also the variables
+ ~org-agenda-use-time-grid~ and ~org-agenda-time-grid~.
+
+- {{{kbd(r)}}}, ~org-agenda-redo~ ::
+ #+kindex: r
+
+ Recreate the agenda buffer, for example to reflect the changes after
+ modification of the timestamps of items with {{{kbdkey(S-,left)}}} and
+ {{{kbdkey(S-,right)}}}. When the buffer is the global TODO list, a prefix
+ argument is interpreted to create a selective list for a specific TODO
+ keyword.
+
+- {{{kbd(g)}}}, ~org-agenda-redo~ ::
+ #+kindex: g
+
+ Same as {{{kbd(r)}}}.
+
+- {{{kbd(C-x C-s)}}} or short {{{kbd(s)}}}, ~org-save-all-org-buffers~ ::
+ #+kindex: C-x C-s
+ #+kindex: s
+
+ Save all Org buffers in the current Emacs session, and also the
+ locations of IDs.
+
+- {{{kbd(C-c C-x C-c)}}}, ~org-agenda-columns~ ::
+ #+kindex: C-c C-x C-c
+ #+vindex: org-columns-default-format
+
+ Invoke column view (see [[Column view]]) in the agenda buffer. The column
+ view format is taken from the entry at point, or (if there is no entry
+ at point), from the first entry in the agenda view. So whatever the
+ format for that entry would be in the original buffer (taken from a
+ property, from a ~#+COLUMNS~ line, or from the default variable
+ ~org-columns-default-format~), will be used in the agenda.
+
+- {{{kbd(C-c C-x >)}}}, ~org-agenda-remove-restriction-lock~ ::
+ #+kindex: C-c C-x >
+
+ Remove the restriction lock on the agenda, if it is currently
+ restricted to a file or subtree (see [[Agenda files]]).
+
+*** FIXME Secondary filtering and query editing
+#+cindex: filtering, by tag category and effort, in agenda
+#+cindex: tag filtering, in agenda
+#+cindex: category filtering, in agenda
+#+cindex: effort filtering, in agenda
+#+cindex: query editing, in agenda
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(<)}}}, ~org-agenda-filter-by-category~ ::
+ #+kindex: <
+ #+vindex: org-agenda-category-filter-preset
+
+ Filter the current agenda view with respect to the category of the
+ item at point. Pressing {{{kbd(<)}}} another time will remove this
+ filter. You can add a filter preset through the option
+ ~org-agenda-category-filter-preset~ (see below).
+
+- {{{kbd(/)}}}, ~org-agenda-filter-by-tag~ ::
+ #+kindex: /
+ #+vindex: org-agenda-tag-filter-preset
+
+ Filter the current agenda view with respect to a tag and/or effort
+ estimates. The difference between this and a custom agenda command is
+ that filtering is very fast, so that you can switch quickly between
+ different filters without having to recreate the
+ agenda.[fn:95]
+
+ You will be prompted for a tag selection letter; {{{key(SPC)}}} will
+ mean any tag at all. Pressing {{{key(TAB)}}} at that prompt will offer
+ use completion to select a tag (including any tags that do not have a
+ selection character). The command then hides all entries that do not
+ contain or inherit this tag. When called with prefix arg, remove the
+ entries that /do/ have the tag. A second {{{kbd(/)}}} at the prompt
+ will turn off the filter and unhide any hidden entries. If the first
+ key you press is either {{{kbd(+)}}} or {{{kbd(-)}}}, the previous
+ filter will be narrowed by requiring or forbidding the selected
+ additional tag. Instead of pressing {{{kbd(+)}}} or {{{kbd(-)}}} after
+ {{{kbd(/)}}}, you can also immediately use the ~\~ command.
+
+ #+vindex: org-sort-agenda-noeffort-is-high
+
+ In order to filter for effort estimates, you should set up allowed
+ efforts globally, for example:
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (setq org-global-properties
+ '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
+ #+end_src
+
+ You can then filter for an effort by first typing an operator, one of
+ {{{kbd(<)}}}, {{{kbd(>)}}}, and {{{kbd(=)}}}, and then the one-digit
+ index of an effort estimate in your array of allowed values, where
+ {{{kbd(0)}}} means the 10th value. The filter will then restrict to
+ entries with effort smaller-or-equal, equal, or larger-or-equal than
+ the selected value. If the digits 0-9 are not used as fast access keys
+ to tags, you can also simply press the index digit directly without an
+ operator. In this case, {{{kbd(<)}}} will be assumed. For application
+ of the operator, entries without a defined effort will be treated
+ according to the value of ~org-sort-agenda-noeffort-is-high~. To
+ filter for tasks without effort definition, press {{{kbd(?)}}} as the
+ operator.
+
+ Org also supports automatic, context-aware tag filtering. If the
+ variable ~org-agenda-auto-exclude-function~ is set to a user-defined
+ function, that function can decide which tags should be excluded from
+ the agenda automatically. Once this is set, the {{{kbd(/)}}} command
+ then accepts {{{kbd(RET)}}} as a sub-option key and runs the auto
+ exclusion logic. For example, let's say you use a ~Net~ tag to
+ identify tasks which need network access, an ~Errand~ tag for errands
+ in town, and a ~Call~ tag for making phone calls. You could
+ auto-exclude these tags based on the availability of the Internet, and
+ outside of business hours, with something like this:
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (defun org-my-auto-exclude-function (tag)
+ (and (cond
+ ((string= tag "Net")
+ (/= 0 (call-process "/sbin/ping" nil nil nil
+ "-c1" "-q" "-t1" "mail.gnu.org")))
+ ((or (string= tag "Errand") (string= tag "Call"))
+ (let ((hour (nth 2 (decode-time))))
+ (or (< hour 8) (> hour 21)))))
+ (concat "-" tag)))
+ (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
+ #+end_src
+
+- ~\~ ~org-agenda-filter-by-tag-refine~ ::
+ #+kindex: XXX
+ #+comment: Should be \
+ Narrow the current agenda filter by an additional condition. When
+ called with prefix arg, remove the entries that /do/ have the tag, or
+ that do match the effort criterion. You can achieve the same effect by
+ pressing {{{kbd(+)}}} or {{{kbd(-)}}} as the first key after the
+ {{{kbd(/)}}} command.
+
+- {{{kbd([)}}} {{{kbd(])}}} {{{kbd({)}}} {{{kbd(})}}} in search view ::
+ #+kindex: [
+ #+kindex: ]
+ #+kindex: @{
+ #+kindex: @}
+
+ Add new search words ({{{kbd([)}}} and {{{kbd(])}}}) or new regular
+ expressions ({{{kbd({)}}} and {{{kbd(})}}}) to the query string. The
+ opening bracket/brace will add a positive search term prefixed by
+ {{{samp(+)}}}, indicating that this search term /must/ occur/match in
+ the entry. The closing bracket/brace will add a negative search term
+ which /must not/ occur/match in the entry for it to be selected.
+
+*** FIXME Remote editing
+#+cindex: remote editing, from agenda
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(0--9)}}} ::
+
+ Digit argument.
+
+- {{{kbd(C-_)}}}, ~org-agenda-undo~ ::
+ #+kindex: C-_
+ #+cindex: undoing remote-editing events
+ #+cindex: remote editing, undo
+
+ Undo a change due to a remote editing command. The change is undone
+ both in the agenda buffer and in the remote buffer.
+
+- {{{kbd(t)}}}, ~org-agenda-todo~ ::
+ #+kindex: t
+
+ Change the TODO state of the item, both in the agenda and in the
+ original org file.
+
+- {{{kbdkey(C-S-,right)}}}, ~org-agenda-todo-nextset~ ::
+ #+kindex: C-S-@key{right}
+
+ Switch to the next set of TODO keywords.
+
+- {{{kbdkey(C-S-,left)}}}, ~org-agenda-todo-previousset~ ::
+ #+kindex: C-S-@key{left}
+
+ Switch to the previous set of TODO keywords.
+
+- {{{kbd(C-k)}}}, ~org-agenda-kill~ ::
+ #+kindex: C-k
+ #+vindex: org-agenda-confirm-kill
+
+ Delete the current agenda item along with the entire subtree belonging
+ to it in the original Org file. If the text to be deleted remotely is
+ longer than one line, the kill needs to be confirmed by the user. See
+ variable ~org-agenda-confirm-kill~.
+
+- {{{kbd(C-c C-w)}}}, ~org-agenda-refile~ ::
+ #+kindex: C-c C-w
+
+ Refile the entry at point.
+
+- {{{kbd(C-c C-x C-a)}}} or short {{{kbd(a)}}}, ~org-agenda-archive-default-with-confirmation~ ::
+ #+kindex: C-c C-x C-a
+ #+kindex: a
+ #+vindex: org-archive-default-command
+
+ Archive the subtree corresponding to the entry at point using the
+ default archiving command set in ~org-archive-default-command~. When
+ using the ~a~ key, confirmation will be required.
+
+- {{{kbd(C-c C-x a)}}}, ~org-agenda-toggle-archive-tag~ ::
+ #+kindex: C-c C-x a
+
+ Toggle the ARCHIVE tag for the current headline.
+
+- {{{kbd(C-c C-x A)}}}, ~org-agenda-archive-to-archive-sibling~ ::
+ #+kindex: C-c C-x A
+
+ Move the subtree corresponding to the current entry to its /archive
+ sibling/.
+
+- {{{kbd(C-c C-x C-s)}}} or short {{{kbd($)}}}, ~org-agenda-archive~ ::
+ #+kindex: C-c C-x C-s
+ #+kindex: $
+
+ Archive the subtree corresponding to the current headline. This means
+ the entry will be moved to the configured archive location, most
+ likely a different file.
+
+- {{{kbd(T)}}}, ~org-agenda-show-tags~ ::
+ #+kindex: T
+ #+vindex: org-agenda-show-inherited-tags
+
+ Show all tags associated with the current item. This is useful if you
+ have turned off ~org-agenda-show-inherited-tags~, but still want to
+ see all tags of a headline occasionally.
+
+- {{{kbd(:)}}}, ~org-agenda-set-tags~ ::
+ #+kindex: :
+
+ Set tags for the current headline. If there is an active region in the
+ agenda, change a tag for all headings in the region.
+
+- {{{kbd(\\\,)}}} ::
+ #+kindex: ,
+ Set the priority for the current item (~org-agenda-priority~). Org
+ mode prompts for the priority character. If you reply with
+ {{{key(SPC)}}}, the priority cookie is removed from the entry.
+
+- {{{kbd(P)}}}, ~org-agenda-show-priority~ ::
+ #+kindex: P
+
+ Display weighted priority of current item.
+
+- {{{kbd(+)}}} {{{kbdkey(S-,up)}}}, ~org-agenda-priority-up~ ::
+ #+kindex: +
+
+ Increase the priority of the current item. The priority is changed in
+ the original buffer, but the agenda is not resorted. Use the
+ {{{kbd(r)}}} key for this.
+
+- {{{kbd(-)}}} {{{kbdkey(S-,down)}}}, ~org-agenda-priority-down~ ::
+ #+kindex: -
+
+ Decrease the priority of the current item.
+
+- {{{kbd(z)}}} {{{kbd(C-c C-z)}}}, ~org-agenda-add-note~ ::
+ #+kindex: z
+ #+vindex: org-log-into-drawer
+
+ Add a note to the entry. This note will be recorded, and then filed to
+ the same location where state change notes are put. Depending on
+ ~org-log-into-drawer~, this may be inside a drawer.
+
+- {{{kbd(C-c C-a)}}}, ~org-attach~ ::
+ #+kindex: C-c C-a
+
+ Dispatcher for all command related to attachments.
+
+- {{{kbd(C-c C-s)}}}, ~org-agenda-schedule~ ::
+ #+kindex: C-c C-s
+
+ Schedule this item. With prefix arg remove the scheduling timestamp
+
+- {{{kbd(C-c C-d)}}}, ~org-agenda-deadline~ ::
+ #+kindex: C-c C-d
+
+ Set a deadline for this item. With prefix arg remove the deadline.
+
+- {{{kbdkey(S-,right)}}}, ~org-agenda-do-date-later~ ::
+ #+kindex: S-@key{right}
+
+ Change the timestamp associated with the current line by one day into
+ the future. If the date is in the past, the first call to this command
+ will move it to today. With a numeric prefix argument, change it by
+ that many days. For example, {{{kbdkey(3 6 5 S-,right)}}} will change
+ it by a year. With a {{{kbd(C-u)}}} prefix, change the time by one
+ hour. If you immediately repeat the command, it will continue to
+ change hours even without the prefix arg. With a double
+ {{{kbd(C-u C-u)}}} prefix, do the same for changing minutes. The stamp is changed
+ in the original Org file, but the change is not directly reflected in
+ the agenda buffer. Use {{{kbd(r)}}} or {{{kbd(g)}}} to update the
+ buffer.
+
+- {{{kbdkey(S-,left)}}}, ~org-agenda-do-date-earlier~ ::
+ #+kindex: S-@key{left}
+
+ Change the timestamp associated with the current line by one day
+ into the past.
+
+- {{{kbd(>)}}}, ~org-agenda-date-prompt~ ::
+ #+kindex: >
+
+ Change the timestamp associated with the current line. The key
+ {{{kbd(>)}}} has been chosen, because it is the same as {{{kbd(S-.)}}}
+ on my keyboard.
+
+- {{{kbd(I)}}}, ~org-agenda-clock-in~ ::
+ #+kindex: I
+
+ Start the clock on the current item. If a clock is running already, it
+ is stopped first.
+
+- {{{kbd(O)}}}, ~org-agenda-clock-out~ ::
+ #+kindex: O
+
+ Stop the previously started clock.
+
+- {{{kbd(X)}}}, ~org-agenda-clock-cancel~ ::
+ #+kindex: X
+
+ Cancel the currently running clock.
+
+- {{{kbd(J)}}}, ~org-agenda-clock-goto~ ::
+ #+kindex: J
+
+ Jump to the running clock in another window.
+
+- {{{kbd(k)}}}, ~org-agenda-capture~ ::
+ #+kindex: k
+ #+cindex: capturing, from agenda
+ #+vindex: org-capture-use-agenda-date
+
+ Like ~org-capture~, but use the date at point as the default date for
+ the capture template. See ~org-capture-use-agenda-date~ to make this
+ the default behavior of ~org-capture~.
+
+*** Bulk remote editing selected entries
+#+cindex: remote editing, bulk, from agenda
+#+vindex: org-agenda-bulk-persistent-marks
+#+vindex: org-agenda-bulk-custom-functions
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(m)}}}, ~org-agenda-bulk-mark~ ::
+ #+kindex: m
+
+ Mark the entry at point for bulk action. With prefix arg, mark that
+ many successive entries.
+
+- {{{kbd(%)}}}, ~org-agenda-bulk-mark-regexp~ ::
+ #+kindex: %
+
+ Mark entries matching a regular expression for bulk action.
+
+- {{{kbd(u)}}}, ~org-agenda-bulk-unmark~ ::
+ #+kindex: u
+
+ Unmark entry for bulk action.
+
+- {{{kbd(U)}}}, ~org-agenda-bulk-remove-all-marks~ ::
+ #+kindex: U
+
+ Unmark all marked entries for bulk action.
+
+- {{{kbd(B)}}}, ~org-agenda-bulk-action~ ::
+ #+kindex: B
+
+ Bulk action: act on all marked entries in the agenda. This will prompt
+ for another key to select the action to be applied. The prefix arg to
+ {{{kbd(B)}}} will be passed through to the {{{kbd(s)}}} and
+ {{{kbd(d)}}} commands, to bulk-remove these special timestamps. By
+ default, marks are removed after the bulk. If you want them to
+ persist, set ~org-agenda-bulk-persistent-marks~ to ~t~ or hit
+ {{{kbd(p)}}} at the prompt.
+
+ - {{{kbd(*)}}} ::
+
+ Toggle persistent marks.
+
+ - {{{kbd($)}}} ::
+
+ Archive all selected entries.
+
+ - {{{kbd(A)}}} ::
+
+ Archive entries by moving them to their respective archive siblings.
+
+ - {{{kbd(t)}}} ::
+
+ Change TODO state. This prompts for a single TODO keyword and changes
+ the state of all selected entries, bypassing blocking and suppressing
+ logging notes (but not timestamps).
+
+ - {{{kbd(+)}}} ::
+
+ Add a tag to all selected entries.
+
+ - {{{kbd(-)}}} ::
+
+ Remove a tag from all selected entries.
+
+ - {{{kbd(s)}}} ::
+
+ Schedule all items to a new date. To shift existing schedule dates by
+ a fixed number of days, use something starting with double plus at the
+ prompt, for example {{{samp(++8d)}}} or {{{samp(++2w)}}}.
+
+ - {{{kbd(d)}}} ::
+
+ Set deadline to a specific date.
+
+ - {{{kbd(r)}}} ::
+
+ Prompt for a single refile target and move all entries. The entries
+ will no longer be in the agenda; refresh ({{{kbd(g)}}}) to bring them
+ back.
+
+ - {{{kbd(S)}}} ::
+
+ Reschedule randomly into the coming N days. N will be prompted for.
+ With prefix arg ({{{kbd(C-u B S)}}}), scatter only across weekdays.
+
+ - {{{kbd(f)}}} ::
+
+ Apply a function to marked entries.[fn:96] For example, the function
+ below sets the CATEGORY property of the entries to web.
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (defun set-category ()
+ (interactive "P")
+ (let* ((marker (or (org-get-at-bol 'org-hd-marker)
+ (org-agenda-error)))
+ (buffer (marker-buffer marker)))
+ (with-current-buffer buffer
+ (save-excursion
+ (save-restriction
+ (widen)
+ (goto-char marker)
+ (org-back-to-heading t)
+ (org-set-property "CATEGORY" "web"))))))
+ #+end_src
+
+*** Calendar commands
+#+cindex: calendar commands, from agenda
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(c)}}}, ~org-agenda-goto-calendar~ ::
+ #+kindex: c
+
+ Open the Emacs calendar and move to the date at the agenda cursor.
+
+- {{{kbd(c)}}}, ~org-calendar-goto-agenda~ ::
+ #+kindex: c
+
+ When in the calendar, compute and show the Org mode agenda for the
+ date at the cursor.
+
+- {{{kbd(i)}}}, ~org-agenda-diary-entry~ ::
+ #+kindex: i
+ #+vindex: org-agenda-diary-file
+ #+cindex: diary entries, creating from agenda
+
+ Insert a new entry into the diary, using the date at the cursor and
+ (for block entries) the date at the mark. This will add to the Emacs
+ diary file, in a way similar to the {{{kbd(i)}}} command in the
+ calendar.[fn:97] The diary file will pop up in another window, where
+ you can add the entry.
+
+ If you configure ~org-agenda-diary-file~ to point to an Org mode file,
+ Org will create entries (in Org mode syntax) in that file instead.
+ Most entries will be stored in a date-based outline tree that will
+ later make it easy to archive appointments from previous months/years.
+ The tree will be built under an entry with a ~DATE_TREE~ property, or
+ else with years as top-level entries. Emacs will prompt you for the
+ entry text---if you specify it, the entry will be created in
+ ~org-agenda-diary-file~ without further interaction. If you directly
+ press {{{key(RET)}}} at the prompt without typing text, the target
+ file will be shown in another window for you to finish the entry
+ there. See also the {{{kbd(k r)}}} command.
+
+- {{{kbd(M)}}}, ~org-agenda-phases-of-moon~ ::
+ #+kindex: M
+
+ Show the phases of the moon for the three months around current date.
+
+- {{{kbd(S)}}}, ~org-agenda-sunrise-sunset~ ::
+ #+kindex: S
+
+ Show sunrise and sunset times. The geographical location must be set
+ with calendar variables, see the documentation for the Emacs calendar.
+
+- {{{kbd(C)}}}, ~org-agenda-convert-date~ ::
+ #+kindex: C
+
+ Convert the date at cursor into many other cultural and historic
+ calendars.
+
+- {{{kbd(H)}}}, ~org-agenda-holidays~ ::
+ #+kindex: H
+
+ Show holidays for three months around the cursor date.
+
+- {{{kbd(M-x org-export-icalendar-combine-agenda-files)}}} ::
+
+ Export a single iCalendar file containing entries from all agenda
+ files. This is a globally available command, and also available in the
+ agenda menu.
+
+*** Exporting to a file
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-x C-w)}}}, ~org-agenda-write~ ::
+ #+kindex: C-x C-w
+ #+cindex: exporting agenda views
+ #+cindex: agenda views, exporting
+ #+vindex: org-agenda-exporter-settings
+
+ Write the agenda view to a file. Depending on the extension of the
+ selected file name, the view will be exported as HTML (extension
+ {{{file(.html)}}} or {{{file(.htm)}}}), Postscript (extension
+ {{{file(.ps)}}}), PDF (extension {{{file(.pdf)}}}), and plain text
+ (any other extension). When called with a {{{kbd(C-u)}}} prefix
+ argument, immediately open the newly created file. Use the variable
+ ~org-agenda-exporter-settings~ to set options for {{{file(ps-print)}}}
+ and for {{{file(htmlize)}}} to be used during export.
+
+*** Quit and exit
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(q)}}}, ~org-agenda-quit~ ::
+ #+kindex: q
+
+ Quit agenda, remove the agenda buffer.
+
+- {{{kbd(x)}}}, ~org-agenda-exit~ ::
+ #+kindex: x
+ #+cindex: agenda files, removing buffers
+
+ Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
+ for the compilation of the agenda. Buffers created by the user to
+ visit Org files will not be removed.
+
+** Custom agenda views
+ :PROPERTIES:
+ :DESCRIPTION: Defining special searches and views
+ :END:
+#+cindex: custom agenda views
+#+cindex: agenda views, custom
+
+Custom agenda commands serve two purposes: to store and quickly access
+frequently used TODO and tags searches, and to create special composite
+agenda buffers. Custom agenda commands will be accessible through the
+dispatcher (see [[Agenda dispatcher]]), just like the default commands.
+
+*** Storing searches
+ :PROPERTIES:
+ :DESCRIPTION: Type once, use often
+ :END:
+
+The first application of custom searches is the definition of keyboard
+shortcuts for frequently used searches, either creating an agenda
+buffer, or a sparse tree (the latter covering of course only the
+current buffer).
+
+#+kindex: C-c a C
+#+vindex: org-agenda-custom-commands
+
+Custom commands are configured in the variable
+~org-agenda-custom-commands~. You can customize this variable, for
+example by pressing {{{kbd(C-c a C)}}}. You can also directly set it
+with Emacs Lisp in {{{file(.emacs)}}}. The following example contains
+all valid search types:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("w" todo "WAITING")
+ ("W" todo-tree "WAITING")
+ ("u" tags "+boss-urgent")
+ ("v" tags-todo "+boss-urgent")
+ ("U" tags-tree "+boss-urgent")
+ ("f" occur-tree "\\<FIXME\\>")
+ ("h" . "HOME+Name tags searches") ; description for "h" prefix
+ ("hl" tags "+home+Lisa")
+ ("hp" tags "+home+Peter")
+ ("hk" tags "+home+Kim")))
+#+end_src
+
+{{{noindent}}} The initial string in each entry defines the keys you
+have to press after the dispatcher command {{{kbd(C-c a)}}} in order
+to access the command. Usually this will be just a single character,
+but if you have many similar commands, you can also define two-letter
+combinations where the first character is the same in several
+combinations and serves as a prefix key.[fn:98] The second parameter
+is the search type, followed by the string or regular expression to be
+used for the matching. The example above will therefore define:
+
+#+attr_texinfo: :table-type table :indic @kbd
+- C-c a w ::
+
+ A global search for TODO entries with {{{samp(WAITING)}}} as the TODO
+ keyword.
+
+- C-c a W ::
+
+ The same search, but only in the current buffer and displaying the
+ results as a sparse tree.
+
+- C-c a u ::
+
+ A global tags search for headlines marked {{{samp(:boss:)}}} but not
+ {{{samp(:urgent:)}}}.
+
+- C-c a v ::
+
+ The same search as {{{kbd(C-c a u)}}}, but limiting the search to
+ headlines that are also TODO items.
+
+- C-c a U ::
+
+ The same search as {{{kbd(C-c a u)}}}, but only in the current buffer and
+ displaying the result as a sparse tree.
+
+- C-c a f ::
+
+ Create a sparse tree (again: current buffer only) with all entries
+ containing the word {{{samp(FIXME)}}}
+
+- C-c a h ::
+
+ A prefix command for a HOME tags search where you have to press an
+ additional key ({{{kbd(l)}}}, {{{kbd(p)}}} or {{{kbd(k)}}}) to select
+ a name (Lisa, Peter, or Kim) as additional tag to match.
+
+
+*** Block agenda
+ :PROPERTIES:
+ :DESCRIPTION: All the stuff you need in a single buffer
+ :END:
+#+cindex: block agenda
+#+cindex: agenda, with block views
+
+Another possibility is the construction of agenda views that comprise
+the results of /several/ commands, each of which creates a block in
+the agenda buffer. The available commands include ~agenda~ for the
+daily or weekly agenda (as created with {{{kbd(C-c a a)}}}), ~alltodo~
+for the global TODO list (as constructed with {{{kbd(C-c a t)}}}), and
+the matching commands discussed above: ~todo~, ~tags~, and
+~tags-todo~. Here are two examples:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("h" "Agenda and Home-related tasks"
+ ((agenda "")
+ (tags-todo "home")
+ (tags "garden")))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda "")
+ (tags-todo "work")
+ (tags "office")))))
+#+end_src
+
+{{{noindent}}} This will define {{{kbd(C-c a h)}}} to create a
+multi-block view for stuff you need to attend to at home. The
+resulting agenda buffer will contain your agenda for the current week,
+all TODO items that carry the tag {{{samp(home)}}}, and also all lines
+tagged with {{{samp(garden)}}}. Finally the command {{{kbd(C-c a o)}}}
+provides a similar view for office tasks.
+
+*** Setting options for custom commands
+ :PROPERTIES:
+ :DESCRIPTION: Changing the rules
+ :END:
+#+cindex: options, for custom agenda views
+#+vindex: org-agenda-custom-commands
+
+Org mode contains a number of variables regulating agenda construction
+and display. The global variables define the behavior for all agenda
+commands, including the custom commands. However, if you want to
+change some settings just for a single custom view, you can do so.
+Setting options requires inserting a list of variable names and values
+at the right spot in ~org-agenda-custom-commands~. For example:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("w" todo "WAITING"
+ ((org-agenda-sorting-strategy '(priority-down))
+ (org-agenda-prefix-format " Mixed: ")))
+ ("U" tags-tree "+boss-urgent"
+ ((org-show-following-heading nil)
+ (org-show-hierarchy-above nil)))
+ ("N" search ""
+ ((org-agenda-files '("~org/notes.org"))
+ (org-agenda-text-search-extra-files nil)))))
+#+end_src
+
+{{{noindent}}} Now the {{{kbd(C-c a w)}}} command will sort the
+collected entries only by priority, and the prefix format is modified
+to just say {{{samp( Mixed: )}}} instead of giving the category of the
+entry. The sparse tags tree of {{{kbd(C-c a U)}}} will now turn out
+ultra-compact, because neither the headline hierarchy above the match,
+nor the headline following the match will be shown. The command
+{{{kbd(C-c a N)}}} will do a text search limited to only a single
+file.
+
+#+vindex: org-agenda-custom-commands
+
+For command sets creating a block agenda, ~org-agenda-custom-commands~
+has two separate spots for setting options. You can add options that
+should be valid for just a single command in the set, and options that
+should be valid for all commands in the set. The former are just added
+to the command entry; the latter must come after the list of command
+entries. Going back to the block agenda example (see [[Block
+agenda]]), let's change the sorting strategy for the {{{kbd(C-c a
+h)}}} commands to ~priority-down~, but let's sort the results for
+GARDEN tags query in the opposite order, ~priority-up~. This would
+look like this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("h" "Agenda and Home-related tasks"
+ ((agenda)
+ (tags-todo "home")
+ (tags "garden"
+ ((org-agenda-sorting-strategy '(priority-up)))))
+ ((org-agenda-sorting-strategy '(priority-down))))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda)
+ (tags-todo "work")
+ (tags "office")))))
+#+end_src
+
+As you see, the values and parentheses setting is a little complex.
+When in doubt, use the customize interface to set this variable---it
+fully supports its structure. Just one caveat: when setting options in
+this interface, the /values/ are just Lisp expressions. So if the
+value is a string, you need to add the double-quotes around the value
+yourself.
+
+#+vindex: org-agenda-custom-commands-contexts
+
+To control whether an agenda command should be accessible from a
+specific context, you can customize
+~org-agenda-custom-commands-contexts~. Let's say for example that you
+have an agenda command {{{kbd(o)}}} displaying a view that you only
+need when reading emails. Then you would configure this option like
+this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" (in-mode . "message-mode"))))
+#+end_src
+
+You can also tell that the command key {{{kbd(o)}}} should refer to another
+command key {{{kbd(r)}}}. In that case, add this command key like this:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" "r" (in-mode . "message-mode"))))
+#+end_src
+
+See the docstring of the variable for more information.
+
+** Exporting agenda views
+ :PROPERTIES:
+ :DESCRIPTION: Writing a view to a file
+ :END:
+#+cindex: agenda views, exporting
+
+If you are away from your computer, it can be very useful to have a
+printed version of some agenda views to carry around. Org mode can
+export custom agenda views as plain text, HTML, Postscript,
+PDF, and iCalendar files.[fn:99] If you want to
+do this only occasionally, use the following command:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-x C-w)}}}, ~org-agenda-write~ ::
+
+ #+cindex: exporting agenda views
+ #+cindex: agenda views, exporting
+ #+vindex: org-agenda-exporter-settings
+
+ Write the agenda view to a file. Depending on the extension of the
+ selected file name, the view will be exported as HTML (extension
+ {{{file(.html)}}} or {{{file(.htm)}}}), Postscript (extension
+ {{{file(.ps)}}}), iCalendar (extension {{{file(.ics)}}}), or plain
+ text (any other extension). Use the variable
+ ~org-agenda-exporter-settings~ to set options for {{{file(ps-print)}}}
+ and for {{{file(htmlize)}}} to be used during export, for example:
+
+ #+vindex: org-agenda-add-entry-text-maxlines
+ #+vindex: htmlize-output-type
+ #+vindex: ps-number-of-columns
+ #+vindex: ps-landscape-mode
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (setq org-agenda-exporter-settings
+ '((ps-number-of-columns 2)
+ (ps-landscape-mode t)
+ (org-agenda-add-entry-text-maxlines 5)
+ (htmlize-output-type 'css)))
+ #+end_src
+
+
+If you need to export certain agenda views frequently, you can
+associate any custom agenda command with a list of output file
+names.[fn:100] Here is an example that first defines custom commands
+for the agenda and the global TODO list, together with a number of
+files to which to export them. Then we define two block agenda
+commands and specify file names for them as well. File names can be
+relative to the current working directory, or absolute.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
+ ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
+ ("h" "Agenda and Home-related tasks"
+ ((agenda "")
+ (tags-todo "home")
+ (tags "garden"))
+ nil
+ ("~/views/home.html"))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda)
+ (tags-todo "work")
+ (tags "office"))
+ nil
+ ("~/views/office.ps" "~/calendars/office.ics"))))
+#+end_src
+
+The extension of the file name determines the type of export. If it is
+{{{file(.html)}}}, Org mode will use the {{{file(htmlize.el)}}}
+package to convert the buffer to HTML and save it to this file name.
+If the extension is {{{file(.ps)}}}, ~ps-print-buffer-with-faces~ is
+used to produce Postscript output. If the extension is
+{{{file(.ics)}}}, iCalendar export is run export over all files that
+were used to construct the agenda, and limit the export to entries
+listed in the agenda. Any other extension produces a plain ASCII file.
+
+The export files are /not/ created when you use one of those
+commands interactively because this might use too much overhead.
+Instead, there is a special command to produce /all/ specified
+files in one step:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c a e)}}}, ~org-store-agenda-views~ ::
+
+ Export all agenda views that have export file names associated with
+ them.
+
+
+You can use the options section of the custom agenda commands to also
+set options for the export commands. For example:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-agenda-custom-commands
+ '(("X" agenda ""
+ ((ps-number-of-columns 2)
+ (ps-landscape-mode t)
+ (org-agenda-prefix-format " [ ] ")
+ (org-agenda-with-colors nil)
+ (org-agenda-remove-tags t))
+ ("theagenda.ps"))))
+#+end_src
+
+{{{noindent}}} This command sets two options for the Postscript
+exporter, to make it print in two columns in landscape format---the
+resulting page can be cut in two and then used in a paper agenda. The
+remaining settings modify the agenda prefix to omit category and
+scheduling information, and instead include a checkbox to check off
+items. We also remove the tags to make the lines compact, and we don't
+want to use colors for the black-and-white printer. Settings specified
+in ~org-agenda-exporter-settings~ will also apply, but the settings in
+~org-agenda-custom-commands~ take precedence.
+
+{{{noindent}}} From the command line you may also use:
+
+#+begin_src sh
+ emacs -eval (org-batch-store-agenda-views) -kill
+#+end_src
+
+{{{noindent}}} or, if you need to modify some parameters:[fn:101]
+
+#+begin_example
+ emacs -eval '(org-batch-store-agenda-views \
+ org-agenda-span (quote month) \
+ org-agenda-start-day "2007-11-01" \
+ org-agenda-include-diary nil \
+ org-agenda-files (quote ("~/org/project.org")))' \
+ -kill
+#+end_example
+
+{{{noindent}}} which will create the agenda views restricted to the
+file {{{file(~/org/project.org)}}}, without diary entries and with a
+30-day extent.
+
+You can also extract agenda information in a way that allows further
+processing by other programs. See [[Extracting agenda information]], for
+more information.
+
+** Using column view in the agenda
+ :PROPERTIES:
+ :DESCRIPTION: Using column view for collected entries
+ :ALT_TITLE: Agenda column view
+ :END:
+#+cindex: column view, in agenda
+#+cindex: agenda, column view
+<<Agenda column view>>
+
+Column view (see [[Column view]]) is normally used to view and edit
+properties embedded in the hierarchical structure of an Org file. It
+can be quite useful to use column view also from the agenda, where
+entries are collected by certain criteria.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-c)}}}, ~org-agenda-columns~ ::
+
+ Turn on column view in the agenda.
+
+
+To understand how to use this properly, it is important to realize that the
+entries in the agenda are no longer in their proper outline environment.
+This causes the following issues:
+
+1. Org needs to make a decision which ~COLUMNS~ format to use. Since
+ the entries in the agenda are collected from different files, and
+ different files may have different ~COLUMNS~ formats, this is a
+ non-trivial problem. Org first checks if the variable
+ ~org-agenda-overriding-columns-format~ is currently set, and if so,
+ takes the format from there. Otherwise it takes the format
+ associated with the first item in the agenda, or, if that item does
+ not have a specific format (defined in a property, or in its file),
+ it uses ~org-columns-default-format~.
+
+ #+vindex: org-columns-default-format
+ #+vindex: org-overriding-columns-format
+
+2. If any of the columns has a summary type defined (see [[Column
+ attributes]]), turning on column view in the agenda will visit all
+ relevant agenda files and make sure that the computations of this
+ property are up to date. This is also true for the special
+ ~CLOCKSUM~ property. Org will then sum the values displayed in the
+ agenda. In the daily/weekly agenda, the sums will cover a single
+ day; in all other views they cover the entire block. It is vital to
+ realize that the agenda may show the same entry /twice/ (for
+ example as scheduled and as a deadline), and it may show two
+ entries from the same hierarchy (for example a /parent/ and its
+ /child/). In these cases, the summation in the agenda will lead to
+ incorrect results because some values will count double.
+
+ #+cindex: property, special, CLOCKSUM
+
+3. When the column view in the agenda shows the ~CLOCKSUM~, that is
+ always the entire clocked time for this item. So even in the
+ daily/weekly agenda, the clocksum listed in column view may
+ originate from times outside the current view. This has the
+ advantage that you can compare these values with a column listing
+ the planned total effort for a task---one of the major applications
+ for column view in the agenda. If you want information about
+ clocked time in the displayed period use clock table mode (press
+ {{{kbd(R)}}} in the agenda).
+
+4. When the column view in the agenda shows the ~CLOCKSUM_T~, that is
+ always today's clocked time for this item. So even in the weekly agenda,
+ the clocksum listed in column view only originates from today. This lets
+ you compare the time you spent on a task for today, with the time already
+ spent (via ~CLOCKSUM~) and with the planned total effort for it.
+
+ #+cindex: property, special, CLOCKSUM_T
+
+* FIXME Markup for rich export
+ :PROPERTIES:
+ :DESCRIPTION: Prepare text for rich export
+ :ALT_TITLE: Markup
+ :END:
+
+When exporting Org mode documents, the exporter tries to reflect the
+structure of the document as accurately as possible in the backend.
+Since export targets like HTML, LaTeX, or DocBook allow much richer
+formatting, Org mode has rules on how to prepare text for rich export.
+This section summarizes the markup rules used in an Org mode buffer.
+
+** Structural markup elements
+ :PROPERTIES:
+ :DESCRIPTION: The basic structure as seen by the exporter
+ :END:
+
+*** Document title
+ :PROPERTIES:
+ :DESCRIPTION: Where the title is taken from
+ :END:
+#+cindex: document title, markup rules
+
+{{{noindent}}} The title of the exported document is taken from the
+special line:
+
+#+cindex: #+TITLE
+#+begin_example
+ ,#+TITLE: This is the title of the document
+#+end_example
+
+{{{noindent}}} If this line does not exist, the title is derived from
+the first non-empty, non-comment line in the buffer. If no such line
+exists, or if you have turned off exporting of the text before the
+first headline (see below), the title will be the file name without
+extension.
+
+#+cindex: property, EXPORT_TITLE
+
+If you are exporting only a subtree by marking is as the region, the
+heading of the subtree will become the title of the document. If the
+subtree has a property ~EXPORT_TITLE~, that will take precedence.
+
+*** Headings and sections
+ :PROPERTIES:
+ :DESCRIPTION: The document structure as seen by the exporter
+ :END:
+#+cindex: headings and sections, markup rules
+
+#+vindex: org-export-headline-levels
+
+The outline structure of the document as described in [[Document
+structure]], forms the basis for defining sections of the exported
+document. However, since the outline structure is also used for (for
+example) lists of tasks, only the first three outline levels will be
+used as headings. Deeper levels will become itemized lists. You can
+change the location of this switch globally by setting the variable
+~org-export-headline-levels~, or on a per-file basis with the ~H~ option:
+
+#+cindex: #+OPTIONS
+#+begin_example
+ ,#+OPTIONS: H:4
+#+end_example
+
+*** Table of contents
+ :PROPERTIES:
+ :DESCRIPTION: The if and where of the table of contents
+ :END:
+#+cindex: table of contents, markup rules
+
+#+vindex: org-export-with-toc
+
+The table of contents is normally inserted directly before the first
+headline of the file. If you would like to get it to a different
+location, insert the string ~[TABLE-OF-CONTENTS]~ on a line by itself
+at the desired location. The depth of the table of contents is by
+default the same as the number of headline levels, but you can choose
+a smaller number, or turn off the table of contents entirely, by
+configuring the variable ~org-export-with-toc~, or on a per-file basis
+with the ~toc~ option:
+
+#+begin_example
+ ,#+OPTIONS: toc:2 (only to two levels in TOC)
+ ,#+OPTIONS: toc:nil (no TOC at all)
+#+end_example
+
+*** Initial text
+ :PROPERTIES:
+ :DESCRIPTION: Text before the first heading?
+ :TITLE: Text before the first headline
+ :END:
+#+cindex: text before first headline, markup rules
+#+cindex: #+TEXT
+
+Org mode normally exports the text before the first headline, and even uses
+the first line as the document title. The text will be fully marked up. If
+you need to include literal HTML, LaTeX, or DocBook code, use the special
+constructs described below in the sections for the individual exporters.
+
+#+vindex: org-export-skip-text-before-1st-heading
+
+Some people like to use the space before the first headline for setup
+and internal links and therefore would like to control the exported
+text before the first headline in a different way. You can do so by
+setting the variable ~org-export-skip-text-before-1st-heading~ to ~t~.
+On a per-file basis, you can get the same effect with
+{{{samp(#+OPTIONS: skip:t)}}}.
+
+{{{noindent}}}
+
+If you still want to have some text before the first headline, use the
+~#+TEXT~ construct:
+
+#+begin_example
+ ,#+OPTIONS: skip:t
+ ,#+TEXT: This text will go before the *first* headline.
+ ,#+TEXT: [TABLE-OF-CONTENTS]
+ ,#+TEXT: This goes between the table of contents and the *first* headline
+#+end_example
+
+*** Lists
+ :PROPERTIES:
+ :DESCRIPTION: Lists
+ :END:
+#+cindex: lists, markup rules
+
+Plain lists as described in [[Plain lists]], are translated to the
+backend's syntax for such lists. Most backends support unordered,
+ordered, and description lists.
+
+*** Paragraphs
+ :PROPERTIES:
+ :DESCRIPTION: Paragraphs
+ :END:
+#+cindex: paragraphs, markup rules
+
+Paragraphs are separated by at least one empty line. If you need to
+enforce a line break within a paragraph, use ~\\~ at the end
+of a line.
+
+To keep the line breaks in a region, but otherwise use normal
+formatting, you can use ~VERSE~ blocks, which can also be used to
+format poetry:
+
+#+cindex: #+BEGIN_VERSE
+#+begin_example
+ #+BEGIN_VERSE
+ Great clouds overhead
+ Tiny black birds rise and fall
+ Snow covers Emacs
+
+ -- AlexSchroeder
+ #+END_VERSE
+#+end_example
+
+When quoting a passage from another document, it is customary to
+format this as a paragraph that is indented on both the left and the
+right margin. You can include quotations in Org mode documents like
+this:
+
+#+cindex: #+BEGIN_QUOTE
+#+begin_example
+ #+BEGIN_QUOTE
+ Everything should be made as simple as possible,
+ but not any simpler -- Albert Einstein
+ #+END_QUOTE
+#+end_example
+
+If you would like to center some text, do it like this:
+#+cindex: #+BEGIN_CENTER
+#+begin_example
+ #+BEGIN_CENTER
+ Everything should be made as simple as possible, \\
+ but not any simpler
+ #+END_CENTER
+#+end_example
+
+*** Footnote markup
+ :PROPERTIES:
+ :DESCRIPTION: Footnotes
+ :END:
+#+cindex: footnotes, markup rules
+#+cindex: @file{footnote.el}
+
+Footnotes defined in the way described in [[Creating footnotes]], will be exported
+by all backends. Org allows multiple references to the same note, and
+multiple footnotes side by side.
+
+*** Emphasis and monospace
+ :PROPERTIES:
+ :DESCRIPTION: Bold, italic, etc.
+ :END:
+
+#+cindex: underlined text, markup rules
+#+cindex: bold text, markup rules
+#+cindex: italic text, markup rules
+#+cindex: verbatim text, markup rules
+#+cindex: code text, markup rules
+#+cindex: strike-through text, markup rules
+
+You can make words **bold**, //italic//, _underlined_, ~=code=~
+and ~~verbatim~~, and, if you must, {{{samp(+strike-through+)}}}. Text
+in the code and verbatim string is not processed for Org mode specific
+syntax; it is exported verbatim.
+
+*** Horizontal rules
+ :PROPERTIES:
+ :DESCRIPTION: Make a line
+ :END:
+#+cindex: horizontal rules, markup rules
+
+A line consisting of only dashes, and at least 5 of them, will be
+exported as a horizontal line (~<hr/>~ in HTML and ~\hrule~
+in LaTeX).
+
+*** Comment lines
+ :PROPERTIES:
+ :DESCRIPTION: What will *not* be exported
+ :END:
+#+cindex: comment lines
+#+cindex: exporting, not
+#+cindex: #+BEGIN_COMMENT
+
+Lines starting with zero or more whitespace characters followed by one
+{{{samp(#)}}} and a whitespace are treated as comments and will never
+be exported. Also entire subtrees starting with the word
+{{{samp(COMMENT)}}} will never be exported. Finally, regions
+surrounded by {{{samp(#+BEGIN_COMMENT)}}} ...
+{{{samp(#+END_COMMENT)}}} will not be exported.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c ;)}}} ::
+ #+kindex: C-c ;
+
+ Toggle the COMMENT keyword at the beginning of an entry.
+
+** Images and tables
+ :PROPERTIES:
+ :DESCRIPTION: Tables and images can be exported
+ :END:
+
+#+cindex: tables, markup rules
+#+cindex: #+CAPTION
+#+cindex: #+LABEL
+
+Both the native Org mode tables (see [[Tables]]) and tables formatted with
+the {{{file(table.el)}}} package will be exported properly. For Org
+mode tables, the lines before the first horizontal separator line will
+become table header lines. You can use the following lines somewhere
+before the table to assign a caption and a label for cross references,
+and in the text you can refer to the object with
+~\ref{tab:basic-data}~:
+
+#+begin_example
+ #+CAPTION: This is the caption for the next table (or link)
+ #+LABEL: tab:basic-data
+ | ... | ...|
+ |-----|----|
+#+end_example
+
+Optionally, the caption can take the form:
+#+begin_example
+ #+CAPTION: [Caption for list of figures]{Caption for table (or link).}
+#+end_example
+
+#+cindex: inlined images, markup rules
+
+Some backends (HTML, LaTeX, and DocBook) allow you to directly
+include images into the exported document. Org does this, if a link to
+an image files does not have a description part, for example
+~[[./img/a.jpg]]~. If you wish to define a caption for the image and maybe
+a label for internal cross references, make sure that the link is on a
+line by itself and precede it with ~#+CAPTION~ and ~#+LABEL~ as
+follows:
+
+#+begin_example
+ #+CAPTION: This is the caption for the next figure link (or table)
+ #+LABEL: fig:SED-HR4049
+ [[./img/a.jpg]]
+#+end_example
+
+You may also define additional attributes for the figure. As this is
+backend-specific, see the sections about the individual backends for
+more information.
+
+See [[Handling links][the discussion of image links]].
+
+** Literal examples
+ :PROPERTIES:
+ :DESCRIPTION: Source code examples with special formatting
+ :END:
+#+cindex: literal examples, markup rules
+#+cindex: code line references, markup rules
+
+You can include literal examples that should not be subjected to
+markup. Such examples will be typeset in monospace, so this is well
+suited for source code and similar examples.
+#+cindex: #+BEGIN_EXAMPLE
+
+#+begin_example
+ ,#+BEGIN_EXAMPLE
+ Some example from a text file.
+ ,#+END_EXAMPLE
+#+end_example
+
+Note that such blocks may be /indented/ in order to align nicely with
+indented text and in particular with plain list structure (see [[Plain
+lists]]). For simplicity when using small examples, you can also start
+the example lines with a colon followed by a space. There may also be
+additional whitespace before the colon:
+
+#+begin_example
+ Here is an example
+ : Some example from a text file.
+#+end_example
+
+#+cindex: formatting source code, markup rules
+
+If the example is source code from a programming language, or any
+other text that can be marked up by font-lock in Emacs, you can ask
+for the example to look like the fontified Emacs buffer.[fn:102] This
+is done with the {{{samp(src)}}} block, where you also need to specify
+the name of the major mode that should be used to fontify the example,
+see [[Easy templates]] for shortcuts to easily insert code blocks.[fn:103]
+
+#+cindex: #+BEGIN_SRC
+
+#+begin_example
+ #+BEGIN_SRC emacs-lisp
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+ #+END_SRC
+#+end_example
+
+Both in ~example~ and in ~src~ snippets, you can add a ~-n~ switch to
+the end of the ~BEGIN~ line, to get the lines of the example numbered.
+If you use a ~+n~ switch, the numbering from the previous numbered
+snippet will be continued in the current one. In literal examples, Org
+will interpret strings like {{{samp((ref:name))}}} as labels, and use
+them as targets for special hyperlinks like ~[[(name)]]~ (i.e., the
+reference name enclosed in single parenthesis). In HTML, hovering the
+mouse over such a link will remote-highlight the corresponding code
+line, which is kind of cool.
+
+You can also add a ~-r~ switch which /removes/ the labels from the
+source code.[fn:104] With the ~-n~ switch, links to these references
+will be labeled by the line numbers from the code listing, otherwise
+links will use the labels with no parentheses. Here is an example:
+
+#+begin_example
+ #+BEGIN_SRC emacs-lisp -n -r
+ (save-excursion (ref:sc)
+ (goto-char (point-min)) (ref:jump)
+ #+END_SRC
+ In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
+ jumps to point-min.
+#+end_example
+
+#+vindex: org-coderef-label-format
+
+If the syntax for the label format conflicts with the language syntax,
+use a ~-l~ switch to change the format, for example
+{{{samp(#+BEGIN_SRC pascal -n -r -l "((%s))")}}}. See also the
+variable ~org-coderef-label-format~.
+
+HTML export also allows examples to be published as text areas
+(see [[Text areas in HTML export]]).
+
+Because the ~#+BEGIN_...~ and ~#+END_...~ patterns need to be added so
+often, shortcuts are provided using the Easy Templates facility (see
+[[Easy templates]]).
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c ')}}} ::
+ #+kindex: C-c '
+
+ Edit the source code example at point in its native mode. This works
+ by switching to a temporary buffer with the source code. You need to
+ exit by pressing {{{kbd(C-c ')}}} again.[fn:105] The edited version
+ will then replace the old version in the Org buffer. Fixed-width
+ regions (where each line starts with a colon followed by a space) will
+ be edited using ~artist-mode~ to allow creating ASCII drawings
+ easily.[fn:106] Using this command in an empty line will create a new
+ fixed-width region.
+
+- {{{kbd(C-c l)}}} ::
+ #+kindex: C-c l
+
+ Calling ~org-store-link~ while editing a source code example in a
+ temporary buffer created with {{{kbd(C-c ')}}} will prompt for a
+ label. Make sure that it is unique in the current buffer, and insert
+ it with the proper formatting like {{{samp((ref:label))}}} at the end
+ of the current line. Then the label is stored as a link
+ {{{samp((label))}}}, for retrieval with {{{kbd(C-c C-l)}}}.
+
+** Include files
+ :PROPERTIES:
+ :DESCRIPTION: Include additional files into a document
+ :END:
+#+cindex: include files, markup rules
+
+During export, you can include the content of another file. For
+example, to include your {{{file(.emacs)}}} file, you could use:
+
+#+cindex: #+INCLUDE
+
+#+begin_example
+ ,#+INCLUDE: "~/.emacs" src emacs-lisp
+#+end_example
+
+{{{noindent}}} The optional second and third parameter are the markup
+(e.g., {{{samp(quote)}}}, {{{samp(example)}}}, or {{{samp(src)}}}),
+and, if the markup is {{{samp(src)}}}, the language for formatting the
+contents. The markup is optional; if it is not given, the text will be
+assumed to be in Org mode format and will be processed normally. The
+include line will also allow additional keyword parameters ~:prefix1~
+and ~:prefix~ to specify prefixes for the first line and for each
+following line, ~:minlevel~ in order to get Org mode content demoted
+to a specified level, as well as any options accepted by the selected
+markup. For example, to include a file as an item, use:
+
+#+begin_example
+ ,#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
+#+end_example
+
+You can also include a portion of a file by specifying a lines range
+using the ~:lines~ parameter. The line at the upper end of the range
+will not be included. The start and/or the end of the range may be
+omitted to use the obvious defaults.
+
+#+attr_texinfo: :table-type table :indic @asis
+- #+INCLUDE: "~/.emacs" :lines "5-10" ::
+
+ Include lines 5 to 10, 10 excluded.
+
+- #+INCLUDE: "~/.emacs" :lines "-10" ::
+
+ Include lines 1 to 10, 10 excluded.
+
+- #+INCLUDE: "~/.emacs" :lines "10-" ::
+
+ Include lines from 10 to EOF.
+
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c ')}}}
+ #+kindex: C-c '
+
+ Visit the include file at point.
+
+** Index entries
+ :PROPERTIES:
+ :DESCRIPTION: Making an index
+ :END:
+#+cindex: index entries, for publishing
+
+You can specify entries that will be used for generating an index
+during publishing. This is done by lines starting with ~#+INDEX~. An
+entry the contains an exclamation mark will create a sub item. See
+[[Generating an index]] for more information.
+
+#+begin_example
+ ,* Curriculum Vitae
+ #+INDEX: CV
+ #+INDEX: Application!CV
+#+end_example
+
+** Macro replacement
+ :PROPERTIES:
+ :DESCRIPTION: Use macros to create complex output
+ :END:
+#+cindex: macro replacement, during export
+#+cindex: #+MACRO
+
+You can define text snippets with a macro:
+
+#+begin_example
+ ,#+MACRO: name replacement text $1, $2 are arguments
+#+end_example
+
+{{{noindent}}} which can be referenced anywhere in the document (even in
+code examples) with ~{{{name(arg1,arg2)}}}~. In addition to
+defined macros, ~{{{title}}}~, ~{{{author}}}~, etc.,
+will reference information set by the ~#+TITLE:~, ~#+AUTHOR:~, and
+similar lines. Also, ~{{{date(FORMAT)}}}~ and
+~{{{modification-time(FORMAT)}}}~ refer to current date time
+and to the modification time of the file being exported, respectively.
+~FORMAT~ should be a format string understood by
+~format-time-string~.
+
+Macro expansion takes place during export, and some people use it to
+construct complex HTML code.
+
+** FIXME Embedded LaTeX
+ :PROPERTIES:
+ :DESCRIPTION: LaTeX can be freely used inside Org documents
+ :ALT_TITLE: Embedded Latex
+ :END:
+#+cindex: @TeX{} interpretation
+#+cindex: @LaTeX{} interpretation
+
+Plain ASCII is normally sufficient for almost all note taking.
+Exceptions include scientific notes, which often require mathematical
+symbols and the occasional formula. LaTeX is widely used to typeset
+scientific documents.[fn:107] Org mode supports embedding LaTeX
+code into its files, because many academics are used to writing and
+reading LaTeX source code, and because it can be readily processed
+to produce pretty output for a number of export backends.
+
+*** Special symbols
+ :PROPERTIES:
+ :DESCRIPTION: Greek letters and other symbols
+ :END:
+#+cindex: math symbols
+#+cindex: special symbols
+#+cindex: @TeX{} macros
+#+cindex: @LaTeX{} fragments, markup rules
+#+cindex: HTML entities
+#+cindex: @LaTeX{} entities
+
+You can use LaTeX macros to insert special symbols like
+~\alpha~ to indicate the Greek letter, or ~\to~ to
+indicate an arrow. Completion for these macros is available, just type
+~\~ and maybe a few letters, and press {{{kbdkey(M-,TAB)}}}
+to see possible completions. Unlike LaTeX code, Org mode allows
+these macros to be present without surrounding math delimiters, for
+example:
+
+#+begin_example
+ Angles are written as Greek letters \alpha, \beta and \gamma.
+#+end_example
+
+#+vindex: org-entities
+
+During export, these symbols will be transformed into the native
+format of the exporter backend. Strings like ~\alpha~ will be exported
+as ~&alpha;~ in the HTML output, and as ~$\alpha$~ in the LaTeX
+output. Similarly, ~\nbsp~ will become ~&nbsp;~ in HTML and ~~~ in
+LaTeX. If you need such a symbol inside a word, terminate it like
+this: ~\Aacute{}stor~.
+
+A large number of entities is provided, with names taken from both
+HTML and LaTeX; see the variable ~org-entities~ for the complete
+list. ~\-~ is treated as a shy hyphen, and {{{samp(--)}}},
+{{{samp(---)}}}, and {{{samp(...)}}} are all converted into special
+commands creating hyphens of different lengths or a compact set of
+dots.
+
+If you would like to see entities displayed as UTF8 characters, use the
+following command:[fn:108]
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x XXX)}}} ::
+ #+kindex: C-c C-x XXX
+# Should be \
+ Toggle display of entities as UTF-8 characters. This does not change
+ the buffer content which remains plain ASCII, but it overlays the
+ UTF-8 character for display purposes only.
+
+*** FIXME Subscripts and superscripts
+ :PROPERTIES:
+ :DESCRIPTION: Simple syntax for raising/lowering text
+ :END:
+#+cindex: subscript
+#+cindex: superscript
+
+Just like in LaTeX, {{{samp(^)}}} and {{{samp(_)}}} are used to
+indicate super- and subscripts. Again, these can be used without
+embedding them in math-mode delimiters. To increase the readability of
+ASCII text, it is not necessary (but OK) to surround multi-character
+sub- and superscripts with curly braces. For example
+
+#+begin_example
+ The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
+ the sun is R_{sun} = 6.96 x 10^8 m.
+#+end_example
+
+#+vindex: org-export-with-sub-superscripts
+
+To avoid interpretation as raised or lowered text, you can quote
+{{{kbd(^)}}} and {{{kbd(_)}}} with a backslash: ~\^~ and ~\_~. If you
+write a text where the underscore is often used in a different
+context, Org's convention to always interpret these as subscripts can
+get in your way. Configure the variable
+~org-export-with-sub-superscripts~ to globally change this convention,
+or use, on a per-file basis:
+
+#+begin_example
+ ,#+OPTIONS: ^:{}
+#+end_example
+
+{{{noindent}}} With this setting, ~a_b~ will not be interpreted as a
+subscript, but ~a_{b}~ will.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x XXX)}}} ::
+ #+kindex: C-c C-x XXX
+# Should be \
+ In addition to showing entities as UTF-8 characters, this command will
+ also format sub- and superscripts in a WYSIWYM way.
+
+*** LaTeX fragments
+ :PROPERTIES:
+ :DESCRIPTION: Complex formulas made easy
+ :END:
+#+cindex: @LaTeX{} fragments
+#+vindex: org-format-latex-header
+
+Going beyond symbols and sub- and superscripts, a full formula
+language is needed. Org mode can contain LaTeX math fragments, and
+it supports ways to process these for several export backends. When
+exporting to LaTeX, the code is obviously left as it is. When
+exporting to HTML, Org invokes the [[http://www.mathjax.org][MathJax library]] (see [[Math
+formatting in HTML export]]) to process and display the math.[fn:109]
+Finally, it can also process the mathematical expressions into images
+that can be displayed in a browser or in DocBook documents.[fn:110]
+
+LaTeX fragments don't need any special marking at all. The following
+snippets will be identified as LaTeX source code:
+
+- Environments of any kind.[fn:111] The only requirement is that the
+ ~\begin~ statement appears on a new line, preceded by only whitespace.
+
+- Text within the usual LaTeX math delimiters. To avoid conflicts
+ with currency specifications, single ~$~ characters are
+ only recognized as math delimiters if the enclosed text contains at
+ most two line breaks, is directly attached to the ~$~
+ characters with no whitespace in between, and if the closing
+ ~$~ is followed by whitespace, punctuation or a dash. For
+ the other delimiters, there is no such restriction, so when in
+ doubt, use ~\(...\)~ as inline math delimiters.
+
+
+{{{noindent}}} For example:
+
+#+begin_example
+ \begin{equation} % arbitrary environments,
+ x=\sqrt{b} % even tables, figures
+ \end{equation} % etc
+
+ If $a^2=b$ and \( b=2 \), then the solution must be
+ either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
+#+end_example
+
+{{{noindent}}}
+#+vindex: org-format-latex-options
+
+If you need any of the delimiter ASCII sequences for other purposes,
+you can configure the option ~org-format-latex-options~ to deselect
+the ones you do not wish to have interpreted by the LaTeX
+converter.
+
+#+vindex: org-export-with-LaTeX-fragments
+
+LaTeX processing can be configured with the variable
+~org-export-with-LaTeX-fragments~. The default setting is ~t~ which
+means {{{file(MathJax)}}} for HTML, and no processing for DocBook,
+ASCII and LaTeX backends. You can also set this variable on a
+per-file basis using one of these lines:
+
+#+attr_texinfo: :table-type table :indic @asis
+- #+OPTIONS: LaTeX:t ::
+
+ Do the right thing automatically (MathJax).
+
+- #+OPTIONS: LaTeX:dvipng ::
+
+ Force using dvipng images.
+
+- #+OPTIONS: LaTeX:nil ::
+
+ Do not process LaTeX fragments at all
+
+- #+OPTIONS: LaTeX:verbatim ::
+
+ Verbatim export, for jsMath or so.
+
+*** Previewing LaTeX fragments
+ :PROPERTIES:
+ :DESCRIPTION: What will this snippet look like?
+ :END:
+#+cindex: @LaTeX{} fragments, preview
+
+If you have {{{file(dvipng)}}} installed, LaTeX fragments can be
+processed to produce preview images of the typeset expressions:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-x C-l)}}} ::
+ #+kindex: C-c C-x C-l
+
+ Produce a preview image of the LaTeX fragment at point and overlay
+ it over the source code. If there is no fragment at point, process all
+ fragments in the current entry (between two headlines). When called
+ with a prefix argument, process the entire subtree. When called with
+ two prefix arguments, or when the cursor is before the first headline,
+ process the entire buffer.
+
+- {{{kbd(C-c C-c)}}} ::
+ #+kindex: C-c C-c
+
+ Remove the overlay preview images.
+
+
+#+vindex: org-format-latex-options
+
+You can customize the variable ~org-format-latex-options~ to influence
+some aspects of the preview. In particular, the ~:scale~ (and for HTML
+export, ~:html-scale~) property can be used to adjust the size of the
+preview images.
+
+*** CDLaTeX mode
+ :PROPERTIES:
+ :DESCRIPTION: Speed up entering of formulas
+ :TITLE: Using CDLaTeX to enter math
+ :END:
+#+cindex: CD@LaTeX{}
+
+CDLaTeX mode is a minor mode that is normally used in combination
+with a major LaTeX mode like AUCTeX in order to speed-up
+insertion of environments and math templates. Inside Org mode, you can
+make use of some of the features of CDLaTeX mode. You need to
+install {{{file(cdlatex.el)}}} and {{{file(texmathp.el)}}} (the latter
+comes also with AUCTeX) from
+[[http://www.astro.uva.nl/~dominik/Tools/cdlatex]]. Don't use CDLaTeX
+mode itself under Org mode, but use the light version
+~org-cdlatex-mode~ that comes as part of Org mode. Turn it on for the
+current buffer with ~M-x org-cdlatex-mode~, or for all Org files with
+this hook:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
+#+end_src
+
+When this mode is enabled, the following features are present (for more
+details see the documentation of CDLaTeX mode):
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c {)}}} ::
+ #+kindex: C-c @{
+
+ Insert an environment template.
+
+- {{{key(TAB)}}} ::
+ #+kindex: @key{TAB}
+
+ Expand a template if the cursor is inside a LaTeX fragment.[fn:112]
+ For example, {{{key(TAB)}}} will expand ~fr~ to ~\frac{}{}~ and
+ position the cursor correctly inside the first brace. Another
+ {{{key(TAB)}}} will get you into the second brace. Even outside
+ fragments, {{{key(TAB)}}} will expand environment abbreviations at the
+ beginning of a line. For example, if you write {{{samp(equ)}}} at the
+ beginning of a line and press {{{key(TAB)}}}, this abbreviation will
+ be expanded to an ~equation~ environment. To get a list of all
+ abbreviations, type {{{kbd(M-x cdlatex-command-help)}}}.
+
+- {{{kbd(_)}}} {{{kbd(^)}}} ::
+ #+kindex: _
+ #+kindex: ^
+ #+vindex: cdlatex-simplify-sub-super-scripts
+
+ Pressing {{{kbd(_)}}} and {{{kbd(^)}}} inside a LaTeX fragment will
+ insert these characters together with a pair of braces. If you use
+ {{{key(TAB)}}} to move out of the braces, and if the braces surround
+ only a single character or macro, they are removed again (depending on
+ the variable ~cdlatex-simplify-sub-super-scripts~).
+
+- {{{kbd(`)}}} ::
+ #+kindex: `
+
+ Pressing the backquote followed by a character inserts math macros,
+ also outside LaTeX fragments. If you wait more than 1.5 seconds
+ after the backquote, a help window will pop up.
+
+- {{{kbd(')}}} ::
+ #+kindex: '
+
+ Pressing the single-quote followed by another character modifies the
+ symbol before point with an accent or a font. If you wait more than
+ 1.5 seconds after the single-quote, a help window will pop up.
+ Character modification will work only inside LaTeX fragments;
+ outside the quote is normal.
+
+* FIXME Exporting
+ :PROPERTIES:
+ :DESCRIPTION: Sharing and publishing notes
+ :END:
+#+cindex: exporting
+
+Org mode documents can be exported into a variety of other formats.
+For printing and sharing of notes, ASCII export produces a readable
+and simple version of an Org file. HTML export allows you to publish a
+notes file on the web, while the XOXO format provides a solid base for
+exchange with a broad range of other applications. LaTeX export
+lets you use Org mode and its structured editing functions to easily
+create LaTeX files. DocBook export makes it possible to convert Org
+files to many other formats using DocBook tools. OpenDocument Text
+(ODT) export allows seamless collaboration across organizational
+boundaries. For project management you can create gantt and resource
+charts by using TaskJuggler export. To incorporate entries with
+associated times like deadlines or appointments into a desktop
+calendar program like iCal, Org mode can also produce extracts in the
+iCalendar format. Currently, Org mode only supports export, not import
+of these different formats.
+
+Org supports export of selected regions when ~transient-mark-mode~ is
+enabled (default in Emacs 23).
+
+** Selective export
+ :PROPERTIES:
+ :DESCRIPTION: Using tags to select and exclude trees
+ :END:
+#+cindex: export, selective by tags or TODO keyword
+#+vindex: org-export-select-tags
+#+vindex: org-export-exclude-tags
+#+cindex: org-export-with-tasks
+
+You may use tags to select the parts of a document that should be exported,
+or to exclude parts from export. This behavior is governed by two variables:
+~org-export-select-tags~ and ~org-export-exclude-tags~,
+respectively defaulting to ~:export:~ and ~:noexport:~.
+
+1. Org first checks if any of the /select/ tags is present in the
+ buffer. If yes, all trees that do not carry one of these tags will
+ be excluded. If a selected tree is a subtree, the heading hierarchy
+ above it will also be selected for export, but not the text below
+ those headings.
+
+2. If none of the select tags is found, the whole buffer will be
+ selected for export.
+
+3. Finally, all subtrees that are marked by any of the /exclude/ tags
+ will be removed from the export buffer.
+
+
+The variable ~org-export-with-tasks~ can be configured to select which
+kind of tasks should be included for export. See the docstring of the
+variable for more information.
+
+** FIXME Export options
+ :PROPERTIES:
+ :DESCRIPTION: Per-file export settings
+ :END:
+#+cindex: options, for export
+#+cindex: completion, of option keywords
+
+The exporter recognizes special lines in the buffer which provide
+additional information. These lines may be put anywhere in the file.
+The whole set of lines can be inserted into the buffer with
+{{{kbd(C-c C-e t)}}}. For individual lines, a good way to make sure the keyword
+is correct is to type {{{samp(#+)}}} and then use {{{kbdkey(M-,TAB)}}}
+completion (see [[Completion]]). For a summary of other in-buffer settings
+not specifically related to export, see [[In-buffer settings]]. In
+particular, note that you can place commonly-used (export) options in
+a separate file which can be included using ~#+SETUPFILE~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e t)}}}, ~org-insert-export-options-template~ ::
+ #+kindex: C-c C-e t
+
+ Insert template with export options, see example below.
+
+
+#+cindex: #+TITLE
+#+cindex: #+AUTHOR
+#+cindex: #+DATE
+#+cindex: #+EMAIL
+#+cindex: #+DESCRIPTION
+#+cindex: #+KEYWORDS
+#+cindex: #+LANGUAGE
+#+cindex: #+TEXT
+#+cindex: #+OPTIONS
+#+cindex: #+BIND
+#+cindex: #+LINK_UP
+#+cindex: #+LINK_HOME
+#+cindex: #+EXPORT_SELECT_TAGS
+#+cindex: #+EXPORT_EXCLUDE_TAGS
+#+cindex: #+XSLT
+#+cindex: #+LaTeX_HEADER
+#+vindex: user-full-name
+#+vindex: user-mail-address
+#+vindex: org-export-default-language
+#+vindex: org-export-date-timestamp-format
+
+#+attr_texinfo: :table-type table :indic @asis
+- #+TITLE: ::
+
+ The title to be shown (default is the buffer name).
+
+- #+AUTHOR: ::
+
+ The author (default taken from ~user-full-name~).
+
+- #+DATE: ::
+
+ A date, an Org timestamp, or a format string for
+ ~format-time-string~.[fn:113]
+
+- #+EMAIL: ::
+
+ His/her email address (default from ~user-mail-address~).
+
+- #+DESCRIPTION: ::
+
+ The page description, e.g., for the XHTML meta tag.
+
+- #+KEYWORDS: ::
+
+ The page keywords, e.g., for the XHTML meta tag.
+
+- #+LANGUAGE: ::
+
+ Language for HTML, e.g., en (~org-export-default-language~).
+
+- #+TEXT: ::
+
+ Some descriptive text to be inserted at the beginning.
+
+- #+TEXT: ::
+
+ Several lines may be given.
+
+- #+OPTIONS: ::
+
+ H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
+
+- #+BIND: ::
+
+ Lisp-var lisp-val, e.g., org-export-latex-low-levels itemize. You need
+ to confirm using these, or configure ~org-export-allow-BIND~.
+
+- #+LINK_UP: ::
+
+ The ``up'' link of an exported page.
+
+- #+LINK_HOME: ::
+
+ The ``home'' link of an exported page.
+
+- #+LaTeX_HEADER: ::
+
+ Extra line(s) for the LaTeX header, like ~\usepackage{xyz}~.
+
+- #+EXPORT_SELECT_TAGS: ::
+
+ Tags that select a tree for export.
+
+- #+EXPORT_EXCLUDE_TAGS: ::
+
+ Tags that exclude a tree from export.
+
+- #+XSLT: ::
+
+ The XSLT stylesheet used by DocBook exporter to generate FO file.
+
+
+
+{{{noindent}}} The ~#+OPTIONS~ line is a compact form to specify
+export settings.[fn:114] Here you can:
+
+#+cindex: headline levels
+#+cindex: section-numbers
+#+cindex: table of contents
+#+cindex: line-break preservation
+#+cindex: quoted HTML tags
+#+cindex: fixed-width sections
+#+cindex: tables
+#+cindex: @TeX{}-like syntax for sub- and superscripts
+#+cindex: footnotes
+#+cindex: special strings
+#+cindex: emphasized text
+#+cindex: @TeX{} macros
+#+cindex: @LaTeX{} fragments
+#+cindex: author info, in export
+#+cindex: time info, in export
+#+vindex: org-export-plist-vars
+#+vindex: org-export-author-info
+#+vindex: org-export-creator-info
+#+vindex: org-export-email-info
+#+vindex: org-export-time-stamp-file
+
+#+attr_texinfo: :table-type table :indic @code
+- H: ::
+
+ Set the number of headline levels for export.
+
+- num: ::
+
+ Turn on/off section-numbers.
+
+- toc: ::
+
+ Turn on/off table of contents, or set level limit (integer).
+
+- \n: ::
+
+ Turn on/off line-break-preservation (DOES NOT WORK).
+
+- @: ::
+
+ Turn on/off quoted HTML tags.
+
+- :: ::
+
+ Turn on/off fixed-width sections.
+
+- |: ::
+
+ Turn on/off tables,
+
+- ^: ::
+
+ Turn on/off TeX-like syntax for sub- and superscripts. If you write
+ "^:{}", ~a_{b}~ will be interpreted, but the simple ~a_b~ will be left
+ as it is.
+
+- : ::
+
+ Turn on/off conversion of special strings.
+
+- f: ::
+
+ Turn on/off footnotes like this: ~[1]~.
+
+- todo: ::
+
+ Turn on/off inclusion of TODO keywords into exported text.
+
+- tasks: ::
+
+ Turn on/off inclusion of tasks (TODO items), can be nil to remove all
+ tasks, ~todo~ to remove DONE tasks, or list of keywords to keep.
+
+- pri: ::
+
+ Turn on/off priority cookies.
+
+- tags: ::
+
+ Turn on/off inclusion of tags, may also be ~not-in-toc~.
+
+- <: ::
+
+ Turn on/off inclusion of any time/date stamps like DEADLINES.
+
+- *: ::
+
+ Turn on/off emphasized text (bold, italic, underlined).
+
+- TeX: ::
+
+ Turn on/off simple TeX macros in plain text.
+
+- LaTeX: ::
+
+ Configure export of LaTeX fragments. Default ~auto~.
+
+- skip: ::
+
+ Turn on/off skipping the text before the first heading.
+
+- author: ::
+
+ Turn on/off inclusion of author name/email into exported file.
+
+- email: ::
+
+ Turn on/off inclusion of author email into exported file.
+
+- creator: ::
+
+ Turn on/off inclusion of creator info into exported file.
+
+- timestamp: ::
+
+ Turn on/off inclusion creation time into exported file.
+
+- d: ::
+
+ Turn on/off inclusion of drawers, or list drawers to include.
+
+
+{{{noindent}}} These options take effect in both the HTML and LaTeX
+export, except for ~TeX~ and ~LaTeX~ options, which are respectively
+~t~ and ~nil~ for the LaTeX export.
+
+The default values for these and many other options are given by a set
+of variables. For a list of such variables, the corresponding OPTIONS
+keys and also the publishing keys (see [[Project alist]]), see the
+constant ~org-export-plist-vars~.
+
+When exporting only a single subtree by selecting it with
+{{{kbd(C-c @)}}} before calling an export command, the subtree can
+overrule some of the file's export settings with properties
+~EXPORT_FILE_NAME~, ~EXPORT_TITLE~, ~EXPORT_TEXT~, ~EXPORT_AUTHOR~,
+~EXPORT_DATE~, and ~EXPORT_OPTIONS~.
+
+** The export dispatcher
+ :PROPERTIES:
+ :DESCRIPTION: How to access exporter commands
+ :END:
+#+cindex: dispatcher, for export commands
+
+All export commands can be reached using the export dispatcher, which
+is a prefix key that prompts for an additional key specifying the
+command. Normally the entire file is exported, but if there is an
+active region that contains one outline tree, the first heading is
+used as document title and the subtrees are exported.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e)}}}, ~org-export~ ::
+ #+kindex: C-c C-e
+ #+vindex: org-export-run-in-background
+
+ Dispatcher for export and publishing commands. Displays a help-window
+ listing the additional key(s) needed to launch an export or publishing
+ command. The prefix arg is passed through to the exporter. A double
+ prefix {{{kbd(C-u C-u)}}} causes most commands to be executed in the
+ background, in a separate Emacs process.[fn:115]
+
+- {{{kbd(C-c C-e v)}}}, ~org-export-visible~ ::
+ #+kindex: C-c C-e v
+
+ Like {{{kbd(C-c C-e)}}}, but only export the text that is currently visible
+ (i.e., not hidden by outline visibility).
+
+- {{{kbd(C-u C-u C-c C-e)}}}, ~org-export~ ::
+ #+kindex: C-u C-u C-c C-e
+ #+vindex: org-export-run-in-background
+
+ Call the exporter, but reverse the setting of
+ ~org-export-run-in-background~, i.e., request background processing if
+ not set, or force processing in the current Emacs process if set.
+
+** ASCII/Latin-1/UTF-8 export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to flat files with encoding
+ :END:
+#+cindex: ASCII export
+#+cindex: Latin-1 export
+#+cindex: UTF-8 export
+
+ASCII export produces a simple and very readable version of an Org
+mode file, containing only plain ASCII. Latin-1 and UTF-8 export
+augment the file with special characters and symbols available in
+these encodings.
+
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient-mark-mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e a)}}}, ~org-export-as-ascii~ ::
+ #+kindex: C-c C-e a
+ #+cindex: property, EXPORT_FILE_NAME
+
+ Export as an ASCII file. For an Org file, {{{file(myfile.org)}}}, the
+ ASCII file will be {{{file(myfile.txt)}}}. The file will be
+ overwritten without warning. If there is an active region, only the
+ region will be exported.[fn:116] If the selected region is a single
+ tree, the tree head will become the document title.[fn:117] If the
+ tree head entry has or inherits an ~EXPORT_FILE_NAME~ property, that
+ name will be used for the export.
+
+- {{{kbd(C-c C-e A)}}}, ~org-export-as-ascii-to-buffer~ ::
+ #+kindex: C-c C-e A
+
+ Export to a temporary buffer. Do not create a file.
+
+- {{{kbd(C-c C-e n)}}}, ~org-export-as-latin1~ ::
+ #+kindex: C-c C-e n
+
+ Like {{{kbd(C-c C-e a)}}}, but use Latin-1 encoding.
+
+- {{{kbd(C-c C-e N)}}}, ~org-export-as-latin1-to-buffer~ ::
+ #+kindex: C-c C-e N
+
+ Like {{{kbd(C-c C-e A)}}}, but use Latin-1 encoding.
+
+- {{{kbd(C-c C-e u)}}}, ~org-export-as-utf8~ ::
+ #+kindex: C-c C-e u
+
+ Like {{{kbd(C-c C-e a)}}}, but use UTF-8 encoding.
+
+- {{{kbd(C-c C-e U)}}}, ~org-export-as-utf8-to-buffer~ ::
+ #+kindex: C-c C-e U
+
+ Like {{{kbd(C-c C-e A)}}}, but use UTF-8 encoding.
+
+
+- {{{kbd(C-c C-e v a/n/u)}}} ::
+ #+kindex: C-c C-e v a
+ #+kindex: C-c C-e v n
+ #+kindex: C-c C-e v u
+
+ Export only the visible part of the document.
+
+
+#+cindex: headline levels, for exporting
+
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemized lists. If you want that transition to
+occur at a different level, specify it with a prefix argument, e.g.:
+
+#+begin_example
+ C-1 C-c C-e a
+#+end_example
+
+{{{noindent}}} This setting creates only top level headlines and
+exports the rest as items. When headlines are converted to items, the
+indentation of the text following the headline is changed to fit
+nicely under the item. This is done with the assumption that the first
+body line indicates the base indentation of the body text. Any
+indentation larger than this is adjusted to preserve the layout
+relative to the first line. Should there be lines with less
+indentation than the first one, these are left alone.
+
+#+vindex: org-export-ascii-links-to-notes
+
+Links will be exported in a footnote-like style, with the descriptive
+part in the text and the link in a note before the next heading. See
+the variable ~org-export-ascii-links-to-notes~ for details and other
+options.
+
+** HTML export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to HTML
+ :END:
+#+cindex: HTML export
+#+cindex: Gruber, John
+
+Org mode contains a HTML (XHTML 1.0 strict) exporter with extensive
+HTML formatting, in ways similar to John Gruber's /markdown/ language,
+but with additional support for tables.
+
+*** HTML export commands
+ :PROPERTIES:
+ :DESCRIPTION: How to invoke HTML export
+ :END:
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient-mark-mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e h)}}}, ~org-export-as-html~ ::
+ #+kindex: C-c C-e h
+ #+cindex: property, EXPORT_FILE_NAME
+
+ Export as an HTML file. For an Org file {{{file(myfile.org)}}}, the
+ HTML file will be {{{file(myfile.html)}}}. The file will be
+ overwritten without warning. If there is an active region, only the
+ active region will be exported.[fn:118] If the selected region is a
+ single tree, the tree head will become the document title.[fn:119] If
+ the tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property,
+ that name will be used for the export.
+
+- {{{kbd(C-c C-e b)}}}, ~org-export-as-html-and-open~ ::
+ #+kindex: C-c C-e b
+
+ Export as a HTML file and immediately open it with a browser.
+
+- {{{kbd(C-c C-e H)}}}, ~org-export-as-html-to-buffer~ ::
+ #+kindex: C-c C-e H
+
+ Export to a temporary buffer. Do not create a file.
+
+- {{{kbd(C-c C-e R)}}}, ~org-export-region-as-html~ ::
+ #+kindex: C-c C-e R
+
+ Export the active region to a temporary buffer. With a prefix
+ argument, do not produce the file header and footer, but just the
+ plain HTML section for the region. This is good for cut-and-paste
+ operations.
+
+- {{{kbd(C-c C-e v h/b/H/R)}}} ::
+ #+kindex: C-c C-e v h
+ #+kindex: C-c C-e v b
+ #+kindex: C-c C-e v H
+ #+kindex: C-c C-e v R
+
+ Export only the visible part of the document.
+
+- {{{kbd(M-x org-export-region-as-html)}}} ::
+
+ Convert the region to HTML under the assumption that it was in Org
+ mode syntax before. This is a global command that can be invoked in
+ any buffer.
+
+- {{{kbd(M-x org-replace-region-by-HTML)}}} ::
+
+ Replace the active region (assumed to be in Org mode syntax) by HTML
+ code.
+
+
+#+cindex: headline levels, for exporting
+
+In the exported version, the first three outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemized lists. If you want that transition to
+occur at a different level, specify it with a numeric prefix argument,
+e.g.:
+
+#+begin_example
+ C-2 C-c C-e b
+#+end_example
+
+{{{noindent}}} This setting creates two levels of headings and exports
+the rest as list items.
+
+*** HTML preamble and postamble
+ :PROPERTIES:
+ :DESCRIPTION: How to insert a preamble and postamble
+ :END:
+#+vindex: org-export-html-preamble
+#+vindex: org-export-html-postamble
+#+vindex: org-export-html-preamble-format
+#+vindex: org-export-html-postamble-format
+#+vindex: org-export-html-validation-link
+#+vindex: org-export-author-info
+#+vindex: org-export-email-info
+#+vindex: org-export-creator-info
+#+vindex: org-export-time-stamp-file
+
+The HTML exporter lets you define a preamble and a postamble.
+
+The default value for ~org-export-html-preamble~ is ~t~, which means
+that the preamble is inserted depending on the relevant format string
+in ~org-export-html-preamble-format~.
+
+Setting ~org-export-html-preamble~ to a string will override the default
+format string. Setting it to a function, will insert the output of the
+function, which must be a string; such a function takes no argument but you
+can check against the value of ~opt-plist~, which contains the list of
+publishing properties for the current file. Setting to ~nil~ will not
+insert any preamble.
+
+The default value for ~org-export-html-postamble~ is
+{{{samp('auto)}}}, which means that the HTML exporter will look for
+the value of ~org-export-author-info~, ~org-export-email-info~,
+~org-export-creator-info~ and ~org-export-time-stamp-file~,
+~org-export-html-validation-link~ and build the postamble from these
+values. Setting ~org-export-html-postamble~ to ~t~ will insert the
+postamble from the relevant format string found in
+~org-export-html-postamble-format~. Setting it to ~nil~ will not
+insert any postamble.
+
+*** Quoting HTML tags
+ :PROPERTIES:
+ :DESCRIPTION: Using direct HTML in Org mode
+ :END:
+
+Plain ~<~ and {{{samp(>)}}} are always transformed to
+{{{samp(&lt;)}}} and {{{samp(&gt;)}}} in HTML export. If you want to
+include simple HTML tags which should be interpreted as such, mark
+them with {{{samp(@)}}} as in {{{samp(@<b>bold text@</b>)}}}. Note
+that this really works only for simple tags. For more extensive HTML
+that should be copied verbatim to the exported file use either ~#+HTML~:
+
+#+cindex: #+HTML
+#+cindex: #+BEGIN_HTML
+#+begin_example
+ ,#+HTML: Literal HTML code for export
+#+end_example
+
+{{{noindent}}} or an HTML block:
+#+cindex: #+BEGIN_HTML
+
+#+begin_example
+ #+BEGIN_HTML
+ All lines between these markers are exported literally
+ #+END_HTML
+#+end_example
+
+*** Links in HTML export
+ :PROPERTIES:
+ :DESCRIPTION: How links will be interpreted and formatted
+ :END:
+#+cindex: links, in HTML export
+#+cindex: internal links, in HTML export
+#+cindex: external links, in HTML export
+
+Internal links (see [[Internal links]]) will continue to work in HTML.
+This includes automatic links created by radio targets (see [[Radio
+targets]]). Links to external files will still work if the target file
+is on the same /relative/ path as the published Org file. Links to
+other {{{file(.org)}}} files will be translated into HTML links under
+the assumption that a HTML version also exists of the linked file, at
+the same relative path. ~id:~ links can then be used to jump
+to specific entries across files. For information related to linking
+files while publishing them to a publishing directory see [[Publishing
+links]].
+
+If you want to specify attributes for links, you can do so using a
+special ~#+ATTR_HTML~ line to define attributes that will be added to
+the ~<a>~ or ~<img>~ tags. Here is an example that sets ~title~ and
+~style~ attributes for a link:
+
+#+cindex: #+ATTR_HTML
+#+begin_example
+ ,#+ATTR_HTML: title="The Org mode homepage" style="color:red;"
+ ,[[http://orgmode.org]]
+#+end_example
+
+*** Tables in HTML export
+ :PROPERTIES:
+ :DESCRIPTION: How to modify the formatting of tables
+ :END:
+#+cindex: tables, in HTML
+#+vindex: org-export-html-table-tag
+
+Org mode tables are exported to HTML using the table tag defined in
+~org-export-html-table-tag~. The default setting makes tables without
+cell borders and frame. If you would like to change this for
+individual tables, place something like the following before the
+table:
+
+#+cindex: #+CAPTION
+#+cindex: #+ATTR_HTML
+#+begin_example
+ ,#+CAPTION: This is a table with lines around and between cells
+ ,#+ATTR_HTML: border="2" rules="all" frame="border"
+#+end_example
+
+*** Images in HTML export
+ :PROPERTIES:
+ :DESCRIPTION: How to insert figures into HTML output
+ :END:
+#+cindex: images, inline in HTML
+#+cindex: inlining images in HTML
+#+vindex: org-export-html-inline-images
+
+HTML export can inline images given as links in the Org file, and it
+can make an image the clickable part of a link. By default, images are
+inlined if a link does not have a description.[fn:120] So
+~[[file:myimg.jpg]]~ will be inlined, while ~[[file:myimg.jpg][the
+image]]~ will just produce a link {{{samp(the image)}}} that points to
+the image. If the description part itself is a ~file:~ link or
+a ~http:~ URL pointing to an image, this image will be inlined and
+activated so that clicking on the image will activate the link. For
+example, to include a thumbnail that will link to a high resolution
+version of the image, you could use:
+
+#+begin_example
+ [[file:highres.jpg][file:thumb.jpg]]
+#+end_example
+
+If you need to add attributes to an inlined image, use a ~#+ATTR_HTML~.
+In the example below we specify the ~alt~ and ~title~ attributes to
+support text viewers and accessibility, and align it to the right.
+
+#+cindex: #+CAPTION
+#+cindex: #+ATTR_HTML
+#+begin_example
+ ,#+CAPTION: A black cat stalking a spider
+ ,#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
+ [[./img/a.jpg]]
+#+end_example
+
+{{{noindent}}} You could use ~http~ addresses just as well.
+
+*** Math formatting in HTML export
+ :PROPERTIES:
+ :DESCRIPTION: Beautiful math also on the web
+ :END:
+#+cindex: MathJax
+#+cindex: dvipng
+
+LaTeX math snippets (see [[LaTeX fragments]]) can be displayed in two
+different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax system]]
+which should work out of the box with Org mode installation because
+~http://orgmode.org~ serves {{{file(MathJax)}}} for Org mode users for
+small applications and for testing purposes.[fn:121] To configure
+{{{file(MathJax)}}}, use the variable
+~org-export-html-mathjax-options~ or insert something like the
+following into the buffer:
+
+#+begin_example
+ ,#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
+#+end_example
+
+{{{noindent}}} See the docstring of the variable
+~org-export-html-mathjax-options~ for the meaning of the parameters in
+this line.
+
+If you prefer, you can also request that LaTeX fragments are
+processed into small images that will be inserted into the browser
+page. Before the availability of MathJax, this was the default method
+for Org files. This method requires that the {{{file(dvipng)}}}
+program is available on your system. You can still get this processing
+with the following option:
+
+#+begin_example
+ ,#+OPTIONS: LaTeX:dvipng
+#+end_example
+
+*** Text areas in HTML export
+ :PROPERTIES:
+ :DESCRIPTION: An alternate way to show an example
+ :END:
+#+cindex: text areas, in HTML
+
+An alternative way to publish literal code examples in HTML is to use
+text areas, where the example can even be edited before pasting it
+into an application. It is triggered by a ~-t~ switch at an ~example~
+or ~src~ block. Using this switch disables any options for syntax and
+label highlighting, and line numbering, which may be present. You may
+also use ~-h~ and ~-w~ switches to specify the height and width of the
+text area, which default to the number of lines in the example, and
+80, respectively. For example
+
+#+begin_example
+ ,#+BEGIN_EXAMPLE -t -w 40
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+ ,#+END_EXAMPLE
+#+end_example
+
+*** CSS support
+ :PROPERTIES:
+ :DESCRIPTION: Changing the appearance of the output
+ :END:
+#+cindex: CSS, for HTML export
+#+cindex: HTML export, CSS
+#+vindex: org-export-html-todo-kwd-class-prefix
+#+vindex: org-export-html-tag-class-prefix
+
+You can also give style information for the exported file. The HTML
+exporter assigns the following special CSS classes to appropriate
+parts of the document---your style specifications may change these, in
+addition to any of the standard classes like for headlines, tables,
+etc.[fn:122]
+
+#+attr_texinfo: :table-type table :indic @code
+- p.author :: author information, including email
+- p.date :: publishing date
+- p.creator :: creator info, about org mode version
+- .title :: document title
+- .todo :: TODO keywords, all not-done states
+- .done :: the DONE keywords, all states that count as done
+- .WAITING :: each TODO keyword also uses a class named after itself
+- .timestamp :: timestamp
+- .timestamp-kwd :: keyword associated with a timestamp, like SCHEDULED
+- .timestamp-wrapper :: span around keyword plus timestamp
+- .tag :: tag in a headline
+- ._HOME :: each tag uses itself as a class, "@" replaced by "_"
+- .target :: target for links
+- .linenr :: the line number in a code example
+- .code-highlighted :: for highlighting referenced code lines
+- div.outline-N :: div for outline level N (headline plus text))
+- div.outline-text-N :: extra div for text at outline level N
+- .section-number-N :: section number in headlines, different for each level
+- div.figure :: how to format an inlined image
+- pre.src :: formatted source code
+- pre.example :: normal example
+- p.verse :: verse paragraph
+- div.footnotes :: footnote section headline
+- p.footnote :: footnote definition paragraph, containing a footnote
+- .footref :: a footnote reference number (always a <sup>)
+- .footnum :: footnote number in footnote definition (always <sup>)
+
+
+#+vindex: org-export-html-style-default
+#+vindex: org-export-html-style-include-default
+#+vindex: org-export-html-style
+#+vindex: org-export-html-extra
+#+vindex: org-export-html-style-default
+
+Each exported file contains a compact default style that defines these
+classes in a basic way.[fn:123] You may overwrite these
+settings, or add to them by using the variables ~org-export-html-style~
+(for Org-wide settings) and ~org-export-html-style-extra~ (for more
+fine-grained settings, like file-local settings). To set the latter variable
+individually for each file, you can use a ~#+STYLE:~ line:
+
+#+cindex: #+STYLE
+#+begin_example
+ ,#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+#+end_example
+
+{{{noindent}}} For longer style definitions, you can use several such
+lines. You could also directly write a ~<style>~ ~</style>~ section in
+this way, without referring to an external file.
+
+In order to add styles to a subtree, use the ~:HTML_CONTAINER_CLASS:~
+property to assign a class to the tree. In order to specify CSS styles
+for a particular headline, you can use the id specified in a
+~:CUSTOM_ID:~ property.
+
+# FIXME: More about header and footer styles
+# FIXME: Talk about links and targets.
+
+*** JavaScript support
+ :PROPERTIES:
+ :DESCRIPTION: Info and folding in a web browser
+ :END:
+#+cindex: Rose, Sebastian
+
+Sebastian Rose has written a JavaScript program especially designed to
+enhance the web viewing experience of HTML files created with Org. This
+program allows you to view large files in two different ways. The first one
+is an /Info/-like mode where each section is displayed separately and
+navigation can be done with the {{{kbd(n)}}} and {{{kbd(p)}}} keys (and some other keys
+as well, press {{{kbd(?)}}} for an overview of the available keys). The second
+view type is a /folding/ view much like Org provides inside Emacs. The
+script is available at [[http://orgmode.org/org-info.js]] and you can find
+the documentation for it at [[http://orgmode.org/worg/code/org-info-js/]].
+We host the script at our site, but if you use it a lot, you might
+not want to be dependent on ~orgmode.org~ and prefer to install a local
+copy on your own web server.
+
+To use the script, you need to make sure that the
+{{{file(org-jsinfo.el)}}} module gets loaded. It should be loaded by
+default, but you can try {{{ksksksk(M-x customize-variable,RET,org-modules,RET)}}}
+to convince yourself that this is indeed the case. All it then takes to make use of the program
+is adding a single line to the Org file:
+
+#+cindex: #+INFOJS_OPT
+#+begin_example
+ ,#+INFOJS_OPT: view:info toc:nil
+#+end_example
+
+{{{noindent}}} If this line is found, the HTML header will
+automatically contain the code needed to invoke the script. Using the
+line above, you can set the following viewing options:
+
+#+attr_texinfo: :table-type table :indic @code
+- path: ::
+
+ The path to the script. The default is to grab the script from
+ [[http://orgmode.org/org-info.js]], but you might want to have
+ a local copy and use a path like {{{samp(../scripts/org-info.js)}}}.
+
+- view: ::
+
+ Initial view when the website is first shown. Possible values are:
+
+ - info :: Info-like interface with one section per page.
+ - overview :: Folding interface, initially showing only top-level.
+ - content :: Folding interface, starting with all headlines visible.
+ - showall :: Folding interface, all headlines and text visible.
+
+- sdepth: ::
+
+ Maximum headline level that will still become an independent section
+ for info and folding modes. The default is taken from
+ ~org-export-headline-levels~ (= the ~H~ switch in ~#+OPTIONS~). If
+ this is smaller than in ~org-export-headline-levels~, each
+ info/folding section can still contain child headlines.
+
+- toc: ::
+
+ Should the table of contents /initially/ be visible? Even when ~nil~,
+ you can always get to the "toc" with {{{kbd(i)}}}.
+
+- tdepth: ::
+
+ The depth of the table of contents. The defaults are taken from the
+ variables ~org-export-headline-levels~ and ~org-export-with-toc~.
+
+- ftoc: ::
+
+ Does the CSS of the page specify a fixed position for the "toc"? If
+ yes, the toc will never be displayed as a section.
+
+- ltoc: ::
+
+ Should there be short contents (children) in each section? Make this
+ ~above~ if the section should be above initial text.
+
+- mouse: ::
+
+ Headings are highlighted when the mouse is over them. Should be
+ {{{samp(underline)}}} (default) or a background color like
+ {{{samp(#cccccc)}}}.
+
+- buttons: ::
+
+ Should view-toggle buttons be everywhere? When ~nil~ (the default),
+ only one such button will be present.
+
+
+#+vindex: org-infojs-options
+#+vindex: org-export-html-use-infojs
+
+{{{noindent}}} You can choose default values for these options by
+customizing the variable ~org-infojs-options~. If you always want to
+apply the script to your pages, configure the variable
+~org-export-html-use-infojs~.
+
+** LaTeX and PDF export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to LaTeX and processing to PDF
+ :END:
+#+cindex: @LaTeX{} export
+#+cindex: PDF export
+#+cindex: Guerry, Bastien
+
+Org mode contains a LaTeX exporter written by Bastien Guerry. With
+further processing, this backend is also used to produce PDF
+output.[fn:124] Since the LaTeX output uses {{{file(hyperref)}}} to
+implement links and cross references, the PDF output file will be
+fully linked. Beware of the fact that your ~org~ file has to be
+properly structured in order to be correctly exported: respect the
+hierarchy of sections.
+
+*** LaTeX/PDF export commands
+ :PROPERTIES:
+ :DESCRIPTION: Invoking export to LaTeX/PDF
+ :END:
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient-mark-mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e l)}}}, ~org-export-as-latex~ ::
+ #+kindex: C-c C-e l
+ #+cindex: property EXPORT_FILE_NAME
+
+ Export as a LaTeX file. For an Org file {{{file(myfile.org)}}}, the
+ LaTeX file will be {{{file(myfile.tex)}}}. The file will be
+ overwritten without warning. If there is an active region, only the
+ active region will be exported.[fn:125] If the selected region is a
+ single tree, the tree head will become the document title.[fn:126] If
+ the tree head entry has or inherits an ~EXPORT_FILE_NAME~ property,
+ that name will be used for the export.
+
+- {{{kbd(C-c C-e L)}}}, ~org-export-as-latex-to-buffer~ ::
+ #+kindex: C-c C-e L
+
+ Export to a temporary buffer. Do not create a file.
+
+- {{{kbd(C-c C-e v l/L)}}} ::
+
+ Export only the visible part of the document.
+
+- {{{kbd(M-x org-export-region-as-latex)}}} ::
+
+ Convert the region to LaTeX under the assumption that it was in Org
+ mode syntax before. This is a global command that can be invoked in
+ any buffer.
+
+- {{{kbd(M-x org-replace-region-by-latex)}}} ::
+
+ Replace the active region (assumed to be in Org mode syntax) by
+ LaTeX code.
+
+- {{{kbd(C-c C-e p)}}}, ~org-export-as-pdf~ ::
+ #+kindex: C-c C-e p
+
+ Export as LaTeX and then process to PDF.
+
+- {{{kbd(C-c C-e d)}}}, ~org-export-as-pdf-and-open~ ::
+ #+kindex: C-c C-e d
+
+ Export as LaTeX and then process to PDF, then open the resulting
+ PDF file.
+
+
+#+cindex: headline levels, for exporting
+#+vindex: org-latex-low-levels
+
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as description lists. The exporter can ignore them or
+convert them to a custom string depending on ~org-latex-low-levels~.
+
+If you want that transition to occur at a different level, specify it
+with a numeric prefix argument, e.g.:
+
+#+begin_example
+ C-2 C-c C-e l
+#+end_example
+
+{{{noindent}}} The example setting creates two levels of headings and
+exports the rest as list items.
+
+*** Header and sectioning
+ :PROPERTIES:
+ :DESCRIPTION: Setting up the export file structure
+ :TITLE: Header and sectioning structure
+ :END:
+#+cindex: @LaTeX{} class
+#+cindex: @LaTeX{} sectioning structure
+#+cindex: @LaTeX{} header
+#+cindex: header, for @LaTeX{} files
+#+cindex: sectioning structure, for @LaTeX{} export
+
+By default, the LaTeX output uses the class ~article~.
+
+#+vindex: org-export-latex-default-class
+#+vindex: org-export-latex-classes
+#+vindex: org-export-latex-default-packages-alist
+#+vindex: org-export-latex-packages-alist
+#+cindex: #+LaTeX_HEADER
+#+cindex: #+LaTeX_CLASS
+#+cindex: #+LaTeX_CLASS_OPTIONS
+#+cindex: property, LaTeX_CLASS
+#+cindex: property, LaTeX_CLASS_OPTIONS
+
+You can change this globally by setting a different value for
+~org-export-latex-default-class~ or locally by adding an option like
+~#+LaTeX_CLASS: myclass~ in your file, or with a ~:LaTeX_CLASS:~
+property that applies when exporting a region containing only this
+(sub)tree. The class must be listed in ~org-export-latex-classes~.
+This variable defines a header template for each class, and allows you
+to define the sectioning structure for each class.[fn:127] You can
+also define your own classes there. ~#+LaTeX_CLASS_OPTIONS~ or a
+~:LaTeX_CLASS_OPTIONS:~ property can specify the options for the
+~\documentclass~ macro. The options to documentclass have to be
+provided, as expected by LaTeX, within square brackets. You can
+also use ~#+LaTeX_HEADER: \usepackage{xyz}~ to add lines to the
+header. See the docstring of ~org-export-latex-classes~ for more
+information. An example is shown below.
+
+#+begin_example
+ ,#+LaTeX_CLASS: article
+ ,#+LaTeX_CLASS_OPTIONS: [a4paper]
+ ,#+LaTeX_HEADER: \usepackage{xyz}
+
+ ,* Headline 1
+ some text
+#+end_example
+
+*** Quoting LaTeX code
+ :PROPERTIES:
+ :DESCRIPTION: Incorporating literal LaTeX code
+ :END:
+
+Embedded LaTeX as described in [[Embedded LaTeX]], will be correctly
+inserted into the LaTeX file. This includes simple macros like
+~\ref{LABEL}~ to create a cross reference to a figure. Furthermore,
+you can add special code that should only be present in LaTeX export
+with the following constructs:
+
+#+cindex: #+LaTeX
+#+cindex: #+BEGIN_LaTeX
+#+begin_example
+ ,#+LaTeX: Literal LaTeX code for export
+#+end_example
+
+{{{noindent}}} or
+
+#+cindex: #+BEGIN_LaTeX
+
+#+begin_example
+ ,#+BEGIN_LaTeX
+ All lines between these markers are exported literally
+ ,#+END_LaTeX
+#+end_example
+
+*** Tables in LaTeX export
+ :PROPERTIES:
+ :DESCRIPTION: Options for exporting tables to LaTeX
+ :END:
+#+cindex: tables, in @LaTeX{} export
+
+For LaTeX export of a table, you can specify a label, a caption and
+placement options (see [[Images and tables]]). You can also use the
+~ATTR_LaTeX~ line to request a ~longtable~ environment for the
+table, so that it may span several pages, or to change the default table
+environment from ~table~ to ~table*~ or to change the default inner
+tabular environment to ~tabularx~ or ~tabulary~. Finally, you can
+set the alignment string, and (with ~tabularx~ or ~tabulary~) the
+width:
+
+#+cindex: #+CAPTION
+#+cindex: #+LABEL
+#+cindex: #+ATTR_LaTeX
+#+begin_example
+ ,#+CAPTION: A long table
+ ,#+LABEL: tbl:long
+ ,#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
+ | ..... | ..... |
+ | ..... | ..... |
+#+end_example
+
+or to specify a multicolumn table with ~tabulary~:
+
+#+cindex: #+CAPTION
+#+cindex: #+LABEL
+#+cindex: #+ATTR_LaTeX
+#+begin_example
+ ,#+CAPTION: A wide table with tabulary
+ ,#+LABEL: tbl:wide
+ ,#+ATTR_LaTeX: table* tabulary width=\textwidth
+ | ..... | ..... |
+ | ..... | ..... |
+#+end_example
+
+*** Images in LaTeX export
+ :PROPERTIES:
+ :DESCRIPTION: How to insert figures into LaTeX output
+ :END:
+#+cindex: images, inline in LaTeX
+#+cindex: inlining images in LaTeX
+
+Images that are linked to without a description part in the link, like
+~[[file:img.jpg]]~ or ~[[./img.jpg]]~ will be inserted into the PDF
+output file resulting from LaTeX processing. Org will use an
+~\includegraphics~ macro to insert the image. If you have specified
+a caption and/or a label as described in [[Images and tables]], the
+figure will be wrapped into a ~figure~ environment and thus become
+a floating element. You can use an ~#+ATTR_LaTeX:~ line to specify
+various other options. You can ask org to export an image as a float
+without specifying a label or a caption by using the keyword ~float~
+in this line. Various optional arguments to the ~\includegraphics~
+macro can also be specified in this fashion. To modify the placement
+option of the floating environment, add something like
+{{{samp(placement=[h!])}}} to the attributes. It is to be noted this
+option can be used with tables as well.[fn:128]
+
+If you would like to let text flow around the image, add the word
+{{{samp(wrap)}}} to the ~#+ATTR_LaTeX:~ line, which will make the
+figure occupy the left half of the page. To fine-tune, the ~placement~
+field will be the set of additional arguments needed by the
+~wrapfigure~ environment. Note that if you change the size of the
+image, you need to use compatible settings for ~\includegraphics~ and
+~wrapfigure~.
+
+#+cindex: #+CAPTION
+#+cindex: #+LABEL
+#+cindex: #+ATTR_LaTeX
+#+begin_example
+ ,#+CAPTION: The black-body emission of the disk around HR 4049
+ ,#+LABEL: fig:SED-HR4049
+ ,#+ATTR_LaTeX: width=5cm,angle=90
+ [[./img/sed-hr4049.pdf]]
+
+ ,#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
+ [[./img/hst.png]]
+#+end_example
+
+If you wish to include an image which spans multiple columns in a page, you
+can use the keyword ~multicolumn~ in the ~#+ATTR_LaTeX~ line. This
+will export the image wrapped in a ~figure*~ environment.
+
+If you need references to a label created in this way, write
+~\ref{fig:SED-HR4049}~ just like in LaTeX.
+
+*** Beamer class export
+ :PROPERTIES:
+ :DESCRIPTION: Turning the file into a presentation
+ :END:
+
+The LaTeX class {{{file(beamer)}}} allows production of high
+quality presentations using LaTeX and pdf processing. Org mode has
+special support for turning an Org mode file or tree into a
+{{{file(beamer)}}} presentation.
+
+When the LaTeX class for the current buffer (as set with ~#+LaTeX_CLASS:
+beamer~) or subtree (set with a ~LaTeX_CLASS~ property) is
+~beamer~, a special export mode will turn the file or tree into a beamer
+presentation. Any tree with not-too-deep level nesting should in principle be
+exportable as a beamer presentation. By default, the top-level entries (or
+the first level below the selected subtree heading) will be turned into
+frames, and the outline structure below this level will become itemize lists.
+You can also configure the variable ~org-beamer-frame-level~ to a
+different level---then the hierarchy above frames will produce the sectioning
+structure of the presentation.
+
+A template for useful in-buffer settings or properties can be inserted
+into the buffer with
+{{{kbd(M-x org-insert-beamer-options-template)}}}. Among other things, this will
+install a column view format which is very handy for editing special
+properties used by beamer.
+
+You can influence the structure of the presentation using the following
+properties:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~BEAMER_env~ ::
+
+ The environment that should be used to format this entry. Valid
+ environments are defined in the constant
+ ~org-beamer-environments-default~, and you can define more in
+ ~org-beamer-environments-extra~. If this property is set, the entry
+ will also get a ~:B_environment:~ tag to make this visible. This tag
+ has no semantic meaning, it is only a visual aid.
+
+- ~BEAMER_envargs~ ::
+
+ The beamer-special arguments that should be used for the environment,
+ like ~[t]~ or ~[<+->]~ of ~<2-3>~. If the ~BEAMER_col~ property is
+ also set, something like ~C[t]~ can be added here as well to set an
+ options argument for the implied ~columns~ environment. ~c[t]~ or
+ ~c<2->~ will set an options for the implied ~column~ environment.
+
+- ~BEAMER_col~ ::
+
+ The width of a column that should start with this entry. If this
+ property is set, the entry will also get a ~:BMCOL:~ property to make
+ this visible. Also this tag is only a visual aid. When this is a plain
+ number, it will be interpreted as a fraction of ~\textwidth~.
+ Otherwise it will be assumed that you have specified the units, like
+ {{{samp(3cm)}}}. The first such property in a frame will start a
+ ~columns~ environment to surround the columns. This environment is
+ closed when an entry has a ~BEAMER_col~ property with value 0 or 1, or
+ automatically at the end of the frame.
+
+- ~BEAMER_extra~ ::
+
+ Additional commands that should be inserted after the environment has
+ been opened. For example, when creating a frame, this can be used to
+ specify transitions.
+
+
+Frames will automatically receive a ~fragile~ option if they contain
+source code that uses the verbatim environment. Special {{{file(beamer)}}}
+specific code can be inserted using ~#+BEAMER:~ and
+~#+BEGIN_BEAMER~ ... ~#+END_BEAMER~ constructs, similar to other export
+backends, but with the difference that ~#+LaTeX:~ stuff will be included
+in the presentation as well.
+
+Outline nodes with ~BEAMER_env~ property value {{{samp(note)}}} or
+{{{samp(noteNH)}}} will be formatted as beamer notes, i,e, they will be wrapped
+into ~\note{...}~. The former will include the heading as part of the
+note text, the latter will ignore the heading of that node. To simplify note
+generation, it is actually enough to mark the note with a /tag/ (either
+~:B_note:~ or ~:B_noteNH:~) instead of creating the
+~BEAMER_env~ property.
+
+You can turn on a special minor mode ~org-beamer-mode~ for editing
+support with the following line:
+
+#+begin_example
+ ,#+STARTUP: beamer
+#+end_example
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-b)}}}, ~org-beamer-select-environment~ ::
+ #+kindex: C-c C-b
+
+ In ~org-beamer-mode~, this key offers fast selection of a beamer
+ environment or the ~BEAMER_col~ property.
+
+
+Column view provides a great way to set the environment of a node and
+other important parameters. Make sure you are using a COLUMN format
+that is geared toward this special purpose. The command
+{{{kbd(M-x org-insert-beamer-options-template)}}} defines such a format.
+
+Here is a simple example Org document that is intended for beamer export.
+
+#+begin_example
+ ,#+LaTeX_CLASS: beamer
+ ,#+TITLE: Example Presentation
+ ,#+AUTHOR: Carsten Dominik
+ ,#+LaTeX_CLASS_OPTIONS: [presentation]
+ ,#+BEAMER_FRAME_LEVEL: 2
+ ,#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
+ ,#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
+
+ ,* This is the first structural section
+
+ ,** Frame 1 \\ with a subtitle
+ ,*** Thanks to Eric Fraga :BMCOL:B_block:
+ :PROPERTIES:
+ :BEAMER_env: block
+ :BEAMER_envargs: C[t]
+ :BEAMER_col: 0.5
+ :END:
+ for the first viable beamer setup in Org
+ ,*** Thanks to everyone else :BMCOL:B_block:
+ :PROPERTIES:
+ :BEAMER_col: 0.5
+ :BEAMER_env: block
+ :BEAMER_envargs: <2->
+ :END:
+ for contributing to the discussion
+ ,**** This will be formatted as a beamer note :B_note:
+ ,** Frame 2 \\ where we will not use columns
+ ,*** Request :B_block:
+ Please test this stuff!
+ :PROPERTIES:
+ :BEAMER_env: block
+ :END:
+#+end_example
+
+For more information, see the documentation on Worg.
+
+** DocBook export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to DocBook
+ :END:
+#+cindex: DocBook export
+#+cindex: PDF export
+#+cindex: Cui, Baoqiu
+
+Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
+exported to DocBook format, it can be further processed to produce other
+formats, including PDF, HTML, man pages, etc., using many available DocBook
+tools and stylesheets.
+
+Currently DocBook exporter only supports DocBook V5.0.
+
+*** DocBook export commands
+ :PROPERTIES:
+ :DESCRIPTION: How to invoke DocBook export
+ :END:
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient-mark-mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e D)}}}, ~org-export-as-docbook~ ::
+ #+kindex: C-c C-e D
+ #+cindex: property EXPORT_FILE_NAME
+
+ Export as a DocBook file. For an Org file, {{{file(myfile.org)}}}, the
+ DocBook XML file will be {{{file(myfile.xml)}}}. The file will be
+ overwritten without warning. If there is an active region, only the
+ region will be exported.[fn:129] If the selected region is a single
+ tree, the tree head will become the document title.[fn:130] If the
+ tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property, that
+ name will be used for the export.
+
+- {{{kbd(C-c C-e V)}}}, ~org-export-as-docbook-pdf-and-open~ ::
+ #+kindex: C-c C-e V
+
+ Export as a DocBook file, process to PDF, then open the resulting PDF
+ file.
+
+ #+vindex: org-export-docbook-xslt-proc-command
+ #+vindex: org-export-docbook-xsl-fo-proc-command
+
+ Note that, in order to produce PDF output based on an exported DocBook
+ file, you need to have XSLT processor and XSL-FO processor software
+ installed on your system. Check variables
+ ~org-export-docbook-xslt-proc-command~ and
+ ~org-export-docbook-xsl-fo-proc-command~.
+
+ #+vindex: org-export-docbook-xslt-stylesheet
+
+ The stylesheet argument ~%s~ in variable
+ ~org-export-docbook-xslt-proc-command~ is replaced by the value of
+ variable ~org-export-docbook-xslt-stylesheet~, which needs to be set by
+ the user. You can also overrule this global setting on a per-file basis by
+ adding an in-buffer setting ~#+XSLT:~ to the Org file.
+
+- {{{kbd(C-c C-e v D)}}} ::
+ #+kindex: C-c C-e v D
+
+ Export only the visible part of the document.
+
+*** Quoting DocBook code
+ :PROPERTIES:
+ :DESCRIPTION: Incorporating DocBook code in Org files
+ :END:
+You can quote DocBook code in Org files and copy it verbatim into exported
+DocBook file with the following constructs:
+
+#+cindex: #+DOCBOOK
+#+cindex: #+BEGIN_DOCBOOK
+#+begin_example
+ ,#+DOCBOOK: Literal DocBook code for export
+#+end_example
+
+{{{noindent}}} or
+#+cindex: #+BEGIN_DOCBOOK
+
+#+begin_example
+ ,#+BEGIN_DOCBOOK
+ All lines between these markers are exported by DocBook exporter
+ literally.
+ ,#+END_DOCBOOK
+#+end_example
+
+For example, you can use the following lines to include a DocBook warning
+admonition. As to what this warning says, you should pay attention to the
+document context when quoting DocBook code in Org files. You may make
+exported DocBook XML files invalid by not quoting DocBook code correctly.
+
+#+begin_example
+ ,#+BEGIN_DOCBOOK
+ <warning>
+ <para>You should know what you are doing when quoting DocBook XML code
+ in your Org file. Invalid DocBook XML may be generated by
+ DocBook exporter if you are not careful!</para>
+ </warning>
+ ,#+END_DOCBOOK
+#+end_example
+
+*** Recursive sections
+ :PROPERTIES:
+ :DESCRIPTION: Recursive sections in DocBook
+ :END:
+#+cindex: DocBook recursive sections
+
+DocBook exporter exports Org files as articles using the ~article~
+element in DocBook. Recursive sections, i.e., ~section~ elements, are
+used in exported articles. Top level headlines in Org files are
+exported as top level sections, and lower level headlines are exported
+as nested sections. The entire structure of Org files will be exported
+completely, no matter how many nested levels of headlines there are.
+
+Using recursive sections makes it easy to port and reuse exported
+DocBook code in other DocBook document types like ~book~ or ~set~.
+
+*** Tables in DocBook export
+ :PROPERTIES:
+ :DESCRIPTION: Tables are exported as HTML tables
+ :END:
+#+cindex: tables, in DocBook export
+
+Tables in Org files are exported as HTML tables, which have been
+supported since DocBook V4.3.
+
+If a table does not have a caption, an informal table is generated
+using the ~informaltable~ element; otherwise, a formal table will be
+generated using the ~table~ element.
+
+*** Images in DocBook export
+ :PROPERTIES:
+ :DESCRIPTION: How to insert figures into DocBook output
+ :END:
+#+cindex: images, inline in DocBook
+#+cindex: inlining images in DocBook
+
+Images that are linked to without a description part in the link, like
+~[[file:img.jpg]]~ or ~[[./img.jpg]]~, will be exported to
+DocBook using ~mediaobject~ elements. Each ~mediaobject~ element
+contains an ~imageobject~ that wraps an ~imagedata~ element. If you
+have specified a caption for an image as described in [[Images and
+tables]], a ~caption~ element will be added in ~mediaobject~. If a label
+is also specified, it will be exported as an ~xml:id~ attribute of the
+~mediaobject~ element.
+
+#+vindex: org-export-docbook-default-image-attributes
+
+Image attributes supported by the ~imagedata~ element, like ~align~ or
+~width~, can be specified in two ways: you can either customize
+variable ~org-export-docbook-default-image-attributes~ or use the
+~#+ATTR_DOCBOOK:~ line. Attributes specified in variable
+~org-export-docbook-default-image-attributes~ are applied to all
+inline images in the Org file to be exported (unless they are
+overridden by image attributes specified in ~#+ATTR_DOCBOOK:~ lines).
+
+The ~#+ATTR_DOCBOOK:~ line can be used to specify additional image
+attributes or override default image attributes for individual images.
+If the same attribute appears in both the ~#+ATTR_DOCBOOK:~ line and
+variable ~org-export-docbook-default-image-attributes~, the former
+takes precedence. Here is an example about how image attributes can be
+set:
+
+#+cindex: #+CAPTION
+#+cindex: #+LABEL
+#+cindex: #+ATTR_DOCBOOK
+#+begin_example
+ ,#+CAPTION: The logo of Org mode
+ ,#+LABEL: unicorn-svg
+ ,#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
+ [[./img/org-mode-unicorn.svg]]
+#+end_example
+
+#+vindex: org-export-docbook-inline-image-extensions
+
+By default, DocBook exporter recognizes the following image file
+types: {{{file(jpeg)}}}, {{{file(jpg)}}}, {{{file(png)}}},
+{{{file(gif)}}}, and {{{file(svg)}}}. You can customize variable
+~org-export-docbook-inline-image-extensions~ to add more types to this
+list as long as DocBook supports them.
+
+*** Special characters
+ :PROPERTIES:
+ :DESCRIPTION: How to handle special characters
+ :TITLE: Special characters in DocBook export
+ :END:
+#+vindex: org-export-docbook-doctype
+#+vindex: org-entities
+
+Special characters that are written in TeX-like syntax, such as
+~\alpha~, ~\Gamma~, and ~\Zeta~, are supported by DocBook exporter.
+These characters are rewritten to XML entities, like ~&alpha;~,
+~&Gamma;~, and ~&Zeta;~, based on the list saved in variable
+~org-entities~. As long as the generated DocBook file includes the
+corresponding entities, these special characters are recognized.
+
+You can customize variable ~org-export-docbook-doctype~ to include the
+entities you need. For example, you can set variable
+~org-export-docbook-doctype~ to the following value to recognize all
+special characters included in XHTML entities:
+
+#+begin_example
+ "<!DOCTYPE article [
+ <!ENTITY % xhtml1-symbol PUBLIC
+ \"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
+ \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
+ >
+ %xhtml1-symbol;
+ ]>
+ "
+#+end_example
+
+** OpenDocument Text export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to OpenDocument Text
+ :END:
+#+cindex: K, Jambunathan
+#+cindex: ODT
+#+cindex: OpenDocument
+#+cindex: export, OpenDocument
+#+cindex: LibreOffice
+#+cindex: org-odt.el
+#+cindex: org-modules
+
+Org Mode supports export to OpenDocument Text (ODT) format using the
+{{{file(org-odt.el)}}} module.[fn:131] Documents created by this
+exporter use the {{{cite(OpenDocument-v1.2 specification)}}} and
+are compatible with LibreOffice 3.4.[fn:132]
+
+*** Pre-requisites for ODT export
+ :PROPERTIES:
+ :DESCRIPTION: What packages ODT exporter relies on
+ :END:
+#+cindex: zip
+
+The ODT exporter relies on the {{{file(zip)}}} program to create the
+final output. Check the availability of this program before proceeding
+further.
+
+*** ODT export commands
+ :PROPERTIES:
+ :DESCRIPTION: How to invoke ODT export
+ :ALT_TITLE: Exporting to ODT
+ :END:
+<<x-export-to-odt>>
+
+#+cindex: region, active
+#+cindex: active region
+#+cindex: transient-mark-mode
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e o)}}}, ~org-export-as-odt~ ::
+ #+kindex: C-c C-e o
+ #+cindex: property EXPORT_FILE_NAME
+
+ Export as OpenDocument Text file.
+
+ #+vindex: org-export-odt-preferred-output-format
+
+ If ~org-export-odt-preferred-output-format~ is specified,
+ automatically convert the exported file to that format. See
+ [[Automatically exporting to other formats]].
+
+ For an Org file {{{file(myfile.org)}}}, the ODT file will be
+ {{{file(myfile.odt)}}}. The file will be overwritten without warning.
+ If there is an active region, only the region will be
+ exported.[fn:133] If the selected region is a single tree, the tree
+ head will become the document title.[fn:134] If the tree head entry
+ has, or inherits, an ~EXPORT_FILE_NAME~ property, that name will be
+ used for the export.
+
+- {{{kbd(C-c C-e O)}}}, ~org-export-as-odt-and-open~ ::
+ #+kindex: C-c C-e O
+
+ Export as an OpenDocument Text file and open the resulting file.
+
+ #+vindex: org-export-odt-preferred-output-format
+
+ If ~org-export-odt-preferred-output-format~ is specified, open the
+ converted file instead. See [[x-export-to-other-formats][Automatically exporting to other formats]].
+
+*** Extending ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How to produce ~doc~, ~pdf~ files
+ :END:
+
+The ODT exporter can interface with a variety of document converters
+and supports popular converters out of the box. As a result, you can
+use it to export to formats like {{{samp(doc)}}} or convert a document
+from one format (say {{{samp(csv)}}}) to another format (say
+{{{samp(ods)}}} or {{{samp(xls)}}}).
+
+#+cindex: @file{unoconv}
+#+cindex: LibreOffice
+
+If you have a working installation of LibreOffice, a document
+converter is pre-configured for you and you can use it right away. If
+you would like to use {{{file(unoconv)}}} as your preferred converter,
+customize the variable ~org-export-odt-convert-process~ to point to
+~unoconv~. You can also use your own favorite converter or tweak the
+default settings of the {{{file(LibreOffice)}}} and
+{{{samp(unoconv)}}} converters. See [[Configuring a document converter]].
+
+**** Automatically exporting to other formats
+ :PROPERTIES:
+ :DESCRIPTION: Automatic conversion to doc, docx, etc.
+ :END:
+<<x-export-to-other-formats>>
+
+#+vindex: org-export-odt-preferred-output-format
+
+Very often, you will find yourself exporting to ODT format, only to
+immediately save the exported document to other formats like
+{{{samp(doc)}}}, {{{samp(docx)}}}, {{{samp(rtf)}}}, {{{samp(pdf)}}}
+etc. In such cases, you can specify your preferred output format by
+customizing the variable ~org-export-odt-preferred-output-format~.
+This way, the export commands (see [[x-export-to-odt][Exporting to ODT]])
+can be extended to export to a format that is of immediate interest to
+you.
+
+**** Converting between document formats
+ :PROPERTIES:
+ :DESCRIPTION: Interacting with configured converters
+ :END:
+# <<x-convert-to-other-formats>>
+
+There are many document converters in the wild that support
+conversion to and from various file formats, including, but not
+limited to the ODT format. LibreOffice converter, mentioned above, is
+one such converter. Once a converter is configured, you can interact
+with it using the following command.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(M-x org-export-odt-convert)}}} ::
+ #+vindex: org-export-odt-convert
+
+ Convert an existing document from one format to another. With a prefix
+ argument, also open the newly produced file.
+
+*** Applying custom styles
+ :PROPERTIES:
+ :DESCRIPTION: How to apply custom styles to the output
+ :END:
+#+cindex: styles, custom
+#+cindex: template, custom
+
+The ODT exporter ships with a set of OpenDocument styles
+(see [[Working with OpenDocument style files]]) that ensure a well-formatted output.
+These factory styles, however, may not cater to your specific tastes.
+To customize the output, you can either modify the above styles files
+directly, or generate the required styles using an application like
+LibreOffice. The latter method is suitable for expert and non-expert
+users alike, and is described here.
+
+Custom styles can be applied in three easy steps:
+
+1. Create a sample {{{file(example.org)}}} file with the below
+ settings and export it to ODT format.
+
+ #+begin_example
+ ,#+OPTIONS: H:10 num:t
+ #+end_example
+
+2. Open the above {{{file(example.odt)}}} using LibreOffice. Use the
+ {{{file(Stylist)}}} to locate the target styles---these typically
+ have the {{{samp(Org)}}} prefix---and modify those to your taste.
+ Save the modified file either as an OpenDocument Text
+ ({{{file(.odt)}}}) or OpenDocument Template ({{{file(.ott)}}})
+ file.
+
+3. Customize the variable ~org-export-odt-styles-file~ and point it to
+ the newly created file. For additional configuration options see
+ [[x-overriding-factory-styles][Overriding factory styles]].
+
+ #+cindex: #+ODT_STYLES_FILE
+ #+vindex: org-export-odt-styles-file
+
+ If you would like to choose a style on a per-file basis, you can use
+ the ~#+ODT_STYLES_FILE~ option. A typical setting will look like
+ one of these two examples:
+
+ #+begin_example
+ ,#+ODT_STYLES_FILE: "/path/to/example.ott"
+ #+end_example
+
+ or
+
+ #+begin_example
+ ,#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
+ #+end_example
+
+Although you can use third-party styles and templates for customizing
+your output, this will produce the desired output only if the template
+provides all style names that the {{{samp(ODT)}}} exporter relies
+upon. Unless this condition is met, the output is going to be less
+than satisfactory. It is highly recommended that you only work with
+templates that are directly derived from the factory settings.
+
+*** Links in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How links will be interpreted and formatted
+ :END:
+#+cindex: tables, in DocBook export
+
+ODT exporter creates native cross-references for internal links. It
+creates Internet-style links for all other links.
+
+A link with no description and destined to a regular (un-itemized)
+outline heading is replaced with a cross-reference and section number
+of the heading.
+
+A ~\ref{label}~-style reference to an image, table etc. is replaced
+with a cross-reference and sequence number of the labeled entity. See
+[[Labels and captions in ODT export]].
+
+*** Tables in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How tables are exported
+ :END:
+
+#+cindex: tables, in DocBook export
+
+Export of native Org mode tables (see [[Tables]]) and simple
+{{{file(table.el)}}} tables is supported. However, export of complex
+{{{file(table.el)}}} tables---tables that have column or row
+spans---is not supported. Such tables are stripped from the exported
+document.
+
+By default, a table is exported with top and bottom frames and with
+rules separating row and column groups (see [[Column groups]]).
+Furthermore, all tables are typeset to occupy the same width. If the
+table specifies alignment and relative width for its columns (see
+[[Column width and alignment]]) then these are honored on export.[fn:135]
+
+#+cindex: #+ATTR_ODT
+
+You can control the width of the table by specifying ~:rel-width~
+property using an ~#+ATTR_ODT~ line.
+
+For example, consider the following table which makes use of all the
+rules mentioned above.
+
+#+begin_example
+ #+ATTR_ODT: :rel-width 50
+ | Area/Month | Jan | Feb | Mar | Sum |
+ |---------------+-------+-------+-------+-------|
+ | / | < | | | < |
+ | <l13> | <r5> | <r5> | <r5> | <r6> |
+ | North America | 1 | 21 | 926 | 948 |
+ | Middle East | 6 | 75 | 844 | 925 |
+ | Asia Pacific | 9 | 27 | 790 | 826 |
+ |---------------+-------+-------+-------+-------|
+ | Sum | 16 | 123 | 2560 | 2699 |
+#+end_example
+
+On export, the table will occupy 50% of text area. The columns will be
+sized (roughly) in the ratio of 13:5:5:5:6. The first column will be
+left-aligned and rest of the columns will be right-aligned. There will
+be vertical rules after separating the header and last columns from
+other columns. There will be horizontal rules separating the header
+and last rows from other rows.
+
+If you are not satisfied with the above formatting options, you can
+create custom table styles and associate them with a table using the
+~#+ATTR_ODT~ line. See [[Customizing tables in ODT export]].
+
+*** Images in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How to insert images
+ :END:
+#+cindex: images, embedding in ODT
+#+cindex: embedding images in ODT
+
+You can embed images within the exported document by providing a link to the
+desired image file with no link description. For example, to embed
+{{{samp(img.png)}}} do either of the following:
+
+#+begin_example
+ [[file:img.png]]
+#+end_example
+
+#+begin_example
+ [[./img.png]]
+#+end_example
+
+You can create clickable images by providing a link whose description
+is a link to an image file. For example, to embed an image
+{{{file(org-mode-unicorn.png)}}}, which when clicked jumps to
+[[http://Orgmode.org]] website, do the following:
+
+#+begin_example
+ [[http://orgmode.org][./org-mode-unicorn.png]]
+#+end_example
+
+#+cindex: #+ATTR_ODT
+
+You can control the size and scale of the embedded images using the
+~#+ATTR_ODT~ attribute.
+
+#+cindex: identify, ImageMagick
+#+vindex: org-export-odt-pixels-per-inch
+
+The exporter specifies the desired size of the image in the final
+document in units of centimeters. In order to scale the embedded
+images, the exporter queries for pixel dimensions of the images using
+either ImageMagick's {{{file(identify)}}} program, or Emacs'
+`create-image' and `image-size' APIs.[fn:136] The pixel dimensions are
+subsequently converted to centimeters using
+~org-export-odt-pixels-per-inch~. The default value of this variable
+is set to ~display-pixels-per-inch~. You can tweak this variable to
+achieve the best results.
+
+The examples below illustrate the various possibilities.
+
+#+attr_texinfo: :table-type table :indic @asis
+- Explicitly size the image ::
+
+ To embed {{{file(img.png)}}} as a 10 cm x 10 cm image, do the
+ following:
+
+ #+begin_example
+ #+ATTR_ODT: :width 10 :height 10
+ [[./img.png]]
+ #+end_example
+
+- Scale the image ::
+
+ To embed {{{file(img.png)}}} at half its size, do the following:
+
+ #+begin_example
+ #+ATTR_ODT: :scale 0.5
+ [[./img.png]]
+ #+end_example
+
+- Scale the image to a specific width ::
+
+ To embed {{{file(img.png)}}} with a width of 10 cm while retaining the
+ original height:width ratio, do the following:
+
+ #+begin_example
+ #+ATTR_ODT: :width 10
+ [[./img.png]]
+ #+end_example
+
+- Scale the image to a specific height ::
+
+ To embed {{{file(img.png)}}} with a height of 10 cm while retaining
+ the original height:width ratio, do the following:
+
+ #+begin_example
+ #+ATTR_ODT: :height 10
+ [[./img.png]]
+ #+end_example
+
+#+cindex: #+ATTR_ODT
+
+You can control the manner in which an image is anchored by setting
+the ~:anchor~ property of it's ~#+ATTR_ODT~ line. You can specify one
+of the the following three values for the ~:anchor~ property -
+{{{samp("as-char")}}}, {{{samp("paragraph")}}} and {{{samp("page")}}}.
+
+To create an image that is anchored to a page, do the following:
+
+#+begin_example
+ #+ATTR_ODT: :anchor "page"
+ [[./img.png]]
+#+end_example
+
+*** Math formatting in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How LaTeX fragments are formatted
+ :END:
+
+The ODT exporter has special support for handling math.
+
+**** Working with LaTeX math snippets
+ :PROPERTIES:
+ :DESCRIPTION: How to embed LaTeX math fragments
+ :END:
+
+LaTeX math snippets (see [[LaTeX fragments]]) can be embedded in the ODT
+document in one of the following ways:
+
+#+cindex: MathML
+#+attr_texinfo: :table-type table :indic @asis
+- MathML ::
+
+ This option is activated on a per-file basis with the following option:
+
+ #+begin_example
+ ,#+OPTIONS: LaTeX:t
+ #+end_example
+
+ With this option, LaTeX fragments are first converted into MathML
+ fragments using an external LaTeX-to-MathML converter program. The
+ resulting MathML fragments are then embedded as an OpenDocument Formula in
+ the exported document.
+
+ #+vindex: org-latex-to-mathml-convert-command
+ #+vindex: org-latex-to-mathml-jar-file
+
+ You can specify the LaTeX-to-MathML converter by customizing the variables
+ ~org-latex-to-mathml-convert-command~ and
+ ~org-latex-to-mathml-jar-file~.
+
+ If you prefer to use {{{file(MathToWeb)}}} as your converter, you can
+ configure the above variables as shown below.[fn:137]
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (setq org-latex-to-mathml-convert-command
+ "java -jar %j -unicode -force -df %o %I"
+ org-latex-to-mathml-jar-file
+ "/path/to/mathtoweb.jar")
+ #+end_src
+
+ You can use the following commands to quickly verify the reliability of
+ the LaTeX-to-MathML converter.
+
+ - {{{kbd(M-x org-export-as-odf)}}} ::
+
+ Convert a LaTeX math snippet to an OpenDocument formula
+ ({{{file(.odf)}}}) file.
+
+ - {{{kbd(M-x org-export-as-odf-and-open)}}} ::
+
+ Convert a LaTeX math snippet to an OpenDocument formula
+ ({{{file(.odf)}}}) file and open the formula file with the
+ system-registered application.
+
+- PNG images ::
+ #+cindex: dvipng
+
+ This option is activated on a per-file basis with
+
+ #+begin_example
+ ,#+OPTIONS: LaTeX:dvipng
+ #+end_example
+
+ With this option, LaTeX fragments are processed into PNG images and
+ the resulting images are embedded in the exported document. This
+ method requires that the {{{file(dvipng)}}} program be available on
+ your system.
+
+**** Working with MathML or OpenDocument formula files
+ :PROPERTIES:
+ :DESCRIPTION: How to embed equations in native format
+ :END:
+
+For various reasons, you may find embedding LaTeX math snippets in
+an ODT document less than reliable. In that case, you can embed a math
+equation by linking to its MathML ({{{file(.mml)}}}) source or its
+OpenDocument formula ({{{file(.odf)}}}) file as shown below:
+
+#+begin_example
+ [[./equation.mml]]
+#+end_example
+
+or
+
+#+begin_example
+ [[./equation.odf]]
+#+end_example
+
+*** Labels and captions in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How captions are rendered
+ :END:
+
+You can label and caption various category of objects---an inline
+image, a table, a LaTeX fragment or a Math formula---using
+~#+LABEL~ and ~#+CAPTION~ lines. See [[Images and tables]]. ODT exporter
+enumerates each labeled or captioned object of a given category
+separately. As a result, each such object is assigned a sequence
+number based on order of its appearance in the Org file.
+
+In the exported document, a user-provided caption is augmented with
+the category and sequence number. Consider the following inline image
+in an Org file:
+
+#+begin_example
+ ,#+CAPTION: Bell curve
+ ,#+LABEL: fig:SED-HR4049
+ [[./img/a.png]]
+#+end_example
+
+It could be rendered as shown below in the exported document.
+
+#+begin_example
+ Figure 2: Bell curve
+#+end_example
+
+#+vindex: org-export-odt-category-strings
+
+You can modify the category component of the caption by customizing
+the variable ~org-export-odt-category-strings~. For example, to tag
+all embedded images with the string {{{samp(Illustration)}}} (instead
+of the default {{{samp(Figure)}}}) use the following setting.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-export-odt-category-strings
+ '(("en" "Table" "Illustration" "Equation" "Equation")))
+#+end_src
+
+With this, previous image will be captioned as below in the exported
+document.
+
+#+begin_example
+ Illustration 2: Bell curve
+#+end_example
+
+*** Literal examples in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How source and example blocks are formatted
+ :END:
+
+Export of literal examples (see [[Literal examples]]) with full
+fontification is supported. Internally, the exporter relies on
+{{{file(htmlfontify.el)}}} to generate all style definitions needed
+for a fancy listing.[fn:138] The auto-generated styles have
+{{{samp(OrgSrc)}}} as prefix and inherit their color from the faces
+used by Emacs ~font-lock~ library for the source language.
+
+#+vindex: org-export-odt-fontify-srcblocks
+
+If you prefer to use your own custom styles for fontification, you can
+do so by customizing the variable
+~org-export-odt-create-custom-styles-for-srcblocks~.
+
+#+vindex: org-export-odt-create-custom-styles-for-srcblocks
+
+You can turn off fontification of literal examples by customizing the
+variable ~org-export-odt-fontify-srcblocks~.
+
+*** Advanced topics in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: Read this if you are a power user
+ :END:
+
+If you rely heavily on ODT export, you may want to exploit the full
+set of features that the exporter offers. This section describes
+features that would be of interest to power users.
+
+**** Configuring a document converter
+ :PROPERTIES:
+ :DESCRIPTION: How to register a document converter
+ :END:
+#+cindex: convert
+#+cindex: doc, docx, rtf
+#+cindex: converter
+
+The ODT exporter can work with popular converters with little or no
+extra configuration from your side. See [[Extending ODT export]]. If you
+are using a converter that is not supported by default or if you would
+like to tweak the default converter settings, proceed as below.
+
+#+attr_texinfo: :table-type table :indic @asis
+- Register the converter ::
+
+ #+vindex: org-export-odt-convert-processes
+
+ Name your converter and add it to the list of known converters by
+ customizing the variable ~org-export-odt-convert-processes~. Also
+ specify how the converter can be invoked via command-line to effect
+ the conversion.
+
+- Configure its capabilities ::
+
+ #+vindex: org-export-odt-convert-capabilities
+ # <<x-odt-converter-capabilities>>
+
+ Specify the set of formats the converter can handle by customizing the
+ variable ~org-export-odt-convert-capabilities~. Use the default value
+ for this variable as a guide for configuring your converter. As suggested by
+ the default setting, you can specify the full set of formats supported by the
+ converter and not limit yourself to specifying formats that are related to
+ just the OpenDocument Text format.
+
+- Choose the converter ::
+
+ #+vindex: org-export-odt-convert-process
+
+ Select the newly added converter as the preferred one by customizing the
+ variable ~org-export-odt-convert-process~.
+
+**** Working with OpenDocument style files
+ :PROPERTIES:
+ :DESCRIPTION: Explore the internals
+ :END:
+#+cindex: styles, custom
+#+cindex: template, custom
+
+This section explores the internals of the ODT exporter and the means
+by which it produces styled documents. Read this section if you are
+interested in exploring the automatic and custom OpenDocument styles
+used by the exporter.
+
+# <<x-factory-styles>>
+
+The ODT exporter relies on two files for generating its output.
+These files are bundled with the distribution under the directory pointed to
+by the variable ~org-odt-styles-dir~. The two files are:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{file(OrgOdtStyles.xml)}}} ::
+ <<x-orgodtstyles-xml>>
+
+ This file contributes to the {{{file(styles.xml)}}} file of the final
+ {{{samp(ODT)}}} document. This file is modified to control outline
+ numbering based on user settings, and To add styles generated by
+ {{{file(htmlfontify.el)}}} for fontification of code blocks.
+
+- {{{file(OrgOdtContentTemplate.xml)}}} ::
+ <<x-orgodtcontenttemplate-xml>>
+
+ This file contributes to the {{{file(content.xml)}}} file of the final
+ {{{samp(ODT)}}} document. The contents of the Org outline are inserted
+ between the ~<office:text>~ and ~</office:text>~
+ elements of this file.
+
+ In addition to serving as a template file for the final
+ {{{file(content.xml)}}}, the file also contains automatic styles for
+ formatting of tables which are referenced by the exporter, and
+ ~<text:sequence-decl>~ ... ~</text:sequence-decl>~
+ elements that control how various entities---tables, images,
+ equations, etc.---are numbered.
+
+
+<<x-overriding-factory-styles>>
+
+The following two variables control the location from which the ODT
+exporter picks up the custom styles and content template files. You
+can customize these variables to override the factory styles used by
+the exporter.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~org-export-odt-styles-file~ ::
+ <<x-org-export-odt-styles-file>>
+
+ Use this variable to specify the {{{file(styles.xml)}}} that will be
+ used in the final output. You can specify one of the following values:
+
+ - A {{{file(styles.xml)}}} file ::
+
+ Use this file instead of the default {{{file(styles.xml)}}}
+
+ - A {{{file(.odt)}}} or {{{file(.ott)}}} file ::
+
+ Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
+ Text or Template file.
+
+ - A {{{file(.odt)}}} or {{{file(.ott)}}} file and a subset of files contained within them ::
+
+ Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
+ Text or Template file. Additionally extract the specified member files
+ and embed those within the final {{{samp(ODT)}}} document.
+
+ Use this option if the {{{file(styles.xml)}}} file references
+ additional files like header and footer images.
+
+ - ~nil~ ::
+
+ Use the default {{{file(styles.xml)}}}
+
+- ~org-export-odt-content-template-file~ ::
+ <<x-org-export-odt-content-template-file>>
+
+ Use this variable to specify the blank {{{file(content.xml)}}} that
+ will be used in the final output.
+
+**** Creating one-off styles
+ :PROPERTIES:
+ :DESCRIPTION: How to produce custom highlighting, etc.
+ :END:
+
+There are times when you would want one-off formatting in the exported
+document. You can achieve this by embedding raw OpenDocument XML in
+the Org file. The use of this feature is better illustrated with
+couple of examples.
+
+#+attr_texinfo: :table-type table :indic @asis
+- Embedding ODT tags as part of regular text ::
+
+ You can include simple OpenDocument tags by prefixing them with
+ {{{samp(@)}}}. For example, to highlight a region of text do the
+ following:
+
+ #+begin_example
+ @<text:span text:style-name="Highlight">This is a
+ highlighted text@</text:span>. But this is a
+ regular text.
+ #+end_example
+
+ *Hint:* To see the above example in action, edit your
+ {{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
+ add a custom {{{samp(Highlight)}}} style as shown below.
+
+ #+begin_example
+ <style:style style:name="Highlight" style:family="text">
+ <style:text-properties fo:background-color="#ff0000"/>
+ </style:style>
+ #+end_example
+
+- Embedding a one-line OpenDocument XML ::
+
+ You can add a simple OpenDocument one-liner using the ~#+ODT:~
+ directive. For example, to force a page break do the following:
+
+ #+begin_example
+ #+ODT: <text:p text:style-name="PageBreak"/>
+ #+end_example
+
+ *Hint:* To see the above example in action, edit your
+ {{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
+ add a custom {{{samp(PageBreak)}}} style as shown below.
+
+ #+begin_example
+ <style:style style:name="PageBreak" style:family="paragraph"
+ style:parent-style-name="Text_20_body">
+ <style:paragraph-properties fo:break-before="page"/>
+ </style:style>
+ #+end_example
+
+- Embedding a block of OpenDocument XML ::
+
+ You can add a large block of OpenDocument XML using the
+ ~#+BEGIN_ODT~ ... ~#+END_ODT~ construct.
+
+ For example, to create a one-off paragraph that uses bold text, do the
+ following:
+
+ #+begin_example
+ #+BEGIN_ODT
+ <text:p text:style-name="Text_20_body_20_bold">
+ This paragraph is specially formatted and uses bold text.
+ </text:p>
+ #+END_ODT
+ #+end_example
+
+**** Customizing tables in ODT export
+ :PROPERTIES:
+ :DESCRIPTION: How to define and use table templates
+ :END:
+#+cindex: tables, in ODT export
+#+cindex: #+ATTR_ODT
+
+You can override the default formatting of the table by specifying a
+custom table style with the ~#+ATTR_ODT~ line. For a discussion on
+default formatting of tables see [[Tables in ODT export]].
+
+This feature closely mimics the way table templates are defined in the
+OpenDocument-v1.2 specification.[fn:139]
+
+To have a quick preview of this feature, install the following setting and
+export the example table.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+ (setq org-export-odt-table-styles
+ (append org-export-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+#+end_src
+
+#+begin_example
+ ,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+ | Name | Phone | Age |
+ | Peter | 1234 | 17 |
+ | Anna | 4321 | 25 |
+#+end_example
+
+In the above example, you used a template named {{{samp(Custom)}}} and
+installed two table styles with the names
+{{{samp(TableWithHeaderRowAndColumn)}}} and
+{{{samp(TableWithFirstRowandLastRow)}}}. (*Important:* The
+OpenDocument styles needed for producing the above template have been
+pre-defined for you. These styles are available under the section
+marked {{{samp(Custom Table Template)}}} in
+{{{file(OrgOdtContentTemplate.xml)}}} (see
+[[x-orgodtcontenttemplate-xml][Factory styles]]). If you need additional
+templates you have to define these styles yourself.
+
+
+To use this feature proceed as follows:
+
+#+attr_texinfo: :table-type table :indic @asis
+- Create a table template[fn:140] ::
+
+ A table template is nothing but a set of {{{samp(table-cell)}}} and
+ {{{samp(paragraph)}}} styles for each of the following table cell
+ categories:
+
+ - Body
+ - First column
+ - Last column
+ - First row
+ - Last row
+ - Even row
+ - Odd row
+ - Even column
+ - Odd Column
+
+ The names for the above styles must be chosen based on the name of the
+ table template using a well-defined convention.
+
+ The naming convention is better illustrated with an example. For a
+ table template with the name {{{samp(Custom)}}}, the needed style
+ names are listed in the following table.
+
+ | Table cell type | ~table-cell~ style | ~paragraph~ style |
+ |-----------------+----------------------------------------+---------------------------------------------|
+ | Body | {{{samp(CustomTableCell)}}} | {{{samp(CustomTableParagraph)}}} |
+ | First column | {{{samp(CustomFirstColumnTableCell)}}} | {{{samp(CustomFirstColumnTableParagraph)}}} |
+ | Last column | {{{samp(CustomLastColumnTableCell)}}} | {{{samp(CustomLastColumnTableParagraph)}}} |
+ | First row | {{{samp(CustomFirstRowTableCell)}}} | {{{samp(CustomFirstRowTableParagraph)}}} |
+ | Last row | {{{samp(CustomLastRowTableCell)}}} | {{{samp(CustomLastRowTableParagraph)}}} |
+ | Even row | {{{samp(CustomEvenRowTableCell)}}} | {{{samp(CustomEvenRowTableParagraph)}}} |
+ | Odd row | {{{samp(CustomOddRowTableCell)}}} | {{{samp(CustomOddRowTableParagraph)}}} |
+ | Even column | {{{samp(CustomEvenColumnTableCell)}}} | {{{samp(CustomEvenColumnTableParagraph)}}} |
+ | Odd column | {{{samp(CustomOddColumnTableCell)}}} | {{{samp(CustomOddColumnTableParagraph)}}} |
+
+
+ To create a table template with the name {{{samp(Custom)}}}, define
+ the above styles in the ~<office:automatic-styles>~ ...
+ ~</office:automatic-styles>~ element of the content template file (see
+ [[x-orgodtcontenttemplate-xml][Factory styles]]).
+
+- Define a table style[fn:141] ::
+
+ #+vindex: org-export-odt-table-styles
+
+ To define a table style, create an entry for the style in the variable
+ ~org-export-odt-table-styles~ and specify the following:
+
+ - the name of the table template created in step (1)
+ - the set of cell styles in that template that are to be activated
+
+
+ For example, the entry below defines two different table styles
+ {{{samp(TableWithHeaderRowAndColumn)}}} and
+ {{{samp(TableWithFirstRowandLastRow)}}} based on the same template
+ {{{samp(Custom)}}}. The styles achieve their intended effect by
+ selectively activating the individual cell styles in that template.
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (setq org-export-odt-table-styles
+ (append org-export-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+ #+end_src
+
+- Associate a table with the table style ::
+
+ To do this, specify the table style created in step (2) as part of
+ the ~ATTR_ODT~ line as shown below.
+
+ #+begin_example
+ ,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+ | Name | Phone | Age |
+ | Peter | 1234 | 17 |
+ | Anna | 4321 | 25 |
+ #+end_example
+
+**** Validating OpenDocument XML
+ :PROPERTIES:
+ :DESCRIPTION: How to debug corrupt OpenDocument files
+ :END:
+
+Occasionally, you will discover that the document created by the ODT
+exporter cannot be opened by your favorite application. One of the
+common reasons for this is that the {{{file(.odt)}}} file is corrupt.
+In such cases, you may want to validate the document against the
+OpenDocument RELAX NG Compact Syntax (RNC) schema.
+
+For de-compressing the {{{file(.odt)}}} file[fn:142]:
+[[info:emacs#File Archives]]. For general help with validation (and
+schema-sensitive editing) of XML files: [[info:nxml-mode#Introduction]].
+#+vindex: org-export-odt-schema-dir
+
+If you have ready access to OpenDocument {{{file(.rnc)}}} files and
+the needed schema-locating rules in a single folder, you can customize
+the variable ~org-export-odt-schema-dir~ to point to that directory.
+The ODT exporter will take care of updating the
+~rng-schema-locating-files~ for you.
+
+** TaskJuggler export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to TaskJuggler
+ :END:
+#+cindex: TaskJuggler export
+#+cindex: Project management
+
+[[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool. It provides an optimizing
+scheduler that computes your project time lines and resource
+assignments based on the project outline and the constraints that you
+have provided.
+
+The TaskJuggler exporter is a bit different from other exporters, such
+as the ~HTML~ and LaTeX exporters for example, in that it does not
+export all the nodes of a document or strictly follow the order of the
+nodes in the document.
+
+Instead the TaskJuggler exporter looks for a tree that defines the
+tasks and optionally trees that define the resources and reports for
+this project. It then creates a TaskJuggler file based on these trees
+and the attributes defined in all the nodes.
+
+*** TaskJuggler export commands
+ :PROPERTIES:
+ :DESCRIPTION: Key bindings for TaskJuggler export
+ :END:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e j)}}}, ~org-export-as-taskjuggler~ ::
+ #+kindex: C-c C-e j
+
+ Export as a TaskJuggler file.
+
+- {{{kbd(C-c C-e J)}}}, ~org-export-as-taskjuggler-and-open~ ::
+ #+kindex: C-c C-e J
+
+ Export as a TaskJuggler file and then open the file with TaskJugglerUI
+ (only for TaskJugglerUI 2.x).
+
+*** Tasks
+ :PROPERTIES:
+ :DESCRIPTION: Marking tasks for TaskJuggler export
+ :END:
+#+vindex: org-export-taskjuggler-project-tag
+
+Create your tasks as you usually do with Org mode. Assign efforts to
+each task using properties (it is easiest to do this in the column
+view). You should end up with something similar to the example by
+Peter Jones in
+[[http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org]].
+Now mark the top node of your tasks with a tag named
+~:taskjuggler_project:~ (or whatever you customized
+~org-export-taskjuggler-project-tag~ to). You are now ready to export
+the project plan with {{{kbd(C-c C-e J)}}} which will export the
+project plan and open a gantt chart in TaskJugglerUI.
+
+*** Resources
+ :PROPERTIES:
+ :DESCRIPTION: Define TaskJuggler resources
+ :END:
+#+vindex: org-export-taskjuggler-resource-tag
+
+Next you can define resources and assign those to work on specific
+tasks. You can group your resources hierarchically. Tag the top node
+of the resources with ~:taskjuggler_resource:~ (or whatever you
+customized ~org-export-taskjuggler-resource-tag~ to). You can
+optionally assign an identifier (named {{{samp(resource_id)}}}) to the
+resources (using the standard Org properties commands, see [[Property
+syntax]]) or you can let the exporter generate identifiers automatically
+(the exporter picks the first word of the headline as the identifier
+as long as it is unique---see the documentation of
+~org-taskjuggler-get-unique-id~). Using that identifier you can then
+allocate resources to tasks. This is again done with the
+{{{samp(allocate)}}} property on the tasks. Do this in column view or
+when on the task type
+{{{ksksksk(C-c C-x p allocate,RET,<resource_id>,RET)}}}.
+
+Once the allocations are done you can again export to TaskJuggler and
+check in the Resource Allocation Graph which person is working on what
+task at what time.
+
+*** Export of properties
+ :PROPERTIES:
+ :DESCRIPTION: Which properties will be exported?
+ :END:
+
+The exporter also takes TODO state information into consideration,
+i.e., if a task is marked as done it will have the corresponding
+attribute in TaskJuggler ({{{samp(complete 100)}}}). Scheduling
+information is also taken into account to set start/end dates for
+tasks.
+
+The exporter will also export any property on a task resource or
+resource node which is known to TaskJuggler, such as
+{{{samp(limits)}}}, {{{samp(vacation)}}}, {{{samp(shift)}}},
+{{{samp(booking)}}}, {{{samp(efficiency)}}}, {{{samp(journalentry)}}},
+{{{samp(rate)}}} for resources or {{{samp(account)}}},
+{{{samp(start)}}}, {{{samp(note)}}}, {{{samp(duration)}}},
+{{{samp(end)}}}, {{{samp(journalentry)}}}, {{{samp(milestone)}}},
+{{{samp(reference)}}}, {{{samp(responsible)}}},
+{{{samp(scheduling)}}}, etc for tasks.
+
+*** Dependencies
+ :PROPERTIES:
+ :DESCRIPTION: How the exporter handles dependencies
+ :END:
+
+The exporter will handle dependencies that are defined in the tasks
+either with the {{{samp(ORDERED)}}} attribute (see [[TODO dependencies]]),
+with the {{{samp(BLOCKER)}}} attribute (see {{{file(org-depend.el)}}})
+or alternatively with a {{{samp(depends)}}} attribute. Both the
+{{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can be
+either {{{samp(previous-sibling)}}} or a reference to an identifier
+(named {{{samp(task_id)}}}) which is defined for another task in the
+project. {{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can
+define multiple dependencies separated by either space or comma. You
+can also specify optional attributes on the dependency by simply
+appending it. The following examples should illustrate this:
+
+#+begin_example
+ ,* Preparation
+ , :PROPERTIES:
+ , :task_id: preparation
+ , :ORDERED: t
+ , :END:
+ ,* Training material
+ , :PROPERTIES:
+ , :task_id: training_material
+ , :ORDERED: t
+ , :END:
+ ,** Markup Guidelines
+ , :PROPERTIES:
+ , :Effort: 2d
+ , :END:
+ ,** Workflow Guidelines
+ , :PROPERTIES:
+ , :Effort: 2d
+ , :END:
+ ,* Presentation
+ , :PROPERTIES:
+ , :Effort: 2d
+ , :BLOCKER: training_material { gapduration 1d } preparation
+ , :END:
+#+end_example
+
+*** Reports
+ :PROPERTIES:
+ :DESCRIPTION: Gantt charts, etc.
+ :END:
+#+vindex: org-export-taskjuggler-default-reports
+
+TaskJuggler can produce many kinds of reports (e.g., gantt chart,
+resource allocation, etc). The user defines what kind of reports
+should be generated for a project in the TaskJuggler file. By default,
+the exporter will automatically insert some pre-set reports in the
+file. These defaults are defined in
+~org-export-taskjuggler-default-reports~. They can be modified using
+customize along with a number of other options. For a more complete
+list, see
+{{{ksksksk(M-x customize-group,RET,org-export-taskjuggler,RET)}}}.
+
+Alternately, the user can tag a tree with
+~org-export-taskjuggler-report-tag~, and define reports in sub-nodes,
+similarly to what is done with tasks or resources. The properties used
+for report generation are defined in
+~org-export-taskjuggler-valid-report-attributes~. In addition, a
+special property named {{{samp(report-kind)}}} is used to define the
+kind of report one wants to generate (by default, a
+{{{samp(taskreport)}}}).
+
+For more information and examples see the Org-taskjuggler tutorial at
+[[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html]].
+
+** Freemind export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to Freemind mind maps
+ :END:
+#+cindex: Freemind export
+#+cindex: mind map
+
+The Freemind exporter was written by Lennart Borgman.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e m)}}}, ~org-export-as-freemind~ ::
+ #+kindex: C-c C-e m
+
+ Export as a Freemind mind map. For an Org file {{{file(myfile.org)}}},
+ the Freemind file will be {{{file(myfile.mm)}}}.
+
+** XOXO export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to XOXO
+ :END:
+#+cindex: XOXO export
+
+Org mode contains an exporter that produces XOXO-style output.
+Currently, this exporter only handles the general outline structure
+and does not interpret any additional Org mode features.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e x)}}}, ~org-export-as-xoxo~ ::
+ #+kindex: C-c C-e x
+
+ Export as an XOXO file. For an Org file {{{file(myfile.org)}}}, the
+ XOXO file will be {{{file(myfile.html)}}}.
+
+- {{{kbd(C-c C-e v x)}}} ::
+ #+kindex: C-c C-e v x
+
+ Export only the visible part of the document.
+
+** iCalendar export
+ :PROPERTIES:
+ :DESCRIPTION: Exporting to iCalendar format
+ :END:
+#+cindex: iCalendar export
+
+#+vindex: org-icalendar-include-todo
+#+vindex: org-icalendar-use-deadline
+#+vindex: org-icalendar-use-scheduled
+#+vindex: org-icalendar-categories
+#+vindex: org-icalendar-alarm-time
+
+Some people use Org mode for keeping track of projects, but still
+prefer a standard calendar application for anniversaries and
+appointments. In this case it can be useful to show deadlines and
+other time-stamped items in Org files in the calendar application. Org
+mode can export calendar information in the standard iCalendar format.
+If you also want to have TODO entries included in the export,
+configure the variable ~org-icalendar-include-todo~. Plain timestamps
+are exported as VEVENT, and TODO items as VTODO. It will also create
+events from deadlines that are in non-TODO items. Deadlines and
+scheduling dates in TODO items will be used to set the start and due
+dates for the TODO entry.[fn:143] As categories, it will use the tags
+locally defined in the heading, and the file/tree category.[fn:144]
+See the variable ~org-icalendar-alarm-time~ for a way to assign alarms
+to entries with a time.
+
+#+vindex: org-icalendar-store-UID
+#+cindex: property, ID
+
+The iCalendar standard requires each entry to have a globally unique
+identifier (UID). Org creates these identifiers during export. If you
+set the variable ~org-icalendar-store-UID~, the UID will be stored in
+the ~:ID:~ property of the entry and re-used next time you report this
+entry. Since a single entry can give rise to multiple iCalendar
+entries (as a timestamp, a deadline, a scheduled item, and as a TODO
+item), Org adds prefixes to the UID, depending on what triggered the
+inclusion of the entry. In this way the UID remains unique, but a
+synchronization program can still figure out from which entry all the
+different instances originate.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e i)}}}, ~org-export-icalendar-this-file~ ::
+ #+kindex: C-c C-e i
+
+ Create iCalendar entries for the current file and store them in the
+ same directory, using a file extension {{{file(.ics)}}}.
+
+- {{{kbd(C-c C-e I)}}}, ~ org-export-icalendar-all-agenda-files~ ::
+ #+kindex: C-c C-e I
+ #+vindex: org-agenda-files
+
+ Like {{{kbd(C-c C-e i)}}}, but do this for all files in
+ ~org-agenda-files~. For each of these files, a separate iCalendar file
+ will be written.
+
+- {{{kbd(C-c C-e c)}}}, ~org-export-icalendar-combine-agenda-files~ ::
+ #+kindex: C-c C-e c
+ #+vindex: org-combined-agenda-icalendar-file
+
+ Create a single large iCalendar file from all files in
+ ~org-agenda-files~ and write it to the file given by
+ ~org-combined-agenda-icalendar-file~.
+
+
+#+vindex: org-use-property-inheritance
+#+vindex: org-icalendar-include-body
+#+cindex: property, SUMMARY
+#+cindex: property, DESCRIPTION
+#+cindex: property, LOCATION
+
+The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
+the selected entries have them.[fn:145] If not, the summary will be
+derived from the headline, and the description from the body (limited
+to ~org-icalendar-include-body~ characters).
+
+How this calendar is best read and updated, depends on the application
+you are using. The FAQ covers this issue.
+
+* Publishing
+ :PROPERTIES:
+ :DESCRIPTION: Create a web site of linked Org files
+ :END:
+#+cindex: publishing
+#+cindex: O'Toole, David
+
+Org includes a publishing management system that allows you to
+configure automatic HTML conversion of /projects/ composed of
+interlinked org files. You can also configure Org to automatically
+upload your exported HTML pages and related attachments, such as
+images and source code files, to a web server.
+
+You can also use Org to convert files into PDF, or even combine HTML
+and PDF conversion so that files are available in both formats on the
+server.
+
+Publishing has been contributed to Org by David O'Toole.
+
+** Configuration
+ :PROPERTIES:
+ :DESCRIPTION: Defining projects
+ :END:
+Publishing needs significant configuration to specify files,
+destination and many other properties of a project.
+
+*** Project alist
+ :PROPERTIES:
+ :DESCRIPTION: The central configuration variable
+ :TITLE: The variable ~org-publish-project-alist~
+ :END:
+#+cindex: org-publish-project-alist
+#+cindex: projects, for publishing
+#+vindex: org-publish-project-alist
+
+Publishing is configured almost entirely through setting the value of
+one variable, called ~org-publish-project-alist~. Each element of the
+list configures one project, and may be in one of the two following
+forms:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+ ("project-name" :property value :property value ...)
+#+end_src
+
+i.e., a well-formed property list with alternating keys and values,
+or:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+ ("project-name" :components ("project-name" "project-name" ...))
+#+end_src
+
+In both cases, projects are configured by specifying property values.
+A project defines the set of files that will be published, as well as
+the publishing configuration to use when publishing those files. When
+a project takes the second form listed above, the individual members
+of the ~:components~ property are taken to be sub-projects, which
+group together files requiring different publishing options. When you
+publish such a "meta-project," all the components will also be
+published, in the sequence given.
+
+*** Sources and destinations
+ :PROPERTIES:
+ :DESCRIPTION: From here to there
+ :TITLE: Sources and destinations for files
+ :END:
+#+cindex: directories, for publishing
+
+Most properties are optional, but some should always be set. In
+particular, Org needs to know where to look for source files, and
+where to put published files.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:base-directory~ ::
+
+ Directory containing publishing source files
+
+- ~:publishing-directory~ ::
+
+ Directory where output files will be published. You can directly
+ publish to a webserver using a file name syntax appropriate for the
+ Emacs {{{file(tramp)}}} package. Or you can publish to a local
+ directory and use external tools to upload your website
+ (see [[Uploading files]]).
+
+- ~:preparation-function~ ::
+
+ Function or list of functions to be called before starting the
+ publishing process, for example, to run ~make~ for updating files to
+ be published. The project property list is scoped into this call as
+ the variable ~project-plist~.
+
+- ~:completion-function~ ::
+
+ Function or list of functions called after finishing the publishing
+ process, for example, to change permissions of the resulting files.
+ The project property list is scoped into this call as the variable
+ ~project-plist~.
+
+*** Selecting files
+ :PROPERTIES:
+ :DESCRIPTION: What files are part of the project?
+ :END:
+#+cindex: files, selecting for publishing
+
+By default, all files with extension {{{file(.org)}}} in the base directory
+are considered part of the project. This can be modified by setting the
+following properties:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:base-extension~ ::
+
+ Extension (without the dot!) of source files. This actually is a
+ regular expression. Set this to the symbol ~any~ if you want to get
+ all files in ~:base-directory~, even without extension.
+
+- ~:exclude~ ::
+
+ Regular expression to match file names that should not be published,
+ even though they have been selected on the basis of their extension.
+
+- ~:include~ ::
+
+ List of files to be included regardless of ~:base-extension~ and
+ ~:exclude~.
+
+- ~:recursive~ ::
+
+ Non-nil means, check base-directory recursively for files to publish.
+
+*** Publishing action
+ :PROPERTIES:
+ :DESCRIPTION: Setting the function doing the publishing
+ :END:
+#+cindex: action, for publishing
+
+Publishing means that a file is copied to the destination directory and
+possibly transformed in the process. The default transformation is to export
+Org files as HTML files, and this is done by the function
+~org-publish-org-to-html~ which calls the HTML exporter (see [[HTML
+export]]). But you also can publish your content as PDF files using
+~org-publish-org-to-pdf~, or as ~ascii~, ~latin1~ or
+~utf8~ encoded files using the corresponding functions. If you want to
+publish the Org file itself, but with /archived/, /commented/, and
+/tag-excluded/ trees removed, use ~org-publish-org-to-org~ and set the
+parameters ~:plain-source~ and/or ~:htmlized-source~. This will
+produce {{{file(file.org)}}} and {{{file(file.org.html)}}} in the publishing
+directory.[fn:146] Other files like images only need to be copied to the
+publishing destination; for this you may use ~org-publish-attachment~.
+For non-Org files, you always need to specify the publishing function:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:publishing-function~ ::
+
+ Function executing the publication of a file. This may also be a list
+ of functions, which will all be called in turn.
+
+- ~:plain-source~ ::
+
+ Non-nil means, publish plain source.
+
+- ~:htmlized-source~ ::
+
+ Non-nil means, publish htmlized source.
+
+
+The function must accept three arguments: a property list containing
+at least a ~:publishing-directory~ property, the name of the file to
+be published, and the path to the publishing directory of the output
+file. It should take the specified file, make the necessary
+transformation (if any) and place the result into the destination
+folder.
+
+*** Publishing options
+ :PROPERTIES:
+ :DESCRIPTION: Tweaking HTML/LaTeX export
+ :END:
+#+cindex: options, for publishing
+
+The property list can be used to set many export options for the HTML
+and LaTeX exporters. In most cases, these properties correspond to user
+variables in Org. The table below lists these properties along
+with the variable they belong to. See the documentation string for the
+respective variable for details.
+
+#+vindex: org-export-html-link-up
+#+vindex: org-export-html-link-home
+#+vindex: org-export-default-language
+#+vindex: org-display-custom-times
+#+vindex: org-export-headline-levels
+#+vindex: org-export-with-section-numbers
+#+vindex: org-export-section-number-format
+#+vindex: org-export-with-toc
+#+vindex: org-export-preserve-breaks
+#+vindex: org-export-with-archived-trees
+#+vindex: org-export-with-emphasize
+#+vindex: org-export-with-sub-superscripts
+#+vindex: org-export-with-special-strings
+#+vindex: org-export-with-footnotes
+#+vindex: org-export-with-drawers
+#+vindex: org-export-with-tags
+#+vindex: org-export-with-todo-keywords
+#+vindex: org-export-with-tasks
+#+vindex: org-export-with-done-tasks
+#+vindex: org-export-with-priority
+#+vindex: org-export-with-TeX-macros
+#+vindex: org-export-with-LaTeX-fragments
+#+vindex: org-export-skip-text-before-1st-heading
+#+vindex: org-export-with-fixed-width
+#+vindex: org-export-with-timestamps
+#+vindex: org-export-author-info
+#+vindex: org-export-email-info
+#+vindex: org-export-creator-info
+#+vindex: org-export-time-stamp-file
+#+vindex: org-export-with-tables
+#+vindex: org-export-highlight-first-table-line
+#+vindex: org-export-html-style-include-default
+#+vindex: org-export-html-style-include-scripts
+#+vindex: org-export-html-style
+#+vindex: org-export-html-style-extra
+#+vindex: org-export-html-link-org-files-as-html
+#+vindex: org-export-html-inline-images
+#+vindex: org-export-html-extension
+#+vindex: org-export-html-table-tag
+#+vindex: org-export-html-expand
+#+vindex: org-export-html-with-timestamp
+#+vindex: org-export-publishing-directory
+#+vindex: org-export-html-preamble
+#+vindex: org-export-html-postamble
+#+vindex: user-full-name
+#+vindex: user-mail-address
+#+vindex: org-export-select-tags
+#+vindex: org-export-exclude-tags
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:link-up~ :: ~org-export-html-link-up~
+- ~:link-home~ :: ~org-export-html-link-home~
+- ~:language~ :: ~org-export-default-language~
+- ~:customtime~ :: ~org-display-custom-times~
+- ~:headline-levels~ :: ~org-export-headline-levels~
+- ~:section-numbers~ :: ~org-export-with-section-numbers~
+- ~:section-number-format~ :: ~org-export-section-number-format~
+- ~:table-of-contents~ :: ~org-export-with-toc~
+- ~:preserve-breaks~ :: ~org-export-preserve-breaks~
+- ~:archived-trees~ :: ~org-export-with-archived-trees~
+- ~:emphasize~ :: ~org-export-with-emphasize~
+- ~:sub-superscript~ :: ~org-export-with-sub-superscripts~
+- ~:special-strings~ :: ~org-export-with-special-strings~
+- ~:footnotes~ :: ~org-export-with-footnotes~
+- ~:drawers~ :: ~org-export-with-drawers~
+- ~:tags~ :: ~org-export-with-tags~
+- ~:todo-keywords~ :: ~org-export-with-todo-keywords~
+- ~:tasks~ :: ~org-export-with-tasks~
+- ~:priority~ :: ~org-export-with-priority~
+- ~:TeX-macros~ :: ~org-export-with-TeX-macros~
+- ~:LaTeX-fragments~ :: ~org-export-with-LaTeX-fragments~
+- ~:latex-listings~ :: ~org-export-latex-listings~
+- ~:skip-before-1st-heading~ :: ~org-export-skip-text-before-1st-heading~
+- ~:fixed-width~ :: ~org-export-with-fixed-width~
+- ~:timestamps~ :: ~org-export-with-timestamps~
+- ~:author~ :: ~user-full-name~
+- ~:email~ :: ~user-mail-address~ : ~addr;addr;..~
+- ~:author-info~ :: ~org-export-author-info~
+- ~:email-info~ :: ~org-export-email-info~
+- ~:creator-info~ :: ~org-export-creator-info~
+- ~:tables~ :: ~org-export-with-tables~
+- ~:table-auto-headline~ :: ~org-export-highlight-first-table-line~
+- ~:style-include-default~ :: ~org-export-html-style-include-default~
+- ~:style-include-scripts~ :: ~org-export-html-style-include-scripts~
+- ~:style~ :: ~org-export-html-style~
+- ~:style-extra~ :: ~org-export-html-style-extra~
+- ~:convert-org-links~ :: ~org-export-html-link-org-files-as-html~
+- ~:inline-images~ :: ~org-export-html-inline-images~
+- ~:html-extension~ :: ~org-export-html-extension~
+- ~:html-preamble~ :: ~org-export-html-preamble~
+- ~:html-postamble~ :: ~org-export-html-postamble~
+- ~:xml-declaration~ :: ~org-export-html-xml-declaration~
+- ~:html-table-tag~ :: ~org-export-html-table-tag~
+- ~:expand-quoted-html~ :: ~org-export-html-expand~
+- ~:timestamp~ :: ~org-export-html-with-timestamp~
+- ~:publishing-directory~ :: ~org-export-publishing-directory~
+- ~:select-tags~ :: ~org-export-select-tags~
+- ~:exclude-tags~ :: ~org-export-exclude-tags~
+- ~:latex-image-options~ :: ~org-export-latex-image-default-option~
+
+
+Most of the ~org-export-with-*~ variables have the same effect in both
+HTML and LaTeX exporters, except for ~:TeX-macros~ and
+~:LaTeX-fragments~ options, respectively ~nil~ and ~t~ in the LaTeX
+export. See ~org-export-plist-vars~ to check this list of options.
+
+#+vindex: org-publish-project-alist
+
+When a property is given a value in ~org-publish-project-alist~, its
+setting overrides the value of the corresponding user variable (if
+any) during publishing. Options set within a file (see [[Export
+options]]), however, override everything.
+
+*** Publishing links
+ :PROPERTIES:
+ :DESCRIPTION: Which links keep working after publishing?
+ :END:
+#+cindex: links, publishing
+
+To create a link from one Org file to another, you would use something
+like ~[[file:foo.org][The foo]]~ or simply ~[[file:foo.org]]~ (see
+[[Hyperlinks]]). When published, this link becomes a link to
+{{{file(foo.html)}}}. In this way, you can interlink the pages of your
+"org web" project and the links will work as expected when you publish
+them to HTML. If you also publish the Org source file and want to link
+to that, use an ~http:~ link instead of a ~file:~ link, because
+~file:~ links are converted to link to the corresponding
+{{{file(html)}}} file.
+
+You may also link to related files, such as images. Provided you are
+careful with relative file names, and provided you have also
+configured Org to upload the related files, these links will work too.
+See [[Complex example]], for an example of this usage.
+
+Sometimes an Org file to be published may contain links that are only
+valid in your production environment, but not in the publishing
+location. In this case, use the following property to define a
+function for checking link validity:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:link-validation-function~ ::
+ Function to validate links
+
+
+{{{noindent}}} This function must accept two arguments, the file name
+and a directory relative to which the file name is interpreted in the
+production environment. If this function returns ~nil~, then the HTML
+generator will only insert a description into the HTML file, but no
+link. One option for this function is ~org-publish-validate-link~
+which checks if the given file is part of any project in
+~org-publish-project-alist~.
+
+*** Site map
+ :PROPERTIES:
+ :DESCRIPTION: Generating a list of all pages
+ :TITLE: Generating a sitemap
+ :END:
+#+cindex: sitemap, of published pages
+
+The following properties may be used to control publishing of
+a map of files for a given project.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:auto-sitemap~ ::
+
+ When non-nil, publish a sitemap during ~org-publish-current-project~
+ or ~org-publish-all~.
+
+- ~:sitemap-filename~ ::
+
+ Filename for output of sitemap. Defaults to {{{file(sitemap.org)}}} (which
+ becomes {{{file(sitemap.html)}}}).
+
+- ~:sitemap-title~ ::
+
+ Title of sitemap page. Defaults to name of file.
+
+- ~:sitemap-function~ ::
+
+ Plug-in function to use for generation of the sitemap. Defaults to
+ ~org-publish-org-sitemap~, which generates a plain list of links to
+ all files in the project.
+
+- ~:sitemap-sort-folders~ ::
+
+ Where folders should appear in the sitemap. Set this to ~first~
+ (default) or ~last~ to display folders first or last, respectively.
+ Any other value will mix files and folders.
+
+- ~:sitemap-sort-files~ ::
+
+ How the files are sorted in the site map. Set this to ~alphabetically~
+ (default), ~chronologically~ or ~anti-chronologically~.
+ ~chronologically~ sorts the files with older date first while
+ ~anti-chronologically~ sorts the files with newer date first.
+ ~alphabetically~ sorts the files alphabetically. The date of a file is
+ retrieved with ~org-publish-find-date~.
+
+- ~:sitemap-ignore-case~ ::
+
+ Should sorting be case-sensitive? Default ~nil~.
+
+- ~:sitemap-file-entry-format~ ::
+
+ With this option one can tell how a sitemap's entry is formatted in
+ the sitemap. This is a format string with some escape sequences: ~%t~
+ stands for the title of the file, ~%a~ stands for the author of the
+ file and ~%d~ stands for the date of the file. The date is retrieved
+ with the ~org-publish-find-date~ function and formatted with
+ ~org-publish-sitemap-date-format~. Default ~%t~.
+
+- ~:sitemap-date-format~ ::
+
+ Format string for the ~format-time-string~ function that tells how a
+ sitemap entry's date is to be formatted. This property bypasses
+ ~org-publish-sitemap-date-format~ which defaults to ~%Y-%m-%d~.
+
+- ~:sitemap-sans-extension~ ::
+
+ When non-nil, remove filenames' extensions from the generated sitemap.
+ Useful to have cool URIs (see [[http://www.w3.org/Provider/Style/URI]]).
+ Defaults to ~nil~.
+
+*** Generating an index
+ :PROPERTIES:
+ :DESCRIPTION: An index that reaches across pages
+ :END:
+#+cindex: index, in a publishing project
+
+Org mode can generate an index across the files of a publishing project.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:makeindex~ ::
+
+ When non-nil, generate in index in the file {{{file(theindex.org)}}}
+ and publish it as {{{file(theindex.html)}}}.
+
+
+The file will be created when first publishing a project with the
+~:makeindex~ set. The file only contains a statement
+{{{samp(#+INCLUDE: "theindex.inc")}}}. You can then build around this
+include statement by adding a title, style information, etc.
+
+** Uploading files
+ :PROPERTIES:
+ :DESCRIPTION: How to get files up on the server
+ :END:
+#+cindex: rsync
+#+cindex: unison
+
+For those people already utilizing third party sync tools such as
+{{{command(rsync)}}} or {{{command(unison)}}}, it might be preferable
+not to use the built in remote publishing facilities of Org mode
+which rely heavily on Tramp. Tramp, while very useful and powerful,
+tends not to be so efficient for multiple file transfer and has been
+known to cause problems under heavy usage.
+
+Specialized synchronization utilities offer several advantages. In
+addition to timestamp comparison, they also do content and
+permissions/attribute checks. For this reason you might prefer to
+publish your web to a local directory (possibly even in place with
+your Org files) and then use {{{file(unison)}}} or {{{file(rsync)}}}
+to do the synchronization with the remote host.
+
+Since Unison (for example) can be configured as to which files to
+transfer to a certain remote destination, it can greatly simplify the
+project publishing definition. Simply keep all files in the correct
+location, process your Org files with ~org-publish~ and let the
+synchronization tool do the rest. You do not need, in this scenario,
+to include attachments such as {{{file(jpg)}}}, {{{file(css)}}} or
+{{{file(gif)}}} files in the project definition since the 3rd party
+tool syncs them.
+
+Publishing to a local directory is also much faster than to a remote
+one, so that you can afford more easily to republish entire projects.
+If you set ~org-publish-use-timestamps-flag~ to ~nil~, you gain the
+main benefit of re-including any changed external files such as source
+example files you might include with ~#+INCLUDE:~. The timestamp
+mechanism in Org is not smart enough to detect if included files have
+been modified.
+
+** Sample configuration
+ :PROPERTIES:
+ :DESCRIPTION: Example projects
+ :END:
+Below we provide two example configurations. The first one is a simple
+project publishing only a set of Org files. The second example is
+more complex, with a multi-component project.
+
+*** Simple example
+ :PROPERTIES:
+ :DESCRIPTION: One-component publishing
+ :TITLE: Example: simple publishing configuration
+ :END:
+This example publishes a set of Org files to the {{{file(public_html)}}}
+directory on the local machine.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-publish-project-alist
+ '(("org"
+ :base-directory "~/org/"
+ :publishing-directory "~/public_html"
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=\"stylesheet\"
+ href=\"../other/mystyle.css\"
+ type=\"text/css\"/>")))
+#+end_src
+
+*** Complex example
+ :PROPERTIES:
+ :DESCRIPTION: A multi-component publishing example
+ :TITLE: Example: complex publishing configuration
+ :END:
+This more complicated example publishes an entire website, including
+Org files converted to HTML, image files, Emacs Lisp source code, and
+style sheets. The publishing directory is remote and private files are
+excluded.
+
+To ensure that links are preserved, care should be taken to replicate
+your directory structure on the web server, and to use relative file
+paths. For example, if your Org files are kept in {{{file(~/org)}}}
+and your publishable images in {{{file(~/images)}}}, you would link to
+an image with
+
+#+begin_example
+ file:../images/myimage.png
+#+end_example
+
+On the web server, the relative path to the image should be the
+same. You can accomplish this by setting up an "images" folder in the
+right place on the web server, and publishing images to it.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(setq org-publish-project-alist
+ '(("orgfiles"
+ :base-directory "~/org/"
+ :base-extension "org"
+ :publishing-directory "/ssh:user@@host:~/html/notebook/"
+ :publishing-function org-publish-org-to-html
+ :exclude "PrivatePage.org" ;; regexp
+ :headline-levels 3
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=\"stylesheet\"
+ href=\"../other/mystyle.css\" type=\"text/css\"/>"
+ :html-preamble t)
+
+ ("images"
+ :base-directory "~/images/"
+ :base-extension "jpg\\|gif\\|png"
+ :publishing-directory "/ssh:user@@host:~/html/images/"
+ :publishing-function org-publish-attachment)
+
+ ("other"
+ :base-directory "~/other/"
+ :base-extension "css\\|el"
+ :publishing-directory "/ssh:user@@host:~/html/other/"
+ :publishing-function org-publish-attachment)
+ ("website" :components ("orgfiles" "images" "other"))))
+#+end_src
+
+** Triggering publication
+ :PROPERTIES:
+ :DESCRIPTION: Publication commands
+ :END:
+Once properly configured, Org can publish with the following commands:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(C-c C-e X)}}}, ~org-publish~ ::
+ #+kindex: C-c C-e X
+
+ Prompt for a specific project and publish all files that belong to it.
+
+- {{{kbd(C-c C-e P)}}}, ~org-publish-current-project~ ::
+ #+kindex: C-c C-e P
+
+ Publish the project containing the current file.
+
+- {{{kbd(C-c C-e F)}}}, ~org-publish-current-file~ ::
+ #+kindex: C-c C-e F
+
+ Publish only the current file.
+
+- {{{kbd(C-c C-e E)}}}, ~org-publish-all~ ::
+ #+kindex: C-c C-e E
+
+ Publish every project.
+
+
+#+vindex: org-publish-use-timestamps-flag
+
+Org uses timestamps to track when a file has changed. The above
+functions normally only publish changed files. You can override this
+and force publishing of all files by giving a prefix argument to any
+of the commands above, or by customizing the variable
+~org-publish-use-timestamps-flag~. This may be necessary in particular
+if files include other files via ~#+SETUPFILE:~ or ~#+INCLUDE:~.
+
+* Working with source code
+ :PROPERTIES:
+ :DESCRIPTION: Export, evaluate, and tangle code blocks
+ :ALT_TITLE: Working With Source Code
+ :END:
+#+cindex: Schulte, Eric
+#+cindex: Davison, Dan
+#+cindex: source code, working with
+
+Source code can be included in Org mode documents using a
+{{{samp(src)}}} block, e.g.:
+
+#+begin_example
+ #+BEGIN_SRC emacs-lisp
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+ #+END_SRC
+#+end_example
+
+Org mode provides a number of features for working with live source
+code, including editing of code blocks in their native major-mode,
+evaluation of code blocks, converting code blocks into source files
+(known as "tangling" in literate programming), and exporting code
+blocks and their results in several formats. This functionality was
+contributed by Eric Schulte and Dan Davison, and was originally named
+Org-babel.
+
+The following sections describe Org mode's code block handling facilities.
+
+** Structure of code blocks
+ :PROPERTIES:
+ :DESCRIPTION: Code block syntax described
+ :END:
+#+cindex: code block, structure
+#+cindex: source code, block structure
+#+cindex: #+NAME
+#+cindex: #+BEGIN_SRC
+
+Live code blocks can be specified with a {{{samp(src)}}} block or
+inline.[fn:147] The structure of a {{{samp(src)}}} block is shown in
+the following example:
+
+#+begin_example
+ ,#+NAME: <name>
+ ,#+BEGIN_SRC <language> <switches> <header arguments>
+ <body>
+ ,#+END_SRC
+#+end_example
+
+The ~#+NAME:~ line is optional, and can be used to name the code
+block. Live code blocks require that a language be specified on the
+~#+BEGIN_SRC~ line. Switches and header arguments are optional.
+#+cindex: source code, inline
+
+Live code blocks can also be specified inline using the following
+syntax:
+
+#+begin_example
+ src_<language>{<body>}
+#+end_example
+
+or
+
+#+begin_example
+ src_<language>[<header arguments>]{<body>}
+#+end_example
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~<#+NAME: name>~ ::
+ #+cindex: #+NAME
+
+ This line associates a name with the code block. This is similar to
+ the ~#+TBLNAME: NAME~ lines that can be used to name tables in Org
+ mode files. Referencing the name of a code block makes it possible to
+ evaluate the block from other places in the file, from other files, or
+ from Org mode table formulas (see [[The spreadsheet]]). Names are assumed
+ to be unique and the behavior of Org mode when two or more blocks
+ share the same name is undefined.
+
+- ~<language>~ ::
+ #+cindex: source code, language
+
+ The language of the code in the block (see [[Languages]]).
+
+- ~<switches>~ ::
+ #+cindex: source code, switches
+
+ Optional switches control code block export (see the discussion of
+ switches in [[Literal examples]]).
+
+- ~<header arguments>~ ::
+ #+cindex: source code, header arguments
+
+ Optional header arguments control many aspects of evaluation, export
+ and tangling of code blocks (see [[Header arguments]]). Header arguments
+ can also be set on a per-buffer or per-subtree basis using properties.
+
+- ~<body>~ ::
+
+ Source code in the specified language.
+
+** Editing source code
+ :PROPERTIES:
+ :DESCRIPTION: Language major-mode editing
+ :END:
+#+cindex: code block, editing
+#+cindex: source code, editing
+#+kindex: C-c '
+
+Use {{{kbd(C-c ')}}} to edit the current code block. This brings up a
+language major-mode edit buffer containing the body of the code block.
+Saving this buffer will write the new contents back to the Org buffer.
+Use {{{kbd(C-c ')}}} again to exit.
+
+The ~org-src-mode~ minor mode will be active in the edit buffer. The
+following variables can be used to configure the behavior of the edit
+buffer. See also the customization group ~org-edit-structure~ for
+further configuration options.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~org-src-lang-modes~ ::
+
+ If an Emacs major-mode named ~<lang>-mode~ exists, where
+ ~<lang>~ is the language named in the header line of the code block,
+ then the edit buffer will be placed in that major-mode. This variable
+ can be used to map arbitrary language names to existing major modes.
+
+- ~org-src-window-setup~ ::
+
+ Controls the way Emacs windows are rearranged when the edit buffer is
+ created.
+
+- ~org-src-preserve-indentation~ ::
+
+ This variable is especially useful for tangling languages such as
+ Python, in which whitespace indentation in the output is meaningful.
+
+- ~org-src-ask-before-returning-to-edit-buffer~ ::
+
+ By default, Org will ask before returning to an open edit buffer. Set this
+ variable to nil to switch without asking.
+
+
+To turn on native code fontification in the Org mode buffer, configure
+the variable ~org-src-fontify-natively~.
+
+** Exporting code blocks
+ :PROPERTIES:
+ :DESCRIPTION: Export contents and/or results
+ :END:
+#+cindex: code block, exporting
+#+cindex: source code, exporting
+
+It is possible to export the /code/ of code blocks, the /results/ of
+code block evaluation, /both/ the code and the results of code block
+evaluation, or /none/. For most languages, the default exports code.
+However, for some languages (e.g., ~ditaa~) the default exports the
+results of code block evaluation. For information on exporting code
+block bodies, see [[Literal examples]].
+
+The ~:exports~ header argument can be used to specify export
+behavior with the following arguments:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:exports code~ ::
+
+ The default in most languages. The body of the code block is exported, as
+ described in [[Literal examples]].
+
+- ~:exports results~ ::
+
+ The code block will be evaluated and the results will be placed in the
+ Org mode buffer for export, either updating previous results of the
+ code block located anywhere in the buffer or, if no previous results
+ exist, placing the results immediately after the code block. The body
+ of the code block will not be exported.
+
+- ~:exports both~ ::
+
+ Both the code block and its results will be exported.
+
+- ~:exports none~ ::
+
+ Neither the code block nor its results will be exported.
+
+
+It is possible to inhibit the evaluation of code blocks during export.
+Setting the ~org-export-babel-evaluate~ variable to ~nil~ will ensure
+that no code blocks are evaluated as part of the export process. This
+can be useful in situations where potentially untrusted Org mode files
+are exported in an automated fashion, for example when Org mode is
+used as the markup language for a wiki.
+
+** Extracting source code
+ :PROPERTIES:
+ :DESCRIPTION: Create pure source code files
+ :END:
+#+cindex: tangling
+#+cindex: source code, extracting
+#+cindex: code block, extracting source code
+
+Creating pure source code files by extracting code from source blocks
+is referred to as "tangling"---a term adopted from the literate
+programming community. During tangling of code blocks their bodies are
+expanded using ~org-babel-expand-src-block~ which can expand both
+variable and ``noweb'' style references (see [[Noweb reference syntax]]).
+
+*** Header arguments for tangling
+#+attr_texinfo: :table-type table :indic @asis
+- ~:tangle no~ ::
+
+ The default. The code block is not included in the tangled output.
+
+- ~:tangle yes~ ::
+
+ Include the code block in the tangled output. The output file name is
+ the name of the org file with the extension {{{samp(.org)}}} replaced
+ by the extension for the block language.
+
+- ~:tangle filename~ ::
+
+ Include the code block in the tangled output to file {{{samp(filename)}}}.
+
+*** Functions for tangling
+#+attr_texinfo: :table-type table :indic @asis
+- ~org-babel-tangle~ ::
+ #+kindex: C-c C-v t
+
+ Tangle the current file. Bound to {{{kbd(C-c C-v t)}}}.
+
+ With a prefix argument only tangle the current code block.
+
+- ~org-babel-tangle-file~ ::
+ #+kindex: C-c C-v f
+
+ Choose a file to tangle. Bound to {{{kbd(C-c C-v f)}}}.
+
+*** Hooks for tangling
+#+attr_texinfo: :table-type table :indic @asis
+- ~org-babel-post-tangle-hook~ ::
+
+ This hook is run from within code files tangled by ~org-babel-tangle~.
+ Example applications could include post-processing, compilation, or
+ evaluation of tangled code files.
+
+** Evaluating code blocks
+ :PROPERTIES:
+ :DESCRIPTION: Place results in the Org buffer
+ :END:
+#+cindex: code block, evaluating
+#+cindex: source code, evaluating
+#+cindex: #+RESULTS
+
+Code blocks can be evaluated and the results of evaluation optionally
+placed in the Org mode buffer.[fn:148] The results of evaluation are
+placed following a line that begins by default with ~#+RESULTS~ and
+optionally a cache identifier and/or the name of the evaluated code
+block. The default value of ~#+RESULTS~ can be changed with the
+customizable variable ~org-babel-results-keyword~.
+
+By default, the evaluation facility is only enabled for Lisp code
+blocks specified as ~emacs-lisp~. However, source code blocks in many
+languages can be evaluated within Org mode (see [[Languages]] for a list
+of supported languages and [[Structure of code blocks]] for information on
+the syntax used to define a code block).
+
+#+kindex: C-c C-c
+#+kindex: C-c C-v e
+
+There are a number of ways to evaluate code blocks. The simplest is to
+press {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-v e)}}} with the point on a
+code block.[fn:149] This will call the ~org-babel-execute-src-block~
+function to evaluate the block and insert its results into the Org
+mode buffer.
+
+#+cindex: #+CALL
+
+It is also possible to evaluate named code blocks from anywhere in an
+Org mode buffer or an Org mode table. Live code blocks located in the
+current Org mode buffer or in the ``Library of Babel'' (see [[Library of
+Babel]]) can be executed. Named code blocks can be executed with a
+separate ~#+CALL:~ line or inline within a block of text.
+
+The syntax of the ~#+CALL:~ line is:
+
+#+begin_example
+ ,#+CALL: <name>(<arguments>)
+ ,#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
+#+end_example
+
+The syntax for inline evaluation of named code blocks is:
+
+#+begin_example
+ ... call_<name>(<arguments>) ...
+ ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
+#+end_example
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~<name>~ ::
+
+ The name of the code block to be evaluated (see [[Structure of code
+ blocks]]).
+
+- ~<arguments>~ ::
+
+ Arguments specified in this section will be passed to the code block.
+ These arguments use standard function call syntax, rather than header
+ argument syntax. For example, a ~#+CALL:~ line that passes the number
+ four to a code block named ~double~, which declares the header
+ argument ~:var n=2~, would be written as ~#+CALL: double(n=4)~.
+
+- ~<inside header arguments>~ ::
+
+ Inside header arguments are passed through and applied to the named
+ code block. These arguments use header argument syntax rather than
+ standard function call syntax. Inside header arguments affect how the
+ code block is evaluated. For example, ~[:results output]~ will collect
+ the results of everything printed to ~STDOUT~ during execution of the
+ code block.
+
+- ~<end header arguments>~ ::
+
+ End header arguments are applied to the calling instance and do not
+ affect evaluation of the named code block. They affect how the results
+ are incorporated into the Org mode buffer and how the call line is
+ exported. For example, ~:results html~ will insert the results of the
+ call line evaluation in the Org buffer, wrapped in a ~BEGIN_HTML:~
+ block.
+
+
+For more examples of passing header arguments to ~#+CALL:~ lines see
+[[Header arguments in function calls]].
+
+** Library of Babel
+ :PROPERTIES:
+ :DESCRIPTION: Use and contribute to a source code library
+ :END:
+#+cindex: babel, library of
+#+cindex: source code, library
+#+cindex: code block, library
+
+The ``Library of Babel'' consists of code blocks that can be called
+from any Org mode file. Code blocks defined in the ``Library of
+Babel'' can be called remotely as if they were in the current Org mode
+buffer (see [[Evaluating code blocks]] for information on the syntax of
+remote code block evaluation).
+
+
+The central repository of code blocks in the ``Library of Babel'' is
+housed in an Org mode file located in the {{{samp(contrib)}}}
+directory of Org mode.
+
+Users can add code blocks they believe to be generally useful to their
+``Library of Babel.'' The code blocks can be stored in any Org mode
+file and then loaded into the library with ~org-babel-lob-ingest~.
+
+#+kindex: C-c C-v i
+
+Code blocks located in any Org mode file can be loaded into the
+``Library of Babel'' with the ~org-babel-lob-ingest~ function, bound
+to {{{kbd(C-c C-v i)}}}.
+
+** Languages
+ :PROPERTIES:
+ :DESCRIPTION: Supported code block languages
+ :END:
+#+cindex: babel, languages
+#+cindex: source code, languages
+#+cindex: code block, languages
+
+Code blocks in the following languages are supported.
+
+#+attr_texinfo: :columns 0.24 0.24 0.04 0.24 0.24
+| Language | Identifier | | Language | Identifier |
+|------------+--------------+---+----------------+--------------|
+| Asymptote | asymptote | | Awk | awk |
+| Emacs Calc | calc | | C | C |
+| C++ | C++ | | Clojure | clojure |
+| CSS | css | | ditaa | ditaa |
+| Graphviz | dot | | Emacs Lisp | emacs-lisp |
+| gnuplot | gnuplot | | Haskell | haskell |
+| Java | java | | | |
+| Javascript | js | | LaTeX | latex |
+| Ledger | ledger | | Lisp | lisp |
+| Lilypond | lilypond | | MATLAB | matlab |
+| Mscgen | mscgen | | Objective Caml | ocaml |
+| Octave | octave | | Org mode | org |
+| Oz | oz | | Perl | perl |
+| Plantuml | plantuml | | Python | python |
+| R | R | | Ruby | ruby |
+| Sass | sass | | Scheme | scheme |
+| GNU Screen | screen | | shell | sh |
+| SQL | sql | | SQLite | sqlite |
+
+
+Language-specific documentation is available for some languages. If
+available, it can be found at
+[[http://orgmode.org/worg/org-contrib/babel/languages.html]].
+
+The variable ~org-babel-load-languages~ controls which languages are
+enabled for evaluation (by default only ~emacs-lisp~ is enabled). This
+variable can be set using the customization interface or by adding
+code like the following example, disables ~emacs-lisp~ evaluation and
+enables evaluation of ~R~ code blocks, to your emacs configuration:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((emacs-lisp . nil)
+ (R . t)))
+#+end_src
+
+It is also possible to enable support for a language by loading the
+related elisp file with ~require~.
+
+{{{noindent}}} The following example adds support for evaluating
+~clojure~ code blocks:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(require 'ob-clojure)
+#+end_src
+
+** Header arguments
+ :PROPERTIES:
+ :DESCRIPTION: Configure code block functionality
+ :END:
+#+cindex: code block, header arguments
+#+cindex: source code, block header arguments
+
+Code block functionality can be configured with header arguments. This
+section provides an overview of the use of header arguments, and then
+describes each header argument in detail.
+
+*** Using header arguments
+ :PROPERTIES:
+ :DESCRIPTION: Different ways to set header arguments
+ :END:
+
+The values of header arguments can be set in six different ways, each
+more specific (and having higher priority) than the last.
+
+**** System-wide header arguments
+ :PROPERTIES:
+ :DESCRIPTION: Set global default values
+ :END:
+#+vindex: org-babel-default-header-args
+
+System-wide values of header arguments can be specified by customizing
+the ~org-babel-default-header-args~ variable:
+
+#+begin_example
+ :session => "none"
+ :results => "replace"
+ :exports => "code"
+ :cache => "no"
+ :noweb => "no"
+#+end_example
+
+# #+begin_example
+# org-babel-default-header-args is a variable defined in `org-babel.el'.
+# Its value is
+# ((:session . "none")
+# (:results . "replace")
+# (:exports . "code")
+# (:cache . "no")
+# (:noweb . "no"))
+
+
+# Documentation:
+# Default arguments to use when evaluating a code block.
+# #+end_example
+
+For example, the following code could be used to set the default
+value of ~:noweb~ header arguments to ~yes~. This would have the
+effect of expanding ~:noweb~ references by default when evaluating
+source code blocks.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+ (setq org-babel-default-header-args
+ (cons '(:noweb . "yes")
+ (assq-delete-all :noweb org-babel-default-header-args)))
+#+end_src
+
+**** Language-specific header arguments
+ :PROPERTIES:
+ :DESCRIPTION: Set default values by language
+ :END:
+
+Each language can define its own set of default header arguments. See
+the language-specific documentation available online at
+[[http://orgmode.org/worg/org-contrib/babel]].
+
+**** Buffer-wide header arguments
+ :PROPERTIES:
+ :DESCRIPTION: Set default values for a specific buffer
+ :END:
+
+Buffer-wide header arguments may be specified as properties through
+the use of ~#+PROPERTY:~ lines placed anywhere in an Org mode file
+(see [[Property syntax]]).
+
+For example the following would set ~session~ to ~*R*~, and ~results~
+to ~silent~ for every code block in the buffer, ensuring that all
+execution took place in the same session, and no results would be
+inserted into the buffer.
+
+#+begin_example
+ ,#+PROPERTY: session *R*
+ ,#+PROPERTY: results silent
+#+end_example
+
+**** Header arguments in Org mode properties
+ :PROPERTIES:
+ :DESCRIPTION: Set default values for a buffer or heading
+ :END:
+
+Header arguments are also read from Org mode properties (see [[Property
+syntax]]), which can be set on a buffer-wide or per-heading basis. An
+example of setting a header argument for all code blocks in a buffer
+is as follows:
+
+#+begin_example
+ ,#+PROPERTY: tangle yes
+#+end_example
+
+#+vindex: org-use-property-inheritance
+
+When properties are used to set default header arguments, they are
+looked up with inheritance, regardless of the value of
+~org-use-property-inheritance~. In the following example the value of
+the ~:cache~ header argument will default to ~yes~ in all code blocks
+in the subtree rooted at the following heading:
+
+#+begin_example
+ ,* outline header
+ ,:PROPERTIES:
+ ,:cache: yes
+ ,:END:
+#+end_example
+
+#+kindex: C-c C-x p
+#+vindex: org-babel-default-header-args
+
+Properties defined in this way override the properties set in
+~org-babel-default-header-args~. It is convenient to use the
+~org-set-property~ function bound to {{{kbd(C-c C-x p)}}} to set
+properties in Org mode documents.
+
+**** Code block specific header arguments
+ :PROPERTIES:
+ :DESCRIPTION: The most common way to set values
+ :END:
+
+The most common way to assign values to header arguments is at the
+code block level. This can be done by listing a sequence of header
+arguments and their values as part of the ~#+BEGIN_SRC~ line.
+Properties set in this way override both the values of
+~org-babel-default-header-args~ and header arguments specified as
+properties. In the following example, the ~:results~ header argument
+is set to ~silent~, meaning the results of execution will not be
+inserted in the buffer, and the ~:exports~ header argument is set to
+~code~, meaning only the body of the code block will be preserved on
+export to HTML or LaTeX.
+
+#+begin_example
+ #+NAME: factorial
+ #+BEGIN_SRC haskell :results silent :exports code :var n=0
+ fac 0 = 1
+ fac n = n * fac (n-1)
+ #+END_SRC
+#+end_example
+
+Similarly, it is possible to set header arguments for inline code blocks:
+
+#+begin_example
+ src_haskell[:exports both]@{fac 5@}
+#+end_example
+
+Code block header arguments can span multiple lines using ~#+HEADER:~
+or ~#+HEADERS:~ lines preceding a code block or nested between the
+~#+NAME:~ line and the ~#+BEGIN_SRC~ line of a named code block.
+
+#+cindex: #+HEADER:
+#+cindex: #+HEADERS:
+
+This is an example of multi-line header arguments on an un-named code
+block:
+
+#+begin_example
+ ,#+HEADERS: :var data1=1
+ ,#+BEGIN_SRC emacs-lisp :var data2=2
+ (message "data1:%S, data2:%S" data1 data2)
+ ,#+END_SRC
+
+ ,#+RESULTS:
+ : data1:1, data2:2
+#+end_example
+
+This is an example of multi-line header arguments on a named code block:
+
+#+begin_example
+ ,#+NAME: named-block
+ ,#+HEADER: :var data=2
+ ,#+BEGIN_SRC emacs-lisp
+ (message "data:%S" data)
+ ,#+END_SRC
+
+ ,#+RESULTS: named-block
+ : data:2
+#+end_example
+
+**** Header arguments in function calls
+ :PROPERTIES:
+ :DESCRIPTION: The most specific level
+ :END:
+
+At the most specific level, header arguments for ``Library of Babel''
+or ~#+CALL:~ lines can be set as shown in the two examples below. For
+more information on the structure of ~#+CALL:~ lines see [[Evaluating
+code blocks]].
+
+The following example will apply the ~:exports results~ header
+argument to the evaluation of the ~#+CALL:~ line:
+
+#+begin_example
+ ,#+CALL: factorial(n=5) :exports results
+#+end_example
+
+The following example will apply the ~:session special~ header
+argument to the evaluation of the ~factorial~ code block:
+
+#+begin_example
+ ,#+CALL: factorial[:session special](n=5)
+#+end_example
+
+*** Specific header arguments
+ :PROPERTIES:
+ :DESCRIPTION: List of header arguments
+ :END:
+Header arguments consist of an initial colon followed by the name of
+the argument in lowercase letters. Additional header arguments are
+defined on a language-specific basis, see [[Languages]].
+
+The following header arguments are defined:
+
+**** var
+ :PROPERTIES:
+ :DESCRIPTION: Pass arguments to code blocks
+ :END:
+The ~:var~ header argument is used to pass arguments to code blocks.
+The specifics of how arguments are included in a code block vary by
+language; these are addressed in the language-specific documentation.
+However, the syntax used to specify arguments is the same across all
+languages. In every case, variables require a default value when they
+are declared.
+
+The values passed to arguments can either be literal values,
+references, or Emacs Lisp code (see [[Emacs Lisp evaluation of
+variables]]). References include anything in the Org mode file that
+takes a ~#+NAME:~, ~#+TBLNAME:~, or ~#+RESULTS:~ line. This includes
+tables, lists, ~#+BEGIN_EXAMPLE~ blocks, other code blocks, and the
+results of other code blocks.
+
+Argument values can be indexed in a manner similar to arrays (see
+[[Indexable variable values]]).
+
+The following syntax is used to pass arguments to code blocks using the
+~:var~ header argument:
+
+#+begin_example
+ :var name=assign
+#+end_example
+
+The argument, ~assign~, can either be a literal value, such as a
+string {{{samp("string")}}} or a number {{{samp(9)}}}, or a reference
+to a table, a list, a literal example, another code block (with or
+without arguments), or the results of evaluating another code block.
+
+Here are examples of passing values by reference:
+
+#+attr_texinfo: :table-type table :indic @asis
+- a table named with either ~#+NAME:~ or ~#+TBLNAME:~ ::
+
+ #+begin_example
+ #+TBLNAME: example-table
+ | 1 |
+ | 2 |
+ | 3 |
+ | 4 |
+
+ #+NAME: table-length
+ #+BEGIN_SRC emacs-lisp :var table=example-table
+ (length table)
+ #+END_SRC
+
+ #+RESULTS: table-length
+ : 4
+ #+end_example
+
+- a simple list named with ~#+NAME:~ ::
+
+ #+begin_example
+ #+NAME: example-list
+ - simple
+ - not
+ - nested
+ - list
+
+ #+BEGIN_SRC emacs-lisp :var x=example-list
+ (print x)
+ #+END_SRC
+
+ #+RESULTS:
+ | simple | list |
+ #+end_example
+
+ Note that nesting is not carried through to the source code block.
+
+- a named code block without arguments, optionally followed by parentheses ::
+
+ #+begin_example
+ #+BEGIN_SRC emacs-lisp :var length=table-length()
+ (* 2 length)
+ #+END_SRC
+
+ #+RESULTS:
+ : 8
+ #+end_example
+
+- a named code block with arguments ::
+
+ #+begin_example
+ #+NAME: double
+ #+BEGIN_SRC emacs-lisp :var input=8
+ (* 2 input)
+ #+END_SRC
+
+ #+RESULTS: double
+ : 16
+
+ #+NAME: squared
+ #+BEGIN_SRC emacs-lisp :var input=double(input=1)
+ (* input input)
+ #+END_SRC
+
+ #+RESULTS: squared
+ : 4
+ #+end_example
+
+- a literal example block ::
+
+ #+begin_example
+ ,#+NAME: literal-example
+ ,#+BEGIN_EXAMPLE
+ A literal example
+ on two lines
+ ,#+END_EXAMPLE
+
+ ,#+NAME: read-literal-example
+ ,#+BEGIN_SRC emacs-lisp :var x=literal-example
+ (concatenate 'string x " for you.")
+ ,#+END_SRC
+
+ ,#+RESULTS: read-literal-example
+ : A literal example
+ : on two lines for you.
+ #+end_example
+
+# ***** Alternate argument syntax
+<<Alternate argument syntax>>
+
+It is also possible to specify arguments in a potentially more natural
+way using the ~#+NAME:~ line of a code block. As in the following
+example, arguments can be packed inside of parentheses, separated by
+commas, following the source name.
+
+#+begin_example
+ ,#+NAME: double(input=0, x=2)
+ ,#+BEGIN_SRC emacs-lisp
+ (* 2 (+ input x))
+ ,#+END_SRC
+#+end_example
+
+# ***** Indexable variable values
+<<Indexable variable values>>
+
+It is possible to reference portions of variable values by
+/indexing/ into the variables. Indexes are 0 based with negative
+values counting back from the end. If an index is separated by commas
+then each subsequent section will index into the next deepest nesting
+or dimension of the value. Note that this indexing occurs /before/
+other table related header arguments like ~:hlines~, ~:colnames~, and
+~:rownames~ are applied. The following example assigns the last cell
+of the first row the table ~example-table~ to the variable ~data~:
+
+#+begin_example
+ ,#+NAME: example-table
+ | 1 | a |
+ | 2 | b |
+ | 3 | c |
+ | 4 | d |
+
+ ,#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
+ data
+ ,#+END_SRC
+
+ ,#+RESULTS:
+ : a
+#+end_example
+
+Ranges of variable values can be referenced using two integers
+separated by a ~:~, in which case the entire inclusive range is
+referenced. The following example assigns the middle three rows of
+~example-table~ to ~data~.
+
+#+begin_example
+ #+NAME: example-table
+ | 1 | a |
+ | 2 | b |
+ | 3 | c |
+ | 4 | d |
+ | 5 | 3 |
+
+ #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
+ data
+ #+END_SRC
+
+ #+RESULTS:
+ | 2 | b |
+ | 3 | c |
+ | 4 | d |
+#+end_example
+
+Additionally, an empty index, or the single character ~*~, are both
+interpreted to mean the entire range and as such are equivalent to
+~0:-1~, as shown in the following example in which the entire first
+column is referenced:
+
+#+begin_example
+ #+NAME: example-table
+ | 1 | a |
+ | 2 | b |
+ | 3 | c |
+ | 4 | d |
+
+ #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
+ data
+ #+END_SRC
+
+ #+RESULTS:
+ | 1 | 2 | 3 | 4 |
+#+end_example
+
+It is possible to index into the results of code blocks as well as
+tables. Any number of dimensions can be indexed. Dimensions are
+separated from one another by commas, as shown in the following
+example:
+
+#+begin_example
+ #+NAME: 3D
+ #+BEGIN_SRC emacs-lisp
+ '(((1 2 3) (4 5 6) (7 8 9))
+ ((10 11 12) (13 14 15) (16 17 18))
+ ((19 20 21) (22 23 24) (25 26 27)))
+ #+END_SRC
+
+ #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
+ data
+ #+END_SRC
+
+ #+RESULTS:
+ | 11 | 14 | 17 |
+#+end_example
+
+# ***** Emacs Lisp evaluation of variables
+<<Emacs Lisp evaluation of variables>>
+
+Emacs lisp code can be used to initialize variable values. When a
+variable value starts with ~(~, ~[~, ~'~ or ~`~ it will be evaluated
+as Emacs Lisp and the result of the evaluation will be assigned as the
+variable value. The following example demonstrates use of this
+evaluation to reliably pass the file-name of the Org mode buffer to a
+code block:[fn:150]
+
+#+begin_example
+ #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
+ wc -w $filename
+ #+END_SRC
+#+end_example
+
+Note that values read from tables and lists will not be evaluated as
+Emacs Lisp, as shown in the following example, which contains a Lisp
+list as the sole table element:
+
+#+begin_example
+ #+NAME: table
+ | (a b c) |
+
+ #+HEADERS: :var data=table[0,0]
+ #+BEGIN_SRC perl
+ $data
+ #+END_SRC
+
+ #+RESULTS:
+ : (a b c)
+#+end_example
+
+**** results
+ :PROPERTIES:
+ :DESCRIPTION: Specify the type of results and how they will be collected and handled
+ :END:
+There are three classes of ~:results~ header argument. Only one option
+per class may be supplied per code block.
+
+#+attr_texinfo: :table-type table :indic @asis
+- Collection ::
+
+ These header arguments specify how the results should be collected
+ from the code block.
+
+- Type ::
+
+ These header arguments specify what type of result the code block will
+ return---which has implications for how they will be inserted into the
+ Org mode buffer.
+
+- Handling ::
+
+ These header arguments specify how the results of evaluating the code
+ block should be handled.
+
+# ***** Collection
+<<Collection>>
+
+The following ~:results~ options are mutually exclusive, and specify
+how the results should be collected from the code block.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~value~ ::
+
+ This is the default. The result is the value of the last statement in
+ the code block. This header argument places the evaluation in
+ functional mode. Note that in some languages, e.g., Python, use of
+ this result type requires that a ~return~ statement be included in the
+ body of the source code block.
+
+- ~output~ ::
+
+ The result is the collection of everything printed to STDOUT during
+ the execution of the code block. This header argument places the
+ evaluation in scripting mode.
+
+# ***** Type
+<<Type>>
+
+The following ~:results~ options are mutually exclusive and specify
+what type of results the code block will return. By default, results
+are inserted as either a table or scalar depending on their value.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~table~, ~vector~ ::
+
+ The results should be interpreted as an Org mode table. If a single
+ value is returned, it will be converted into a table with one row and
+ one column. E.g., ~:results value table~.
+
+- ~scalar~, ~verbatim~ ::
+
+ The results should be interpreted literally---they will not be
+ converted into a table. The results will be inserted into the Org mode
+ buffer as quoted text. E.g., ~:results value verbatim~.
+
+- ~list~ ::
+
+ The results should be interpreted as an Org mode list. If a single
+ scalar value is returned it will be converted into a list with only
+ one element.
+
+- ~file~ ::
+
+ The results will be interpreted as the path to a file, and will be
+ inserted into the Org mode buffer as a file link. E.g., ~:results
+ value file~.
+
+- ~raw~ ::
+
+ The results are interpreted as raw Org mode code and are inserted
+ directly into the buffer. If the results look like a table they will
+ be aligned as such by Org mode. E.g., ~:results value raw~.
+
+- ~org~ ::
+
+ The results are will be enclosed in a ~BEGIN_SRC org~ block. They are
+ not comma-escaped by default but they will be if you hit
+ {{{kbd(TAB)}}} in the block and/or if you export the file. E.g.,
+ ~:results value org~.
+
+- ~html~ ::
+
+ Results are assumed to be HTML and will be enclosed in a ~BEGIN_HTML~
+ block. E.g., ~:results value html~.
+
+- ~latex~ ::
+
+ Results assumed to be LaTeX and are enclosed in a ~BEGIN_LaTeX~
+ block. E.g., ~:results value latex~.
+
+- ~code~ ::
+
+ Result are assumed to be parsable code and are enclosed in a code
+ block. E.g., ~:results value code~.
+
+- ~pp~ ::
+
+ The result is converted to pretty-printed code and is enclosed in a
+ code block. This option currently supports Emacs Lisp, Python, and
+ Ruby. E.g., ~:results value pp~.
+
+- ~drawer~ ::
+
+ The result is wrapped in a RESULTS drawer. This can be useful for
+ inserting ~raw~ or ~org~ syntax results in such a way that their
+ extent is known and they can be automatically removed or replaced.
+
+# ***** Handling
+<<Handling>>
+The following ~:results~ options indicate what happens with the
+results once they are collected.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~replace~ ::
+
+ The default value. Any existing results will be removed, and the new
+ results will be inserted into the Org mode buffer in their place.
+ E.g., ~:results output replace~.
+
+- ~append~ ::
+
+ If there are pre-existing results of the code block then the new
+ results will be appended to the existing results. Otherwise the new
+ results will be inserted as with ~replace~.
+
+- ~prepend~ ::
+
+ If there are pre-existing results of the code block then the new
+ results will be prepended to the existing results. Otherwise the new
+ results will be inserted as with ~replace~.
+
+- ~silent~ ::
+
+ The results will be echoed in the minibuffer but will not be inserted
+ into the Org mode buffer. E.g., ~:results output silent~.
+
+**** file
+ :PROPERTIES:
+ :DESCRIPTION: Specify a path for file output
+ :END:
+
+The header argument ~:file~ is used to specify an external file in
+which to save code block results. After code block evaluation an Org
+mode style ~[[file:]]~ link (see [[Link format]]) to the file will be inserted
+into the Org mode buffer. Some languages including R, gnuplot, dot,
+and ditaa provide special handling of the ~:file~ header argument,
+automatically wrapping the code block body in the boilerplate code
+required to save output to the specified file. This is often useful
+for saving graphical output of a code block to the specified file.
+
+The argument to ~:file~ should be either a string specifying the path
+to a file, or a list of two strings in which case the first element of
+the list should be the path to a file and the second a description for
+the link.
+
+**** file-desc
+ :PROPERTIES:
+ :DESCRIPTION: Specify a description for file results
+ :END:
+
+The value of the ~:file-desc~ header argument is used to provide a
+description for file code block results which are inserted as Org mode
+links (see [[Link format]]). If the ~:file-desc~ header argument is given
+with no value the link path will be placed in both the ``link'' and
+the ``description'' portion of the Org mode link.
+
+**** dir
+ :PROPERTIES:
+ :DESCRIPTION: Specify the default (possibly remote) directory for code block execution
+ :TITLE: ~:dir~ and remote execution
+ :END:
+
+While the ~:file~ header argument can be used to specify the path to
+the output file, ~:dir~ specifies the default directory during code
+block execution. If it is absent, then the directory associated with
+the current buffer is used. In other words, supplying ~:dir path~
+temporarily has the same effect as changing the current directory with
+{{{kbd(M-x cd path)}}}, and then not supplying ~:dir~. Under the
+surface, ~:dir~ simply sets the value of the Emacs variable
+~default-directory~.
+
+When using ~:dir~, you should supply a relative path for file output
+(e.g., ~:file myfile.jpg~ or ~:file results/myfile.jpg~) in which
+case that path will be interpreted relative to the default directory.
+
+In other words, if you want your plot to go into a folder called
+{{{file(Work)}}} in your home directory, you could use a code block
+like the following example:
+
+#+begin_example
+ #+BEGIN_SRC R :file myplot.png :dir ~/Work
+ matplot(matrix(rnorm(100), 10), type="l")
+ #+END_SRC
+#+end_example
+
+# ***** Remote execution
+<<Remote execution>>
+
+A directory on a remote machine can be specified using tramp file
+syntax, in which case the code will be evaluated on the remote
+machine. An example is:
+
+#+begin_example
+ #+BEGIN_SRC R :file plot.png :dir /dand@yakuba.princeton.edu:
+ plot(1:10, main=system("hostname", intern=TRUE))
+ #+END_SRC
+#+end_example
+
+Text results will be returned to the local Org mode buffer as usual,
+and file output will be created on the remote machine with relative
+paths interpreted relative to the remote directory. An Org mode link
+to the remote file will be created.
+
+So, in the above example a plot will be created on the remote machine,
+and a link of the following form will be inserted in the org buffer:
+
+#+begin_example
+ [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
+#+end_example
+
+Most of this functionality follows immediately from the fact that
+~:dir~ sets the value of the Emacs variable ~default-directory~,
+thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23
+may need to install tramp separately in order for these features to
+work correctly.
+
+# ***** Further points
+<<Further points>>
+Please be aware of these further points:
+
+- If ~:dir~ is used in conjunction with ~:session~, although it will
+ determine the starting directory for a new session as expected, no
+ attempt is currently made to alter the directory associated with an
+ existing session.
+
+- ~:dir~ should typically not be used to create files during export
+ with ~:exports results~ or ~:exports both~. The reason is that, in
+ order to retain portability of exported material between machines,
+ during export links inserted into the buffer will /not/ be expanded
+ against ~default directory~. Therefore, if ~default-directory~ is
+ altered using ~:dir~, it is probable that the file will be created
+ in a location to which the link does not point.
+
+**** exports
+ :PROPERTIES:
+ :DESCRIPTION: Export code and/or results
+ :END:
+The ~:exports~ header argument specifies what should be included in HTML
+or LaTeX exports of the Org mode file.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~code~ ::
+
+ The default. The body of code is included into the exported file.
+ E.g., ~:exports code~.
+
+- ~results~ ::
+
+ The result of evaluating the code is included in the exported file.
+ E.g., ~:exports results~.
+
+- ~both~ ::
+
+ Both the code and results are included in the exported file. E.g.,
+ ~:exports both~.
+
+- ~none~ ::
+
+ Nothing is included in the exported file. E.g., ~:exports none~.
+
+**** tangle
+ :PROPERTIES:
+ :DESCRIPTION: Toggle tangling and specify file name
+ :END:
+
+The ~:tangle~ header argument specifies whether or not the code
+block should be included in tangled extraction of source code files.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~tangle~ ::
+
+ The code block is exported to a source code file named after the full
+ path (including the directory) and file name (w/o extension) of the
+ Org mode file. E.g., ~:tangle yes~.
+
+- ~no~ ::
+
+ The default. The code block is not exported to a source code file.
+ E.g., ~:tangle no~.
+
+- other ::
+
+ Any other string passed to the ~:tangle~ header argument is
+ interpreted as a path (directory and file name relative to the
+ directory of the Org mode file) to which the block will be exported,
+ e.g., ~:tangle path~.
+
+**** mkdirp
+:PROPERTIES:
+:DESCRIPTION: Toggle creation of parent directories of target files during tangling
+:END:
+
+The ~:mkdirp~ header argument can be used to create parent directories
+of tangled files when missing. This can be set to ~yes~ to enable
+directory creation or to ~no~ to inhibit directory creation.
+
+**** comments
+:PROPERTIES:
+:DESCRIPTION: Toggle insertion of comments in tangled code files
+:END:
+
+By default code blocks are tangled to source-code files without any
+insertion of comments beyond those which may already exist in the body
+of the code block. The ~:comments~ header argument can be set as
+follows to control the insertion of extra comments into the tangled
+code file.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~no~ ::
+
+ The default. No extra comments are inserted during tangling.
+
+- ~link~ ::
+
+ The code block is wrapped in comments which contain pointers back to
+ the original Org file from which the code was tangled.
+
+- ~yes~ ::
+
+ A synonym for ``link'' to maintain backwards compatibility.
+
+- ~org~ ::
+
+ Include text from the Org mode file as a comment.
+
+ The text is picked from the leading context of the tangled code and is
+ limited by the nearest headline or source block as the case may be.
+
+- ~both~ ::
+
+ Turns on both the ``link'' and ``org'' comment options.
+
+- ~noweb~ ::
+
+ Turns on the ``link'' comment option, and additionally wraps expanded
+ noweb references in the code block body in link comments.
+
+**** padline
+:PROPERTIES:
+:DESCRIPTION: Control insertion of padding lines in tangle code files
+:END:
+
+Control in insertion of padding lines around code block bodies in tangled
+code files. The default value is ~yes~ which results in insertion of
+newlines before and after each tangled code block. The following arguments
+are accepted:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~yes~ ::
+
+ Insert newlines before and after each code block body in tangled code
+ files.
+
+- ~no~ ::
+
+ Do not insert any newline padding in tangled output.
+
+**** no-expand
+:PROPERTIES:
+:DESCRIPTION: Turn off variable assignment and noweb expansion during tangling
+:END:
+
+By default, code blocks are expanded with ~org-babel-expand-src-block~
+during tangling. This has the effect of assigning values to variables
+specified with ~:var~ (see [[var]]), and of replacing ``noweb'' references
+(see [[Noweb reference syntax]]) with their targets. The ~:no-expand~
+header argument can be used to turn off this behavior.
+
+**** session
+:PROPERTIES:
+:DESCRIPTION: Preserve state of code evaluation
+:END:
+
+The ~:session~ header argument starts a session for an interpreted
+language where state is preserved.
+
+By default, a session is not started.
+
+A string passed to the ~:session~ header argument will give the
+session a name. This makes it possible to run concurrent sessions for
+each interpreted language.
+
+**** noweb
+:PROPERTIES:
+:DESCRIPTION: Toggle expansion of noweb references
+:END:
+
+The ~:noweb~ header argument controls expansion of ``noweb'' syntax
+references (see [[Noweb reference syntax]]) when the code block is
+evaluated, tangled, or exported. The ~:noweb~ header argument can have
+one of the five values: ~no~, ~yes~, ~tangle~, ~no-export~, or
+~strip-export~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~no~ ::
+
+ The default. ``Noweb'' syntax references in the body of the code block
+ will not be expanded before the code block is evaluated, tangled or
+ exported.
+
+- ~yes~ ::
+
+ ``Noweb'' syntax references in the body of the code block will be
+ expanded before the code block is evaluated, tangled or exported.
+
+- ~tangle~ ::
+
+ ``Noweb'' syntax references in the body of the code block will be
+ expanded before the code block is tangled. However, ``noweb'' syntax
+ references will not be expanded when the code block is evaluated or
+ exported.
+
+- ~no-export~ ::
+
+ ``Noweb'' syntax references in the body of the code block will be
+ expanded before the block is evaluated or tangled. However, ``noweb''
+ syntax references will not be expanded when the code block is
+ exported.
+
+- ~strip-export~ ::
+
+ ``Noweb'' syntax references in the body of the code block will be
+ expanded before the block is evaluated or tangled. However, ``noweb''
+ syntax references will not be removed when the code block is exported.
+
+- ~eval~ ::
+
+ ``Noweb'' syntax references in the body of the code block will only be
+ expanded before the block is evaluated.
+
+# ***** Noweb prefix lines
+<<Noweb prefix lines>>
+
+Noweb insertions are placed behind the line prefix of the
+~<<reference>>~. Because the ~<<example>>~ noweb reference appears
+behind the SQL comment syntax in the following example, each line of
+the expanded noweb reference will be commented.
+
+This code block:
+
+#+begin_example
+ -- <<example>>
+#+end_example
+
+
+expands to:
+
+#+begin_example
+ -- this is the
+ -- multi-line body of example
+#+end_example
+
+Note that noweb replacement text that does not contain any newlines
+will not be inserted behind the line prefix, so it is always possible
+to use inline noweb references.
+
+**** noweb-ref
+:PROPERTIES:
+:DESCRIPTION: Specify block's noweb reference resolution target
+:END:
+
+When expanding ``noweb'' style references the bodies of all code block
+with /either/ a block name matching the reference name /or/ a
+~:noweb-ref~ header argument matching the reference name will be
+concatenated together to form the replacement text.
+
+By setting this header argument at the sub-tree or file level, simple code
+block concatenation may be achieved. For example, when tangling the
+following Org mode file, the bodies of code blocks will be concatenated into
+the resulting pure code file.[fn:151]
+
+#+begin_example
+ #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
+ <<fullest-disk>>
+ #+END_SRC
+ ,* the mount point of the fullest disk
+ :PROPERTIES:
+ :noweb-ref: fullest-disk
+ :END:
+
+ ,** query all mounted disks
+ #+BEGIN_SRC sh
+ df \
+ #+END_SRC
+
+ ,** strip the header row
+ #+BEGIN_SRC sh
+ |sed '1d' \
+ #+END_SRC
+
+ ,** sort by the percent full
+ #+BEGIN_SRC sh
+ |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
+ #+END_SRC
+
+ ,** extract the mount point
+ #+BEGIN_SRC sh
+ |awk '@{print $2@}'
+ #+END_SRC
+#+end_example
+
+The ~:noweb-sep~ (see [[noweb-sep]]) header argument holds the string used
+to separate accumulate noweb references like those above. By default a
+newline is used.
+
+**** noweb-sep
+:PROPERTIES:
+:DESCRIPTION: String used to separate noweb references
+:END:
+
+The ~:noweb-sep~ header argument holds the string used to separate
+accumulated noweb references (see [[noweb-ref]]). By default a newline is
+used.
+
+**** cache
+:PROPERTIES:
+:DESCRIPTION: Avoid re-evaluating unchanged code blocks
+:END:
+
+The ~:cache~ header argument controls the use of in-buffer caching of
+the results of evaluating code blocks. It can be used to avoid
+re-evaluating unchanged code blocks. Note that the ~:cache~ header
+argument will not attempt to cache results when the ~:session~ header
+argument is used, because the results of the code block execution may
+be stored in the session outside of the Org mode buffer. The ~:cache~
+header argument can have one of two values: ~yes~ or ~no~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~no~ ::
+
+ The default. No caching takes place, and the code block will be
+ evaluated every time it is called.
+
+- ~yes~ ::
+
+ Every time the code block is run a SHA1 hash of the code and arguments
+ passed to the block will be generated. This hash is packed into the
+ ~#+RESULTS:~ line and will be checked on subsequent executions of the
+ code block. If the code block has not changed since the last time it
+ was evaluated, it will not be re-evaluated.
+
+
+Code block caches notice if the value of a variable argument
+to the code block has changed. If this is the case, the cache is
+invalidated and the code block is re-run. In the following example,
+~caller~ will not be re-run unless the results of ~random~ have
+changed since it was last run.
+
+#+begin_example
+ #+NAME: random
+ #+BEGIN_SRC R :cache yes
+ runif(1)
+ #+END_SRC
+
+ #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
+ 0.4659510825295
+
+ #+NAME: caller
+ #+BEGIN_SRC emacs-lisp :var x=random :cache yes
+ x
+ #+END_SRC
+
+ #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
+ 0.254227238707244
+#+end_example
+
+**** sep
+:PROPERTIES:
+:DESCRIPTION: Delimiter for writing tabular results outside Org
+:END:
+#+kindex: C-c C-o
+
+The ~:sep~ header argument can be used to control the delimiter used
+when writing tabular results out to files external to Org mode. This
+is used either when opening tabular results of a code block by calling
+the ~org-open-at-point~ function bound to {{{kbd(C-c C-o)}}} on the
+code block, or when writing code block results to an external file
+(see [[file]]) header argument.
+
+By default, when ~:sep~ is not specified output tables are tab
+delimited.
+
+**** hlines
+:PROPERTIES:
+:DESCRIPTION: Handle horizontal lines in tables
+:END:
+
+Tables are frequently represented with one or more horizontal lines,
+or hlines. The ~:hlines~ argument to a code block accepts the values
+~yes~ or ~no~, with a default value of ~no~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~no~ ::
+
+ Strips horizontal lines from the input table. In most languages this
+ is the desired effect because an ~hline~ symbol is interpreted as an
+ unbound variable and raises an error. Setting ~:hlines no~ or relying
+ on the default value yields the following results.
+
+ #+begin_example
+ #+TBLNAME: many-cols
+ | a | b | c |
+ |---+---+---|
+ | d | e | f |
+ |---+---+---|
+ | g | h | i |
+
+ #+NAME: echo-table
+ #+BEGIN_SRC python :var tab=many-cols
+ return tab
+ #+END_SRC
+
+ #+RESULTS: echo-table
+ | a | b | c |
+ | d | e | f |
+ | g | h | i |
+ #+end_example
+
+- ~yes~ ::
+
+ Leaves hlines in the table. Setting ~:hlines yes~ has this effect.
+
+ #+begin_example
+ #+TBLNAME: many-cols
+ | a | b | c |
+ |---+---+---|
+ | d | e | f |
+ |---+---+---|
+ | g | h | i |
+
+ #+NAME: echo-table
+ #+BEGIN_SRC python :var tab=many-cols :hlines yes
+ return tab
+ #+END_SRC
+
+ #+RESULTS: echo-table
+ | a | b | c |
+ |---+---+---|
+ | d | e | f |
+ |---+---+---|
+ | g | h | i |
+ #+end_example
+
+**** colnames
+:PROPERTIES:
+:DESCRIPTION: Handle column names in tables
+:END:
+
+The ~:colnames~ header argument accepts the values ~yes~, ~no~, or
+~nil~ for unassigned. The default value is ~nil~. Note that the
+behavior of the ~:colnames~ header argument may differ across
+languages. For example Emacs Lisp code blocks ignore the ~:colnames~
+header argument entirely given the ease with which tables with column
+names may be handled directly in Emacs Lisp.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~nil~ ::
+
+ If an input table looks like it has column names (because its second
+ row is an hline), then the column names will be removed from the table
+ before processing, then reapplied to the results.
+
+ #+begin_example
+ #+TBLNAME: less-cols
+ | a |
+ |---|
+ | b |
+ | c |
+
+ #+NAME: echo-table-again
+ #+BEGIN_SRC python :var tab=less-cols
+ return [[val + '*' for val in row] for row in tab]
+ #+END_SRC
+
+ #+RESULTS: echo-table-again
+ | a |
+ |----|
+ | b* |
+ | c* |
+ #+end_example
+
+ Please note that column names are not removed before the table is
+ indexed using variable indexing. See [[Indexable variable values]].
+
+- ~no~ ::
+
+ No column name pre-processing takes place
+
+- ~yes~ ::
+
+ Column names are removed and reapplied as with ~nil~ even if the table
+ does not ``look like'' it has column names (i.e., the second row is
+ not an hline).
+
+**** rownames
+:PROPERTIES:
+:DESCRIPTION: Handle row names in tables
+:END:
+
+The ~:rownames~ header argument can take on the values ~yes~
+or ~no~, with a default value of ~no~.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~no~ ::
+
+ No row name pre-processing will take place.
+
+- ~yes~ ::
+
+ The first column of the table is removed from the table before
+ processing, and is then reapplied to the results.
+
+ #+begin_example
+ #+TBLNAME: with-rownames
+ | one | 1 | 2 | 3 | 4 | 5 |
+ | two | 6 | 7 | 8 | 9 | 10 |
+
+ #+NAME: echo-table-once-again
+ #+BEGIN_SRC python :var tab=with-rownames :rownames yes
+ return [[val + 10 for val in row] for row in tab]
+ #+END_SRC
+
+ #+RESULTS: echo-table-once-again
+ | one | 11 | 12 | 13 | 14 | 15 |
+ | two | 16 | 17 | 18 | 19 | 20 |
+ #+end_example
+
+ Please note that row names are not removed before the table is indexed
+ using variable indexing. See [[Indexable variable values]].
+
+**** shebang
+:PROPERTIES:
+:DESCRIPTION: Make tangles files executable
+:END:
+
+Setting the ~:shebang~ header argument to a string value (e.g.,
+{{{samp(:shebang "#!/bin/bash")}}}) causes the string to be inserted as the
+first line of any tangled file holding the code block, and the file
+permissions of the tangled file are set to make it executable.
+
+**** eval
+:PROPERTIES:
+:DESCRIPTION: Limit evaluation of specific code blocks
+:END:
+
+The ~:eval~ header argument can be used to limit the evaluation of
+specific code blocks. The ~:eval~ header argument can be useful for
+protecting against the evaluation of dangerous code blocks or to
+ensure that evaluation will require a query regardless of the value of
+the ~org-confirm-babel-evaluate~ variable. The possible values of
+~:eval~ and their effects are shown below.
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~never~ or ~no~ ::
+
+ The code block will not be evaluated under any circumstances.
+
+- ~query~ ::
+
+ Evaluation of the code block will require an affirmative answer to a
+ query.
+
+- ~never-export~ or ~no-export~ ::
+
+ The code block will not be evaluated during export but may still be
+ called interactively.
+
+- ~query-export~ ::
+
+ Evaluation of the code block during export will require an affirmative
+ answer to a query.
+
+
+If this header argument is not set then evaluation is determined by the value
+of the ~org-confirm-babel-evaluate~ variable (see [[Code evaluation
+security]]).
+
+**** wrap
+:PROPERTIES:
+:DESCRIPTION: Mark source block evaluation results
+:END:
+
+The ~:wrap~ header argument is used to mark the results of source
+block evaluation. The header argument can be passed a string that will
+be appended to ~#+BEGIN_~ and ~#+END_~, which will then be used to
+wrap the results. If no string is specified then the results will be
+wrapped in a ~#+BEGIN/END_RESULTS~ block.
+
+** Results of evaluation
+ :PROPERTIES:
+ :DESCRIPTION: How evaluation results are handled
+ :END:
+#+cindex: code block, results of evaluation
+#+cindex: source code, results of evaluation
+
+The way in which results are handled depends on whether a session is
+invoked, as well as on whether ~:results value~ or ~:results output~
+is used. The following table shows the table possibilities. For a full
+listing of the possible results header arguments, see [[results]].
+
+| | *Non-session* | *Session* |
+|-------------------+--------------------------+-------------------------------------|
+| ~:results value~ | value of last expression | value of last expression |
+| ~:results output~ | contents of STDOUT | concatenation of interpreter output |
+
+
+Please note that with ~:results value~, the result in both ~:session~
+and non-session is returned to Org mode as a table (a one- or
+two-dimensional vector of strings or numbers) when appropriate.
+
+*** Non-session
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:results value~ ::
+
+ This is the default. Internally, the value is obtained by wrapping the
+ code in a function definition in the external language, and evaluating
+ that function. Therefore, code should be written as if it were the
+ body of such a function. In particular, note that Python does not
+ automatically return a value from a function unless a ~return~
+ statement is present, and so a {{{samp(return)}}} statement will
+ usually be required in Python.
+
+ This is the only one of the four evaluation contexts in which the code
+ is automatically wrapped in a function definition.
+
+- ~:results output~ ::
+
+ The code is passed to the interpreter as an external process, and the
+ contents of the standard output stream are returned as text.[fn:152]
+
+*** Session
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:results value~ ::
+
+ The code is passed to an interpreter running as an interactive Emacs
+ inferior process. Only languages which provide tools for interactive
+ evaluation of code have session support, so some language (e.g., C and
+ ditaa) do not support the ~:session~ header argument, and in other
+ languages (e.g., Python and Haskell) which have limitations on the
+ code which may be entered into interactive sessions, those limitations
+ apply to the code in code blocks using the ~:session~ header argument
+ as well.
+
+ Unless the ~:results output~ option is supplied (see below) the result
+ returned is the result of the last evaluation performed by the
+ interpreter.[fn:153]
+
+- ~:results output~ ::
+
+ The code is passed to the interpreter running as an interactive Emacs
+ inferior process. The result returned is the concatenation of the
+ sequence of (text) output from the interactive interpreter. Notice
+ that this is not necessarily the same as what would be sent to
+ ~STDOUT~ if the same code were passed to a non-interactive interpreter
+ running as an external process. Compare the following two
+ examples:
+
+ #+begin_example
+ #+BEGIN_SRC python :results output
+ print "hello"
+ 2
+ print "bye"
+ #+END_SRC
+
+ #+RESULTS:
+ : hello
+ : bye
+ #+end_example
+
+ In non-session mode, the `2' is not printed and does not appear.
+
+ #+begin_example
+ #+BEGIN_SRC python :results output :session
+ print "hello"
+ 2
+ print "bye"
+ #+END_SRC
+
+ #+RESULTS:
+ : hello
+ : 2
+ : bye
+ #+end_example
+
+ But in ~:session~ mode, the interactive interpreter receives input `2'
+ and prints out its value, `2'. (Indeed, the other print statements are
+ unnecessary here).
+
+** Noweb reference syntax
+ :PROPERTIES:
+ :DESCRIPTION: Literate programming in Org mode
+ :END:
+#+cindex: code block, noweb reference
+#+cindex: syntax, noweb
+#+cindex: source code, noweb reference
+
+The ``noweb'' (see [[http://www.cs.tufts.edu/~nr/noweb/]]) Literate
+Programming system allows named blocks of code to be referenced using
+the familiar Noweb syntax:
+
+#+begin_example
+ <<code-block-name>>
+#+end_example
+
+When a code block is tangled or evaluated, whether or not ``noweb''
+references are expanded depends upon the value of the ~:noweb~ header
+argument. If ~:noweb yes~, then a Noweb reference is expanded before
+evaluation. If ~:noweb no~, the default, then the reference is not
+expanded before evaluation. See the [[noweb-ref]] header argument for a
+more flexible way to resolve noweb references.
+
+It is possible to include the /results/ of a code block rather than
+the body. This is done by appending parenthesis to the code block
+name, which may optionally contain arguments to the code block as
+shown below.
+
+#+begin_example
+ <<code-block-name(optional arguments)>>
+#+end_example
+
+Note that the default value, ~:noweb no~, was chosen to ensure that
+correct code is not broken in a language, such as Ruby, where
+~<<arg>>~ is a syntactically valid construct. If ~<<arg>>~ is not
+syntactically valid in languages that you use, then please consider
+setting the default value.
+
+If noweb tangling is slow in large Org mode files, consider
+setting the ~*org-babel-use-quick-and-dirty-noweb-expansion*~ variable
+to true. This will result in faster noweb reference resolution at the
+expense of not correctly resolving inherited values of the
+~:noweb-ref~ header argument.
+
+** Key bindings and useful functions
+ :PROPERTIES:
+ :DESCRIPTION: Work quickly with code blocks
+ :END:
+#+cindex: code block, key bindings
+
+Many common Org mode key sequences are re-bound depending on
+the context.
+
+Within a code block, the following key bindings
+are active:
+#+kindex: C-c C-c
+#+kindex: C-c C-o
+#+kindex: C-up
+#+kindex: M-down
+
+#+attr_texinfo: :columns 0.2 0.55
+| Key binding | Function |
+|-----------------------+-----------------------------------|
+| {{{kbd(C-c C-c)}}} | ~org-babel-execute-src-block~ |
+| {{{kbd(C-c C-o)}}} | ~org-babel-open-src-block-result~ |
+| {{{kbdkey(C-,up)}}} | ~org-babel-load-in-session~ |
+| {{{kbdkey(M-,down)}}} | ~org-babel-pop-to-session~ |
+
+
+In an Org mode buffer, the following key bindings are active:
+
+#+kindex: C-c C-v p
+#+kindex: C-c C-v C-p
+#+kindex: C-c C-v n
+#+kindex: C-c C-v C-n
+#+kindex: C-c C-v e
+#+kindex: C-c C-v C-e
+#+kindex: C-c C-v o
+#+kindex: C-c C-v C-o
+#+kindex: C-c C-v v
+#+kindex: C-c C-v C-v
+#+kindex: C-c C-v u
+#+kindex: C-c C-v C-u
+#+kindex: C-c C-v g
+#+kindex: C-c C-v C-g
+#+kindex: C-c C-v r
+#+kindex: C-c C-v C-r
+#+kindex: C-c C-v b
+#+kindex: C-c C-v C-b
+#+kindex: C-c C-v s
+#+kindex: C-c C-v C-s
+#+kindex: C-c C-v d
+#+kindex: C-c C-v C-d
+#+kindex: C-c C-v t
+#+kindex: C-c C-v C-t
+#+kindex: C-c C-v f
+#+kindex: C-c C-v C-f
+#+kindex: C-c C-v c
+#+kindex: C-c C-v C-c
+#+kindex: C-c C-v j
+#+kindex: C-c C-v C-j
+#+kindex: C-c C-v l
+#+kindex: C-c C-v C-l
+#+kindex: C-c C-v i
+#+kindex: C-c C-v C-i
+#+kindex: C-c C-v I
+#+kindex: C-c C-v C-I
+#+kindex: C-c C-v z
+#+kindex: C-c C-v C-z
+#+kindex: C-c C-v a
+#+kindex: C-c C-v C-a
+#+kindex: C-c C-v h
+#+kindex: C-c C-v C-h
+#+kindex: C-c C-v x
+#+kindex: C-c C-v C-x
+
+#+attr_texinfo: :columns 0.4 0.6
+| Key binding | Function |
+|------------------------------------------------+--------------------------------------------|
+| {{{kbd(C-c C-v p)}}} or {{{kbd(C-c C-v C-p)}}} | ~org-babel-previous-src-block~ |
+| {{{kbd(C-c C-v n)}}} or {{{kbd(C-c C-v C-n)}}} | ~org-babel-next-src-block~ |
+| {{{kbd(C-c C-v e)}}} or {{{kbd(C-c C-v C-e)}}} | ~org-babel-execute-maybe~ |
+| {{{kbd(C-c C-v o)}}} or {{{kbd(C-c C-v C-o)}}} | ~org-babel-open-src-block-result~ |
+| {{{kbd(C-c C-v v)}}} or {{{kbd(C-c C-v C-v)}}} | ~org-babel-expand-src-block~ |
+| {{{kbd(C-c C-v u)}}} or {{{kbd(C-c C-v C-u)}}} | ~org-babel-goto-src-block-head~ |
+| {{{kbd(C-c C-v g)}}} or {{{kbd(C-c C-v C-g)}}} | ~org-babel-goto-named-src-block~ |
+| {{{kbd(C-c C-v r)}}} or {{{kbd(C-c C-v C-r)}}} | ~org-babel-goto-named-result~ |
+| {{{kbd(C-c C-v b)}}} or {{{kbd(C-c C-v C-b)}}} | ~org-babel-execute-buffer~ |
+| {{{kbd(C-c C-v s)}}} or {{{kbd(C-c C-v C-s)}}} | ~org-babel-execute-subtree~ |
+| {{{kbd(C-c C-v d)}}} or {{{kbd(C-c C-v C-d)}}} | ~org-babel-demarcate-block~ |
+| {{{kbd(C-c C-v t)}}} or {{{kbd(C-c C-v C-t)}}} | ~org-babel-tangle~ |
+| {{{kbd(C-c C-v f)}}} or {{{kbd(C-c C-v C-f)}}} | ~org-babel-tangle-file~ |
+| {{{kbd(C-c C-v c)}}} or {{{kbd(C-c C-v C-c)}}} | ~org-babel-check-src-block~ |
+| {{{kbd(C-c C-v j)}}} or {{{kbd(C-c C-v C-j)}}} | ~org-babel-insert-header-arg~ |
+| {{{kbd(C-c C-v l)}}} or {{{kbd(C-c C-v C-l)}}} | ~org-babel-load-in-session~ |
+| {{{kbd(C-c C-v i)}}} or {{{kbd(C-c C-v C-i)}}} | ~org-babel-lob-ingest~ |
+| {{{kbd(C-c C-v I)}}} or {{{kbd(C-c C-v C-I)}}} | ~org-babel-view-src-block-info~ |
+| {{{kbd(C-c C-v z)}}} or {{{kbd(C-c C-v C-z)}}} | ~org-babel-switch-to-session-with-code~ |
+| {{{kbd(C-c C-v a)}}} or {{{kbd(C-c C-v C-a)}}} | ~org-babel-sha1-hash~ |
+| {{{kbd(C-c C-v h)}}} or {{{kbd(C-c C-v C-h)}}} | ~org-babel-describe-bindings~ |
+| {{{kbd(C-c C-v x)}}} or {{{kbd(C-c C-v C-x)}}} | ~org-babel-do-key-sequence-in-edit-buffer~ |
+
+
+# When possible these keybindings were extended to work when the control key is
+# kept pressed, resulting in the following additional keybindings.
+
+# @multitable @columnfractions 0.25 0.75
+# - {{{kbd(C-c C-v C-a)}}} @tab ~org-babel-sha1-hash~
+# - {{{kbd(C-c C-v C-b)}}} @tab ~org-babel-execute-buffer~
+# - {{{kbd(C-c C-v C-f)}}} @tab ~org-babel-tangle-file~
+# - {{{kbd(C-c C-v C-l)}}} @tab ~org-babel-lob-ingest~
+# - {{{kbd(C-c C-v C-p)}}} @tab ~org-babel-expand-src-block~
+# - {{{kbd(C-c C-v C-s)}}} @tab ~org-babel-execute-subtree~
+# - {{{kbd(C-c C-v C-t)}}} @tab ~org-babel-tangle~
+# - {{{kbd(C-c C-v C-z)}}} @tab ~org-babel-switch-to-session~
+# @end multitable
+
+** Batch execution
+ :PROPERTIES:
+ :DESCRIPTION: Call functions from the command line
+ :END:
+#+cindex: code block, batch execution
+#+cindex: source code, batch execution
+
+It is possible to call functions from the command line. This shell
+script calls ~org-babel-tangle~ on every one of its arguments.
+
+Be sure to adjust the paths to fit your system.
+
+#+begin_example
+ #!/bin/sh
+ # -*- mode: shell-script -*-
+ #
+ # tangle files with org-mode
+ #
+ DIR=`pwd`
+ FILES=""
+
+ # wrap each argument in the code required to call tangle on it
+ for i in $@; do
+ FILES="$FILES \"$i\""
+ done
+
+ emacs -Q --batch \
+ --eval "(progn
+ (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
+ (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
+ (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
+ (mapc (lambda (file)
+ (find-file (expand-file-name file \"$DIR\"))
+ (org-babel-tangle)
+ (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
+#+end_example
+
+* FIXME Miscellaneous
+ :PROPERTIES:
+ :DESCRIPTION: All the rest which did not fit elsewhere
+ :END:
+
+** FIXME Completion
+ :PROPERTIES:
+ :DESCRIPTION: M-TAB knows what you need
+ :END:
+#+cindex: completion, of @TeX{} symbols
+#+cindex: completion, of TODO keywords
+#+cindex: completion, of dictionary words
+#+cindex: completion, of option keywords
+#+cindex: completion, of tags
+#+cindex: completion, of property keys
+#+cindex: completion, of link abbreviations
+#+cindex: @TeX{} symbol completion
+#+cindex: TODO keywords completion
+#+cindex: dictionary word completion
+#+cindex: option keyword completion
+#+cindex: tag completion
+#+cindex: link abbreviations, completion of
+
+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~ or ~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(TAB)}}} key to complete text right there.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbdkey(M-,TAB)}}} ::
+ #+kindex: M-@key{TAB}
+
+ Complete word at point.
+
+ - At the beginning of a headline ::
+
+ Complete TODO keywords.
+
+ - After {{{kbd(XXX)}}} ::
+ # Should be \
+ Complete TeX symbols supported by the exporter.
+
+ - After {{{samp(*)}}} ::
+
+ Complete headlines in the current buffer so that they can be used in
+ search links like:
+
+ #+begin_example
+ [[*find this headline]]
+ #+end_example
+
+ - After {{{samp(:)}}} in a headline ::
+
+ Complete tags. The list of tags is taken from the variable
+ ~org-tag-alist~ (possibly set through the {{{samp(#+TAGS)}}} in-buffer
+ option, see [[Setting tags]]), or it is created dynamically from all tags
+ used in the current buffer.
+
+ - After {{{samp(:)}}} and not in a headline ::
+
+ Complete property keys. The list of keys is constructed dynamically
+ from all keys used in the current buffer.
+
+ - After {{{samp([)}}} ::
+
+ Complete link abbreviations (see [[Link abbreviations]]).
+
+ - After {{{samp(#+)}}} ::
+
+ Complete the special keywords like {{{samp(TYP_TODO)}}} or
+ {{{samp(OPTIONS)}}} which set file-specific options for Org mode. When
+ the option keyword is already complete, pressing {{{kbdkey(M-,TAB)}}}
+ again will insert example settings for this keyword.
+
+ - In the line after {{{samp(#+STARTUP: )}}} ::
+
+ Complete startup keywords, i.e., valid keys for this line.
+
+ - Elsewhere ::
+
+ Complete dictionary words using Ispell.
+
+** Easy templates
+ :PROPERTIES:
+ :DESCRIPTION: Quick insertion of structural elements
+ :END:
+#+cindex: template insertion
+#+cindex: insertion, of templates
+
+Org mode supports insertion of empty structural elements (like
+~#+BEGIN_SRC~ and ~#+END_SRC~ pairs) with just a few key strokes. This
+is achieved through a native template expansion mechanism. Note that
+Emacs has several other template mechanisms which could be used in a
+similar way, for example {{{file(yasnippet)}}}.
+
+To insert a structural element, type a {{{kbd(<)}}}, followed by a
+template selector and {{{kbdkey(,TAB)}}}. Completion takes effect only
+when the above keystrokes are typed on a line by itself.
+
+The following template selectors are currently supported:
+#+kindex: s
+#+kindex: e
+#+kindex: q
+#+kindex: v
+#+kindex: c
+#+kindex: l
+#+kindex: L
+#+kindex: h
+#+kindex: H
+#+kindex: a
+#+kindex: A
+#+kindex: i
+#+kindex: I
+
+#+attr_texinfo: :columns 0.2 0.7
+| Selector | Template |
+|--------------+---------------------------------------|
+| {{{kbd(a)}}} | ~#+BEGIN_ASCII~ ...~ #+END_ASCII~ |
+| {{{kbd(A)}}} | ~#+ASCII:~ |
+| {{{kbd(c)}}} | ~#+BEGIN_CENTER~ ... ~#+END_CENTER~ |
+| {{{kbd(e)}}} | ~#+BEGIN_EXAMPLE~ ... ~#+END_EXAMPLE~ |
+| {{{kbd(h)}}} | ~#+BEGIN_HTML~ ... ~#+END_HTML~ |
+| {{{kbd(H)}}} | ~#+HTML:~ |
+| {{{kbd(i)}}} | ~#+INDEX:~ |
+| {{{kbd(I)}}} | ~#+INCLUDE:~ |
+| {{{kbd(l)}}} | ~#+BEGIN_LaTeX~ ... ~#+END_LaTeX~ |
+| {{{kbd(L)}}} | ~#+LaTeX:~ |
+| {{{kbd(q)}}} | ~#+BEGIN_QUOTE~ ... ~#+END_QUOTE~ |
+| {{{kbd(s)}}} | ~#+BEGIN_SRC~ ... ~#+END_SRC~ |
+| {{{kbd(v)}}} | ~#+BEGIN_VERSE~ ... ~#+END_VERSE~ |
+
+For example, on an empty line, typing "<e" and then pressing TAB, will expand
+into a complete EXAMPLE template.
+
+You can install additional templates by customizing the variable
+~org-structure-template-alist~. See the docstring of the variable for
+additional details.
+
+** Speed keys
+ :PROPERTIES:
+ :DESCRIPTION: Electric commands at the beginning of a headline
+ :END:
+#+cindex: speed keys
+#+vindex: org-use-speed-commands
+#+vindex: org-speed-commands-user
+
+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
+{{{kbd(?)}}} with the cursor at the beginning of a headline.
+
+** Code evaluation security
+ :PROPERTIES:
+ :DESCRIPTION: Org mode files evaluate in-line code
+ :TITLE: Code evaluation and security issues
+ :END:
+
+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 that will only evaluate source 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 source 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:
+
+#+attr_texinfo: :table-type table :indic @asis
+- Source code blocks ::
+
+ Source code blocks can be evaluated during export, or when pressing
+ {{{kbd(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
+ that take off the default security brakes.
+
+ - ~org-confirm-babel-evaluate~ ::
+
+ When ~t~ (the default), the user is asked before every code block
+ evaluation. When ~nil~, the user is not asked. When set to a function,
+ it is called with two arguments (language and body of the code block)
+ and should return ~t~ to ask and ~nil~ not to ask.
+
+ For example, here is how to execute "ditaa" code (which is considered
+ safe) without asking:
+
+ #+header: :eval no
+ #+header: :exports code
+ #+begin_src emacs-lisp
+ (defun my-org-confirm-babel-evaluate (lang body)
+ (not (string= lang "ditaa"))) ; don't ask for ditaa
+ (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
+ #+end_src
+
+- Following ~shell~ and ~elisp~ links ::
+
+ Org has two link types that can directly evaluate code (see [[External
+ links]]). These links can be problematic because the code to be
+ evaluated is not visible.
+
+ - ~org-confirm-shell-link-function~ ::
+
+ Function to queries user about shell link execution.
+
+ - ~org-confirm-elisp-link-function~ ::
+
+ Function to query user for Emacs Lisp link execution.
+
+- Formulas in tables ::
+
+ Formulas in tables (see [[The spreadsheet]]) are code that is evaluated
+ either by the /calc/ interpreter, or by the /Emacs Lisp/ interpreter.
+
+** Customization
+ :PROPERTIES:
+ :DESCRIPTION: Adapting Org to your taste
+ :END:
+#+cindex: customization
+#+cindex: options, for customization
+#+cindex: variables, for customization
+
+There are more than 500 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 {{{kbd(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 [[In-buffer settings]]).
+
+** In-buffer settings
+ :PROPERTIES:
+ :DESCRIPTION: Overview of the #+KEYWORDS
+ :TITLE: Summary of in-buffer settings
+ :END:
+#+cindex: in-buffer settings
+#+cindex: special keywords
+
+Org mode uses special lines in the buffer to define settings on a
+per-file basis. These lines start with a {{{samp(#+)}}} 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 {{{kbd(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.
+
+#+vindex: org-archive-location
+#+attr_texinfo: :table-type table :indic @asis
+- {{{kbd(#+ARCHIVE: %s_done)}}} ::
+
+ This line sets the archive location for the agenda file. It applies to
+ all subsequent lines, until the next {{{samp(#+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~.
+
+- {{{kbd(#+CATEGORY:)}}} ::
+
+ This line sets the category for the agenda file. The category applies
+ to all subsequent lines, until the next {{{samp(#+CATEGORY)}}} line or
+ the end of the file. The first such line also applies to any entries
+ before it.
+
+- {{{kbd(#+COLUMNS: %25ITEM ...)}}} ::
+ #+cindex: property, COLUMNS
+
+ Set the default format for columns view. This format applies when
+ columns view is invoked in locations where no ~COLUMNS~ property
+ applies.
+
+- {{{kbd(#+CONSTANTS: name1=value1 ...)}}} ::
+ #+vindex: org-table-formula-constants
+ #+vindex: org-table-formula
+
+ Set file-local values for constants to be used in table formulas. This
+ line sets the local variable ~org-table-formula-constants-local~. The
+ global version of this variable is ~org-table-formula-constants~.
+
+- {{{kbd(#+FILETAGS: :tag1:tag2:tag3:)}}} ::
+
+ Set tags that can be inherited by any entry in the file, including the
+ top-level entries.
+
+- {{{kbd(#+DRAWERS: NAME1 ...)}}} ::
+ #+vindex: org-drawers
+
+ Set the file-local set of additional drawers. The corresponding global
+ variable is ~org-drawers~.
+
+- {{{kbd(#+LINK: linkword replace)}}} ::
+ #+vindex: org-link-abbrev-alist
+
+ These lines (several are allowed) specify link abbreviations. See
+ [[Link abbreviations]]. The corresponding variable is ~org-link-abbrev-alist~.
+
+- {{{kbd(#+PRIORITIES: highest lowest default)}}} ::
+ #+vindex: org-highest-priority
+ #+vindex: org-lowest-priority
+ #+vindex: org-default-priority
+
+ 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 than the lowest priority.
+
+- {{{kbd(#+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.
+
+- {{{kbd(#+SETUPFILE: file)}}} ::
+ #+cindex: #+SETUPFILE
+
+ 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 {{{kbd(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 {{{kbd(C-c ')}}}.
+
+- {{{kbd(#+STARTUP:)}}} ::
+ #+cindex: #+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~.
+
+ #+vindex: org-startup-folded
+ #+cindex: @code{overview}, STARTUP keyword
+ #+cindex: @code{content}, STARTUP keyword
+ #+cindex: @code{showall}, STARTUP keyword
+ #+cindex: @code{showeverything}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~overview~ :: top-level headlines only
+ - ~content~ :: all headlines
+ - ~showall~ :: no folding of any entries
+ - ~showeverything~ :: show even drawer contents
+
+ #+vindex: org-startup-indented
+ #+cindex: @code{indent}, STARTUP keyword
+ #+cindex: @code{noindent}, STARTUP keyword
+
+ Dynamic virtual indentation is controlled by the variable
+ ~org-startup-indented~.[fn:182]
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~indent~ :: start with ~org-indent-mode~ turned on
+ - ~noindent~ :: start with ~org-indent-mode~ turned off
+
+ #+vindex: org-startup-align-all-tables
+
+ 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~.
+
+ #+cindex: @code{align}, STARTUP keyword
+ #+cindex: @code{noalign}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~align~ :: align all tables
+ - ~noalign~ :: don't align tables on startup
+
+ #+vindex: org-startup-with-inline-images
+
+ When visiting a file, inline images can be automatically displayed.
+ The corresponding variable is ~org-startup-with-inline-images~, with a
+ default value ~nil~ to avoid delays when visiting a file.
+
+ #+cindex: @code{inlineimages}, STARTUP keyword
+ #+cindex: @code{noinlineimages}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~inlineimages~ show inline images
+ - ~noinlineimages~ don't show inline images on startup
+
+ #+vindex: org-log-done
+ #+vindex: org-log-note-clock-out
+ #+vindex: org-log-repeat
+
+ 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~).
+
+ #+cindex: @code{logdone}, STARTUP keyword
+ #+cindex: @code{lognotedone}, STARTUP keyword
+ #+cindex: @code{nologdone}, STARTUP keyword
+ #+cindex: @code{lognoteclock-out}, STARTUP keyword
+ #+cindex: @code{nolognoteclock-out}, STARTUP keyword
+ #+cindex: @code{logrepeat}, STARTUP keyword
+ #+cindex: @code{lognoterepeat}, STARTUP keyword
+ #+cindex: @code{nologrepeat}, STARTUP keyword
+ #+cindex: @code{logreschedule}, STARTUP keyword
+ #+cindex: @code{lognotereschedule}, STARTUP keyword
+ #+cindex: @code{nologreschedule}, STARTUP keyword
+ #+cindex: @code{logredeadline}, STARTUP keyword
+ #+cindex: @code{lognoteredeadline}, STARTUP keyword
+ #+cindex: @code{nologredeadline}, STARTUP keyword
+ #+cindex: @code{logrefile}, STARTUP keyword
+ #+cindex: @code{lognoterefile}, STARTUP keyword
+ #+cindex: @code{nologrefile}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~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
+
+ #+vindex: org-hide-leading-stars
+ #+vindex: org-odd-levels-only
+
+ 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~).
+
+ #+cindex: @code{hidestars}, STARTUP keyword
+ #+cindex: @code{showstars}, STARTUP keyword
+ #+cindex: @code{odd}, STARTUP keyword
+ #+cindex: @code{even}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~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
+
+ #+vindex: org-put-time-stamp-overlays
+ #+vindex: org-time-stamp-overlay-formats
+
+ To turn on custom format overlays over timestamps (variables
+ ~org-put-time-stamp-overlays~ and ~org-time-stamp-overlay-formats~),
+ use:
+
+ #+cindex: @code{customtime}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~customtime~ :: overlay custom time format
+
+ #+vindex: constants-unit-system
+
+ The following options influence the table spreadsheet (variable
+ ~constants-unit-system~).
+
+ #+cindex: @code{constcgs}, STARTUP keyword
+ #+cindex: @code{constSI}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~constcgs~ :: {{{file(constants.el)}}} should use the c-g-s unit system
+ - ~constSI~ :: {{{file(constants.el)}}} should use the SI unit system
+
+ #+vindex: org-footnote-define-inline
+ #+vindex: org-footnote-auto-label
+ #+vindex: org-footnote-auto-adjust
+
+ 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~.
+
+ #+cindex: @code{fninline}, STARTUP keyword
+ #+cindex: @code{nofninline}, STARTUP keyword
+ #+cindex: @code{fnlocal}, STARTUP keyword
+ #+cindex: @code{fnprompt}, STARTUP keyword
+ #+cindex: @code{fnauto}, STARTUP keyword
+ #+cindex: @code{fnconfirm}, STARTUP keyword
+ #+cindex: @code{fnplain}, STARTUP keyword
+ #+cindex: @code{fnadjust}, STARTUP keyword
+ #+cindex: @code{nofnadjust}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~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
+
+ #+cindex: org-hide-block-startup
+
+ To hide blocks on startup, use these keywords. The corresponding
+ variable is ~org-hide-block-startup~.
+
+ #+cindex: @code{hideblocks}, STARTUP keyword
+ #+cindex: @code{nohideblocks}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~hideblocks~ :: Hide all begin/end blocks on startup
+ - ~nohideblocks~ :: Do not hide blocks on startup
+
+ #+cindex: org-pretty-entities
+
+ The display of entities as UTF-8 characters is governed by the
+ variable ~org-pretty-entities~ and the keywords
+
+ #+cindex: @code{entitiespretty}, STARTUP keyword
+ #+cindex: @code{entitiesplain}, STARTUP keyword
+
+ #+attr_texinfo: :table-type table :indic @asis
+ - ~entitiespretty~ :: Show entities as UTF-8 characters where possible
+ - ~entitiesplain~ :: Leave entities plain
+
+- {{{kbd(#+TAGS: TAG1(c1) TAG2(c2))}}} ::
+ #+vindex: org-tag-alist
+
+ 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~.
+
+- {{{kbd(#+TBLFM:)}}} ::
+
+ This line contains the formulas for the table directly above the line.
+
+- {{{kbd(#+TITLE:)}}}, {{{kbd(#+AUTHOR:)}}}, {{{kbd(#+EMAIL:)}}}, {{{kbd(#+LANGUAGE:)}}}, {{{kbd(#+TEXT:)}}}, {{{kbd(#+DATE:)}}}, {{{kbd(#+OPTIONS:)}}}, {{{kbd(#+BIND:)}}}, {{{kbd(#+XSLT:)}}}, {{{kbd(#+DESCRIPTION:)}}}, {{{kbd(#+KEYWORDS:)}}}, {{{kbd(#+LaTeX_HEADER:)}}}, {{{kbd(#+STYLE:)}}}, {{{kbd(#+LINK_UP:)}}}, {{{kbd(#+LINK_HOME:)}}}, {{{kbd(#+EXPORT_SELECT_TAGS:)}}}, {{{kbd(#+EXPORT_EXCLUDE_TAGS:)}}} ::
+
+ These lines provide settings for exporting files. For more details see
+ [[Export options]].
+
+- {{{kbd(#+TODO:)}}}, {{{kbd(#+SEQ_TODO:)}}}, {{{kbd(#+TYP_TODO:)}}} ::
+ #+vindex: org-todo-keywords
+
+ These lines set the TODO keywords and their interpretation in the
+ current file. The corresponding variable is ~org-todo-keywords~.
+
+** The very busy C-c C-c key
+ :PROPERTIES:
+ :DESCRIPTION: When in doubt, press C-c C-c
+ :TITLE: The very busy C-c C-c key
+ :END:
+#+kindex: C-c C-c
+#+cindex: C-c C-c, overview
+
+The key {{{kbd(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 [[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 ~<<<target>>>~, 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.
+- If the cursor is at a timestamp, fix the day name in the timestamp.
+
+** Clean view
+ :PROPERTIES:
+ :DESCRIPTION: Getting rid of leading stars in the outline
+ :TITLE: A cleaner outline view
+ :END:
+#+cindex: hiding leading stars
+#+cindex: dynamic indentation
+#+cindex: odd-levels-only outlines
+#+cindex: clean 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:
+
+#+begin_example
+ ,* 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
+#+end_example
+
+{{{noindent}}} If you are using at least Emacs 23.2 and version 6.29
+of Org, this kind of view can be achieved dynamically at display time
+using ~org-indent-mode~.[fn:183] In this minor mode, all lines are
+prefixed for display with the necessary amount of space.[fn:154] Also
+headlines are prefixed with additional stars, so that the amount of
+indentation shifts by two spaces per level.[fn:155] All headline stars
+but the last one are made invisible using the ~org-hide~ face---see
+below under {{{samp(2.)}}} for more information on how this
+works.[fn:156] 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
+
+#+begin_example
+ ,#+STARTUP: indent
+#+end_example
+
+If you want a similar effect in an 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:
+
+#+attr_texinfo: :table-type table :indic @asis
+- Indentation of text below headlines ::
+
+ You may indent text below each headline to make the left boundary line up
+ with the headline, like
+
+ #+begin_example
+ ,*** 3rd level
+ more text, now indented
+ #+end_example
+
+ #+vindex: org-adapt-indentation
+
+ Org supports this with paragraph filling, line wrapping, and structure
+ editing,
+ preserving or adapting the indentation as appropriate.[fn:157]
+
+- Hiding leading stars ::
+ #+vindex: org-hide-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
+
+ #+begin_example
+ ,#+STARTUP: hidestars
+ ,#+STARTUP: showstars
+ #+end_example
+
+ With hidden stars, the tree becomes:
+
+ #+begin_example
+ ,* Top level headline
+ , * Second level
+ , * 3rd level
+ ...
+ #+end_example
+
+ #+vindex: org-hide @r{(face)}
+
+ {{{noindent}}} 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.
+- Odd levels ::
+ #+vindex: org-odd-levels-only
+
+ 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.[fn:158] 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:
+
+ #+begin_example
+ ,#+STARTUP: odd
+ ,#+STARTUP: oddeven
+ #+end_example
+
+ You can convert an Org file from single-star-per-level to the
+ double-star-per-level convention with {{{kbdkey(M-x
+ org-convert-to-odd-levels , RET)}}} in that file. The reverse
+ operation is {{{kbd(M-x org-convert-to-oddeven-levels)}}}.
+
+** TTY keys
+ :PROPERTIES:
+ :DESCRIPTION: Using Org on a tty
+ :TITLE: Using Org on a tty
+ :END:
+
+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 ({{{key(left)}}},
+{{{key(right)}}}, {{{key(up)}}}, {{{key(down)}}}), {{{key(TAB)}}} and
+{{{key(RET)}}}, in particular when used together with modifiers like
+{{{key(Meta)}}} and/or {{{key(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 {{{kbdkey(S-,cursor)}}} keys,
+whereas on a tty you would rather use {{{kbd(C-c .)}}} to re-insert
+the timestamp.
+
+#+attr_texinfo: :columns 0.2 0.3 0.1 0.4
+| Default | Alternative 1 | Speed key | Alternative 2 |
+|--------------------------+------------------------------+--------------+---------------------------|
+| {{{kbdkey(S-,TAB)}}} | {{{kbdspckey(C-u,TAB)}}} | {{{kbd(C)}}} | |
+| {{{kbdkey(M-,left)}}} | {{{kbd(C-c C-x l)}}} | {{{kbd(l)}}} | {{{kbdkeys(,Esc,left)}}} |
+| {{{kbdkey(M-S-,left)}}} | {{{kbd(C-c C-x L)}}} | {{{kbd(L)}}} | |
+| {{{kbdkey(M-,right)}}} | {{{kbd(C-c C-x r)}}} | {{{kbd(r)}}} | {{{kbdkeys(,Esc,right)}}} |
+| {{{kbdkey(M-S-,right)}}} | {{{kbd(C-c C-x R)}}} | {{{kbd(R)}}} | |
+| {{{kbdkey(M-,up)}}} | {{{kbd(C-c C-x u)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,up)}}} |
+| {{{kbdkey(M-S-,up)}}} | {{{kbd(C-c C-x U)}}} | {{{kbd(U)}}} | |
+| {{{kbdkey(M-,down)}}} | {{{kbd(C-c C-x d)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,down)}}} |
+| {{{kbdkey(M-S-,down)}}} | {{{kbd(C-c C-x D)}}} | {{{kbd(D)}}} | |
+| {{{kbdkey(S-,RET)}}} | {{{kbd(C-c C-x c)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(M-,RET)}}} | {{{kbd(C-c C-x m)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,RET)}}} |
+| {{{kbdkey(M-S-,RET)}}} | {{{kbd(C-c C-x M)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(S-,left)}}} | {{{kbdspckey(C-c,left)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(S-,right)}}} | {{{kbdspckey(C-c,right)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(S-,up)}}} | {{{kbdspckey(C-c,up)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(S-,down)}}} | {{{kbdspckey(C-c,down)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(C-S-,left)}}} | {{{kbdspckey(C-c C-x,left)}}} | {{{kbd( )}}} | |
+| {{{kbdkey(C-S-,right)}}} | {{{kbdspckey(C-c C-x,right)}}} | {{{kbd( )}}} | |
+
+** Interaction
+ :PROPERTIES:
+ :DESCRIPTION: Other Emacs packages
+ :TITLE: Interaction with other packages
+ :END:
+#+cindex: packages, interaction with other
+Org lives in the world of GNU Emacs and interacts in various ways
+with other code out there.
+
+*** FIXME Cooperation
+ :PROPERTIES:
+ :DESCRIPTION: Packages Org cooperates with
+ :TITLE: Packages that Org cooperates with
+ :END:
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{file(calc.el)}}} by Dave Gillespie ::
+ #+cindex: @file{calc.el}
+ #+cindex: Gillespie, Dave
+
+ Org uses the Calc package for implementing spreadsheet functionality
+ in its tables (see [[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 [[info:calc:Embedded Mode][GNU Emacs Calc Manual]].
+
+- {{{file(constants.el)}}} by Carsten Dominik ::
+ #+cindex: @file{constants.el}
+ #+cindex: Dominik, Carsten
+ #+vindex: org-table-formula-constants
+
+ In a table formula (see [[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
+ {{{file(constants)}}} package which defines a large number of
+ constants and units, and lets you use unit prefixes like {{{samp(M)}}}
+ for {{{samp(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
+ {{{file(constants.el)}}}.
+
+- {{{file(cdlatex.el)}}} by Carsten Dominik ::
+ #+cindex: @file{cdlatex.el}
+ #+cindex: Dominik, Carsten
+
+ Org mode can make use of the CDLaTeX package to efficiently enter
+ LaTeX fragments into Org files. See [[CDLaTeX mode]].
+
+- {{{file(imenu.el)}}} by Ake Stenhoff and Lars Lindberg ::
+ #+cindex: @file{imenu.el}
+ #+cindex: Stenhoff, Ake
+ #+cindex: Lindberg, Lars
+
+ 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:
+
+ #+begin_src emacs-lisp
+ (add-hook 'org-mode-hook
+ (lambda () (imenu-add-to-menubar "Imenu")))
+ #+end_src
+
+ #+vindex: org-imenu-depth
+
+ By default the index is two levels deep---you can modify the depth
+ using the option ~org-imenu-depth~.
+
+- {{{file(remember.el)}}} by John Wiegley ::
+ #+cindex: @file{remember.el}
+ #+cindex: Wiegley, John
+
+ Org used to use this package for capture, but no longer does.
+
+- {{{file(speedbar.el)}}} by Eric M. Ludlam ::
+ #+cindex: @file{speedbar.el}
+ #+cindex: Ludlam, Eric M.
+
+ 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 {{{kbd(<)}}} in the Speedbar frame.
+
+- {{{file(table.el)}}} by Takaaki Ota ::
+ #+kindex: C-c C-c
+ #+cindex: table editor, @file{table.el}
+ #+cindex: @file{table.el}
+ #+cindex: Ota, Takaaki
+
+ 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
+ {{{kbd(C-c ')}}} to edit them, similar to source code snippets.
+
+ - {{{kbd(C-c ')}}}, ~org-edit-special~ ::
+ #+kindex: C-c '
+
+ Edit a {{{file(table.el)}}} table. Works when the cursor is in a
+ table.el table.
+
+ - {{{kbd(C-c XXX)}}}, ~org-table-create-with-table.el~ ::
+ #+kindex: C-c ~
+ # Should be ~
+ Insert a {{{file(table.el)}}} table. If there is already a table at
+ point, this command converts it between the {{{file(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.
+
+ {{{file(table.el)}}} is part of Emacs since Emacs 22.
+
+- {{{file(footnote.el)}}} by Steven L. Baur ::
+ #+cindex: @file{footnote.el}
+ #+cindex: Baur, Steven L.
+
+ Org mode recognizes numerical footnotes as provided by this package.
+ However, Org mode also has its own footnote support (see [[Creating footnotes]]),
+ which makes using {{{file(footnote.el)}}} unnecessary.
+
+*** Conflicts
+ :PROPERTIES:
+ :DESCRIPTION: Packages that lead to conflicts
+ :END:
+
+#+cindex: @code{shift-selection-mode}
+#+vindex: org-support-shift-select
+
+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 {{{kbdkey(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,
+{{{kbdkey(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 using it outside of the special contexts where
+special commands apply, and by extending an existing active
+region even if the cursor moves across a special context.
+
+#+attr_texinfo: :table-type table :indic @asis
+- {{{file(CUA.el)}}} by Kim. F. Storm ::
+ #+cindex: @file{CUA.el}
+ #+cindex: Storm, Kim. F.
+ #+vindex: org-replace-disputed-keys
+
+ Key bindings in Org conflict with the {{{kbdkey(S-,<cursor>)}}} 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 {{{result}}} M-p | S-DOWN {{{result}}} M-n |
+ | S-LEFT {{{result}}} M-- | S-RIGHT {{{result}}} M-+ |
+ | C-S-LEFT {{{result}}} M-S-- | C-S-RIGHT {{{result}}} M-S-+ |
+
+ #+vindex: org-disputed-keys
+
+ Yes, these are unfortunately more difficult to remember. If you want
+ to have other replacement keys, look at the variable
+ ~org-disputed-keys~.
+
+- {{{file(filladapt.el)}}} by Kyle Jones ::
+ #+cindex: @file{filladapt.el}
+ #+cindex: Jones, Kyle
+
+ Org mode tries to do the right thing when filling paragraphs, list
+ items and other elements. Many users reported they had problems using
+ both {{{file(filladapt.el)}}} and Org mode, so a safe thing to do is
+ to disable it like this:
+
+ #+begin_src emacs-lisp
+ (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
+ #+end_src
+
+- {{{file(yasnippet.el)}}} ::
+ #+cindex: @file{yasnippet.el}
+
+ The way Org mode binds the {{{key(TAB)}}} key (binding to ~[tab]~
+ instead of ~"\t"~) overrules YASnippet's access to this key. The
+ following code fixed this problem:
+
+ #+begin_src emacs-lisp
+ (add-hook 'org-mode-hook
+ (lambda ()
+ (org-set-local 'yas/trigger-key [tab])
+ (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
+ #+end_src
+
+ The latest version of yasnippet doesn't play well with Org mode. If the
+ above code does not fix the conflict, start by defining the following
+ function:
+
+ #+begin_src emacs-lisp
+ (defun yas/org-very-safe-expand ()
+ (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
+ #+end_src
+
+ Then, tell Org mode what to do with the new function:
+
+ #+begin_src emacs-lisp
+ (add-hook 'org-mode-hook
+ (lambda ()
+ (make-variable-buffer-local 'yas/trigger-key)
+ (setq yas/trigger-key [tab])
+ (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+ (define-key yas/keymap [tab] 'yas/next-field)))
+ #+end_src
+
+- {{{file(windmove.el)}}} by Hovav Shacham ::
+ #+cindex: @file{windmove.el}
+ #+cindex: Shacham, Hovav
+
+ This package also uses the {{{kbd(S-<cursor>)}}} 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 {{{kbdkey(S-,cursor)}}}, add
+ this to your configuration:
+
+ #+begin_src emacs-lisp
+ ;; 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)
+ #+end_src
+
+- {{{file(viper.el)}}} by Michael Kifer ::
+ #+cindex: @file{viper.el}
+ #+cindex: Kifer, Michael
+ #+kindex: C-c /
+
+ Viper uses {{{kbd(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
+
+ #+begin_src emacs-lisp
+ (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
+ #+end_src
+
+** org-crypt
+ :PROPERTIES:
+ :DESCRIPTION: Encrypting Org files
+ :END:
+#+cindex: @file{+org-crypt.el}
+#+cindex: @code{org-decrypt-entry}
+
+Org-crypt will encrypt the text of an entry, but not the headline, or
+properties. Org-crypt uses the Emacs EasyPG library to encrypt and
+decrypt files.
+
+Any text below a headline that has a {{{samp(:crypt:)}}} tag will
+automatically be encrypted when the file is saved. If you want to use
+a different tag just customize the ~org-crypt-tag-matcher~ setting.
+
+To use org-crypt it is suggested that you have the following in your
+{{{file(.emacs)}}}:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(require 'org-crypt)
+(org-crypt-use-before-save-magic)
+(setq org-tags-exclude-from-inheritance (quote ("crypt")))
+
+(setq org-crypt-key nil)
+ ;; GPG key to use for encryption
+ ;; Either the Key ID or set to nil to use symmetric encryption.
+
+(setq auto-save-default nil)
+ ;; Auto-saving does not cooperate with org-crypt.el: so you need
+ ;; to turn it off if you plan to use org-crypt.el quite often.
+ ;; Otherwise, you'll get an (annoying) message each time you
+ ;; start Org.
+
+ ;; To turn it off only locally, you can insert this:
+ ;;
+ ;; # -*- buffer-auto-save-file-name: nil; -*-
+#+end_src
+
+Excluding the crypt tag from inheritance prevents already encrypted text
+being encrypted again.
+
+* Hacking
+ :PROPERTIES:
+ :DESCRIPTION: How to hack your way around
+ :APPENDIX: Appendix
+ :END:
+#+cindex: hacking
+
+This appendix describes some ways a user can extend the functionality
+of Org.
+
+** Hooks
+ :PROPERTIES:
+ :DESCRIPTION: How to reach into Org's internals
+ :END:
+#+cindex: hooks
+
+Org has a large number of hook variables that can be used to add
+functionality. This appendix about hacking is going to illustrate the
+use of some of them. A complete list of all hooks with documentation is
+maintained by the Worg project and can be found at
+[[http://orgmode.org/worg/org-configs/org-hooks.php]].
+
+** Add-on packages
+ :PROPERTIES:
+ :DESCRIPTION: Available extensions
+ :END:
+#+cindex: add-on packages
+
+A large number of add-on packages have been written by various
+authors. These packages are not part of Emacs, but they are
+distributed as contributed packages with the separate release
+available at the Org mode home page at [[http://orgmode.org]]. The
+list of contributed packages, along with documentation about each
+package, is maintained by the Worg project at
+[[http://orgmode.org/worg/org-contrib/]].
+
+** Adding hyperlink types
+ :PROPERTIES:
+ :DESCRIPTION: New custom link types
+ :END:
+#+cindex: hyperlinks, adding new types
+
+Org has a large number of hyperlink types built-in (see [[Hyperlinks]]).
+If you would like to add new link types, Org provides an interface for
+doing so. Let's look at an example file, {{{file(org-man.el)}}}, that
+will add support for creating links like:
+
+#+begin_example
+ [[man:printf][The printf manual]]
+#+end_example
+
+to show Unix manual pages inside Emacs:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+;;; org-man.el - Support for links to manpages in Org
+
+(require 'org)
+
+(org-add-link-type "man" 'org-man-open)
+(add-hook 'org-store-link-functions 'org-man-store-link)
+
+(defcustom org-man-command 'man
+ "The Emacs command to be used to display a man page."
+ :group 'org-link
+ :type '(choice (const man) (const woman)))
+
+(defun org-man-open (path)
+ "Visit the manpage on PATH.
+PATH should be a topic that can be thrown at the man command."
+ (funcall org-man-command path))
+
+(defun org-man-store-link ()
+ "Store a link to a manpage."
+ (when (memq major-mode '(Man-mode woman-mode))
+ ;; This is a man page, we do make this link
+ (let* ((page (org-man-get-page-name))
+ (link (concat "man:" page))
+ (description (format "Manpage for %s" page)))
+ (org-store-link-props
+ :type "man"
+ :link link
+ :description description))))
+
+(defun org-man-get-page-name ()
+ "Extract the page name from the buffer name."
+ ;; This works for both `Man-mode' and `woman-mode'.
+ (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
+ (match-string 1 (buffer-name))
+ (error "Cannot create link to this man page")))
+
+(provide 'org-man)
+
+;;; org-man.el ends here
+#+end_src
+
+{{{noindent}}} You would activate this new link type in
+{{{file(.emacs)}}} with:
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(require 'org-man)
+#+end_src
+
+{{{noindent}}} Let's go through the file and see what it does.
+#+vindex: org-store-link-functions
+
+1. It does ~(require 'org)~ to make sure that {{{file(org.el)}}} has
+ been loaded.
+
+2. The next line calls ~org-add-link-type~ to define a new link type
+ with prefix {{{samp(man)}}}. The call also contains the name of a
+ function that will be called to follow such a link.
+
+3. The next line adds a function to ~org-store-link-functions~, in
+ order to allow the command {{{kbd(C-c l)}}} to record a useful link
+ in a buffer displaying a man page.
+
+
+The rest of the file defines the necessary variables and functions.
+First there is a customization variable that determines which Emacs
+command should be used to display man pages. There are two options,
+~man~ and ~woman~. Then the function to follow a link is defined. It
+gets the link path as an argument---in this case the link path is just
+a topic for the manual command. The function calls the value of
+~org-man-command~ to display the man page.
+
+Finally the function ~org-man-store-link~ is defined. When you try to
+store a link with {{{kbd(C-c l)}}}, this function will be called to
+try to make a link. The function must first decide if it is supposed
+to create the link for this buffer type; we do this by checking the
+value of the variable ~major-mode~. If not, the function must exit and
+return the value ~nil~. If yes, the link is created by getting the
+manual topic from the buffer name and prefixing it with the string
+{{{samp(man:)}}}. Then it must call the command ~org-store-link-props~
+and set the ~:type~ and ~:link~ properties. Optionally you can also
+set the ~:description~ property to provide a default for the link
+description when the link is later inserted into an Org buffer with
+{{{kbd(C-c C-l)}}}.
+
+When it makes sense for your new link type, you may also define a
+function that implements special (e.g., completion) support for
+inserting such a link with {{{kbd(C-c C-l)}}}. Such a function should
+not accept any arguments, and return the full link with prefix.
+
+** Context-sensitive commands
+ :PROPERTIES:
+ :DESCRIPTION: How to add functionality to such commands
+ :END:
+#+cindex: context-sensitive commands, hooks
+#+cindex: add-ons, context-sensitive commands
+#+vindex: org-ctrl-c-ctrl-c-hook
+
+Org has several commands that act differently depending on context.
+The most important example is the {{{kbd(C-c C-c)}}} (see [[The very
+busy C-c C-c key]]). Also the {{{kbd(M-cursor)}}} and
+{{{kbd(M-S-cursor)}}} keys have this property.
+
+Add-ons can tap into this functionality by providing a function that
+detects special context for that add-on and executes functionality
+appropriate for the context. Here is an example from Dan Davison's
+{{{file(org-R.el)}}} which allows you to evaluate commands based on
+the {{{file(R)}}} programming language.[fn:159] For this package,
+special contexts are lines that start with ~#+R:~ or ~#+RR:~.
+
+#+header: :eval no
+#+header: :exports code
+#+begin_src emacs-lisp
+(defun org-R-apply-maybe ()
+ "Detect if this is context for org-R and execute R commands."
+ (if (save-excursion
+ (beginning-of-line 1)
+ (looking-at "#\\+RR?:"))
+ (progn (call-interactively 'org-R-apply)
+ t) ;; to signal that we took action
+ nil)) ;; to signal that we did not
+
+(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
+#+end_src
+
+The function first checks if the cursor is in such a line. If that is
+the case, ~org-R-apply~ is called and the function returns ~t~ to
+signal that action was taken, and {{{kbd(C-c C-c)}}} will stop looking
+for other contexts. If the function finds it should do nothing
+locally, it returns ~nil~ so that other, similar functions can have a
+try.
+
+** Tables in arbitrary syntax
+ :PROPERTIES:
+ :DESCRIPTION: Orgtbl for LaTeX and other programs
+ :END:
+#+cindex: tables, in other modes
+#+cindex: lists, in other modes
+#+cindex: Orgtbl mode
+
+Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
+frequent feature request has been to make it work with native tables
+in specific languages, for example LaTeX. However, this is
+extremely hard to do in a general way, would lead to a customization
+nightmare, and would take away much of the simplicity of the Orgtbl
+mode table editor.
+
+This appendix describes a different approach. We keep the Orgtbl mode
+table in its native format (the source table), and use a custom
+function to /translate/ the table to the correct syntax, and to
+/install/ it in the right location (the target table). This puts
+the burden of writing conversion functions on the user, but it allows
+for a very flexible system.
+
+Bastien added the ability to do the same with lists, in Orgstruct
+mode. You can use Org's facilities to edit and structure lists by
+turning ~orgstruct-mode~ on, then locally exporting such lists in
+another format (HTML, LaTeX or Texinfo.)
+
+*** Radio tables
+ :PROPERTIES:
+ :DESCRIPTION: Sending and receiving radio tables
+ :END:
+#+cindex: radio tables
+
+To define the location of the target table, you first need to create
+two lines that are comments in the current mode, but contain magic
+words for Orgtbl mode to find. Orgtbl mode will insert the translated
+table between these lines, replacing whatever was there before. For
+example:
+
+#+begin_example
+ /* BEGIN RECEIVE ORGTBL table_name */
+ /* END RECEIVE ORGTBL table_name */
+#+end_example
+
+{{{noindent}}} Just above the source table, we put a special line that
+tells Orgtbl mode how to translate this table and where to install it.
+For example:
+
+#+cindex: #+ORGTBL
+#+begin_example
+ ,#+ORGTBL: SEND table_name translation_function arguments ...
+#+end_example
+
+{{{noindent}}} Here, ~table_name~ is the reference name for the table
+that is also used in the receiver lines. ~translation_function~ is the
+Lisp function that does the translation. Furthermore, the line can
+contain a list of arguments (alternating key and value) at the end.
+The arguments will be passed as a property list to the translation
+function for interpretation. A few standard parameters are already
+recognized and acted upon before the translation function is called:
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:skip N~ ::
+
+ Skip the first N lines of the table. Hlines do count as separate lines
+ for this parameter!
+
+- ~:skipcols (n1 n2 ...)~ ::
+
+ List of columns that should be skipped. If the table has a column with
+ calculation marks, that column is automatically discarded as well.
+ Please note that the translator function sees the table /after/ the
+ removal of these columns, the function never knows that there have
+ been additional columns.
+
+- ~:no-escape t~ ::
+
+ When non-nil, do not escape special characters ~&%#_^~ when exporting
+ the table. The default value is nil.
+
+
+{{{noindent}}} The one problem remaining is how to keep the source
+table in the buffer without disturbing the normal workings of the
+file, for example during compilation of a C file or processing of a
+LaTeX file. There are a number of different solutions:
+
+- The table could be placed in a block comment if that is supported by
+ the language. For example, in C mode you could wrap the table
+ between {{{samp(/*)}}} and {{{samp(*/)}}} lines.
+
+- Sometimes it is possible to put the table after some kind of END
+ statement, for example ~\bye~ in TeX and ~\end{document}~ in
+ LaTeX.
+
+- You can just comment the table line-by-line whenever you want to
+ process the file, and uncomment it whenever you need to edit the
+ table. This only sounds tedious---the command {{{kbd(M-x
+ orgtbl-toggle-comment)}}} makes this comment-toggling very easy, in
+ particular if you bind it to a key.
+
+*** A LaTeX example
+ :PROPERTIES:
+ :DESCRIPTION: Step by step, almost a tutorial
+ :TITLE: A LaTeX example of radio tables
+ :END:
+#+cindex: @LaTeX{}, and Orgtbl mode
+
+The best way to wrap the source table in LaTeX is to use the
+~comment~ environment provided by {{{file(comment.sty)}}}. It has to
+be activated by placing ~\usepackage{comment}~ into the document
+header. Orgtbl mode can insert a radio table skeleton with the command
+{{{kbd(M-x orgtbl-insert-radio-table)}}}.[fn:160] You will be prompted
+for a table name, let's say we use {{{samp(salesfigures)}}}. You will
+then get the following template:
+
+#+cindex: #+ORGTBL, SEND
+#+begin_example
+ % BEGIN RECEIVE ORGTBL salesfigures
+ % END RECEIVE ORGTBL salesfigures
+ \begin{comment}
+ #+ORGTBL: SEND salesfigures orgtbl-to-latex
+ | | |
+ \end{comment}
+#+end_example
+
+#+vindex: @LaTeX{}-verbatim-environments
+
+{{{noindent}}} The ~#+ORGTBL: SEND~ line tells Orgtbl mode to use the
+function ~orgtbl-to-latex~ to convert the table into LaTeX and to
+put it into the receiver location with name ~salesfigures~. You may
+now fill in the table---feel free to use the spreadsheet features:[fn:161]
+
+#+begin_example
+ % BEGIN RECEIVE ORGTBL salesfigures
+ % END RECEIVE ORGTBL salesfigures
+ \begin{comment}
+ #+ORGTBL: SEND salesfigures orgtbl-to-latex
+ | Month | Days | Nr sold | per day |
+ |-------+------+---------+---------|
+ | Jan | 23 | 55 | 2.4 |
+ | Feb | 21 | 16 | 0.8 |
+ | March | 22 | 278 | 12.6 |
+ #+TBLFM: $4=$3/$2;%.1f
+ % $ (optional extra dollar to keep font-lock happy, see footnote)
+ \end{comment}
+#+end_example
+
+{{{noindent}}} When you are done, press {{{kbd(C-c C-c)}}} in the
+table to get the converted table inserted between the two marker
+lines.
+
+Now let's assume you want to make the table header by hand, because
+you want to control how columns are aligned, etc. In this case we make
+sure that the table translator skips the first 2 lines of the source
+table, and tell the command to work as a splice, i.e., to not
+produce header and footer commands of the target table:
+
+#+begin_example
+ \begin{tabular}{lrrr}
+ Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
+ % BEGIN RECEIVE ORGTBL salesfigures
+ % END RECEIVE ORGTBL salesfigures
+ \end{tabular}
+ %
+ \begin{comment}
+ #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
+ | Month | Days | Nr sold | per day |
+ |-------+------+---------+---------|
+ | Jan | 23 | 55 | 2.4 |
+ | Feb | 21 | 16 | 0.8 |
+ | March | 22 | 278 | 12.6 |
+ #+TBLFM: $4=$3/$2;%.1f
+ \end{comment}
+#+end_example
+
+The LaTeX translator function ~orgtbl-to-latex~ is already part of
+Orgtbl mode. It uses a ~tabular~ environment to typeset the table and
+marks horizontal lines with ~\hline~. Furthermore, it interprets the
+following parameters (see also see [[Translator functions]]):
+
+#+attr_texinfo: :table-type table :indic @asis
+- ~:splice nil/t~ ::
+
+ When set to ~t~, return only table body lines, don't wrap them into a
+ tabular environment. Default is ~nil~.
+
+- ~:fmt fmt~ ::
+
+ A format to be used to wrap each field, it should contain ~%s~ for the
+ original field value. For example, to wrap each field value in
+ dollars, you could use ~:fmt "$%s$"~. This may also be a property list
+ with column numbers and formats, for example ~:fmt (2 "$%s$" 4
+ "%s\\%%")~. A function of one argument can be used in place of the
+ strings; the function must return a formatted string.
+
+- ~:efmt efmt~ ::
+
+ Use this format to print numbers with exponentials. The format should
+ have ~%s~ twice for inserting mantissa and exponent, for example:
+
+ #+begin_example
+ "%s\\times10^{%s}"
+ #+end_example
+
+ The default is:
+
+ #+begin_example
+ "%s\\,(%s)"
+ #+end_example
+
+ This may also be a property list with column numbers and formats, for
+ example:
+
+ #+begin_example
+ :efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")
+ #+end_example
+
+ After ~efmt~ has been applied to a value, ~fmt~ will also be applied.
+ Similar to ~fmt~, functions of two arguments can be supplied instead
+ of s