diff options
author | Sébastien Delafond <sdelafond@gmail.com> | 2016-12-18 18:31:55 +0100 |
---|---|---|
committer | Sébastien Delafond <sdelafond@gmail.com> | 2016-12-18 18:31:55 +0100 |
commit | 3c1786756e434dae5960b1eed5cf1f84e4bd3a07 (patch) | |
tree | bc4c0c9d855b88134b6d1a001f12e4718744196e | |
parent | 818c794a1dceed58f42fdbd8595da59c383dabb5 (diff) |
Imported Upstream version 9.0.2
-rw-r--r-- | contrib/orgmanual.org | 19743 |
1 files changed, 0 insertions, 19743 deletions
diff --git a/contrib/orgmanual.org b/contrib/orgmanual.org deleted file mode 100644 index 8b8ae1e..0000000 --- a/contrib/orgmanual.org +++ /dev/null @@ -1,19743 +0,0 @@ -#+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: |