summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorS├ębastien Delafond <sdelafond@gmail.com>2016-12-18 18:31:55 +0100
committerS├ębastien Delafond <sdelafond@gmail.com>2016-12-18 18:31:55 +0100
commit3c1786756e434dae5960b1eed5cf1f84e4bd3a07 (patch)
treebc4c0c9d855b88134b6d1a001f12e4718744196e
parent818c794a1dceed58f42fdbd8595da59c383dabb5 (diff)
Imported Upstream version 9.0.2
-rw-r--r--contrib/orgmanual.org19743
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 ~&alpha;~ in the HTML output, and as ~$\alpha$~ in the LaTeX
-output. Similarly, ~\nbsp~ will become ~&nbsp;~ in HTML and ~~~ in
-LaTeX. If you need such a symbol inside a word, terminate it like
-this: ~\Aacute{}stor~.
-
-A large number of entities is provided, with names taken from both
-HTML and LaTeX; see the variable ~org-entities~ for the complete
-list. ~\-~ is treated as a shy hyphen, and {{{samp(--)}}},
-{{{samp(---)}}}, and {{{samp(...)}}} are all converted into special
-commands creating hyphens of different lengths or a compact set of
-dots.
-
-If you would like to see entities displayed as UTF8 characters, use the
-following command:[fn:108]
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-x XXX)}}} ::
- #+kindex: C-c C-x XXX
-# Should be \
- Toggle display of entities as UTF-8 characters. This does not change
- the buffer content which remains plain ASCII, but it overlays the
- UTF-8 character for display purposes only.
-
-*** FIXME Subscripts and superscripts
- :PROPERTIES:
- :DESCRIPTION: Simple syntax for raising/lowering text
- :END:
-#+cindex: subscript
-#+cindex: superscript
-
-Just like in LaTeX, {{{samp(^)}}} and {{{samp(_)}}} are used to
-indicate super- and subscripts. Again, these can be used without
-embedding them in math-mode delimiters. To increase the readability of
-ASCII text, it is not necessary (but OK) to surround multi-character
-sub- and superscripts with curly braces. For example
-
-#+begin_example
- The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
- the sun is R_{sun} = 6.96 x 10^8 m.
-#+end_example
-
-#+vindex: org-export-with-sub-superscripts
-
-To avoid interpretation as raised or lowered text, you can quote
-{{{kbd(^)}}} and {{{kbd(_)}}} with a backslash: ~\^~ and ~\_~. If you
-write a text where the underscore is often used in a different
-context, Org's convention to always interpret these as subscripts can
-get in your way. Configure the variable
-~org-export-with-sub-superscripts~ to globally change this convention,
-or use, on a per-file basis:
-
-#+begin_example
- ,#+OPTIONS: ^:{}
-#+end_example
-
-{{{noindent}}} With this setting, ~a_b~ will not be interpreted as a
-subscript, but ~a_{b}~ will.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-x XXX)}}} ::
- #+kindex: C-c C-x XXX
-# Should be \
- In addition to showing entities as UTF-8 characters, this command will
- also format sub- and superscripts in a WYSIWYM way.
-
-*** LaTeX fragments
- :PROPERTIES:
- :DESCRIPTION: Complex formulas made easy
- :END:
-#+cindex: @LaTeX{} fragments
-#+vindex: org-format-latex-header
-
-Going beyond symbols and sub- and superscripts, a full formula
-language is needed. Org mode can contain LaTeX math fragments, and
-it supports ways to process these for several export backends. When
-exporting to LaTeX, the code is obviously left as it is. When
-exporting to HTML, Org invokes the [[http://www.mathjax.org][MathJax library]] (see [[Math
-formatting in HTML export]]) to process and display the math.[fn:109]
-Finally, it can also process the mathematical expressions into images
-that can be displayed in a browser or in DocBook documents.[fn:110]
-
-LaTeX fragments don't need any special marking at all. The following
-snippets will be identified as LaTeX source code:
-
-- Environments of any kind.[fn:111] The only requirement is that the
- ~\begin~ statement appears on a new line, preceded by only whitespace.
-
-- Text within the usual LaTeX math delimiters. To avoid conflicts
- with currency specifications, single ~$~ characters are
- only recognized as math delimiters if the enclosed text contains at
- most two line breaks, is directly attached to the ~$~
- characters with no whitespace in between, and if the closing
- ~$~ is followed by whitespace, punctuation or a dash. For
- the other delimiters, there is no such restriction, so when in
- doubt, use ~\(...\)~ as inline math delimiters.
-
-
-{{{noindent}}} For example:
-
-#+begin_example
- \begin{equation} % arbitrary environments,
- x=\sqrt{b} % even tables, figures
- \end{equation} % etc
-
- If $a^2=b$ and \( b=2 \), then the solution must be
- either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
-#+end_example
-
-{{{noindent}}}
-#+vindex: org-format-latex-options
-
-If you need any of the delimiter ASCII sequences for other purposes,
-you can configure the option ~org-format-latex-options~ to deselect
-the ones you do not wish to have interpreted by the LaTeX
-converter.
-
-#+vindex: org-export-with-LaTeX-fragments
-
-LaTeX processing can be configured with the variable
-~org-export-with-LaTeX-fragments~. The default setting is ~t~ which
-means {{{file(MathJax)}}} for HTML, and no processing for DocBook,
-ASCII and LaTeX backends. You can also set this variable on a
-per-file basis using one of these lines:
-
-#+attr_texinfo: :table-type table :indic @asis
-- #+OPTIONS: LaTeX:t ::
-
- Do the right thing automatically (MathJax).
-
-- #+OPTIONS: LaTeX:dvipng ::
-
- Force using dvipng images.
-
-- #+OPTIONS: LaTeX:nil ::
-
- Do not process LaTeX fragments at all
-
-- #+OPTIONS: LaTeX:verbatim ::
-
- Verbatim export, for jsMath or so.
-
-*** Previewing LaTeX fragments
- :PROPERTIES:
- :DESCRIPTION: What will this snippet look like?
- :END:
-#+cindex: @LaTeX{} fragments, preview
-
-If you have {{{file(dvipng)}}} installed, LaTeX fragments can be
-processed to produce preview images of the typeset expressions:
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-x C-l)}}} ::
- #+kindex: C-c C-x C-l
-
- Produce a preview image of the LaTeX fragment at point and overlay
- it over the source code. If there is no fragment at point, process all
- fragments in the current entry (between two headlines). When called
- with a prefix argument, process the entire subtree. When called with
- two prefix arguments, or when the cursor is before the first headline,
- process the entire buffer.
-
-- {{{kbd(C-c C-c)}}} ::
- #+kindex: C-c C-c
-
- Remove the overlay preview images.
-
-
-#+vindex: org-format-latex-options
-
-You can customize the variable ~org-format-latex-options~ to influence
-some aspects of the preview. In particular, the ~:scale~ (and for HTML
-export, ~:html-scale~) property can be used to adjust the size of the
-preview images.
-
-*** CDLaTeX mode
- :PROPERTIES:
- :DESCRIPTION: Speed up entering of formulas
- :TITLE: Using CDLaTeX to enter math
- :END:
-#+cindex: CD@LaTeX{}
-
-CDLaTeX mode is a minor mode that is normally used in combination
-with a major LaTeX mode like AUCTeX in order to speed-up
-insertion of environments and math templates. Inside Org mode, you can
-make use of some of the features of CDLaTeX mode. You need to
-install {{{file(cdlatex.el)}}} and {{{file(texmathp.el)}}} (the latter
-comes also with AUCTeX) from
-[[http://www.astro.uva.nl/~dominik/Tools/cdlatex]]. Don't use CDLaTeX
-mode itself under Org mode, but use the light version
-~org-cdlatex-mode~ that comes as part of Org mode. Turn it on for the
-current buffer with ~M-x org-cdlatex-mode~, or for all Org files with
-this hook:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
-#+end_src
-
-When this mode is enabled, the following features are present (for more
-details see the documentation of CDLaTeX mode):
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c {)}}} ::
- #+kindex: C-c @{
-
- Insert an environment template.
-
-- {{{key(TAB)}}} ::
- #+kindex: @key{TAB}
-
- Expand a template if the cursor is inside a LaTeX fragment.[fn:112]
- For example, {{{key(TAB)}}} will expand ~fr~ to ~\frac{}{}~ and
- position the cursor correctly inside the first brace. Another
- {{{key(TAB)}}} will get you into the second brace. Even outside
- fragments, {{{key(TAB)}}} will expand environment abbreviations at the
- beginning of a line. For example, if you write {{{samp(equ)}}} at the
- beginning of a line and press {{{key(TAB)}}}, this abbreviation will
- be expanded to an ~equation~ environment. To get a list of all
- abbreviations, type {{{kbd(M-x cdlatex-command-help)}}}.
-
-- {{{kbd(_)}}} {{{kbd(^)}}} ::
- #+kindex: _
- #+kindex: ^
- #+vindex: cdlatex-simplify-sub-super-scripts
-
- Pressing {{{kbd(_)}}} and {{{kbd(^)}}} inside a LaTeX fragment will
- insert these characters together with a pair of braces. If you use
- {{{key(TAB)}}} to move out of the braces, and if the braces surround
- only a single character or macro, they are removed again (depending on
- the variable ~cdlatex-simplify-sub-super-scripts~).
-
-- {{{kbd(`)}}} ::
- #+kindex: `
-
- Pressing the backquote followed by a character inserts math macros,
- also outside LaTeX fragments. If you wait more than 1.5 seconds
- after the backquote, a help window will pop up.
-
-- {{{kbd(')}}} ::
- #+kindex: '
-
- Pressing the single-quote followed by another character modifies the
- symbol before point with an accent or a font. If you wait more than
- 1.5 seconds after the single-quote, a help window will pop up.
- Character modification will work only inside LaTeX fragments;
- outside the quote is normal.
-
-* FIXME Exporting
- :PROPERTIES:
- :DESCRIPTION: Sharing and publishing notes
- :END:
-#+cindex: exporting
-
-Org mode documents can be exported into a variety of other formats.
-For printing and sharing of notes, ASCII export produces a readable
-and simple version of an Org file. HTML export allows you to publish a
-notes file on the web, while the XOXO format provides a solid base for
-exchange with a broad range of other applications. LaTeX export
-lets you use Org mode and its structured editing functions to easily
-create LaTeX files. DocBook export makes it possible to convert Org
-files to many other formats using DocBook tools. OpenDocument Text
-(ODT) export allows seamless collaboration across organizational
-boundaries. For project management you can create gantt and resource
-charts by using TaskJuggler export. To incorporate entries with
-associated times like deadlines or appointments into a desktop
-calendar program like iCal, Org mode can also produce extracts in the
-iCalendar format. Currently, Org mode only supports export, not import
-of these different formats.
-
-Org supports export of selected regions when ~transient-mark-mode~ is
-enabled (default in Emacs 23).
-
-** Selective export
- :PROPERTIES:
- :DESCRIPTION: Using tags to select and exclude trees
- :END:
-#+cindex: export, selective by tags or TODO keyword
-#+vindex: org-export-select-tags
-#+vindex: org-export-exclude-tags
-#+cindex: org-export-with-tasks
-
-You may use tags to select the parts of a document that should be exported,
-or to exclude parts from export. This behavior is governed by two variables:
-~org-export-select-tags~ and ~org-export-exclude-tags~,
-respectively defaulting to ~:export:~ and ~:noexport:~.
-
-1. Org first checks if any of the /select/ tags is present in the
- buffer. If yes, all trees that do not carry one of these tags will
- be excluded. If a selected tree is a subtree, the heading hierarchy
- above it will also be selected for export, but not the text below
- those headings.
-
-2. If none of the select tags is found, the whole buffer will be
- selected for export.
-
-3. Finally, all subtrees that are marked by any of the /exclude/ tags
- will be removed from the export buffer.
-
-
-The variable ~org-export-with-tasks~ can be configured to select which
-kind of tasks should be included for export. See the docstring of the
-variable for more information.
-
-** FIXME Export options
- :PROPERTIES:
- :DESCRIPTION: Per-file export settings
- :END:
-#+cindex: options, for export
-#+cindex: completion, of option keywords
-
-The exporter recognizes special lines in the buffer which provide
-additional information. These lines may be put anywhere in the file.
-The whole set of lines can be inserted into the buffer with
-{{{kbd(C-c C-e t)}}}. For individual lines, a good way to make sure the keyword
-is correct is to type {{{samp(#+)}}} and then use {{{kbdkey(M-,TAB)}}}
-completion (see [[Completion]]). For a summary of other in-buffer settings
-not specifically related to export, see [[In-buffer settings]]. In
-particular, note that you can place commonly-used (export) options in
-a separate file which can be included using ~#+SETUPFILE~.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e t)}}}, ~org-insert-export-options-template~ ::
- #+kindex: C-c C-e t
-
- Insert template with export options, see example below.
-
-
-#+cindex: #+TITLE
-#+cindex: #+AUTHOR
-#+cindex: #+DATE
-#+cindex: #+EMAIL
-#+cindex: #+DESCRIPTION
-#+cindex: #+KEYWORDS
-#+cindex: #+LANGUAGE
-#+cindex: #+TEXT
-#+cindex: #+OPTIONS
-#+cindex: #+BIND
-#+cindex: #+LINK_UP
-#+cindex: #+LINK_HOME
-#+cindex: #+EXPORT_SELECT_TAGS
-#+cindex: #+EXPORT_EXCLUDE_TAGS
-#+cindex: #+XSLT
-#+cindex: #+LaTeX_HEADER
-#+vindex: user-full-name
-#+vindex: user-mail-address
-#+vindex: org-export-default-language
-#+vindex: org-export-date-timestamp-format
-
-#+attr_texinfo: :table-type table :indic @asis
-- #+TITLE: ::
-
- The title to be shown (default is the buffer name).
-
-- #+AUTHOR: ::
-
- The author (default taken from ~user-full-name~).
-
-- #+DATE: ::
-
- A date, an Org timestamp, or a format string for
- ~format-time-string~.[fn:113]
-
-- #+EMAIL: ::
-
- His/her email address (default from ~user-mail-address~).
-
-- #+DESCRIPTION: ::
-
- The page description, e.g., for the XHTML meta tag.
-
-- #+KEYWORDS: ::
-
- The page keywords, e.g., for the XHTML meta tag.
-
-- #+LANGUAGE: ::
-
- Language for HTML, e.g., en (~org-export-default-language~).
-
-- #+TEXT: ::
-
- Some descriptive text to be inserted at the beginning.
-
-- #+TEXT: ::
-
- Several lines may be given.
-
-- #+OPTIONS: ::
-
- H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
-
-- #+BIND: ::
-
- Lisp-var lisp-val, e.g., org-export-latex-low-levels itemize. You need
- to confirm using these, or configure ~org-export-allow-BIND~.
-
-- #+LINK_UP: ::
-
- The ``up'' link of an exported page.
-
-- #+LINK_HOME: ::
-
- The ``home'' link of an exported page.
-
-- #+LaTeX_HEADER: ::
-
- Extra line(s) for the LaTeX header, like ~\usepackage{xyz}~.
-
-- #+EXPORT_SELECT_TAGS: ::
-
- Tags that select a tree for export.
-
-- #+EXPORT_EXCLUDE_TAGS: ::
-
- Tags that exclude a tree from export.
-
-- #+XSLT: ::
-
- The XSLT stylesheet used by DocBook exporter to generate FO file.
-
-
-
-{{{noindent}}} The ~#+OPTIONS~ line is a compact form to specify
-export settings.[fn:114] Here you can:
-
-#+cindex: headline levels
-#+cindex: section-numbers
-#+cindex: table of contents
-#+cindex: line-break preservation
-#+cindex: quoted HTML tags
-#+cindex: fixed-width sections
-#+cindex: tables
-#+cindex: @TeX{}-like syntax for sub- and superscripts
-#+cindex: footnotes
-#+cindex: special strings
-#+cindex: emphasized text
-#+cindex: @TeX{} macros
-#+cindex: @LaTeX{} fragments
-#+cindex: author info, in export
-#+cindex: time info, in export
-#+vindex: org-export-plist-vars
-#+vindex: org-export-author-info
-#+vindex: org-export-creator-info
-#+vindex: org-export-email-info
-#+vindex: org-export-time-stamp-file
-
-#+attr_texinfo: :table-type table :indic @code
-- H: ::
-
- Set the number of headline levels for export.
-
-- num: ::
-
- Turn on/off section-numbers.
-
-- toc: ::
-
- Turn on/off table of contents, or set level limit (integer).
-
-- \n: ::
-
- Turn on/off line-break-preservation (DOES NOT WORK).
-
-- @: ::
-
- Turn on/off quoted HTML tags.
-
-- :: ::
-
- Turn on/off fixed-width sections.
-
-- |: ::
-
- Turn on/off tables,
-
-- ^: ::
-
- Turn on/off TeX-like syntax for sub- and superscripts. If you write
- "^:{}", ~a_{b}~ will be interpreted, but the simple ~a_b~ will be left
- as it is.
-
-- : ::
-
- Turn on/off conversion of special strings.
-
-- f: ::
-
- Turn on/off footnotes like this: ~[1]~.
-
-- todo: ::
-
- Turn on/off inclusion of TODO keywords into exported text.
-
-- tasks: ::
-
- Turn on/off inclusion of tasks (TODO items), can be nil to remove all
- tasks, ~todo~ to remove DONE tasks, or list of keywords to keep.
-
-- pri: ::
-
- Turn on/off priority cookies.
-
-- tags: ::
-
- Turn on/off inclusion of tags, may also be ~not-in-toc~.
-
-- <: ::
-
- Turn on/off inclusion of any time/date stamps like DEADLINES.
-
-- *: ::
-
- Turn on/off emphasized text (bold, italic, underlined).
-
-- TeX: ::
-
- Turn on/off simple TeX macros in plain text.
-
-- LaTeX: ::
-
- Configure export of LaTeX fragments. Default ~auto~.
-
-- skip: ::
-
- Turn on/off skipping the text before the first heading.
-
-- author: ::
-
- Turn on/off inclusion of author name/email into exported file.
-
-- email: ::
-
- Turn on/off inclusion of author email into exported file.
-
-- creator: ::
-
- Turn on/off inclusion of creator info into exported file.
-
-- timestamp: ::
-
- Turn on/off inclusion creation time into exported file.
-
-- d: ::
-
- Turn on/off inclusion of drawers, or list drawers to include.
-
-
-{{{noindent}}} These options take effect in both the HTML and LaTeX
-export, except for ~TeX~ and ~LaTeX~ options, which are respectively
-~t~ and ~nil~ for the LaTeX export.
-
-The default values for these and many other options are given by a set
-of variables. For a list of such variables, the corresponding OPTIONS
-keys and also the publishing keys (see [[Project alist]]), see the
-constant ~org-export-plist-vars~.
-
-When exporting only a single subtree by selecting it with
-{{{kbd(C-c @)}}} before calling an export command, the subtree can
-overrule some of the file's export settings with properties
-~EXPORT_FILE_NAME~, ~EXPORT_TITLE~, ~EXPORT_TEXT~, ~EXPORT_AUTHOR~,
-~EXPORT_DATE~, and ~EXPORT_OPTIONS~.
-
-** The export dispatcher
- :PROPERTIES:
- :DESCRIPTION: How to access exporter commands
- :END:
-#+cindex: dispatcher, for export commands
-
-All export commands can be reached using the export dispatcher, which
-is a prefix key that prompts for an additional key specifying the
-command. Normally the entire file is exported, but if there is an
-active region that contains one outline tree, the first heading is
-used as document title and the subtrees are exported.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e)}}}, ~org-export~ ::
- #+kindex: C-c C-e
- #+vindex: org-export-run-in-background
-
- Dispatcher for export and publishing commands. Displays a help-window
- listing the additional key(s) needed to launch an export or publishing
- command. The prefix arg is passed through to the exporter. A double
- prefix {{{kbd(C-u C-u)}}} causes most commands to be executed in the
- background, in a separate Emacs process.[fn:115]
-
-- {{{kbd(C-c C-e v)}}}, ~org-export-visible~ ::
- #+kindex: C-c C-e v
-
- Like {{{kbd(C-c C-e)}}}, but only export the text that is currently visible
- (i.e., not hidden by outline visibility).
-
-- {{{kbd(C-u C-u C-c C-e)}}}, ~org-export~ ::
- #+kindex: C-u C-u C-c C-e
- #+vindex: org-export-run-in-background
-
- Call the exporter, but reverse the setting of
- ~org-export-run-in-background~, i.e., request background processing if
- not set, or force processing in the current Emacs process if set.
-
-** ASCII/Latin-1/UTF-8 export
- :PROPERTIES:
- :DESCRIPTION: Exporting to flat files with encoding
- :END:
-#+cindex: ASCII export
-#+cindex: Latin-1 export
-#+cindex: UTF-8 export
-
-ASCII export produces a simple and very readable version of an Org
-mode file, containing only plain ASCII. Latin-1 and UTF-8 export
-augment the file with special characters and symbols available in
-these encodings.
-
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient-mark-mode
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e a)}}}, ~org-export-as-ascii~ ::
- #+kindex: C-c C-e a
- #+cindex: property, EXPORT_FILE_NAME
-
- Export as an ASCII file. For an Org file, {{{file(myfile.org)}}}, the
- ASCII file will be {{{file(myfile.txt)}}}. The file will be
- overwritten without warning. If there is an active region, only the
- region will be exported.[fn:116] If the selected region is a single
- tree, the tree head will become the document title.[fn:117] If the
- tree head entry has or inherits an ~EXPORT_FILE_NAME~ property, that
- name will be used for the export.
-
-- {{{kbd(C-c C-e A)}}}, ~org-export-as-ascii-to-buffer~ ::
- #+kindex: C-c C-e A
-
- Export to a temporary buffer. Do not create a file.
-
-- {{{kbd(C-c C-e n)}}}, ~org-export-as-latin1~ ::
- #+kindex: C-c C-e n
-
- Like {{{kbd(C-c C-e a)}}}, but use Latin-1 encoding.
-
-- {{{kbd(C-c C-e N)}}}, ~org-export-as-latin1-to-buffer~ ::
- #+kindex: C-c C-e N
-
- Like {{{kbd(C-c C-e A)}}}, but use Latin-1 encoding.
-
-- {{{kbd(C-c C-e u)}}}, ~org-export-as-utf8~ ::
- #+kindex: C-c C-e u
-
- Like {{{kbd(C-c C-e a)}}}, but use UTF-8 encoding.
-
-- {{{kbd(C-c C-e U)}}}, ~org-export-as-utf8-to-buffer~ ::
- #+kindex: C-c C-e U
-
- Like {{{kbd(C-c C-e A)}}}, but use UTF-8 encoding.
-
-
-- {{{kbd(C-c C-e v a/n/u)}}} ::
- #+kindex: C-c C-e v a
- #+kindex: C-c C-e v n
- #+kindex: C-c C-e v u
-
- Export only the visible part of the document.
-
-
-#+cindex: headline levels, for exporting
-
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as itemized lists. If you want that transition to
-occur at a different level, specify it with a prefix argument, e.g.:
-
-#+begin_example
- C-1 C-c C-e a
-#+end_example
-
-{{{noindent}}} This setting creates only top level headlines and
-exports the rest as items. When headlines are converted to items, the
-indentation of the text following the headline is changed to fit
-nicely under the item. This is done with the assumption that the first
-body line indicates the base indentation of the body text. Any
-indentation larger than this is adjusted to preserve the layout
-relative to the first line. Should there be lines with less
-indentation than the first one, these are left alone.
-
-#+vindex: org-export-ascii-links-to-notes
-
-Links will be exported in a footnote-like style, with the descriptive
-part in the text and the link in a note before the next heading. See
-the variable ~org-export-ascii-links-to-notes~ for details and other
-options.
-
-** HTML export
- :PROPERTIES:
- :DESCRIPTION: Exporting to HTML
- :END:
-#+cindex: HTML export
-#+cindex: Gruber, John
-
-Org mode contains a HTML (XHTML 1.0 strict) exporter with extensive
-HTML formatting, in ways similar to John Gruber's /markdown/ language,
-but with additional support for tables.
-
-*** HTML export commands
- :PROPERTIES:
- :DESCRIPTION: How to invoke HTML export
- :END:
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient-mark-mode
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e h)}}}, ~org-export-as-html~ ::
- #+kindex: C-c C-e h
- #+cindex: property, EXPORT_FILE_NAME
-
- Export as an HTML file. For an Org file {{{file(myfile.org)}}}, the
- HTML file will be {{{file(myfile.html)}}}. The file will be
- overwritten without warning. If there is an active region, only the
- active region will be exported.[fn:118] If the selected region is a
- single tree, the tree head will become the document title.[fn:119] If
- the tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property,
- that name will be used for the export.
-
-- {{{kbd(C-c C-e b)}}}, ~org-export-as-html-and-open~ ::
- #+kindex: C-c C-e b
-
- Export as a HTML file and immediately open it with a browser.
-
-- {{{kbd(C-c C-e H)}}}, ~org-export-as-html-to-buffer~ ::
- #+kindex: C-c C-e H
-
- Export to a temporary buffer. Do not create a file.
-
-- {{{kbd(C-c C-e R)}}}, ~org-export-region-as-html~ ::
- #+kindex: C-c C-e R
-
- Export the active region to a temporary buffer. With a prefix
- argument, do not produce the file header and footer, but just the
- plain HTML section for the region. This is good for cut-and-paste
- operations.
-
-- {{{kbd(C-c C-e v h/b/H/R)}}} ::
- #+kindex: C-c C-e v h
- #+kindex: C-c C-e v b
- #+kindex: C-c C-e v H
- #+kindex: C-c C-e v R
-
- Export only the visible part of the document.
-
-- {{{kbd(M-x org-export-region-as-html)}}} ::
-
- Convert the region to HTML under the assumption that it was in Org
- mode syntax before. This is a global command that can be invoked in
- any buffer.
-
-- {{{kbd(M-x org-replace-region-by-HTML)}}} ::
-
- Replace the active region (assumed to be in Org mode syntax) by HTML
- code.
-
-
-#+cindex: headline levels, for exporting
-
-In the exported version, the first three outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as itemized lists. If you want that transition to
-occur at a different level, specify it with a numeric prefix argument,
-e.g.:
-
-#+begin_example
- C-2 C-c C-e b
-#+end_example
-
-{{{noindent}}} This setting creates two levels of headings and exports
-the rest as list items.
-
-*** HTML preamble and postamble
- :PROPERTIES:
- :DESCRIPTION: How to insert a preamble and postamble
- :END:
-#+vindex: org-export-html-preamble
-#+vindex: org-export-html-postamble
-#+vindex: org-export-html-preamble-format
-#+vindex: org-export-html-postamble-format
-#+vindex: org-export-html-validation-link
-#+vindex: org-export-author-info
-#+vindex: org-export-email-info
-#+vindex: org-export-creator-info
-#+vindex: org-export-time-stamp-file
-
-The HTML exporter lets you define a preamble and a postamble.
-
-The default value for ~org-export-html-preamble~ is ~t~, which means
-that the preamble is inserted depending on the relevant format string
-in ~org-export-html-preamble-format~.
-
-Setting ~org-export-html-preamble~ to a string will override the default
-format string. Setting it to a function, will insert the output of the
-function, which must be a string; such a function takes no argument but you
-can check against the value of ~opt-plist~, which contains the list of
-publishing properties for the current file. Setting to ~nil~ will not
-insert any preamble.
-
-The default value for ~org-export-html-postamble~ is
-{{{samp('auto)}}}, which means that the HTML exporter will look for
-the value of ~org-export-author-info~, ~org-export-email-info~,
-~org-export-creator-info~ and ~org-export-time-stamp-file~,
-~org-export-html-validation-link~ and build the postamble from these
-values. Setting ~org-export-html-postamble~ to ~t~ will insert the
-postamble from the relevant format string found in
-~org-export-html-postamble-format~. Setting it to ~nil~ will not
-insert any postamble.
-
-*** Quoting HTML tags
- :PROPERTIES:
- :DESCRIPTION: Using direct HTML in Org mode
- :END:
-
-Plain ~<~ and {{{samp(>)}}} are always transformed to
-{{{samp(&lt;)}}} and {{{samp(&gt;)}}} in HTML export. If you want to
-include simple HTML tags which should be interpreted as such, mark
-them with {{{samp(@)}}} as in {{{samp(@<b>bold text@</b>)}}}. Note
-that this really works only for simple tags. For more extensive HTML
-that should be copied verbatim to the exported file use either ~#+HTML~:
-
-#+cindex: #+HTML
-#+cindex: #+BEGIN_HTML
-#+begin_example
- ,#+HTML: Literal HTML code for export
-#+end_example
-
-{{{noindent}}} or an HTML block:
-#+cindex: #+BEGIN_HTML
-
-#+begin_example
- #+BEGIN_HTML
- All lines between these markers are exported literally
- #+END_HTML
-#+end_example
-
-*** Links in HTML export
- :PROPERTIES:
- :DESCRIPTION: How links will be interpreted and formatted
- :END:
-#+cindex: links, in HTML export
-#+cindex: internal links, in HTML export
-#+cindex: external links, in HTML export
-
-Internal links (see [[Internal links]]) will continue to work in HTML.
-This includes automatic links created by radio targets (see [[Radio
-targets]]). Links to external files will still work if the target file
-is on the same /relative/ path as the published Org file. Links to
-other {{{file(.org)}}} files will be translated into HTML links under
-the assumption that a HTML version also exists of the linked file, at
-the same relative path. ~id:~ links can then be used to jump
-to specific entries across files. For information related to linking
-files while publishing them to a publishing directory see [[Publishing
-links]].
-
-If you want to specify attributes for links, you can do so using a
-special ~#+ATTR_HTML~ line to define attributes that will be added to
-the ~<a>~ or ~<img>~ tags. Here is an example that sets ~title~ and
-~style~ attributes for a link:
-
-#+cindex: #+ATTR_HTML
-#+begin_example
- ,#+ATTR_HTML: title="The Org mode homepage" style="color:red;"
- ,[[http://orgmode.org]]
-#+end_example
-
-*** Tables in HTML export
- :PROPERTIES:
- :DESCRIPTION: How to modify the formatting of tables
- :END:
-#+cindex: tables, in HTML
-#+vindex: org-export-html-table-tag
-
-Org mode tables are exported to HTML using the table tag defined in
-~org-export-html-table-tag~. The default setting makes tables without
-cell borders and frame. If you would like to change this for
-individual tables, place something like the following before the
-table:
-
-#+cindex: #+CAPTION
-#+cindex: #+ATTR_HTML
-#+begin_example
- ,#+CAPTION: This is a table with lines around and between cells
- ,#+ATTR_HTML: border="2" rules="all" frame="border"
-#+end_example
-
-*** Images in HTML export
- :PROPERTIES:
- :DESCRIPTION: How to insert figures into HTML output
- :END:
-#+cindex: images, inline in HTML
-#+cindex: inlining images in HTML
-#+vindex: org-export-html-inline-images
-
-HTML export can inline images given as links in the Org file, and it
-can make an image the clickable part of a link. By default, images are
-inlined if a link does not have a description.[fn:120] So
-~[[file:myimg.jpg]]~ will be inlined, while ~[[file:myimg.jpg][the
-image]]~ will just produce a link {{{samp(the image)}}} that points to
-the image. If the description part itself is a ~file:~ link or
-a ~http:~ URL pointing to an image, this image will be inlined and
-activated so that clicking on the image will activate the link. For
-example, to include a thumbnail that will link to a high resolution
-version of the image, you could use:
-
-#+begin_example
- [[file:highres.jpg][file:thumb.jpg]]
-#+end_example
-
-If you need to add attributes to an inlined image, use a ~#+ATTR_HTML~.
-In the example below we specify the ~alt~ and ~title~ attributes to
-support text viewers and accessibility, and align it to the right.
-
-#+cindex: #+CAPTION
-#+cindex: #+ATTR_HTML
-#+begin_example
- ,#+CAPTION: A black cat stalking a spider
- ,#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
- [[./img/a.jpg]]
-#+end_example
-
-{{{noindent}}} You could use ~http~ addresses just as well.
-
-*** Math formatting in HTML export
- :PROPERTIES:
- :DESCRIPTION: Beautiful math also on the web
- :END:
-#+cindex: MathJax
-#+cindex: dvipng
-
-LaTeX math snippets (see [[LaTeX fragments]]) can be displayed in two
-different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax system]]
-which should work out of the box with Org mode installation because
-~http://orgmode.org~ serves {{{file(MathJax)}}} for Org mode users for
-small applications and for testing purposes.[fn:121] To configure
-{{{file(MathJax)}}}, use the variable
-~org-export-html-mathjax-options~ or insert something like the
-following into the buffer:
-
-#+begin_example
- ,#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
-#+end_example
-
-{{{noindent}}} See the docstring of the variable
-~org-export-html-mathjax-options~ for the meaning of the parameters in
-this line.
-
-If you prefer, you can also request that LaTeX fragments are
-processed into small images that will be inserted into the browser
-page. Before the availability of MathJax, this was the default method
-for Org files. This method requires that the {{{file(dvipng)}}}
-program is available on your system. You can still get this processing
-with the following option:
-
-#+begin_example
- ,#+OPTIONS: LaTeX:dvipng
-#+end_example
-
-*** Text areas in HTML export
- :PROPERTIES:
- :DESCRIPTION: An alternate way to show an example
- :END:
-#+cindex: text areas, in HTML
-
-An alternative way to publish literal code examples in HTML is to use
-text areas, where the example can even be edited before pasting it
-into an application. It is triggered by a ~-t~ switch at an ~example~
-or ~src~ block. Using this switch disables any options for syntax and
-label highlighting, and line numbering, which may be present. You may
-also use ~-h~ and ~-w~ switches to specify the height and width of the
-text area, which default to the number of lines in the example, and
-80, respectively. For example
-
-#+begin_example
- ,#+BEGIN_EXAMPLE -t -w 40
- (defun org-xor (a b)
- "Exclusive or."
- (if a (not b) b))
- ,#+END_EXAMPLE
-#+end_example
-
-*** CSS support
- :PROPERTIES:
- :DESCRIPTION: Changing the appearance of the output
- :END:
-#+cindex: CSS, for HTML export
-#+cindex: HTML export, CSS
-#+vindex: org-export-html-todo-kwd-class-prefix
-#+vindex: org-export-html-tag-class-prefix
-
-You can also give style information for the exported file. The HTML
-exporter assigns the following special CSS classes to appropriate
-parts of the document---your style specifications may change these, in
-addition to any of the standard classes like for headlines, tables,
-etc.[fn:122]
-
-#+attr_texinfo: :table-type table :indic @code
-- p.author :: author information, including email
-- p.date :: publishing date
-- p.creator :: creator info, about org mode version
-- .title :: document title
-- .todo :: TODO keywords, all not-done states
-- .done :: the DONE keywords, all states that count as done
-- .WAITING :: each TODO keyword also uses a class named after itself
-- .timestamp :: timestamp
-- .timestamp-kwd :: keyword associated with a timestamp, like SCHEDULED
-- .timestamp-wrapper :: span around keyword plus timestamp
-- .tag :: tag in a headline
-- ._HOME :: each tag uses itself as a class, "@" replaced by "_"
-- .target :: target for links
-- .linenr :: the line number in a code example
-- .code-highlighted :: for highlighting referenced code lines
-- div.outline-N :: div for outline level N (headline plus text))
-- div.outline-text-N :: extra div for text at outline level N
-- .section-number-N :: section number in headlines, different for each level
-- div.figure :: how to format an inlined image
-- pre.src :: formatted source code
-- pre.example :: normal example
-- p.verse :: verse paragraph
-- div.footnotes :: footnote section headline
-- p.footnote :: footnote definition paragraph, containing a footnote
-- .footref :: a footnote reference number (always a <sup>)
-- .footnum :: footnote number in footnote definition (always <sup>)
-
-
-#+vindex: org-export-html-style-default
-#+vindex: org-export-html-style-include-default
-#+vindex: org-export-html-style
-#+vindex: org-export-html-extra
-#+vindex: org-export-html-style-default
-
-Each exported file contains a compact default style that defines these
-classes in a basic way.[fn:123] You may overwrite these
-settings, or add to them by using the variables ~org-export-html-style~
-(for Org-wide settings) and ~org-export-html-style-extra~ (for more
-fine-grained settings, like file-local settings). To set the latter variable
-individually for each file, you can use a ~#+STYLE:~ line:
-
-#+cindex: #+STYLE
-#+begin_example
- ,#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
-#+end_example
-
-{{{noindent}}} For longer style definitions, you can use several such
-lines. You could also directly write a ~<style>~ ~</style>~ section in
-this way, without referring to an external file.
-
-In order to add styles to a subtree, use the ~:HTML_CONTAINER_CLASS:~
-property to assign a class to the tree. In order to specify CSS styles
-for a particular headline, you can use the id specified in a
-~:CUSTOM_ID:~ property.
-
-# FIXME: More about header and footer styles
-# FIXME: Talk about links and targets.
-
-*** JavaScript support
- :PROPERTIES:
- :DESCRIPTION: Info and folding in a web browser
- :END:
-#+cindex: Rose, Sebastian
-
-Sebastian Rose has written a JavaScript program especially designed to
-enhance the web viewing experience of HTML files created with Org. This
-program allows you to view large files in two different ways. The first one
-is an /Info/-like mode where each section is displayed separately and
-navigation can be done with the {{{kbd(n)}}} and {{{kbd(p)}}} keys (and some other keys
-as well, press {{{kbd(?)}}} for an overview of the available keys). The second
-view type is a /folding/ view much like Org provides inside Emacs. The
-script is available at [[http://orgmode.org/org-info.js]] and you can find
-the documentation for it at [[http://orgmode.org/worg/code/org-info-js/]].
-We host the script at our site, but if you use it a lot, you might
-not want to be dependent on ~orgmode.org~ and prefer to install a local
-copy on your own web server.
-
-To use the script, you need to make sure that the
-{{{file(org-jsinfo.el)}}} module gets loaded. It should be loaded by
-default, but you can try {{{ksksksk(M-x customize-variable,RET,org-modules,RET)}}}
-to convince yourself that this is indeed the case. All it then takes to make use of the program
-is adding a single line to the Org file:
-
-#+cindex: #+INFOJS_OPT
-#+begin_example
- ,#+INFOJS_OPT: view:info toc:nil
-#+end_example
-
-{{{noindent}}} If this line is found, the HTML header will
-automatically contain the code needed to invoke the script. Using the
-line above, you can set the following viewing options:
-
-#+attr_texinfo: :table-type table :indic @code
-- path: ::
-
- The path to the script. The default is to grab the script from
- [[http://orgmode.org/org-info.js]], but you might want to have
- a local copy and use a path like {{{samp(../scripts/org-info.js)}}}.
-
-- view: ::
-
- Initial view when the website is first shown. Possible values are:
-
- - info :: Info-like interface with one section per page.
- - overview :: Folding interface, initially showing only top-level.
- - content :: Folding interface, starting with all headlines visible.
- - showall :: Folding interface, all headlines and text visible.
-
-- sdepth: ::
-
- Maximum headline level that will still become an independent section
- for info and folding modes. The default is taken from
- ~org-export-headline-levels~ (= the ~H~ switch in ~#+OPTIONS~). If
- this is smaller than in ~org-export-headline-levels~, each
- info/folding section can still contain child headlines.
-
-- toc: ::
-
- Should the table of contents /initially/ be visible? Even when ~nil~,
- you can always get to the "toc" with {{{kbd(i)}}}.
-
-- tdepth: ::
-
- The depth of the table of contents. The defaults are taken from the
- variables ~org-export-headline-levels~ and ~org-export-with-toc~.
-
-- ftoc: ::
-
- Does the CSS of the page specify a fixed position for the "toc"? If
- yes, the toc will never be displayed as a section.
-
-- ltoc: ::
-
- Should there be short contents (children) in each section? Make this
- ~above~ if the section should be above initial text.
-
-- mouse: ::
-
- Headings are highlighted when the mouse is over them. Should be
- {{{samp(underline)}}} (default) or a background color like
- {{{samp(#cccccc)}}}.
-
-- buttons: ::
-
- Should view-toggle buttons be everywhere? When ~nil~ (the default),
- only one such button will be present.
-
-
-#+vindex: org-infojs-options
-#+vindex: org-export-html-use-infojs
-
-{{{noindent}}} You can choose default values for these options by
-customizing the variable ~org-infojs-options~. If you always want to
-apply the script to your pages, configure the variable
-~org-export-html-use-infojs~.
-
-** LaTeX and PDF export
- :PROPERTIES:
- :DESCRIPTION: Exporting to LaTeX and processing to PDF
- :END:
-#+cindex: @LaTeX{} export
-#+cindex: PDF export
-#+cindex: Guerry, Bastien
-
-Org mode contains a LaTeX exporter written by Bastien Guerry. With
-further processing, this backend is also used to produce PDF
-output.[fn:124] Since the LaTeX output uses {{{file(hyperref)}}} to
-implement links and cross references, the PDF output file will be
-fully linked. Beware of the fact that your ~org~ file has to be
-properly structured in order to be correctly exported: respect the
-hierarchy of sections.
-
-*** LaTeX/PDF export commands
- :PROPERTIES:
- :DESCRIPTION: Invoking export to LaTeX/PDF
- :END:
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient-mark-mode
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e l)}}}, ~org-export-as-latex~ ::
- #+kindex: C-c C-e l
- #+cindex: property EXPORT_FILE_NAME
-
- Export as a LaTeX file. For an Org file {{{file(myfile.org)}}}, the
- LaTeX file will be {{{file(myfile.tex)}}}. The file will be
- overwritten without warning. If there is an active region, only the
- active region will be exported.[fn:125] If the selected region is a
- single tree, the tree head will become the document title.[fn:126] If
- the tree head entry has or inherits an ~EXPORT_FILE_NAME~ property,
- that name will be used for the export.
-
-- {{{kbd(C-c C-e L)}}}, ~org-export-as-latex-to-buffer~ ::
- #+kindex: C-c C-e L
-
- Export to a temporary buffer. Do not create a file.
-
-- {{{kbd(C-c C-e v l/L)}}} ::
-
- Export only the visible part of the document.
-
-- {{{kbd(M-x org-export-region-as-latex)}}} ::
-
- Convert the region to LaTeX under the assumption that it was in Org
- mode syntax before. This is a global command that can be invoked in
- any buffer.
-
-- {{{kbd(M-x org-replace-region-by-latex)}}} ::
-
- Replace the active region (assumed to be in Org mode syntax) by
- LaTeX code.
-
-- {{{kbd(C-c C-e p)}}}, ~org-export-as-pdf~ ::
- #+kindex: C-c C-e p
-
- Export as LaTeX and then process to PDF.
-
-- {{{kbd(C-c C-e d)}}}, ~org-export-as-pdf-and-open~ ::
- #+kindex: C-c C-e d
-
- Export as LaTeX and then process to PDF, then open the resulting
- PDF file.
-
-
-#+cindex: headline levels, for exporting
-#+vindex: org-latex-low-levels
-
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as description lists. The exporter can ignore them or
-convert them to a custom string depending on ~org-latex-low-levels~.
-
-If you want that transition to occur at a different level, specify it
-with a numeric prefix argument, e.g.:
-
-#+begin_example
- C-2 C-c C-e l
-#+end_example
-
-{{{noindent}}} The example setting creates two levels of headings and
-exports the rest as list items.
-
-*** Header and sectioning
- :PROPERTIES:
- :DESCRIPTION: Setting up the export file structure
- :TITLE: Header and sectioning structure
- :END:
-#+cindex: @LaTeX{} class
-#+cindex: @LaTeX{} sectioning structure
-#+cindex: @LaTeX{} header
-#+cindex: header, for @LaTeX{} files
-#+cindex: sectioning structure, for @LaTeX{} export
-
-By default, the LaTeX output uses the class ~article~.
-
-#+vindex: org-export-latex-default-class
-#+vindex: org-export-latex-classes
-#+vindex: org-export-latex-default-packages-alist
-#+vindex: org-export-latex-packages-alist
-#+cindex: #+LaTeX_HEADER
-#+cindex: #+LaTeX_CLASS
-#+cindex: #+LaTeX_CLASS_OPTIONS
-#+cindex: property, LaTeX_CLASS
-#+cindex: property, LaTeX_CLASS_OPTIONS
-
-You can change this globally by setting a different value for
-~org-export-latex-default-class~ or locally by adding an option like
-~#+LaTeX_CLASS: myclass~ in your file, or with a ~:LaTeX_CLASS:~
-property that applies when exporting a region containing only this
-(sub)tree. The class must be listed in ~org-export-latex-classes~.
-This variable defines a header template for each class, and allows you
-to define the sectioning structure for each class.[fn:127] You can
-also define your own classes there. ~#+LaTeX_CLASS_OPTIONS~ or a
-~:LaTeX_CLASS_OPTIONS:~ property can specify the options for the
-~\documentclass~ macro. The options to documentclass have to be
-provided, as expected by LaTeX, within square brackets. You can
-also use ~#+LaTeX_HEADER: \usepackage{xyz}~ to add lines to the
-header. See the docstring of ~org-export-latex-classes~ for more
-information. An example is shown below.
-
-#+begin_example
- ,#+LaTeX_CLASS: article
- ,#+LaTeX_CLASS_OPTIONS: [a4paper]
- ,#+LaTeX_HEADER: \usepackage{xyz}
-
- ,* Headline 1
- some text
-#+end_example
-
-*** Quoting LaTeX code
- :PROPERTIES:
- :DESCRIPTION: Incorporating literal LaTeX code
- :END:
-
-Embedded LaTeX as described in [[Embedded LaTeX]], will be correctly
-inserted into the LaTeX file. This includes simple macros like
-~\ref{LABEL}~ to create a cross reference to a figure. Furthermore,
-you can add special code that should only be present in LaTeX export
-with the following constructs:
-
-#+cindex: #+LaTeX
-#+cindex: #+BEGIN_LaTeX
-#+begin_example
- ,#+LaTeX: Literal LaTeX code for export
-#+end_example
-
-{{{noindent}}} or
-
-#+cindex: #+BEGIN_LaTeX
-
-#+begin_example
- ,#+BEGIN_LaTeX
- All lines between these markers are exported literally
- ,#+END_LaTeX
-#+end_example
-
-*** Tables in LaTeX export
- :PROPERTIES:
- :DESCRIPTION: Options for exporting tables to LaTeX
- :END:
-#+cindex: tables, in @LaTeX{} export
-
-For LaTeX export of a table, you can specify a label, a caption and
-placement options (see [[Images and tables]]). You can also use the
-~ATTR_LaTeX~ line to request a ~longtable~ environment for the
-table, so that it may span several pages, or to change the default table
-environment from ~table~ to ~table*~ or to change the default inner
-tabular environment to ~tabularx~ or ~tabulary~. Finally, you can
-set the alignment string, and (with ~tabularx~ or ~tabulary~) the
-width:
-
-#+cindex: #+CAPTION
-#+cindex: #+LABEL
-#+cindex: #+ATTR_LaTeX
-#+begin_example
- ,#+CAPTION: A long table
- ,#+LABEL: tbl:long
- ,#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
- | ..... | ..... |
- | ..... | ..... |
-#+end_example
-
-or to specify a multicolumn table with ~tabulary~:
-
-#+cindex: #+CAPTION
-#+cindex: #+LABEL
-#+cindex: #+ATTR_LaTeX
-#+begin_example
- ,#+CAPTION: A wide table with tabulary
- ,#+LABEL: tbl:wide
- ,#+ATTR_LaTeX: table* tabulary width=\textwidth
- | ..... | ..... |
- | ..... | ..... |
-#+end_example
-
-*** Images in LaTeX export
- :PROPERTIES:
- :DESCRIPTION: How to insert figures into LaTeX output
- :END:
-#+cindex: images, inline in LaTeX
-#+cindex: inlining images in LaTeX
-
-Images that are linked to without a description part in the link, like
-~[[file:img.jpg]]~ or ~[[./img.jpg]]~ will be inserted into the PDF
-output file resulting from LaTeX processing. Org will use an
-~\includegraphics~ macro to insert the image. If you have specified
-a caption and/or a label as described in [[Images and tables]], the
-figure will be wrapped into a ~figure~ environment and thus become
-a floating element. You can use an ~#+ATTR_LaTeX:~ line to specify
-various other options. You can ask org to export an image as a float
-without specifying a label or a caption by using the keyword ~float~
-in this line. Various optional arguments to the ~\includegraphics~
-macro can also be specified in this fashion. To modify the placement
-option of the floating environment, add something like
-{{{samp(placement=[h!])}}} to the attributes. It is to be noted this
-option can be used with tables as well.[fn:128]
-
-If you would like to let text flow around the image, add the word
-{{{samp(wrap)}}} to the ~#+ATTR_LaTeX:~ line, which will make the
-figure occupy the left half of the page. To fine-tune, the ~placement~
-field will be the set of additional arguments needed by the
-~wrapfigure~ environment. Note that if you change the size of the
-image, you need to use compatible settings for ~\includegraphics~ and
-~wrapfigure~.
-
-#+cindex: #+CAPTION
-#+cindex: #+LABEL
-#+cindex: #+ATTR_LaTeX
-#+begin_example
- ,#+CAPTION: The black-body emission of the disk around HR 4049
- ,#+LABEL: fig:SED-HR4049
- ,#+ATTR_LaTeX: width=5cm,angle=90
- [[./img/sed-hr4049.pdf]]
-
- ,#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
- [[./img/hst.png]]
-#+end_example
-
-If you wish to include an image which spans multiple columns in a page, you
-can use the keyword ~multicolumn~ in the ~#+ATTR_LaTeX~ line. This
-will export the image wrapped in a ~figure*~ environment.
-
-If you need references to a label created in this way, write
-~\ref{fig:SED-HR4049}~ just like in LaTeX.
-
-*** Beamer class export
- :PROPERTIES:
- :DESCRIPTION: Turning the file into a presentation
- :END:
-
-The LaTeX class {{{file(beamer)}}} allows production of high
-quality presentations using LaTeX and pdf processing. Org mode has
-special support for turning an Org mode file or tree into a
-{{{file(beamer)}}} presentation.
-
-When the LaTeX class for the current buffer (as set with ~#+LaTeX_CLASS:
-beamer~) or subtree (set with a ~LaTeX_CLASS~ property) is
-~beamer~, a special export mode will turn the file or tree into a beamer
-presentation. Any tree with not-too-deep level nesting should in principle be
-exportable as a beamer presentation. By default, the top-level entries (or
-the first level below the selected subtree heading) will be turned into
-frames, and the outline structure below this level will become itemize lists.
-You can also configure the variable ~org-beamer-frame-level~ to a
-different level---then the hierarchy above frames will produce the sectioning
-structure of the presentation.
-
-A template for useful in-buffer settings or properties can be inserted
-into the buffer with
-{{{kbd(M-x org-insert-beamer-options-template)}}}. Among other things, this will
-install a column view format which is very handy for editing special
-properties used by beamer.
-
-You can influence the structure of the presentation using the following
-properties:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~BEAMER_env~ ::
-
- The environment that should be used to format this entry. Valid
- environments are defined in the constant
- ~org-beamer-environments-default~, and you can define more in
- ~org-beamer-environments-extra~. If this property is set, the entry
- will also get a ~:B_environment:~ tag to make this visible. This tag
- has no semantic meaning, it is only a visual aid.
-
-- ~BEAMER_envargs~ ::
-
- The beamer-special arguments that should be used for the environment,
- like ~[t]~ or ~[<+->]~ of ~<2-3>~. If the ~BEAMER_col~ property is
- also set, something like ~C[t]~ can be added here as well to set an
- options argument for the implied ~columns~ environment. ~c[t]~ or
- ~c<2->~ will set an options for the implied ~column~ environment.
-
-- ~BEAMER_col~ ::
-
- The width of a column that should start with this entry. If this
- property is set, the entry will also get a ~:BMCOL:~ property to make
- this visible. Also this tag is only a visual aid. When this is a plain
- number, it will be interpreted as a fraction of ~\textwidth~.
- Otherwise it will be assumed that you have specified the units, like
- {{{samp(3cm)}}}. The first such property in a frame will start a
- ~columns~ environment to surround the columns. This environment is
- closed when an entry has a ~BEAMER_col~ property with value 0 or 1, or
- automatically at the end of the frame.
-
-- ~BEAMER_extra~ ::
-
- Additional commands that should be inserted after the environment has
- been opened. For example, when creating a frame, this can be used to
- specify transitions.
-
-
-Frames will automatically receive a ~fragile~ option if they contain
-source code that uses the verbatim environment. Special {{{file(beamer)}}}
-specific code can be inserted using ~#+BEAMER:~ and
-~#+BEGIN_BEAMER~ ... ~#+END_BEAMER~ constructs, similar to other export
-backends, but with the difference that ~#+LaTeX:~ stuff will be included
-in the presentation as well.
-
-Outline nodes with ~BEAMER_env~ property value {{{samp(note)}}} or
-{{{samp(noteNH)}}} will be formatted as beamer notes, i,e, they will be wrapped
-into ~\note{...}~. The former will include the heading as part of the
-note text, the latter will ignore the heading of that node. To simplify note
-generation, it is actually enough to mark the note with a /tag/ (either
-~:B_note:~ or ~:B_noteNH:~) instead of creating the
-~BEAMER_env~ property.
-
-You can turn on a special minor mode ~org-beamer-mode~ for editing
-support with the following line:
-
-#+begin_example
- ,#+STARTUP: beamer
-#+end_example
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-b)}}}, ~org-beamer-select-environment~ ::
- #+kindex: C-c C-b
-
- In ~org-beamer-mode~, this key offers fast selection of a beamer
- environment or the ~BEAMER_col~ property.
-
-
-Column view provides a great way to set the environment of a node and
-other important parameters. Make sure you are using a COLUMN format
-that is geared toward this special purpose. The command
-{{{kbd(M-x org-insert-beamer-options-template)}}} defines such a format.
-
-Here is a simple example Org document that is intended for beamer export.
-
-#+begin_example
- ,#+LaTeX_CLASS: beamer
- ,#+TITLE: Example Presentation
- ,#+AUTHOR: Carsten Dominik
- ,#+LaTeX_CLASS_OPTIONS: [presentation]
- ,#+BEAMER_FRAME_LEVEL: 2
- ,#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
- ,#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
-
- ,* This is the first structural section
-
- ,** Frame 1 \\ with a subtitle
- ,*** Thanks to Eric Fraga :BMCOL:B_block:
- :PROPERTIES:
- :BEAMER_env: block
- :BEAMER_envargs: C[t]
- :BEAMER_col: 0.5
- :END:
- for the first viable beamer setup in Org
- ,*** Thanks to everyone else :BMCOL:B_block:
- :PROPERTIES:
- :BEAMER_col: 0.5
- :BEAMER_env: block
- :BEAMER_envargs: <2->
- :END:
- for contributing to the discussion
- ,**** This will be formatted as a beamer note :B_note:
- ,** Frame 2 \\ where we will not use columns
- ,*** Request :B_block:
- Please test this stuff!
- :PROPERTIES:
- :BEAMER_env: block
- :END:
-#+end_example
-
-For more information, see the documentation on Worg.
-
-** DocBook export
- :PROPERTIES:
- :DESCRIPTION: Exporting to DocBook
- :END:
-#+cindex: DocBook export
-#+cindex: PDF export
-#+cindex: Cui, Baoqiu
-
-Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
-exported to DocBook format, it can be further processed to produce other
-formats, including PDF, HTML, man pages, etc., using many available DocBook
-tools and stylesheets.
-
-Currently DocBook exporter only supports DocBook V5.0.
-
-*** DocBook export commands
- :PROPERTIES:
- :DESCRIPTION: How to invoke DocBook export
- :END:
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient-mark-mode
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e D)}}}, ~org-export-as-docbook~ ::
- #+kindex: C-c C-e D
- #+cindex: property EXPORT_FILE_NAME
-
- Export as a DocBook file. For an Org file, {{{file(myfile.org)}}}, the
- DocBook XML file will be {{{file(myfile.xml)}}}. The file will be
- overwritten without warning. If there is an active region, only the
- region will be exported.[fn:129] If the selected region is a single
- tree, the tree head will become the document title.[fn:130] If the
- tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property, that
- name will be used for the export.
-
-- {{{kbd(C-c C-e V)}}}, ~org-export-as-docbook-pdf-and-open~ ::
- #+kindex: C-c C-e V
-
- Export as a DocBook file, process to PDF, then open the resulting PDF
- file.
-
- #+vindex: org-export-docbook-xslt-proc-command
- #+vindex: org-export-docbook-xsl-fo-proc-command
-
- Note that, in order to produce PDF output based on an exported DocBook
- file, you need to have XSLT processor and XSL-FO processor software
- installed on your system. Check variables
- ~org-export-docbook-xslt-proc-command~ and
- ~org-export-docbook-xsl-fo-proc-command~.
-
- #+vindex: org-export-docbook-xslt-stylesheet
-
- The stylesheet argument ~%s~ in variable
- ~org-export-docbook-xslt-proc-command~ is replaced by the value of
- variable ~org-export-docbook-xslt-stylesheet~, which needs to be set by
- the user. You can also overrule this global setting on a per-file basis by
- adding an in-buffer setting ~#+XSLT:~ to the Org file.
-
-- {{{kbd(C-c C-e v D)}}} ::
- #+kindex: C-c C-e v D
-
- Export only the visible part of the document.
-
-*** Quoting DocBook code
- :PROPERTIES:
- :DESCRIPTION: Incorporating DocBook code in Org files
- :END:
-You can quote DocBook code in Org files and copy it verbatim into exported
-DocBook file with the following constructs:
-
-#+cindex: #+DOCBOOK
-#+cindex: #+BEGIN_DOCBOOK
-#+begin_example
- ,#+DOCBOOK: Literal DocBook code for export
-#+end_example
-
-{{{noindent}}} or
-#+cindex: #+BEGIN_DOCBOOK
-
-#+begin_example
- ,#+BEGIN_DOCBOOK
- All lines between these markers are exported by DocBook exporter
- literally.
- ,#+END_DOCBOOK
-#+end_example
-
-For example, you can use the following lines to include a DocBook warning
-admonition. As to what this warning says, you should pay attention to the
-document context when quoting DocBook code in Org files. You may make
-exported DocBook XML files invalid by not quoting DocBook code correctly.
-
-#+begin_example
- ,#+BEGIN_DOCBOOK
- <warning>
- <para>You should know what you are doing when quoting DocBook XML code
- in your Org file. Invalid DocBook XML may be generated by
- DocBook exporter if you are not careful!</para>
- </warning>
- ,#+END_DOCBOOK
-#+end_example
-
-*** Recursive sections
- :PROPERTIES:
- :DESCRIPTION: Recursive sections in DocBook
- :END:
-#+cindex: DocBook recursive sections
-
-DocBook exporter exports Org files as articles using the ~article~
-element in DocBook. Recursive sections, i.e., ~section~ elements, are
-used in exported articles. Top level headlines in Org files are
-exported as top level sections, and lower level headlines are exported
-as nested sections. The entire structure of Org files will be exported
-completely, no matter how many nested levels of headlines there are.
-
-Using recursive sections makes it easy to port and reuse exported
-DocBook code in other DocBook document types like ~book~ or ~set~.
-
-*** Tables in DocBook export
- :PROPERTIES:
- :DESCRIPTION: Tables are exported as HTML tables
- :END:
-#+cindex: tables, in DocBook export
-
-Tables in Org files are exported as HTML tables, which have been
-supported since DocBook V4.3.
-
-If a table does not have a caption, an informal table is generated
-using the ~informaltable~ element; otherwise, a formal table will be
-generated using the ~table~ element.
-
-*** Images in DocBook export
- :PROPERTIES:
- :DESCRIPTION: How to insert figures into DocBook output
- :END:
-#+cindex: images, inline in DocBook
-#+cindex: inlining images in DocBook
-
-Images that are linked to without a description part in the link, like
-~[[file:img.jpg]]~ or ~[[./img.jpg]]~, will be exported to
-DocBook using ~mediaobject~ elements. Each ~mediaobject~ element
-contains an ~imageobject~ that wraps an ~imagedata~ element. If you
-have specified a caption for an image as described in [[Images and
-tables]], a ~caption~ element will be added in ~mediaobject~. If a label
-is also specified, it will be exported as an ~xml:id~ attribute of the
-~mediaobject~ element.
-
-#+vindex: org-export-docbook-default-image-attributes
-
-Image attributes supported by the ~imagedata~ element, like ~align~ or
-~width~, can be specified in two ways: you can either customize
-variable ~org-export-docbook-default-image-attributes~ or use the
-~#+ATTR_DOCBOOK:~ line. Attributes specified in variable
-~org-export-docbook-default-image-attributes~ are applied to all
-inline images in the Org file to be exported (unless they are
-overridden by image attributes specified in ~#+ATTR_DOCBOOK:~ lines).
-
-The ~#+ATTR_DOCBOOK:~ line can be used to specify additional image
-attributes or override default image attributes for individual images.
-If the same attribute appears in both the ~#+ATTR_DOCBOOK:~ line and
-variable ~org-export-docbook-default-image-attributes~, the former
-takes precedence. Here is an example about how image attributes can be
-set:
-
-#+cindex: #+CAPTION
-#+cindex: #+LABEL
-#+cindex: #+ATTR_DOCBOOK
-#+begin_example
- ,#+CAPTION: The logo of Org mode
- ,#+LABEL: unicorn-svg
- ,#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
- [[./img/org-mode-unicorn.svg]]
-#+end_example
-
-#+vindex: org-export-docbook-inline-image-extensions
-
-By default, DocBook exporter recognizes the following image file
-types: {{{file(jpeg)}}}, {{{file(jpg)}}}, {{{file(png)}}},
-{{{file(gif)}}}, and {{{file(svg)}}}. You can customize variable
-~org-export-docbook-inline-image-extensions~ to add more types to this
-list as long as DocBook supports them.
-
-*** Special characters
- :PROPERTIES:
- :DESCRIPTION: How to handle special characters
- :TITLE: Special characters in DocBook export
- :END:
-#+vindex: org-export-docbook-doctype
-#+vindex: org-entities
-
-Special characters that are written in TeX-like syntax, such as
-~\alpha~, ~\Gamma~, and ~\Zeta~, are supported by DocBook exporter.
-These characters are rewritten to XML entities, like ~&alpha;~,
-~&Gamma;~, and ~&Zeta;~, based on the list saved in variable
-~org-entities~. As long as the generated DocBook file includes the
-corresponding entities, these special characters are recognized.
-
-You can customize variable ~org-export-docbook-doctype~ to include the
-entities you need. For example, you can set variable
-~org-export-docbook-doctype~ to the following value to recognize all
-special characters included in XHTML entities:
-
-#+begin_example
- "<!DOCTYPE article [
- <!ENTITY % xhtml1-symbol PUBLIC
- \"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
- \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
- >
- %xhtml1-symbol;
- ]>
- "
-#+end_example
-
-** OpenDocument Text export
- :PROPERTIES:
- :DESCRIPTION: Exporting to OpenDocument Text
- :END:
-#+cindex: K, Jambunathan
-#+cindex: ODT
-#+cindex: OpenDocument
-#+cindex: export, OpenDocument
-#+cindex: LibreOffice
-#+cindex: org-odt.el
-#+cindex: org-modules
-
-Org Mode supports export to OpenDocument Text (ODT) format using the
-{{{file(org-odt.el)}}} module.[fn:131] Documents created by this
-exporter use the {{{cite(OpenDocument-v1.2 specification)}}} and
-are compatible with LibreOffice 3.4.[fn:132]
-
-*** Pre-requisites for ODT export
- :PROPERTIES:
- :DESCRIPTION: What packages ODT exporter relies on
- :END:
-#+cindex: zip
-
-The ODT exporter relies on the {{{file(zip)}}} program to create the
-final output. Check the availability of this program before proceeding
-further.
-
-*** ODT export commands
- :PROPERTIES:
- :DESCRIPTION: How to invoke ODT export
- :ALT_TITLE: Exporting to ODT
- :END:
-<<x-export-to-odt>>
-
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient-mark-mode
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e o)}}}, ~org-export-as-odt~ ::
- #+kindex: C-c C-e o
- #+cindex: property EXPORT_FILE_NAME
-
- Export as OpenDocument Text file.
-
- #+vindex: org-export-odt-preferred-output-format
-
- If ~org-export-odt-preferred-output-format~ is specified,
- automatically convert the exported file to that format. See
- [[Automatically exporting to other formats]].
-
- For an Org file {{{file(myfile.org)}}}, the ODT file will be
- {{{file(myfile.odt)}}}. The file will be overwritten without warning.
- If there is an active region, only the region will be
- exported.[fn:133] If the selected region is a single tree, the tree
- head will become the document title.[fn:134] If the tree head entry
- has, or inherits, an ~EXPORT_FILE_NAME~ property, that name will be
- used for the export.
-
-- {{{kbd(C-c C-e O)}}}, ~org-export-as-odt-and-open~ ::
- #+kindex: C-c C-e O
-
- Export as an OpenDocument Text file and open the resulting file.
-
- #+vindex: org-export-odt-preferred-output-format
-
- If ~org-export-odt-preferred-output-format~ is specified, open the
- converted file instead. See [[x-export-to-other-formats][Automatically exporting to other formats]].
-
-*** Extending ODT export
- :PROPERTIES:
- :DESCRIPTION: How to produce ~doc~, ~pdf~ files
- :END:
-
-The ODT exporter can interface with a variety of document converters
-and supports popular converters out of the box. As a result, you can
-use it to export to formats like {{{samp(doc)}}} or convert a document
-from one format (say {{{samp(csv)}}}) to another format (say
-{{{samp(ods)}}} or {{{samp(xls)}}}).
-
-#+cindex: @file{unoconv}
-#+cindex: LibreOffice
-
-If you have a working installation of LibreOffice, a document
-converter is pre-configured for you and you can use it right away. If
-you would like to use {{{file(unoconv)}}} as your preferred converter,
-customize the variable ~org-export-odt-convert-process~ to point to
-~unoconv~. You can also use your own favorite converter or tweak the
-default settings of the {{{file(LibreOffice)}}} and
-{{{samp(unoconv)}}} converters. See [[Configuring a document converter]].
-
-**** Automatically exporting to other formats
- :PROPERTIES:
- :DESCRIPTION: Automatic conversion to doc, docx, etc.
- :END:
-<<x-export-to-other-formats>>
-
-#+vindex: org-export-odt-preferred-output-format
-
-Very often, you will find yourself exporting to ODT format, only to
-immediately save the exported document to other formats like
-{{{samp(doc)}}}, {{{samp(docx)}}}, {{{samp(rtf)}}}, {{{samp(pdf)}}}
-etc. In such cases, you can specify your preferred output format by
-customizing the variable ~org-export-odt-preferred-output-format~.
-This way, the export commands (see [[x-export-to-odt][Exporting to ODT]])
-can be extended to export to a format that is of immediate interest to
-you.
-
-**** Converting between document formats
- :PROPERTIES:
- :DESCRIPTION: Interacting with configured converters
- :END:
-# <<x-convert-to-other-formats>>
-
-There are many document converters in the wild that support
-conversion to and from various file formats, including, but not
-limited to the ODT format. LibreOffice converter, mentioned above, is
-one such converter. Once a converter is configured, you can interact
-with it using the following command.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(M-x org-export-odt-convert)}}} ::
- #+vindex: org-export-odt-convert
-
- Convert an existing document from one format to another. With a prefix
- argument, also open the newly produced file.
-
-*** Applying custom styles
- :PROPERTIES:
- :DESCRIPTION: How to apply custom styles to the output
- :END:
-#+cindex: styles, custom
-#+cindex: template, custom
-
-The ODT exporter ships with a set of OpenDocument styles
-(see [[Working with OpenDocument style files]]) that ensure a well-formatted output.
-These factory styles, however, may not cater to your specific tastes.
-To customize the output, you can either modify the above styles files
-directly, or generate the required styles using an application like
-LibreOffice. The latter method is suitable for expert and non-expert
-users alike, and is described here.
-
-Custom styles can be applied in three easy steps:
-
-1. Create a sample {{{file(example.org)}}} file with the below
- settings and export it to ODT format.
-
- #+begin_example
- ,#+OPTIONS: H:10 num:t
- #+end_example
-
-2. Open the above {{{file(example.odt)}}} using LibreOffice. Use the
- {{{file(Stylist)}}} to locate the target styles---these typically
- have the {{{samp(Org)}}} prefix---and modify those to your taste.
- Save the modified file either as an OpenDocument Text
- ({{{file(.odt)}}}) or OpenDocument Template ({{{file(.ott)}}})
- file.
-
-3. Customize the variable ~org-export-odt-styles-file~ and point it to
- the newly created file. For additional configuration options see
- [[x-overriding-factory-styles][Overriding factory styles]].
-
- #+cindex: #+ODT_STYLES_FILE
- #+vindex: org-export-odt-styles-file
-
- If you would like to choose a style on a per-file basis, you can use
- the ~#+ODT_STYLES_FILE~ option. A typical setting will look like
- one of these two examples:
-
- #+begin_example
- ,#+ODT_STYLES_FILE: "/path/to/example.ott"
- #+end_example
-
- or
-
- #+begin_example
- ,#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
- #+end_example
-
-Although you can use third-party styles and templates for customizing
-your output, this will produce the desired output only if the template
-provides all style names that the {{{samp(ODT)}}} exporter relies
-upon. Unless this condition is met, the output is going to be less
-than satisfactory. It is highly recommended that you only work with
-templates that are directly derived from the factory settings.
-
-*** Links in ODT export
- :PROPERTIES:
- :DESCRIPTION: How links will be interpreted and formatted
- :END:
-#+cindex: tables, in DocBook export
-
-ODT exporter creates native cross-references for internal links. It
-creates Internet-style links for all other links.
-
-A link with no description and destined to a regular (un-itemized)
-outline heading is replaced with a cross-reference and section number
-of the heading.
-
-A ~\ref{label}~-style reference to an image, table etc. is replaced
-with a cross-reference and sequence number of the labeled entity. See
-[[Labels and captions in ODT export]].
-
-*** Tables in ODT export
- :PROPERTIES:
- :DESCRIPTION: How tables are exported
- :END:
-
-#+cindex: tables, in DocBook export
-
-Export of native Org mode tables (see [[Tables]]) and simple
-{{{file(table.el)}}} tables is supported. However, export of complex
-{{{file(table.el)}}} tables---tables that have column or row
-spans---is not supported. Such tables are stripped from the exported
-document.
-
-By default, a table is exported with top and bottom frames and with
-rules separating row and column groups (see [[Column groups]]).
-Furthermore, all tables are typeset to occupy the same width. If the
-table specifies alignment and relative width for its columns (see
-[[Column width and alignment]]) then these are honored on export.[fn:135]
-
-#+cindex: #+ATTR_ODT
-
-You can control the width of the table by specifying ~:rel-width~
-property using an ~#+ATTR_ODT~ line.
-
-For example, consider the following table which makes use of all the
-rules mentioned above.
-
-#+begin_example
- #+ATTR_ODT: :rel-width 50
- | Area/Month | Jan | Feb | Mar | Sum |
- |---------------+-------+-------+-------+-------|
- | / | < | | | < |
- | <l13> | <r5> | <r5> | <r5> | <r6> |
- | North America | 1 | 21 | 926 | 948 |
- | Middle East | 6 | 75 | 844 | 925 |
- | Asia Pacific | 9 | 27 | 790 | 826 |
- |---------------+-------+-------+-------+-------|
- | Sum | 16 | 123 | 2560 | 2699 |
-#+end_example
-
-On export, the table will occupy 50% of text area. The columns will be
-sized (roughly) in the ratio of 13:5:5:5:6. The first column will be
-left-aligned and rest of the columns will be right-aligned. There will
-be vertical rules after separating the header and last columns from
-other columns. There will be horizontal rules separating the header
-and last rows from other rows.
-
-If you are not satisfied with the above formatting options, you can
-create custom table styles and associate them with a table using the
-~#+ATTR_ODT~ line. See [[Customizing tables in ODT export]].
-
-*** Images in ODT export
- :PROPERTIES:
- :DESCRIPTION: How to insert images
- :END:
-#+cindex: images, embedding in ODT
-#+cindex: embedding images in ODT
-
-You can embed images within the exported document by providing a link to the
-desired image file with no link description. For example, to embed
-{{{samp(img.png)}}} do either of the following:
-
-#+begin_example
- [[file:img.png]]
-#+end_example
-
-#+begin_example
- [[./img.png]]
-#+end_example
-
-You can create clickable images by providing a link whose description
-is a link to an image file. For example, to embed an image
-{{{file(org-mode-unicorn.png)}}}, which when clicked jumps to
-[[http://Orgmode.org]] website, do the following:
-
-#+begin_example
- [[http://orgmode.org][./org-mode-unicorn.png]]
-#+end_example
-
-#+cindex: #+ATTR_ODT
-
-You can control the size and scale of the embedded images using the
-~#+ATTR_ODT~ attribute.
-
-#+cindex: identify, ImageMagick
-#+vindex: org-export-odt-pixels-per-inch
-
-The exporter specifies the desired size of the image in the final
-document in units of centimeters. In order to scale the embedded
-images, the exporter queries for pixel dimensions of the images using
-either ImageMagick's {{{file(identify)}}} program, or Emacs'
-`create-image' and `image-size' APIs.[fn:136] The pixel dimensions are
-subsequently converted to centimeters using
-~org-export-odt-pixels-per-inch~. The default value of this variable
-is set to ~display-pixels-per-inch~. You can tweak this variable to
-achieve the best results.
-
-The examples below illustrate the various possibilities.
-
-#+attr_texinfo: :table-type table :indic @asis
-- Explicitly size the image ::
-
- To embed {{{file(img.png)}}} as a 10 cm x 10 cm image, do the
- following:
-
- #+begin_example
- #+ATTR_ODT: :width 10 :height 10
- [[./img.png]]
- #+end_example
-
-- Scale the image ::
-
- To embed {{{file(img.png)}}} at half its size, do the following:
-
- #+begin_example
- #+ATTR_ODT: :scale 0.5
- [[./img.png]]
- #+end_example
-
-- Scale the image to a specific width ::
-
- To embed {{{file(img.png)}}} with a width of 10 cm while retaining the
- original height:width ratio, do the following:
-
- #+begin_example
- #+ATTR_ODT: :width 10
- [[./img.png]]
- #+end_example
-
-- Scale the image to a specific height ::
-
- To embed {{{file(img.png)}}} with a height of 10 cm while retaining
- the original height:width ratio, do the following:
-
- #+begin_example
- #+ATTR_ODT: :height 10
- [[./img.png]]
- #+end_example
-
-#+cindex: #+ATTR_ODT
-
-You can control the manner in which an image is anchored by setting
-the ~:anchor~ property of it's ~#+ATTR_ODT~ line. You can specify one
-of the the following three values for the ~:anchor~ property -
-{{{samp("as-char")}}}, {{{samp("paragraph")}}} and {{{samp("page")}}}.
-
-To create an image that is anchored to a page, do the following:
-
-#+begin_example
- #+ATTR_ODT: :anchor "page"
- [[./img.png]]
-#+end_example
-
-*** Math formatting in ODT export
- :PROPERTIES:
- :DESCRIPTION: How LaTeX fragments are formatted
- :END:
-
-The ODT exporter has special support for handling math.
-
-**** Working with LaTeX math snippets
- :PROPERTIES:
- :DESCRIPTION: How to embed LaTeX math fragments
- :END:
-
-LaTeX math snippets (see [[LaTeX fragments]]) can be embedded in the ODT
-document in one of the following ways:
-
-#+cindex: MathML
-#+attr_texinfo: :table-type table :indic @asis
-- MathML ::
-
- This option is activated on a per-file basis with the following option:
-
- #+begin_example
- ,#+OPTIONS: LaTeX:t
- #+end_example
-
- With this option, LaTeX fragments are first converted into MathML
- fragments using an external LaTeX-to-MathML converter program. The
- resulting MathML fragments are then embedded as an OpenDocument Formula in
- the exported document.
-
- #+vindex: org-latex-to-mathml-convert-command
- #+vindex: org-latex-to-mathml-jar-file
-
- You can specify the LaTeX-to-MathML converter by customizing the variables
- ~org-latex-to-mathml-convert-command~ and
- ~org-latex-to-mathml-jar-file~.
-
- If you prefer to use {{{file(MathToWeb)}}} as your converter, you can
- configure the above variables as shown below.[fn:137]
-
- #+header: :eval no
- #+header: :exports code
- #+begin_src emacs-lisp
- (setq org-latex-to-mathml-convert-command
- "java -jar %j -unicode -force -df %o %I"
- org-latex-to-mathml-jar-file
- "/path/to/mathtoweb.jar")
- #+end_src
-
- You can use the following commands to quickly verify the reliability of
- the LaTeX-to-MathML converter.
-
- - {{{kbd(M-x org-export-as-odf)}}} ::
-
- Convert a LaTeX math snippet to an OpenDocument formula
- ({{{file(.odf)}}}) file.
-
- - {{{kbd(M-x org-export-as-odf-and-open)}}} ::
-
- Convert a LaTeX math snippet to an OpenDocument formula
- ({{{file(.odf)}}}) file and open the formula file with the
- system-registered application.
-
-- PNG images ::
- #+cindex: dvipng
-
- This option is activated on a per-file basis with
-
- #+begin_example
- ,#+OPTIONS: LaTeX:dvipng
- #+end_example
-
- With this option, LaTeX fragments are processed into PNG images and
- the resulting images are embedded in the exported document. This
- method requires that the {{{file(dvipng)}}} program be available on
- your system.
-
-**** Working with MathML or OpenDocument formula files
- :PROPERTIES:
- :DESCRIPTION: How to embed equations in native format
- :END:
-
-For various reasons, you may find embedding LaTeX math snippets in
-an ODT document less than reliable. In that case, you can embed a math
-equation by linking to its MathML ({{{file(.mml)}}}) source or its
-OpenDocument formula ({{{file(.odf)}}}) file as shown below:
-
-#+begin_example
- [[./equation.mml]]
-#+end_example
-
-or
-
-#+begin_example
- [[./equation.odf]]
-#+end_example
-
-*** Labels and captions in ODT export
- :PROPERTIES:
- :DESCRIPTION: How captions are rendered
- :END:
-
-You can label and caption various category of objects---an inline
-image, a table, a LaTeX fragment or a Math formula---using
-~#+LABEL~ and ~#+CAPTION~ lines. See [[Images and tables]]. ODT exporter
-enumerates each labeled or captioned object of a given category
-separately. As a result, each such object is assigned a sequence
-number based on order of its appearance in the Org file.
-
-In the exported document, a user-provided caption is augmented with
-the category and sequence number. Consider the following inline image
-in an Org file:
-
-#+begin_example
- ,#+CAPTION: Bell curve
- ,#+LABEL: fig:SED-HR4049
- [[./img/a.png]]
-#+end_example
-
-It could be rendered as shown below in the exported document.
-
-#+begin_example
- Figure 2: Bell curve
-#+end_example
-
-#+vindex: org-export-odt-category-strings
-
-You can modify the category component of the caption by customizing
-the variable ~org-export-odt-category-strings~. For example, to tag
-all embedded images with the string {{{samp(Illustration)}}} (instead
-of the default {{{samp(Figure)}}}) use the following setting.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(setq org-export-odt-category-strings
- '(("en" "Table" "Illustration" "Equation" "Equation")))
-#+end_src
-
-With this, previous image will be captioned as below in the exported
-document.
-
-#+begin_example
- Illustration 2: Bell curve
-#+end_example
-
-*** Literal examples in ODT export
- :PROPERTIES:
- :DESCRIPTION: How source and example blocks are formatted
- :END:
-
-Export of literal examples (see [[Literal examples]]) with full
-fontification is supported. Internally, the exporter relies on
-{{{file(htmlfontify.el)}}} to generate all style definitions needed
-for a fancy listing.[fn:138] The auto-generated styles have
-{{{samp(OrgSrc)}}} as prefix and inherit their color from the faces
-used by Emacs ~font-lock~ library for the source language.
-
-#+vindex: org-export-odt-fontify-srcblocks
-
-If you prefer to use your own custom styles for fontification, you can
-do so by customizing the variable
-~org-export-odt-create-custom-styles-for-srcblocks~.
-
-#+vindex: org-export-odt-create-custom-styles-for-srcblocks
-
-You can turn off fontification of literal examples by customizing the
-variable ~org-export-odt-fontify-srcblocks~.
-
-*** Advanced topics in ODT export
- :PROPERTIES:
- :DESCRIPTION: Read this if you are a power user
- :END:
-
-If you rely heavily on ODT export, you may want to exploit the full
-set of features that the exporter offers. This section describes
-features that would be of interest to power users.
-
-**** Configuring a document converter
- :PROPERTIES:
- :DESCRIPTION: How to register a document converter
- :END:
-#+cindex: convert
-#+cindex: doc, docx, rtf
-#+cindex: converter
-
-The ODT exporter can work with popular converters with little or no
-extra configuration from your side. See [[Extending ODT export]]. If you
-are using a converter that is not supported by default or if you would
-like to tweak the default converter settings, proceed as below.
-
-#+attr_texinfo: :table-type table :indic @asis
-- Register the converter ::
-
- #+vindex: org-export-odt-convert-processes
-
- Name your converter and add it to the list of known converters by
- customizing the variable ~org-export-odt-convert-processes~. Also
- specify how the converter can be invoked via command-line to effect
- the conversion.
-
-- Configure its capabilities ::
-
- #+vindex: org-export-odt-convert-capabilities
- # <<x-odt-converter-capabilities>>
-
- Specify the set of formats the converter can handle by customizing the
- variable ~org-export-odt-convert-capabilities~. Use the default value
- for this variable as a guide for configuring your converter. As suggested by
- the default setting, you can specify the full set of formats supported by the
- converter and not limit yourself to specifying formats that are related to
- just the OpenDocument Text format.
-
-- Choose the converter ::
-
- #+vindex: org-export-odt-convert-process
-
- Select the newly added converter as the preferred one by customizing the
- variable ~org-export-odt-convert-process~.
-
-**** Working with OpenDocument style files
- :PROPERTIES:
- :DESCRIPTION: Explore the internals
- :END:
-#+cindex: styles, custom
-#+cindex: template, custom
-
-This section explores the internals of the ODT exporter and the means
-by which it produces styled documents. Read this section if you are
-interested in exploring the automatic and custom OpenDocument styles
-used by the exporter.
-
-# <<x-factory-styles>>
-
-The ODT exporter relies on two files for generating its output.
-These files are bundled with the distribution under the directory pointed to
-by the variable ~org-odt-styles-dir~. The two files are:
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{file(OrgOdtStyles.xml)}}} ::
- <<x-orgodtstyles-xml>>
-
- This file contributes to the {{{file(styles.xml)}}} file of the final
- {{{samp(ODT)}}} document. This file is modified to control outline
- numbering based on user settings, and To add styles generated by
- {{{file(htmlfontify.el)}}} for fontification of code blocks.
-
-- {{{file(OrgOdtContentTemplate.xml)}}} ::
- <<x-orgodtcontenttemplate-xml>>
-
- This file contributes to the {{{file(content.xml)}}} file of the final
- {{{samp(ODT)}}} document. The contents of the Org outline are inserted
- between the ~<office:text>~ and ~</office:text>~
- elements of this file.
-
- In addition to serving as a template file for the final
- {{{file(content.xml)}}}, the file also contains automatic styles for
- formatting of tables which are referenced by the exporter, and
- ~<text:sequence-decl>~ ... ~</text:sequence-decl>~
- elements that control how various entities---tables, images,
- equations, etc.---are numbered.
-
-
-<<x-overriding-factory-styles>>
-
-The following two variables control the location from which the ODT
-exporter picks up the custom styles and content template files. You
-can customize these variables to override the factory styles used by
-the exporter.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~org-export-odt-styles-file~ ::
- <<x-org-export-odt-styles-file>>
-
- Use this variable to specify the {{{file(styles.xml)}}} that will be
- used in the final output. You can specify one of the following values:
-
- - A {{{file(styles.xml)}}} file ::
-
- Use this file instead of the default {{{file(styles.xml)}}}
-
- - A {{{file(.odt)}}} or {{{file(.ott)}}} file ::
-
- Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
- Text or Template file.
-
- - A {{{file(.odt)}}} or {{{file(.ott)}}} file and a subset of files contained within them ::
-
- Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
- Text or Template file. Additionally extract the specified member files
- and embed those within the final {{{samp(ODT)}}} document.
-
- Use this option if the {{{file(styles.xml)}}} file references
- additional files like header and footer images.
-
- - ~nil~ ::
-
- Use the default {{{file(styles.xml)}}}
-
-- ~org-export-odt-content-template-file~ ::
- <<x-org-export-odt-content-template-file>>
-
- Use this variable to specify the blank {{{file(content.xml)}}} that
- will be used in the final output.
-
-**** Creating one-off styles
- :PROPERTIES:
- :DESCRIPTION: How to produce custom highlighting, etc.
- :END:
-
-There are times when you would want one-off formatting in the exported
-document. You can achieve this by embedding raw OpenDocument XML in
-the Org file. The use of this feature is better illustrated with
-couple of examples.
-
-#+attr_texinfo: :table-type table :indic @asis
-- Embedding ODT tags as part of regular text ::
-
- You can include simple OpenDocument tags by prefixing them with
- {{{samp(@)}}}. For example, to highlight a region of text do the
- following:
-
- #+begin_example
- @<text:span text:style-name="Highlight">This is a
- highlighted text@</text:span>. But this is a
- regular text.
- #+end_example
-
- *Hint:* To see the above example in action, edit your
- {{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
- add a custom {{{samp(Highlight)}}} style as shown below.
-
- #+begin_example
- <style:style style:name="Highlight" style:family="text">
- <style:text-properties fo:background-color="#ff0000"/>
- </style:style>
- #+end_example
-
-- Embedding a one-line OpenDocument XML ::
-
- You can add a simple OpenDocument one-liner using the ~#+ODT:~
- directive. For example, to force a page break do the following:
-
- #+begin_example
- #+ODT: <text:p text:style-name="PageBreak"/>
- #+end_example
-
- *Hint:* To see the above example in action, edit your
- {{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
- add a custom {{{samp(PageBreak)}}} style as shown below.
-
- #+begin_example
- <style:style style:name="PageBreak" style:family="paragraph"
- style:parent-style-name="Text_20_body">
- <style:paragraph-properties fo:break-before="page"/>
- </style:style>
- #+end_example
-
-- Embedding a block of OpenDocument XML ::
-
- You can add a large block of OpenDocument XML using the
- ~#+BEGIN_ODT~ ... ~#+END_ODT~ construct.
-
- For example, to create a one-off paragraph that uses bold text, do the
- following:
-
- #+begin_example
- #+BEGIN_ODT
- <text:p text:style-name="Text_20_body_20_bold">
- This paragraph is specially formatted and uses bold text.
- </text:p>
- #+END_ODT
- #+end_example
-
-**** Customizing tables in ODT export
- :PROPERTIES:
- :DESCRIPTION: How to define and use table templates
- :END:
-#+cindex: tables, in ODT export
-#+cindex: #+ATTR_ODT
-
-You can override the default formatting of the table by specifying a
-custom table style with the ~#+ATTR_ODT~ line. For a discussion on
-default formatting of tables see [[Tables in ODT export]].
-
-This feature closely mimics the way table templates are defined in the
-OpenDocument-v1.2 specification.[fn:139]
-
-To have a quick preview of this feature, install the following setting and
-export the example table.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
- (setq org-export-odt-table-styles
- (append org-export-odt-table-styles
- '(("TableWithHeaderRowAndColumn" "Custom"
- ((use-first-row-styles . t)
- (use-first-column-styles . t)))
- ("TableWithFirstRowandLastRow" "Custom"
- ((use-first-row-styles . t)
- (use-last-row-styles . t))))))
-#+end_src
-
-#+begin_example
- ,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
- | Name | Phone | Age |
- | Peter | 1234 | 17 |
- | Anna | 4321 | 25 |
-#+end_example
-
-In the above example, you used a template named {{{samp(Custom)}}} and
-installed two table styles with the names
-{{{samp(TableWithHeaderRowAndColumn)}}} and
-{{{samp(TableWithFirstRowandLastRow)}}}. (*Important:* The
-OpenDocument styles needed for producing the above template have been
-pre-defined for you. These styles are available under the section
-marked {{{samp(Custom Table Template)}}} in
-{{{file(OrgOdtContentTemplate.xml)}}} (see
-[[x-orgodtcontenttemplate-xml][Factory styles]]). If you need additional
-templates you have to define these styles yourself.
-
-
-To use this feature proceed as follows:
-
-#+attr_texinfo: :table-type table :indic @asis
-- Create a table template[fn:140] ::
-
- A table template is nothing but a set of {{{samp(table-cell)}}} and
- {{{samp(paragraph)}}} styles for each of the following table cell
- categories:
-
- - Body
- - First column
- - Last column
- - First row
- - Last row
- - Even row
- - Odd row
- - Even column
- - Odd Column
-
- The names for the above styles must be chosen based on the name of the
- table template using a well-defined convention.
-
- The naming convention is better illustrated with an example. For a
- table template with the name {{{samp(Custom)}}}, the needed style
- names are listed in the following table.
-
- | Table cell type | ~table-cell~ style | ~paragraph~ style |
- |-----------------+----------------------------------------+---------------------------------------------|
- | Body | {{{samp(CustomTableCell)}}} | {{{samp(CustomTableParagraph)}}} |
- | First column | {{{samp(CustomFirstColumnTableCell)}}} | {{{samp(CustomFirstColumnTableParagraph)}}} |
- | Last column | {{{samp(CustomLastColumnTableCell)}}} | {{{samp(CustomLastColumnTableParagraph)}}} |
- | First row | {{{samp(CustomFirstRowTableCell)}}} | {{{samp(CustomFirstRowTableParagraph)}}} |
- | Last row | {{{samp(CustomLastRowTableCell)}}} | {{{samp(CustomLastRowTableParagraph)}}} |
- | Even row | {{{samp(CustomEvenRowTableCell)}}} | {{{samp(CustomEvenRowTableParagraph)}}} |
- | Odd row | {{{samp(CustomOddRowTableCell)}}} | {{{samp(CustomOddRowTableParagraph)}}} |
- | Even column | {{{samp(CustomEvenColumnTableCell)}}} | {{{samp(CustomEvenColumnTableParagraph)}}} |
- | Odd column | {{{samp(CustomOddColumnTableCell)}}} | {{{samp(CustomOddColumnTableParagraph)}}} |
-
-
- To create a table template with the name {{{samp(Custom)}}}, define
- the above styles in the ~<office:automatic-styles>~ ...
- ~</office:automatic-styles>~ element of the content template file (see
- [[x-orgodtcontenttemplate-xml][Factory styles]]).
-
-- Define a table style[fn:141] ::
-
- #+vindex: org-export-odt-table-styles
-
- To define a table style, create an entry for the style in the variable
- ~org-export-odt-table-styles~ and specify the following:
-
- - the name of the table template created in step (1)
- - the set of cell styles in that template that are to be activated
-
-
- For example, the entry below defines two different table styles
- {{{samp(TableWithHeaderRowAndColumn)}}} and
- {{{samp(TableWithFirstRowandLastRow)}}} based on the same template
- {{{samp(Custom)}}}. The styles achieve their intended effect by
- selectively activating the individual cell styles in that template.
-
- #+header: :eval no
- #+header: :exports code
- #+begin_src emacs-lisp
- (setq org-export-odt-table-styles
- (append org-export-odt-table-styles
- '(("TableWithHeaderRowAndColumn" "Custom"
- ((use-first-row-styles . t)
- (use-first-column-styles . t)))
- ("TableWithFirstRowandLastRow" "Custom"
- ((use-first-row-styles . t)
- (use-last-row-styles . t))))))
- #+end_src
-
-- Associate a table with the table style ::
-
- To do this, specify the table style created in step (2) as part of
- the ~ATTR_ODT~ line as shown below.
-
- #+begin_example
- ,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
- | Name | Phone | Age |
- | Peter | 1234 | 17 |
- | Anna | 4321 | 25 |
- #+end_example
-
-**** Validating OpenDocument XML
- :PROPERTIES:
- :DESCRIPTION: How to debug corrupt OpenDocument files
- :END:
-
-Occasionally, you will discover that the document created by the ODT
-exporter cannot be opened by your favorite application. One of the
-common reasons for this is that the {{{file(.odt)}}} file is corrupt.
-In such cases, you may want to validate the document against the
-OpenDocument RELAX NG Compact Syntax (RNC) schema.
-
-For de-compressing the {{{file(.odt)}}} file[fn:142]:
-[[info:emacs#File Archives]]. For general help with validation (and
-schema-sensitive editing) of XML files: [[info:nxml-mode#Introduction]].
-#+vindex: org-export-odt-schema-dir
-
-If you have ready access to OpenDocument {{{file(.rnc)}}} files and
-the needed schema-locating rules in a single folder, you can customize
-the variable ~org-export-odt-schema-dir~ to point to that directory.
-The ODT exporter will take care of updating the
-~rng-schema-locating-files~ for you.
-
-** TaskJuggler export
- :PROPERTIES:
- :DESCRIPTION: Exporting to TaskJuggler
- :END:
-#+cindex: TaskJuggler export
-#+cindex: Project management
-
-[[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool. It provides an optimizing
-scheduler that computes your project time lines and resource
-assignments based on the project outline and the constraints that you
-have provided.
-
-The TaskJuggler exporter is a bit different from other exporters, such
-as the ~HTML~ and LaTeX exporters for example, in that it does not
-export all the nodes of a document or strictly follow the order of the
-nodes in the document.
-
-Instead the TaskJuggler exporter looks for a tree that defines the
-tasks and optionally trees that define the resources and reports for
-this project. It then creates a TaskJuggler file based on these trees
-and the attributes defined in all the nodes.
-
-*** TaskJuggler export commands
- :PROPERTIES:
- :DESCRIPTION: Key bindings for TaskJuggler export
- :END:
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e j)}}}, ~org-export-as-taskjuggler~ ::
- #+kindex: C-c C-e j
-
- Export as a TaskJuggler file.
-
-- {{{kbd(C-c C-e J)}}}, ~org-export-as-taskjuggler-and-open~ ::
- #+kindex: C-c C-e J
-
- Export as a TaskJuggler file and then open the file with TaskJugglerUI
- (only for TaskJugglerUI 2.x).
-
-*** Tasks
- :PROPERTIES:
- :DESCRIPTION: Marking tasks for TaskJuggler export
- :END:
-#+vindex: org-export-taskjuggler-project-tag
-
-Create your tasks as you usually do with Org mode. Assign efforts to
-each task using properties (it is easiest to do this in the column
-view). You should end up with something similar to the example by
-Peter Jones in
-[[http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org]].
-Now mark the top node of your tasks with a tag named
-~:taskjuggler_project:~ (or whatever you customized
-~org-export-taskjuggler-project-tag~ to). You are now ready to export
-the project plan with {{{kbd(C-c C-e J)}}} which will export the
-project plan and open a gantt chart in TaskJugglerUI.
-
-*** Resources
- :PROPERTIES:
- :DESCRIPTION: Define TaskJuggler resources
- :END:
-#+vindex: org-export-taskjuggler-resource-tag
-
-Next you can define resources and assign those to work on specific
-tasks. You can group your resources hierarchically. Tag the top node
-of the resources with ~:taskjuggler_resource:~ (or whatever you
-customized ~org-export-taskjuggler-resource-tag~ to). You can
-optionally assign an identifier (named {{{samp(resource_id)}}}) to the
-resources (using the standard Org properties commands, see [[Property
-syntax]]) or you can let the exporter generate identifiers automatically
-(the exporter picks the first word of the headline as the identifier
-as long as it is unique---see the documentation of
-~org-taskjuggler-get-unique-id~). Using that identifier you can then
-allocate resources to tasks. This is again done with the
-{{{samp(allocate)}}} property on the tasks. Do this in column view or
-when on the task type
-{{{ksksksk(C-c C-x p allocate,RET,<resource_id>,RET)}}}.
-
-Once the allocations are done you can again export to TaskJuggler and
-check in the Resource Allocation Graph which person is working on what
-task at what time.
-
-*** Export of properties
- :PROPERTIES:
- :DESCRIPTION: Which properties will be exported?
- :END:
-
-The exporter also takes TODO state information into consideration,
-i.e., if a task is marked as done it will have the corresponding
-attribute in TaskJuggler ({{{samp(complete 100)}}}). Scheduling
-information is also taken into account to set start/end dates for
-tasks.
-
-The exporter will also export any property on a task resource or
-resource node which is known to TaskJuggler, such as
-{{{samp(limits)}}}, {{{samp(vacation)}}}, {{{samp(shift)}}},
-{{{samp(booking)}}}, {{{samp(efficiency)}}}, {{{samp(journalentry)}}},
-{{{samp(rate)}}} for resources or {{{samp(account)}}},
-{{{samp(start)}}}, {{{samp(note)}}}, {{{samp(duration)}}},
-{{{samp(end)}}}, {{{samp(journalentry)}}}, {{{samp(milestone)}}},
-{{{samp(reference)}}}, {{{samp(responsible)}}},
-{{{samp(scheduling)}}}, etc for tasks.
-
-*** Dependencies
- :PROPERTIES:
- :DESCRIPTION: How the exporter handles dependencies
- :END:
-
-The exporter will handle dependencies that are defined in the tasks
-either with the {{{samp(ORDERED)}}} attribute (see [[TODO dependencies]]),
-with the {{{samp(BLOCKER)}}} attribute (see {{{file(org-depend.el)}}})
-or alternatively with a {{{samp(depends)}}} attribute. Both the
-{{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can be
-either {{{samp(previous-sibling)}}} or a reference to an identifier
-(named {{{samp(task_id)}}}) which is defined for another task in the
-project. {{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can
-define multiple dependencies separated by either space or comma. You
-can also specify optional attributes on the dependency by simply
-appending it. The following examples should illustrate this:
-
-#+begin_example
- ,* Preparation
- , :PROPERTIES:
- , :task_id: preparation
- , :ORDERED: t
- , :END:
- ,* Training material
- , :PROPERTIES:
- , :task_id: training_material
- , :ORDERED: t
- , :END:
- ,** Markup Guidelines
- , :PROPERTIES:
- , :Effort: 2d
- , :END:
- ,** Workflow Guidelines
- , :PROPERTIES:
- , :Effort: 2d
- , :END:
- ,* Presentation
- , :PROPERTIES:
- , :Effort: 2d
- , :BLOCKER: training_material { gapduration 1d } preparation
- , :END:
-#+end_example
-
-*** Reports
- :PROPERTIES:
- :DESCRIPTION: Gantt charts, etc.
- :END:
-#+vindex: org-export-taskjuggler-default-reports
-
-TaskJuggler can produce many kinds of reports (e.g., gantt chart,
-resource allocation, etc). The user defines what kind of reports
-should be generated for a project in the TaskJuggler file. By default,
-the exporter will automatically insert some pre-set reports in the
-file. These defaults are defined in
-~org-export-taskjuggler-default-reports~. They can be modified using
-customize along with a number of other options. For a more complete
-list, see
-{{{ksksksk(M-x customize-group,RET,org-export-taskjuggler,RET)}}}.
-
-Alternately, the user can tag a tree with
-~org-export-taskjuggler-report-tag~, and define reports in sub-nodes,
-similarly to what is done with tasks or resources. The properties used
-for report generation are defined in
-~org-export-taskjuggler-valid-report-attributes~. In addition, a
-special property named {{{samp(report-kind)}}} is used to define the
-kind of report one wants to generate (by default, a
-{{{samp(taskreport)}}}).
-
-For more information and examples see the Org-taskjuggler tutorial at
-[[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html]].
-
-** Freemind export
- :PROPERTIES:
- :DESCRIPTION: Exporting to Freemind mind maps
- :END:
-#+cindex: Freemind export
-#+cindex: mind map
-
-The Freemind exporter was written by Lennart Borgman.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e m)}}}, ~org-export-as-freemind~ ::
- #+kindex: C-c C-e m
-
- Export as a Freemind mind map. For an Org file {{{file(myfile.org)}}},
- the Freemind file will be {{{file(myfile.mm)}}}.
-
-** XOXO export
- :PROPERTIES:
- :DESCRIPTION: Exporting to XOXO
- :END:
-#+cindex: XOXO export
-
-Org mode contains an exporter that produces XOXO-style output.
-Currently, this exporter only handles the general outline structure
-and does not interpret any additional Org mode features.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e x)}}}, ~org-export-as-xoxo~ ::
- #+kindex: C-c C-e x
-
- Export as an XOXO file. For an Org file {{{file(myfile.org)}}}, the
- XOXO file will be {{{file(myfile.html)}}}.
-
-- {{{kbd(C-c C-e v x)}}} ::
- #+kindex: C-c C-e v x
-
- Export only the visible part of the document.
-
-** iCalendar export
- :PROPERTIES:
- :DESCRIPTION: Exporting to iCalendar format
- :END:
-#+cindex: iCalendar export
-
-#+vindex: org-icalendar-include-todo
-#+vindex: org-icalendar-use-deadline
-#+vindex: org-icalendar-use-scheduled
-#+vindex: org-icalendar-categories
-#+vindex: org-icalendar-alarm-time
-
-Some people use Org mode for keeping track of projects, but still
-prefer a standard calendar application for anniversaries and
-appointments. In this case it can be useful to show deadlines and
-other time-stamped items in Org files in the calendar application. Org
-mode can export calendar information in the standard iCalendar format.
-If you also want to have TODO entries included in the export,
-configure the variable ~org-icalendar-include-todo~. Plain timestamps
-are exported as VEVENT, and TODO items as VTODO. It will also create
-events from deadlines that are in non-TODO items. Deadlines and
-scheduling dates in TODO items will be used to set the start and due
-dates for the TODO entry.[fn:143] As categories, it will use the tags
-locally defined in the heading, and the file/tree category.[fn:144]
-See the variable ~org-icalendar-alarm-time~ for a way to assign alarms
-to entries with a time.
-
-#+vindex: org-icalendar-store-UID
-#+cindex: property, ID
-
-The iCalendar standard requires each entry to have a globally unique
-identifier (UID). Org creates these identifiers during export. If you
-set the variable ~org-icalendar-store-UID~, the UID will be stored in
-the ~:ID:~ property of the entry and re-used next time you report this
-entry. Since a single entry can give rise to multiple iCalendar
-entries (as a timestamp, a deadline, a scheduled item, and as a TODO
-item), Org adds prefixes to the UID, depending on what triggered the
-inclusion of the entry. In this way the UID remains unique, but a
-synchronization program can still figure out from which entry all the
-different instances originate.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e i)}}}, ~org-export-icalendar-this-file~ ::
- #+kindex: C-c C-e i
-
- Create iCalendar entries for the current file and store them in the
- same directory, using a file extension {{{file(.ics)}}}.
-
-- {{{kbd(C-c C-e I)}}}, ~ org-export-icalendar-all-agenda-files~ ::
- #+kindex: C-c C-e I
- #+vindex: org-agenda-files
-
- Like {{{kbd(C-c C-e i)}}}, but do this for all files in
- ~org-agenda-files~. For each of these files, a separate iCalendar file
- will be written.
-
-- {{{kbd(C-c C-e c)}}}, ~org-export-icalendar-combine-agenda-files~ ::
- #+kindex: C-c C-e c
- #+vindex: org-combined-agenda-icalendar-file
-
- Create a single large iCalendar file from all files in
- ~org-agenda-files~ and write it to the file given by
- ~org-combined-agenda-icalendar-file~.
-
-
-#+vindex: org-use-property-inheritance
-#+vindex: org-icalendar-include-body
-#+cindex: property, SUMMARY
-#+cindex: property, DESCRIPTION
-#+cindex: property, LOCATION
-
-The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
-the selected entries have them.[fn:145] If not, the summary will be
-derived from the headline, and the description from the body (limited
-to ~org-icalendar-include-body~ characters).
-
-How this calendar is best read and updated, depends on the application
-you are using. The FAQ covers this issue.
-
-* Publishing
- :PROPERTIES:
- :DESCRIPTION: Create a web site of linked Org files
- :END:
-#+cindex: publishing
-#+cindex: O'Toole, David
-
-Org includes a publishing management system that allows you to
-configure automatic HTML conversion of /projects/ composed of
-interlinked org files. You can also configure Org to automatically
-upload your exported HTML pages and related attachments, such as
-images and source code files, to a web server.
-
-You can also use Org to convert files into PDF, or even combine HTML
-and PDF conversion so that files are available in both formats on the
-server.
-
-Publishing has been contributed to Org by David O'Toole.
-
-** Configuration
- :PROPERTIES:
- :DESCRIPTION: Defining projects
- :END:
-Publishing needs significant configuration to specify files,
-destination and many other properties of a project.
-
-*** Project alist
- :PROPERTIES:
- :DESCRIPTION: The central configuration variable
- :TITLE: The variable ~org-publish-project-alist~
- :END:
-#+cindex: org-publish-project-alist
-#+cindex: projects, for publishing
-#+vindex: org-publish-project-alist
-
-Publishing is configured almost entirely through setting the value of
-one variable, called ~org-publish-project-alist~. Each element of the
-list configures one project, and may be in one of the two following
-forms:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
- ("project-name" :property value :property value ...)
-#+end_src
-
-i.e., a well-formed property list with alternating keys and values,
-or:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
- ("project-name" :components ("project-name" "project-name" ...))
-#+end_src
-
-In both cases, projects are configured by specifying property values.
-A project defines the set of files that will be published, as well as
-the publishing configuration to use when publishing those files. When
-a project takes the second form listed above, the individual members
-of the ~:components~ property are taken to be sub-projects, which
-group together files requiring different publishing options. When you
-publish such a "meta-project," all the components will also be
-published, in the sequence given.
-
-*** Sources and destinations
- :PROPERTIES:
- :DESCRIPTION: From here to there
- :TITLE: Sources and destinations for files
- :END:
-#+cindex: directories, for publishing
-
-Most properties are optional, but some should always be set. In
-particular, Org needs to know where to look for source files, and
-where to put published files.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:base-directory~ ::
-
- Directory containing publishing source files
-
-- ~:publishing-directory~ ::
-
- Directory where output files will be published. You can directly
- publish to a webserver using a file name syntax appropriate for the
- Emacs {{{file(tramp)}}} package. Or you can publish to a local
- directory and use external tools to upload your website
- (see [[Uploading files]]).
-
-- ~:preparation-function~ ::
-
- Function or list of functions to be called before starting the
- publishing process, for example, to run ~make~ for updating files to
- be published. The project property list is scoped into this call as
- the variable ~project-plist~.
-
-- ~:completion-function~ ::
-
- Function or list of functions called after finishing the publishing
- process, for example, to change permissions of the resulting files.
- The project property list is scoped into this call as the variable
- ~project-plist~.
-
-*** Selecting files
- :PROPERTIES:
- :DESCRIPTION: What files are part of the project?
- :END:
-#+cindex: files, selecting for publishing
-
-By default, all files with extension {{{file(.org)}}} in the base directory
-are considered part of the project. This can be modified by setting the
-following properties:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:base-extension~ ::
-
- Extension (without the dot!) of source files. This actually is a
- regular expression. Set this to the symbol ~any~ if you want to get
- all files in ~:base-directory~, even without extension.
-
-- ~:exclude~ ::
-
- Regular expression to match file names that should not be published,
- even though they have been selected on the basis of their extension.
-
-- ~:include~ ::
-
- List of files to be included regardless of ~:base-extension~ and
- ~:exclude~.
-
-- ~:recursive~ ::
-
- Non-nil means, check base-directory recursively for files to publish.
-
-*** Publishing action
- :PROPERTIES:
- :DESCRIPTION: Setting the function doing the publishing
- :END:
-#+cindex: action, for publishing
-
-Publishing means that a file is copied to the destination directory and
-possibly transformed in the process. The default transformation is to export
-Org files as HTML files, and this is done by the function
-~org-publish-org-to-html~ which calls the HTML exporter (see [[HTML
-export]]). But you also can publish your content as PDF files using
-~org-publish-org-to-pdf~, or as ~ascii~, ~latin1~ or
-~utf8~ encoded files using the corresponding functions. If you want to
-publish the Org file itself, but with /archived/, /commented/, and
-/tag-excluded/ trees removed, use ~org-publish-org-to-org~ and set the
-parameters ~:plain-source~ and/or ~:htmlized-source~. This will
-produce {{{file(file.org)}}} and {{{file(file.org.html)}}} in the publishing
-directory.[fn:146] Other files like images only need to be copied to the
-publishing destination; for this you may use ~org-publish-attachment~.
-For non-Org files, you always need to specify the publishing function:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:publishing-function~ ::
-
- Function executing the publication of a file. This may also be a list
- of functions, which will all be called in turn.
-
-- ~:plain-source~ ::
-
- Non-nil means, publish plain source.
-
-- ~:htmlized-source~ ::
-
- Non-nil means, publish htmlized source.
-
-
-The function must accept three arguments: a property list containing
-at least a ~:publishing-directory~ property, the name of the file to
-be published, and the path to the publishing directory of the output
-file. It should take the specified file, make the necessary
-transformation (if any) and place the result into the destination
-folder.
-
-*** Publishing options
- :PROPERTIES:
- :DESCRIPTION: Tweaking HTML/LaTeX export
- :END:
-#+cindex: options, for publishing
-
-The property list can be used to set many export options for the HTML
-and LaTeX exporters. In most cases, these properties correspond to user
-variables in Org. The table below lists these properties along
-with the variable they belong to. See the documentation string for the
-respective variable for details.
-
-#+vindex: org-export-html-link-up
-#+vindex: org-export-html-link-home
-#+vindex: org-export-default-language
-#+vindex: org-display-custom-times
-#+vindex: org-export-headline-levels
-#+vindex: org-export-with-section-numbers
-#+vindex: org-export-section-number-format
-#+vindex: org-export-with-toc
-#+vindex: org-export-preserve-breaks
-#+vindex: org-export-with-archived-trees
-#+vindex: org-export-with-emphasize
-#+vindex: org-export-with-sub-superscripts
-#+vindex: org-export-with-special-strings
-#+vindex: org-export-with-footnotes
-#+vindex: org-export-with-drawers
-#+vindex: org-export-with-tags
-#+vindex: org-export-with-todo-keywords
-#+vindex: org-export-with-tasks
-#+vindex: org-export-with-done-tasks
-#+vindex: org-export-with-priority
-#+vindex: org-export-with-TeX-macros
-#+vindex: org-export-with-LaTeX-fragments
-#+vindex: org-export-skip-text-before-1st-heading
-#+vindex: org-export-with-fixed-width
-#+vindex: org-export-with-timestamps
-#+vindex: org-export-author-info
-#+vindex: org-export-email-info
-#+vindex: org-export-creator-info
-#+vindex: org-export-time-stamp-file
-#+vindex: org-export-with-tables
-#+vindex: org-export-highlight-first-table-line
-#+vindex: org-export-html-style-include-default
-#+vindex: org-export-html-style-include-scripts
-#+vindex: org-export-html-style
-#+vindex: org-export-html-style-extra
-#+vindex: org-export-html-link-org-files-as-html
-#+vindex: org-export-html-inline-images
-#+vindex: org-export-html-extension
-#+vindex: org-export-html-table-tag
-#+vindex: org-export-html-expand
-#+vindex: org-export-html-with-timestamp
-#+vindex: org-export-publishing-directory
-#+vindex: org-export-html-preamble
-#+vindex: org-export-html-postamble
-#+vindex: user-full-name
-#+vindex: user-mail-address
-#+vindex: org-export-select-tags
-#+vindex: org-export-exclude-tags
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:link-up~ :: ~org-export-html-link-up~
-- ~:link-home~ :: ~org-export-html-link-home~
-- ~:language~ :: ~org-export-default-language~
-- ~:customtime~ :: ~org-display-custom-times~
-- ~:headline-levels~ :: ~org-export-headline-levels~
-- ~:section-numbers~ :: ~org-export-with-section-numbers~
-- ~:section-number-format~ :: ~org-export-section-number-format~
-- ~:table-of-contents~ :: ~org-export-with-toc~
-- ~:preserve-breaks~ :: ~org-export-preserve-breaks~
-- ~:archived-trees~ :: ~org-export-with-archived-trees~
-- ~:emphasize~ :: ~org-export-with-emphasize~
-- ~:sub-superscript~ :: ~org-export-with-sub-superscripts~
-- ~:special-strings~ :: ~org-export-with-special-strings~
-- ~:footnotes~ :: ~org-export-with-footnotes~
-- ~:drawers~ :: ~org-export-with-drawers~
-- ~:tags~ :: ~org-export-with-tags~
-- ~:todo-keywords~ :: ~org-export-with-todo-keywords~
-- ~:tasks~ :: ~org-export-with-tasks~
-- ~:priority~ :: ~org-export-with-priority~
-- ~:TeX-macros~ :: ~org-export-with-TeX-macros~
-- ~:LaTeX-fragments~ :: ~org-export-with-LaTeX-fragments~
-- ~:latex-listings~ :: ~org-export-latex-listings~
-- ~:skip-before-1st-heading~ :: ~org-export-skip-text-before-1st-heading~
-- ~:fixed-width~ :: ~org-export-with-fixed-width~
-- ~:timestamps~ :: ~org-export-with-timestamps~
-- ~:author~ :: ~user-full-name~
-- ~:email~ :: ~user-mail-address~ : ~addr;addr;..~
-- ~:author-info~ :: ~org-export-author-info~
-- ~:email-info~ :: ~org-export-email-info~
-- ~:creator-info~ :: ~org-export-creator-info~
-- ~:tables~ :: ~org-export-with-tables~
-- ~:table-auto-headline~ :: ~org-export-highlight-first-table-line~
-- ~:style-include-default~ :: ~org-export-html-style-include-default~
-- ~:style-include-scripts~ :: ~org-export-html-style-include-scripts~
-- ~:style~ :: ~org-export-html-style~
-- ~:style-extra~ :: ~org-export-html-style-extra~
-- ~:convert-org-links~ :: ~org-export-html-link-org-files-as-html~
-- ~:inline-images~ :: ~org-export-html-inline-images~
-- ~:html-extension~ :: ~org-export-html-extension~
-- ~:html-preamble~ :: ~org-export-html-preamble~
-- ~:html-postamble~ :: ~org-export-html-postamble~
-- ~:xml-declaration~ :: ~org-export-html-xml-declaration~
-- ~:html-table-tag~ :: ~org-export-html-table-tag~
-- ~:expand-quoted-html~ :: ~org-export-html-expand~
-- ~:timestamp~ :: ~org-export-html-with-timestamp~
-- ~:publishing-directory~ :: ~org-export-publishing-directory~
-- ~:select-tags~ :: ~org-export-select-tags~
-- ~:exclude-tags~ :: ~org-export-exclude-tags~
-- ~:latex-image-options~ :: ~org-export-latex-image-default-option~
-
-
-Most of the ~org-export-with-*~ variables have the same effect in both
-HTML and LaTeX exporters, except for ~:TeX-macros~ and
-~:LaTeX-fragments~ options, respectively ~nil~ and ~t~ in the LaTeX
-export. See ~org-export-plist-vars~ to check this list of options.
-
-#+vindex: org-publish-project-alist
-
-When a property is given a value in ~org-publish-project-alist~, its
-setting overrides the value of the corresponding user variable (if
-any) during publishing. Options set within a file (see [[Export
-options]]), however, override everything.
-
-*** Publishing links
- :PROPERTIES:
- :DESCRIPTION: Which links keep working after publishing?
- :END:
-#+cindex: links, publishing
-
-To create a link from one Org file to another, you would use something
-like ~[[file:foo.org][The foo]]~ or simply ~[[file:foo.org]]~ (see
-[[Hyperlinks]]). When published, this link becomes a link to
-{{{file(foo.html)}}}. In this way, you can interlink the pages of your
-"org web" project and the links will work as expected when you publish
-them to HTML. If you also publish the Org source file and want to link
-to that, use an ~http:~ link instead of a ~file:~ link, because
-~file:~ links are converted to link to the corresponding
-{{{file(html)}}} file.
-
-You may also link to related files, such as images. Provided you are
-careful with relative file names, and provided you have also
-configured Org to upload the related files, these links will work too.
-See [[Complex example]], for an example of this usage.
-
-Sometimes an Org file to be published may contain links that are only
-valid in your production environment, but not in the publishing
-location. In this case, use the following property to define a
-function for checking link validity:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:link-validation-function~ ::
- Function to validate links
-
-
-{{{noindent}}} This function must accept two arguments, the file name
-and a directory relative to which the file name is interpreted in the
-production environment. If this function returns ~nil~, then the HTML
-generator will only insert a description into the HTML file, but no
-link. One option for this function is ~org-publish-validate-link~
-which checks if the given file is part of any project in
-~org-publish-project-alist~.
-
-*** Site map
- :PROPERTIES:
- :DESCRIPTION: Generating a list of all pages
- :TITLE: Generating a sitemap
- :END:
-#+cindex: sitemap, of published pages
-
-The following properties may be used to control publishing of
-a map of files for a given project.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:auto-sitemap~ ::
-
- When non-nil, publish a sitemap during ~org-publish-current-project~
- or ~org-publish-all~.
-
-- ~:sitemap-filename~ ::
-
- Filename for output of sitemap. Defaults to {{{file(sitemap.org)}}} (which
- becomes {{{file(sitemap.html)}}}).
-
-- ~:sitemap-title~ ::
-
- Title of sitemap page. Defaults to name of file.
-
-- ~:sitemap-function~ ::
-
- Plug-in function to use for generation of the sitemap. Defaults to
- ~org-publish-org-sitemap~, which generates a plain list of links to
- all files in the project.
-
-- ~:sitemap-sort-folders~ ::
-
- Where folders should appear in the sitemap. Set this to ~first~
- (default) or ~last~ to display folders first or last, respectively.
- Any other value will mix files and folders.
-
-- ~:sitemap-sort-files~ ::
-
- How the files are sorted in the site map. Set this to ~alphabetically~
- (default), ~chronologically~ or ~anti-chronologically~.
- ~chronologically~ sorts the files with older date first while
- ~anti-chronologically~ sorts the files with newer date first.
- ~alphabetically~ sorts the files alphabetically. The date of a file is
- retrieved with ~org-publish-find-date~.
-
-- ~:sitemap-ignore-case~ ::
-
- Should sorting be case-sensitive? Default ~nil~.
-
-- ~:sitemap-file-entry-format~ ::
-
- With this option one can tell how a sitemap's entry is formatted in
- the sitemap. This is a format string with some escape sequences: ~%t~
- stands for the title of the file, ~%a~ stands for the author of the
- file and ~%d~ stands for the date of the file. The date is retrieved
- with the ~org-publish-find-date~ function and formatted with
- ~org-publish-sitemap-date-format~. Default ~%t~.
-
-- ~:sitemap-date-format~ ::
-
- Format string for the ~format-time-string~ function that tells how a
- sitemap entry's date is to be formatted. This property bypasses
- ~org-publish-sitemap-date-format~ which defaults to ~%Y-%m-%d~.
-
-- ~:sitemap-sans-extension~ ::
-
- When non-nil, remove filenames' extensions from the generated sitemap.
- Useful to have cool URIs (see [[http://www.w3.org/Provider/Style/URI]]).
- Defaults to ~nil~.
-
-*** Generating an index
- :PROPERTIES:
- :DESCRIPTION: An index that reaches across pages
- :END:
-#+cindex: index, in a publishing project
-
-Org mode can generate an index across the files of a publishing project.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:makeindex~ ::
-
- When non-nil, generate in index in the file {{{file(theindex.org)}}}
- and publish it as {{{file(theindex.html)}}}.
-
-
-The file will be created when first publishing a project with the
-~:makeindex~ set. The file only contains a statement
-{{{samp(#+INCLUDE: "theindex.inc")}}}. You can then build around this
-include statement by adding a title, style information, etc.
-
-** Uploading files
- :PROPERTIES:
- :DESCRIPTION: How to get files up on the server
- :END:
-#+cindex: rsync
-#+cindex: unison
-
-For those people already utilizing third party sync tools such as
-{{{command(rsync)}}} or {{{command(unison)}}}, it might be preferable
-not to use the built in remote publishing facilities of Org mode
-which rely heavily on Tramp. Tramp, while very useful and powerful,
-tends not to be so efficient for multiple file transfer and has been
-known to cause problems under heavy usage.
-
-Specialized synchronization utilities offer several advantages. In
-addition to timestamp comparison, they also do content and
-permissions/attribute checks. For this reason you might prefer to
-publish your web to a local directory (possibly even in place with
-your Org files) and then use {{{file(unison)}}} or {{{file(rsync)}}}
-to do the synchronization with the remote host.
-
-Since Unison (for example) can be configured as to which files to
-transfer to a certain remote destination, it can greatly simplify the
-project publishing definition. Simply keep all files in the correct
-location, process your Org files with ~org-publish~ and let the
-synchronization tool do the rest. You do not need, in this scenario,
-to include attachments such as {{{file(jpg)}}}, {{{file(css)}}} or
-{{{file(gif)}}} files in the project definition since the 3rd party
-tool syncs them.
-
-Publishing to a local directory is also much faster than to a remote
-one, so that you can afford more easily to republish entire projects.
-If you set ~org-publish-use-timestamps-flag~ to ~nil~, you gain the
-main benefit of re-including any changed external files such as source
-example files you might include with ~#+INCLUDE:~. The timestamp
-mechanism in Org is not smart enough to detect if included files have
-been modified.
-
-** Sample configuration
- :PROPERTIES:
- :DESCRIPTION: Example projects
- :END:
-Below we provide two example configurations. The first one is a simple
-project publishing only a set of Org files. The second example is
-more complex, with a multi-component project.
-
-*** Simple example
- :PROPERTIES:
- :DESCRIPTION: One-component publishing
- :TITLE: Example: simple publishing configuration
- :END:
-This example publishes a set of Org files to the {{{file(public_html)}}}
-directory on the local machine.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(setq org-publish-project-alist
- '(("org"
- :base-directory "~/org/"
- :publishing-directory "~/public_html"
- :section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
- href=\"../other/mystyle.css\"
- type=\"text/css\"/>")))
-#+end_src
-
-*** Complex example
- :PROPERTIES:
- :DESCRIPTION: A multi-component publishing example
- :TITLE: Example: complex publishing configuration
- :END:
-This more complicated example publishes an entire website, including
-Org files converted to HTML, image files, Emacs Lisp source code, and
-style sheets. The publishing directory is remote and private files are
-excluded.
-
-To ensure that links are preserved, care should be taken to replicate
-your directory structure on the web server, and to use relative file
-paths. For example, if your Org files are kept in {{{file(~/org)}}}
-and your publishable images in {{{file(~/images)}}}, you would link to
-an image with
-
-#+begin_example
- file:../images/myimage.png
-#+end_example
-
-On the web server, the relative path to the image should be the
-same. You can accomplish this by setting up an "images" folder in the
-right place on the web server, and publishing images to it.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(setq org-publish-project-alist
- '(("orgfiles"
- :base-directory "~/org/"
- :base-extension "org"
- :publishing-directory "/ssh:user@@host:~/html/notebook/"
- :publishing-function org-publish-org-to-html
- :exclude "PrivatePage.org" ;; regexp
- :headline-levels 3
- :section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
- href=\"../other/mystyle.css\" type=\"text/css\"/>"
- :html-preamble t)
-
- ("images"
- :base-directory "~/images/"
- :base-extension "jpg\\|gif\\|png"
- :publishing-directory "/ssh:user@@host:~/html/images/"
- :publishing-function org-publish-attachment)
-
- ("other"
- :base-directory "~/other/"
- :base-extension "css\\|el"
- :publishing-directory "/ssh:user@@host:~/html/other/"
- :publishing-function org-publish-attachment)
- ("website" :components ("orgfiles" "images" "other"))))
-#+end_src
-
-** Triggering publication
- :PROPERTIES:
- :DESCRIPTION: Publication commands
- :END:
-Once properly configured, Org can publish with the following commands:
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(C-c C-e X)}}}, ~org-publish~ ::
- #+kindex: C-c C-e X
-
- Prompt for a specific project and publish all files that belong to it.
-
-- {{{kbd(C-c C-e P)}}}, ~org-publish-current-project~ ::
- #+kindex: C-c C-e P
-
- Publish the project containing the current file.
-
-- {{{kbd(C-c C-e F)}}}, ~org-publish-current-file~ ::
- #+kindex: C-c C-e F
-
- Publish only the current file.
-
-- {{{kbd(C-c C-e E)}}}, ~org-publish-all~ ::
- #+kindex: C-c C-e E
-
- Publish every project.
-
-
-#+vindex: org-publish-use-timestamps-flag
-
-Org uses timestamps to track when a file has changed. The above
-functions normally only publish changed files. You can override this
-and force publishing of all files by giving a prefix argument to any
-of the commands above, or by customizing the variable
-~org-publish-use-timestamps-flag~. This may be necessary in particular
-if files include other files via ~#+SETUPFILE:~ or ~#+INCLUDE:~.
-
-* Working with source code
- :PROPERTIES:
- :DESCRIPTION: Export, evaluate, and tangle code blocks
- :ALT_TITLE: Working With Source Code
- :END:
-#+cindex: Schulte, Eric
-#+cindex: Davison, Dan
-#+cindex: source code, working with
-
-Source code can be included in Org mode documents using a
-{{{samp(src)}}} block, e.g.:
-
-#+begin_example
- #+BEGIN_SRC emacs-lisp
- (defun org-xor (a b)
- "Exclusive or."
- (if a (not b) b))
- #+END_SRC
-#+end_example
-
-Org mode provides a number of features for working with live source
-code, including editing of code blocks in their native major-mode,
-evaluation of code blocks, converting code blocks into source files
-(known as "tangling" in literate programming), and exporting code
-blocks and their results in several formats. This functionality was
-contributed by Eric Schulte and Dan Davison, and was originally named
-Org-babel.
-
-The following sections describe Org mode's code block handling facilities.
-
-** Structure of code blocks
- :PROPERTIES:
- :DESCRIPTION: Code block syntax described
- :END:
-#+cindex: code block, structure
-#+cindex: source code, block structure
-#+cindex: #+NAME
-#+cindex: #+BEGIN_SRC
-
-Live code blocks can be specified with a {{{samp(src)}}} block or
-inline.[fn:147] The structure of a {{{samp(src)}}} block is shown in
-the following example:
-
-#+begin_example
- ,#+NAME: <name>
- ,#+BEGIN_SRC <language> <switches> <header arguments>
- <body>
- ,#+END_SRC
-#+end_example
-
-The ~#+NAME:~ line is optional, and can be used to name the code
-block. Live code blocks require that a language be specified on the
-~#+BEGIN_SRC~ line. Switches and header arguments are optional.
-#+cindex: source code, inline
-
-Live code blocks can also be specified inline using the following
-syntax:
-
-#+begin_example
- src_<language>{<body>}
-#+end_example
-
-or
-
-#+begin_example
- src_<language>[<header arguments>]{<body>}
-#+end_example
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~<#+NAME: name>~ ::
- #+cindex: #+NAME
-
- This line associates a name with the code block. This is similar to
- the ~#+TBLNAME: NAME~ lines that can be used to name tables in Org
- mode files. Referencing the name of a code block makes it possible to
- evaluate the block from other places in the file, from other files, or
- from Org mode table formulas (see [[The spreadsheet]]). Names are assumed
- to be unique and the behavior of Org mode when two or more blocks
- share the same name is undefined.
-
-- ~<language>~ ::
- #+cindex: source code, language
-
- The language of the code in the block (see [[Languages]]).
-
-- ~<switches>~ ::
- #+cindex: source code, switches
-
- Optional switches control code block export (see the discussion of
- switches in [[Literal examples]]).
-
-- ~<header arguments>~ ::
- #+cindex: source code, header arguments
-
- Optional header arguments control many aspects of evaluation, export
- and tangling of code blocks (see [[Header arguments]]). Header arguments
- can also be set on a per-buffer or per-subtree basis using properties.
-
-- ~<body>~ ::
-
- Source code in the specified language.
-
-** Editing source code
- :PROPERTIES:
- :DESCRIPTION: Language major-mode editing
- :END:
-#+cindex: code block, editing
-#+cindex: source code, editing
-#+kindex: C-c '
-
-Use {{{kbd(C-c ')}}} to edit the current code block. This brings up a
-language major-mode edit buffer containing the body of the code block.
-Saving this buffer will write the new contents back to the Org buffer.
-Use {{{kbd(C-c ')}}} again to exit.
-
-The ~org-src-mode~ minor mode will be active in the edit buffer. The
-following variables can be used to configure the behavior of the edit
-buffer. See also the customization group ~org-edit-structure~ for
-further configuration options.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~org-src-lang-modes~ ::
-
- If an Emacs major-mode named ~<lang>-mode~ exists, where
- ~<lang>~ is the language named in the header line of the code block,
- then the edit buffer will be placed in that major-mode. This variable
- can be used to map arbitrary language names to existing major modes.
-
-- ~org-src-window-setup~ ::
-
- Controls the way Emacs windows are rearranged when the edit buffer is
- created.
-
-- ~org-src-preserve-indentation~ ::
-
- This variable is especially useful for tangling languages such as
- Python, in which whitespace indentation in the output is meaningful.
-
-- ~org-src-ask-before-returning-to-edit-buffer~ ::
-
- By default, Org will ask before returning to an open edit buffer. Set this
- variable to nil to switch without asking.
-
-
-To turn on native code fontification in the Org mode buffer, configure
-the variable ~org-src-fontify-natively~.
-
-** Exporting code blocks
- :PROPERTIES:
- :DESCRIPTION: Export contents and/or results
- :END:
-#+cindex: code block, exporting
-#+cindex: source code, exporting
-
-It is possible to export the /code/ of code blocks, the /results/ of
-code block evaluation, /both/ the code and the results of code block
-evaluation, or /none/. For most languages, the default exports code.
-However, for some languages (e.g., ~ditaa~) the default exports the
-results of code block evaluation. For information on exporting code
-block bodies, see [[Literal examples]].
-
-The ~:exports~ header argument can be used to specify export
-behavior with the following arguments:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:exports code~ ::
-
- The default in most languages. The body of the code block is exported, as
- described in [[Literal examples]].
-
-- ~:exports results~ ::
-
- The code block will be evaluated and the results will be placed in the
- Org mode buffer for export, either updating previous results of the
- code block located anywhere in the buffer or, if no previous results
- exist, placing the results immediately after the code block. The body
- of the code block will not be exported.
-
-- ~:exports both~ ::
-
- Both the code block and its results will be exported.
-
-- ~:exports none~ ::
-
- Neither the code block nor its results will be exported.
-
-
-It is possible to inhibit the evaluation of code blocks during export.
-Setting the ~org-export-babel-evaluate~ variable to ~nil~ will ensure
-that no code blocks are evaluated as part of the export process. This
-can be useful in situations where potentially untrusted Org mode files
-are exported in an automated fashion, for example when Org mode is
-used as the markup language for a wiki.
-
-** Extracting source code
- :PROPERTIES:
- :DESCRIPTION: Create pure source code files
- :END:
-#+cindex: tangling
-#+cindex: source code, extracting
-#+cindex: code block, extracting source code
-
-Creating pure source code files by extracting code from source blocks
-is referred to as "tangling"---a term adopted from the literate
-programming community. During tangling of code blocks their bodies are
-expanded using ~org-babel-expand-src-block~ which can expand both
-variable and ``noweb'' style references (see [[Noweb reference syntax]]).
-
-*** Header arguments for tangling
-#+attr_texinfo: :table-type table :indic @asis
-- ~:tangle no~ ::
-
- The default. The code block is not included in the tangled output.
-
-- ~:tangle yes~ ::
-
- Include the code block in the tangled output. The output file name is
- the name of the org file with the extension {{{samp(.org)}}} replaced
- by the extension for the block language.
-
-- ~:tangle filename~ ::
-
- Include the code block in the tangled output to file {{{samp(filename)}}}.
-
-*** Functions for tangling
-#+attr_texinfo: :table-type table :indic @asis
-- ~org-babel-tangle~ ::
- #+kindex: C-c C-v t
-
- Tangle the current file. Bound to {{{kbd(C-c C-v t)}}}.
-
- With a prefix argument only tangle the current code block.
-
-- ~org-babel-tangle-file~ ::
- #+kindex: C-c C-v f
-
- Choose a file to tangle. Bound to {{{kbd(C-c C-v f)}}}.
-
-*** Hooks for tangling
-#+attr_texinfo: :table-type table :indic @asis
-- ~org-babel-post-tangle-hook~ ::
-
- This hook is run from within code files tangled by ~org-babel-tangle~.
- Example applications could include post-processing, compilation, or
- evaluation of tangled code files.
-
-** Evaluating code blocks
- :PROPERTIES:
- :DESCRIPTION: Place results in the Org buffer
- :END:
-#+cindex: code block, evaluating
-#+cindex: source code, evaluating
-#+cindex: #+RESULTS
-
-Code blocks can be evaluated and the results of evaluation optionally
-placed in the Org mode buffer.[fn:148] The results of evaluation are
-placed following a line that begins by default with ~#+RESULTS~ and
-optionally a cache identifier and/or the name of the evaluated code
-block. The default value of ~#+RESULTS~ can be changed with the
-customizable variable ~org-babel-results-keyword~.
-
-By default, the evaluation facility is only enabled for Lisp code
-blocks specified as ~emacs-lisp~. However, source code blocks in many
-languages can be evaluated within Org mode (see [[Languages]] for a list
-of supported languages and [[Structure of code blocks]] for information on
-the syntax used to define a code block).
-
-#+kindex: C-c C-c
-#+kindex: C-c C-v e
-
-There are a number of ways to evaluate code blocks. The simplest is to
-press {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-v e)}}} with the point on a
-code block.[fn:149] This will call the ~org-babel-execute-src-block~
-function to evaluate the block and insert its results into the Org
-mode buffer.
-
-#+cindex: #+CALL
-
-It is also possible to evaluate named code blocks from anywhere in an
-Org mode buffer or an Org mode table. Live code blocks located in the
-current Org mode buffer or in the ``Library of Babel'' (see [[Library of
-Babel]]) can be executed. Named code blocks can be executed with a
-separate ~#+CALL:~ line or inline within a block of text.
-
-The syntax of the ~#+CALL:~ line is:
-
-#+begin_example
- ,#+CALL: <name>(<arguments>)
- ,#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
-#+end_example
-
-The syntax for inline evaluation of named code blocks is:
-
-#+begin_example
- ... call_<name>(<arguments>) ...
- ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
-#+end_example
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~<name>~ ::
-
- The name of the code block to be evaluated (see [[Structure of code
- blocks]]).
-
-- ~<arguments>~ ::
-
- Arguments specified in this section will be passed to the code block.
- These arguments use standard function call syntax, rather than header
- argument syntax. For example, a ~#+CALL:~ line that passes the number
- four to a code block named ~double~, which declares the header
- argument ~:var n=2~, would be written as ~#+CALL: double(n=4)~.
-
-- ~<inside header arguments>~ ::
-
- Inside header arguments are passed through and applied to the named
- code block. These arguments use header argument syntax rather than
- standard function call syntax. Inside header arguments affect how the
- code block is evaluated. For example, ~[:results output]~ will collect
- the results of everything printed to ~STDOUT~ during execution of the
- code block.
-
-- ~<end header arguments>~ ::
-
- End header arguments are applied to the calling instance and do not
- affect evaluation of the named code block. They affect how the results
- are incorporated into the Org mode buffer and how the call line is
- exported. For example, ~:results html~ will insert the results of the
- call line evaluation in the Org buffer, wrapped in a ~BEGIN_HTML:~
- block.
-
-
-For more examples of passing header arguments to ~#+CALL:~ lines see
-[[Header arguments in function calls]].
-
-** Library of Babel
- :PROPERTIES:
- :DESCRIPTION: Use and contribute to a source code library
- :END:
-#+cindex: babel, library of
-#+cindex: source code, library
-#+cindex: code block, library
-
-The ``Library of Babel'' consists of code blocks that can be called
-from any Org mode file. Code blocks defined in the ``Library of
-Babel'' can be called remotely as if they were in the current Org mode
-buffer (see [[Evaluating code blocks]] for information on the syntax of
-remote code block evaluation).
-
-
-The central repository of code blocks in the ``Library of Babel'' is
-housed in an Org mode file located in the {{{samp(contrib)}}}
-directory of Org mode.
-
-Users can add code blocks they believe to be generally useful to their
-``Library of Babel.'' The code blocks can be stored in any Org mode
-file and then loaded into the library with ~org-babel-lob-ingest~.
-
-#+kindex: C-c C-v i
-
-Code blocks located in any Org mode file can be loaded into the
-``Library of Babel'' with the ~org-babel-lob-ingest~ function, bound
-to {{{kbd(C-c C-v i)}}}.
-
-** Languages
- :PROPERTIES:
- :DESCRIPTION: Supported code block languages
- :END:
-#+cindex: babel, languages
-#+cindex: source code, languages
-#+cindex: code block, languages
-
-Code blocks in the following languages are supported.
-
-#+attr_texinfo: :columns 0.24 0.24 0.04 0.24 0.24
-| Language | Identifier | | Language | Identifier |
-|------------+--------------+---+----------------+--------------|
-| Asymptote | asymptote | | Awk | awk |
-| Emacs Calc | calc | | C | C |
-| C++ | C++ | | Clojure | clojure |
-| CSS | css | | ditaa | ditaa |
-| Graphviz | dot | | Emacs Lisp | emacs-lisp |
-| gnuplot | gnuplot | | Haskell | haskell |
-| Java | java | | | |
-| Javascript | js | | LaTeX | latex |
-| Ledger | ledger | | Lisp | lisp |
-| Lilypond | lilypond | | MATLAB | matlab |
-| Mscgen | mscgen | | Objective Caml | ocaml |
-| Octave | octave | | Org mode | org |
-| Oz | oz | | Perl | perl |
-| Plantuml | plantuml | | Python | python |
-| R | R | | Ruby | ruby |
-| Sass | sass | | Scheme | scheme |
-| GNU Screen | screen | | shell | sh |
-| SQL | sql | | SQLite | sqlite |
-
-
-Language-specific documentation is available for some languages. If
-available, it can be found at
-[[http://orgmode.org/worg/org-contrib/babel/languages.html]].
-
-The variable ~org-babel-load-languages~ controls which languages are
-enabled for evaluation (by default only ~emacs-lisp~ is enabled). This
-variable can be set using the customization interface or by adding
-code like the following example, disables ~emacs-lisp~ evaluation and
-enables evaluation of ~R~ code blocks, to your emacs configuration:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(org-babel-do-load-languages
- 'org-babel-load-languages
- '((emacs-lisp . nil)
- (R . t)))
-#+end_src
-
-It is also possible to enable support for a language by loading the
-related elisp file with ~require~.
-
-{{{noindent}}} The following example adds support for evaluating
-~clojure~ code blocks:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(require 'ob-clojure)
-#+end_src
-
-** Header arguments
- :PROPERTIES:
- :DESCRIPTION: Configure code block functionality
- :END:
-#+cindex: code block, header arguments
-#+cindex: source code, block header arguments
-
-Code block functionality can be configured with header arguments. This
-section provides an overview of the use of header arguments, and then
-describes each header argument in detail.
-
-*** Using header arguments
- :PROPERTIES:
- :DESCRIPTION: Different ways to set header arguments
- :END:
-
-The values of header arguments can be set in six different ways, each
-more specific (and having higher priority) than the last.
-
-**** System-wide header arguments
- :PROPERTIES:
- :DESCRIPTION: Set global default values
- :END:
-#+vindex: org-babel-default-header-args
-
-System-wide values of header arguments can be specified by customizing
-the ~org-babel-default-header-args~ variable:
-
-#+begin_example
- :session => "none"
- :results => "replace"
- :exports => "code"
- :cache => "no"
- :noweb => "no"
-#+end_example
-
-# #+begin_example
-# org-babel-default-header-args is a variable defined in `org-babel.el'.
-# Its value is
-# ((:session . "none")
-# (:results . "replace")
-# (:exports . "code")
-# (:cache . "no")
-# (:noweb . "no"))
-
-
-# Documentation:
-# Default arguments to use when evaluating a code block.
-# #+end_example
-
-For example, the following code could be used to set the default
-value of ~:noweb~ header arguments to ~yes~. This would have the
-effect of expanding ~:noweb~ references by default when evaluating
-source code blocks.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
- (setq org-babel-default-header-args
- (cons '(:noweb . "yes")
- (assq-delete-all :noweb org-babel-default-header-args)))
-#+end_src
-
-**** Language-specific header arguments
- :PROPERTIES:
- :DESCRIPTION: Set default values by language
- :END:
-
-Each language can define its own set of default header arguments. See
-the language-specific documentation available online at
-[[http://orgmode.org/worg/org-contrib/babel]].
-
-**** Buffer-wide header arguments
- :PROPERTIES:
- :DESCRIPTION: Set default values for a specific buffer
- :END:
-
-Buffer-wide header arguments may be specified as properties through
-the use of ~#+PROPERTY:~ lines placed anywhere in an Org mode file
-(see [[Property syntax]]).
-
-For example the following would set ~session~ to ~*R*~, and ~results~
-to ~silent~ for every code block in the buffer, ensuring that all
-execution took place in the same session, and no results would be
-inserted into the buffer.
-
-#+begin_example
- ,#+PROPERTY: session *R*
- ,#+PROPERTY: results silent
-#+end_example
-
-**** Header arguments in Org mode properties
- :PROPERTIES:
- :DESCRIPTION: Set default values for a buffer or heading
- :END:
-
-Header arguments are also read from Org mode properties (see [[Property
-syntax]]), which can be set on a buffer-wide or per-heading basis. An
-example of setting a header argument for all code blocks in a buffer
-is as follows:
-
-#+begin_example
- ,#+PROPERTY: tangle yes
-#+end_example
-
-#+vindex: org-use-property-inheritance
-
-When properties are used to set default header arguments, they are
-looked up with inheritance, regardless of the value of
-~org-use-property-inheritance~. In the following example the value of
-the ~:cache~ header argument will default to ~yes~ in all code blocks
-in the subtree rooted at the following heading:
-
-#+begin_example
- ,* outline header
- ,:PROPERTIES:
- ,:cache: yes
- ,:END:
-#+end_example
-
-#+kindex: C-c C-x p
-#+vindex: org-babel-default-header-args
-
-Properties defined in this way override the properties set in
-~org-babel-default-header-args~. It is convenient to use the
-~org-set-property~ function bound to {{{kbd(C-c C-x p)}}} to set
-properties in Org mode documents.
-
-**** Code block specific header arguments
- :PROPERTIES:
- :DESCRIPTION: The most common way to set values
- :END:
-
-The most common way to assign values to header arguments is at the
-code block level. This can be done by listing a sequence of header
-arguments and their values as part of the ~#+BEGIN_SRC~ line.
-Properties set in this way override both the values of
-~org-babel-default-header-args~ and header arguments specified as
-properties. In the following example, the ~:results~ header argument
-is set to ~silent~, meaning the results of execution will not be
-inserted in the buffer, and the ~:exports~ header argument is set to
-~code~, meaning only the body of the code block will be preserved on
-export to HTML or LaTeX.
-
-#+begin_example
- #+NAME: factorial
- #+BEGIN_SRC haskell :results silent :exports code :var n=0
- fac 0 = 1
- fac n = n * fac (n-1)
- #+END_SRC
-#+end_example
-
-Similarly, it is possible to set header arguments for inline code blocks:
-
-#+begin_example
- src_haskell[:exports both]@{fac 5@}
-#+end_example
-
-Code block header arguments can span multiple lines using ~#+HEADER:~
-or ~#+HEADERS:~ lines preceding a code block or nested between the
-~#+NAME:~ line and the ~#+BEGIN_SRC~ line of a named code block.
-
-#+cindex: #+HEADER:
-#+cindex: #+HEADERS:
-
-This is an example of multi-line header arguments on an un-named code
-block:
-
-#+begin_example
- ,#+HEADERS: :var data1=1
- ,#+BEGIN_SRC emacs-lisp :var data2=2
- (message "data1:%S, data2:%S" data1 data2)
- ,#+END_SRC
-
- ,#+RESULTS:
- : data1:1, data2:2
-#+end_example
-
-This is an example of multi-line header arguments on a named code block:
-
-#+begin_example
- ,#+NAME: named-block
- ,#+HEADER: :var data=2
- ,#+BEGIN_SRC emacs-lisp
- (message "data:%S" data)
- ,#+END_SRC
-
- ,#+RESULTS: named-block
- : data:2
-#+end_example
-
-**** Header arguments in function calls
- :PROPERTIES:
- :DESCRIPTION: The most specific level
- :END:
-
-At the most specific level, header arguments for ``Library of Babel''
-or ~#+CALL:~ lines can be set as shown in the two examples below. For
-more information on the structure of ~#+CALL:~ lines see [[Evaluating
-code blocks]].
-
-The following example will apply the ~:exports results~ header
-argument to the evaluation of the ~#+CALL:~ line:
-
-#+begin_example
- ,#+CALL: factorial(n=5) :exports results
-#+end_example
-
-The following example will apply the ~:session special~ header
-argument to the evaluation of the ~factorial~ code block:
-
-#+begin_example
- ,#+CALL: factorial[:session special](n=5)
-#+end_example
-
-*** Specific header arguments
- :PROPERTIES:
- :DESCRIPTION: List of header arguments
- :END:
-Header arguments consist of an initial colon followed by the name of
-the argument in lowercase letters. Additional header arguments are
-defined on a language-specific basis, see [[Languages]].
-
-The following header arguments are defined:
-
-**** var
- :PROPERTIES:
- :DESCRIPTION: Pass arguments to code blocks
- :END:
-The ~:var~ header argument is used to pass arguments to code blocks.
-The specifics of how arguments are included in a code block vary by
-language; these are addressed in the language-specific documentation.
-However, the syntax used to specify arguments is the same across all
-languages. In every case, variables require a default value when they
-are declared.
-
-The values passed to arguments can either be literal values,
-references, or Emacs Lisp code (see [[Emacs Lisp evaluation of
-variables]]). References include anything in the Org mode file that
-takes a ~#+NAME:~, ~#+TBLNAME:~, or ~#+RESULTS:~ line. This includes
-tables, lists, ~#+BEGIN_EXAMPLE~ blocks, other code blocks, and the
-results of other code blocks.
-
-Argument values can be indexed in a manner similar to arrays (see
-[[Indexable variable values]]).
-
-The following syntax is used to pass arguments to code blocks using the
-~:var~ header argument:
-
-#+begin_example
- :var name=assign
-#+end_example
-
-The argument, ~assign~, can either be a literal value, such as a
-string {{{samp("string")}}} or a number {{{samp(9)}}}, or a reference
-to a table, a list, a literal example, another code block (with or
-without arguments), or the results of evaluating another code block.
-
-Here are examples of passing values by reference:
-
-#+attr_texinfo: :table-type table :indic @asis
-- a table named with either ~#+NAME:~ or ~#+TBLNAME:~ ::
-
- #+begin_example
- #+TBLNAME: example-table
- | 1 |
- | 2 |
- | 3 |
- | 4 |
-
- #+NAME: table-length
- #+BEGIN_SRC emacs-lisp :var table=example-table
- (length table)
- #+END_SRC
-
- #+RESULTS: table-length
- : 4
- #+end_example
-
-- a simple list named with ~#+NAME:~ ::
-
- #+begin_example
- #+NAME: example-list
- - simple
- - not
- - nested
- - list
-
- #+BEGIN_SRC emacs-lisp :var x=example-list
- (print x)
- #+END_SRC
-
- #+RESULTS:
- | simple | list |
- #+end_example
-
- Note that nesting is not carried through to the source code block.
-
-- a named code block without arguments, optionally followed by parentheses ::
-
- #+begin_example
- #+BEGIN_SRC emacs-lisp :var length=table-length()
- (* 2 length)
- #+END_SRC
-
- #+RESULTS:
- : 8
- #+end_example
-
-- a named code block with arguments ::
-
- #+begin_example
- #+NAME: double
- #+BEGIN_SRC emacs-lisp :var input=8
- (* 2 input)
- #+END_SRC
-
- #+RESULTS: double
- : 16
-
- #+NAME: squared
- #+BEGIN_SRC emacs-lisp :var input=double(input=1)
- (* input input)
- #+END_SRC
-
- #+RESULTS: squared
- : 4
- #+end_example
-
-- a literal example block ::
-
- #+begin_example
- ,#+NAME: literal-example
- ,#+BEGIN_EXAMPLE
- A literal example
- on two lines
- ,#+END_EXAMPLE
-
- ,#+NAME: read-literal-example
- ,#+BEGIN_SRC emacs-lisp :var x=literal-example
- (concatenate 'string x " for you.")
- ,#+END_SRC
-
- ,#+RESULTS: read-literal-example
- : A literal example
- : on two lines for you.
- #+end_example
-
-# ***** Alternate argument syntax
-<<Alternate argument syntax>>
-
-It is also possible to specify arguments in a potentially more natural
-way using the ~#+NAME:~ line of a code block. As in the following
-example, arguments can be packed inside of parentheses, separated by
-commas, following the source name.
-
-#+begin_example
- ,#+NAME: double(input=0, x=2)
- ,#+BEGIN_SRC emacs-lisp
- (* 2 (+ input x))
- ,#+END_SRC
-#+end_example
-
-# ***** Indexable variable values
-<<Indexable variable values>>
-
-It is possible to reference portions of variable values by
-/indexing/ into the variables. Indexes are 0 based with negative
-values counting back from the end. If an index is separated by commas
-then each subsequent section will index into the next deepest nesting
-or dimension of the value. Note that this indexing occurs /before/
-other table related header arguments like ~:hlines~, ~:colnames~, and
-~:rownames~ are applied. The following example assigns the last cell
-of the first row the table ~example-table~ to the variable ~data~:
-
-#+begin_example
- ,#+NAME: example-table
- | 1 | a |
- | 2 | b |
- | 3 | c |
- | 4 | d |
-
- ,#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
- data
- ,#+END_SRC
-
- ,#+RESULTS:
- : a
-#+end_example
-
-Ranges of variable values can be referenced using two integers
-separated by a ~:~, in which case the entire inclusive range is
-referenced. The following example assigns the middle three rows of
-~example-table~ to ~data~.
-
-#+begin_example
- #+NAME: example-table
- | 1 | a |
- | 2 | b |
- | 3 | c |
- | 4 | d |
- | 5 | 3 |
-
- #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
- data
- #+END_SRC
-
- #+RESULTS:
- | 2 | b |
- | 3 | c |
- | 4 | d |
-#+end_example
-
-Additionally, an empty index, or the single character ~*~, are both
-interpreted to mean the entire range and as such are equivalent to
-~0:-1~, as shown in the following example in which the entire first
-column is referenced:
-
-#+begin_example
- #+NAME: example-table
- | 1 | a |
- | 2 | b |
- | 3 | c |
- | 4 | d |
-
- #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
- data
- #+END_SRC
-
- #+RESULTS:
- | 1 | 2 | 3 | 4 |
-#+end_example
-
-It is possible to index into the results of code blocks as well as
-tables. Any number of dimensions can be indexed. Dimensions are
-separated from one another by commas, as shown in the following
-example:
-
-#+begin_example
- #+NAME: 3D
- #+BEGIN_SRC emacs-lisp
- '(((1 2 3) (4 5 6) (7 8 9))
- ((10 11 12) (13 14 15) (16 17 18))
- ((19 20 21) (22 23 24) (25 26 27)))
- #+END_SRC
-
- #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
- data
- #+END_SRC
-
- #+RESULTS:
- | 11 | 14 | 17 |
-#+end_example
-
-# ***** Emacs Lisp evaluation of variables
-<<Emacs Lisp evaluation of variables>>
-
-Emacs lisp code can be used to initialize variable values. When a
-variable value starts with ~(~, ~[~, ~'~ or ~`~ it will be evaluated
-as Emacs Lisp and the result of the evaluation will be assigned as the
-variable value. The following example demonstrates use of this
-evaluation to reliably pass the file-name of the Org mode buffer to a
-code block:[fn:150]
-
-#+begin_example
- #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
- wc -w $filename
- #+END_SRC
-#+end_example
-
-Note that values read from tables and lists will not be evaluated as
-Emacs Lisp, as shown in the following example, which contains a Lisp
-list as the sole table element:
-
-#+begin_example
- #+NAME: table
- | (a b c) |
-
- #+HEADERS: :var data=table[0,0]
- #+BEGIN_SRC perl
- $data
- #+END_SRC
-
- #+RESULTS:
- : (a b c)
-#+end_example
-
-**** results
- :PROPERTIES:
- :DESCRIPTION: Specify the type of results and how they will be collected and handled
- :END:
-There are three classes of ~:results~ header argument. Only one option
-per class may be supplied per code block.
-
-#+attr_texinfo: :table-type table :indic @asis
-- Collection ::
-
- These header arguments specify how the results should be collected
- from the code block.
-
-- Type ::
-
- These header arguments specify what type of result the code block will
- return---which has implications for how they will be inserted into the
- Org mode buffer.
-
-- Handling ::
-
- These header arguments specify how the results of evaluating the code
- block should be handled.
-
-# ***** Collection
-<<Collection>>
-
-The following ~:results~ options are mutually exclusive, and specify
-how the results should be collected from the code block.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~value~ ::
-
- This is the default. The result is the value of the last statement in
- the code block. This header argument places the evaluation in
- functional mode. Note that in some languages, e.g., Python, use of
- this result type requires that a ~return~ statement be included in the
- body of the source code block.
-
-- ~output~ ::
-
- The result is the collection of everything printed to STDOUT during
- the execution of the code block. This header argument places the
- evaluation in scripting mode.
-
-# ***** Type
-<<Type>>
-
-The following ~:results~ options are mutually exclusive and specify
-what type of results the code block will return. By default, results
-are inserted as either a table or scalar depending on their value.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~table~, ~vector~ ::
-
- The results should be interpreted as an Org mode table. If a single
- value is returned, it will be converted into a table with one row and
- one column. E.g., ~:results value table~.
-
-- ~scalar~, ~verbatim~ ::
-
- The results should be interpreted literally---they will not be
- converted into a table. The results will be inserted into the Org mode
- buffer as quoted text. E.g., ~:results value verbatim~.
-
-- ~list~ ::
-
- The results should be interpreted as an Org mode list. If a single
- scalar value is returned it will be converted into a list with only
- one element.
-
-- ~file~ ::
-
- The results will be interpreted as the path to a file, and will be
- inserted into the Org mode buffer as a file link. E.g., ~:results
- value file~.
-
-- ~raw~ ::
-
- The results are interpreted as raw Org mode code and are inserted
- directly into the buffer. If the results look like a table they will
- be aligned as such by Org mode. E.g., ~:results value raw~.
-
-- ~org~ ::
-
- The results are will be enclosed in a ~BEGIN_SRC org~ block. They are
- not comma-escaped by default but they will be if you hit
- {{{kbd(TAB)}}} in the block and/or if you export the file. E.g.,
- ~:results value org~.
-
-- ~html~ ::
-
- Results are assumed to be HTML and will be enclosed in a ~BEGIN_HTML~
- block. E.g., ~:results value html~.
-
-- ~latex~ ::
-
- Results assumed to be LaTeX and are enclosed in a ~BEGIN_LaTeX~
- block. E.g., ~:results value latex~.
-
-- ~code~ ::
-
- Result are assumed to be parsable code and are enclosed in a code
- block. E.g., ~:results value code~.
-
-- ~pp~ ::
-
- The result is converted to pretty-printed code and is enclosed in a
- code block. This option currently supports Emacs Lisp, Python, and
- Ruby. E.g., ~:results value pp~.
-
-- ~drawer~ ::
-
- The result is wrapped in a RESULTS drawer. This can be useful for
- inserting ~raw~ or ~org~ syntax results in such a way that their
- extent is known and they can be automatically removed or replaced.
-
-# ***** Handling
-<<Handling>>
-The following ~:results~ options indicate what happens with the
-results once they are collected.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~replace~ ::
-
- The default value. Any existing results will be removed, and the new
- results will be inserted into the Org mode buffer in their place.
- E.g., ~:results output replace~.
-
-- ~append~ ::
-
- If there are pre-existing results of the code block then the new
- results will be appended to the existing results. Otherwise the new
- results will be inserted as with ~replace~.
-
-- ~prepend~ ::
-
- If there are pre-existing results of the code block then the new
- results will be prepended to the existing results. Otherwise the new
- results will be inserted as with ~replace~.
-
-- ~silent~ ::
-
- The results will be echoed in the minibuffer but will not be inserted
- into the Org mode buffer. E.g., ~:results output silent~.
-
-**** file
- :PROPERTIES:
- :DESCRIPTION: Specify a path for file output
- :END:
-
-The header argument ~:file~ is used to specify an external file in
-which to save code block results. After code block evaluation an Org
-mode style ~[[file:]]~ link (see [[Link format]]) to the file will be inserted
-into the Org mode buffer. Some languages including R, gnuplot, dot,
-and ditaa provide special handling of the ~:file~ header argument,
-automatically wrapping the code block body in the boilerplate code
-required to save output to the specified file. This is often useful
-for saving graphical output of a code block to the specified file.
-
-The argument to ~:file~ should be either a string specifying the path
-to a file, or a list of two strings in which case the first element of
-the list should be the path to a file and the second a description for
-the link.
-
-**** file-desc
- :PROPERTIES:
- :DESCRIPTION: Specify a description for file results
- :END:
-
-The value of the ~:file-desc~ header argument is used to provide a
-description for file code block results which are inserted as Org mode
-links (see [[Link format]]). If the ~:file-desc~ header argument is given
-with no value the link path will be placed in both the ``link'' and
-the ``description'' portion of the Org mode link.
-
-**** dir
- :PROPERTIES:
- :DESCRIPTION: Specify the default (possibly remote) directory for code block execution
- :TITLE: ~:dir~ and remote execution
- :END:
-
-While the ~:file~ header argument can be used to specify the path to
-the output file, ~:dir~ specifies the default directory during code
-block execution. If it is absent, then the directory associated with
-the current buffer is used. In other words, supplying ~:dir path~
-temporarily has the same effect as changing the current directory with
-{{{kbd(M-x cd path)}}}, and then not supplying ~:dir~. Under the
-surface, ~:dir~ simply sets the value of the Emacs variable
-~default-directory~.
-
-When using ~:dir~, you should supply a relative path for file output
-(e.g., ~:file myfile.jpg~ or ~:file results/myfile.jpg~) in which
-case that path will be interpreted relative to the default directory.
-
-In other words, if you want your plot to go into a folder called
-{{{file(Work)}}} in your home directory, you could use a code block
-like the following example:
-
-#+begin_example
- #+BEGIN_SRC R :file myplot.png :dir ~/Work
- matplot(matrix(rnorm(100), 10), type="l")
- #+END_SRC
-#+end_example
-
-# ***** Remote execution
-<<Remote execution>>
-
-A directory on a remote machine can be specified using tramp file
-syntax, in which case the code will be evaluated on the remote
-machine. An example is:
-
-#+begin_example
- #+BEGIN_SRC R :file plot.png :dir /dand@yakuba.princeton.edu:
- plot(1:10, main=system("hostname", intern=TRUE))
- #+END_SRC
-#+end_example
-
-Text results will be returned to the local Org mode buffer as usual,
-and file output will be created on the remote machine with relative
-paths interpreted relative to the remote directory. An Org mode link
-to the remote file will be created.
-
-So, in the above example a plot will be created on the remote machine,
-and a link of the following form will be inserted in the org buffer:
-
-#+begin_example
- [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
-#+end_example
-
-Most of this functionality follows immediately from the fact that
-~:dir~ sets the value of the Emacs variable ~default-directory~,
-thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23
-may need to install tramp separately in order for these features to
-work correctly.
-
-# ***** Further points
-<<Further points>>
-Please be aware of these further points:
-
-- If ~:dir~ is used in conjunction with ~:session~, although it will
- determine the starting directory for a new session as expected, no
- attempt is currently made to alter the directory associated with an
- existing session.
-
-- ~:dir~ should typically not be used to create files during export
- with ~:exports results~ or ~:exports both~. The reason is that, in
- order to retain portability of exported material between machines,
- during export links inserted into the buffer will /not/ be expanded
- against ~default directory~. Therefore, if ~default-directory~ is
- altered using ~:dir~, it is probable that the file will be created
- in a location to which the link does not point.
-
-**** exports
- :PROPERTIES:
- :DESCRIPTION: Export code and/or results
- :END:
-The ~:exports~ header argument specifies what should be included in HTML
-or LaTeX exports of the Org mode file.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~code~ ::
-
- The default. The body of code is included into the exported file.
- E.g., ~:exports code~.
-
-- ~results~ ::
-
- The result of evaluating the code is included in the exported file.
- E.g., ~:exports results~.
-
-- ~both~ ::
-
- Both the code and results are included in the exported file. E.g.,
- ~:exports both~.
-
-- ~none~ ::
-
- Nothing is included in the exported file. E.g., ~:exports none~.
-
-**** tangle
- :PROPERTIES:
- :DESCRIPTION: Toggle tangling and specify file name
- :END:
-
-The ~:tangle~ header argument specifies whether or not the code
-block should be included in tangled extraction of source code files.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~tangle~ ::
-
- The code block is exported to a source code file named after the full
- path (including the directory) and file name (w/o extension) of the
- Org mode file. E.g., ~:tangle yes~.
-
-- ~no~ ::
-
- The default. The code block is not exported to a source code file.
- E.g., ~:tangle no~.
-
-- other ::
-
- Any other string passed to the ~:tangle~ header argument is
- interpreted as a path (directory and file name relative to the
- directory of the Org mode file) to which the block will be exported,
- e.g., ~:tangle path~.
-
-**** mkdirp
-:PROPERTIES:
-:DESCRIPTION: Toggle creation of parent directories of target files during tangling
-:END:
-
-The ~:mkdirp~ header argument can be used to create parent directories
-of tangled files when missing. This can be set to ~yes~ to enable
-directory creation or to ~no~ to inhibit directory creation.
-
-**** comments
-:PROPERTIES:
-:DESCRIPTION: Toggle insertion of comments in tangled code files
-:END:
-
-By default code blocks are tangled to source-code files without any
-insertion of comments beyond those which may already exist in the body
-of the code block. The ~:comments~ header argument can be set as
-follows to control the insertion of extra comments into the tangled
-code file.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~no~ ::
-
- The default. No extra comments are inserted during tangling.
-
-- ~link~ ::
-
- The code block is wrapped in comments which contain pointers back to
- the original Org file from which the code was tangled.
-
-- ~yes~ ::
-
- A synonym for ``link'' to maintain backwards compatibility.
-
-- ~org~ ::
-
- Include text from the Org mode file as a comment.
-
- The text is picked from the leading context of the tangled code and is
- limited by the nearest headline or source block as the case may be.
-
-- ~both~ ::
-
- Turns on both the ``link'' and ``org'' comment options.
-
-- ~noweb~ ::
-
- Turns on the ``link'' comment option, and additionally wraps expanded
- noweb references in the code block body in link comments.
-
-**** padline
-:PROPERTIES:
-:DESCRIPTION: Control insertion of padding lines in tangle code files
-:END:
-
-Control in insertion of padding lines around code block bodies in tangled
-code files. The default value is ~yes~ which results in insertion of
-newlines before and after each tangled code block. The following arguments
-are accepted:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~yes~ ::
-
- Insert newlines before and after each code block body in tangled code
- files.
-
-- ~no~ ::
-
- Do not insert any newline padding in tangled output.
-
-**** no-expand
-:PROPERTIES:
-:DESCRIPTION: Turn off variable assignment and noweb expansion during tangling
-:END:
-
-By default, code blocks are expanded with ~org-babel-expand-src-block~
-during tangling. This has the effect of assigning values to variables
-specified with ~:var~ (see [[var]]), and of replacing ``noweb'' references
-(see [[Noweb reference syntax]]) with their targets. The ~:no-expand~
-header argument can be used to turn off this behavior.
-
-**** session
-:PROPERTIES:
-:DESCRIPTION: Preserve state of code evaluation
-:END:
-
-The ~:session~ header argument starts a session for an interpreted
-language where state is preserved.
-
-By default, a session is not started.
-
-A string passed to the ~:session~ header argument will give the
-session a name. This makes it possible to run concurrent sessions for
-each interpreted language.
-
-**** noweb
-:PROPERTIES:
-:DESCRIPTION: Toggle expansion of noweb references
-:END:
-
-The ~:noweb~ header argument controls expansion of ``noweb'' syntax
-references (see [[Noweb reference syntax]]) when the code block is
-evaluated, tangled, or exported. The ~:noweb~ header argument can have
-one of the five values: ~no~, ~yes~, ~tangle~, ~no-export~, or
-~strip-export~.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~no~ ::
-
- The default. ``Noweb'' syntax references in the body of the code block
- will not be expanded before the code block is evaluated, tangled or
- exported.
-
-- ~yes~ ::
-
- ``Noweb'' syntax references in the body of the code block will be
- expanded before the code block is evaluated, tangled or exported.
-
-- ~tangle~ ::
-
- ``Noweb'' syntax references in the body of the code block will be
- expanded before the code block is tangled. However, ``noweb'' syntax
- references will not be expanded when the code block is evaluated or
- exported.
-
-- ~no-export~ ::
-
- ``Noweb'' syntax references in the body of the code block will be
- expanded before the block is evaluated or tangled. However, ``noweb''
- syntax references will not be expanded when the code block is
- exported.
-
-- ~strip-export~ ::
-
- ``Noweb'' syntax references in the body of the code block will be
- expanded before the block is evaluated or tangled. However, ``noweb''
- syntax references will not be removed when the code block is exported.
-
-- ~eval~ ::
-
- ``Noweb'' syntax references in the body of the code block will only be
- expanded before the block is evaluated.
-
-# ***** Noweb prefix lines
-<<Noweb prefix lines>>
-
-Noweb insertions are placed behind the line prefix of the
-~<<reference>>~. Because the ~<<example>>~ noweb reference appears
-behind the SQL comment syntax in the following example, each line of
-the expanded noweb reference will be commented.
-
-This code block:
-
-#+begin_example
- -- <<example>>
-#+end_example
-
-
-expands to:
-
-#+begin_example
- -- this is the
- -- multi-line body of example
-#+end_example
-
-Note that noweb replacement text that does not contain any newlines
-will not be inserted behind the line prefix, so it is always possible
-to use inline noweb references.
-
-**** noweb-ref
-:PROPERTIES:
-:DESCRIPTION: Specify block's noweb reference resolution target
-:END:
-
-When expanding ``noweb'' style references the bodies of all code block
-with /either/ a block name matching the reference name /or/ a
-~:noweb-ref~ header argument matching the reference name will be
-concatenated together to form the replacement text.
-
-By setting this header argument at the sub-tree or file level, simple code
-block concatenation may be achieved. For example, when tangling the
-following Org mode file, the bodies of code blocks will be concatenated into
-the resulting pure code file.[fn:151]
-
-#+begin_example
- #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
- <<fullest-disk>>
- #+END_SRC
- ,* the mount point of the fullest disk
- :PROPERTIES:
- :noweb-ref: fullest-disk
- :END:
-
- ,** query all mounted disks
- #+BEGIN_SRC sh
- df \
- #+END_SRC
-
- ,** strip the header row
- #+BEGIN_SRC sh
- |sed '1d' \
- #+END_SRC
-
- ,** sort by the percent full
- #+BEGIN_SRC sh
- |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
- #+END_SRC
-
- ,** extract the mount point
- #+BEGIN_SRC sh
- |awk '@{print $2@}'
- #+END_SRC
-#+end_example
-
-The ~:noweb-sep~ (see [[noweb-sep]]) header argument holds the string used
-to separate accumulate noweb references like those above. By default a
-newline is used.
-
-**** noweb-sep
-:PROPERTIES:
-:DESCRIPTION: String used to separate noweb references
-:END:
-
-The ~:noweb-sep~ header argument holds the string used to separate
-accumulated noweb references (see [[noweb-ref]]). By default a newline is
-used.
-
-**** cache
-:PROPERTIES:
-:DESCRIPTION: Avoid re-evaluating unchanged code blocks
-:END:
-
-The ~:cache~ header argument controls the use of in-buffer caching of
-the results of evaluating code blocks. It can be used to avoid
-re-evaluating unchanged code blocks. Note that the ~:cache~ header
-argument will not attempt to cache results when the ~:session~ header
-argument is used, because the results of the code block execution may
-be stored in the session outside of the Org mode buffer. The ~:cache~
-header argument can have one of two values: ~yes~ or ~no~.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~no~ ::
-
- The default. No caching takes place, and the code block will be
- evaluated every time it is called.
-
-- ~yes~ ::
-
- Every time the code block is run a SHA1 hash of the code and arguments
- passed to the block will be generated. This hash is packed into the
- ~#+RESULTS:~ line and will be checked on subsequent executions of the
- code block. If the code block has not changed since the last time it
- was evaluated, it will not be re-evaluated.
-
-
-Code block caches notice if the value of a variable argument
-to the code block has changed. If this is the case, the cache is
-invalidated and the code block is re-run. In the following example,
-~caller~ will not be re-run unless the results of ~random~ have
-changed since it was last run.
-
-#+begin_example
- #+NAME: random
- #+BEGIN_SRC R :cache yes
- runif(1)
- #+END_SRC
-
- #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
- 0.4659510825295
-
- #+NAME: caller
- #+BEGIN_SRC emacs-lisp :var x=random :cache yes
- x
- #+END_SRC
-
- #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
- 0.254227238707244
-#+end_example
-
-**** sep
-:PROPERTIES:
-:DESCRIPTION: Delimiter for writing tabular results outside Org
-:END:
-#+kindex: C-c C-o
-
-The ~:sep~ header argument can be used to control the delimiter used
-when writing tabular results out to files external to Org mode. This
-is used either when opening tabular results of a code block by calling
-the ~org-open-at-point~ function bound to {{{kbd(C-c C-o)}}} on the
-code block, or when writing code block results to an external file
-(see [[file]]) header argument.
-
-By default, when ~:sep~ is not specified output tables are tab
-delimited.
-
-**** hlines
-:PROPERTIES:
-:DESCRIPTION: Handle horizontal lines in tables
-:END:
-
-Tables are frequently represented with one or more horizontal lines,
-or hlines. The ~:hlines~ argument to a code block accepts the values
-~yes~ or ~no~, with a default value of ~no~.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~no~ ::
-
- Strips horizontal lines from the input table. In most languages this
- is the desired effect because an ~hline~ symbol is interpreted as an
- unbound variable and raises an error. Setting ~:hlines no~ or relying
- on the default value yields the following results.
-
- #+begin_example
- #+TBLNAME: many-cols
- | a | b | c |
- |---+---+---|
- | d | e | f |
- |---+---+---|
- | g | h | i |
-
- #+NAME: echo-table
- #+BEGIN_SRC python :var tab=many-cols
- return tab
- #+END_SRC
-
- #+RESULTS: echo-table
- | a | b | c |
- | d | e | f |
- | g | h | i |
- #+end_example
-
-- ~yes~ ::
-
- Leaves hlines in the table. Setting ~:hlines yes~ has this effect.
-
- #+begin_example
- #+TBLNAME: many-cols
- | a | b | c |
- |---+---+---|
- | d | e | f |
- |---+---+---|
- | g | h | i |
-
- #+NAME: echo-table
- #+BEGIN_SRC python :var tab=many-cols :hlines yes
- return tab
- #+END_SRC
-
- #+RESULTS: echo-table
- | a | b | c |
- |---+---+---|
- | d | e | f |
- |---+---+---|
- | g | h | i |
- #+end_example
-
-**** colnames
-:PROPERTIES:
-:DESCRIPTION: Handle column names in tables
-:END:
-
-The ~:colnames~ header argument accepts the values ~yes~, ~no~, or
-~nil~ for unassigned. The default value is ~nil~. Note that the
-behavior of the ~:colnames~ header argument may differ across
-languages. For example Emacs Lisp code blocks ignore the ~:colnames~
-header argument entirely given the ease with which tables with column
-names may be handled directly in Emacs Lisp.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~nil~ ::
-
- If an input table looks like it has column names (because its second
- row is an hline), then the column names will be removed from the table
- before processing, then reapplied to the results.
-
- #+begin_example
- #+TBLNAME: less-cols
- | a |
- |---|
- | b |
- | c |
-
- #+NAME: echo-table-again
- #+BEGIN_SRC python :var tab=less-cols
- return [[val + '*' for val in row] for row in tab]
- #+END_SRC
-
- #+RESULTS: echo-table-again
- | a |
- |----|
- | b* |
- | c* |
- #+end_example
-
- Please note that column names are not removed before the table is
- indexed using variable indexing. See [[Indexable variable values]].
-
-- ~no~ ::
-
- No column name pre-processing takes place
-
-- ~yes~ ::
-
- Column names are removed and reapplied as with ~nil~ even if the table
- does not ``look like'' it has column names (i.e., the second row is
- not an hline).
-
-**** rownames
-:PROPERTIES:
-:DESCRIPTION: Handle row names in tables
-:END:
-
-The ~:rownames~ header argument can take on the values ~yes~
-or ~no~, with a default value of ~no~.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~no~ ::
-
- No row name pre-processing will take place.
-
-- ~yes~ ::
-
- The first column of the table is removed from the table before
- processing, and is then reapplied to the results.
-
- #+begin_example
- #+TBLNAME: with-rownames
- | one | 1 | 2 | 3 | 4 | 5 |
- | two | 6 | 7 | 8 | 9 | 10 |
-
- #+NAME: echo-table-once-again
- #+BEGIN_SRC python :var tab=with-rownames :rownames yes
- return [[val + 10 for val in row] for row in tab]
- #+END_SRC
-
- #+RESULTS: echo-table-once-again
- | one | 11 | 12 | 13 | 14 | 15 |
- | two | 16 | 17 | 18 | 19 | 20 |
- #+end_example
-
- Please note that row names are not removed before the table is indexed
- using variable indexing. See [[Indexable variable values]].
-
-**** shebang
-:PROPERTIES:
-:DESCRIPTION: Make tangles files executable
-:END:
-
-Setting the ~:shebang~ header argument to a string value (e.g.,
-{{{samp(:shebang "#!/bin/bash")}}}) causes the string to be inserted as the
-first line of any tangled file holding the code block, and the file
-permissions of the tangled file are set to make it executable.
-
-**** eval
-:PROPERTIES:
-:DESCRIPTION: Limit evaluation of specific code blocks
-:END:
-
-The ~:eval~ header argument can be used to limit the evaluation of
-specific code blocks. The ~:eval~ header argument can be useful for
-protecting against the evaluation of dangerous code blocks or to
-ensure that evaluation will require a query regardless of the value of
-the ~org-confirm-babel-evaluate~ variable. The possible values of
-~:eval~ and their effects are shown below.
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~never~ or ~no~ ::
-
- The code block will not be evaluated under any circumstances.
-
-- ~query~ ::
-
- Evaluation of the code block will require an affirmative answer to a
- query.
-
-- ~never-export~ or ~no-export~ ::
-
- The code block will not be evaluated during export but may still be
- called interactively.
-
-- ~query-export~ ::
-
- Evaluation of the code block during export will require an affirmative
- answer to a query.
-
-
-If this header argument is not set then evaluation is determined by the value
-of the ~org-confirm-babel-evaluate~ variable (see [[Code evaluation
-security]]).
-
-**** wrap
-:PROPERTIES:
-:DESCRIPTION: Mark source block evaluation results
-:END:
-
-The ~:wrap~ header argument is used to mark the results of source
-block evaluation. The header argument can be passed a string that will
-be appended to ~#+BEGIN_~ and ~#+END_~, which will then be used to
-wrap the results. If no string is specified then the results will be
-wrapped in a ~#+BEGIN/END_RESULTS~ block.
-
-** Results of evaluation
- :PROPERTIES:
- :DESCRIPTION: How evaluation results are handled
- :END:
-#+cindex: code block, results of evaluation
-#+cindex: source code, results of evaluation
-
-The way in which results are handled depends on whether a session is
-invoked, as well as on whether ~:results value~ or ~:results output~
-is used. The following table shows the table possibilities. For a full
-listing of the possible results header arguments, see [[results]].
-
-| | *Non-session* | *Session* |
-|-------------------+--------------------------+-------------------------------------|
-| ~:results value~ | value of last expression | value of last expression |
-| ~:results output~ | contents of STDOUT | concatenation of interpreter output |
-
-
-Please note that with ~:results value~, the result in both ~:session~
-and non-session is returned to Org mode as a table (a one- or
-two-dimensional vector of strings or numbers) when appropriate.
-
-*** Non-session
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:results value~ ::
-
- This is the default. Internally, the value is obtained by wrapping the
- code in a function definition in the external language, and evaluating
- that function. Therefore, code should be written as if it were the
- body of such a function. In particular, note that Python does not
- automatically return a value from a function unless a ~return~
- statement is present, and so a {{{samp(return)}}} statement will
- usually be required in Python.
-
- This is the only one of the four evaluation contexts in which the code
- is automatically wrapped in a function definition.
-
-- ~:results output~ ::
-
- The code is passed to the interpreter as an external process, and the
- contents of the standard output stream are returned as text.[fn:152]
-
-*** Session
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:results value~ ::
-
- The code is passed to an interpreter running as an interactive Emacs
- inferior process. Only languages which provide tools for interactive
- evaluation of code have session support, so some language (e.g., C and
- ditaa) do not support the ~:session~ header argument, and in other
- languages (e.g., Python and Haskell) which have limitations on the
- code which may be entered into interactive sessions, those limitations
- apply to the code in code blocks using the ~:session~ header argument
- as well.
-
- Unless the ~:results output~ option is supplied (see below) the result
- returned is the result of the last evaluation performed by the
- interpreter.[fn:153]
-
-- ~:results output~ ::
-
- The code is passed to the interpreter running as an interactive Emacs
- inferior process. The result returned is the concatenation of the
- sequence of (text) output from the interactive interpreter. Notice
- that this is not necessarily the same as what would be sent to
- ~STDOUT~ if the same code were passed to a non-interactive interpreter
- running as an external process. Compare the following two
- examples:
-
- #+begin_example
- #+BEGIN_SRC python :results output
- print "hello"
- 2
- print "bye"
- #+END_SRC
-
- #+RESULTS:
- : hello
- : bye
- #+end_example
-
- In non-session mode, the `2' is not printed and does not appear.
-
- #+begin_example
- #+BEGIN_SRC python :results output :session
- print "hello"
- 2
- print "bye"
- #+END_SRC
-
- #+RESULTS:
- : hello
- : 2
- : bye
- #+end_example
-
- But in ~:session~ mode, the interactive interpreter receives input `2'
- and prints out its value, `2'. (Indeed, the other print statements are
- unnecessary here).
-
-** Noweb reference syntax
- :PROPERTIES:
- :DESCRIPTION: Literate programming in Org mode
- :END:
-#+cindex: code block, noweb reference
-#+cindex: syntax, noweb
-#+cindex: source code, noweb reference
-
-The ``noweb'' (see [[http://www.cs.tufts.edu/~nr/noweb/]]) Literate
-Programming system allows named blocks of code to be referenced using
-the familiar Noweb syntax:
-
-#+begin_example
- <<code-block-name>>
-#+end_example
-
-When a code block is tangled or evaluated, whether or not ``noweb''
-references are expanded depends upon the value of the ~:noweb~ header
-argument. If ~:noweb yes~, then a Noweb reference is expanded before
-evaluation. If ~:noweb no~, the default, then the reference is not
-expanded before evaluation. See the [[noweb-ref]] header argument for a
-more flexible way to resolve noweb references.
-
-It is possible to include the /results/ of a code block rather than
-the body. This is done by appending parenthesis to the code block
-name, which may optionally contain arguments to the code block as
-shown below.
-
-#+begin_example
- <<code-block-name(optional arguments)>>
-#+end_example
-
-Note that the default value, ~:noweb no~, was chosen to ensure that
-correct code is not broken in a language, such as Ruby, where
-~<<arg>>~ is a syntactically valid construct. If ~<<arg>>~ is not
-syntactically valid in languages that you use, then please consider
-setting the default value.
-
-If noweb tangling is slow in large Org mode files, consider
-setting the ~*org-babel-use-quick-and-dirty-noweb-expansion*~ variable
-to true. This will result in faster noweb reference resolution at the
-expense of not correctly resolving inherited values of the
-~:noweb-ref~ header argument.
-
-** Key bindings and useful functions
- :PROPERTIES:
- :DESCRIPTION: Work quickly with code blocks
- :END:
-#+cindex: code block, key bindings
-
-Many common Org mode key sequences are re-bound depending on
-the context.
-
-Within a code block, the following key bindings
-are active:
-#+kindex: C-c C-c
-#+kindex: C-c C-o
-#+kindex: C-up
-#+kindex: M-down
-
-#+attr_texinfo: :columns 0.2 0.55
-| Key binding | Function |
-|-----------------------+-----------------------------------|
-| {{{kbd(C-c C-c)}}} | ~org-babel-execute-src-block~ |
-| {{{kbd(C-c C-o)}}} | ~org-babel-open-src-block-result~ |
-| {{{kbdkey(C-,up)}}} | ~org-babel-load-in-session~ |
-| {{{kbdkey(M-,down)}}} | ~org-babel-pop-to-session~ |
-
-
-In an Org mode buffer, the following key bindings are active:
-
-#+kindex: C-c C-v p
-#+kindex: C-c C-v C-p
-#+kindex: C-c C-v n
-#+kindex: C-c C-v C-n
-#+kindex: C-c C-v e
-#+kindex: C-c C-v C-e
-#+kindex: C-c C-v o
-#+kindex: C-c C-v C-o
-#+kindex: C-c C-v v
-#+kindex: C-c C-v C-v
-#+kindex: C-c C-v u
-#+kindex: C-c C-v C-u
-#+kindex: C-c C-v g
-#+kindex: C-c C-v C-g
-#+kindex: C-c C-v r
-#+kindex: C-c C-v C-r
-#+kindex: C-c C-v b
-#+kindex: C-c C-v C-b
-#+kindex: C-c C-v s
-#+kindex: C-c C-v C-s
-#+kindex: C-c C-v d
-#+kindex: C-c C-v C-d
-#+kindex: C-c C-v t
-#+kindex: C-c C-v C-t
-#+kindex: C-c C-v f
-#+kindex: C-c C-v C-f
-#+kindex: C-c C-v c
-#+kindex: C-c C-v C-c
-#+kindex: C-c C-v j
-#+kindex: C-c C-v C-j
-#+kindex: C-c C-v l
-#+kindex: C-c C-v C-l
-#+kindex: C-c C-v i
-#+kindex: C-c C-v C-i
-#+kindex: C-c C-v I
-#+kindex: C-c C-v C-I
-#+kindex: C-c C-v z
-#+kindex: C-c C-v C-z
-#+kindex: C-c C-v a
-#+kindex: C-c C-v C-a
-#+kindex: C-c C-v h
-#+kindex: C-c C-v C-h
-#+kindex: C-c C-v x
-#+kindex: C-c C-v C-x
-
-#+attr_texinfo: :columns 0.4 0.6
-| Key binding | Function |
-|------------------------------------------------+--------------------------------------------|
-| {{{kbd(C-c C-v p)}}} or {{{kbd(C-c C-v C-p)}}} | ~org-babel-previous-src-block~ |
-| {{{kbd(C-c C-v n)}}} or {{{kbd(C-c C-v C-n)}}} | ~org-babel-next-src-block~ |
-| {{{kbd(C-c C-v e)}}} or {{{kbd(C-c C-v C-e)}}} | ~org-babel-execute-maybe~ |
-| {{{kbd(C-c C-v o)}}} or {{{kbd(C-c C-v C-o)}}} | ~org-babel-open-src-block-result~ |
-| {{{kbd(C-c C-v v)}}} or {{{kbd(C-c C-v C-v)}}} | ~org-babel-expand-src-block~ |
-| {{{kbd(C-c C-v u)}}} or {{{kbd(C-c C-v C-u)}}} | ~org-babel-goto-src-block-head~ |
-| {{{kbd(C-c C-v g)}}} or {{{kbd(C-c C-v C-g)}}} | ~org-babel-goto-named-src-block~ |
-| {{{kbd(C-c C-v r)}}} or {{{kbd(C-c C-v C-r)}}} | ~org-babel-goto-named-result~ |
-| {{{kbd(C-c C-v b)}}} or {{{kbd(C-c C-v C-b)}}} | ~org-babel-execute-buffer~ |
-| {{{kbd(C-c C-v s)}}} or {{{kbd(C-c C-v C-s)}}} | ~org-babel-execute-subtree~ |
-| {{{kbd(C-c C-v d)}}} or {{{kbd(C-c C-v C-d)}}} | ~org-babel-demarcate-block~ |
-| {{{kbd(C-c C-v t)}}} or {{{kbd(C-c C-v C-t)}}} | ~org-babel-tangle~ |
-| {{{kbd(C-c C-v f)}}} or {{{kbd(C-c C-v C-f)}}} | ~org-babel-tangle-file~ |
-| {{{kbd(C-c C-v c)}}} or {{{kbd(C-c C-v C-c)}}} | ~org-babel-check-src-block~ |
-| {{{kbd(C-c C-v j)}}} or {{{kbd(C-c C-v C-j)}}} | ~org-babel-insert-header-arg~ |
-| {{{kbd(C-c C-v l)}}} or {{{kbd(C-c C-v C-l)}}} | ~org-babel-load-in-session~ |
-| {{{kbd(C-c C-v i)}}} or {{{kbd(C-c C-v C-i)}}} | ~org-babel-lob-ingest~ |
-| {{{kbd(C-c C-v I)}}} or {{{kbd(C-c C-v C-I)}}} | ~org-babel-view-src-block-info~ |
-| {{{kbd(C-c C-v z)}}} or {{{kbd(C-c C-v C-z)}}} | ~org-babel-switch-to-session-with-code~ |
-| {{{kbd(C-c C-v a)}}} or {{{kbd(C-c C-v C-a)}}} | ~org-babel-sha1-hash~ |
-| {{{kbd(C-c C-v h)}}} or {{{kbd(C-c C-v C-h)}}} | ~org-babel-describe-bindings~ |
-| {{{kbd(C-c C-v x)}}} or {{{kbd(C-c C-v C-x)}}} | ~org-babel-do-key-sequence-in-edit-buffer~ |
-
-
-# When possible these keybindings were extended to work when the control key is
-# kept pressed, resulting in the following additional keybindings.
-
-# @multitable @columnfractions 0.25 0.75
-# - {{{kbd(C-c C-v C-a)}}} @tab ~org-babel-sha1-hash~
-# - {{{kbd(C-c C-v C-b)}}} @tab ~org-babel-execute-buffer~
-# - {{{kbd(C-c C-v C-f)}}} @tab ~org-babel-tangle-file~
-# - {{{kbd(C-c C-v C-l)}}} @tab ~org-babel-lob-ingest~
-# - {{{kbd(C-c C-v C-p)}}} @tab ~org-babel-expand-src-block~
-# - {{{kbd(C-c C-v C-s)}}} @tab ~org-babel-execute-subtree~
-# - {{{kbd(C-c C-v C-t)}}} @tab ~org-babel-tangle~
-# - {{{kbd(C-c C-v C-z)}}} @tab ~org-babel-switch-to-session~
-# @end multitable
-
-** Batch execution
- :PROPERTIES:
- :DESCRIPTION: Call functions from the command line
- :END:
-#+cindex: code block, batch execution
-#+cindex: source code, batch execution
-
-It is possible to call functions from the command line. This shell
-script calls ~org-babel-tangle~ on every one of its arguments.
-
-Be sure to adjust the paths to fit your system.
-
-#+begin_example
- #!/bin/sh
- # -*- mode: shell-script -*-
- #
- # tangle files with org-mode
- #
- DIR=`pwd`
- FILES=""
-
- # wrap each argument in the code required to call tangle on it
- for i in $@; do
- FILES="$FILES \"$i\""
- done
-
- emacs -Q --batch \
- --eval "(progn
- (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
- (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
- (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
- (mapc (lambda (file)
- (find-file (expand-file-name file \"$DIR\"))
- (org-babel-tangle)
- (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
-#+end_example
-
-* FIXME Miscellaneous
- :PROPERTIES:
- :DESCRIPTION: All the rest which did not fit elsewhere
- :END:
-
-** FIXME Completion
- :PROPERTIES:
- :DESCRIPTION: M-TAB knows what you need
- :END:
-#+cindex: completion, of @TeX{} symbols
-#+cindex: completion, of TODO keywords
-#+cindex: completion, of dictionary words
-#+cindex: completion, of option keywords
-#+cindex: completion, of tags
-#+cindex: completion, of property keys
-#+cindex: completion, of link abbreviations
-#+cindex: @TeX{} symbol completion
-#+cindex: TODO keywords completion
-#+cindex: dictionary word completion
-#+cindex: option keyword completion
-#+cindex: tag completion
-#+cindex: link abbreviations, completion of
-
-Emacs would not be Emacs without completion, and Org mode uses it
-whenever it makes sense. If you prefer an iswitchb- or ido-like
-interface for some of the completion prompts, you can specify your
-preference by setting at most one of the variables
-~org-completion-use-iswitchb~ or ~org-completion-use-ido~.
-
-Org supports in-buffer completion. This type of completion does not
-make use of the minibuffer. You simply type a few letters into the
-buffer and use the {{{key(TAB)}}} key to complete text right there.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbdkey(M-,TAB)}}} ::
- #+kindex: M-@key{TAB}
-
- Complete word at point.
-
- - At the beginning of a headline ::
-
- Complete TODO keywords.
-
- - After {{{kbd(XXX)}}} ::
- # Should be \
- Complete TeX symbols supported by the exporter.
-
- - After {{{samp(*)}}} ::
-
- Complete headlines in the current buffer so that they can be used in
- search links like:
-
- #+begin_example
- [[*find this headline]]
- #+end_example
-
- - After {{{samp(:)}}} in a headline ::
-
- Complete tags. The list of tags is taken from the variable
- ~org-tag-alist~ (possibly set through the {{{samp(#+TAGS)}}} in-buffer
- option, see [[Setting tags]]), or it is created dynamically from all tags
- used in the current buffer.
-
- - After {{{samp(:)}}} and not in a headline ::
-
- Complete property keys. The list of keys is constructed dynamically
- from all keys used in the current buffer.
-
- - After {{{samp([)}}} ::
-
- Complete link abbreviations (see [[Link abbreviations]]).
-
- - After {{{samp(#+)}}} ::
-
- Complete the special keywords like {{{samp(TYP_TODO)}}} or
- {{{samp(OPTIONS)}}} which set file-specific options for Org mode. When
- the option keyword is already complete, pressing {{{kbdkey(M-,TAB)}}}
- again will insert example settings for this keyword.
-
- - In the line after {{{samp(#+STARTUP: )}}} ::
-
- Complete startup keywords, i.e., valid keys for this line.
-
- - Elsewhere ::
-
- Complete dictionary words using Ispell.
-
-** Easy templates
- :PROPERTIES:
- :DESCRIPTION: Quick insertion of structural elements
- :END:
-#+cindex: template insertion
-#+cindex: insertion, of templates
-
-Org mode supports insertion of empty structural elements (like
-~#+BEGIN_SRC~ and ~#+END_SRC~ pairs) with just a few key strokes. This
-is achieved through a native template expansion mechanism. Note that
-Emacs has several other template mechanisms which could be used in a
-similar way, for example {{{file(yasnippet)}}}.
-
-To insert a structural element, type a {{{kbd(<)}}}, followed by a
-template selector and {{{kbdkey(,TAB)}}}. Completion takes effect only
-when the above keystrokes are typed on a line by itself.
-
-The following template selectors are currently supported:
-#+kindex: s
-#+kindex: e
-#+kindex: q
-#+kindex: v
-#+kindex: c
-#+kindex: l
-#+kindex: L
-#+kindex: h
-#+kindex: H
-#+kindex: a
-#+kindex: A
-#+kindex: i
-#+kindex: I
-
-#+attr_texinfo: :columns 0.2 0.7
-| Selector | Template |
-|--------------+---------------------------------------|
-| {{{kbd(a)}}} | ~#+BEGIN_ASCII~ ...~ #+END_ASCII~ |
-| {{{kbd(A)}}} | ~#+ASCII:~ |
-| {{{kbd(c)}}} | ~#+BEGIN_CENTER~ ... ~#+END_CENTER~ |
-| {{{kbd(e)}}} | ~#+BEGIN_EXAMPLE~ ... ~#+END_EXAMPLE~ |
-| {{{kbd(h)}}} | ~#+BEGIN_HTML~ ... ~#+END_HTML~ |
-| {{{kbd(H)}}} | ~#+HTML:~ |
-| {{{kbd(i)}}} | ~#+INDEX:~ |
-| {{{kbd(I)}}} | ~#+INCLUDE:~ |
-| {{{kbd(l)}}} | ~#+BEGIN_LaTeX~ ... ~#+END_LaTeX~ |
-| {{{kbd(L)}}} | ~#+LaTeX:~ |
-| {{{kbd(q)}}} | ~#+BEGIN_QUOTE~ ... ~#+END_QUOTE~ |
-| {{{kbd(s)}}} | ~#+BEGIN_SRC~ ... ~#+END_SRC~ |
-| {{{kbd(v)}}} | ~#+BEGIN_VERSE~ ... ~#+END_VERSE~ |
-
-For example, on an empty line, typing "<e" and then pressing TAB, will expand
-into a complete EXAMPLE template.
-
-You can install additional templates by customizing the variable
-~org-structure-template-alist~. See the docstring of the variable for
-additional details.
-
-** Speed keys
- :PROPERTIES:
- :DESCRIPTION: Electric commands at the beginning of a headline
- :END:
-#+cindex: speed keys
-#+vindex: org-use-speed-commands
-#+vindex: org-speed-commands-user
-
-Single keys can be made to execute commands when the cursor is at the
-beginning of a headline, i.e., before the first star. Configure the
-variable ~org-use-speed-commands~ to activate this feature. There is a
-pre-defined list of commands, and you can add more such commands using
-the variable ~org-speed-commands-user~. Speed keys do not only speed
-up navigation and other commands, but they also provide an alternative
-way to execute commands bound to keys that are not or not easily
-available on a TTY, or on a small mobile device with a limited
-keyboard.
-
-To see which commands are available, activate the feature and press
-{{{kbd(?)}}} with the cursor at the beginning of a headline.
-
-** Code evaluation security
- :PROPERTIES:
- :DESCRIPTION: Org mode files evaluate in-line code
- :TITLE: Code evaluation and security issues
- :END:
-
-Org provides tools to work with the code snippets, including
-evaluating them.
-
-Running code on your machine always comes with a security risk. Badly
-written or malicious code can be executed on purpose or by accident.
-Org has default settings that will only evaluate source code if you
-give explicit permission to do so, and as a casual user of these
-features you should leave these precautions intact.
-
-For people who regularly work with source code, the confirmation
-prompts can become annoying, and you might want to turn them off. This
-can be done, but you must be aware of the risks that are involved.
-
-Code evaluation can happen under the following circumstances:
-
-#+attr_texinfo: :table-type table :indic @asis
-- Source code blocks ::
-
- Source code blocks can be evaluated during export, or when pressing
- {{{kbd(C-c C-c)}}} in the block. The most important thing to realize
- here is that Org mode files which contain code snippets are, in a
- certain sense, like executable files. So you should accept them and
- load them into Emacs only from trusted sources---just like you would
- do with a program you install on your computer.
-
- Make sure you know what you are doing before customizing the variables
- that take off the default security brakes.
-
- - ~org-confirm-babel-evaluate~ ::
-
- When ~t~ (the default), the user is asked before every code block
- evaluation. When ~nil~, the user is not asked. When set to a function,
- it is called with two arguments (language and body of the code block)
- and should return ~t~ to ask and ~nil~ not to ask.
-
- For example, here is how to execute "ditaa" code (which is considered
- safe) without asking:
-
- #+header: :eval no
- #+header: :exports code
- #+begin_src emacs-lisp
- (defun my-org-confirm-babel-evaluate (lang body)
- (not (string= lang "ditaa"))) ; don't ask for ditaa
- (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
- #+end_src
-
-- Following ~shell~ and ~elisp~ links ::
-
- Org has two link types that can directly evaluate code (see [[External
- links]]). These links can be problematic because the code to be
- evaluated is not visible.
-
- - ~org-confirm-shell-link-function~ ::
-
- Function to queries user about shell link execution.
-
- - ~org-confirm-elisp-link-function~ ::
-
- Function to query user for Emacs Lisp link execution.
-
-- Formulas in tables ::
-
- Formulas in tables (see [[The spreadsheet]]) are code that is evaluated
- either by the /calc/ interpreter, or by the /Emacs Lisp/ interpreter.
-
-** Customization
- :PROPERTIES:
- :DESCRIPTION: Adapting Org to your taste
- :END:
-#+cindex: customization
-#+cindex: options, for customization
-#+cindex: variables, for customization
-
-There are more than 500 variables that can be used to customize Org.
-For the sake of compactness of the manual, I am not describing the
-variables here. A structured overview of customization variables is
-available with {{{kbd(M-x org-customize)}}}. Or select ~Browse Org
-Group~ from the ~Org->Customization~ menu. Many settings can also be
-activated on a per-file basis, by putting special lines into the
-buffer (see [[In-buffer settings]]).
-
-** In-buffer settings
- :PROPERTIES:
- :DESCRIPTION: Overview of the #+KEYWORDS
- :TITLE: Summary of in-buffer settings
- :END:
-#+cindex: in-buffer settings
-#+cindex: special keywords
-
-Org mode uses special lines in the buffer to define settings on a
-per-file basis. These lines start with a {{{samp(#+)}}} followed by a
-keyword, a colon, and then individual words defining a setting.
-Several setting words can be in the same line, but you can also have
-multiple lines for the keyword. While these settings are described
-throughout the manual, here is a summary. After changing any of those
-lines in the buffer, press {{{kbd(C-c C-c)}}} with the cursor still in
-the line to activate the changes immediately. Otherwise they become
-effective only when the file is visited again in a new Emacs session.
-
-#+vindex: org-archive-location
-#+attr_texinfo: :table-type table :indic @asis
-- {{{kbd(#+ARCHIVE: %s_done)}}} ::
-
- This line sets the archive location for the agenda file. It applies to
- all subsequent lines, until the next {{{samp(#+ARCHIVE)}}} line or the
- end of the file. The first such line also applies to any entries
- before it. The corresponding variable is ~org-archive-location~.
-
-- {{{kbd(#+CATEGORY:)}}} ::
-
- This line sets the category for the agenda file. The category applies
- to all subsequent lines, until the next {{{samp(#+CATEGORY)}}} line or
- the end of the file. The first such line also applies to any entries
- before it.
-
-- {{{kbd(#+COLUMNS: %25ITEM ...)}}} ::
- #+cindex: property, COLUMNS
-
- Set the default format for columns view. This format applies when
- columns view is invoked in locations where no ~COLUMNS~ property
- applies.
-
-- {{{kbd(#+CONSTANTS: name1=value1 ...)}}} ::
- #+vindex: org-table-formula-constants
- #+vindex: org-table-formula
-
- Set file-local values for constants to be used in table formulas. This
- line sets the local variable ~org-table-formula-constants-local~. The
- global version of this variable is ~org-table-formula-constants~.
-
-- {{{kbd(#+FILETAGS: :tag1:tag2:tag3:)}}} ::
-
- Set tags that can be inherited by any entry in the file, including the
- top-level entries.
-
-- {{{kbd(#+DRAWERS: NAME1 ...)}}} ::
- #+vindex: org-drawers
-
- Set the file-local set of additional drawers. The corresponding global
- variable is ~org-drawers~.
-
-- {{{kbd(#+LINK: linkword replace)}}} ::
- #+vindex: org-link-abbrev-alist
-
- These lines (several are allowed) specify link abbreviations. See
- [[Link abbreviations]]. The corresponding variable is ~org-link-abbrev-alist~.
-
-- {{{kbd(#+PRIORITIES: highest lowest default)}}} ::
- #+vindex: org-highest-priority
- #+vindex: org-lowest-priority
- #+vindex: org-default-priority
-
- This line sets the limits and the default for the priorities. All
- three must be either letters A-Z or numbers 0-9. The highest priority
- must have a lower ASCII number than the lowest priority.
-
-- {{{kbd(#+PROPERTY: Property_Name Value)}}} ::
-
- This line sets a default inheritance value for entries in the current
- buffer, most useful for specifying the allowed values of a property.
-
-- {{{kbd(#+SETUPFILE: file)}}} ::
- #+cindex: #+SETUPFILE
-
- This line defines a file that holds more in-buffer setup. Normally
- this is entirely ignored. Only when the buffer is parsed for
- option-setting lines (i.e., when starting Org mode for a file, when
- pressing {{{kbd(C-c C-c)}}} in a settings line, or when exporting),
- then the contents of this file are parsed as if they had been included
- in the buffer. In particular, the file can be any other Org mode file
- with internal setup. You can visit the file the cursor is in the line
- with {{{kbd(C-c ')}}}.
-
-- {{{kbd(#+STARTUP:)}}} ::
- #+cindex: #+STARTUP:
-
- This line sets options to be used at startup of Org mode, when an
- Org file is being visited.
-
- The first set of options deals with the initial visibility of the
- outline tree. The corresponding variable for global default settings
- is ~org-startup-folded~, with a default value ~t~, which means
- ~overview~.
-
- #+vindex: org-startup-folded
- #+cindex: @code{overview}, STARTUP keyword
- #+cindex: @code{content}, STARTUP keyword
- #+cindex: @code{showall}, STARTUP keyword
- #+cindex: @code{showeverything}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~overview~ :: top-level headlines only
- - ~content~ :: all headlines
- - ~showall~ :: no folding of any entries
- - ~showeverything~ :: show even drawer contents
-
- #+vindex: org-startup-indented
- #+cindex: @code{indent}, STARTUP keyword
- #+cindex: @code{noindent}, STARTUP keyword
-
- Dynamic virtual indentation is controlled by the variable
- ~org-startup-indented~.[fn:182]
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~indent~ :: start with ~org-indent-mode~ turned on
- - ~noindent~ :: start with ~org-indent-mode~ turned off
-
- #+vindex: org-startup-align-all-tables
-
- Then there are options for aligning tables upon visiting a file. This
- is useful in files containing narrowed table columns. The corresponding
- variable is ~org-startup-align-all-tables~, with a default value
- ~nil~.
-
- #+cindex: @code{align}, STARTUP keyword
- #+cindex: @code{noalign}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~align~ :: align all tables
- - ~noalign~ :: don't align tables on startup
-
- #+vindex: org-startup-with-inline-images
-
- When visiting a file, inline images can be automatically displayed.
- The corresponding variable is ~org-startup-with-inline-images~, with a
- default value ~nil~ to avoid delays when visiting a file.
-
- #+cindex: @code{inlineimages}, STARTUP keyword
- #+cindex: @code{noinlineimages}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~inlineimages~ show inline images
- - ~noinlineimages~ don't show inline images on startup
-
- #+vindex: org-log-done
- #+vindex: org-log-note-clock-out
- #+vindex: org-log-repeat
-
- Logging the closing and reopening of TODO items and clock intervals
- can be configured using these options (see variables ~org-log-done~,
- ~org-log-note-clock-out~, and ~org-log-repeat~).
-
- #+cindex: @code{logdone}, STARTUP keyword
- #+cindex: @code{lognotedone}, STARTUP keyword
- #+cindex: @code{nologdone}, STARTUP keyword
- #+cindex: @code{lognoteclock-out}, STARTUP keyword
- #+cindex: @code{nolognoteclock-out}, STARTUP keyword
- #+cindex: @code{logrepeat}, STARTUP keyword
- #+cindex: @code{lognoterepeat}, STARTUP keyword
- #+cindex: @code{nologrepeat}, STARTUP keyword
- #+cindex: @code{logreschedule}, STARTUP keyword
- #+cindex: @code{lognotereschedule}, STARTUP keyword
- #+cindex: @code{nologreschedule}, STARTUP keyword
- #+cindex: @code{logredeadline}, STARTUP keyword
- #+cindex: @code{lognoteredeadline}, STARTUP keyword
- #+cindex: @code{nologredeadline}, STARTUP keyword
- #+cindex: @code{logrefile}, STARTUP keyword
- #+cindex: @code{lognoterefile}, STARTUP keyword
- #+cindex: @code{nologrefile}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~logdone~ :: record a timestamp when an item is marked DONE
- - ~lognotedone~ :: record timestamp and a note when DONE
- - ~nologdone~ :: don't record when items are marked DONE
- - ~logrepeat~ :: record a time when reinstating a repeating item
- - ~lognoterepeat~ :: record a note when reinstating a repeating item
- - ~nologrepeat~ :: do not record when reinstating repeating item
- - ~lognoteclock-out~ :: record a note when clocking out
- - ~nolognoteclock-out~ :: don't record a note when clocking out
- - ~logreschedule~ :: record a timestamp when scheduling time changes
- - ~lognotereschedule~ :: record a note when scheduling time changes
- - ~nologreschedule~ :: do not record when a scheduling date changes
- - ~logredeadline~ :: record a timestamp when deadline changes
- - ~lognoteredeadline~ :: record a note when deadline changes
- - ~nologredeadline~ :: do not record when a deadline date changes
- - ~logrefile~ :: record a timestamp when refiling
- - ~lognoterefile~ :: record a note when refiling
- - ~nologrefile~ :: do not record when refiling
-
- #+vindex: org-hide-leading-stars
- #+vindex: org-odd-levels-only
-
- Here are the options for hiding leading stars in outline headings, and
- for indenting outlines. The corresponding variables are
- ~org-hide-leading-stars~ and ~org-odd-levels-only~, both with a
- default setting ~nil~ (meaning ~showstars~ and ~oddeven~).
-
- #+cindex: @code{hidestars}, STARTUP keyword
- #+cindex: @code{showstars}, STARTUP keyword
- #+cindex: @code{odd}, STARTUP keyword
- #+cindex: @code{even}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~hidestars~ :: make all but one of the stars starting a headline invisible.
- - ~showstars~ :: show all stars starting a headline
- - ~indent~ :: virtual indentation according to outline level
- - ~noindent~ :: no virtual indentation according to outline level
- - ~odd~ :: allow only odd outline levels (1, 3, ...)
- - ~oddeven~ :: allow all outline levels
-
- #+vindex: org-put-time-stamp-overlays
- #+vindex: org-time-stamp-overlay-formats
-
- To turn on custom format overlays over timestamps (variables
- ~org-put-time-stamp-overlays~ and ~org-time-stamp-overlay-formats~),
- use:
-
- #+cindex: @code{customtime}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~customtime~ :: overlay custom time format
-
- #+vindex: constants-unit-system
-
- The following options influence the table spreadsheet (variable
- ~constants-unit-system~).
-
- #+cindex: @code{constcgs}, STARTUP keyword
- #+cindex: @code{constSI}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~constcgs~ :: {{{file(constants.el)}}} should use the c-g-s unit system
- - ~constSI~ :: {{{file(constants.el)}}} should use the SI unit system
-
- #+vindex: org-footnote-define-inline
- #+vindex: org-footnote-auto-label
- #+vindex: org-footnote-auto-adjust
-
- To influence footnote settings, use the following keywords. The
- corresponding variables are ~org-footnote-define-inline~,
- ~org-footnote-auto-label~, and ~org-footnote-auto-adjust~.
-
- #+cindex: @code{fninline}, STARTUP keyword
- #+cindex: @code{nofninline}, STARTUP keyword
- #+cindex: @code{fnlocal}, STARTUP keyword
- #+cindex: @code{fnprompt}, STARTUP keyword
- #+cindex: @code{fnauto}, STARTUP keyword
- #+cindex: @code{fnconfirm}, STARTUP keyword
- #+cindex: @code{fnplain}, STARTUP keyword
- #+cindex: @code{fnadjust}, STARTUP keyword
- #+cindex: @code{nofnadjust}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~fninline~ :: define footnotes inline
- - ~fnnoinline~ :: define footnotes in separate section
- - ~fnlocal~ :: define footnotes near first reference, but not inline
- - ~fnprompt~ :: prompt for footnote labels
- - ~fnauto~ :: create ~[fn:1]~-like labels automatically (default)
- - ~fnconfirm~ :: offer automatic label for editing or confirmation
- - ~fnplain~ :: create ~[1]~-like labels automatically
- - ~fnadjust~ :: automatically renumber and sort footnotes
- - ~nofnadjust~ :: do not renumber and sort automatically
-
- #+cindex: org-hide-block-startup
-
- To hide blocks on startup, use these keywords. The corresponding
- variable is ~org-hide-block-startup~.
-
- #+cindex: @code{hideblocks}, STARTUP keyword
- #+cindex: @code{nohideblocks}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~hideblocks~ :: Hide all begin/end blocks on startup
- - ~nohideblocks~ :: Do not hide blocks on startup
-
- #+cindex: org-pretty-entities
-
- The display of entities as UTF-8 characters is governed by the
- variable ~org-pretty-entities~ and the keywords
-
- #+cindex: @code{entitiespretty}, STARTUP keyword
- #+cindex: @code{entitiesplain}, STARTUP keyword
-
- #+attr_texinfo: :table-type table :indic @asis
- - ~entitiespretty~ :: Show entities as UTF-8 characters where possible
- - ~entitiesplain~ :: Leave entities plain
-
-- {{{kbd(#+TAGS: TAG1(c1) TAG2(c2))}}} ::
- #+vindex: org-tag-alist
-
- These lines (several such lines are allowed) specify the valid tags in
- this file, and (potentially) the corresponding /fast tag selection/
- keys. The corresponding variable is ~org-tag-alist~.
-
-- {{{kbd(#+TBLFM:)}}} ::
-
- This line contains the formulas for the table directly above the line.
-
-- {{{kbd(#+TITLE:)}}}, {{{kbd(#+AUTHOR:)}}}, {{{kbd(#+EMAIL:)}}}, {{{kbd(#+LANGUAGE:)}}}, {{{kbd(#+TEXT:)}}}, {{{kbd(#+DATE:)}}}, {{{kbd(#+OPTIONS:)}}}, {{{kbd(#+BIND:)}}}, {{{kbd(#+XSLT:)}}}, {{{kbd(#+DESCRIPTION:)}}}, {{{kbd(#+KEYWORDS:)}}}, {{{kbd(#+LaTeX_HEADER:)}}}, {{{kbd(#+STYLE:)}}}, {{{kbd(#+LINK_UP:)}}}, {{{kbd(#+LINK_HOME:)}}}, {{{kbd(#+EXPORT_SELECT_TAGS:)}}}, {{{kbd(#+EXPORT_EXCLUDE_TAGS:)}}} ::
-
- These lines provide settings for exporting files. For more details see
- [[Export options]].
-
-- {{{kbd(#+TODO:)}}}, {{{kbd(#+SEQ_TODO:)}}}, {{{kbd(#+TYP_TODO:)}}} ::
- #+vindex: org-todo-keywords
-
- These lines set the TODO keywords and their interpretation in the
- current file. The corresponding variable is ~org-todo-keywords~.
-
-** The very busy C-c C-c key
- :PROPERTIES:
- :DESCRIPTION: When in doubt, press C-c C-c
- :TITLE: The very busy C-c C-c key
- :END:
-#+kindex: C-c C-c
-#+cindex: C-c C-c, overview
-
-The key {{{kbd(C-c C-c)}}} has many purposes in Org, which are all
-mentioned scattered throughout this manual. One specific function of
-this key is to add /tags/ to a headline (see [[Tags]]). In many
-other circumstances it means something like "Hey Org, look
-here and update according to what you see here." Here is a summary of
-what this means in different contexts.
-
-- If there are highlights in the buffer from the creation of a sparse
- tree, or from clock display, remove these highlights.
-- If the cursor is in one of the special ~#+KEYWORD~ lines, this
- triggers scanning the buffer for these lines and updating the
- information.
-- If the cursor is inside a table, realign the table. This command
- works even if the automatic table editor has been turned off.
-- If the cursor is on a ~#+TBLFM~ line, re-apply the formulas to the
- entire table.
-- If the current buffer is a capture buffer, close the note and file
- it. With a prefix argument, file it, without further interaction, to
- the default location.
-- If the cursor is on a ~<<<target>>>~, update radio targets and
- corresponding links in this buffer.
-- If the cursor is in a property line or at the start or end of a
- property drawer, offer property commands.
-- If the cursor is at a footnote reference, go to the corresponding
- definition, and vice versa.
-- If the cursor is on a statistics cookie, update it.
-- If the cursor is in a plain list item with a checkbox, toggle the
- status of the checkbox.
-- If the cursor is on a numbered item in a plain list, renumber the
- ordered list.
-- If the cursor is on the ~#+BEGIN~ line of a dynamic block, the block
- is updated.
-- If the cursor is at a timestamp, fix the day name in the timestamp.
-
-** Clean view
- :PROPERTIES:
- :DESCRIPTION: Getting rid of leading stars in the outline
- :TITLE: A cleaner outline view
- :END:
-#+cindex: hiding leading stars
-#+cindex: dynamic indentation
-#+cindex: odd-levels-only outlines
-#+cindex: clean outline view
-
-Some people find it noisy and distracting that the Org headlines start
-with a potentially large number of stars, and that text below the
-headlines is not indented. While this is no problem when writing a
-/book-like/ document where the outline headings are really section
-headings, in a more /list-oriented/ outline, indented structure is a
-lot cleaner:
-
-#+begin_example
- ,* Top level headline | * Top level headline
- ,** Second level | * Second level
- ,*** 3rd level | * 3rd level
- some text | some text
- ,*** 3rd level | * 3rd level
- more text | more text
- ,* Another top level headline | * Another top level headline
-#+end_example
-
-{{{noindent}}} If you are using at least Emacs 23.2 and version 6.29
-of Org, this kind of view can be achieved dynamically at display time
-using ~org-indent-mode~.[fn:183] In this minor mode, all lines are
-prefixed for display with the necessary amount of space.[fn:154] Also
-headlines are prefixed with additional stars, so that the amount of
-indentation shifts by two spaces per level.[fn:155] All headline stars
-but the last one are made invisible using the ~org-hide~ face---see
-below under {{{samp(2.)}}} for more information on how this
-works.[fn:156] You can turn on ~org-indent-mode~ for all files by
-customizing the variable ~org-startup-indented~, or you can turn it on
-for individual files using
-
-#+begin_example
- ,#+STARTUP: indent
-#+end_example
-
-If you want a similar effect in an earlier version of Emacs and/or
-Org, or if you want the indentation to be hard space characters so
-that the plain text file looks as similar as possible to the Emacs
-display, Org supports you in the following way:
-
-#+attr_texinfo: :table-type table :indic @asis
-- Indentation of text below headlines ::
-
- You may indent text below each headline to make the left boundary line up
- with the headline, like
-
- #+begin_example
- ,*** 3rd level
- more text, now indented
- #+end_example
-
- #+vindex: org-adapt-indentation
-
- Org supports this with paragraph filling, line wrapping, and structure
- editing,
- preserving or adapting the indentation as appropriate.[fn:157]
-
-- Hiding leading stars ::
- #+vindex: org-hide-leading-stars
-
- You can modify the display in such a way that all leading stars become
- invisible. To do this in a global way, configure the variable
- ~org-hide-leading-stars~ or change this on a per-file basis with
-
- #+begin_example
- ,#+STARTUP: hidestars
- ,#+STARTUP: showstars
- #+end_example
-
- With hidden stars, the tree becomes:
-
- #+begin_example
- ,* Top level headline
- , * Second level
- , * 3rd level
- ...
- #+end_example
-
- #+vindex: org-hide @r{(face)}
-
- {{{noindent}}} The leading stars are not truly replaced by whitespace,
- they are only fontified with the face ~org-hide~ that uses the
- background color as font color. If you are not using either white or
- black background, you may have to customize this face to get the
- wanted effect. Another possibility is to set this font such that the
- extra stars are /almost/ invisible, for example using the color
- ~grey90~ on a white background.
-- Odd levels ::
- #+vindex: org-odd-levels-only
-
- Things become cleaner still if you skip all the even levels and use
- only odd levels 1, 3, 5, ..., effectively adding two stars to go from
- one outline level to the next.[fn:158] In this way we get the outline
- view shown at the beginning of this section. In order to make the
- structure editing and export commands handle this convention
- correctly, configure the variable ~org-odd-levels-only~, or set this
- on a per-file basis with one of the following lines:
-
- #+begin_example
- ,#+STARTUP: odd
- ,#+STARTUP: oddeven
- #+end_example
-
- You can convert an Org file from single-star-per-level to the
- double-star-per-level convention with {{{kbdkey(M-x
- org-convert-to-odd-levels , RET)}}} in that file. The reverse
- operation is {{{kbd(M-x org-convert-to-oddeven-levels)}}}.
-
-** TTY keys
- :PROPERTIES:
- :DESCRIPTION: Using Org on a tty
- :TITLE: Using Org on a tty
- :END:
-
-Because Org contains a large number of commands, by default many of
-Org's core commands are bound to keys that are generally not
-accessible on a tty, such as the cursor keys ({{{key(left)}}},
-{{{key(right)}}}, {{{key(up)}}}, {{{key(down)}}}), {{{key(TAB)}}} and
-{{{key(RET)}}}, in particular when used together with modifiers like
-{{{key(Meta)}}} and/or {{{key(Shift)}}}. To access these commands on a
-tty when special keys are unavailable, the following alternative
-bindings can be used. The tty bindings below will likely be more
-cumbersome; you may find for some of the bindings below that a
-customized workaround suits you better. For example, changing a
-timestamp is really only fun with {{{kbdkey(S-,cursor)}}} keys,
-whereas on a tty you would rather use {{{kbd(C-c .)}}} to re-insert
-the timestamp.
-
-#+attr_texinfo: :columns 0.2 0.3 0.1 0.4
-| Default | Alternative 1 | Speed key | Alternative 2 |
-|--------------------------+------------------------------+--------------+---------------------------|
-| {{{kbdkey(S-,TAB)}}} | {{{kbdspckey(C-u,TAB)}}} | {{{kbd(C)}}} | |
-| {{{kbdkey(M-,left)}}} | {{{kbd(C-c C-x l)}}} | {{{kbd(l)}}} | {{{kbdkeys(,Esc,left)}}} |
-| {{{kbdkey(M-S-,left)}}} | {{{kbd(C-c C-x L)}}} | {{{kbd(L)}}} | |
-| {{{kbdkey(M-,right)}}} | {{{kbd(C-c C-x r)}}} | {{{kbd(r)}}} | {{{kbdkeys(,Esc,right)}}} |
-| {{{kbdkey(M-S-,right)}}} | {{{kbd(C-c C-x R)}}} | {{{kbd(R)}}} | |
-| {{{kbdkey(M-,up)}}} | {{{kbd(C-c C-x u)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,up)}}} |
-| {{{kbdkey(M-S-,up)}}} | {{{kbd(C-c C-x U)}}} | {{{kbd(U)}}} | |
-| {{{kbdkey(M-,down)}}} | {{{kbd(C-c C-x d)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,down)}}} |
-| {{{kbdkey(M-S-,down)}}} | {{{kbd(C-c C-x D)}}} | {{{kbd(D)}}} | |
-| {{{kbdkey(S-,RET)}}} | {{{kbd(C-c C-x c)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(M-,RET)}}} | {{{kbd(C-c C-x m)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,RET)}}} |
-| {{{kbdkey(M-S-,RET)}}} | {{{kbd(C-c C-x M)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(S-,left)}}} | {{{kbdspckey(C-c,left)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(S-,right)}}} | {{{kbdspckey(C-c,right)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(S-,up)}}} | {{{kbdspckey(C-c,up)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(S-,down)}}} | {{{kbdspckey(C-c,down)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(C-S-,left)}}} | {{{kbdspckey(C-c C-x,left)}}} | {{{kbd( )}}} | |
-| {{{kbdkey(C-S-,right)}}} | {{{kbdspckey(C-c C-x,right)}}} | {{{kbd( )}}} | |
-
-** Interaction
- :PROPERTIES:
- :DESCRIPTION: Other Emacs packages
- :TITLE: Interaction with other packages
- :END:
-#+cindex: packages, interaction with other
-Org lives in the world of GNU Emacs and interacts in various ways
-with other code out there.
-
-*** FIXME Cooperation
- :PROPERTIES:
- :DESCRIPTION: Packages Org cooperates with
- :TITLE: Packages that Org cooperates with
- :END:
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{file(calc.el)}}} by Dave Gillespie ::
- #+cindex: @file{calc.el}
- #+cindex: Gillespie, Dave
-
- Org uses the Calc package for implementing spreadsheet functionality
- in its tables (see [[The spreadsheet]]). Org checks for the availability
- of Calc by looking for the function ~calc-eval~ which will have been
- autoloaded during setup if Calc has been installed properly. As of
- Emacs 22, Calc is part of the Emacs distribution. Another possibility
- for interaction between the two packages is using Calc for embedded
- calculations. See [[info:calc:Embedded Mode][GNU Emacs Calc Manual]].
-
-- {{{file(constants.el)}}} by Carsten Dominik ::
- #+cindex: @file{constants.el}
- #+cindex: Dominik, Carsten
- #+vindex: org-table-formula-constants
-
- In a table formula (see [[The spreadsheet]]), it is possible to use names
- for natural constants or units. Instead of defining your own constants
- in the variable ~org-table-formula-constants~, install the
- {{{file(constants)}}} package which defines a large number of
- constants and units, and lets you use unit prefixes like {{{samp(M)}}}
- for {{{samp(Mega)}}}, etc. You will need version 2.0 of this package,
- available at [[http://www.astro.uva.nl/~dominik/Tools]]. Org checks for
- the function ~constants-get~, which has to be autoloaded in your
- setup. See the installation instructions in the file
- {{{file(constants.el)}}}.
-
-- {{{file(cdlatex.el)}}} by Carsten Dominik ::
- #+cindex: @file{cdlatex.el}
- #+cindex: Dominik, Carsten
-
- Org mode can make use of the CDLaTeX package to efficiently enter
- LaTeX fragments into Org files. See [[CDLaTeX mode]].
-
-- {{{file(imenu.el)}}} by Ake Stenhoff and Lars Lindberg ::
- #+cindex: @file{imenu.el}
- #+cindex: Stenhoff, Ake
- #+cindex: Lindberg, Lars
-
- Imenu allows menu access to an index of items in a file. Org mode
- supports Imenu---all you need to do to get the index is the following:
-
- #+begin_src emacs-lisp
- (add-hook 'org-mode-hook
- (lambda () (imenu-add-to-menubar "Imenu")))
- #+end_src
-
- #+vindex: org-imenu-depth
-
- By default the index is two levels deep---you can modify the depth
- using the option ~org-imenu-depth~.
-
-- {{{file(remember.el)}}} by John Wiegley ::
- #+cindex: @file{remember.el}
- #+cindex: Wiegley, John
-
- Org used to use this package for capture, but no longer does.
-
-- {{{file(speedbar.el)}}} by Eric M. Ludlam ::
- #+cindex: @file{speedbar.el}
- #+cindex: Ludlam, Eric M.
-
- Speedbar is a package that creates a special frame displaying files and
- index items in files. Org mode supports Speedbar and allows you to
- drill into Org files directly from the Speedbar. It also allows you to
- restrict the scope of agenda commands to a file or a subtree by using
- the command {{{kbd(<)}}} in the Speedbar frame.
-
-- {{{file(table.el)}}} by Takaaki Ota ::
- #+kindex: C-c C-c
- #+cindex: table editor, @file{table.el}
- #+cindex: @file{table.el}
- #+cindex: Ota, Takaaki
-
- Complex ASCII tables with automatic line wrapping, column- and row-spanning,
- and alignment can be created using the Emacs table package by Takaaki Ota
- ([[http://sourceforge.net/projects/table]], and also part of Emacs 22).
- Org mode will recognize these tables and export them properly. Because of
- interference with other Org mode functionality, you unfortunately cannot edit
- these tables directly in the buffer. Instead, you need to use the command
- {{{kbd(C-c ')}}} to edit them, similar to source code snippets.
-
- - {{{kbd(C-c ')}}}, ~org-edit-special~ ::
- #+kindex: C-c '
-
- Edit a {{{file(table.el)}}} table. Works when the cursor is in a
- table.el table.
-
- - {{{kbd(C-c XXX)}}}, ~org-table-create-with-table.el~ ::
- #+kindex: C-c ~
- # Should be ~
- Insert a {{{file(table.el)}}} table. If there is already a table at
- point, this command converts it between the {{{file(table.el)}}}
- format and the Org mode format. See the documentation string of the
- command ~org-convert-table~ for the restrictions under which this is
- possible.
-
- {{{file(table.el)}}} is part of Emacs since Emacs 22.
-
-- {{{file(footnote.el)}}} by Steven L. Baur ::
- #+cindex: @file{footnote.el}
- #+cindex: Baur, Steven L.
-
- Org mode recognizes numerical footnotes as provided by this package.
- However, Org mode also has its own footnote support (see [[Creating footnotes]]),
- which makes using {{{file(footnote.el)}}} unnecessary.
-
-*** Conflicts
- :PROPERTIES:
- :DESCRIPTION: Packages that lead to conflicts
- :END:
-
-#+cindex: @code{shift-selection-mode}
-#+vindex: org-support-shift-select
-
-In Emacs 23, ~shift-selection-mode~ is on by default, meaning that
-cursor motions combined with the shift key should start or enlarge
-regions. This conflicts with the use of {{{kbdkey(S-,cursor)}}}
-commands in Org to change timestamps, TODO keywords, priorities, and
-item bullet types if the cursor is at such a location. By default,
-{{{kbdkey(S-,cursor)}}} commands outside special contexts don't do
-anything, but you can customize the variable
-~org-support-shift-select~. Org mode then tries to accommodate shift
-selection by using it outside of the special contexts where
-special commands apply, and by extending an existing active
-region even if the cursor moves across a special context.
-
-#+attr_texinfo: :table-type table :indic @asis
-- {{{file(CUA.el)}}} by Kim. F. Storm ::
- #+cindex: @file{CUA.el}
- #+cindex: Storm, Kim. F.
- #+vindex: org-replace-disputed-keys
-
- Key bindings in Org conflict with the {{{kbdkey(S-,<cursor>)}}} keys
- used by CUA mode (as well as ~pc-select-mode~ and ~s-region-mode~) to
- select and extend the region. In fact, Emacs 23 has this built-in in
- the form of ~shift-selection-mode~, see previous paragraph. If you are
- using Emacs 23, you probably don't want to use another package for
- this purpose. However, if you prefer to leave these keys to a
- different package while working in Org mode, configure the variable
- ~org-replace-disputed-keys~. When set, Org will move the following key
- bindings in Org files, and in the agenda buffer (but not during date
- selection).
-
- | S-UP {{{result}}} M-p | S-DOWN {{{result}}} M-n |
- | S-LEFT {{{result}}} M-- | S-RIGHT {{{result}}} M-+ |
- | C-S-LEFT {{{result}}} M-S-- | C-S-RIGHT {{{result}}} M-S-+ |
-
- #+vindex: org-disputed-keys
-
- Yes, these are unfortunately more difficult to remember. If you want
- to have other replacement keys, look at the variable
- ~org-disputed-keys~.
-
-- {{{file(filladapt.el)}}} by Kyle Jones ::
- #+cindex: @file{filladapt.el}
- #+cindex: Jones, Kyle
-
- Org mode tries to do the right thing when filling paragraphs, list
- items and other elements. Many users reported they had problems using
- both {{{file(filladapt.el)}}} and Org mode, so a safe thing to do is
- to disable it like this:
-
- #+begin_src emacs-lisp
- (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
- #+end_src
-
-- {{{file(yasnippet.el)}}} ::
- #+cindex: @file{yasnippet.el}
-
- The way Org mode binds the {{{key(TAB)}}} key (binding to ~[tab]~
- instead of ~"\t"~) overrules YASnippet's access to this key. The
- following code fixed this problem:
-
- #+begin_src emacs-lisp
- (add-hook 'org-mode-hook
- (lambda ()
- (org-set-local 'yas/trigger-key [tab])
- (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
- #+end_src
-
- The latest version of yasnippet doesn't play well with Org mode. If the
- above code does not fix the conflict, start by defining the following
- function:
-
- #+begin_src emacs-lisp
- (defun yas/org-very-safe-expand ()
- (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
- #+end_src
-
- Then, tell Org mode what to do with the new function:
-
- #+begin_src emacs-lisp
- (add-hook 'org-mode-hook
- (lambda ()
- (make-variable-buffer-local 'yas/trigger-key)
- (setq yas/trigger-key [tab])
- (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
- (define-key yas/keymap [tab] 'yas/next-field)))
- #+end_src
-
-- {{{file(windmove.el)}}} by Hovav Shacham ::
- #+cindex: @file{windmove.el}
- #+cindex: Shacham, Hovav
-
- This package also uses the {{{kbd(S-<cursor>)}}} keys, so everything
- written in the paragraph above about CUA mode also applies here. If
- you want make the windmove function active in locations where Org mode
- does not have special functionality on {{{kbdkey(S-,cursor)}}}, add
- this to your configuration:
-
- #+begin_src emacs-lisp
- ;; Make windmove work in org-mode:
- (add-hook 'org-shiftup-final-hook 'windmove-up)
- (add-hook 'org-shiftleft-final-hook 'windmove-left)
- (add-hook 'org-shiftdown-final-hook 'windmove-down)
- (add-hook 'org-shiftright-final-hook 'windmove-right)
- #+end_src
-
-- {{{file(viper.el)}}} by Michael Kifer ::
- #+cindex: @file{viper.el}
- #+cindex: Kifer, Michael
- #+kindex: C-c /
-
- Viper uses {{{kbd(C-c /)}}} and therefore makes this key not access the
- corresponding Org mode command ~org-sparse-tree~. You need to find
- another key for this command, or override the key in
- ~viper-vi-global-user-map~ with
-
- #+begin_src emacs-lisp
- (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
- #+end_src
-
-** org-crypt
- :PROPERTIES:
- :DESCRIPTION: Encrypting Org files
- :END:
-#+cindex: @file{+org-crypt.el}
-#+cindex: @code{org-decrypt-entry}
-
-Org-crypt will encrypt the text of an entry, but not the headline, or
-properties. Org-crypt uses the Emacs EasyPG library to encrypt and
-decrypt files.
-
-Any text below a headline that has a {{{samp(:crypt:)}}} tag will
-automatically be encrypted when the file is saved. If you want to use
-a different tag just customize the ~org-crypt-tag-matcher~ setting.
-
-To use org-crypt it is suggested that you have the following in your
-{{{file(.emacs)}}}:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(require 'org-crypt)
-(org-crypt-use-before-save-magic)
-(setq org-tags-exclude-from-inheritance (quote ("crypt")))
-
-(setq org-crypt-key nil)
- ;; GPG key to use for encryption
- ;; Either the Key ID or set to nil to use symmetric encryption.
-
-(setq auto-save-default nil)
- ;; Auto-saving does not cooperate with org-crypt.el: so you need
- ;; to turn it off if you plan to use org-crypt.el quite often.
- ;; Otherwise, you'll get an (annoying) message each time you
- ;; start Org.
-
- ;; To turn it off only locally, you can insert this:
- ;;
- ;; # -*- buffer-auto-save-file-name: nil; -*-
-#+end_src
-
-Excluding the crypt tag from inheritance prevents already encrypted text
-being encrypted again.
-
-* Hacking
- :PROPERTIES:
- :DESCRIPTION: How to hack your way around
- :APPENDIX: Appendix
- :END:
-#+cindex: hacking
-
-This appendix describes some ways a user can extend the functionality
-of Org.
-
-** Hooks
- :PROPERTIES:
- :DESCRIPTION: How to reach into Org's internals
- :END:
-#+cindex: hooks
-
-Org has a large number of hook variables that can be used to add
-functionality. This appendix about hacking is going to illustrate the
-use of some of them. A complete list of all hooks with documentation is
-maintained by the Worg project and can be found at
-[[http://orgmode.org/worg/org-configs/org-hooks.php]].
-
-** Add-on packages
- :PROPERTIES:
- :DESCRIPTION: Available extensions
- :END:
-#+cindex: add-on packages
-
-A large number of add-on packages have been written by various
-authors. These packages are not part of Emacs, but they are
-distributed as contributed packages with the separate release
-available at the Org mode home page at [[http://orgmode.org]]. The
-list of contributed packages, along with documentation about each
-package, is maintained by the Worg project at
-[[http://orgmode.org/worg/org-contrib/]].
-
-** Adding hyperlink types
- :PROPERTIES:
- :DESCRIPTION: New custom link types
- :END:
-#+cindex: hyperlinks, adding new types
-
-Org has a large number of hyperlink types built-in (see [[Hyperlinks]]).
-If you would like to add new link types, Org provides an interface for
-doing so. Let's look at an example file, {{{file(org-man.el)}}}, that
-will add support for creating links like:
-
-#+begin_example
- [[man:printf][The printf manual]]
-#+end_example
-
-to show Unix manual pages inside Emacs:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-;;; org-man.el - Support for links to manpages in Org
-
-(require 'org)
-
-(org-add-link-type "man" 'org-man-open)
-(add-hook 'org-store-link-functions 'org-man-store-link)
-
-(defcustom org-man-command 'man
- "The Emacs command to be used to display a man page."
- :group 'org-link
- :type '(choice (const man) (const woman)))
-
-(defun org-man-open (path)
- "Visit the manpage on PATH.
-PATH should be a topic that can be thrown at the man command."
- (funcall org-man-command path))
-
-(defun org-man-store-link ()
- "Store a link to a manpage."
- (when (memq major-mode '(Man-mode woman-mode))
- ;; This is a man page, we do make this link
- (let* ((page (org-man-get-page-name))
- (link (concat "man:" page))
- (description (format "Manpage for %s" page)))
- (org-store-link-props
- :type "man"
- :link link
- :description description))))
-
-(defun org-man-get-page-name ()
- "Extract the page name from the buffer name."
- ;; This works for both `Man-mode' and `woman-mode'.
- (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
- (match-string 1 (buffer-name))
- (error "Cannot create link to this man page")))
-
-(provide 'org-man)
-
-;;; org-man.el ends here
-#+end_src
-
-{{{noindent}}} You would activate this new link type in
-{{{file(.emacs)}}} with:
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(require 'org-man)
-#+end_src
-
-{{{noindent}}} Let's go through the file and see what it does.
-#+vindex: org-store-link-functions
-
-1. It does ~(require 'org)~ to make sure that {{{file(org.el)}}} has
- been loaded.
-
-2. The next line calls ~org-add-link-type~ to define a new link type
- with prefix {{{samp(man)}}}. The call also contains the name of a
- function that will be called to follow such a link.
-
-3. The next line adds a function to ~org-store-link-functions~, in
- order to allow the command {{{kbd(C-c l)}}} to record a useful link
- in a buffer displaying a man page.
-
-
-The rest of the file defines the necessary variables and functions.
-First there is a customization variable that determines which Emacs
-command should be used to display man pages. There are two options,
-~man~ and ~woman~. Then the function to follow a link is defined. It
-gets the link path as an argument---in this case the link path is just
-a topic for the manual command. The function calls the value of
-~org-man-command~ to display the man page.
-
-Finally the function ~org-man-store-link~ is defined. When you try to
-store a link with {{{kbd(C-c l)}}}, this function will be called to
-try to make a link. The function must first decide if it is supposed
-to create the link for this buffer type; we do this by checking the
-value of the variable ~major-mode~. If not, the function must exit and
-return the value ~nil~. If yes, the link is created by getting the
-manual topic from the buffer name and prefixing it with the string
-{{{samp(man:)}}}. Then it must call the command ~org-store-link-props~
-and set the ~:type~ and ~:link~ properties. Optionally you can also
-set the ~:description~ property to provide a default for the link
-description when the link is later inserted into an Org buffer with
-{{{kbd(C-c C-l)}}}.
-
-When it makes sense for your new link type, you may also define a
-function that implements special (e.g., completion) support for
-inserting such a link with {{{kbd(C-c C-l)}}}. Such a function should
-not accept any arguments, and return the full link with prefix.
-
-** Context-sensitive commands
- :PROPERTIES:
- :DESCRIPTION: How to add functionality to such commands
- :END:
-#+cindex: context-sensitive commands, hooks
-#+cindex: add-ons, context-sensitive commands
-#+vindex: org-ctrl-c-ctrl-c-hook
-
-Org has several commands that act differently depending on context.
-The most important example is the {{{kbd(C-c C-c)}}} (see [[The very
-busy C-c C-c key]]). Also the {{{kbd(M-cursor)}}} and
-{{{kbd(M-S-cursor)}}} keys have this property.
-
-Add-ons can tap into this functionality by providing a function that
-detects special context for that add-on and executes functionality
-appropriate for the context. Here is an example from Dan Davison's
-{{{file(org-R.el)}}} which allows you to evaluate commands based on
-the {{{file(R)}}} programming language.[fn:159] For this package,
-special contexts are lines that start with ~#+R:~ or ~#+RR:~.
-
-#+header: :eval no
-#+header: :exports code
-#+begin_src emacs-lisp
-(defun org-R-apply-maybe ()
- "Detect if this is context for org-R and execute R commands."
- (if (save-excursion
- (beginning-of-line 1)
- (looking-at "#\\+RR?:"))
- (progn (call-interactively 'org-R-apply)
- t) ;; to signal that we took action
- nil)) ;; to signal that we did not
-
-(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
-#+end_src
-
-The function first checks if the cursor is in such a line. If that is
-the case, ~org-R-apply~ is called and the function returns ~t~ to
-signal that action was taken, and {{{kbd(C-c C-c)}}} will stop looking
-for other contexts. If the function finds it should do nothing
-locally, it returns ~nil~ so that other, similar functions can have a
-try.
-
-** Tables in arbitrary syntax
- :PROPERTIES:
- :DESCRIPTION: Orgtbl for LaTeX and other programs
- :END:
-#+cindex: tables, in other modes
-#+cindex: lists, in other modes
-#+cindex: Orgtbl mode
-
-Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
-frequent feature request has been to make it work with native tables
-in specific languages, for example LaTeX. However, this is
-extremely hard to do in a general way, would lead to a customization
-nightmare, and would take away much of the simplicity of the Orgtbl
-mode table editor.
-
-This appendix describes a different approach. We keep the Orgtbl mode
-table in its native format (the source table), and use a custom
-function to /translate/ the table to the correct syntax, and to
-/install/ it in the right location (the target table). This puts
-the burden of writing conversion functions on the user, but it allows
-for a very flexible system.
-
-Bastien added the ability to do the same with lists, in Orgstruct
-mode. You can use Org's facilities to edit and structure lists by
-turning ~orgstruct-mode~ on, then locally exporting such lists in
-another format (HTML, LaTeX or Texinfo.)
-
-*** Radio tables
- :PROPERTIES:
- :DESCRIPTION: Sending and receiving radio tables
- :END:
-#+cindex: radio tables
-
-To define the location of the target table, you first need to create
-two lines that are comments in the current mode, but contain magic
-words for Orgtbl mode to find. Orgtbl mode will insert the translated
-table between these lines, replacing whatever was there before. For
-example:
-
-#+begin_example
- /* BEGIN RECEIVE ORGTBL table_name */
- /* END RECEIVE ORGTBL table_name */
-#+end_example
-
-{{{noindent}}} Just above the source table, we put a special line that
-tells Orgtbl mode how to translate this table and where to install it.
-For example:
-
-#+cindex: #+ORGTBL
-#+begin_example
- ,#+ORGTBL: SEND table_name translation_function arguments ...
-#+end_example
-
-{{{noindent}}} Here, ~table_name~ is the reference name for the table
-that is also used in the receiver lines. ~translation_function~ is the
-Lisp function that does the translation. Furthermore, the line can
-contain a list of arguments (alternating key and value) at the end.
-The arguments will be passed as a property list to the translation
-function for interpretation. A few standard parameters are already
-recognized and acted upon before the translation function is called:
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:skip N~ ::
-
- Skip the first N lines of the table. Hlines do count as separate lines
- for this parameter!
-
-- ~:skipcols (n1 n2 ...)~ ::
-
- List of columns that should be skipped. If the table has a column with
- calculation marks, that column is automatically discarded as well.
- Please note that the translator function sees the table /after/ the
- removal of these columns, the function never knows that there have
- been additional columns.
-
-- ~:no-escape t~ ::
-
- When non-nil, do not escape special characters ~&%#_^~ when exporting
- the table. The default value is nil.
-
-
-{{{noindent}}} The one problem remaining is how to keep the source
-table in the buffer without disturbing the normal workings of the
-file, for example during compilation of a C file or processing of a
-LaTeX file. There are a number of different solutions:
-
-- The table could be placed in a block comment if that is supported by
- the language. For example, in C mode you could wrap the table
- between {{{samp(/*)}}} and {{{samp(*/)}}} lines.
-
-- Sometimes it is possible to put the table after some kind of END
- statement, for example ~\bye~ in TeX and ~\end{document}~ in
- LaTeX.
-
-- You can just comment the table line-by-line whenever you want to
- process the file, and uncomment it whenever you need to edit the
- table. This only sounds tedious---the command {{{kbd(M-x
- orgtbl-toggle-comment)}}} makes this comment-toggling very easy, in
- particular if you bind it to a key.
-
-*** A LaTeX example
- :PROPERTIES:
- :DESCRIPTION: Step by step, almost a tutorial
- :TITLE: A LaTeX example of radio tables
- :END:
-#+cindex: @LaTeX{}, and Orgtbl mode
-
-The best way to wrap the source table in LaTeX is to use the
-~comment~ environment provided by {{{file(comment.sty)}}}. It has to
-be activated by placing ~\usepackage{comment}~ into the document
-header. Orgtbl mode can insert a radio table skeleton with the command
-{{{kbd(M-x orgtbl-insert-radio-table)}}}.[fn:160] You will be prompted
-for a table name, let's say we use {{{samp(salesfigures)}}}. You will
-then get the following template:
-
-#+cindex: #+ORGTBL, SEND
-#+begin_example
- % BEGIN RECEIVE ORGTBL salesfigures
- % END RECEIVE ORGTBL salesfigures
- \begin{comment}
- #+ORGTBL: SEND salesfigures orgtbl-to-latex
- | | |
- \end{comment}
-#+end_example
-
-#+vindex: @LaTeX{}-verbatim-environments
-
-{{{noindent}}} The ~#+ORGTBL: SEND~ line tells Orgtbl mode to use the
-function ~orgtbl-to-latex~ to convert the table into LaTeX and to
-put it into the receiver location with name ~salesfigures~. You may
-now fill in the table---feel free to use the spreadsheet features:[fn:161]
-
-#+begin_example
- % BEGIN RECEIVE ORGTBL salesfigures
- % END RECEIVE ORGTBL salesfigures
- \begin{comment}
- #+ORGTBL: SEND salesfigures orgtbl-to-latex
- | Month | Days | Nr sold | per day |
- |-------+------+---------+---------|
- | Jan | 23 | 55 | 2.4 |
- | Feb | 21 | 16 | 0.8 |
- | March | 22 | 278 | 12.6 |
- #+TBLFM: $4=$3/$2;%.1f
- % $ (optional extra dollar to keep font-lock happy, see footnote)
- \end{comment}
-#+end_example
-
-{{{noindent}}} When you are done, press {{{kbd(C-c C-c)}}} in the
-table to get the converted table inserted between the two marker
-lines.
-
-Now let's assume you want to make the table header by hand, because
-you want to control how columns are aligned, etc. In this case we make
-sure that the table translator skips the first 2 lines of the source
-table, and tell the command to work as a splice, i.e., to not
-produce header and footer commands of the target table:
-
-#+begin_example
- \begin{tabular}{lrrr}
- Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
- % BEGIN RECEIVE ORGTBL salesfigures
- % END RECEIVE ORGTBL salesfigures
- \end{tabular}
- %
- \begin{comment}
- #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
- | Month | Days | Nr sold | per day |
- |-------+------+---------+---------|
- | Jan | 23 | 55 | 2.4 |
- | Feb | 21 | 16 | 0.8 |
- | March | 22 | 278 | 12.6 |
- #+TBLFM: $4=$3/$2;%.1f
- \end{comment}
-#+end_example
-
-The LaTeX translator function ~orgtbl-to-latex~ is already part of
-Orgtbl mode. It uses a ~tabular~ environment to typeset the table and
-marks horizontal lines with ~\hline~. Furthermore, it interprets the
-following parameters (see also see [[Translator functions]]):
-
-#+attr_texinfo: :table-type table :indic @asis
-- ~:splice nil/t~ ::
-
- When set to ~t~, return only table body lines, don't wrap them into a
- tabular environment. Default is ~nil~.
-
-- ~:fmt fmt~ ::
-
- A format to be used to wrap each field, it should contain ~%s~ for the
- original field value. For example, to wrap each field value in
- dollars, you could use ~:fmt "$%s$"~. This may also be a property list
- with column numbers and formats, for example ~:fmt (2 "$%s$" 4
- "%s\\%%")~. A function of one argument can be used in place of the
- strings; the function must return a formatted string.
-
-- ~:efmt efmt~ ::
-
- Use this format to print numbers with exponentials. The format should
- have ~%s~ twice for inserting mantissa and exponent, for example:
-
- #+begin_example
- "%s\\times10^{%s}"
- #+end_example
-
- The default is:
-
- #+begin_example
- "%s\\,(%s)"
- #+end_example
-
- This may also be a property list with column numbers and formats, for
- example:
-
- #+begin_example
- :efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")
- #+end_example
-
- After ~efmt~ has been applied to a value, ~fmt~ will also be applied.
- Similar to ~fmt~, functions of two arguments can be supplied instead
- of 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