+@node Table calculations, orgtbl-mode, Built-in table editor, Tables
+@section Calculations in tables
+@cindex calculations, in tables
+
+The table editor makes use of the Emacs @file{calc} package to
+implement spreadsheet-like capabilities. Org-mode has two levels of
+complexity for table calculations. On the basic level, tables do only
+horizontal computations, so a field can be computed from other fields
+@emph{in the same row}, and Org-mode assumes that there is only one
+formula for each column. This is very efficient to work with and
+enough for many tasks. On the complex level, columns and individual
+fields can be named for easier referencing in formulas, individual
+named fields can have their own formula associated with them, and
+recalculation can be automated.
+
+@menu
+* Formula syntax:: How to write a formula
+* Column formulas:: Formulas valid for all fields in a column
+* Advanced features:: Field names, parameters and automatic recalc
+* Named-field formulas:: Formulas valid in single fields
+* Editing/debugging formulas:: Changing a stored formula
+* Appetizer:: Taste the power of calc
+@end menu
+
+@node Formula syntax, Column formulas, Table calculations, Table calculations
+@subsection Formula syntax
+
+A formula can be any algebraic expression understood by the Emacs
+@file{calc} package. Before evaluation by @code{calc-eval}
+(@pxref{Calling Calc from Your Lisp Programs,calc-eval,Calling calc
+from Your Lisp Programs,calc,GNU Emacs Calc Manual}), variable
+substitution takes place:
+
+@example
+ $ @r{refers to the current field}
+ $3 @r{refers to the field in column 3 of the current row}
+ $3..$7 @r{a vector of the fields in columns 3-7 of current row}
+ $P1..$P3 @r{vector of column range, using column names}
+ &2 @r{second data field above the current, in same column}
+ &5-2 @r{vector from fifth to second field above current}
+ &III-II @r{vector of fields between 2nd and 3rd hline above}
+ &III @r{vector of fields between third hline above and current field}
+ $name @r{a named field, parameter or constant}
+@end example
+
+The range vectors can be directly fed into the calc vector functions
+like functions @samp{vmean} and @samp{vsum}.
+
+@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 Planck's
+constant, units like @samp{$km} for kilometers. Column names and
+parameters can be specified in special table lines. These are
+described below, see @ref{Advanced features}.
+
+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 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} format
+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}
+ sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
+ vmean($2..$7) @r{Compute column range mean, using vector function}
+ vsum(&III) @r{Sum numbers from 3rd hline above to here}
+ taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
+@end example
+
+@node Column formulas, Advanced features, Formula syntax, Table calculations
+@subsection Column formulas
+
+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 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-mode will remember the most recently used
+formula. The information is stored in a special line starting with
+@samp{#+TBLFM} 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. A
+numerical prefix (e.g. @kbd{C-5 C-c =}) will apply it to that many
+subsequent fields in the current column.
+
+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. @kbd{C-u C-c C-c} is another way to update the
+entire table. Global updating does not touch the line(s) above the
+first horizontal separator line, assuming that this is the table
+header.
+
+@node Advanced features, Named-field formulas, Column formulas, Table calculations
+@subsection Advanced features
+
+If you want want the recalculation of fields to happen automatically,
+or if you want to be able to assign a formula to an individual field
+(instead of an entire column) you need to reserve the first column of
+the table for special marking characters. Here is an example of a
+table that collects exam results of students and makes use of these
+features:
+@example
+@group
+|---+---------+--------+--------+--------+-------+------|
+| | 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 |
+| # | Sara | 6 | 14 | 19 | 39 | 7.8 |
+| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
+|---+---------+--------+--------+--------+-------+------|
+| | Average | | | | 29.7 | |
+| ^ | | | | | at | |
+| $ | max=50 | | | | | |
+|---+---------+--------+--------+--------+-------+------|
+#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f
+@end group
+@end example
+
+@noindent @b{Important}: Please note that for these special tables,
+recalculating the table with @kbd{C-u C-c *} does only affect rows
+which are marked @samp{#} or @samp{*}, and named fields. The column
+formulas are not applied in rows with empty first field.
+
+The marking characters have the following meaning:
+@table @samp
+@item !
+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}.
+@item ^
+This row define 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, named fields can have their own formula
+associated with them.
+@item _
+Similar to @samp{^}, but defines names for the fields in the row
+@emph{below}.
+@item $
+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.
+@item #
+Fields in this row are automatically recalculated when pressing
+@key{TAB} or @key{RET} or @kbd{S-@key{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.
+@item *
+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.
+@item
+Unmarked lines are exempted from recalculation with @kbd{C-u C-c *}.
+All lines that should be recalculated should be marked with @samp{#}
+or @samp{*}.
+@end table
+
+@node Named-field formulas, Editing/debugging formulas, Advanced features, Table calculations
+@subsection Named-field formulas
+
+A named field can have its own formula associated with it. In the
+example above, this is used for the @samp{at} field that contains
+the average result of the students. To enter a formula for a named
+field, just type it onto the buffer, preceded by @samp{:=}. Or use
+@kbd{C-u C-c =}. This equation will be stored below the table like
+@samp{$name=...}. Any recalculation in the table (even if only
+requested for the current line) will also update all named field
+formulas.
+
+@node Editing/debugging formulas, Appetizer, Named-field formulas, Table calculations
+@subsection Editing and debugging formulas
+
+To edit a column or field formula, you can use the commands @kbd{C-c
+=} and @kbd{C-u C-c =}, respectively. The currently active expression
+is then presented as default in the minibuffer, were it may be edited.
+
+Note that making a table field blank does not remove the formula
+associated with the field - 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.
+
+@kindex C-c '
+@kindex C-c C-c
+@kindex C-c C-q
+@kindex C-c ?
+In particular for large tables with many formulas, it is convenient to
+use the command @kbd{C-c '} to edit the formulas of the current table
+in a separate buffer. That buffer will show the formulas one per
+line, and you are free to edit, add and remove formulas. Press
+@kbd{C-c ?} on a @samp{$...} expression to get information about its
+interpretation. Exiting the buffer with @kbd{C-c C-c} only stores the
+modified formulas below the table. Exiting with @kbd{C-u C-c C-c}
+also applies them to the entire table. @kbd{C-c C-q} exits without
+installing the changes.
+
+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 Appetizer, , Editing/debugging formulas, Table calculations
+@subsection Appetizer
+
+Finally, 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 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