diff options
Diffstat (limited to 'contrib/orgmanual.org')
| -rw-r--r-- | contrib/orgmanual.org | 19743 |
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 ~α~ in the HTML output, and as ~$\alpha$~ in the LaTeX +output. Similarly, ~\nbsp~ will become ~ ~ 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(<)}}} and {{{samp(>)}}} 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 ~α~, +~Γ~, and ~Ζ~, 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 strings. + +*** Translator functions + :PROPERTIES: + :DESCRIPTION: Copy and modify + :END: +#+cindex: HTML, and Orgtbl mode +#+cindex: translator function + +Orgtbl mode has several translator functions built-in: ~orgtbl-to-csv~ +(comma-separated values), ~orgtbl-to-tsv~ (TAB-separated values) +~orgtbl-to-latex~, ~orgtbl-to-html~, and ~orgtbl-to-texinfo~. Except +for ~orgtbl-to-html~, these all use a generic translator, +~orgtbl-to-generic~.[fn:162] For example, ~orgtbl-to-latex~ itself is +a very short function that computes the column definitions for the +~tabular~ environment, defines a few field and line separators and +then hands processing over to the generic translator. Here is the +entire code: + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(defun orgtbl-to-latex (table params) + "Convert the Orgtbl mode TABLE to LaTeX." + (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) + org-table-last-alignment "")) + (params2 + (list + :tstart (concat "\\begin@{tabular@}@{" alignment "@}") + :tend "\\end@{tabular@}" + :lstart "" :lend " \\\\" :sep " & " + :efmt "%s\\,(%s)" :hline "\\hline"))) + (orgtbl-to-generic table (org-combine-plists params2 params)))) +#+end_src + +As you can see, the properties passed into the function (variable +~PARAMS~) are combined with the ones newly defined in the function +(variable ~PARAMS2~). The ones passed into the function (i.e., the +ones set by the {{{samp(ORGTBL SEND)}}} line) take precedence. So if +you would like to use the LaTeX translator, but wanted the line +endings to be ~\\[2mm]~ instead of the default ~\\~, you could just +overrule the default with: + +#+begin_example + ,#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" +#+end_example + +For a new language, you can either write your own converter function +in analogy with the LaTeX translator, or you can use the generic +function directly. For example, if you have a language where a table +is started with {{{samp(!BTBL!)}}}, ended with {{{samp(!ETBL!)}}}, and +where table lines are started with {{{samp(!BL!)}}}, ended with +{{{samp(!EL!)}}}, and where the field separator is a TAB, you could +call the generic translator like this (on a single line!): + +#+begin_example + ,#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" + :lstart "!BL! " :lend " !EL!" :sep "\t" +#+end_example + +{{{noindent}}} Please check the documentation string of the function +~orgtbl-to-generic~ for a full list of parameters understood by that +function, and remember that you can pass each of them into +~orgtbl-to-latex~, ~orgtbl-to-texinfo~, and any other function using +the generic function. + +Of course you can also write a completely new function doing +complicated things the generic translator cannot do. A translator +function takes two arguments. The first argument is the table, a list +of lines, each line either the symbol ~hline~ or a list of fields. The +second argument is the property list containing all parameters +specified in the {{{samp(#+ORGTBL: SEND)}}} line. The function must +return a single string containing the formatted table. If you write a +generally useful translator, please post it to the [[mailto:emacs-orgmode@gnu.org][mailing list]] so +that others can benefit from your work. + +*** Radio lists + :PROPERTIES: + :DESCRIPTION: Doing the same for lists + :END: +#+cindex: radio lists +#+cindex: org-list-insert-radio-list + +Sending and receiving radio lists works exactly the same way as +sending and receiving radio tables (see [[Radio tables]]). As for radio +tables, you can insert radio list templates in HTML, LaTeX and +Texinfo modes by calling ~org-list-insert-radio-list~. + +Here are the differences with radio tables: + +- Orgstruct mode must be active. + +- Use the ~ORGLST~ keyword instead of ~ORGTBL~. + +- The available translation functions for radio lists don't take + parameters. + +- {{{kbd(C-c C-c)}}} will work when pressed on the first item of the + list. + + +Here is a LaTeX example. Let's say that you have this in your +LaTeX file: + +#+cindex: #+ORGLST +#+begin_example + % BEGIN RECEIVE ORGLST to-buy + % END RECEIVE ORGLST to-buy + \begin{comment} + #+ORGLST: SEND to-buy org-list-to-latex + - a new house + - a new computer + + a new keyboard + + a new mouse + - a new life + \end{comment} +#+end_example + +Pressing `C-c C-c' on ~a new house~ will insert the converted +LaTeX list between the two marker lines. + +** Dynamic blocks + :PROPERTIES: + :DESCRIPTION: Automatically filled blocks + :END: +#+cindex: dynamic blocks + +Org documents can contain /dynamic blocks/. These are specially marked +regions that are updated by some user-written function. A good example +for such a block is the clock table inserted by the command +{{{kbd(C-c C-x C-r)}}} (see [[Clocking work time]]). + +Dynamic blocks are enclosed by a BEGIN-END structure that assigns a +name to the block and can also specify parameters for the function +producing the content of the block. + +#+cindex: #+BEGIN:dynamic block +#+begin_example + ,#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... + + ,#+END: +#+end_example + +Dynamic blocks are updated with the following commands: + +#+attr_texinfo: :table-type table :indic @asis +- {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ :: + #+kindex: C-c C-x C-u + + Update dynamic block at point. + +- {{{kbd(C-u C-c C-x C-u)}}} :: + #+kindex: C-u C-c C-x C-u + + Update all dynamic blocks in the current file. + + +Updating a dynamic block means to remove all the text between ~BEGIN~ +and ~END~, parse the ~BEGIN~ line for parameters and then call the +specific writer function for this block to insert the new content. If +you want to use the original content in the writer function, you can +use the extra parameter ~:content~. + +For a block with name ~myblock~, the writer function is +~org-dblock-write:myblock~ with as only parameter a property list +with the parameters given in the begin line. Here is a trivial example +of a block that keeps track of when the block update function was last +run: + +#+begin_example + ,#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" + + ,#+END: +#+end_example + +{{{noindent}}} The corresponding block writer function could look like +this: + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(defun org-dblock-write:block-update-time (params) + (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) + (insert "Last block update at: " + (format-time-string fmt (current-time))))) +#+end_src + +If you want to make sure that all dynamic blocks are always +up-to-date, you could add the function ~org-update-all-dblocks~ to a +hook, for example ~before-save-hook~. ~org-update-all-dblocks~ is +written in a way such that it does nothing in buffers that are not in +~org-mode~. + +You can narrow the current buffer to the current dynamic block (like +any other block) with ~org-narrow-to-block~. + +** Special agenda views + :PROPERTIES: + :DESCRIPTION: Customized views + :END: +#+cindex: agenda views, user-defined +#+vindex: org-agenda-skip-function +#+vindex: org-agenda-skip-function-global + +Org provides a special hook that can be used to narrow down the +selection made by these agenda views: ~agenda~, ~todo~, ~alltodo~, +~tags~, ~tags-todo~, ~tags-tree~. You may specify a function that is +used at each match to verify if the match should indeed be part of the +agenda view, and if not, how much should be skipped. You can specify a +global condition that will be applied to all agenda views, this +condition would be stored in the variable +~org-agenda-skip-function-global~. More commonly, such a definition is +applied only to specific custom searches, using +~org-agenda-skip-function~. + +Let's say you want to produce a list of projects that contain a +~WAITING~ tag anywhere in the project tree. Let's further assume that +you have marked all tree headings that define a project with the TODO +keyword PROJECT. In this case you would run a TODO search for the +keyword PROJECT, but skip the match unless there is a ~WAITING~ tag +anywhere in the subtree belonging to the project line. + +To achieve this, you must write a function that searches the subtree for +the tag. If the tag is found, the function must return ~nil~ to +indicate that this match should not be skipped. If there is no such +tag, return the location of the end of the subtree, to indicate that +search should continue from there. + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(defun my-skip-unless-waiting () + "Skip trees that are not waiting" + (let ((subtree-end (save-excursion (org-end-of-subtree t)))) + (if (re-search-forward ":waiting:" subtree-end t) + nil ; tag found, do not skip + subtree-end))) ; tag not found, continue after end of subtree +#+end_src + +Now you may use this function in an agenda custom command, for example +like this: + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(org-add-agenda-custom-command + '("b" todo "PROJECT" + ((org-agenda-skip-function 'my-skip-unless-waiting) + (org-agenda-overriding-header "Projects waiting for something: ")))) +#+end_src + +#+vindex: org-agenda-overriding-header + +Note that this also binds ~org-agenda-overriding-header~ to get a +meaningful header in the agenda view. + +#+vindex: org-odd-levels-only +#+vindex: org-agenda-skip-function + +A general way to create custom searches is to base them on a search +for entries with a certain level limit. If you want to study all +entries with your custom search function, simply do a search for +{{{samp(LEVEL>0)}}}, and then use ~org-agenda-skip-function~ to select +the entries you really want to have.[fn:163] + +You may also put a Lisp form into ~org-agenda-skip-function~. In +particular, you may use the functions ~org-agenda-skip-entry-if~ +and ~org-agenda-skip-subtree-if~ in this form, for example: + +#+attr_texinfo: :table-type table :indic @asis +- {{{samp((org-agenda-skip-entry-if 'scheduled))}}} :: + + Skip current entry if it has been scheduled. + +- {{{samp((org-agenda-skip-entry-if 'notscheduled))}}} :: + + Skip current entry if it has not been scheduled. + +- {{{samp((org-agenda-skip-entry-if 'deadline))}}} :: + + Skip current entry if it has a deadline. + +- {{{samp((org-agenda-skip-entry-if 'scheduled 'deadline))}}} :: + + Skip current entry if it has a deadline, or if it is scheduled. + +- {{{samp((org-agenda-skip-entry-if 'todo '("TODO" "WAITING")))}}} :: + + Skip current entry if the TODO keyword is TODO or WAITING. + +- {{{samp((org-agenda-skip-entry-if 'todo 'done))}}} :: + + Skip current entry if the TODO keyword marks a DONE state. + +- {{{samp((org-agenda-skip-entry-if 'timestamp))}}} :: + + Skip current entry if it has any timestamp, may also be deadline or scheduled. + <<x-agenda-skip-entry-regexp>> + +- {{{samp((org-agenda-skip-entry-if 'regexp "regular expression"))}}} :: + + Skip current entry if the regular expression matches in the entry. + +- {{{samp((org-agenda-skip-entry-if 'notregexp "regular expression"))}}} :: + + Skip current entry unless the regular expression matches. + +- {{{samp((org-agenda-skip-subtree-if 'regexp "regular expression"))}}} :: + + Same as above, but check and skip the entire subtree. + + +Therefore we could also have written the search for WAITING projects +like this, even without defining a special function: + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(org-add-agenda-custom-command + '("b" todo "PROJECT" + ((org-agenda-skip-function '(org-agenda-skip-subtree-if + 'regexp ":waiting:")) + (org-agenda-overriding-header "Projects waiting for something: ")))) +#+end_src + +** Extracting agenda information + :PROPERTIES: + :DESCRIPTION: Post-processing agenda information + :END: +#+cindex: agenda, pipe +#+cindex: Scripts, for agenda processing +#+vindex: org-agenda-custom-commands + +Org provides commands to access agenda information for the command +line in Emacs batch mode. This extracted information can be sent +directly to a printer, or it can be read by a program that does +further processing of the data. The first of these commands is the +function ~org-batch-agenda~, that produces an agenda view and sends it +as ASCII text to STDOUT. The command takes a single string as +parameter. If the string has length 1, it is used as a key to one of +the commands you have configured in ~org-agenda-custom-commands~, +basically any key you can use after {{{kbd(C-c a)}}}. For example, to +directly print the current TODO list, you could use: + +#+header: :eval no +#+header: :exports code +#+begin_src sh +emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr +#+end_src + +If the parameter is a string with 2 or more characters, it is used as +a tags/TODO match string. For example, to print your local shopping +list (all items with the tag {{{samp(shop)}}}, but excluding the tag +{{{samp(NewYork)}}}), you could use: + +#+header: :eval no +#+header: :exports code +#+begin_src sh +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "+shop-NewYork")' | lpr +#+end_src + +{{{noindent}}} You may also modify parameters on the fly like this: + +#+header: :eval no +#+header: :exports code +#+begin_src sh +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "a" \ + org-agenda-span (quote month) \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + | lpr +#+end_src + +{{{noindent}}} which will produce a 30-day agenda, fully restricted to +the Org file {{{file(~/org/projects.org)}}}, not even including the +diary. + +If you want to process the agenda data in more sophisticated ways, you +can use the command ~org-batch-agenda-csv~ to get a comma-separated +list of values for each agenda item. Each line in the output will +contain a number of fields separated by commas. The fields in a line +are: + +#+attr_texinfo: :table-type table :indic @code +- category :: The category of the item +- head :: The headline, without TODO keyword, TAGS and PRIORITY +- type :: The type of the agenda entry, can be: + - todo :: selected in TODO match + - tagsmatch :: selected in tags match + - diary :: imported from diary + - deadline :: a deadline + - scheduled :: scheduled + - timestamp :: appointment, selected by timestamp + - closed :: entry was closed on date + - upcoming-deadline :: warning about nearing deadline + - past-scheduled :: forwarded scheduled item + - block :: entry has date block including date +- todo :: The TODO keyword, if any +- tags :: All tags including inherited ones, separated by colons +- date :: The relevant date, like 2007-2-14 +- time :: The time, like 15:00-16:50 +- extra :: String with extra planning info +- priority-l :: The priority letter if any was given +- priority-n :: The computed numerical priority + +{{{noindent}}} Time and date will only be given if a timestamp (or +deadline/scheduled) led to the selection of the item. + +A CSV list like this is very easy to use in a post-processing script. +For example, here is a Perl program that gets the TODO list from +Emacs/Org and prints all the items, preceded by a checkbox: + +#+header: :eval no +#+header: :exports code +#+begin_src perl +#!/usr/bin/perl + +# define the Emacs command to run +$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; + +# run it and capture the output +$agenda = qx@{$cmd 2>/dev/null@}; + +# loop over all lines +foreach $line (split(/\n/,$agenda)) @{ + # get the individual values + ($category,$head,$type,$todo,$tags,$date,$time,$extra, + $priority_l,$priority_n) = split(/,/,$line); + # process and print + print "[ ] $head\n"; +@} +#+end_src + +** Using the property API + :PROPERTIES: + :DESCRIPTION: Writing programs that use entry properties + :END: +#+cindex: API, for properties +#+cindex: properties, API + +Here is a description of the functions that can be used to work with +properties. + +#+attr_texinfo: :options org-entry-properties &optional pom which +#+begin_defun +Get all properties of the entry at point-or-marker POM. +This includes the TODO keyword, the tags, time strings for deadline, +scheduled, and clocking, and any additional properties defined in the +entry. The return value is an alist. Keys may occur multiple times +if the property key was used several times.@* +POM may also be nil, in which case the current entry is used. +If WHICH is nil or `all', get all properties. If WHICH is +`special' or `standard', only get that subclass. +#+end_defun + +#+vindex: org-use-property-inheritance +#+findex: org-insert-property-drawer +#+attr_texinfo: :options org-entry-get pom property &optional inherit +#+begin_defun +Get value of PROPERTY for entry at point-or-marker POM. By default, +this only looks at properties defined locally in the entry. If INHERIT +is non-nil and the entry does not have the property, then also check +higher levels of the hierarchy. If INHERIT is the symbol +~selective~, use inheritance if and only if the setting of +~org-use-property-inheritance~ selects PROPERTY for inheritance. +#+end_defun + +#+attr_texinfo: :options org-entry-delete pom property +#+begin_defun +Delete the property PROPERTY from entry at point-or-marker POM. +#+end_defun + +#+attr_texinfo: :options org-entry-put pom property value +#+begin_defun +Set PROPERTY to VALUE for entry at point-or-marker POM. +#+end_defun + +#+attr_texinfo: :options org-buffer-property-keys &optional include-specials +#+begin_defun +Get all property keys in the current buffer. +#+end_defun +#+attr_texinfo: :options org-insert-property-drawer +#+begin_defun +Insert a property drawer for the current entry. Also +#+end_defun + +#+attr_texinfo: :options org-entry-put-multivalued-property pom property &rest values +#+begin_defun +Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of +strings. They will be concatenated, with spaces as separators. +#+end_defun + +#+attr_texinfo: :options org-entry-get-multivalued-property pom property +#+begin_defun +Treat the value of the property PROPERTY as a whitespace-separated list of +values and return the values as a list of strings. +#+end_defun + +#+attr_texinfo: :options org-entry-add-to-multivalued-property pom property value +#+begin_defun +Treat the value of the property PROPERTY as a whitespace-separated list of +values and make sure that VALUE is in this list. +#+end_defun + +#+attr_texinfo: :options org-entry-remove-from-multivalued-property pom property value +#+begin_defun +Treat the value of the property PROPERTY as a whitespace-separated list of +values and make sure that VALUE is /not/ in this list. +#+end_defun + +#+attr_texinfo: :options org-entry-member-in-multivalued-property pom property value +#+begin_defun +Treat the value of the property PROPERTY as a whitespace-separated list of +values and check if VALUE is in this list. +#+end_defun + +#+attr_texinfo: :options org-property-allowed-value-functions +#+begin_defopt +Hook for functions supplying allowed values for a specific property. +The functions must take a single argument, the name of the property, and +return a flat list of allowed values. If {{{samp(:ETC)}}} is one of +the values, use the values as completion help, but allow also other values +to be entered. The functions must return ~nil~ if they are not +responsible for this property. +#+end_defopt + +** Using the mapping API + :PROPERTIES: + :DESCRIPTION: Mapping over all or selected entries + :END: +#+cindex: API, for mapping +#+cindex: mapping entries, API + +Org has sophisticated mapping capabilities to find all entries satisfying +certain criteria. Internally, this functionality is used to produce agenda +views, but there is also an API that can be used to execute arbitrary +functions for each or selected entries. The main entry point for this API +is: + +#+attr_texinfo: :options org-map-entries func &optional match scope &rest skip +#+begin_defun +Call FUNC at each headline selected by MATCH in SCOPE. + +FUNC is a function or a Lisp form. The function will be called without +arguments, with the cursor positioned at the beginning of the headline. +The return values of all calls to the function will be collected and +returned as a list. + +The call to FUNC will be wrapped into a save-excursion form, so FUNC +does not need to preserve point. After evaluation, the cursor will be +moved to the end of the line (presumably of the headline of the +processed entry) and search continues from there. Under some +circumstances, this may not produce the wanted results. For example, +if you have removed (e.g., archived) the current (sub)tree it could +mean that the next entry will be skipped entirely. In such cases, you +can specify the position from where search should continue by making +FUNC set the variable `org-map-continue-from' to the desired buffer +position. + +MATCH is a tags/property/todo match as it is used in the agenda match view. +Only headlines that are matched by this query will be considered during +the iteration. When MATCH is nil or t, all headlines will be +visited by the iteration. + +SCOPE determines the scope of this command. It can be any of: + +#+attr_texinfo: :table-type table :indic @code +- nil :: + + The current buffer, respecting the restriction, if any. + +- tree :: + + The subtree started with the entry at point. + +- region :: + + The entries within the active region, if any. + +- file :: + + The current buffer, without restriction. + +- file-with-archives :: + + The current buffer, and any archives associated with it. + +- agenda :: + + All agenda files. + +- agenda-with-archives :: + + All agenda files with any archive files associated with them. + +- (file1 file2 ...) :: + + If this is a list, all files in the list will be scanned. + + +{{{noindent}}} The remaining args are treated as settings for the +skipping facilities of the scanner. The following items can be given +here: + +#+vindex: org-agenda-skip-function +#+attr_texinfo: :table-type table :indic @asis +- ~archive~ :: + + Skip trees with the archive tag. + +- ~comment~ :: + + Skip trees with the COMMENT keyword. + +- function or Lisp form :: + + Will be used as value for ~org-agenda-skip-function~, so whenever the + function returns t, FUNC will not be called for that entry and search + will continue from the point where the function leaves it. +#+end_defun + +The function given to that mapping routine can really do anything you like. +It can use the property API (see [[Using the property API]]) to gather more +information about the entry, or in order to change metadata in the entry. +Here are a few functions that might be handy: + +#+attr_texinfo: :options org-todo &optional arg +#+begin_defun +Change the TODO state of the entry. See the docstring of the functions for +the many possible values for the argument ARG. +#+end_defun + +#+attr_texinfo: :options org-priority &optional action +#+begin_defun +Change the priority of the entry. See the docstring of this function for the +possible values for ACTION. +#+end_defun + +#+attr_texinfo: :options org-toggle-tag tag &optional onoff +#+begin_defun +Toggle the tag TAG in the current entry. Setting ONOFF to either ~on~ +or ~off~ will not toggle tag, but ensure that it is either on or off. +#+end_defun + +#+attr_texinfo: :options org-promote +#+begin_defun +Promote the current entry. +#+end_defun + +#+attr_texinfo: :options org-demote +#+begin_defun +Demote the current entry. +#+end_defun + +The following simple example will turn all entries in the current file +with a tag ~TOMORROW~ into TODO entries with the keyword ~UPCOMING~. +Entries in comment trees and in archive trees will be ignored. + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(org-map-entries + '(org-todo "UPCOMING") + "+TOMORROW" 'file 'archive 'comment) +#+end_src + +The following example counts the number of entries with TODO keyword +~WAITING~, in all agenda files. + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(length (org-map-entries t "/+WAITING" 'agenda)) +#+end_src + +* MobileOrg + :PROPERTIES: + :DESCRIPTION: Viewing and capture on a mobile device + :APPENDIX: Appendix + :END: +#+cindex: iPhone +#+cindex: MobileOrg +#+cindex: Moreland, Richard +#+cindex: Jones, Matt + +MobileOrg is the name of the mobile companion app for Org mode, +currently available for iOS and for Android. MobileOrg offers +offline viewing and capture support for an Org mode system rooted on a +``real'' computer. It does also allow you to record changes to +existing entries. The [[http://mobileorg.ncogni.to/][iOS implementation]] for the iPhone/iPod +Touch/iPad series of devices, was developed by Richard Moreland. +Android users should check out [[http://wiki.github.com/matburt/mobileorg-android/][MobileOrg Android]] by Matt Jones. The +two implementations are not identical but offer similar features. + +This appendix describes the support Org has for creating agenda views +in a format that can be displayed by MobileOrg, and for integrating +notes captured and changes made by MobileOrg into the main system. + +For changing tags and TODO states in MobileOrg, you should have set up +the customization variables ~org-todo-keywords~ and ~org-tags-alist~ +to cover all important tags and TODO keywords, even if individual +files use only part of these. MobileOrg will also offer you states and +tags set up with in-buffer settings, but it will understand the +logistics of TODO state /sets/ (see [[Per-file keywords]]) and /mutually +exclusive/ tags (see [[Setting tags]]) only for those set in these +variables. + +** Setting up the staging area + :PROPERTIES: + :DESCRIPTION: Where to interact with the mobile device + :END: + +MobileOrg needs to interact with Emacs through a directory on a +server. If you are using a public server, you should consider to +encrypt the files that are uploaded to the server. This can be done +with Org mode 7.02 and with MobileOrg 1.5 (iPhone version), and you +need an {{{file(openssl)}}} installation on your system. To turn on +encryption, set a password in MobileOrg and, on the Emacs side, +configure the variable ~org-mobile-use-encryption~.[fn:164] + +The easiest way to create that directory is to use a free [[http://dropbox.com][Dropbox]] +account.[fn:165] When MobileOrg first connects to your Dropbox, it +will create a directory MobileOrg inside the Dropbox. After the +directory has been created, tell Emacs about it: + +#+header: :eval no +#+header: :exports code +#+begin_src emacs-lisp +(setq org-mobile-directory "~/Dropbox/MobileOrg") +#+end_src + +Org mode has commands to put files for MobileOrg into that +directory, and to read captured notes from there. + +** Pushing to MobileOrg + :PROPERTIES: + :DESCRIPTION: Uploading Org files and agendas + :END: + +This operation copies all files currently listed in ~org-mobile-files~ +to the directory ~org-mobile-directory~. By default this list contains +all agenda files (as listed in ~org-agenda-files~), but additional +files can be included by customizing ~org-mobile-files~. File names +will be staged with paths relative to ~org-directory~, so all files +should be inside this directory.[fn:184] + +The push operation also creates a special Org file +{{{file(agendas.org)}}} with all custom agenda view defined by the +user.[fn:166] + +Finally, Org writes the file {{{file(index.org)}}}, containing links +to all other files. MobileOrg first reads this file from the server, +and then downloads all agendas and Org files listed in it. To speed up +the download, MobileOrg will only read files whose checksums have +changed.[fn:167] + +** Pulling from MobileOrg + :PROPERTIES: + :DESCRIPTION: Integrating captured and flagged items + :END: + +When MobileOrg synchronizes with the server, it not only pulls the +Org files for viewing. It also appends captured entries and pointers +to flagged and changed entries to the file {{{file(mobileorg.org)}}} +on the server. Org has a /pull/ operation that integrates this +information into an inbox file and operates on the pointers to flagged +entries. Here is how it works: + +1. Org moves all entries found in {{{file(mobileorg.org)}}} and + appends them to the file pointed to by the variable + ~org-mobile-inbox-for-pull~.[fn:168] Each captured entry and each + editing event will be a top-level entry in the inbox file. + +2. After moving the entries, Org will attempt to implement the changes + made in MobileOrg. Some changes are applied directly and without + user interaction. Examples are all changes to tags, TODO state, + headline and body text that can be cleanly applied. Entries that + have been flagged for further action will receive a tag + ~:FLAGGED:~, so that they can be easily found again. When there is + a problem finding an entry or applying the change, the pointer + entry will remain in the inbox and will be marked with an error + message. You need to later resolve these issues by hand. + +3. Org will then generate an agenda view with all flagged entries. The + user should then go through these entries and do whatever actions + are necessary. If a note has been stored while flagging an entry in + MobileOrg, that note will be displayed in the echo area when the + cursor is on the corresponding agenda line. + + #+attr_texinfo: :table-type table :indic @asis + - {{{kbd(?)}}} :: + #+kindex: ? + + Pressing {{{kbd(?)}}} in that special agenda will display the full + flagging note in another window and also push it onto the kill ring. + So you could use {{{kbd(? z C-y C-c C-c)}}} to store that flagging + note as a normal note in the entry. Pressing {{{kbd(?)}}} twice in + succession will offer to remove the ~:FLAGGED:~ tag along with the + recorded flagging note (which is stored in a property). In this way + you indicate that the intended processing for this flagged entry is + finished. + + +#+kindex: C-c a ? + +If you are not able to process all flagged entries directly, you can always +return to this agenda view using {{{kbd(C-c a ?)}}}.[fn:169] + +* History and acknowledgments + :PROPERTIES: + :DESCRIPTION: How Org came into being + :ALT_TITLE: History and Acknowledgments + :APPENDIX: Appendix + :END: +** From Carsten + +Org was born in 2003, out of frustration over the user interface of +the Emacs Outline mode. I was trying to organize my notes and +projects, and using Emacs seemed to be the natural way to go. However, +having to remember eleven different commands with two or three keys +per command, only to hide and show parts of the outline tree, that +seemed entirely unacceptable to me. Also, when using outlines to take +notes, I constantly wanted to restructure the tree, organizing it +parallel to my thoughts and plans. /Visibility cycling/ and /structure +editing/ were originally implemented in the package +{{{file(outline-magic.el)}}}, but quickly moved to the more general +{{{file(org.el)}}}. As this environment became comfortable for project +planning, the next step was adding /TODO entries/, basic /timestamps/, +and /table support/. These areas highlighted the two main goals that +Org still has today: to be a new, outline-based, plain text mode with +innovative and intuitive editing features, and to incorporate project +planning functionality directly into a notes file. + +Since the first release, literally thousands of emails to me or to the +[[mailto:emacs-orgmode@gnu.org][mailing list]] have provided a constant stream of bug reports, feedback, +new ideas, and sometimes patches and add-on code. Many thanks to +everyone who has helped to improve this package. I am trying to keep +here a list of the people who had significant influence in shaping one +or more aspects of Org. The list may not be complete, if I have +forgotten someone, please accept my apologies and let me know. + +Before I get to this list, a few special mentions are in order: + +#+attr_texinfo: :table-type table :indic @asis +- Bastien Guerry :: + + Bastien has written a large number of extensions to Org (most of them + integrated into the core by now), including the LaTeX exporter and + the plain list parser. His support during the early days, when he + basically acted as co-maintainer, was central to the success of this + project. Bastien also invented Worg, helped establishing the Web + presence of Org, and sponsored hosting costs for the ~orgmode.org~ + website. + +- Eric Schulte and Dan Davison :: + + Eric and Dan are jointly responsible for the Org-babel system, which + turns Org into a multi-language environment for evaluating code and + doing literate programming and reproducible research. + +- John Wiegley :: + + John has contributed a number of great ideas and patches directly to + Org, including the attachment system ({{{file(org-attach.el)}}}), + integration with Apple Mail ({{{file(org-mac-message.el)}}}), + hierarchical dependencies of TODO items, habit tracking + ({{{file(org-habits.el)}}}), and encryption + ({{{file(org-crypt.el)}}}). Also, the capture system is really an + extended copy of his great {{{file(remember.el)}}}. + +- Sebastian Rose :: + + Without Sebastian, the HTML/XHTML publishing of Org would be the + pitiful work of an ignorant amateur. Sebastian has pushed this part of + Org onto a much higher level. He also wrote {{{file(org-info.js)}}}, a + Java script for displaying webpages derived from Org using an + Info-like or a folding interface with single-key navigation. + + +{{{noindent}}} See [[List of contributions][below]] for the full list of contributions! Again, +please let me know what I am missing here! + +** From Bastien + +I (Bastien) have been maintaining Org since January 2011. This +appendix would not be complete without adding a few more +acknowledgements and thanks to Carsten's ones above. + +I am first grateful to Carsten for his trust while handing me over the +maintainership of Org. His support as been great since day one of this +new adventure, and it helped a lot. + +When I took over maintainership, I knew I would have to make Org more +collaborative than ever, as I would have to rely on people that are +more knowledgeable than I am on many parts of the code. Here is a list +of the persons I could rely on, they should really be considered +co-maintainers, either of the code or the community: + +#+attr_texinfo: :table-type table :indic @asis +- Eric Schulte :: + + Eric is maintaining the Babel parts of Org. His reactivity here kept + me away from worrying about possible bugs here and let me focus on + other parts. + +- Nicolas Goaziou :: + + Nicolas is maintaining the consistency of the deepest parts of Org. + His work on {{{file(org-element.el)}}} and {{{file(org-export.el)}}} + has been outstanding, and opened the doors for many new ideas and + features. + +- Jambunathan K :: + + Jambunathan contributed the ODT exporter, definitly a killer feature + of Org mode. He also contributed the new HTML exporter, which is + another core feature of Org. Here too, I knew I could rely on him to + fix bugs in these areas and to patiently explain the users what was + the problems and solutions. + +- Achim Gratz :: + + Achim rewrote the building process of Org, turning some /ad hoc/ tools + into a flexible and conceptually clean process. He patiently coped + with the many hicups that such a change can create for users. + +- Nick Dokos :: + + The Org mode mailing list would not be such a nice place without Nick, + who patiently helped users so many times. It is impossible to + overestimate such a great help, and the list would not be so active + without him. + + +I received support from so many users that it is clearly impossible to be +fair when shortlisting a few of them---but Org's history would not be +complete if the ones above were not mentioned in this manual. + +** List of contributions + +- Russel Adams came up with the idea for drawers. + +- Thomas Baumann wrote {{{file(org-bbdb.el)}}} and {{{file(org-mhe.el)}}}. + +- Christophe Bataillon created the great unicorn logo that we use on + the Org mode website. + +- Alex Bochannek provided a patch for rounding timestamps. + +- Jan Böcker wrote {{{file(org-docview.el)}}}. + +- Brad Bozarth showed how to pull RSS feed data into Org mode files. + +- Tom Breton wrote {{{file(org-choose.el)}}}. + +- Charles Cave's suggestion sparked the implementation of templates + for Remember, which are now templates for capture. + +- Pavel Chalmoviansky influenced the agenda treatment of items with + specified time. + +- Gregory Chernov patched support for Lisp forms into table + calculations and improved XEmacs compatibility, in particular by + porting {{{file(nouline.el)}}} to XEmacs. + +- Sacha Chua suggested copying some linking code from Planner. + +- Baoqiu Cui contributed the DocBook exporter. + +- Eddward DeVilla proposed and tested checkbox statistics. He also + came up with the idea of properties, and that there should be an API + for them. + +- Nick Dokos tracked down several nasty bugs. + +- Kees Dullemond used to edit projects lists directly in HTML and so + inspired some of the early development, including HTML export. He + also asked for a way to narrow wide table columns. + +- Thomas S. Dye contributed documentation on Worg and helped + integrating the Org-Babel documentation into the manual. + +- Christian Egli converted the documentation into Texinfo format, + inspired the agenda, patched CSS formatting into the HTML exporter, + and wrote {{{file(org-taskjuggler.el)}}}. + +- David Emery provided a patch for custom CSS support in exported + HTML agendas. + +- Nic Ferrier contributed mailcap and XOXO support. + +- Miguel A. Figueroa-Villanueva implemented hierarchical checkboxes. + +- John Foerch figured out how to make incremental search show + context around a match in a hidden outline tree. + +- Raimar Finken wrote {{{file(org-git-line.el)}}}. + +- Mikael Fornius works as a mailing list moderator. + +- Austin Frank works as a mailing list moderator. + +- Eric Fraga drove the development of BEAMER export with ideas and + testing. + +- Barry Gidden did proofreading the manual in preparation for the + book publication through Network Theory Ltd. + +- Niels Giesen had the idea to automatically archive DONE trees. + +- Nicolas Goaziou rewrote much of the plain list code. + +- Kai Grossjohann pointed out key-binding conflicts with other packages. + +- Brian Gough of Network Theory Ltd publishes the Org mode manual as + a book. + +- Bernt Hansen has driven much of the support for auto-repeating + tasks, task state change logging, and the clocktable. His clear + explanations have been critical when we started to adopt the Git + version control system. + +- Manuel Hermenegildo has contributed various ideas, small fixes + and patches. + +- Phil Jackson wrote {{{file(org-irc.el)}}}. + +- Scott Jaderholm proposed footnotes, control over whitespace + between folded entries, and column view for properties. + +- Matt Jones wrote /MobileOrg Android/. + +- Tokuya Kameshima wrote {{{file(org-wl.el)}}} and {{{file(org-mew.el)}}}. + +- Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He + also provided frequent feedback and some patches. + +- Matt Lundin has proposed last-row references for table formulas + and named invisible anchors. He has also worked a lot on the FAQ. + +- David Maus wrote {{{file(org-atom.el)}}}, maintains the issues + file for Org, and is a prolific contributor on the mailing list with + competent replies, small fixes and patches. + +- Jason F. McBrayer suggested agenda export to CSV format. + +- Max Mikhanosha came up with the idea of refiling. + +- Dmitri Minaev sent a patch to set priority limits on a per-file + basis. + +- Stefan Monnier provided a patch to keep the Emacs-Lisp compiler + happy. + +- Richard Moreland wrote /MobileOrg/ for the iPhone. + +- Rick Moynihan proposed allowing multiple TODO sequences in a file + and being able to quickly restrict the agenda to a subtree. + +- Todd Neal provided patches for links to Info files and Elisp forms. + +- Greg Newman refreshed the unicorn logo into its current form. + +- Tim O'Callaghan suggested in-file links, search options for + general file links, and TAGS. + +- Osamu Okano wrote {{{file(orgcard2ref.pl)}}}, a Perl program to + create a text version of the reference card. + +- Takeshi Okano translated the manual and David O'Toole's tutorial + into Japanese. + +- Oliver Oppitz suggested multi-state TODO items. + +- Scott Otterson sparked the introduction of descriptive text for + links, among other things. + +- Pete Phillips helped during the development of the TAGS feature, + and provided frequent feedback. + +- Martin Pohlack provided the code snippet to bundle character + insertion into bundles of 20 for undo. + +- T.V. Raman reported bugs and suggested improvements. + +- Matthias Rempe (Oelde) provided ideas, Windows support, and + quality control. + +- Paul Rivier provided the basic implementation of named footnotes. + He also acted as mailing list moderator for some time. + +- Kevin Rogers contributed code to access VM files on remote hosts. + +- Frank Ruell solved the mystery of the ~keymapp nil~ bug, a + conflict with {{{file(allout.el)}}}. + +- Jason Riedy generalized the send-receive mechanism for Orgtbl + tables with extensive patches. + +- Philip Rooke created the Org reference card, provided lots of + feedback, developed and applied standards to the Org documentation. + +- Christian Schlauer proposed angular brackets around links, among + other things. + +- Paul Sexton wrote {{{file(org-ctags.el)}}}. + +- Tom Shannon's {{{file(organizer-mode.el)}}} inspired linking to VM/BBDB/Gnus. + +- Ilya Shlyakhter proposed the Archive Sibling, line numbering in + literal examples, and remote highlighting for referenced code lines. + +- Stathis Sideris wrote the {{{file(ditaa.jar)}}} ASCII to PNG + converter that is now packaged into Org's {{{file(contrib)}}} + directory. + +- Daniel Sinder came up with the idea of internal archiving by + locking subtrees. + +- Dale Smith proposed link abbreviations. + +- James TD Smith has contributed a large number of patches for + useful tweaks and features. + +- Adam Spiers asked for global linking commands, inspired the link + extension system, added support for mairix, and proposed the mapping + API. + +- Ulf Stegemann created the table to translate special symbols to + HTML, LaTeX, UTF-8, Latin-1 and ASCII. + +- Andy Stewart contributed code to {{{file(org-w3m.el)}}}, to copy + HTML content with links transformation to Org syntax. + +- David O'Toole wrote {{{file(org-publish.el)}}} and drafted the + manual chapter about publishing. + +- Jambunathan K contributed the ODT exporter. + +- Sebastien Vauban reported many issues with LaTeX and BEAMER + export and enabled source code highlighting in Gnus. + +- Stefan Vollmar organized a video-recorded talk at the + Max-Planck-Institute for Neurology. He also inspired the creation + of a concept index for HTML export. + +- J\"urgen Vollmer contributed code generating the table of contents + in HTML output. + +- Samuel Wales has provided important feedback and bug reports. + +- Chris Wallace provided a patch implementing the {{{samp(QUOTE)}}} + keyword. + +- David Wainberg suggested archiving, and improvements to the + linking system. + +- Carsten Wimmer suggested some changes and helped fix a bug in + linking to Gnus. + +- Roland Winkler requested additional key bindings to make Org work + on a tty. + +- Piotr Zielinski wrote {{{file(org-mouse.el)}}}, proposed agenda + blocks and contributed various ideas and code snippets. + +* GNU Free Documentation License +:PROPERTIES: +:APPENDIX: t +:DESCRIPTION: The license for this documentation. +:END: + +#+TEXINFO: @include ../doc/doclicense.texi + +* Concept index +:PROPERTIES: +:ALT_TITLE: Main Index +:INDEX: cp +:DESCRIPTION: Org's concepts and features +:END: + +* Key index + :PROPERTIES: + :DESCRIPTION: Key bindings and where they are described + :ALT_TITLE: Key Index + :INDEX: ky + :END: + +* Command and function index + :PROPERTIES: + :DESCRIPTION: Command names and some internal functions + :ALT_TITLE: Command and Function Index + :INDEX: fn + :END: + +* Variable index + :PROPERTIES: + :DESCRIPTION: Variables mentioned in the manual + :ALT_TITLE: Variable Index + :INDEX: vr + :END: + +This is not a complete index of variables and faces, only the ones +that are mentioned in the manual. For a more complete list, use +{{{kbdspckey(M-x org-customize,RET)}}} and then click yourself through +the tree. + +* Copying + :PROPERTIES: + :copying: t + :END: + +This manual is for Org version {{{version}}}. + +Copyright (C) 2004-2013 Free Software Foundation, Inc. + +#+BEGIN_QUOTE +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +#+END_QUOTE + +* Macro definitions :noexport: + +# Version macro, with commit hash +#+MACRO: version (eval (pcase (split-string (org-version nil t) "[ (_]" t) (`(,_ ,_ ,n ,_ ,r . ,_) (format "%s (release_%s)" n r)))) + +# Markup macros. In texinfo export they will be marked up, otherwise +# they will be inserted verbatim. markup is the generic form that can +# be used to insert any @-command with the second variable being the +# text to mark up. +#+MACRO: markup @@info:@$1{@@$2@@info:}@@ +#+MACRO: kbd {{{markup(kbd,$1)}}} +#+MACRO: key {{{markup(key,$1)}}} +#+MACRO: samp {{{markup(samp,$1)}}} +#+MACRO: command {{{markup(command,$1)}}} +#+MACRO: file {{{markup(file,$1)}}} +#+MACRO: var {{{markup(var,$1)}}} +#+MACRO: cite {{{markup(cite,$1)}}} +#+MACRO: value {{{markup(value,$1)}}} + +#+MACRO: kbdkey {{{kbd($1{{{key($2)}}})}}} +#+MACRO: kbdspckey {{{kbd($1 {{{key($2)}}})}}} +#+MACRO: ksksksk {{{kbd($1 {{{key($2)}}} $3 {{{key($4)}}})}}} +#+MACRO: ksksksksk {{{kbd($1 {{{key($2)}}} $3 {{{key($4)}}} {{{key($5)}}})}}} +#+MACRO: kbdkeys {{{kbd($1{{{key($2)}}}{{{key($3)}}})}}} + +# Plain macros. +#+MACRO: noindent @@info:@noindent@@ +#+MACRO: result @@info:@result{}@@ +#+MACRO: page @@info:@page@@ + +* Instructions for use :noexport: +- [ ] Tangle the makefile, `C-c C-v t' +- [ ] Execute [[Editing setup][this source code block]] +- [ ] Asynchronously generate the info file, `C-e i i' + +* Improvements and fixes [10/12] :noexport: +- [X] Jon will fix detailed node listing +- [X] Jon will fix :INDEX: property +- [ ] New link type to generate pxref? (asked on ML) +- [X] New macro for kbdkey that preserves space, e.g., `C-c <RET>' +- [X] Indent examples one more space to match indentation of footnotes +- [X] How to generate @kbd{\}? +- [X] How to generate @kbd{~}? +- [X] How to include GNU Free Documentation License as Appendix D? +- [X] Straighten out footnotes +- [X] Truncated footnote (asked on ML) +- [ ] Resolve macros with XXX arguments +- [X] Get @appendix instead of @chapter? + +* Nicolas Goaziou's instructions for v.8 :noexport: + +** Global Changes +All occurrences of "#+LABEL:" should be replaced with "#+NAME:". + +*** TODO Replace #+LABEL with #+NAME + +** Chapter 2, Document Structure + :PROPERTIES: + :CATEGORY: Ch. 2 + :END: +In "2. Document Structure", one section could be added about +cross-referencing, which would point to "Internal links". There, targets +in comments can be removed. Also most back-ends will turn links to +targets into proper cross-reference number (see `org-export-get-ordinal' +docstring for cases handled). + +*** TODO Add section about cross-referencing + +** Chapter 4, Hyperlinks + :PROPERTIES: + :CATEGORY: Ch. 4 + :END: +"Internal links". There, targets +in comments can be removed. Also most back-ends will turn links to +targets into proper cross-reference number (see `org-export-get-ordinal' +docstring for cases handled). + +*** TODO Remove targets in comments + +** Chapter 11, Markup for Rich Export + :PROPERTIES: + :CATEGORY: Ch. 11 + :END: +*** Include Keyword +The "#+INCLUDE:" keyword syntax and effect is slightly different. You +may want to look at `org-export-expand-include-keyword'. + +**** TODO Revise Include keyword +** Chapter 12, Exporting + :PROPERTIES: + :CATEGORY: Ch. 12 + :END: +*** Export Options +In "12. Exporting", "Export options" section need an overhaul. See +`org-export-options-alist' for the default list of export options. Other +options are back-end specific and should be introduced in their own +section. Also "#+KEYWORD:" renaming into ":EXPORT_KEYWORD:" property is +systematic. + +**** TODO Overhaul Export options section + +**** TODO KEYWORD now EXPORT_KEYWORD + +*** Macros +There should also be a section about macros (and move it out of "11 +Markup for rich export"), general, hard-coded ({{{time(...)}}}, +{{{property(...)}}}, {{{input-file}}} and {{{modification-time(...)}}}) +and specific ({{{date}}}, {{{author}}}, {{{title}}} and {{{email}}}). It +should be specified that macros are recursive and only apply to one +line. Therefore, they are appropriate for small replacements. For more +complex ones, one may use Babel instead. + +**** TODO Write macros section +Subsections: General, Hard-coded, Specific + +*** Filters +There should also be a section about filters used to customize export +output and another one about `org-export-define-derived-backend' which +allow someone to tweak a back-end. + +**** TODO Write filters section + +*** Define derived back-end +and another one about `org-export-define-derived-backend' which +allow someone to tweak a back-end. + +**** TODO Write derived back-end section + +*** Export Snippets +A section can be added about export snippets, i.e. + + @@ob-latex:\something{...}@@ + +They are a generalization for @<html> tags. + +**** TODO Write export snippets section +*** Captions +There may be a section about captions and their syntax. A note should +specify that export back-ends may or may not respect a caption. On the +other hand "11.2 Images and Tables" focuses on captions. Since these are +not specific to Images and Tables, it may be removed. + +**** TODO Write captions section +*** Back-ends +I would also regroup every back-end into a sub-section to not clutter +main section. + +Other options are back-end specific and should be introduced in their +own section. + +Also most back-ends will turn links to +targets into proper cross-reference number (see `org-export-get-ordinal' +docstring for cases handled). + + +**** Old back-ends + +"DocBook export" (though texinfo back-end can export to DocBook) and +"XOXO export" sections can be removed as the back-ends are discontinued. +There is no equivalent to "Taskjuggler export" yet, so it can be removed +too. + +***** TODO Remove DocBook backend + +***** TODO Remove XOXO backend + +***** TODO Remove Taskjuggler backend + +**** Back-end template +These are only suggestion. There is also probably many more things to +do. But I think that the hardest part is to start writing it. If you +come up with a good organization for e-latex back-end documentation, we +can use it for other back-ends thereafter. + +***** TODO Write back-end template + +****** TODO Does back-end turn links to targets? + +**** LaTeX Back-end +About the latex back-end, you know certainly a lot. It should be +specified that it introduces 3 new keywords, namely "LATEX_CLASS", +"LATEX_CLASS_OPTIONS" and "LATEX_HEADER". It also introduces +"BEGIN_LATEX" and "BEGIN_TEX" blocks (the latter being just a synonym +for the former). It would be worth to add that it handles footnotes in +item tags and footnotes within footnotes. It also handles booktabs, +paralist types, automatic babel language selection with #+LANGUAGE: in +addition to already present features (minted/listings package handling). + +***** TODO Write LaTeX back-end +**** Beamer Back-end +The BEAMER export back-end deserves, IMO, its own section. + +***** TODO Write Beamer back-end +**** TexInfo Back-end +> BTW, it would be great to have a texinfo exporter so the Org +> documentation could be written in Org-mode :) + +There is one, albeit barely tested: (require 'org-e-texinfo). + +though texinfo back-end can export to DocBook + +***** TODO Write texinfo backend +*** Export dispatcher +I think that the export dispatcher doesn't deserve its own section. The +introduction to Export subsystem can talk about "M-x +org-export-dispatch" (bound to C-c C-e) instead. +**** TODO Remove export dispatcher section + +*** Smart quotes +There should be a section about smart-quotes too. + +**** TODO Add smart quotes section + +* Org-mode setup :noexport: +** Editing setup +#+name: setup-editing +#+header: :results silent +#+header: :noweb yes +#+header: :eval no-export +#+begin_src emacs-lisp +(require 'ox-texinfo) +(define-key org-mode-map (kbd "C-c e") 'org-export-dispatch) +(setq org-src-preserve-indentation t) +(setq org-export-in-background t) +(setq org-export-async-debug t) +(setq org-export-async-init-file (expand-file-name "init.el")) +(setq org-pretty-entities nil) +(setq org-footnote-auto-adjust nil) +(setq org-confirm-babel-evaluate nil) +(org-babel-do-load-languages + 'org-babel-load-languages + '((emacs-lisp . t) + (sh . t))) +(org-add-link-type + "pxref" nil + (lambda (path desc format) + (cond + ((eq format 'html) + (format "<span class=\"pxref\">%s</span>" path)) + ((eq format 'latex) + (format "\\ref{%s}" path)) + ((eq format 'texinfo) + (format "@pxref{%s,%s}" path desc))))) +(add-to-list 'org-export-snippet-translation-alist + '("info" . "texinfo")) +#+end_src + +** init.el file +This source code block requires paths to your Org mode installation. +Modify accordingly. + +#+name: emacs-init +#+header: :tangle init.el +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(setq load-path (cons "~/.emacs.d/src/org-mode/lisp" load-path)) +; (setq load-path (cons "~/.emacs.d/src/org-mode/contrib/lisp" load-path)) +(require 'ox-texinfo) +(setq org-src-preserve-indentation t) +(setq org-confirm-babel-evaluate nil) +(setq org-footnote-auto-adjust nil) +(org-babel-do-load-languages + 'org-babel-load-languages + '((emacs-lisp . t) + (makefile . t) + (sh . t))) +(add-to-list 'org-export-snippet-translation-alist + '("info" . "texinfo")) +#+end_src + +** Texi -> Org helpers :noexport: +This section contains source code blocks that help translate from +=texinfo= to =Org=. + +#+name: tsd-helpers +#+header: :noweb yes +#+header: :eval no-export +#+begin_src emacs-lisp +<<tsd-index-to-macro>> +<<tsd-samp-to-macro>> +<<tsd-kbdkey-to-macro>> +<<tsd-kbd-to-macro>> +<<tsd-key-to-macro>> +<<tsd-command-to-macro>> +<<tsd-file-to-macro>> +<<tsd-noindent>> +<<tsd-example-block-begin>> +<<tsd-example-block-end>> +<<tsd-table-begin>> +<<tsd-table-end>> +<<tsd-pxref>> +<<tsd-xref>> +<<tsd-ref>> +<<tsd-orgcmd>> +<<tsd-orgkey>> +<<tsd-code-to-markup>> +<<tsd-emph-to-markup>> +<<tsd-i-to-markup>> +<<tsd-lisp-begin>> +<<tsd-lisp-end>> +#+end_src + +#+results: tsd-helpers +: tsd-lisp-end + +#+name: tsd-index-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-index-to-macro () + "Make macros out of @[cpfvk]index commands. Doesn't handle commas." + (interactive) + (query-replace-regexp "@\\([cpfvk]\\)index\\ \\(.*\\)$" "{{{\\1index(\\2)}}}" nil)) +#+end_src + +#+name: tsd-samp-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-samp-to-macro () + "Make macros out of @samp commands." + (interactive) + (query-replace-regexp "@samp{\\([^}]*\\)}" "{{{samp(\\1)}}}" nil)) +#+end_src + +#+name: tsd-kbdkey-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-kbdkey-to-macro () + "Make macros out of @kbd,@key commands." + (interactive) + (query-replace-regexp "@kbd{\\([^@]*\\)@key{\\([^}]*\\)}}" "{{{kbdkey(\\1,\\2)}}}" nil)) +#+end_src + +#+name: tsd-kbd-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-kbd-to-macro () + "Make macros out of @kbd commands." + (interactive) + (query-replace-regexp "@kbd{\\([^}]*\\)}" "{{{kbd(\\1)}}}" nil)) +#+end_src + +#+name: tsd-key-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-key-to-macro () + "Make macros out of @key commands." + (interactive) + (query-replace-regexp "@key{\\([^}]*\\)}" "{{{key(\\1)}}}" nil)) +#+end_src + +#+name: tsd-command-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-command-to-macro () + "Make macros out of @command commands." + (interactive) + (query-replace-regexp "@command{\\([^}]*\\)}" "{{{command(\\1)}}}" nil)) +#+end_src + +#+name: tsd-file-to-macro +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-file-to-macro () + "Make macros out of @file commands." + (interactive) + (query-replace-regexp "@file{\\([^}]*\\)}" "{{{file(\\1)}}}" nil)) +#+end_src + +#+name: tsd-noindent +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-noindent () + "Make macros out of @noindent commands." + (interactive) + (query-replace "@noindent" "{{{noindent}}}" t)) +#+end_src + +#+name: tsd-example-block-begin +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-example-block-begin () + "Convert example blocks." + (interactive) + (query-replace "@example" "#+begin_example" t)) +#+end_src + +#+name: tsd-example-block-end +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-example-block-end () + "Convert example blocks." + (interactive) + (query-replace "@end example" "#+end_example" nil)) +#+end_src + +#+name: tsd-table-begin +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-table-begin () + "Convert table blocks." + (interactive) + (query-replace-regexp "@table\\ \\([@a-z]*\\)" "#+attr_texinfo: :table-type table :indic \\1 t)) +#+end_src + +#+name: tsd-table-end +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-table-end () + "Convert table blocks." + (interactive) + (query-replace "@end table" "" nil)) +#+end_src + +#+name: tsd-pxref +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-pxref () + "Convert @pxref to links." + (interactive) + (query-replace-regexp "@pxref{\\([^}]*\\)}" "see \[\[\\1\]\]" nil)) +#+end_src + +#+name: tsd-xref +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-xref () + "Convert @xref to links." + (interactive) + (query-replace-regexp "@xref{\\([^}]*\\)}" "See \[\[\\1\]\]" nil)) +#+end_src + +#+name: tsd-ref +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-ref () + "Convert @ref to links." + (interactive) + (query-replace-regexp "@ref{\\([^}]*\\)}" "\[\[\\1\]\]" nil)) +#+end_src + +#+name: tsd-orgcmd +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-orgcmd () + "Convert @orgcmd to list entry." + (interactive) + (query-replace-regexp "@orgcmd{\\([^,]*\\),\\([^}]*\\)}" "- {{{kbd(\\1)}}}, ~\\2~ ::" nil)) +#+end_src + +#+name: tsd-orgkey +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-orgkey () + "Convert @orgkey to list entry." + (interactive) + (query-replace-regexp "@orgkey{\\([^}]*\\)}" "- {{{kbd(\\1)}}} ::" nil)) +#+end_src + +#+name: tsd-code-to-markup +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-code-to-markup () + "Convert @code to markup." + (interactive) + (query-replace-regexp "@code{\\([^}]*\\)}" "~\\1~" nil)) +#+end_src + +#+name: tsd-emph-to-markup +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-emph-to-markup () + "Convert @emph to markup." + (interactive) + (query-replace-regexp "@emph{\\([^}]*\\)}" "/\\1/" nil)) +#+end_src + +#+name: tsd-i-to-markup +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-i-to-markup () + "Convert @i to markup." + (interactive) + (query-replace-regexp "@i{\\([^}]*\\)}" "/\\1/" nil)) +#+end_src + +#+name: tsd-b-to-markup +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-b-to-markup () + "Convert @b to markup." + (interactive) + (query-replace-regexp "@b{\\([^}]*\\)}" "*\\1*" nil)) +#+end_src + +#+name: tsd-lisp-begin +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-lisp-begin () + "Convert @lisp blocks." + (interactive) + (query-replace "@lisp" "#+begin_src emacs-lisp" t)) +#+end_src + +#+name: tsd-lisp-end +#+header: :results silent +#+header: :eval no-export +#+begin_src emacs-lisp +(defun tsd-lisp-end () + "Convert @lisp blocks." + (interactive) + (query-replace "@end lisp" "#+end_src" nil)) +#+end_src + +* Footnotes + +[fn:1] The iCalendar file will contain TODO and agenda items only. + +[fn:2] If your Emacs distribution does not come with Org, +the function ~org-version~ will not be defined. + +[fn:3] The ~master~ branch is where development takes place. + +[fn:4] The output from install-info (if any) is system dependent. In +particular, Debian and its derivatives use two different versions of +install-info. You may safely ignore the message: +#+begin_example + This is not dpkg install-info anymore, but GNU install-info + See the man page for ginstall-info for command line arguments +#+end_example +returned by install-info. + +[fn:5] If you don't use font-lock globally, turn it on in an Org +buffer with ~(add-hook 'org-mode-hook 'turn-on-font-lock)~. + +[fn:6] Please consider subscribing to the mailing list in order to +minimize the work the mailing list moderators have to do. + +[fn:7] Easy templates insert lowercase keywords and Babel dynamically +inserts ~#+results~. + +[fn:8] See the variables ~org-special-ctrl-a/e~, ~org-special-ctrl-k~, +and ~org-ctrl-k-protect-subtree~ to configure special behavior of +{{{kbd(C-a)}}}, {{{kbd(C-e)}}}, and {{{kbd(C-k)}}} in headlines. Note +also that clocking only works with headings indented less than 30 +stars. + +[fn:9] See the option ~org-cycle-global-at-bob~. + +[fn:10] The indirect buffer will contain the entire buffer, but will +be narrowed to the current tree. Editing the indirect buffer will also +change the original buffer, but without affecting visibility in that +buffer. For more information about indirect buffers, +[[info:emacs:Indirect Buffers][GNU Emacs Manual]]. + +[fn:11] If you do not want the line to be split, customize the +variable ~org-M-RET-may-split-line~. + +[fn:12] See also the variables ~org-show-hierarchy-above~, +~org-show-following-heading~, ~org-show-siblings~, and +~org-show-entry-below~ for detailed control on how much context is +shown around each match. + +[fn:13] This depends on the option ~org-remove-highlights-with-change~. + +[fn:14] This does not work under XEmacs, because XEmacs uses selective +display for outlining, not text properties. + +[fn:15] When using ~*~ as a bullet, lines must be indented or they will +be seen as top-level headlines. Also, when you are hiding leading +stars to get a clean outline view, plain list items starting with a +star may be hard to distinguish from true headlines. In short: even +though ~*~ is supported, it may be better to not use it for plain list +items. + +[fn:16] You can filter out any of them by configuring +~org-plain-list-ordered-item-terminator~. + +[fn:17] If there's a checkbox in the item, the cookie must be put +_before_ the checkbox. If you have activated alphabetical lists, you +can also use counters like ~[@b]~. + +[fn:18] Org only changes the filling settings for Emacs. For XEmacs, +you should use Kyle E. Jones' {{{file(filladapt.el)}}}. + +[fn:19] If you do not want the item to be split, customize the +variable ~org-M-RET-may-split-line~. + +[fn:20] If you want to cycle around items that way, you may customize +~org-list-use-circular-motion~. + +[fn:21] See ~org-list-use-circular-motion~ for a cyclic behavior. + +[fn:24] Centering does not work inside Emacs, but it does have an +effect when exporting to HTML. + +[fn:26] For backward compatibility you can also use special names like +~$LR5~ and ~$LR12~ to refer in a stable way to the fifth and twelfth +field in the last row of the table. However, this syntax is +deprecated, it should not be used for new documents. Use ~@>$~ +instead. + +[fn:25] Org will understand references typed by the user as +{{{samp(B4)}}}, but it will not use this syntax when offering a +formula for editing. You can customize this behavior using the +variable ~org-table-use-standard-references~. + +[fn:22] To insert a vertical bar into a table field, use ~\vert~ or, +inside a word ~abc\vert{}def~. + +[fn:23] This feature does not work on XEmacs. + +[fn:27] The computation time scales as O(N^2) because table FOO is +parsed for each field to be copied. + +[fn:28] The {{{file(calc)}}} package has the non-standard +convention that ~/~ has lower precedence than ~*~, so that ~a/b*c~ is +interpreted as ~a/(b*c)~. + +[fn:29] The ~printf~ reformatting is limited in precision because the +value passed to it is converted into an ~integer~ or ~double~. The +~integer~ is limited in size by truncating the signed value to 32 +bits. The ~double~ is limited in precision to 64 bits overall which +leaves approximately 16 significant decimal digits. + +[fn:30] Such names must start with an alphabetic character and use +only alphanumeric/underscore characters. + +[fn:31] Note that text before the first headline is usually not +exported, so the first such target should be after the first headline, +or in the line directly before the first headline. + +[fn:32] To insert a link targeting a headline, in-buffer completion +can be used. Just type a star followed by a few optional letters into +the buffer and press {{{kbdkey(M-,TAB)}}}. All headlines in the +current buffer will be offered as completions. + +[fn:33] The actual behavior of the search will depend on the value of +the variable ~org-link-search-must-match-exact-headline~. If its value +is ~nil~, then a fuzzy text search will be done. If it is ~t~, then +only the exact headline will be matched. If the value is +{{{samp('query-to-create)}}}, then an exact headline will be searched; +if it is not found, then the user will be queried to create it. + +[fn:34] If the headline contains a timestamp, it will be removed from +the link and result in a wrong link -- you should avoid putting a +timestamp in the headline. + +[fn:35] Note that you don't have to use this command to insert a link. +Links in Org are plain text, and you can type or paste them straight +into the buffer. By using this command, the links are automatically +enclosed in double brackets, and you will be asked for the optional +descriptive text. + +[fn:36] After insertion of a stored link, the link will be removed +from the list of stored links. To keep it in the list later use, use a +triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or +configure the option ~org-keep-stored-link-after-insertion~. + +[fn:37] This works if a function has been defined in the ~:complete~ +property of a link in ~org-link-parameters~. + +[fn:38] See the variable ~org-display-internal-link-with-indirect-buffer~. + +[fn:44] Check also the variable ~org-fast-tag-selection-include-todo~, +it allows you to change the TODO state through the tags interface +([[Setting tags]]), in case you like to mingle the two concepts. Note that +this means you need to come up with unique keys across both sets of +keywords. + +[fn:39] For backward compatibility, line numbers can also follow a +single colon. + +[fn:40] Of course, you can make a document that contains only long +lists of TODO items, but this is not required. + +[fn:41] Changing the variable ~org-todo-keywords~ only becomes +effective after restarting Org mode in a buffer. + +[fn:42] This is also true for the {{{kbd(t)}}} command in the timeline +and agenda buffers. + +[fn:43] All characters are allowed except ~@^!~, which have a special +meaning here. + +[fn:45] Org mode parses these lines only when Org mode is activated +after visiting a file. {{{kbd(C-c C-c)}}} with the cursor in a line +starting with {{{samp(#+)}}} is simply restarting Org mode for the +current buffer. + +[fn:46] The corresponding in-buffer setting is: ~#+STARTUP: logdone~. + +[fn:47] The corresponding in-buffer setting is: ~#+STARTUP: lognotedone~. + +[fn:48] See the variable ~org-log-states-order-reversed~. + +[fn:54] {{{kbd(C-u C-c C-c)}}} on the /first/ item of a list with no +checkbox will add checkboxes to the rest of the list. + +[fn:49] It is possible that Org mode will record two timestamps when +you are using both ~org-log-done~ and state change logging. However, +it will never prompt for two notes---if you have configured both, the +state change recording note will take precedence and cancel the +{{{samp(Closing Note)}}}. + +[fn:50] See also the option ~org-priority-start-cycle-with-default~. + +[fn:51] To keep subtasks out of the global TODO list, see the +~org-agenda-todo-list-sublevels~. + +[fn:52] With the exception of description lists. But you can allow it +by modifying ~org-list-automatic-rules~ accordingly. + +[fn:53] Set the variable ~org-hierarchical-checkbox-statistics~ if you +want such cookies to count all checkboxes below the cookie, not just +those belonging to direct children. + +[fn:55] As with all these in-buffer settings, pressing +{{{kbd(C-c C-c)}}} activates any changes in the line. + +[fn:56] This is only true if the search does not involve more complex +tests including properties (see [[Property searches]]). + +[fn:57] Keys will automatically be assigned to tags that have no +configured keys. + +[fn:58] Please note that the COLUMNS definition must be on a single +line---it is wrapped here only because of formatting constraints. + +[fn:59] Contributed packages are not part of Emacs, but are +distributed with the main distribution of Org (visit +[[http://orgmode.org]]). + +[fn:60] The Org date format is inspired by the standard ISO 8601 +date/time format. To use an alternative format, see [[Custom time +format]]. The day name is optional when you type the date yourself. +However, any dates inserted or modified by Org will add that day name, +for reading convenience. + +[fn:61] When working with the standard diary sexp functions, you need +to be very careful with the order of the arguments. That order depends +evilly on the variable ~calendar-date-style~ (or, for older Emacs +versions, ~european-calendar-style~). For example, to specify a date +December 12, 2005, the call might look like ~(diary-date 12 1 2005)~ +or ~(diary-date 1 12 2005)~ or ~(diary-date 2005 12 1)~, depending on +the settings. This has been the source of much confusion. Org mode +users can resort to special versions of these functions like +~org-date~ or ~org-anniversary~. These work just like the +corresponding ~diary-~ functions, but with stable ISO order of +arguments (year, month, day) wherever applicable, independent of the +value of ~calendar-date-style~. + +[fn:62] See the variable ~org-read-date-prefer-future~. You may +set that variable to the symbol ~time~ to even make a time before now +shift the date to tomorrow. + +[fn:63] If you don't need/want the calendar, configure the variable +~org-popup-calendar-for-date-prompt~. + +[fn:64] If you find this distracting, turn off the display with +~org-read-date-display-live~. + +[fn:65] It will still be listed on that date after it has been marked +DONE. If you don't like this, set the variable +~org-agenda-skip-scheduled-if-done~. + +[fn:66] The {{{samp(SCHEDULED)}}} and {{{samp(DEADLINE)}}} dates are +inserted on the line right below the headline. Don't put any text +between this line and the headline. + +[fn:67] Note the corresponding ~#+STARTUP~ keywords ~logredeadline~, +~lognoteredeadline~, and ~nologredeadline~. + +[fn:68] Note the corresponding ~#+STARTUP~ keywords ~logreschedule~, +~lognotereschedule~, and ~nologreschedule~. + +[fn:69] In fact, the target state is taken from, in this sequence, the +~REPEAT_TO_STATE~ property or the variable ~org-todo-repeat-to-state~. +If neither of these is specified, the target state defaults to the +first state of the TODO state sequence. + +[fn:70] You can change this using the option ~org-log-repeat~, or the +~#+STARTUP~ options ~logrepeat~, ~lognoterepeat~, and ~nologrepeat~. +With ~lognoterepeat~, you will also be prompted for a note. + +[fn:71] Clocking only works if all headings are indented with less +than 30 stars. This is a hardcoded limitation of ~lmax~ in +~org-clock-sum~. + +[fn:72] To resume the clock under the assumption that you have worked +on this task while outside Emacs, use ~(setq org-clock-persist t)~. + +[fn:73] To add an effort estimate ``on the fly'', hook a function +doing this to ~org-clock-in-prepare-hook~. + +[fn:74] The last reset of the task is recorded by the ~LAST_REPEAT~ +property. + +[fn:75] See also the variable ~org-clock-modeline-total~. + +[fn:76] The corresponding in-buffer setting is: +~#+STARTUP: lognoteclock-out~. + +[fn:77] Language terms can be set through the variable +~org-clock-clocktable-language-setup~. + +[fn:78] Note that all parameters must be specified in a single +line---the line is broken here only to fit it into the manual. + +[fn:79] On computers using Mac OS X, idleness is based on actual user +idleness, not just Emacs' idle time. For X11, you can install a +utility program {{{file(x11idle.c)}}}, available in the +~contrib/scripts~ directory of the Org git distribution, to get the +same general treatment of idleness. On other systems, idle time refers +to Emacs idle time only. + +[fn:80] You may change the property being used with the variable +~org-effort-property~. + +[fn:86] Note the corresponding ~#+STARTUP~ keywords ~logrefile~, +~lognoterefile~, and ~nologrefile~. + +[fn:81] Please select your own key, {{{kbd(C-c c)}}} is only a +suggestion. + +[fn:82] If you need one of these sequences literally, escape the +{{{kbd(%)}}} with a backslash. + +[fn:83] If you define your own link types (see [[Adding hyperlink +types]]), any property you store with ~org-store-link-props~ can be +accessed in capture templates in a similar way. + +[fn:84] This will always be the other, not the user. See the variable +~org-from-is-user-regexp~. + +[fn:85] If you move entries or Org files from one directory to +another, you may want to configure ~org-attach-directory~ to contain +an absolute path. + +[fn:87] For backward compatibility, the following also works: If there +are several such lines in a file, each specifies the archive location +for the text below it. The first such line also applies to any text +before its definition. However, using this method is /strongly/ +deprecated as it is incompatible with the outline structure of the +document. The correct method for setting multiple archive locations in +a buffer is using properties. + +[fn:94] Only tags filtering will be respected here, effort filtering +is ignored. + +[fn:88] When using the dispatcher, pressing {{{kbd(<)}}} before +selecting a command will actually limit the command to the current +file, and ignore ~org-agenda-files~ until the next dispatcher command. + +[fn:89] For backward compatibility, you can also press {{{kbd(1)}}} to +restrict to the current buffer. + +[fn:90] For backward compatibility, you can also press {{{kbd(0)}}} to +restrict to the current region/subtree. + +[fn:91] For backward compatibility, the universal prefix +{{{kbd(C-u)}}} causes all TODO entries to be listed before the agenda. +This feature is deprecated, use the dedicated TODO list, or a block +agenda instead (see [[Block agenda]]). + +[fn:92] But see [[x-agenda-skip-entry-regexp][skipping entries based on regexp]]. + +[fn:93] For backward compatibility, the following also works: if +there are several such lines in a file, each specifies the category +for the text below it. The first category also applies to any text +before the first CATEGORY line. However, using this method is +/strongly/ deprecated as it is incompatible with the outline structure +of the document. The correct method for setting multiple categories in +a buffer is using a property. + +[fn:95] Custom commands can preset a filter by binding the variable +~org-agenda-tag-filter-preset~ as an option. This filter will then be +applied to the view and persist as a basic filter through refreshes +and more secondary filtering. The filter is a global property of the +entire agenda view---in a block agenda, you should only set this in +the global options section, not in the section of an individual block. + +[fn:96] You can also create persistent custom functions through +~org-agenda-bulk-custom-functions~. + +[fn:97] The Emacs diary file is parsed for the agenda when +~org-agenda-include-diary~ is set. + +[fn:98] You can provide a description for a prefix key by inserting a +cons cell with the prefix and the description. + +[fn:99] For HTML you need to install Hrvoje Niksic's +{{{file(htmlize.el)}}}. To create PDF output, the ghostscript +{{{file(ps2pdf)}}} utility must be installed on the system. Selecting +a PDF file will also create the postscript file. + +[fn:100] If you want to store standard views like the weekly agenda or +the global TODO list as well, you need to define custom commands for +them in order to be able to specify file names. + +[fn:101] Quoting depends on the system you use, please check the FAQ +for examples. + +[fn:102] This works automatically for the HTML backend (it requires +version 1.34 of the {{{file(htmlize.el)}}} package, which is +distributed with Org). Fontified code chunks in LaTeX can be +achieved using either the listings package or the [[http://code.google.com/p/minted][minted]] package. +Refer to ~org-export-latex-listings~ documentation for details. + +[fn:103] Code in {{{samp(src)}}} blocks may also be evaluated either +interactively or on export. See [[Working with source code]] for more +information on evaluating code blocks. + +[fn:104] Adding ~-k~ to ~-n -r~ will /keep/ the labels in the source +code while using line numbers for the links, which might be useful to +explain those in an Org mode example code. + +[fn:105] Upon exit, lines starting with {{{samp(*)}}}, {{{samp(\,*)}}}, +{{{samp(#+)}}} and {{{samp(\,#+)}}} will get a comma prepended, to keep +them from being interpreted by Org as outline nodes or special syntax. +These commas will be stripped for editing with {{{kbd(C-c ')}}}, and +also for export. + +[fn:106] You may select a different-mode with the variable +~org-edit-fixed-width-region-mode~. + +[fn:107] LaTeX is a macro system based on Donald\nbsp{}E.\nbsp{}Knuth's TeX +system. Many of the features described here as LaTeX are really +from TeX, but for simplicity I am blurring this distinction. + +[fn:108] You can turn this on by default by setting the variable +~org-pretty-entities~, or on a per-file base with the ~#+STARTUP~ +option ~entitiespretty~. + +[fn:109] If you plan to use this regularly or on pages with +significant page views, you should install {{{file(MathJax)}}} on your +own server in order to limit the load of our server. + +[fn:110] For this to work you need to be on a system with a working +LaTeX installation. You also need the {{{file(dvipng)}}} program or +the {{{file(convert)}}}, respectively available at +[[http://sourceforge.net/projects/dvipng/]] and from the +{{{file(ImageMagick)}}} suite. The LaTeX header that will be used +when processing a fragment can be configured with the variable +~org-format-latex-header~. + +[fn:111] When {{{file(MathJax)}}} is used, only the environment +recognized by {{{file(MathJax)}}} will be processed. When +{{{file(dvipng)}}} is used to create images, any LaTeX environments +will be handled. + +[fn:112] Org mode has a method to test if the cursor is inside such a +fragment, see the documentation of the function +~org-inside-LaTeX-fragment-p~. + +[fn:113] The variable ~org-export-date-timestamp-format~ defines how +this timestamp will be exported. + +[fn:114] If you want to configure many options this way, you can use +several ~#+OPTIONS~ lines. + +[fn:115] To make this behavior the default, customize the variable +~org-export-run-in-background~. + +[fn:116] This requires ~transient-mark-mode~ be turned on. + +[fn:117] To select the current subtree, use {{{kbd(C-c @)}}}. + +[fn:118] This requires ~transient-mark-mode~ be turned on. + +[fn:119] To select the current subtree, use {{{kbd(C-c @)}}}. + +[fn:120] But see the variable ~org-export-html-inline-images~. + +[fn:121] If you plan to use this regularly or on pages with +significant page views, you should install MathJax on your own server +in order to limit the load of our server. Installation instructions +can be found on the MathJax website, see +[[http://www.mathjax.org/resources/docs/?installation.html]]. + +[fn:122] If the classes on TODO keywords and tags lead to conflicts, +use the variables ~org-export-html-todo-kwd-class-prefix~ and +~org-export-html-tag-class-prefix~ to make them unique. + +[fn:123] This style is defined in the constant +~org-export-html-style-default~, which you should not modify. To turn +inclusion of these defaults off, customize +~org-export-html-style-include-default~. + +[fn:124] The default LaTeX output is designed for processing with +~pdftex~ or LaTeX. It includes packages that are not compatible +with ~xetex~ and possibly ~luatex~. See the variables +~org-export-latex-default-packages-alist~ and +~org-export-latex-packages-alist~. + +[fn:125] This requires ~transient-mark-mode~ be turned on. + +[fn:126] To select the current subtree, use {{{kbd(C-c @)}}}. + +[fn:127] Into which the values of +~org-export-latex-default-packages-alist~ and +~org-export-latex-packages-alist~ are spliced. + +[fn:128] One can also take advantage of this option to pass other, +unrelated options into the figure or table environment. For an example +see the section ``Exporting org files'' in +[[http://orgmode.org/worg/org-hacks.html]]. + +[fn:129] This requires ~transient-mark-mode~ to be turned on. + +[fn:130] To select the current subtree, use {{{kbd(C-c @)}}}. + +[fn:131] ODT export was added in Org mode version 7.8. + +[fn:132] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications (OpenDocument) +Version 1.2]]. + +[fn:133] This requires ~transient-mark-mode~ to be turned on. + +[fn:134] To select the current subtree, use {{{kbd(C-c @)}}}. + +[fn:135] The column widths are interpreted as weighted ratios with the +default weight being 1. + +[fn:136] Use of {{{file(ImageMagick)}}} is only desirable. However, if +you routinely produce documents that have large images or you export +your Org files that has images using a Emacs batch script, then the +use of {{{file(ImageMagick)}}} is mandatory. + +[fn:137] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. + +[fn:138] Your {{{file(htmlfontify.el)}}} library must at least be at +Emacs 24.1 levels for fontification to be turned on. + +[fn:139] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]]. + +[fn:140] See the ~<table:table-template>~ element of the +OpenDocument-v1.2 specification. + +[fn:141] See the attributes ~table:template-name~, +~table:use-first-row-styles~, ~table:use-last-row-styles~, +~table:use-first-column-styles~, ~table:use-last-column-styles~, +~table:use-banding-rows-styles~, and ~table:use-banding-column-styles~ +of the ~<table:table>~ element in the OpenDocument-v1.2 specification. + +[fn:142] Note that {{{file(.odt)}}} files are {{{samp(zip)}}} +archives. + +[fn:143] See the variables ~org-icalendar-use-deadline~ and +~org-icalendar-use-scheduled~. + +[fn:144] To add inherited tags or the TODO state, configure the +variable ~org-icalendar-categories~. + +[fn:145] The LOCATION property can be inherited from higher in the +hierarchy if you configure ~org-use-property-inheritance~ accordingly. + +[fn:146] The files {{{file(file-source.org)}}} and +{{{file(file-source.org.html)}}} if source and publishing directories +are equal. Note that with this kind of setup, you need to add +~:exclude "-source\\.org"~ to the project definition in +~org-publish-project-alist~ to prevent the published source files from +being considered as new org files the next time the project is +published. + +[fn:147] Note that {{{samp(src)}}} blocks may be inserted using Org +mode's [[Easy templates]] system. + +[fn:148] Whenever code is evaluated there is a potential for that code +to do harm. Org mode provides safeguards to ensure that code is only +evaluated after explicit confirmation from the user. For information +on these safeguards (and on how to disable them) see [[Code evaluation +security]]. + +[fn:149] The ~org-babel-no-eval-on-ctrl-c-ctrl-c~ variable can be used +to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding. + +[fn:150] Note that evaluation of header arguments is guaranteed to +take place in the original Org mode file, while there is no such +guarantee for evaluation of the code block body. + +[fn:151] The example requires that property inheritance be turned on +for the ~noweb-ref~ property, see [[Property inheritance]]. + +[fn:152] In certain languages this also contains the error output +stream; this is an area for future work. + +[fn:153] The last evaluation performed by the interpreter is obtained +in a language-specific manner: the value of the variable ~_~ in Python +and Ruby, and the value of ~.Last.value~ in R. + +[fn:161] If the {{{samp(#+TBLFM)}}} line contains an odd number of +dollar characters, this may cause problems with font-lock in LaTeX +mode. As shown in the example you can fix this by adding an extra line +inside the ~comment~ environment that is used to balance the dollar +expressions. If you are using AUCTeX with the font-latex library, a +much better solution is to add the ~comment~ environment to the +variable ~LaTeX-verbatim-environments~. + +[fn:162] The HTML translator uses the same code that produces tables +during HTML export. + +[fn:154] Note that ~org-indent-mode~ also sets the ~wrap-prefix~ +property, such that ~visual-line-mode~ (or purely setting ~word-wrap~) +wraps long lines (including headlines) correctly indented. + +[fn:155] See the variable ~org-indent-indentation-per-level~. + +[fn:156] Turning on ~org-indent-mode~ sets ~org-hide-leading-stars~ to +~t~ and ~org-adapt-indentation~ to ~nil~. + +[fn:157] See also the variable ~org-adapt-indentation~. + +[fn:158] When you need to specify a level for a property search or +refile targets, ~LEVEL=2~ will correspond to 3 stars, etc. + +[fn:159] The {{{file(org-R.el)}}} package has been replaced by the +Org mode functionality described in [[Working with source code]] and is +now obsolete. + +[fn:160] By default this works only for LaTeX, HTML, and Texinfo. +Configure the variable ~orgtbl-radio-tables~ to install templates for +other modes. + +[fn:163] Note that, when using ~org-odd-levels-only~, a level number +corresponds to order in the hierarchy, not to the number of stars. + +[fn:164] If you can safely store the password in your Emacs setup, you +might also want to configure `org-mobile-encryption-password'. Please +read the docstring of that variable. Note that encryption will apply +only to the contents of the `.org' files. The file names themselves +will remain visible. + +[fn:165] If you cannot use Dropbox, or if your version of MobileOrg +does not support it, you can use a webdav server. For more +information, check out the documentation of MobileOrg and also this +[[http://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]]. + +[fn:166] While creating the agendas, Org mode will force ID properties +on all referenced entries, so that these entries can be uniquely +identified if /MobileOrg/ flags them for further action. If you do not +want to get these properties in so many entries, you can set the +variable ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode will +then rely on outline paths, in the hope that these will be unique +enough. + +[fn:167] Checksums are stored automatically in the file +{{{file(checksums.dat)}}}. + +[fn:168] The file {{{file(mobileorg.org)}}} will be empty after this +operation. + +[fn:169] Note, however, that there is a subtle difference. The view +created automatically by {{{kbdspckey(M-x org-mobile-pull,RET)}}} is +guaranteed to search all files that have been addressed by the last +pull. This might include a file that is not currently in your list of +agenda files. If you later use {{{kbd(C-c a ?)}}} to regenerate the +view, only the current agenda files will be searched. + +[fn:170] You can also get `a.', `A.', `a)' and `A)' by configuring +`org-alphabetical-lists'. To minimize confusion with normal text, +those are limited to one character only. Beyond that limit, bullets +will automatically fallback to numbers. + +[fn:171] See also ~org-empty-line-terminates-plain-lists~. + +[fn:172] You can define additional drawers on a per-file basis with a +line like ~#+DRAWERS: HIDDEN STATE~. + +[fn:173] The corresponding in-buffer setting is: ~#+STARTUP: fninline~ or +~#+STARTUP: nofninline~. + +[fn:174] The corresponding in-buffer options are ~#+STARTUP: fnadjust~ and +~#+STARTUP: nofnadjust~. + +[fn:175] The file {{{file(constants.el)}}} can supply the values of constants in two +different unit systems, ~SI~ and ~cgs~. Which one is used depends on +the value of the variable ~constants-unit-system~. You can use the +~#+STARTUP:~ options ~constSI~ and ~constcgs~ to set this value for the +current buffer. + +[fn:176] The library {{{file(org-id)}}} must first be loaded, either through +~org-customize~ by enabling ~id~ in ~org-modules~, or by adding +~(require 'org-id)~ in your {{{file(.emacs)}}}. + +[fn:177] The variable ~org-startup-with-inline-images~ can be set +within a buffer with the ~#+STARTUP:~ keywords ~inlineimages~ and +~noinlineimages~. + +[fn:178] Note that the ~LOGBOOK~ drawer is unfolded when pressing +{{{key(SPC)}}} in the agenda to show an entry---use +{{{kbdspckey(C-u,SPC)}}} to keep it folded here. + +[fn:179] Please note the pitfalls of summing hierarchical data in a flat +list ([[Agenda column view]]). + +[fn:180] If the value of that variable is not a list, but a single file +name, then the list of agenda files will be maintained in that external +file. + +[fn:181] The variable ~org-anniversary~ used in the example +is just like ~diary-anniversary~, but the argument order is +always according to ISO and therefore independent of the value of +~calendar-date-style~. + +[fn:182] Emacs 23 and Org mode 6.29 are required. + +[fn:183] Emacs 23.1 can actually crash with ~org-indent-mode~. + +[fn:184] Symbolic links in ~org-directory~ need to have the same name +as their targets. + + +# Local Variables: +# sentence-end-double-space: t +# End: |