@setfilename ../info/org
@settitle Org Mode Manual
-@set VERSION 3.11
+@set VERSION 3.12
@set DATE June 2005
@dircategory Emacs
Tables
* Built-in table editor:: Simple tables
-* table.el:: Complex tables
+* Table calculations:: Compute a field from other fields
* orgtbl-mode:: The table editor as minor mode
+* table.el:: Complex tables
+
+Calculations in tables
+
+* Formula syntax:: How to write a formula
+* Applying a formula:: How to get a formula executed
+* Recalculation:: Re-applying all formulas in a table
+* Summing:: Summing columns and rows
Hyperlinks
@example
@r{@bullet{} as an outline extension with visibility cycling and structure editing}
@r{@bullet{} as an ASCII system and table editor to take structured notes}
+@r{@bullet{} as an ASCII table editor with some spreadsheet-like capabilities}
@r{@bullet{} as a simple hypertext system, with HTML export}
@r{@bullet{} as a TODO list editor}
@r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
Show all.
@end table
-When Emacs firsts visits a Org-mode file, the global state is set to
+When Emacs first visits an Org-mode file, the global state is set to
OVERVIEW, i.e. only the top level headlines are visible. This can be
configured through the variable @code{org-startup-folded}, or on a
per-file basis by adding one of the following lines anywhere in the
@cindex promotion, of subtrees
@cindex demotion, of subtrees
@cindex subtree, cut and paste
-@cindex pasting, subtrees
-@cindex cutting, subtrees
-@cindex copying, subtrees
+@cindex pasting, of subtrees
+@cindex cutting, of subtrees
+@cindex copying, of subtrees
@table @kbd
@kindex M-@key{RET}
@section Archiving
@cindex archiving
-When an project represented by a (sub)tree is finished, you may want
-to move the tree to an Archive place, either in the same file under a
+When a project represented by a (sub)tree is finished, you may want
+to move the tree to an archive place, either in the same file under a
special top-level heading, or even to a different file.
@table @kbd
-@kindex @kbd{C-c $}
+@kindex C-c $
@item @kbd{C-c $}
Archive the subtree starting at the cursor position to the location
given by @code{org-archive-location}.
sparse tree means that the entire document is folded as much as
possible, but the selected information is made visible along with the
headline structure above it@footnote{See also the variable
-@code{org-show-following-heading}}. Just try it out and you will see
+@code{org-show-following-heading}.}. Just try it out and you will see
immediately how it works.
Org-mode contains several commands creating such trees. The most
@cindex visible text, printing
To print a sparse tree, you can use the Emacs command
@code{ps-print-buffer-with-faces} which does not print invisible parts
-of the document @footnote{this does not work under XEmacs, because
+of the document @footnote{This does not work under XEmacs, because
XEmacs uses selective display for outlining, not text properties}.
Or you can use the command @kbd{C-c C-x v} to copy the visible part of
the document to another file (extension @file{.txt}) which then can be
@chapter Tables
@cindex tables
-For taking notes, tables are an essential tool because they allow
-immediate and clear structuring of data. Org-mode has a very fast and
-intuitive table editor built-in. More complex tables can be created
-with the Emacs table.el package.
+Org-mode has a very fast and intuitive table editor built-in.
+Spreadsheet-like calculations are supported in connection with the
+Emacs @file{calc} package.
@menu
* Built-in table editor:: Simple tables
-* table.el:: Complex tables
+* Table calculations:: Compute a field from other fields
* orgtbl-mode:: The table editor as minor mode
+* table.el:: Complex tables
@end menu
-@node Built-in table editor, table.el, Tables, Tables
+@node Built-in table editor, Table calculations, Tables, Tables
@section The built-in table editor
@cindex table editor, builtin
@end example
A table is re-aligned automatically each time you press @key{TAB} or
-@key{RET} 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
+@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
@example
|Name|Phone|Age
@table @kbd
@tsubheading{Creation and conversion}
-@kindex C-c C-c
-@item C-c C-c
-Recognize @file{table.el} table. Works when the cursor is in a
-table.el table
+@item M-x org-table-create
+Creates an empty Org-mode table. However, it is much easier to just
+start typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}
@kindex C-c C-c
@item C-c C-c
can use a prefix argument to indicate how many consecutive spaces are
at least required to indicate a field separator (default: just one).
-@item M-x org-table-create
-Creates an empty Org-mode table. However, it is much easier to just
-start typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}
-
@tsubheading{Re-aligning and field motion}
@kindex C-c C-c
@item C-c C-c
@kindex S-@key{TAB}
@item S-@key{TAB}
-Move to previous field.
+Re-align, move to previous field.
@kindex @key{RET}
@item @key{RET}
@kindex C-c -
@item C-c -
-Insert a horizontal line below current row. With prefix arg, line is
-created above the current line.
+Insert a horizontal line below current row. With prefix arg, the line
+is created above the current line.
@tsubheading{Regions}
@kindex C-c C-h M-w
@item C-c C-h M-w
-Copy an rectangular region from a table to a special clipboard. Point
+Copy a rectangular region from a table to a special clipboard. Point
and mark determine edge fields of the rectangle. The process ignores
horizontal separator lines.
@kindex C-c C-h C-w
@item C-c C-h C-w
-Copy an rectangular region from a table to a special clipboard, and
-blank all fields in the rectangle.
+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-h C-y
@item C-c C-h C-y
Paste a rectangular region into a table.
above.
@tsubheading{Calculations}
+@cindex formula, in tables
+@cindex calculations, in tables
+@kindex C-c =
+@item C-c =
+Replace current field with the result of a formula. When called with a
+@kbd{C-u} prefix, apply the equation in the current field and down
+through the current column to a horizonal separator line or the end of
+the table. For details, see @ref{Table calculations}.
+
+@kindex C-c *
+@item C-c *
+Recalculate the current row by applying the stored formulas from left
+to right. When called with a @kbd{C-u} prefix, recalculate the
+entire table, starting with the first non-header line (i.e. below the
+first horizontal separator line). For details, see @ref{Table calculations}.
+
+@kindex C-#
+@item C-#
+Rotate the recalculation mark in first column through the states
+@samp{}, @samp{#}, @samp{*}, @samp{!}, @samp{$}. For the meaning of
+these marks see @ref{Table calculations}. When there is an active
+region, change all marks in the region.
+
@kindex C-c ?
@item C-c ?
Which table column is the cursor in? Displays number >0 in echo
@kindex C-c +
@item C-c +
Sum the numbers in the current column, or in the rectangle defined by
-the active region. The result is displayed in the echo area and can
+the active region. The result is shown in the echo area and can
be inserted with @kbd{C-y}.
@kindex S-@key{RET}
incremented during copy. This key is also used by CUA-mode
(@pxref{Interaction}).
-@cindex formula, in tables
-@cindex calculations, in tables
-@kindex C-c =
-@item C-c =
-Replace current field with the result of a formula. Requires the
-Emacs calc package. The formula can access the current field with
-@samp{$}, and the other fields in the current row
-with @samp{$1}, @samp{$2},... For details see the documentation of the
-command @command{org-table-eval-formula}.
-
@tsubheading{Miscellaneous}
@kindex C-c |
@item C-c |
Toggle the visibility of vertical lines in tables. The lines are
still there, only made invisible with a text property. Any @samp{|}
added by hand will become invisible on the next align.
-Typographically it is good style to have no vertical lines in tables.
@item M-x org-table-import
Import a file as a table. The table should be TAB- or whitespace
@noindent The only table command which then still works is
@kbd{C-c C-c} to do a manual re-align.
-@node table.el, orgtbl-mode, Built-in table editor, Tables
+@node Table calculations, orgtbl-mode, Built-in table editor, Tables
+@section Calculations in tables
+@cindex calculations, in tables
+
+While the Org-mode table editor misses many features of a full
+spreadsheet, it nevertheless has very useful capabilities to compute
+fields. In horizontal direction, it can use complex expressions to
+compute a field from other fields @emph{in the same row}, using named
+columns, constants and parameters. The Emacs @file{calc} package is
+required for this feature to work. In vertical direction, only
+summing is supported.
+
+@menu
+* Formula syntax:: How to write a formula
+* Applying a formula:: How to get a formula executed
+* Recalculation:: Re-applying all formulas in a table
+* Summing:: Summing columns and rows
+@end menu
+
+@node Formula syntax, Applying a formula, Table calculations, Table calculations
+@subsection Formula syntax
+
+A formula for horizontal computations can be any algebraic expression
+understood by the Emacs @file{calc} package. Before evaluation,
+variable substitution takes place: @samp{$} is replaced by the field
+the cursor is currently in, and $1..$n reference the fields in the
+current row. @samp{$name} is interpreted as the name of a column,
+parameter or constant. Constants are defined globally through the
+variable @code{org-table-formula-constants}. If you have the
+@file{constants.el} package, it will also be used to resolve
+constants, including natural constants like @samp{$k} for Plancks
+constant, units like @samp{$km} for kilometers. Column names and
+parameters can be specified in special table lines. These are
+described below, see @ref{Recalculation}.
+
+A formula can contain an optional mode string after a semicolon. This
+string consists of flags to influence calc's modes@footnote{By
+default, Org-mode uses the standard calc modes (precision 12, angular
+units degrees, fraction and symbolic modes off). However, the display
+format which has been changed to @code{(float 5)} to keep tables
+compact. The default settings can be configured using the variable
+@code{org-calc-default-modes}.} during execution, e.g. @samp{p20} to
+switch the internal precision to 20 digits, @samp{n3}, @samp{s3},
+@samp{e2} or @samp{f4} to switch to normal, scientific, engineering,
+or fix display format, respectively, and @samp{D}, @samp{R}, @samp{F},
+and @samp{S} to turn on degrees, radians, fraction and symbolic modes,
+respectively. In addition, you may provide a @code{printf} specifier
+to reformat the final result. A few examples:
+@example
+ $1+$2 @r{Sum of first and second field}
+ $1+$2;%.2f @r{Same, format result to two decimals}
+ exp($2)+exp($1) @r{Math functions can be used}
+ $;%.1f @r{Reformat current cell to 1 decimal}
+ ($3-32)*5/9 @r{degrees F -> C conversion}
+ $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
+ tan($1);Dp3s1 @r{compute in degrees, precision 3, display SCI 1}
+ vmean($2..$7) @r{compute column range mean, using vector function}
+ taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
+@end example
+
+@node Applying a formula, Recalculation, Formula syntax, Table calculations
+@subsection Applying a formula
+
+To apply a formula to a field, type it directly into the field,
+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 evaluated and replaced with the result. If
+the field contains only @samp{=}, the formula most recently applied
+anywhere in the @emph{same column} will be used.
+
+For each column, Org-mode will remember the most recently used
+formula. The information is stored in a special line directly below
+the table. When adding/deleting/moving columns with the appropriate
+commands, the stored equations will be modified accordingly. When a
+column used in a calculation is removed, references to this column
+become invalid and will cause an error upon applying the equation.
+
+Instead of typing an equation into the field, you may also use the
+command @kbd{C-c =}. It prompts for a formula (with default taken
+from the @samp{#+TBLFM:} line) and applies it to the current field.
+If you use a prefix argument (i.e. @kbd{C-u C-c =}), the formula will
+be applied to the current field and down to the next separator line
+or the end of the table. A numerical prefix will apply it to that
+many fields in the current column.
+
+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 menu and repeat the calculation
+by pressing, for example by pressing @kbd{C-c = @key{RET}} in a field.
+Detailed information will be displayed.
+
+@node Recalculation, Summing, Applying a formula, Table calculations
+@subsection Recalculation
+
+To recompute all the fields in a line, use the command @kbd{C-c *}.
+It re-applies all stored equations to the current row, from left to
+right. With a @kbd{C-u} prefix, this will be done to every line in
+the table, so use this command it you want to make sure the entire
+table is up-to-date. A more automatic way of recalculating the
+current line requires marking the line: If the first column of a row
+contains only @samp{#}, the row will be re-computed with every
+@key{TAB}, @key{RET}, and @kbd{C-c C-c} in this row. Here is an
+example of a table that collects exam results of students, with some
+rows activated for semi-automatic computations.
+
+@example
+@group
+|---+---------+--------+--------+--------+-------+------|
+| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
+|---+---------+--------+--------+--------+-------+------|
+| ! | | P1 | P2 | P3 | Tot | |
+| # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
+|---+---------+--------+--------+--------+-------+------|
+| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
+| # | Sara | 7 | 14 | 19 | 40 | 8.0 |
+| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
+|---+---------+--------+--------+--------+-------+------|
+| $ | max=50 | | | | | |
+|---+---------+--------+--------+--------+-------+------|
+#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f
+@end group
+@end example
+@noindent
+The example also demonstrates a number of convenience features:
+@enumerate
+@item
+If the first field of a row contains only @samp{!}, this row defines
+@emph{names} for the different columns so that you can write
+@samp{$Tot} instead of @samp{$6} --- useful in larger tables,
+when counting columns becomes error prone.
+@item
+If the first field of a row contains only @samp{$}, fields in this row
+can define @emph{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.
+Changing a parameter and then recalculating the table can be useful
+and fun.
+@item
+A column range @samp{$P1..$P3} is expanded to a vector, so that calc's
+vector functions (in this case @samp{vsum}, but there are many more)
+can be applied to ranges. For a range, columns may be referenced by
+name or number, in either sequence.
+@end enumerate
+
+@noindent If a table contains any line with @samp{#} as the
+first field, @kbd{C-u C-c *} will only change the marked lines and
+leave all unmarked lines alone. You can also mark a line with
+@samp{*}. These lines will also be recalculated with @kbd{C-u C-c *},
+but not upon @key{TAB} and @key{RET}. Use this for lines which are
+slow to calculate.
+
+Just to wet your appetite on what can be done with the fantastic
+@file{calc} package, here is a table that computes the Taylor series
+for a couple of functions (homework: try that with Excel :-)
+
+@example
+@group
+|---+-------------+---+-----+--------------------------------------|
+| | 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 group
+@end example
+
+@node Summing, , Recalculation, Table calculations
+@subsection Summing
+
+Finally, when typing a formula into a field, a number of special
+keywords execute predefined sums over the current row or column and
+enter the result into the current field. These calculations are
+one-off, the formula is not stored, and you will neet to re-enter it
+in order to compute again.
+
+@example
+= @r{Execute the stored formula valid in this column.}
+=sum @r{Sum all fields above the current (alias @code{=sumv}).}
+=sumh @r{Sum all fields to the left of the current field.}
+=sum3 @r{Same as @samp{=sum}, but use just 3 fields above current.}
+@end example
+
+@node orgtbl-mode, table.el, Table calculations, Tables
+@section The Orgtbl minor mode
+@cindex orgtbl-mode
+@cindex minor mode for tables
+
+If you like the intuitive way the Org-mode table editor works, you
+might want to use it also 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 mail mode, use
+@lisp
+(add-hook 'mail-mode-hook 'turn-on-orgtbl)
+@end lisp
+
+@node table.el, , orgtbl-mode, Tables
@section The @file{table.el} package
@kindex C-c C-c
-@cindex table editor, table.el
+@cindex table editor, @file{table.el}
@cindex @file{table.el}
-More complex ASCII tables (with automatic line wrapping, column- and
-row-spanning, and alignment) can be created using the Emacs table
+Complex ASCII tables with automatic line wrapping, column- and
+row-spanning, and alignment can be created using the Emacs table
package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}).
When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
will call @command{table-recognize-table} and move the cursor into the
table. Inside a table, the keymap of Org-mode is inactive. In order
-to execute org-related commands, leave the table.
+to execute Org-mode-related commands, leave the table.
@table @kbd
-@kindex C-c #
-@item C-c #
+@kindex C-c C-c
+@item C-c C-c
+Recognize @file{table.el} table. Works when the cursor is in a
+table.el table.
+
+@kindex C-c ~
+@item C-c ~
Insert a table.el table. If there is already a table at point, this
command converts it between the table.el format and the Org-mode
format. See the documentation string of the command
possible.
@end table
-@node orgtbl-mode, , table.el, Tables
-@section The Orgtbl minor mode
-@cindex orgtbl-mode
-@cindex Minor mode for tables
-
-If you like the intuitive way the Org-mode table editor works, you
-might want to use it also 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 mail mode, use
-@lisp
-(add-hook 'mail-mode-hook 'turn-on-orgtbl)
-@end lisp
-
@node Hyperlinks, TODO items, Tables, Top
@chapter Hyperlinks
@cindex hyperlinks
@cindex links
@cindex GNUS links
@cindex BBDB links
+@cindex URL links
+@cindex file links
@cindex VM links
@cindex RMAIL links
@cindex WANDERLUST links
@ref{Installation and Activation}.
@kindex C-c C-l
+@cindex completion, of links
+@cindex completion, of file names
@item C-c C-l
Insert a link. This prompts for a link to be inserted into the
buffer. You can just type a link, using one of the link type prefixes
text has a headline, i.e. a first line that starts with a @samp{*}.
If not, a headline is constructed from the current date and some
additional data. If the variable @code{org-adapt-indentation} is
-non-@code{nil}, the entire text is also indented so that it starts in
-the same column as the headline (after the asterisks).
+non-nil, the entire text is also indented so that it starts in the
+same column as the headline (after the asterisks).
@node TODO items, Timestamps, Hyperlinks, Top
@chapter TODO items
org-todo-interpretation 'sequence)
@end lisp
+@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 too DONE. You may also
use a prefix argument to quickly select a specific state. For example
In this case, different keywords do not indicate a sequence, but
rather different types. So it is normally not useful to change from
-one type to another. Therefore, in this case the the behavior of the
+one type to another. Therefore, in this case the behavior of the
command @kbd{C-c C-t} is changed slightly@footnote{This is also true
-for the @kbd{t} command in the timeline and agenda buffers}. When
+for the @kbd{t} command in the timeline and agenda buffers.}. When
used several times in succession, it will still cycle through all
names. But when when you return to the item after some time and
execute @kbd{C-c C-t} again, it will switch from each name directly to
#+TYP_TODO: Fred Sara Lucy Mike DONE
@end example
-@cindex Completing option keywords
+@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 @kbd{M-@key{TAB}} completion.
@itemx S-@key{down}
Increase/decrease priority of current item. Note that these keys are
also used to modify time stamps (@pxref{Creating timestamps}).
-Furthermore, these keys is also used by CUA-mode
+Furthermore, these keys are also used by CUA-mode
(@pxref{Interaction}).
@end table
@end example
@item DEADLINE
-@cindex deadline
+@cindex DEADLINE keyword
If a time stamp is preceded by the word @samp{DEADLINE:}, the task
(most likely a TODO item) is supposed to be finished on that date, and
-it will be listed then. In addition, the compilation for the
-@emph{current day} will carry a warning about the approaching or
-missed deadline, starting @code{org-deadline-warning-days} before the
-due date, and continuing until the entry is marked DONE. An example:
+it will be listed then. In addition, the compilation for @emph{today}
+will carry a warning about the approaching or missed deadline,
+starting @code{org-deadline-warning-days} before the due date, and
+continuing until the entry is marked DONE. An example:
@example
*** TODO write article about the Earth for the Guide
- The editor in charge is bbdb:Ford Prefect
+ The editor in charge is <bbdb:Ford Prefect>
DEADLINE: <2004-02-29 Sun>
@end example
@item SCHEDULED
-@cindex scheduled
+@cindex DEADLINE keyword
If a time stamp is preceded by the word @samp{SCHEDULED:}, it means
you are planning to start working on that task on the given date. The
headline will be listed under the given date. In addition, a reminder
that the scheduled date has passed will be present in the compilation
-for the @emph{current day}, until the entry is marked DONE. I.e., the
+for the @emph{today}, until the entry is marked DONE. I.e., the
task will automatically be forwarded.
@end table
Change the item under the cursor in a timestamp. The cursor can be on
a year, month, day, hour or minute. Note that if the cursor is not at
a time stamp, these same keys modify the priority of an item.
-(@pxref{Priorities}). These key bindings conflict with CUA-mode
+(@pxref{Priorities}). The key bindings also conflict with CUA-mode
(@pxref{Interaction}).
@cindex date, reading in minibuffer
@cindex time, reading in minibuffer
@cindex calendar, for selecting date
-When org prompts for a date/time, the function reading your input will
-replace anything you choose not to specify with the current date and
-time. For details, see the documentation string of
+When Org-mode prompts for a date/time, the function reading your input
+will replace anything you choose not to specify with the current date
+and time. For details, see the documentation string of
@command{org-read-date}. Also, a calender will pop up to allow
selecting a date. The calendar can be fully controlled from the
minibuffer, and a date can be selected with the following commands:
The display in the agenda buffer looks best if the category is not
longer than 10 characters.
-@subsection Time Specifications
+@subsection Time-of-Day Specifications
-Org-mode checks each agenda item for a time specification. The time
-can be part of the time stamp that triggered inclusion into the agenda,
-for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ranges can
-be specified with two time stamps, like
+Org-mode checks each agenda item for a timeof-day specification. The
+time can be part of the time stamp that triggered inclusion into the
+agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
+ranges can be specified with two time stamps, like
@c
@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
@kindex w
@item w
-Toggle between weekly and daily view.
+Switch to weekly view (7 days displayed together)
@kindex d
@item d
+Switch to daily view (just one day displayed)
+
+@kindex D
+@item D
Toggle the inclusion of diary entries. See @ref{Calendar/Diary integration}.
@kindex g
@kindex +
@kindex S-@key{up}
@item +
-@item S-@key{up}
+@itemx S-@key{up}
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.
@kindex -
@kindex S-@key{down}
@item -
-@item S-@key{down}
+@itemx S-@key{down}
Decrease the priority of the current item.
@kindex S-@key{right}
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. Also 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.
+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.
@node Agenda to diary, , Diary to agenda, Calendar/Diary integration
@subsection Including the agenda into the diary
@node Exporting, Miscellaneous, Timeline and Agenda, Top
@chapter Exporting
@cindex exporting
-@cindex ASCII file
-@cindex HTML
-
+@cindex ASCII export
+@cindex HTML export
@cindex headline levels, for exporting
For printing and sharing of notes, an Org-mode document can be
@item
Simple @TeX{}-like math constructs are interpreted:
+@cindex completion, of @TeX{} symbols
@itemize @minus
@item
@samp{10^22} and @samp{J_n} are super- and subscripts. You can quote
@section Export options
@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
@cindex headline levels
@cindex section-numbers
@cindex table of contents
-@cindex linebreak-preservation
+@cindex linebreak preservation
@cindex quoted html tags
@cindex fixed-width sections
@cindex tables
@node Completion, Customization, Miscellaneous, Miscellaneous
@section Completion
-@cindex complete @TeX{} symbols
-@cindex complete TODO keywords
-@cindex complete dictionary words
-@cindex complete option keywords
+@cindex completion, of @TeX{} symbols
+@cindex completion, of TODO keywords
+@cindex completion, of dictionary words
+@cindex completion, of option keywords
+@cindex completion, of keyword formulas
Org-mode supports in-buffer completion. This type of completion does
not make use of the minibuffer. You simply type a few letters into
option keyword is already complete, pressing @kbd{M-@key{TAB}} again
will insert example settings for this keyword.
@item
+After @samp{=}, complete keyword formulas for tables.
+@item
Elsewhere, complete dictionary words using ispell.
@end itemize
@end table
@section Frequently asked questions
@enumerate
-@item @b{Org-mode seems to be useful default mode for the various
+@item @b{Org-mode seems to be auseful default mode for the various
@file{README} files I have scattered through my directories. How do I
turn it on for all @file{README} files?}
@example
@item @b{Is there an easy way to insert links to web locations?}@*
@cindex URL, paste into buffer
-Sure, just paste them into the buffer. A plain-text URL-like string
-is directly interpreted as a link.
+Sure, just type or paste them into the buffer. A plain-text URL-like
+string is directly interpreted as a link.
@item @b{When I export my TODO list, every TODO item becomes a
separate section. How do I enforce these items to be exported as an
@code{org-table-default-size}. However, just starting to type the
first line is usually much easier.
+@item @b{One of my table columns has started to fill up with
+@samp{#ERROR}. What is going on?}@*
+Org-mode tried to compute the column from other fields using a
+formula stored in the @samp{#+TBLFMT:} line just below the table, and
+the evaluation of the formula fails. Fix the fields used in the
+formula, or fix the formula, or remove it!
+
@item @b{When I am in the last column of a table and just above a
horizontal line in the table, pressing TAB creates a new table line
@i{before} the horizontal line. How can I quickly move to the line
@node Interaction, Bugs, FAQ, Miscellaneous
@section Interaction with other packages
@cindex packages, interaction with other
-@cindex @file{planner.el}
-@cindex @file{remember.el}
-@cindex @file{table.el}
-@file{Org.el} can cooperate with the following packages:
+Org-mode can cooperate with the following packages:
@table @asis
-@cindex @file{remember.el}
-@item @file{remember.el} by John Wiegley
-Org mode cooperates with remember, see @ref{Remember}.
-@cindex @file{plannner.el}
-@item @file{planner.el} by John Wiegley
-Planner is another tool to plan work and keep track of tasks. Planner
-uses a multi-file approach with project pages and day pages. Is based
-on Emacs-Wiki. It can be useful to display the agenda entries
-resulting from org files in day-pages of the planner. This can be
-done through the diary of the calendar: Integrate org files into the
-diary as described above, and then turn on the diary support of
-planner.
@cindex @file{table.el}
@item @file{table.el} by Takaaki Ota
Org mode cooperates with table.el, see @ref{table.el}.
+@cindex @file{calc.el}
+@item @file{calc.el} by Dave Gillespie
+Org-mode uses the calc package for implementing spreadsheet
+functionality in its tables (@pxref{Table calculations}). Org-modes
+checks for the availability of calc by looking for the function
+@code{calc-eval} which should be autoloaded in your 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. @xref{Embedded Mode,
+, Embedded Mode, calc, The calc maanual}.
+@cindex @file{constants.el}
+@item @file{constants.el} by Carsten Dominik
+In a table formula (@pxref{Table calculations}), it is possible to use
+names for natural constants or units. Instead of defining you own
+constants in the variable @code{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 @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
+the function @code{constants-get}, which has to be autoloaded in your
+setup. See the installation instructions in the file
+@file{constants.el}.
+@cindex @file{remember.el}
@cindex @file{CUA.el}
@item @file{CUA.el} by Kim. F. Storm
Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
used by CUA-mode (as well as pc-select-mode and s-region-mode) to
select and extend the region. If you want to use one of these
packages along with Org-mode, configure the variable
-@code{org-CUA-compatible}. When set, Org-mode will move the folowing
+@code{org-CUA-compatible}. When set, Org-mode will move the following
keybindings in org-mode files, and in the agenda buffer (but not
during date selection).
@example
Yes, these are unfortunately more difficult to remember. If you want
to have other replacement keys, look at the variable
@code{org-disputed-keys}.
-
+@item @file{remember.el} by John Wiegley
+Org mode cooperates with remember, see @ref{Remember}.
+@cindex @file{planner.el}
+@item @file{planner.el} by John Wiegley
+Planner is another tool to plan work and keep track of tasks. Planner
+uses a multi-file approach with project pages and day pages. Is based
+on Emacs-Wiki. If Planner is your primary tool, it can be useful to
+display the agenda entries resulting from org files in day-pages of
+the planner. This can be done through the diary of the calendar:
+Integrate org files into the diary as described above, and then turn
+on the diary support of planner.
@end table
@node Bugs, Acknowledgments, Interaction, Miscellaneous
@item
If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a table, the
filling is correctly disabled. However, if some text directly
-(without an empty line in between) preceeds or follws a table, calling
+(without an empty line in between) preceeds or follows a table, calling
@code{fill-paragraph} in that text will also fill the table like
normal text. Also, @code{fill-region} does bypass the
@code{fill-paragraph} code and will fill tables like normal text.
(for example because the application does not exits or refuses to open
the file), it does so silently. No error message is displayed.
@item
+Recalculating a table line applies the formulas from left to right.
+If a formula calculated fields further doen the row, multiple
+recalculation may be needed to get all fields consistent.
+@item
Under XEmacs, if Org-mode entries are included into the diary, it is
not possible to jump back from the diary to the org file. Apparently,
the text properties are lost when the fancy-diary-display is used.
@itemize @bullet
@item
-Matthias Rempe (Oelde) provided ideas and suggestions, a patch
-introducing Windows NT/2000 support, and quality control.
+Matthias Rempe (Oelde) provided ideas, a patch introducing Windows
+NT/2000 support, and quality control.
@item
Kevin Rogers contributed code to access VM files on remote hosts.
@item
Philip Rooke created the Org-mode reference card. He also helped with
beta testing and contributed a number of very useful ideas.
@item
-Christian Schlauer proposed angular brackets around links, and some
+Christian Schlauer proposed angular brackets around links, among other
+things.
other useful stuff.
@item
David Wainberg suggested to implement an archiving mechanism.