This manual is for Org (version 6.12b).
Copyright © 2004, 2005, 2006, 2007, 2008 Free Software Foundation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”(a) The FSF's Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”
This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.
--- The Detailed Node Listing ---
Introduction
Document Structure
Archiving
Tables
The spreadsheet
Hyperlinks
Internal links
TODO Items
Extended use of TODO keywords
Progress logging
Tags
Properties and Columns
Column view
Defining columns
Dates and Times
Creating timestamps
Deadlines and scheduling
Capture
Remember
Agenda Views
The built-in agenda views
Presentation and sorting
Custom agenda views
Embedded LaTeX
Exporting
Markup rules
HTML export
LaTeX and PDF export
Publishing
Configuration
Sample configuration
Miscellaneous
Interaction with other packages
Extensions
Hacking
Tables and lists in arbitrary syntax
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, time stamps, 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 (TODO and agenda items only) as an iCalendar file. It can also serve as a publishing tool for a set of linked web pages.
An important design aspect that distinguishes Org from for example Planner/Muse is that it encourages to store every piece of information only once. In Planner, you have project pages, day pages and possibly other files, duplicating some information such as tasks. In Org, you only have notes files. In your notes you mark entries as tasks, label them with tags and timestamps. All necessary lists like a schedule for the day, the agenda for a meeting, tasks lists selected by tags etc are created dynamically when you need them.
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, for example as:
• outline extension with visibility cycling and structure editing • ASCII system and table editor for taking structured notes • ASCII table editor with spreadsheet-like capabilities • TODO list editor • full agenda and planner with deadlines and work scheduling • environment to implement David Allen's GTD system • a basic database application • simple hypertext system, with HTML and LaTeX export • publishing tool to create a set of interlinked webpages
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.
There is a website for Org which provides links to the newest version of Org, as well as additional information, frequently asked questions (FAQ), links to tutorials etc. This page is located at http://orgmode.org.
Important: If Org is part of the Emacs distribution or an XEmacs package, please skip this section and go directly to Activation.
If you have downloaded Org from the Web, either as a distribution .zip or .tar file, or as a GIT archive, you must take the following steps to install it: Go into the unpacked Org distribution directory and edit the top section of the file Makefile. You must set the name of the Emacs binary (likely either emacs or xemacs), and the paths to the directories where local Lisp and Info files are kept. If you don't have access to the system-wide directories, you can simply run Org directly from the distribution directory by adding the lisp subdirectory to the Emacs load path. To do this, add the following line to .emacs:
(setq load-path (cons "~/path/to/orgdir/lisp" load-path))
If you plan to use code from the contrib subdirectory, do a similar step for this directory:
(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
XEmacs users now need to install the file noutline.el from the xemacs sub-directory of the Org distribution. Use the command:
make install-noutline
Now byte-compile the Lisp files with the shell command:
make
If you are running Org from the distribution directory, this is all. If you want to install into the system directories, use
make install
make install-info
Then add to .emacs:
;; This line only if Org is not part of the X/Emacs distribution.
(require 'org-install)
Add the following lines to your .emacs file. The last three lines define global keys for the commands org-store-link, org-agenda, and org-iswitchb - please choose suitable keys yourself.
;; The following lines are always needed. Choose your own keys.
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)
Furthermore, you must activate font-lock-mode in Org
buffers, because significant functionality depends on font-locking being
active. You can do this with either one of the following two lines
(XEmacs user must use the second option):
(global-font-lock-mode 1) ; for all buffers
(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only
With this setup, all files with extension `.org' will be put into Org mode. As an alternative, make the first line of a file look like this:
MY PROJECTS -*- mode: org; -*-
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.
If you find problems with Org, or if you have questions, remarks, or ideas
about it, please mail to the Org mailing list emacs-orgmode@gnu.org.
If you are not a member of the mailing list, your mail will be reviewed by a
moderator and then passed through to the list.
For bug reports, please provide as much information as possible, including the version information of Emacs (C-h v emacs-version <RET>) and Org (C-h v org-version <RET>), as well as the Org related setup in .emacs. If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information about:
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:
emacs -l /path/to/org.el
Options menu and select Enter Debugger on Error
(XEmacs has this option in the Troubleshooting sub-menu).
Org uses three types of keywords: TODO keywords, tags, and property names. In this manual we use the following conventions:
TODOWAITINGbossARCHIVEReleasePRIORITYOrg is based on outline mode and provides flexible commands to edit the structure of the document.
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 org-cycle, which is bound to the <TAB> key.
Headlines define the structure of an outline tree. The headlines in Org start with one or more stars, on the left margin1. For example:
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. Clean view describes a setup to realize this.
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.
Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to <TAB> and S-<TAB> to change the visibility in the buffer.
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
The cursor must be on a headline for this to work2. When the cursor is at the beginning of the buffer and the first line is not a headline, then <TAB> actually runs global cycling (see below)3. Also when called with a prefix argument (C-u <TAB>), global cycling is invoked.
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
When 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, S-<TAB> jumps to the previous field.
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:
#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
Forthermore, any entries with a `VISIBILITY' property (see Properties and Columns) will get their visibility adapted accordingly. Allowed values
for this property are folded, children, content, and
all.
The following commands jump to other headlines in the buffer.
<TAB> Cycle visibility.
<down> / <up> Next/previous visible headline.
<RET> Select this location.
/ 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
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 C-c
C-x C-y. With the default settings, level adjustment will take place and
yanked trees 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 C-u C-y.
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.
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. Org mode knows two ways of archiving. You can mark a tree with the ARCHIVE tag, or you can move an entire (sub)tree to a different location.
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:
org-cycle-open-archived-trees. Also normal outline commands like
show-all will open archived subtrees.
org-sparse-tree-open-archived-trees.
org-agenda-skip-archived-trees, in which case these trees will always
be included. In the agenda you can press the v key to get archives
temporarily included.
org-export-with-archived-trees.
The following commands help managing the ARCHIVE tag:
Once an entire project is finished, you may want to move it to a different location. Org can move it to an Archive Sibling in the same tree, to a different tree in the current file, or to a different file, the archive file.
org-archive-location. Context information that could be
lost like the file name, the category, inherited tags, and the TODO
state will be store as properties in the entry.
The default archive location is a file in the same directory as the
current file, with the name derived by appending _archive to the
current file name. For information and examples on how to change this,
see the documentation string of the variable
org-archive-location. There is also an in-buffer option for
setting this variable, for example6:
#+ARCHIVE: %s_done::
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).
When a subtree is moved, it receives a number of special properties that
record context information like the file from where the entry came, it's
outline path the archiving time etc. Configure the variable
org-archive-save-context-info to adjust the amount of information
added.
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 it7. 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:
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:
(setq org-agenda-custom-commands
'(("f" occur-tree "FIXME")))
will define the key C-c a f as a shortcut for creating a sparse tree matching the string `FIXME'.
The other sparse tree commands select headings based on TODO keywords, tags, or properties and will be discussed later in this manual.
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 9.
Or you can use the command C-c C-e v to export only the visible
part of the document and print the resulting file.
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 the HTML exporter (see Exporting) parses and formats them.
Org knows ordered lists, unordered lists, and description lists.
Items belonging to the same list must have the same indentation on the first
line. In particular, if an ordered list reaches number `10.', then the
2–digit numbers must be written left-aligned with the other numbers in the
list. Indentation also determines the end of a list item. It ends before
the next line that is indented like the bullet/number, or less. Empty lines
are part of the previous item, so you can have several paragraphs in one
item. If you would like an empty line to terminate all currently open plain
lists, configure the variable org-empty-line-terminates-plain-lists.
Here is an example:
** Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyns 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, not individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays the Frodo
- Sean Austin :: He plays the Sam, Frodos friend. I still remember
him very well from his role as Mikey Walsh a in the Goonies.
Org supports these lists by tuning filling and wrapping commands to deal with them correctly11, and by exporting them properly (see Exporting).
The following commands act on items when the cursor is in the first line of an item (the line with the bullet or number).
org-cycle-include-plain-lists. 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.
If org-cycle-include-plain-lists has not been set, <TAB>
fixes the indentation of the current line in a heuristic way.
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-drawers13. Drawers
look like this:
** This is a headline
Still outside the drawer
:DRAWERNAME:
This is inside the drawer.
:END:
After the drawer.
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 <TAB> there. Org mode uses a drawer for storing properties (see Properties and Columns), and another one for storing clock times (see Clocking work time).
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. You can always toggle the mode with M-x orgstruct-mode. To turn it on by default, for example in Mail mode, use
(add-hook 'mail-mode-hook 'turn-on-orgstruct)
When this mode is active and the cursor is on a line that looks to Org like a headline of 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 shadow.
Org comes with a fast and intuitive table editor. Spreadsheet-like calculations are supported in connection with the Emacs calc package (see the Emacs Calculator manual for more information about the Emacs calculator).
Org makes it easy to format tables in plain ASCII. Any line with `|' as the first non-whitespace character is considered part of a table. `|' is also the column separator. A table might look like this:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
A table is re-aligned automatically each time you press <TAB> or <RET> or C-c C-c inside the table. <TAB> also moves to the next field (<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 `|-' 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
|Name|Phone|Age|
|-
and then press <TAB> to align the table and start filling in fields.
When typing text into a field, Org treats <DEL>,
<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 <TAB>, S-<TAB> or <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.
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 dispables the
increment. This key is also used by CUA mode (see Cooperation).
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.
If you don't like the automatic table editor because it gets in your way on lines which you would like to start with `|', you can turn it off with
(setq org-enable-table-editor nil)
Then the only table command that still works is C-c C-c to do a manual re-align.
The width of columns is automatically determined by the table editor. Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. To limit14 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. The next re-align will then set the width of this column to no more than this value.
|---+------------------------------| |---+--------|
| | | | | <6> |
| 1 | one | | 1 | one |
| 2 | two | ----\ | 2 | two |
| 3 | This is a long chunk of text | ----/ | 3 | This=> |
| 4 | four | | 4 | four |
|---+------------------------------| |---+--------|
Fields that are wider become clipped and end in the string `=>'. Note that the full text is still in the buffer, it is only invisible. 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 C-c ` (that is C-c followed by the backquote). This will open a new window with the full field. Edit it and finish with C-c C-c.
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:
#+STARTUP: align
#+STARTUP: noalign
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 `/'. The further fields can either contain `<' to indicate that this column should start a group, `>' to indicate the end of a column, or `<>' 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:
| | 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: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2)))
It is also sufficient to just insert the column group starters after every vertical line you'd like to have:
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|----+-----+-----+-----+---------+------------|
| / | < | | | < | |
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 M-x orgtbl-mode. To turn it on by default, for example in mail mode, use
(add-hook 'mail-mode-hook 'turn-on-orgtbl)
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 table editor makes use of the Emacs 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.
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 C-c ? in that field, or press C-c } to toggle the display of a grid.
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.
Org also uses another, more general operator that looks like this:
@row$column
Column references can be absolute like `1', `2',...`N', or relative to the current column like `+1' or `-2'.
The row specification only counts data lines and ignores horizontal separator lines (hlines). You can use absolute row numbers `1'...`N', and row numbers relative to the current row like `+3' or `-1'. Or specify the row relative to one of the hlines: `I' refers to the first hline15, `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. Relative row numbers like `-3' will not cross hlines if the current line is too close to the hline. Instead, the value directly at the hline is used.
`0' refers to the current row and column. 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:
@2$3 2nd row, 3rd column C2 same as previous $5 column 5 in the current row E& same as previous @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
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:
$1..$3 First three fields in the current row. $P..$Q Range, using column names (see under Advanced) @2$1..@4$3 6 fields between these two fields. A2..C4 Same as above. @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
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.
`$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
#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
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 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 kilometers16. Column names and parameters can be specified in special table lines. These are described below, see Advanced features. All names must start with a letter, and further consist of letters and numbers.
A formula can be any algebraic expression understood by the Emacs
Calc package. Note that calc has the
non-standard convention that `/' has lower precedence than
`*', so that `a/b*c' is interpreted as `a/(b*c)'. Before
evaluation by calc-eval (see calc-eval),
variable substitution takes place according to the rules described above.
The range vectors can be directly fed into the Calc vector functions
like `vmean' and `vsum'.
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 5) to keep tables
compact. The default settings can be configured using the variable
org-calc-default-modes.
p20 switch the internal precision to 20 digits n3 s3 e2 f4 normal, scientific, engineering, or fixed display format D R angle modes: degrees, radians F S fraction and symbolic modes N interpret all fields as numbers, use 0 for non-numbers T force text interpretation E keep empty fields in ranges
In addition, you may provide a printf format specifier to
reformat the final result. A few examples:
$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 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
if($1<20,teen,string("")) ``teen'' if age $1 less than 20, else empty
It is also possible to write a formula in Emacs Lisp; this can be useful
for string manipulation and control structures, if the 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
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 `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
`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. A few examples, note how the
`N' mode is used when we do computations in lisp.
Swap the first two characters of the content of column 1 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) Add columns 1 and 2, equivalent to the Calc's$1+$2'(+ $1 $2);N Compute the sum of columns 1-4, like Calc'svsum($1..$4)'(apply '+ '($1..$4));N
To assign a formula to a particular field, type it directly into the field, preceded by `:=', for example `:=$1+$2'. When you press <TAB> or <RET> or 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 replaced with the result.
Formulas are stored in a special line starting with `#+TBLFM:' directly below the table. If you typed the equation in the 4th field of the 3rd 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. Of cause this is not true 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
Often in a table, the same formula should be used for all fields in a particular column. Instead of having to copy the formula to all fields in that column, Org allows to assign a single formula to an entire column. If the table contains horizontal separator hlines, everything before the first such line is considered part of the table header and will not be modified by column formulas.
To assign a formula to a column, type it directly into any field in the column, preceded by an equal sign, like `=$1+$2'. When you press <TAB> or <RET> or 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 `=', the previously stored formula for this column is used. For each column, Org will only remember the most recently used formula. In the `TBLFM:' line, column formulas will look like `$4=$1+$2'.
Instead of typing an equation into the field, you may also use the following command:
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.
B3) and internal (like @3$2).
B3 and you press S-<right>, it will become C3.
This also works for relative references, and for hline references.
Making a table field blank does not remove the formula associated with the field, because that is stored in a different line (the `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 `#+TBLFM' line.
You may edit the `#+TBLFM' directly and re-apply the changed equations with C-c C-c in that line, or with the normal recalculation commands in the table.
When the evaluation of a formula leads to an error, the field content
becomes the string `#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 C-u C-u C-c = <RET> in a
field. Detailed information will be displayed.
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-automatically.
In order to recalculate a line of a table or the entire table, use the following commands: