diff options
| author | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:33:41 +0100 |
|---|---|---|
| committer | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:33:41 +0100 |
| commit | 82bb96f8a947ddfaf9d0311688836d9f79831f4d (patch) | |
| tree | 904e643980cc85ea72861d994a305e2a7c6605b3 | |
| parent | 38745a43c93d4593e803a068f39393e40bbd7cff (diff) | |
| download | org-mode-82bb96f8a947ddfaf9d0311688836d9f79831f4d.tar.gz | |
Release 4.62release_4.62
| -rw-r--r-- | Makefile | 9 | ||||
| -rw-r--r-- | org | 1175 | ||||
| -rw-r--r-- | org.el | 1251 | ||||
| -rw-r--r-- | org.pdf | bin | 656620 -> 666884 bytes | |||
| -rw-r--r-- | org.texi | 722 | ||||
| -rw-r--r-- | orgcard.pdf | bin | 59705 -> 59695 bytes | |||
| -rw-r--r-- | orgcard.tex | 14 |
7 files changed, 1920 insertions, 1251 deletions
@@ -42,7 +42,6 @@ MKDIR = mkdir -p MAKEINFO = makeinfo # How to create the HTML file -#TEXI2HTML = ./texi2html -monolithic -number TEXI2HTML = makeinfo --html --number-sections --no-split # How to move the byte compiled files to their destination. @@ -58,6 +57,7 @@ CP = cp -p # The following variables need to be defined by the maintainer LISPFILES = org.el org-publish.el org-mouse.el org-install.el ELCFILES = $(LISPFILES:.el=.elc) +DOCFILES = org.texi org.pdf org orgcard.tex orgcard.pdf TEXIFILES = org.texi INFOFILES = org HTMLDIR = /home/dominik/public_html/Tools/org @@ -65,7 +65,8 @@ HTMLDIR = /home/dominik/public_html/Tools/org .SUFFIXES: .el .elc .texi SHELL = /bin/sh -DISTFILES= README xemacs ${LISPFILES} org.texi org.pdf org orgcard.tex orgcard.pdf Makefile +DISTFILES= README ${LISPFILES} ${DOCFILES} Makefile +DISTFILES_xemacs= xemacs/noutline.el xemacs/ps-print-invisible.el xemacs/README all: $(ELCFILES) @@ -134,7 +135,9 @@ distfile: make doc rm -rf org-$(TAG) org-$(TAG).zip $(MKDIR) org-$(TAG) - cp -r $(DISTFILES) org-$(TAG)/ + $(MKDIR) org-$(TAG)/xemacs + cp $(DISTFILES) org-$(TAG)/ + cp $(DISTFILES_xemacs) org-$(TAG)/xemacs/ zip -r org-$(TAG).zip org-$(TAG) gtar zcvf org-$(TAG).tar.gz org-$(TAG) @@ -5,9 +5,9 @@ START-INFO-DIR-ENTRY * Org Mode: (org). outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.61). + This manual is for Org-mode (version 4.62). - Copyright (C) 2004, 2005, 2006 Free Software Foundation + Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -27,9 +27,9 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.61). +This manual is for Org-mode (version 4.62). - Copyright (C) 2004, 2005, 2006 Free Software Foundation + Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -91,19 +91,19 @@ Tables * Built-in table editor:: Simple tables * Narrow columns:: Stop wasting space in tables -* Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode -* table.el:: Complex tables +* The spreadsheet:: The table editor has spreadsheet capabilities. -Calculations in tables +The spreadsheet -* Formula syntax:: How to write a formula -* Lisp formulas:: An alternative way to write formulas -* Column formulas:: Formulas valid for all fields in a column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debuggung formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields * 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 Hyperlinks @@ -140,7 +140,7 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format -* Repeating items:: +* Repeating items:: Deadlines that come back again and again * Progress logging:: Documenting when what work was done. Creating timestamps @@ -312,19 +312,20 @@ selected by tags etc are created dynamically when you need them. 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-mode can be used on different levels and in different ways, for -example: +example as: - * as an outline extension with visibility cycling and structure editing - * as an ASCII system and table editor for taking structured notes - * as an ASCII table editor with spreadsheet-like capabilities - * as a TODO list editor - * as a full agenda and planner with deadlines and work scheduling - * as an environment to implement David Allen's GTD system - * as a simple hypertext system, with HTML export - * as a publishing tool to create a set of interlinked webpages + * 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 + * simple hypertext system, with HTML export + * publishing tool to create a set of interlinked webpages - Org-mode's automatic, context sensitive table editor can be -integrated into any major mode by activating the minor Orgtbl-mode. + Org-mode's automatic, context sensitive table editor with spreadsheet +capabilities can be integrated into any major mode by activating the +minor Orgtbl-mode. There is a website for Org-mode which provides links to the newest version of Org-mode, as well as additional information, frequently asked @@ -936,9 +937,8 @@ Emacs `calc' package. * Built-in table editor:: Simple tables * Narrow columns:: Stop wasting space in tables -* Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode -* table.el:: Complex tables +* The spreadsheet:: The table editor has spreadsheet capabilities. File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables @@ -1081,38 +1081,6 @@ Regions Calculations ............ -`C-c =' - Install a new formula for the current column and replace current - field with the result of the formula. - -`C-u C-c =' - Install a new formula for the current field, which must be a named - field. Evaluate the formula and replace the field content with the - result. - -`C-c '' - Edit all formulas associated with the current table in a separate - buffer. Use `C-u C-u C-c =' to edit the formula directly in the - current field, to allow checking complex references with `C-c ?'. - -`C-c *' - Recalculate the current row by applying the stored formulas from - left to right. When called with a `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 *Note - Table calculations::. - -`C-#' - Rotate the calculation mark in first column through the states `', - `#', `*', `!', `$'. For the meaning of these marks see *Note - Advanced features::. When there is an active region, change all - marks in the region. - -`C-c ?' - Display line and column number of current field in echo area. If - the cursor is currently editing a formula, the field or range - referenced by the expression at point will be highlighted. - `C-c +' 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 @@ -1163,7 +1131,7 @@ Then the only table command that still works is `C-c C-c' to do a manual re-align. -File: org, Node: Narrow columns, Next: Table calculations, Prev: Built-in table editor, Up: Tables +File: org, Node: Narrow columns, Next: orgtbl-mode, Prev: Built-in table editor, Up: Tables 3.2 Narrow columns ================== @@ -1206,72 +1174,144 @@ a per-file basis with: (1) This feature does not work on XEmacs. -File: org, Node: Table calculations, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables +File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Narrow columns, Up: Tables -3.3 Calculations in tables -========================== +3.3 The Orgtbl minor mode +========================= + +If you like the intuitive way the Org-mode 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) + + +File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables + +3.4 The spreadsheet +=================== 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. 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 _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. +derive fields from other fields. * Menu: -* Formula syntax:: How to write a formula -* Lisp formulas:: An alternative way to write formulas -* Column formulas:: Formulas valid for all fields in a column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debuggung formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields * 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 -File: org, Node: Formula syntax, Next: Lisp formulas, Prev: Table calculations, Up: Table calculations +File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet -3.3.1 Formula syntax --------------------- +3.4.1 References +---------------- -A formula can be any algebraic expression understood by the Emacs -`calc' package. Note that `calc' has the slightly non-standard -convention that `/' has lower precedence than `*', so that `a/b*c' is -interpreted as `a/(b*c)'. Before evaluation by `calc-eval' (*note -calc-eval: (calc)Calling Calc from Your Programs.), variable -substitution takes place: - - $ refers to the current field - $3 refers to the field in column 3 of the current row - $3..$7 a vector of the fields in columns 3-7 of current row - $P1..$P3 vector of column range, using column names - &2 second data field above the current, in same column - &5-2 vector from fifth to second field above current - &III-II vector of fields between 2nd and 3rd hline above - &III vector of fields between third hline above and current field - $name a named field, parameter or constant - - The range vectors can be directly fed into the calc vector functions -like `vmean' and `vsum'. - - `$name' is interpreted as the name of a column, parameter or -constant. Constants are defined globally through the variable +To compute fields in the table from other fields, formulas must +reference other fields or ranges. In Org-mode, 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. + +Field references +................ + +Formulas can reference the value of another field with the operator + @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 +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. 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. Here are a few examples: + + @2$3 2nd row, 3rd column + $5 column 5 in the current row + @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 + +Range references +................ + +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. + @-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. + +Named references +................ + +`$name' is interpreted as the name of a column, parameter or constant. +Constants are defined globally through the variable `org-table-formula-constants'. 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 kilometers. Column names and parameters can be specified in special table lines. These are described below, see *Note Advanced features::. + +File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet + +3.4.2 Formula syntax for Calc +----------------------------- + +A formula can be any algebraic expression understood by the Emacs +`Calc' package. Note that `calc' has the slightly non-standard +convention that `/' has lower precedence than `*', so that `a/b*c' is +interpreted as `a/(b*c)'. Before evaluation by `calc-eval' (*note +calc-eval: (calc)Calling Calc from Your Programs.), 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's modes(1) during -execution, e.g. `p20' to switch the internal precision to 20 digits, -`n3', `s3', `e2' or `f4' to switch to normal, scientific, engineering, -or fixed display format, respectively, and `D', `R', `F', and `S' to -turn on degrees, radians, fraction and symbolic modes, respectively. +This string consists of flags to influence Calc and other modes during +execution. By default, Org-mode 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: @@ -1284,81 +1324,208 @@ the final result. A few examples: 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 - vsum(&III) Sum numbers from 3rd hline above, up to here + 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 - ---------- Footnotes ---------- - - (1) By default, Org-mode 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'. - -File: org, Node: Lisp formulas, Next: Column formulas, Prev: Formula syntax, Up: Table calculations +File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet -3.3.2 Emacs Lisp forms as formulas +3.4.3 Emacs Lisp forms as formulas ---------------------------------- -It is also possible to write a formula in Emacs lisp; this can be useful +It is also possible to write a formula in Emacs Lisp; this can be useful for string manipulation and control structures. 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 provide a format -specifier after a semicolon. A few examples: +or a number. Just as with `calc' formulas, you can specify modes and a +printf format after a semicolon. A reference will be replaced with a +string (in double quotes) containing the field. If you provide the `N' +mode switch, all referenced elements will be numbers. 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's `vsum($1..$4)' + '(apply '+ '($1..$4));N + + +File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet + +3.4.4 Field formulas +-------------------- + +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$2=$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 go and fix equations yourself. - 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) + Instead of typing an equation into the field, you may also use the +following command + +`C-u C-c =' + Install a new formula for the current field. The command prompts + for a formula, with default taken from the `#+TBLFM:' line, applies + it to the current field and stores it. -File: org, Node: Column formulas, Next: Advanced features, Prev: Lisp formulas, Up: Table calculations +File: org, Node: Column formulas, Next: Editing and debuggung formulas, Prev: Field formulas, Up: The spreadsheet -3.3.3 Column formulas +3.4.5 Column formulas --------------------- -To apply a formula to a field, type it directly into the field, -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-mode will remember the most recently used -formula. The information is stored in a special line starting with -`#+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. +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-mode allows to assign a single formula to an entire +column. + + 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-mode 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 -command `C-c ='. It prompts for a formula (with default taken from the -`#+TBLFM:' line) and applies it to the current field. A numerical -prefix (e.g. `C-5 C-c =') will apply it to that many consecutive fields -in the current column. +following command: + +`C-c =' + 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 `#+TBLFM' line, applies it to + the current field and stores it. With a numerical prefix (e.g. + `C-5 C-c =') will apply it to that many consecutive fields in the + current column. + + +File: org, Node: Editing and debuggung formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet + +3.4.6 Editing and Debugging formulas +------------------------------------ + +You can edit individual formulas in the minibuffer or directly in the +field. Org-mode can also prepare a special buffer with all active +formulas of a table. + +`C-c =' +`C-u C-c =' + Edit the formula associated with the current column/field in the + minibuffer. See *Note Column formulas:: and *Note Field + formulas::. + +`C-u C-u C-c =' + 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 `C-c ?'. + +`C-c ?' + While editing a formula in a table field, highlight the field(s) + referenced by the reference at the cursor position in the formula. + +`C-c '' + Edit all formulas for the current table in a special buffer, where + the formulas will be displayed one per line. While inside the + special buffer, Org-mode will automatically highlight any field or + range reference at the cursor position. You may edit, remove and + add formulas, and use the following commands: + `C-c C-c' + Exit the buffer and store the modified formulas. With `C-u' + prefix, also apply the new formulas to the entire table. + + `C-c C-q' + Exit the buffer without installing changes. + + `S-<up>/<down>' + Move the reference line in the Org-mode buffer up and down. + This is important for highlighting the references of column + formulas for different rows. + + `M-<up>/<down>' + Scroll the window displaying the table. + + 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. + +Debugging formulas +.................. + +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-c = <RET>' in a field. Detailed information +will be displayed. + + +File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debuggung formulas, Up: The spreadsheet + +3.4.7 Updating the Table +------------------------ + +Recalculation of a table is normally not automatic, but needs to be +triggered by a command. See *Note 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: + +`C-c *' + Recalculate the current row by first applying the stored column + formulas from left to right, and all field formulas in the current + row. - To recompute all the fields in a line, use the command `C-c *'. It -re-applies all stored equations to the current row, from left to right. -With a `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. `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. +`C-u C-c *' +`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. + +`C-u C-u C-c *' + 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. -File: org, Node: Advanced features, Next: Named-field formulas, Prev: Column formulas, Up: Table calculations +File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet -3.3.4 Advanced features +3.4.8 Advanced features ----------------------- If you 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: +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. +`C-#' + Rotate the calculation mark in first column through the states `', + `#', `*', `!', `$'. The meaning of these characters is discussed + below. When there is an active region, change all marks in the + region. + + Here is an example of a table that collects exam results of students +and makes use of these features: |---+---------+--------+--------+--------+-------+------| | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | @@ -1375,12 +1542,12 @@ collects exam results of students and makes use of these features: | ^ | | | | | at | | | $ | max=50 | | | | | | |---+---------+--------+--------+--------+-------+------| - #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f + #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f Important: Please note that for these special tables, recalculating the table with `C-u C-c *' will only affect rows that are marked `#' or -`*', and named fields. The column formulas are not applied in rows -with empty first field. +`*', and fields that have a formula assigned to the field itself. The +column formulas are not applied in rows with empty first field. The marking characters have the following meaning: `!' @@ -1390,8 +1557,8 @@ with empty first field. `^' This row defines names for the fields _above_ the row. With such a definition, any formula in the table may use `$m1' to refer to - the value `10'. Also, named fields can have their own formula - associated with them. + the value `10'. Also, if you assign a formula to a names field, it + will be stored as `$name=...'. `_' Similar to `^', but defines names for the fields in the row @@ -1402,8 +1569,7 @@ with empty first field. example, if a field in a `$' row contains `max=50', then formulas in this table can refer to the value 50 using `$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. + per-table basis. `#' Fields in this row are automatically recalculated when pressing @@ -1421,65 +1587,10 @@ with empty first field. All lines that should be recalculated should be marked with `#' or `*'. - -File: org, Node: Named-field formulas, Next: Editing/debugging formulas, Prev: Advanced features, Up: Table calculations - -3.3.5 Named-field formulas --------------------------- - -A named field can have its own formula associated with it. In the -example above, this is used for the `at' field that contains the -average result of the students. To enter a formula for a named field, -just type it into the buffer, preceded by `:='. Or use `C-u C-c ='. -This equation will be stored below the table like `$name=...'. Any -recalculation in the table (even if only requested for the current -line) will also update all named field formulas. - - -File: org, Node: Editing/debugging formulas, Next: Appetizer, Prev: Named-field formulas, Up: Table calculations - -3.3.6 Editing and debugging formulas ------------------------------------- - -To edit a column or field formula, use the commands `C-c =' and `C-u -C-c =', respectively. The currently active expression is then -presented as default in the minibuffer, where 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 -`#+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. - - In particular for large tables with many formulas, it is convenient -to use the command `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 `C-c ?' on a -`$...' expression to get information about its interpretation. -Exiting the buffer with `C-c C-c' only stores the modified formulas -below the table. Exiting with `C-u C-c C-c' also applies them to the -entire table. `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 `#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, for -example by pressing `C-c = <RET>' in a field. Detailed information -will be displayed. - - -File: org, Node: Appetizer, Prev: Editing/debugging formulas, Up: Table calculations - -3.3.7 Appetizer ---------------- - -Finally, just to whet your appetite on what can be done with the + Finally, just to whet your appetite on what can be done with the fantastic `calc' package, here is a table that computes the Taylor -series for a couple of functions (homework: try that with Excel :-) +series of degree `n' at location `x' for a couple of functions +(homework: try that with Excel :-) |---+-------------+---+-----+--------------------------------------| | | Func | n | x | Result | @@ -1494,45 +1605,6 @@ series for a couple of functions (homework: try that with Excel :-) #+TBLFM: $5=taylor($2,$4,$3);n3 -File: org, Node: orgtbl-mode, Next: table.el, Prev: Table calculations, Up: Tables - -3.4 The Orgtbl minor mode -========================= - -If you like the intuitive way the Org-mode 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) - - -File: org, Node: table.el, Prev: orgtbl-mode, Up: Tables - -3.5 The `table.el' package -========================== - -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). When <TAB> or `C-c C-c' is pressed in such a -table, Org-mode will call `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-mode-related commands, leave the table. - -`C-c C-c' - Recognize `table.el' table. Works when the cursor is in a - table.el table. - -`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 - `org-convert-table' for the restrictions under which this is - possible. - - File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top 4 Hyperlinks @@ -1743,15 +1815,17 @@ insert it into an org-mode file, and to follow the link. link, or one of the link type prefixes mentioned in the examples above. Through completion, all links stored during the current session can be accessed(1). The link will be inserted into the - buffer, along with a descriptive text. Note that you don't have - to use this command to insert a link. Links in Org-mode are plain - text, and you can type or paste them straight into the buffer. By - using this command, the links are automatically enclosed in double - brackets, and you will be asked for the optional descriptive text. - If the link is a `file:' link and the linked file is located in - the same directory as the current file or a subdirectory of it, the - path of the file will be inserted relative to the current - directory. + buffer, along with a descriptive text. If some text was selecten + when this command is called, the selected text becomes the default + description. + Note that you don't have to use this command to insert a link. + Links in Org-mode are plain text, and you can type or paste them + straight into the buffer. By using this command, the links are + automatically enclosed in double brackets, and you will be asked + for the optional descriptive text. If the link is a `file:' link + and the linked file is located in the same directory as the + current file or a subdirectory of it, the path of the file will be + inserted relative to the current directory. `C-u C-c C-l' When `C-c C-l' is called with a `C-u' prefix argument, a link to a @@ -2623,7 +2697,7 @@ have closed this item in a note under the headline. instance of each exist at any given time. So if you look back or ahead in the agenda, you will not find past and future instances, only the current one will show up. Use a cyclic diary entry if you need all -past and future instances to be visible in the angenda. +past and future instances to be visible in the agenda. File: org, Node: Progress logging, Prev: Repeating items, Up: Timestamps @@ -3012,7 +3086,7 @@ tag starting with `BOSS'. You can also require a headline to be of a certain level, by writing instead of any TAG an expression like `LEVEL=3'. For example, a search `+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag -BOSS and are _not_ marked witht the todo keyword DONE. +BOSS and are _not_ marked with the todo keyword DONE. File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Tags, Up: Top @@ -3035,7 +3109,7 @@ in a separate buffer. Six different view types are provided: * a _TODO list_ that covers all unfinished action items, * a _tags view_, showings headlines based on the tags associated - them, + with them, * a _timeline view_ that shows all events in a single Org-mode file, in time-sorted view, @@ -3085,6 +3159,7 @@ way to maintain it is through the following commands Remove current file from the list of agenda files. `C-,' +`C-'' Cycle through agenda file list, visiting one file after the other. The Org menu contains the current list of files and can be used to @@ -3589,7 +3664,7 @@ Remote editing priority character. If you reply with <SPC>, the priority cookie is removed from the entry. -`p' +`P' Display weighted priority of current item. `+' @@ -4923,7 +4998,7 @@ file is visited again in a new Emacs session. This line sets the archive location for the agenda file. It applies for all subsequent lines until the next `#+CATEGORY' line, or the end of the file. The first such line also applies to any - entries before it. The correspoinding variable is + entries before it. The corresponding variable is `org-archive-location'. `#+TBLFM:' @@ -5122,23 +5197,23 @@ File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Intera `calc.el' by Dave Gillespie Org-mode uses the calc package for implementing spreadsheet - functionality in its tables (*note Table calculations::). - Org-modes checks for the availability of calc by looking for the - function `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. - *Note Embedded Mode: (calc)Embedded Mode. + functionality in its tables (*note The spreadsheet::). Org-modes + checks for the availability of calc by looking for the function + `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. *Note Embedded + Mode: (calc)Embedded Mode. `constants.el' by Carsten Dominik - In a table formula (*note Table calculations::), 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 `constants' package which defines a large number of - constants and units, and lets you use unit prefixes like `M' for - `Mega' etc. You will need version 2.0 of this package, available - at `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for - the function `constants-get', which has to be autoloaded in your + In a table formula (*note 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 `constants' package which defines a large number of constants + and units, and lets you use unit prefixes like `M' for `Mega' etc. + You will need version 2.0 of this package, available at + `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the + function `constants-get', which has to be autoloaded in your setup. See the installation instructions in the file `constants.el'. @@ -5151,7 +5226,25 @@ File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Intera `Remember.el' is not part of Emacs, find it on the web. `table.el' by Takaaki Ota - Org mode cooperates with table.el, see *Note table.el::. + 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). When <TAB> or `C-c C-c' is pressed in + such a table, Org-mode will call `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-mode-related commands, leave + the table. + + `C-c C-c' + Recognize `table.el' table. Works when the cursor is in a + table.el table. + + `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 `org-convert-table' for the restrictions under which + this is possible. `table.el' is part of Emacs 22. @@ -5353,7 +5446,7 @@ WAITING tag anywhere in the project tree. Let's further assume that you have marked all tree headings that define a project with the todo keyword PROJECT. In this case you would run a todo search for the keyword PROJECT, but skip the match unless there is a WAITING tag -anywhere in the subtree belonging to the project line.. +anywhere in the subtree belonging to the project line. To achieve this, you must write a function that searches the subtree for the tag. If the tag is found, the function must return `nil' to @@ -5369,7 +5462,7 @@ search should continue from there. subtree-end))) ; tag not found, continue after end of subtree Furthermore you must write a command that uses `let' to temporarily -puts this function into the variable `org-agenda-skip-function', sets +put this function into the variable `org-agenda-skip-function', sets the header string for the agenda buffer, and calls the todo-list generator while asking for the specific TODO keyword PROJECT. The function must also accept one argument MATCH, but it can choose to @@ -5549,7 +5642,7 @@ Index * active region <1>: Export commands. (line 6) * active region <2>: ASCII export. (line 9) * active region <3>: Built-in table editor. - (line 173) + (line 141) * active region: Structure editing. (line 64) * agenda: Weekly/Daily agenda. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) @@ -5578,9 +5671,9 @@ Index * bugs: Bugs. (line 6) * C-c C-c, overview: The very busy C-c C-c key. (line 6) -* calc package: Table calculations. (line 6) +* calc package: The spreadsheet. (line 6) * calc.el: Cooperation. (line 6) -* calculations, in tables <1>: Table calculations. (line 6) +* calculations, in tables <1>: The spreadsheet. (line 6) * calculations, in tables: Built-in table editor. (line 141) * calendar commands, from agenda: Agenda commands. (line 191) @@ -5605,7 +5698,8 @@ Index * completion, of CamelCase links <1>: Completion. (line 6) * completion, of CamelCase links: CamelCase links. (line 6) * completion, of dictionary words: Completion. (line 6) -* completion, of file names: Handling links. (line 43) +* completion, of file names: Handling links. (line 45) +* completion, of link abbreviations: Completion. (line 6) * completion, of links: Handling links. (line 27) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords: Export options. (line 6) @@ -5615,7 +5709,7 @@ Index * completion, of TeX symbols: Completion. (line 6) * completion, of TODO keywords <1>: Completion. (line 6) * completion, of TODO keywords: Workflow states. (line 12) -* constants, in calculations: Formula syntax. (line 26) +* constants, in calculations: References. (line 65) * constants.el: Cooperation. (line 14) * content, STARTUP keyword: In-buffer settings. (line 22) * contents, global visibility state: Visibility cycling. (line 22) @@ -5639,6 +5733,8 @@ Index * DEADLINE keyword: Time stamps. (line 53) * deadlines: Time stamps. (line 6) * Deadlines, repeating: Repeating items. (line 6) +* debugging, of table formulas: Editing and debuggung formulas. + (line 60) * demotion, of subtrees: Structure editing. (line 6) * diary entries, creating from agenda: Agenda commands. (line 198) * diary integration: Weekly/Daily agenda. (line 24) @@ -5650,7 +5746,7 @@ Index * document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 20) * editing tables: Tables. (line 6) -* editing, of table formulas: Editing/debugging formulas. +* editing, of table formulas: Editing and debuggung formulas. (line 6) * elisp links: External links. (line 6) * emphasized text: Export options. (line 25) @@ -5663,11 +5759,13 @@ Index * external archiving: Moving subtrees. (line 6) * external links: External links. (line 6) * external links, in HTML export: Links. (line 6) -* FAQ: Summary. (line 51) +* FAQ: Summary. (line 52) * feedback: Feedback. (line 6) +* field formula: Field formulas. (line 6) +* field references: References. (line 14) * file links: External links. (line 6) * file links, searching: Search options. (line 6) -* file name completion: Handling links. (line 43) +* file name completion: Handling links. (line 45) * files for agenda: Agenda files. (line 6) * files, adding to agenda list: Agenda files. (line 12) * files, selecting for publishing: Selecting files. (line 6) @@ -5675,14 +5773,17 @@ Index * fixed-width sections: Export options. (line 25) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Handling links. (line 58) -* format specifier: Formula syntax. (line 34) +* following links: Handling links. (line 60) +* format specifier: Formula syntax for Calc. + (line 15) * format, of links: Link format. (line 6) -* formula editing: Editing/debugging formulas. +* formula debugging: Editing and debuggung formulas. + (line 60) +* formula editing: Editing and debuggung formulas. (line 6) -* formula syntax: Formula syntax. (line 6) -* formula, for named table field: Named-field formulas. +* formula syntax, Calc: Formula syntax for Calc. (line 6) +* formula, for individual table field: Field formulas. (line 6) * formula, for table column: Column formulas. (line 6) * formula, in tables: Built-in table editor. (line 141) @@ -5734,6 +5835,7 @@ Index * linebreak preservation: Export options. (line 25) * linebreak, forced: Enhancing text. (line 32) * link abbreviations: Link abbreviations. (line 6) +* link abbreviations, completion of: Completion. (line 6) * link completion: Handling links. (line 27) * link format: Link format. (line 6) * links, external: External links. (line 6) @@ -5742,8 +5844,9 @@ Index * links, internal: Internal links. (line 6) * links, publishing: Publishing links. (line 6) * links, radio targets: Radio targets. (line 6) -* links, returning to: Handling links. (line 85) -* Lisp forms, as table formulas: Lisp formulas. (line 6) +* links, returning to: Handling links. (line 87) +* Lisp forms, as table formulas: Formula syntax for Lisp. + (line 6) * lists, hand-formatted: Enhancing text. (line 11) * lists, ordered: Plain lists. (line 6) * lists, plain: Plain lists. (line 6) @@ -5753,20 +5856,20 @@ Index * lognotedone, STARTUP keyword: In-buffer settings. (line 33) * lognotestate, STARTUP keyword: In-buffer settings. (line 33) * maintainer: Feedback. (line 6) -* mark ring: Handling links. (line 81) -* marking characters, tables: Advanced features. (line 34) +* mark ring: Handling links. (line 83) +* marking characters, tables: Advanced features. (line 40) * matching, of tags: Matching headline tags. (line 6) * matching, tags: Tags. (line 6) * math symbols: Math symbols. (line 6) * MH-E links: External links. (line 6) * minor mode for tables: orgtbl-mode. (line 6) -* mode, for calc: Formula syntax. (line 34) +* mode, for calc: Formula syntax for Calc. + (line 15) * motion commands in agenda: Agenda commands. (line 19) * motion, between headlines: Motion. (line 6) -* name, of column or field: Formula syntax. (line 26) -* named field formula: Named-field formulas. - (line 6) +* name, of column or field: References. (line 65) +* named references: References. (line 65) * names as TODO keywords: TODO types. (line 6) * narrow columns in tables: Narrow columns. (line 6) * noalign, STARTUP keyword: In-buffer settings. (line 29) @@ -5809,12 +5912,17 @@ Index * publishing: Publishing. (line 6) * quoted HTML tags: Export options. (line 25) * radio targets: Radio targets. (line 6) +* range references: References. (line 44) * ranges, time: Time stamps. (line 6) -* recomputing table fields: Column formulas. (line 27) +* recomputing table fields: Updating the table. (line 6) +* references: References. (line 6) +* references, named: References. (line 65) +* references, to fields: References. (line 14) +* references, to ranges: References. (line 44) * region, active <1>: Export commands. (line 6) * region, active <2>: ASCII export. (line 9) * region, active <3>: Built-in table editor. - (line 173) + (line 141) * region, active: Structure editing. (line 64) * regular expressions, with tags search: Tag searches. (line 63) * remember.el <1>: Cooperation. (line 33) @@ -5844,7 +5952,7 @@ Index * sparse tree, tag based: Tags. (line 6) * sparse trees: Sparse trees. (line 6) * special keywords: In-buffer settings. (line 6) -* spreadsheet capabilities: Table calculations. (line 6) +* spreadsheet capabilities: The spreadsheet. (line 6) * statistics, for checkboxes: Checkboxes. (line 23) * storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) @@ -5861,13 +5969,13 @@ Index * summary: Summary. (line 6) * superscript: Subscripts and Superscripts. (line 6) -* syntax, of formulas: Formula syntax. (line 6) +* syntax, of formulas: Formula syntax for Calc. + (line 6) * table editor, builtin: Built-in table editor. (line 6) -* table editor, table.el: table.el. (line 6) +* table editor, table.el: Cooperation. (line 37) * table of contents: Export options. (line 25) -* table.el <1>: Cooperation. (line 34) -* table.el: table.el. (line 6) +* table.el: Cooperation. (line 34) * tables <1>: Export options. (line 25) * tables: Tables. (line 6) * tables, export: Enhancing text. (line 21) @@ -5915,7 +6023,7 @@ Index * transient-mark-mode <1>: Export commands. (line 6) * transient-mark-mode <2>: ASCII export. (line 9) * transient-mark-mode <3>: Built-in table editor. - (line 173) + (line 141) * transient-mark-mode: Structure editing. (line 64) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) @@ -5923,10 +6031,12 @@ Index * types as TODO keywords: TODO types. (line 6) * underlined text: Enhancing text. (line 15) * undoing remote-editing events: Agenda commands. (line 109) +* updating, table: Updating the table. (line 6) * URL links: External links. (line 6) * USENET links: External links. (line 6) * variables, for customization: Customization. (line 6) -* vectors, in table calculations: Formula syntax. (line 23) +* vectors, in table calculations: Formula syntax for Calc. + (line 11) * visibility cycling: Visibility cycling. (line 6) * visible text, printing: Sparse trees. (line 41) * VM links: External links. (line 6) @@ -5982,23 +6092,20 @@ Key Index * b: Agenda commands. (line 51) * C: Agenda commands. (line 213) * c: Agenda commands. (line 191) -* C-#: Built-in table editor. - (line 162) +* C-#: Advanced features. (line 9) +* C-': Agenda files. (line 18) * C-,: Agenda files. (line 18) * C-_: Agenda commands. (line 109) * C-a a L: Timeline. (line 10) * C-c !: Creating timestamps. (line 21) * C-c #: Checkboxes. (line 56) -* C-c %: Handling links. (line 81) -* C-c &: Handling links. (line 85) -* C-c ' <1>: Editing/debugging formulas. - (line 20) -* C-c ': Built-in table editor. - (line 150) -* C-c *: Built-in table editor. - (line 155) +* C-c %: Handling links. (line 83) +* C-c &: Handling links. (line 87) +* C-c ': Editing and debuggung formulas. + (line 24) +* C-c *: Updating the table. (line 13) * C-c +: Built-in table editor. - (line 173) + (line 141) * C-c ,: Priorities. (line 18) * C-c -: Built-in table editor. (line 92) @@ -6008,14 +6115,13 @@ Key Index * C-c ;: Comment lines. (line 11) * C-c <: Creating timestamps. (line 25) * C-c <TAB>: Built-in table editor. - (line 195) -* C-c =: Built-in table editor. - (line 141) + (line 163) +* C-c = <1>: Editing and debuggung formulas. + (line 10) +* C-c =: Column formulas. (line 24) * C-c >: Creating timestamps. (line 29) -* C-c ? <1>: Editing/debugging formulas. +* C-c ?: Editing and debuggung formulas. (line 20) -* C-c ?: Built-in table editor. - (line 168) * C-c [: Agenda files. (line 12) * C-c \: Tag searches. (line 9) * C-c ]: Agenda files. (line 15) @@ -6023,7 +6129,7 @@ Key Index (line 96) * C-c ^: Structure editing. (line 52) * C-c `: Built-in table editor. - (line 189) + (line 157) * C-c a !: Stuck projects. (line 14) * C-c a #: Stuck projects. (line 13) * C-c a a: Weekly/Daily agenda. (line 9) @@ -6039,15 +6145,15 @@ Key Index * C-c a t: TODO basics. (line 33) * C-c C-a: Visibility cycling. (line 31) * C-c C-b: Motion. (line 15) -* C-c C-c <1>: The very busy C-c C-c key. +* C-c C-c <1>: Cooperation. (line 37) +* C-c C-c <2>: The very busy C-c C-c key. (line 6) -* C-c C-c <2>: Processing LaTeX fragments. +* C-c C-c <3>: Processing LaTeX fragments. (line 15) -* C-c C-c <3>: Setting tags. (line 10) -* C-c C-c <4>: Checkboxes. (line 37) -* C-c C-c <5>: table.el. (line 6) -* C-c C-c <6>: Editing/debugging formulas. - (line 16) +* C-c C-c <4>: Setting tags. (line 10) +* C-c C-c <5>: Checkboxes. (line 37) +* C-c C-c <6>: Editing and debuggung formulas. + (line 32) * C-c C-c <7>: Built-in table editor. (line 54) * C-c C-c: Plain lists. (line 74) @@ -6072,10 +6178,10 @@ Key Index * C-c C-l: Handling links. (line 27) * C-c C-n: Motion. (line 8) * C-c C-o <1>: Creating timestamps. (line 33) -* C-c C-o: Handling links. (line 58) +* C-c C-o: Handling links. (line 60) * C-c C-p: Motion. (line 9) -* C-c C-q <1>: Editing/debugging formulas. - (line 20) +* C-c C-q <1>: Editing and debuggung formulas. + (line 34) * C-c C-q: Built-in table editor. (line 125) * C-c C-r: Visibility cycling. (line 32) @@ -6116,17 +6222,23 @@ Key Index * C-c {: CDLaTeX mode. (line 21) * C-c |: Built-in table editor. (line 40) -* C-c ~: table.el. (line 18) +* C-c ~: Cooperation. (line 50) * C-k: Agenda commands. (line 117) * C-TAB: ARCHIVE tag. (line 38) +* C-u C-c *: Updating the table. (line 18) * C-u C-c .: Creating timestamps. (line 16) -* C-u C-c =: Built-in table editor. - (line 145) -* C-u C-c C-l: Handling links. (line 43) +* C-u C-c = <1>: Editing and debuggung formulas. + (line 10) +* C-u C-c =: Field formulas. (line 24) +* C-u C-c C-c: Updating the table. (line 19) +* C-u C-c C-l: Handling links. (line 45) * C-u C-c C-x C-a: ARCHIVE tag. (line 31) * C-u C-c C-x C-s: Moving subtrees. (line 12) * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22) * C-u C-c C-x C-u: Clocking work time. (line 70) +* C-u C-u C-c *: Updating the table. (line 24) +* C-u C-u C-c =: Editing and debuggung formulas. + (line 14) * D: Agenda commands. (line 74) * d: Agenda commands. (line 71) * f: Agenda commands. (line 44) @@ -6137,6 +6249,8 @@ Key Index * l: Agenda commands. (line 57) * L: Agenda commands. (line 32) * M: Agenda commands. (line 204) +* M-<down> <1>: Editing and debuggung formulas. + (line 42) * M-<down>: Built-in table editor. (line 82) * M-<left> <1>: Built-in table editor. @@ -6150,6 +6264,8 @@ Key Index * M-<TAB> <1>: Completion. (line 10) * M-<TAB> <2>: Setting tags. (line 6) * M-<TAB>: Per file keywords. (line 17) +* M-<up> <1>: Editing and debuggung formulas. + (line 42) * M-<up>: Built-in table editor. (line 82) * M-S-<down> <1>: Built-in table editor. @@ -6178,11 +6294,11 @@ Key Index * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: The date/time prompt. (line 33) -* mouse-1: Handling links. (line 72) +* mouse-1: Handling links. (line 74) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Handling links. (line 72) +* mouse-2: Handling links. (line 74) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Handling links. (line 77) +* mouse-3: Handling links. (line 79) * n: Agenda commands. (line 19) * O: Agenda commands. (line 180) * o: Agenda commands. (line 65) @@ -6198,6 +6314,8 @@ Key Index (line 42) * S-<down> <3>: Creating timestamps. (line 58) * S-<down> <4>: Priorities. (line 25) +* S-<down> <5>: Editing and debuggung formulas. + (line 37) * S-<down>: Plain lists. (line 55) * S-<left> <1>: Agenda commands. (line 169) * S-<left> <2>: The date/time prompt. @@ -6205,7 +6323,7 @@ Key Index * S-<left> <3>: Creating timestamps. (line 53) * S-<left>: TODO basics. (line 20) * S-<RET>: Built-in table editor. - (line 178) + (line 146) * S-<right> <1>: Agenda commands. (line 161) * S-<right> <2>: The date/time prompt. (line 36) @@ -6219,6 +6337,8 @@ Key Index (line 45) * S-<up> <3>: Creating timestamps. (line 58) * S-<up> <4>: Priorities. (line 25) +* S-<up> <5>: Editing and debuggung formulas. + (line 37) * S-<up>: Plain lists. (line 55) * T: Agenda commands. (line 126) * t: Agenda commands. (line 113) @@ -6229,173 +6349,172 @@ Key Index Tag Table: -Node: Top964 -Node: Introduction10853 -Node: Summary11268 -Node: Installation14180 -Node: Activation15558 -Node: Feedback16807 -Node: Document structure18883 -Node: Outlines19657 -Node: Headlines20317 -Node: Visibility cycling20940 -Ref: Visibility cycling-Footnote-123031 -Ref: Visibility cycling-Footnote-223089 -Ref: Visibility cycling-Footnote-323139 -Node: Motion23408 -Node: Structure editing24192 -Node: Archiving27018 -Node: ARCHIVE tag27576 -Node: Moving subtrees29369 -Node: Sparse trees30680 -Ref: Sparse trees-Footnote-132811 -Ref: Sparse trees-Footnote-232993 -Node: Plain lists33108 -Ref: Plain lists-Footnote-136633 -Ref: Plain lists-Footnote-236990 -Node: Tables37174 -Node: Built-in table editor37722 -Node: Narrow columns45999 -Ref: Narrow columns-Footnote-147938 -Node: Table calculations47984 -Node: Formula syntax49304 -Ref: Formula syntax-Footnote-152209 -Node: Lisp formulas52509 -Node: Column formulas53298 -Node: Advanced features55060 -Node: Named-field formulas58314 -Node: Editing/debugging formulas58954 -Node: Appetizer60712 -Node: orgtbl-mode61815 -Node: table.el62306 -Node: Hyperlinks63283 -Node: Link format64056 -Node: Internal links65349 -Ref: Internal links-Footnote-167338 -Node: Radio targets67470 -Node: CamelCase links68185 -Node: External links68779 -Node: Handling links71183 -Ref: Handling links-Footnote-175835 -Ref: Handling links-Footnote-276072 -Node: Link abbreviations76146 -Node: Search options77825 -Ref: Search options-Footnote-179605 -Node: Custom searches79686 -Node: Remember80734 -Node: TODO items84428 -Node: TODO basics85410 -Node: TODO extensions86937 -Node: Workflow states87732 -Node: TODO types88717 -Ref: TODO types-Footnote-190375 -Node: Per file keywords90457 -Ref: Per file keywords-Footnote-191911 -Node: Priorities92112 -Node: Breaking down tasks93356 -Ref: Breaking down tasks-Footnote-193875 -Node: Checkboxes93971 -Node: Timestamps96726 -Node: Time stamps97260 -Ref: Time stamps-Footnote-1100754 -Ref: Time stamps-Footnote-2100870 -Node: Creating timestamps101025 -Node: The date/time prompt103651 -Ref: The date/time prompt-Footnote-1105417 -Node: Custom time format105523 -Node: Repeating items107081 -Node: Progress logging108892 -Node: Closing items109538 -Ref: Closing items-Footnote-1110472 -Ref: Closing items-Footnote-2110541 -Node: Tracking TODO state changes110614 -Node: Clocking work time111470 -Ref: Clocking work time-Footnote-1115116 -Ref: Clocking work time-Footnote-2115194 -Node: Tags115320 -Node: Tag inheritance116082 -Node: Setting tags117019 -Ref: Setting tags-Footnote-1121218 -Ref: Setting tags-Footnote-2121330 -Node: Tag searches121413 -Node: Agenda views124125 -Node: Agenda files126065 -Ref: Agenda files-Footnote-1127025 -Ref: Agenda files-Footnote-2127174 -Node: Agenda dispatcher127367 -Node: Built-in agenda views129058 -Node: Weekly/Daily agenda129636 -Node: Global TODO list131765 -Node: Matching headline tags133938 -Node: Timeline135009 -Node: Stuck projects135675 -Node: Presentation and sorting137374 -Node: Categories138165 -Node: Time-of-day specifications138829 -Node: Sorting of agenda items140800 -Node: Agenda commands142082 -Node: Custom agenda views148735 -Node: Storing searches149410 -Node: Block agenda151322 -Node: Setting Options152552 -Node: Batch processing155264 -Node: Embedded LaTeX156394 -Ref: Embedded LaTeX-Footnote-1157486 -Node: Math symbols157676 -Node: Subscripts and Superscripts158441 -Node: LaTeX fragments159285 -Ref: LaTeX fragments-Footnote-1161393 -Node: Processing LaTeX fragments161655 -Node: CDLaTeX mode162601 -Ref: CDLaTeX mode-Footnote-1165085 -Node: Exporting165233 -Node: ASCII export166547 -Node: HTML export167837 -Node: Export commands168456 -Node: Quoting HTML tags169180 -Node: Links169523 -Node: Images170220 -Ref: Images-Footnote-1171091 -Node: CSS support171152 -Ref: CSS support-Footnote-1172471 -Node: XOXO export172584 -Node: iCalendar export173023 -Node: Text interpretation174846 -Node: Comment lines175325 -Node: Enhancing text175796 -Node: Export options177488 -Node: Publishing179155 -Ref: Publishing-Footnote-1179951 -Node: Configuration180147 -Node: Project alist180865 -Node: Sources and destinations181931 -Node: Selecting files182661 -Node: Publishing action183409 -Node: Publishing options184642 -Node: Publishing links186794 -Node: Project page index188307 -Node: Sample configuration189085 -Node: Simple example189577 -Node: Complex example190250 -Node: Triggering publication192326 -Node: Miscellaneous193011 -Node: Completion193645 -Node: Customization195116 -Node: In-buffer settings195699 -Node: The very busy C-c C-c key199940 -Node: Clean view201584 -Node: TTY keys204161 -Node: Interaction205770 -Node: Cooperation206167 -Node: Conflicts208034 -Node: Bugs209626 -Node: Extensions and Hacking211020 -Node: Extensions211524 -Node: Dynamic blocks213467 -Node: Special agenda views215423 -Ref: Special agenda views-Footnote-1217704 -Node: History and Acknowledgments217964 -Node: Index223323 -Node: Key Index252098 +Node: Top970 +Node: Introduction10946 +Node: Summary11361 +Node: Installation14262 +Node: Activation15640 +Node: Feedback16889 +Node: Document structure18965 +Node: Outlines19739 +Node: Headlines20399 +Node: Visibility cycling21022 +Ref: Visibility cycling-Footnote-123113 +Ref: Visibility cycling-Footnote-223171 +Ref: Visibility cycling-Footnote-323221 +Node: Motion23490 +Node: Structure editing24274 +Node: Archiving27100 +Node: ARCHIVE tag27658 +Node: Moving subtrees29451 +Node: Sparse trees30762 +Ref: Sparse trees-Footnote-132893 +Ref: Sparse trees-Footnote-233075 +Node: Plain lists33190 +Ref: Plain lists-Footnote-136715 +Ref: Plain lists-Footnote-237072 +Node: Tables37256 +Node: Built-in table editor37770 +Node: Narrow columns44766 +Ref: Narrow columns-Footnote-146698 +Node: orgtbl-mode46744 +Node: The spreadsheet47238 +Node: References48056 +Node: Formula syntax for Calc51313 +Node: Formula syntax for Lisp53630 +Node: Field formulas54858 +Node: Column formulas56169 +Node: Editing and debuggung formulas57592 +Node: Updating the table60300 +Node: Advanced features61331 +Node: Hyperlinks65756 +Node: Link format66529 +Node: Internal links67822 +Ref: Internal links-Footnote-169811 +Node: Radio targets69943 +Node: CamelCase links70658 +Node: External links71252 +Node: Handling links73656 +Ref: Handling links-Footnote-178424 +Ref: Handling links-Footnote-278661 +Node: Link abbreviations78735 +Node: Search options80414 +Ref: Search options-Footnote-182194 +Node: Custom searches82275 +Node: Remember83323 +Node: TODO items87017 +Node: TODO basics87999 +Node: TODO extensions89526 +Node: Workflow states90321 +Node: TODO types91306 +Ref: TODO types-Footnote-192964 +Node: Per file keywords93046 +Ref: Per file keywords-Footnote-194500 +Node: Priorities94701 +Node: Breaking down tasks95945 +Ref: Breaking down tasks-Footnote-196464 +Node: Checkboxes96560 +Node: Timestamps99315 +Node: Time stamps99849 +Ref: Time stamps-Footnote-1103343 +Ref: Time stamps-Footnote-2103459 +Node: Creating timestamps103614 +Node: The date/time prompt106240 +Ref: The date/time prompt-Footnote-1108006 +Node: Custom time format108112 +Node: Repeating items109670 +Node: Progress logging111480 +Node: Closing items112126 +Ref: Closing items-Footnote-1113060 +Ref: Closing items-Footnote-2113129 +Node: Tracking TODO state changes113202 +Node: Clocking work time114058 +Ref: Clocking work time-Footnote-1117704 +Ref: Clocking work time-Footnote-2117782 +Node: Tags117908 +Node: Tag inheritance118670 +Node: Setting tags119607 +Ref: Setting tags-Footnote-1123806 +Ref: Setting tags-Footnote-2123918 +Node: Tag searches124001 +Node: Agenda views126712 +Node: Agenda files128657 +Ref: Agenda files-Footnote-1129623 +Ref: Agenda files-Footnote-2129772 +Node: Agenda dispatcher129965 +Node: Built-in agenda views131656 +Node: Weekly/Daily agenda132234 +Node: Global TODO list134363 +Node: Matching headline tags136536 +Node: Timeline137607 +Node: Stuck projects138273 +Node: Presentation and sorting139972 +Node: Categories140763 +Node: Time-of-day specifications141427 +Node: Sorting of agenda items143398 +Node: Agenda commands144680 +Node: Custom agenda views151333 +Node: Storing searches152008 +Node: Block agenda153920 +Node: Setting Options155150 +Node: Batch processing157862 +Node: Embedded LaTeX158992 +Ref: Embedded LaTeX-Footnote-1160084 +Node: Math symbols160274 +Node: Subscripts and Superscripts161039 +Node: LaTeX fragments161883 +Ref: LaTeX fragments-Footnote-1163991 +Node: Processing LaTeX fragments164253 +Node: CDLaTeX mode165199 +Ref: CDLaTeX mode-Footnote-1167683 +Node: Exporting167831 +Node: ASCII export169145 +Node: HTML export170435 +Node: Export commands171054 +Node: Quoting HTML tags171778 +Node: Links172121 +Node: Images172818 +Ref: Images-Footnote-1173689 +Node: CSS support173750 +Ref: CSS support-Footnote-1175069 +Node: XOXO export175182 +Node: iCalendar export175621 +Node: Text interpretation177444 +Node: Comment lines177923 +Node: Enhancing text178394 +Node: Export options180086 +Node: Publishing181753 +Ref: Publishing-Footnote-1182549 +Node: Configuration182745 +Node: Project alist183463 +Node: Sources and destinations184529 +Node: Selecting files185259 +Node: Publishing action186007 +Node: Publishing options187240 +Node: Publishing links189392 +Node: Project page index190905 +Node: Sample configuration191683 +Node: Simple example192175 +Node: Complex example192848 +Node: Triggering publication194924 +Node: Miscellaneous195609 +Node: Completion196243 +Node: Customization197714 +Node: In-buffer settings198297 +Node: The very busy C-c C-c key202537 +Node: Clean view204181 +Node: TTY keys206758 +Node: Interaction208367 +Node: Cooperation208764 +Node: Conflicts211505 +Node: Bugs213097 +Node: Extensions and Hacking214491 +Node: Extensions214995 +Node: Dynamic blocks216938 +Node: Special agenda views218894 +Ref: Special agenda views-Footnote-1221173 +Node: History and Acknowledgments221433 +Node: Index226792 +Node: Key Index256794 End Tag Table @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik <dominik at science dot uva dot nl> ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.61 +;; Version: 4.62 ;; ;; This file is part of GNU Emacs. ;; @@ -61,6 +61,24 @@ ;; ;; Recent changes ;; -------------- +;; Version 4.62 +;; - Many changes to the spreadsheet functions in the table editor. +;; For deatils, please re-read the manual section 3.4. +;; + New Features +;; - It is much easier to assign formulas to individual fields. +;; - References to arbitrary fields and ranges. +;; - Absolute references are modified in row-editing commands. +;; - Formula editor that highlights referenced fields. +;; + Incompatible changes +;; - Empty fields are excluded in range references, see "E" mode flag. +;; - &... ranges no longer supported, use new @... ranges. +;; - Variable insertion into Lisp formulas work differently. +;; - Selected text becomes the default description for C-c C-l links.(Scott) +;; - The date format in the agenda/timeline views is now customizable. +;; See the new option `org-agenda-date-format'. (request by Victor) +;; - Link abbreviations no longer need a double colon, single colon is fine. +;; - Bug fixes. +;; ;; Version 4.61 ;; - Avoiding keybinding clashes with flyspell ;; - Archiving is now also on `C-C C-x C-s' (was just `C-c $') @@ -138,7 +156,7 @@ ;;; Version -(defvar org-version "4.61" +(defvar org-version "4.62" "The version number of the file org.el.") (defun org-version () (interactive) @@ -859,7 +877,9 @@ the command \\[org-table-eval-formula]." :group 'org-table-calculation :type 'boolean) - +;; FIXME this is also a variable that makes Org-mode files non-portable +;; Maybe I should have a #+ options for constants? +;; How about the SI/cgs issue? (defcustom org-table-formula-use-constants t "Non-nil means, interpret constants in formulas in tables. A constant looks like `$c' or `$Grav' and will be replaced before evaluation @@ -886,7 +906,8 @@ and then use it in an equation like `$1*$c'." "Non-nil means, calculate only with numbers in table formulas. Then all input fields will be converted to a number, and the result must also be a number. When nil, calc's full potential is available -in table calculations, including symbolics etc." +in table calculations, including symbolics etc. +It is more portable to set this mode uding the \"N\" mode switch in formulas," :group 'org-table-calculation :type 'boolean) @@ -912,7 +933,7 @@ The car of each element is a string, to be replaced at the start of a link. The cdrs are replacement values, like (\"linkkey\" . REPLACE). Abbreviated links in Org-mode buffers can have an optional tag after a double colon, e.g. - [[linkkey::tag][description]] + [[linkkey:tag][description]] If REPLACE is a string, the tag will simply be appended to create the link. If the string contains \"%s\", the tag will be inserted there. REPLACE may @@ -1927,12 +1948,20 @@ When nil, always start on the current day." :group 'org-agenda-daily/weekly :type '(choice (const :tag "Today" nil) (number :tag "Weekday No."))) + (defcustom org-agenda-show-all-dates t "Non-nil means, `org-agenda' shows every day in the selected range. When nil, only the days which actually have entries are shown." :group 'org-agenda-daily/weekly :type 'boolean) +(defcustom org-agenda-date-format "%A %d %B %Y" + "Format string for displaying dates in the agenda. +Used by the daily/weekly agenda and by the timeline. This should be +a format string understood by `format-time-string'." + :group 'org-agenda-daily/weekly + :type 'string) + (defcustom org-agenda-include-diary nil "If non-nil, include in the agenda entries from the Emacs Calendar's diary." :group 'org-agenda-daily/weekly @@ -3083,7 +3112,7 @@ Also put tags into group 4 if tags are present.") (make-variable-buffer-local 'org-maybe-keyword-time-regexp) (defconst org-rm-props '(invisible t face t keymap t intangible t mouse-face t - rear-nonsticky t mouse-map t) + rear-nonsticky t mouse-map t fontified t) "Properties to remove when a string without properties is wanted.") (defsubst org-match-string-no-properties (num &optional string) @@ -3536,7 +3565,7 @@ The following commands are available: (org-update-radio-target-regexp) ;; Comment characters - (org-set-local 'comment-start "#") +; (org-set-local 'comment-start "#") ;; FIXME: this breaks wrapping (org-set-local 'comment-padding " ") ;; Make isearch reveal context @@ -4102,6 +4131,7 @@ between words." (outline-end-of-heading) (setq eoh (point)) (org-end-of-subtree t) (skip-chars-forward " \t\n") + (beginning-of-line 1) ; in case this is an item (setq eos (1- (point)))) ;; Find out what to do next and set `this-command' (cond @@ -4380,7 +4410,6 @@ frame is not changed." (let ((cbuf (current-buffer)) (cwin (selected-window)) (pos (point)) - (bname (buffer-name (current-buffer))) beg end level heading ibuf) (save-excursion (org-back-to-heading t) @@ -4537,18 +4566,6 @@ in the region." (org-demote))) (org-fix-position-after-promote)) -;; FIXME: check and remove -;(defun org-fix-position-after-promote () -; "Make sure that after pro/demotion cursor position is right." -; (if (and (or (eobp) (equal (char-after) ?\n)) -; (save-excursion -; (skip-chars-backward "a-zA-Z0-9_@") -; (looking-at org-todo-regexp))) -; (insert " ")) -; (and (equal (char-after) ?\ ) -; (equal (char-before) ?*) -; (forward-char 1))) - (defun org-fix-position-after-promote () "Make sure that after pro/demotion cursor position is right." (let ((pos (point))) @@ -5447,6 +5464,8 @@ with something like \"1.\" or \"2)\"." ;;;; Archiving +(defalias 'org-advertized-archive-subtree 'org-archive-subtree) + (defun org-archive-subtree (&optional find-done) "Move the current subtree to the archive. The archive can be a certain top-level heading in the current file, or in @@ -5717,6 +5736,39 @@ outside the table.") "Searching from within a table (any type) this finds the first line outside the table.") +(defvar org-table-last-highlighted-reference nil) +(defvar org-table-formula-history nil) + +(defvar org-table-column-names nil + "Alist with column names, derived from the `!' line.") +(defvar org-table-column-name-regexp nil + "Regular expression matching the current column names.") +(defvar org-table-local-parameters nil + "Alist with parameter names, derived from the `$' line.") +(defvar org-table-named-field-locations nil + "Alist with locations of named fields.") + +(defvar org-table-current-line-types nil + "Table row types, non-nil only for the duration of a comand.") +(defvar org-table-current-begin-line nil + "Table begin line, non-nil only for the duration of a comand.") +(defvar org-table-dlines nil + "Vector of data line line numbers in the current table.") +(defvar org-table-hlines nil + "Vector of hline line numbers in the current table.") + +(defconst org-table-range-regexp + "@\\([-+]?I*[-+]?[0-9]*\\)?\\(\\$[-+]?[0-9]+\\)?\\(\\.\\.@?\\([-+]?I*[-+]?[0-9]*\\)?\\(\\$[-+]?[0-9]+\\)?\\)?" + ;; 1 2 3 4 5 + "Regular expression for matching ranges in formulas.") + +(defconst org-table-range-regexp2 + "@\\([-+]?I*[-+]?[0-9]*\\)?\\(\\$[-+]?[a-zA-Z0-9]+\\)?\\(\\.\\.@?\\([-+]?I*[-+]?[0-9]*\\)?\\(\\$[-+]?[a-zA-Z0-9]+\\)?\\)?\\|\\$[a-zA-Z0-9]+\\.\\.\\$[a-zA-Z0-9]+" + "Regular expression to recognize ranges in formulas for highlighting.") + +(defvar org-inhibit-highlight-removal nil) + + (defun org-table-create-with-table.el () "Use the table.el package to insert a new table. If there is already a table at point, convert between Org-mode tables @@ -6277,12 +6329,36 @@ is always the old value." val) (forward-char 1) "")) -(defun org-table-field-info () - (interactive) - (let ((current (org-table-get-field)) - (col (org-table-current-column)) - (line (org-table-current-line))) - (message "Table data line %d, column %d" line col))) + +(defun org-table-field-info (arg) + "Show info about the current field, and highlight any reference at point." + (interactive "P") + (org-table-get-specials) + (save-excursion + (let* ((pos (point)) + (col (org-table-current-column)) + (cname (car (rassoc (int-to-string col) org-table-column-names))) + (name (car (rassoc (list (org-current-line) col) + org-table-named-field-locations))) + (eql (org-table-get-stored-formulas)) + (dline (org-table-current-dline)) + (ref (format "@%d$%d" dline col)) + (fequation (or (assoc name eql) (assoc ref eql))) + (cequation (assoc (int-to-string col) eql))) + (goto-char pos) + (condition-case nil + (org-show-reference 'local) + (error nil)) + (message "line @%d, col $%s%s, ref @%d$%d%s%s" + dline col + (if cname (concat " or $" cname) "") + dline col + (if name (concat " or $" name) "") + ;; FIXME: formula info not correct if special table line + (if (or fequation cequation) + (concat ", " (if fequation "field" "column") + " formula applies" "") + ""))))) (defun org-table-current-column () "Find out which column we are in. @@ -6297,15 +6373,15 @@ When called interactively, column is also displayed in echo area." (if (interactive-p) (message "This is table column %d" cnt)) cnt))) -(defun org-table-current-line () - "Find out what table line we are in. +(defun org-table-current-dline () + "Find out what table data line we are in. Only datalins count for this." (interactive) (if (interactive-p) (org-table-check-inside-data-field)) (save-excursion (let ((cnt 0) (pos (point))) (goto-char (org-table-begin)) - (while (< (point) pos) + (while (<= (point) pos) (if (looking-at org-table-dataline-regexp) (setq cnt (1+ cnt))) (beginning-of-line 2)) (if (interactive-p) (message "This is table line %d" cnt)) @@ -6408,7 +6484,7 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." (goto-line linepos) (org-table-goto-column colpos) (org-table-align) - (org-table-modify-formulas 'insert col))) + (org-table-fix-formulas "$" nil (1- col) 1))) (defun org-table-find-dataline () "Find a dataline in the current table, which is needed for column commands." @@ -6454,7 +6530,8 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." (goto-line linepos) (org-table-goto-column colpos) (org-table-align) - (org-table-modify-formulas 'remove col))) + (org-table-fix-formulas "$" (list (cons (number-to-string col) "INVALID")) + col -1 col))) (defun org-table-move-column-right () "Move column to the right." @@ -6495,7 +6572,9 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." (goto-line linepos) (org-table-goto-column colpos) (org-table-align) - (org-table-modify-formulas 'swap col (if left (1- col) (1+ col))))) + (org-table-fix-formulas + "$" (list (cons (number-to-string col) (number-to-string colpos)) + (cons (number-to-string colpos) (number-to-string col)))))) (defun org-table-move-row-down () "Move table row down." @@ -6509,15 +6588,19 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." (defun org-table-move-row (&optional up) "Move the current table line down. With arg UP, move it up." (interactive "P") - (let ((col (current-column)) - (pos (point)) - (tonew (if up 0 2)) - txt) + (let* ((col (current-column)) + (pos (point)) + (hline1p (save-excursion (beginning-of-line 1) + (looking-at org-table-hline-regexp))) + (dline1 (org-table-current-dline)) + (dline2 (+ dline1 (if up -1 1))) + (tonew (if up 0 2)) + txt hline2p) (beginning-of-line tonew) - (if (not (org-at-table-p)) - (progn - (goto-char pos) - (error "Cannot move row further"))) + (unless (org-at-table-p) + (goto-char pos) + (error "Cannot move row further")) + (setq hline2p (looking-at org-table-hline-regexp)) (goto-char pos) (beginning-of-line 1) (setq pos (point)) @@ -6526,7 +6609,11 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." (beginning-of-line tonew) (insert txt) (beginning-of-line 0) - (move-to-column col))) + (move-to-column col) + (unless (or hline1p hline2p) + (org-table-fix-formulas + "@" (list (cons (number-to-string dline1) (number-to-string dline2)) + (cons (number-to-string dline2) (number-to-string dline1))))))) (defun org-table-insert-row (&optional arg) "Insert a new row above the current line into the table. @@ -6543,7 +6630,8 @@ With prefix ARG, insert below the current line." (let (org-table-may-need-update) (insert-before-markers new "\n")) (beginning-of-line 0) (re-search-forward "| ?" (point-at-eol) t) - (and org-table-may-need-update (org-table-align)))) + (and org-table-may-need-update (org-table-align)) + (org-table-fix-formulas "@" nil (1- (org-table-current-dline)) 1))) (defun org-table-insert-hline (&optional arg) "Insert a horizontal-line below the current line into the table. @@ -6582,10 +6670,14 @@ In particular, this does handle wide and invisible characters." (interactive) (if (not (org-at-table-p)) (error "Not at a table")) - (let ((col (current-column))) + (let ((col (current-column)) + (dline (org-table-current-dline))) (kill-region (point-at-bol) (min (1+ (point-at-eol)) (point-max))) (if (not (org-at-table-p)) (beginning-of-line 0)) - (move-to-column col))) + (move-to-column col) + (org-table-fix-formulas "@" (list (cons (number-to-string dline) "INVALID")) + dline -1 dline))) + (defun org-table-sort-lines (with-case &optional sorting-type) "Sort table lines according to the column at point. @@ -7063,101 +7155,40 @@ If NLAST is a number, only the NLAST fields will actually be summed." ((equal n 0) nil) (t n)))) -(defun org-table-get-vertical-vector (desc &optional tbeg col) - "Get a calc vector from a column, accorting to descriptor DESC. -Optional arguments TBEG and COL can give the beginning of the table and -the current column, to avoid unnecessary parsing." - (save-excursion - (or tbeg (setq tbeg (org-table-begin))) - (or col (setq col (org-table-current-column))) - (let (beg end nn n n1 n2 l (thisline (org-current-line)) hline-list) - (cond - ((string-match "\\(I+\\)\\(-\\(I+\\)\\)?" desc) - (setq n1 (- (match-end 1) (match-beginning 1))) - (if (match-beginning 3) - (setq n2 (- (match-end 2) (match-beginning 3)))) - (setq n (if n2 (max n1 n2) n1)) - (setq n1 (if n2 (min n1 n2))) - (setq nn n) - (while (and (> nn 0) - (re-search-backward org-table-hline-regexp tbeg t)) - (push (org-current-line) hline-list) - (setq nn (1- nn))) - (setq hline-list (nreverse hline-list)) - (goto-line (nth (1- n) hline-list)) - (when (re-search-forward org-table-dataline-regexp) - (org-table-goto-column col) - (setq beg (point))) - (goto-line (if n1 (nth (1- n1) hline-list) thisline)) - (when (re-search-backward org-table-dataline-regexp) - (org-table-goto-column col) - (setq end (point))) - (setq l (apply 'append (org-table-copy-region beg end))) - (concat "[" (mapconcat (lambda (x) (setq x (org-trim x)) - (if (equal x "") "0" x)) - l ",") "]")) - ((string-match "\\([0-9]+\\)-\\([0-9]+\\)" desc) - (setq n1 (string-to-number (match-string 1 desc)) - n2 (string-to-number (match-string 2 desc))) - (beginning-of-line 1) - (save-excursion - (when (re-search-backward org-table-dataline-regexp tbeg t n1) - (org-table-goto-column col) - (setq beg (point)))) - (when (re-search-backward org-table-dataline-regexp tbeg t n2) - (org-table-goto-column col) - (setq end (point))) - (setq l (apply 'append (org-table-copy-region beg end))) - (concat "[" (mapconcat - (lambda (x) (setq x (org-trim x)) - (if (equal x "") "0" x)) - l ",") "]")) - ((string-match "\\([0-9]+\\)" desc) - (beginning-of-line 1) - (when (re-search-backward org-table-dataline-regexp tbeg t - (string-to-number (match-string 0 desc))) - (org-table-goto-column col) - (org-trim (org-table-get-field)))))))) - -(defvar org-table-formula-history nil) - -(defvar org-table-column-names nil - "Alist with column names, derived from the `!' line.") -(defvar org-table-column-name-regexp nil - "Regular expression matching the current column names.") -(defvar org-table-local-parameters nil - "Alist with parameter names, derived from the `$' line.") -(defvar org-table-named-field-locations nil - "Alist with locations of named fields.") - (defun org-table-current-field-formula () "Return the formula active for the current field. Assumes that specials are in place." (let* ((name (car (rassoc (list (org-current-line) (org-table-current-column)) org-table-named-field-locations))) - (scol (if name name - (int-to-string (org-table-current-column)))) + (col (org-table-current-column)) + (scol (int-to-string col)) + (ref (format "@%d$%d" (org-table-current-dline) col)) (stored-list (org-table-get-stored-formulas)) - (stored (cdr (assoc scol stored-list)))) - (if stored (concat (if name ":=" "=") stored)))) + (ass (or (assoc name stored-list) + (assoc ref stored-list) + (assoc scol stored-list)))) + (if ass (concat (if (string-match "^[0-9]+$" (car ass)) "=" ":=") + (cdr ass))))) (defun org-table-get-formula (&optional equation named) "Read a formula from the minibuffer, offer stored formula as default. -When NAMED is non-nil, look for a named equation. -When JUST-RETURN is non-nil, return equation without prompting." - (let* ((name (car (rassoc (list (org-current-line) +When NAMED is non-nil, look for a named equation." + (let* ((stored-list (org-table-get-stored-formulas)) + (name (car (rassoc (list (org-current-line) (org-table-current-column)) org-table-named-field-locations))) + (ref (format "@%d$%d" (org-table-current-dline) + (org-table-current-column))) + (refass (assoc ref stored-list)) (scol (if named - (if name name - (error "Not in a named field")) + (if name name ref) (int-to-string (org-table-current-column)))) - (dummy (and name (not named) - (not (y-or-n-p "Replace named-field formula with column equation? " )) - (error "Abort"))) + (dummy (and (or name refass) (not named) + (not (y-or-n-p "Replace field formula with column formula? " )) + (error "Abort"))) + (name (or name ref)) (org-table-may-need-update nil) - (stored-list (org-table-get-stored-formulas)) (stored (cdr (assoc scol stored-list))) (eq (cond ((and stored equation (string-match "^ *=? *$" equation)) @@ -7197,7 +7228,9 @@ When JUST-RETURN is non-nil, return equation without prompting." (delete-region (point) (match-end 0))) (insert "#+TBLFM: " (mapconcat (lambda (x) - (concat "$" (car x) "=" (cdr x))) + (concat + (if (equal (string-to-char (car x)) ?@) "" "$") + (car x) "=" (cdr x))) alist "::") "\n"))) @@ -7210,75 +7243,53 @@ When JUST-RETURN is non-nil, return equation without prompting." (when (looking-at "\\([ \t]*\n\\)*#\\+TBLFM: *\\(.*\\)") (setq strings (org-split-string (match-string 2) " *:: *")) (while (setq string (pop strings)) - (when (string-match "\\$\\([a-zA-Z0-9]+\\) *= *\\(.*[^ \t]\\)" string) - (setq scol (match-string 1 string) - eq (match-string 2 string) + (when (string-match "\\(@[0-9]+\\$[0-9]+\\|\\$\\([a-zA-Z0-9]+\\)\\) *= *\\(.*[^ \t]\\)" string) + (setq scol (if (match-end 2) + (match-string 2 string) + (match-string 1 string)) + eq (match-string 3 string) eq-alist (cons (cons scol eq) eq-alist)) (if (member scol seen) (error "Double definition `$%s=' in TBLFM line, please fix by hand" scol) (push scol seen)))))) (nreverse eq-alist))) -(defun org-table-modify-formulas (action &rest columns) - "Modify the formulas stored below the current table. -ACTION can be `remove', `insert', `swap'. For `swap', two column numbers are -expected, for the other actions only a single column number is needed." - (let ((list (org-table-get-stored-formulas)) - (nmax (length (org-split-string - (buffer-substring (point-at-bol) (point-at-eol)) - "|"))) - col col1 col2 scol si sc1 sc2) - (cond - ((null list)) ; No action needed if there are no stored formulas - ((eq action 'remove) - (setq col (car columns) - scol (int-to-string col)) - (org-table-replace-in-formulas list scol "INVALID") - (if (assoc scol list) (setq list (delq (assoc scol list) list))) - (loop for i from (1+ col) upto nmax by 1 do - (setq si (int-to-string i)) - (org-table-replace-in-formulas list si (int-to-string (1- i))) - (if (assoc si list) (setcar (assoc si list) - (int-to-string (1- i)))))) - ((eq action 'insert) - (setq col (car columns)) - (loop for i from nmax downto col by 1 do - (setq si (int-to-string i)) - (org-table-replace-in-formulas list si (int-to-string (1+ i))) - (if (assoc si list) (setcar (assoc si list) - (int-to-string (1+ i)))))) - ((eq action 'swap) - (setq col1 (car columns) col2 (nth 1 columns) - sc1 (int-to-string col1) sc2 (int-to-string col2)) - ;; Hopefully, ZqZtZ will never be a name in a table - (org-table-replace-in-formulas list sc1 "ZqZtZ") - (org-table-replace-in-formulas list sc2 sc1) - (org-table-replace-in-formulas list "ZqZtZ" sc2) - (if (assoc sc1 list) (setcar (assoc sc1 list) "ZqZtZ")) - (if (assoc sc2 list) (setcar (assoc sc2 list) sc1)) - (if (assoc "ZqZtZ" list) (setcar (assoc "ZqZtZ" list) sc2))) - (t (error "Invalid action in `org-table-modify-formulas'"))) - (if list (org-table-store-formulas list)))) - -(defun org-table-replace-in-formulas (list s1 s2) - (let (elt re s) - (setq s1 (concat "$" (if (integerp s1) (int-to-string s1) s1)) - s2 (concat "$" (if (integerp s2) (int-to-string s2) s2)) - re (concat (regexp-quote s1) "\\>")) - (while (setq elt (pop list)) - (setq s (cdr elt)) - (while (string-match re s) - (setq s (replace-match s2 t t s))) - (setcdr elt s)))) +(defun org-table-fix-formulas (key replace &optional limit delta remove) + "Modify the equations after the table structure has been edited. +KEY is \"@\" or \"$\". REPLACE is an alist of numbers to replace. +For all numbers larger than LIMIT, shift them by DELTA." + (save-excursion + (goto-char (org-table-end)) + (when (looking-at "#\\+TBLFM:") + (let ((re (concat key "\\([0-9]+\\)")) + (re2 + (when remove + (if (equal key "$") + (format "\\(@[0-9]+\\)?\\$%d=.*?\\(::\\|$\\)" remove) + (format "@%d\\$[0-9]+=.*?\\(::\\|$\\)" remove)))) + s n a) + (when remove + (while (re-search-forward re2 (point-at-eol) t) + (replace-match ""))) + (while (re-search-forward re (point-at-eol) t) + (setq s (match-string 1) n (string-to-number s)) + (cond + ((setq a (assoc s replace)) + (replace-match (concat key (cdr a)) t t)) + ((and limit (> n limit)) + (replace-match (concat key (int-to-string (+ n delta))) t t)))))))) (defun org-table-get-specials () "Get the column names and local parameters for this table." (save-excursion (let ((beg (org-table-begin)) (end (org-table-end)) - names name fields fields1 field cnt c v line col) + names name fields fields1 field cnt + c v l line col types dlines hlines) (setq org-table-column-names nil org-table-local-parameters nil - org-table-named-field-locations nil) + org-table-named-field-locations nil + org-table-current-begin-line nil + org-table-current-line-types nil) (goto-char beg) (when (re-search-forward "^[ \t]*| *! *\\(|.*\\)" end t) (setq names (org-split-string (match-string 1) " *| *") @@ -7311,7 +7322,19 @@ expected, for the other actions only a single column number is needed." (when (and (stringp field) (stringp v) (string-match "^[a-zA-Z][a-zA-Z0-9]*$" field)) (push (cons field v) org-table-local-parameters) - (push (list field line col) org-table-named-field-locations))))))) + (push (list field line col) org-table-named-field-locations)))) + ;; Analyse the line types + (goto-char beg) + (setq org-table-current-begin-line (org-current-line) + l org-table-current-begin-line) + (while (looking-at "[ \t]*|\\(-\\)?") + (push (if (match-end 1) 'hline 'dline) types) + (if (match-end 1) (push l hlines) (push l dlines)) + (beginning-of-line 2) + (setq l (1+ l))) + (setq org-table-current-line-types (apply 'vector (nreverse types)) + org-table-dlines (apply 'vector (cons nil (nreverse dlines))) + org-table-hlines (apply 'vector (cons nil (nreverse hlines))))))) (defun org-this-word () ;; Get the current word @@ -7417,7 +7440,6 @@ of the new mark." (equal org-last-recalc-line (org-current-line)))) (save-excursion (beginning-of-line 1) (looking-at org-table-auto-recalculate-regexp)) - ;; (fboundp 'calc-eval) ;; FIXME: correct to remove this? (org-table-recalculate) t)) (defvar org-table-formula-debug nil @@ -7439,7 +7461,7 @@ When nil, simply write \"#ERROR\" in corrupted fields.") (defun org-table-eval-formula (&optional arg equation suppress-align suppress-const - suppress-store) + suppress-store suppress-analysis) "Replace the table field value at the cursor by the result of a calculation. This function makes use of Dave Gillespie's Calc package, in my view the @@ -7454,8 +7476,8 @@ formula is installed as valid in only this specific field. When called with two `C-u' prefixes, insert the active equation for the field back into the current field, so that it can be -edited there. This is useful in order to use \\[org-show-variable] to check -the referenced fields. +edited there. This is useful in order to use \\[org-show-reference] +to check the referenced fields. When called, the command first prompts for a formula, which is read in the minibuffer. Previously entered formulas are available through the @@ -7477,7 +7499,7 @@ it is already stored, or because it is a modified equation that should not overwrite the stored one." (interactive "P") (org-table-check-inside-data-field) - (org-table-get-specials) + (or suppress-analysis (org-table-get-specials)) (if (equal arg '(16)) (let ((eq (org-table-current-field-formula))) (or eq (error "No equation active for current field")) @@ -7494,7 +7516,9 @@ not overwrite the stored one." (org-table-get-formula equation (equal arg '(4))))) (n0 (org-table-current-column)) (modes (copy-sequence org-calc-default-modes)) - n form fmt x ev orig c lispp) + (numbers org-table-formula-numbers-only) + (keep-empty nil) + n form form0 bw fmt x ev orig c lispp) ;; Parse the format string. Since we have a lot of modes, this is ;; a lot of work. However, I think calc still uses most of the time. (if (string-match ";" formula) @@ -7513,6 +7537,12 @@ not overwrite the stored one." (?s . sci) (?e . eng)))) n)))) (setq fmt (replace-match "" t t fmt))) + (if (string-match "[NT]" fmt) + (setq numbers (equal (match-string 0 fmt) "N") + fmt (replace-match "" t t fmt))) + (if (string-match "E" fmt) + (setq keep-empty t + fmt (replace-match "" t t fmt))) (while (string-match "[DRFS]" fmt) (setq modes (org-set-calc-mode (match-string 0 fmt))) (setq fmt (replace-match "" t t fmt))) @@ -7523,15 +7553,39 @@ not overwrite the stored one." (setq orig (or (get-text-property 1 :orig-formula formula) "?")) (while (> ndown 0) (setq fields (org-split-string - (buffer-substring - (point-at-bol) (point-at-eol)) " *| *")) - (if org-table-formula-numbers-only + (org-no-properties + (buffer-substring (point-at-bol) (point-at-eol))) + " *| *")) + (if numbers (setq fields (mapcar (lambda (x) (number-to-string (string-to-number x))) fields))) (setq ndown (1- ndown)) (setq form (copy-sequence formula) lispp (and (> (length form) 2)(equal (substring form 0 2) "'("))) + ;; Check for old vertical references + (setq form (org-rewrite-old-row-references form)) + ;; Insert complex ranges + (while (string-match org-table-range-regexp form) + (setq form + (replace-match + (save-match-data + (org-table-make-reference + (org-table-get-range (match-string 0 form) nil n0) + keep-empty numbers lispp)) + t t form))) + ;; Insert simple ranges + (while (string-match "\\$\\([0-9]+\\)\\.\\.\\$\\([0-9]+\\)" form) + (setq form + (replace-match + (save-match-data + (org-table-make-reference + (org-sublist + fields (string-to-number (match-string 1 form)) + (string-to-number (match-string 2 form))) + keep-empty numbers lispp)) + t t form))) + (setq form0 form) ;; Insert the references to fields in same row (while (string-match "\\$\\([0-9]+\\)?" form) (setq n (if (match-beginning 1) @@ -7540,44 +7594,41 @@ not overwrite the stored one." x (nth (1- n) fields)) (unless x (error "Invalid field specifier \"%s\"" (match-string 0 form))) - (if (equal x "") (setq x "0")) - (setq form (replace-match - (if lispp x (concat "(" x ")")) - t t form))) - ;; Insert ranges in current column - (while (string-match "\\&[-I0-9]+" form) (setq form (replace-match (save-match-data - (org-table-get-vertical-vector (match-string 0 form) - nil n0)) + (org-table-make-reference x nil numbers lispp)) t t form))) (if lispp - (setq ev (eval (eval (read form))) + (setq ev (condition-case nil + (eval (eval (read form))) + (error "#ERROR")) ev (if (numberp ev) (number-to-string ev) ev)) (or (fboundp 'calc-eval) (error "Calc does not seem to be installed, and is needed to evaluate the formula")) (setq ev (calc-eval (cons form modes) - (if org-table-formula-numbers-only 'num)))) + (if numbers 'num)))) (when org-table-formula-debug - (with-output-to-temp-buffer "*Help*" + (with-output-to-temp-buffer "*Substitution History*" (princ (format "Substitution history of formula Orig: %s $xyz-> %s -$1-> %s\n" orig formula form)) +@r$c-> %s +$1-> %s\n" orig formula form0 form)) (if (listp ev) (princ (format " %s^\nError: %s" (make-string (car ev) ?\-) (nth 1 ev))) (princ (format "Result: %s\nFormat: %s\nFinal: %s" ev (or fmt "NONE") (if fmt (format fmt (string-to-number ev)) ev))))) - (shrink-window-if-larger-than-buffer (get-buffer-window "*Help*")) + (setq bw (get-buffer-window "*Substitution History*")) + (shrink-window-if-larger-than-buffer bw) (unless (and (interactive-p) (not ndown)) (unless (let (inhibit-redisplay) (y-or-n-p "Debugging Formula. Continue to next? ")) (org-table-align) (error "Abort")) - (delete-window (get-buffer-window "*Help*")) + (delete-window bw) (message ""))) (if (listp ev) (setq fmt nil ev "#ERROR")) (org-table-justify-field-maybe @@ -7589,6 +7640,147 @@ $1-> %s\n" orig formula form)) (or suppress-align (and org-table-may-need-update (org-table-align)))))) +(defun org-table-get-range (desc &optional tbeg col highlight) + "Get a calc vector from a column, accorting to descriptor DESC. +Optional arguments TBEG and COL can give the beginning of the table and +the current column, to avoid unnecessary parsing. +HIGHLIGHT means, just highlight the range." + (if (not (equal (string-to-char desc) ?@)) + (setq desc (concat "@" desc))) + (save-excursion + (or tbeg (setq tbeg (org-table-begin))) + (or col (setq col (org-table-current-column))) + (let ((thisline (org-current-line)) + beg end c1 c2 r1 r2 rangep tmp) + (unless (string-match org-table-range-regexp desc) + (error "Invalid table range specifier `%s'" desc)) + (setq rangep (match-end 3) + r1 (and (match-end 1) (match-string 1 desc)) + r2 (and (match-end 4) (match-string 4 desc)) + c1 (and (match-end 2) (substring (match-string 2 desc) 1)) + c2 (and (match-end 5) (substring (match-string 5 desc) 1))) + + (and c1 (setq c1 (+ (string-to-number c1) + (if (memq (string-to-char c1) '(?- ?+)) col 0)))) + (and c2 (setq c2 (+ (string-to-number c2) + (if (memq (string-to-char c2) '(?- ?+)) col 0)))) + (if (equal r1 "") (setq r1 nil)) + (if (equal r2 "") (setq r2 nil)) + (if r1 (setq r1 (org-table-get-descriptor-line r1))) + (if r2 (setq r2 (org-table-get-descriptor-line r2))) +; (setq r2 (or r2 r1) c2 (or c2 c1)) + (if (not r1) (setq r1 thisline)) + (if (not r2) (setq r2 thisline)) + (if (not c1) (setq c1 col)) + (if (not c2) (setq c2 col)) + (if (or (not rangep) (and (= r1 r2) (= c1 c2))) + ;; just one field + (progn + (goto-line r1) + (while (not (looking-at org-table-dataline-regexp)) + (beginning-of-line 2)) + (prog1 (org-table-get-field c1) + (if highlight (org-table-highlight-rectangle (point) (point))))) + ;; A range, return a vector + ;; First sort the numbers to get a regular ractangle + (if (< r2 r1) (setq tmp r1 r1 r2 r2 tmp)) + (if (< c2 c1) (setq tmp c1 c1 c2 c2 tmp)) + (goto-line r1) + (while (not (looking-at org-table-dataline-regexp)) + (beginning-of-line 2)) + (org-table-goto-column c1) + (setq beg (point)) + (goto-line r2) + (while (not (looking-at org-table-dataline-regexp)) + (beginning-of-line 0)) + (org-table-goto-column c2) + (setq end (point)) + (if highlight + (org-table-highlight-rectangle + beg (progn (skip-chars-forward "^|\n") (point)))) + ;; return string representation of calc vector + (apply 'append (org-table-copy-region beg end)))))) + +(defun org-table-get-descriptor-line (desc &optional cline bline table) + "Analyze descriptor DESC and retrieve the corresponding line number. +The cursor is currently in line CLINE, the table begins in line BLINE, +and TABLE is a vector with line types." + (if (string-match "^[0-9]+$" desc) + (aref org-table-dlines (string-to-number desc)) + (setq cline (or cline (org-current-line)) + bline (or bline org-table-current-begin-line) + table (or table org-table-current-line-types)) + (if (or + (not (string-match "^\\(\\([-+]\\)?\\(I+\\)\\)?\\(\\([-+]\\)?\\([0-9]+\\)\\)?" desc)) + ;; 1 2 3 4 5 6 + (and (not (match-end 3)) (not (match-end 6))) + (and (match-end 3) (match-end 6) (not (match-end 5)))) + (error "invalid row descriptor `%s'" desc)) + (let* ((hdir (and (match-end 2) (match-string 2 desc))) + (hn (if (match-end 3) (- (match-end 3) (match-beginning 3)) nil)) + (odir (and (match-end 5) (match-string 5 desc))) + (on (if (match-end 6) (string-to-number (match-string 6 desc)))) + (i (- cline bline)) + (rel (and (match-end 6) + (or (and (match-end 1) (not (match-end 3))) + (match-end 5))))) + (if (and hn (not hdir)) + (progn + (setq i 0 hdir "+") + (if (eq (aref table 0) 'hline) (setq hn (1- hn))))) + (if (and (not hn) on (not odir)) + (error "should never happen");;(aref org-table-dlines on) FIXME + (if (and hn (> hn 0)) + (setq i (org-find-row-type table i 'hline (equal hdir "-") nil hn))) + (if on + (setq i (org-find-row-type table i 'dline (equal odir "-") rel on))) + (+ bline i))))) + +(defun org-find-row-type (table i type backwards relative n) + (let ((l (length table))) + (while (> n 0) + (while (and (setq i (+ i (if backwards -1 1))) + (>= i 0) (< i l) + (not (eq (aref table i) type)) + (if (and relative (eq (aref table i) 'hline)) + (progn (setq i (- i (if backwards -1 1)) n 1) nil) + t))) + (setq n (1- n))) + (if (or (< i 0) (>= i l)) + (error "Row descriptior leads outside table") + i))) + +(defun org-rewrite-old-row-references (s) + (if (string-match "&[-+0-9I]" s) + (error "Formula contains old &row reference, please rewrite using @-syntax") + s)) + +(defun org-table-make-reference (elements keep-empty numbers lispp) + "Convert list ELEMENTS to something appropriate to insert into formula. +KEEP-EMPTY indicated to keep empty fields, default is to skip them. +NUMBERS indicates that everything should be converted to numbers. +LISPP means to return something appropriate for a Lisp list." + (if (stringp elements) ; just a single val + (if lispp + (prin1-to-string (if numbers (string-to-number elements) elements)) + (if (equal elements "") (setq elements "0")) + (if numbers (number-to-string (string-to-number elements)) elements)) + (unless keep-empty + (setq elements + (delq nil + (mapcar (lambda (x) (if (string-match "\\S-" x) x nil)) + elements)))) + (setq elements (or elements '("0"))) + (if lispp + (mapconcat 'prin1-to-string + (if numbers (mapcar 'string-to-number elements) elements) + " ") + (concat "[" (mapconcat + (lambda (x) + (if numbers (number-to-string (string-to-number x)) x)) + elements + ",") "]")))) + (defun org-table-recalculate (&optional all noalign) "Recalculate the current table line by applying all stored formulas. With prefix arg ALL, do this for all lines in the table." @@ -7596,92 +7788,113 @@ With prefix arg ALL, do this for all lines in the table." (or (memq this-command org-recalc-commands) (setq org-recalc-commands (cons this-command org-recalc-commands))) (unless (org-at-table-p) (error "Not at a table")) - (org-table-get-specials) - (let* ((eqlist (sort (org-table-get-stored-formulas) - (lambda (a b) (string< (car a) (car b))))) - (inhibit-redisplay t) - (line-re org-table-dataline-regexp) - (thisline (org-current-line)) - (thiscol (org-table-current-column)) - beg end entry eqlnum eqlname eql (cnt 0) eq a name) - ;; Insert constants in all formulas - (setq eqlist - (mapcar (lambda (x) - (setcdr x (org-table-formula-substitute-names (cdr x))) - x) - eqlist)) - ;; Split the equation list - (while (setq eq (pop eqlist)) - (if (<= (string-to-char (car eq)) ?9) - (push eq eqlnum) - (push eq eqlname))) - (setq eqlnum (nreverse eqlnum) eqlname (nreverse eqlname)) - (if all - (progn - (setq end (move-marker (make-marker) (1+ (org-table-end)))) - (goto-char (setq beg (org-table-begin))) - (if (re-search-forward org-table-calculate-mark-regexp end t) - ;; This is a table with marked lines, only compute selected lines - (setq line-re org-table-recalculate-regexp) - ;; Move forward to the first non-header line - (if (and (re-search-forward org-table-dataline-regexp end t) - (re-search-forward org-table-hline-regexp end t) - (re-search-forward org-table-dataline-regexp end t)) - (setq beg (match-beginning 0)) - nil))) ;; just leave beg where it is - (setq beg (point-at-bol) - end (move-marker (make-marker) (1+ (point-at-eol))))) - (goto-char beg) - (and all (message "Re-applying formulas to full table...")) - (while (re-search-forward line-re end t) - (unless (string-match "^ *[_^!$] *$" (org-table-get-field 1)) - ;; Unprotected line, recalculate - (and all (message "Re-applying formulas to full table...(line %d)" - (setq cnt (1+ cnt)))) - (setq org-last-recalc-line (org-current-line)) - (setq eql eqlnum) - (while (setq entry (pop eql)) - (goto-line org-last-recalc-line) - (org-table-goto-column (string-to-number (car entry)) nil 'force) - (org-table-eval-formula nil (cdr entry) 'noalign 'nocst 'nostore)))) - (goto-line thisline) - (org-table-goto-column thiscol) - (or noalign (and org-table-may-need-update (org-table-align)) - (and all (message "Re-applying formulas to %d lines...done" cnt))) - ;; Now do the names fields - (while (setq eq (pop eqlname)) - (setq name (car eq) - a (assoc name org-table-named-field-locations)) - (when a - (message "Re-applying formula to named field: %s" name) - (goto-line (nth 1 a)) - (org-table-goto-column (nth 2 a)) - (org-table-eval-formula nil (cdr eq) 'noalign 'nocst 'nostore))) - ;; back to initial position - (goto-line thisline) - (org-table-goto-column thiscol) - (or noalign (and org-table-may-need-update (org-table-align)) - (and all (message "Re-applying formulas...done"))))) + (if (equal all '(16)) + (org-table-iterate) + (org-table-get-specials) + (let* ((eqlist (sort (org-table-get-stored-formulas) + (lambda (a b) (string< (car a) (car b))))) + (inhibit-redisplay (not debug-on-error)) + (line-re org-table-dataline-regexp) + (thisline (org-current-line)) + (thiscol (org-table-current-column)) + beg end entry eqlnum eqlname eql (cnt 0) eq a name) + ;; Insert constants in all formulas + (setq eqlist + (mapcar (lambda (x) + (setcdr x (org-table-formula-substitute-names (cdr x))) + x) + eqlist)) + ;; Split the equation list + (while (setq eq (pop eqlist)) + (if (<= (string-to-char (car eq)) ?9) + (push eq eqlnum) + (push eq eqlname))) + (setq eqlnum (nreverse eqlnum) eqlname (nreverse eqlname)) + (if all + (progn + (setq end (move-marker (make-marker) (1+ (org-table-end)))) + (goto-char (setq beg (org-table-begin))) + (if (re-search-forward org-table-calculate-mark-regexp end t) + ;; This is a table with marked lines, compute selected lines + (setq line-re org-table-recalculate-regexp) + ;; Move forward to the first non-header line + (if (and (re-search-forward org-table-dataline-regexp end t) + (re-search-forward org-table-hline-regexp end t) + (re-search-forward org-table-dataline-regexp end t)) + (setq beg (match-beginning 0)) + nil))) ;; just leave beg where it is + (setq beg (point-at-bol) + end (move-marker (make-marker) (1+ (point-at-eol))))) + (goto-char beg) + (and all (message "Re-applying formulas to full table...")) + (while (re-search-forward line-re end t) + (unless (string-match "^ *[_^!$] *$" (org-table-get-field 1)) + ;; Unprotected line, recalculate + (and all (message "Re-applying formulas to full table...(line %d)" + (setq cnt (1+ cnt)))) + (setq org-last-recalc-line (org-current-line)) + (setq eql eqlnum) + (while (setq entry (pop eql)) + (goto-line org-last-recalc-line) + (org-table-goto-column (string-to-number (car entry)) nil 'force) + (org-table-eval-formula nil (cdr entry) + 'noalign 'nocst 'nostore 'noanalysis)))) + (goto-line thisline) + (org-table-goto-column thiscol) + (or noalign (and org-table-may-need-update (org-table-align)) + (and all (message "Re-applying formulas to %d lines...done" cnt))) + ;; Now do the named fields + (while (setq eq (pop eqlname)) + (setq name (car eq) + a (assoc name org-table-named-field-locations)) + (and (not a) + (string-match "@\\([0-9]+\\)\\$\\([0-9]+\\)" name) + (setq a + (list + name + (aref org-table-dlines + (string-to-number (match-string 1 name))) + (string-to-number (match-string 2 name))))) + (when (and a (or all (equal (nth 1 a) thisline))) + (message "Re-applying formula to field: %s" name) + (goto-line (nth 1 a)) + (org-table-goto-column (nth 2 a)) + (org-table-eval-formula nil (cdr eq) 'noalign 'nocst + 'nostore 'noanalysis))) + ;; back to initial position + (goto-line thisline) + (org-table-goto-column thiscol) + (or noalign (and org-table-may-need-update (org-table-align)) + (and all (message "Re-applying formulas...done")))))) + +(defun org-table-iterate (&optional arg) + "Recalculate the table until it does not change anymore." + (interactive "P") + (let ((imax (if arg (prefix-numeric-value arg) 10)) + (i 0) + (lasttbl (buffer-substring (org-table-begin) (org-table-end))) + thistbl) + (catch 'exit + (while (< i imax) + (setq i (1+ i)) + (org-table-recalculate 'all) + (setq thistbl (buffer-substring (org-table-begin) (org-table-end))) + (if (not (string= lasttbl thistbl)) + (setq lasttbl thistbl) + (if (> i 1) + (message "Convergence after %d iterations" i) + (message "Table was already stable")) + (throw 'exit t))) + (error "No convergence after %d iterations" i)))) (defun org-table-formula-substitute-names (f) "Replace $const with values in string F." - (let ((start 0) a n1 n2 nn1 nn2 s (f1 f)) + (let ((start 0) a (f1 f)) ;; First, check for column names (while (setq start (string-match org-table-column-name-regexp f start)) (setq start (1+ start)) (setq a (assoc (match-string 1 f) org-table-column-names)) (setq f (replace-match (concat "$" (cdr a)) t t f))) - ;; Expand ranges to vectors - (while (string-match "\\$\\([0-9]+\\)\\.\\.\\.?\\$\\([0-9]+\\)" f) - (setq n1 (string-to-number (match-string 1 f)) - n2 (string-to-number (match-string 2 f)) - nn1 (1+ (min n1 n2)) nn2 (max n1 n2) - s (concat "[($" (number-to-string (1- nn1)) ")")) - (loop for i from nn1 upto nn2 do - (setq s (concat s ",($" (int-to-string i) ")"))) - (setq s (concat s "]")) - (if (< n2 n1) (setq s (concat "rev(" s ")"))) - (setq f (replace-match s t t f))) ;; Parameters and constants (setq start 0) (while (setq start (string-match "\\$\\([a-zA-Z][a-zA-Z0-9]*\\)" f start)) @@ -7702,9 +7915,15 @@ Parameters get priority." "#UNDEFINED_NAME")) (defvar org-edit-formulas-map (make-sparse-keymap)) -(define-key org-edit-formulas-map "\C-c\C-c" 'org-finish-edit-formulas) -(define-key org-edit-formulas-map "\C-c\C-q" 'org-abort-edit-formulas) -(define-key org-edit-formulas-map "\C-c?" 'org-show-variable) +(define-key org-edit-formulas-map "\C-c\C-c" 'org-finish-edit-formulas) +(define-key org-edit-formulas-map "\C-c\C-q" 'org-abort-edit-formulas) +(define-key org-edit-formulas-map "\C-c?" 'org-show-reference) +(define-key org-edit-formulas-map [(shift up)] 'org-table-edit-line-up) +(define-key org-edit-formulas-map [(shift down)] 'org-table-edit-line-down) +(define-key org-edit-formulas-map [(shift left)] 'org-table-edit-backward-field) +(define-key org-edit-formulas-map [(shift right)] 'org-table-edit-next-field) +(define-key org-edit-formulas-map [(meta up)] 'org-table-edit-scroll-down) +(define-key org-edit-formulas-map [(meta down)] 'org-table-edit-scroll) (defvar org-pos) @@ -7716,99 +7935,48 @@ Parameters get priority." (let ((eql (org-table-get-stored-formulas)) (pos (move-marker (make-marker) (point))) (wc (current-window-configuration)) - entry loc s) + entry s) (switch-to-buffer-other-window "*Edit Formulas*") (erase-buffer) (fundamental-mode) (org-set-local 'org-pos pos) (org-set-local 'org-window-configuration wc) (use-local-map org-edit-formulas-map) - (setq s "# Edit formulas and finish with `C-c C-c'. -# Use `C-u C-c C-c' to also appy them immediately to the entire table. -# Use `C-c ?' to get information about $name at point. -# To cancel editing, press `C-c C-q'.\n") + (org-add-hook 'post-command-hook 'org-table-edit-formulas-post-command t t) + (setq s "# `C-c C-c' to finish, `C-u C-c C-c' to also apply, `C-c C-q' to abort. +# `M-up/down' to scroll table, `S-up/down' to change line for column formulas\n") + (put-text-property 0 (length s) 'face 'font-lock-comment-face s) (insert s) (while (setq entry (pop eql)) - (when (setq loc (assoc (car entry) org-table-named-field-locations)) - (setq s (format "# Named formula, referring to column %d in line %d\n" - (nth 2 loc) (nth 1 loc))) - (put-text-property 0 (length s) 'face 'font-lock-comment-face s) - (insert s)) - (setq s (concat "$" (car entry) "=" (cdr entry) "\n")) + (setq s (concat (if (equal (string-to-char (car entry)) ?@) "" "$") + (car entry) "=" (cdr entry) "\n")) (remove-text-properties 0 (length s) '(face nil) s) (insert s)) (goto-char (point-min)) (message "Edit formulas and finish with `C-c C-c'."))) -;; FIXME: make this work in fields, directly highlighting the referenced fields -(defun org-show-variable () - "Show the location/value of the $ expression at point." - (interactive) - (let (var (pos org-pos) (win (selected-window)) e) +(defun org-table-edit-formulas-post-command () + (let ((win (selected-window))) (save-excursion - (or (looking-at "\\$") (skip-chars-backward "$a-zA-Z0-9")) - (if (looking-at "\\$\\([a-zA-Z0-9]+\\)") - (setq var (match-string 1)) - (error "No variable at point"))) - (cond - ((setq e (assoc var org-table-named-field-locations)) - (switch-to-buffer-other-window (marker-buffer pos)) - (goto-line (nth 1 e)) - (org-table-goto-column (nth 2 e)) - (select-window win) - (message "Named field, column %d of line %d" (nth 2 e) (nth 1 e))) - ((setq e (assoc var org-table-column-names)) - (switch-to-buffer-other-window (marker-buffer pos)) - (goto-char pos) - (goto-char (org-table-begin)) - (if (re-search-forward (concat "^[ \t]*| *! *.*?| *\\(" var "\\) *|") - (org-table-end) t) - (progn - (goto-char (match-beginning 1)) - (message "Named column (column %s)" (cdr e))) - (error "Column name not found")) - (select-window win)) - ((string-match "^[0-9]$" var) - ;; column number - (switch-to-buffer-other-window (marker-buffer pos)) - (goto-char pos) - (goto-char (org-table-begin)) - (recenter 1) - (if (re-search-forward org-table-dataline-regexp - (org-table-end) t) - (progn - (goto-char (match-beginning 0)) - (org-table-goto-column (string-to-number var)) - (message "Column %s" var)) - (error "Column name not found")) - (select-window win)) - ((setq e (assoc var org-table-local-parameters)) - (switch-to-buffer-other-window (marker-buffer pos)) - (goto-char pos) - (goto-char (org-table-begin)) - (if (re-search-forward (concat "^[ \t]*| *\\$ *.*?| *\\(" var "=\\)") nil t) - (progn - (goto-char (match-beginning 1)) - (message "Local parameter.")) - (error "Parameter not found")) - (select-window win)) - (t - (cond - ((setq e (assoc var org-table-formula-constants)) - (message "Constant: $%s=%s in `org-table-formula-constants'." var (cdr e))) - ((setq e (and (fboundp 'constants-get) (constants-get var))) - (message "Constant: $%s=%s, retrieved from `constants.el'." var e)) - (t (error "Undefined name $%s" var))))))) + (condition-case nil + (org-show-reference) + (error nil)) + (select-window win)))) (defun org-finish-edit-formulas (&optional arg) "Parse the buffer for formula definitions and install them. With prefix ARG, apply the new formulas to the table." (interactive "P") + (org-table-remove-rectangle-highlight) (let ((pos org-pos) eql) + (setq org-pos nil) (goto-char (point-min)) - (while (re-search-forward "^\\$\\([a-zA-Z0-9]+\\) *= *\\(.*?\\) *$" nil t) - (push (cons (match-string 1) (match-string 2)) eql)) + (while (re-search-forward + "^\\(@[0-9]+\\$[0-9]+\\|\\$\\([a-zA-Z0-9]+\\)\\) *= *\\(.*?\\) *$" + nil t) + (push (cons (if (match-end 2) (match-string 2) (match-string 1)) + (match-string 3)) eql)) (set-window-configuration org-window-configuration) (select-window (get-buffer-window (marker-buffer pos))) (goto-char pos) @@ -7824,12 +7992,232 @@ With prefix ARG, apply the new formulas to the table." (defun org-abort-edit-formulas () "Abort editing formulas, without installing the changes." (interactive) + (org-table-remove-rectangle-highlight) (let ((pos org-pos)) (set-window-configuration org-window-configuration) (select-window (get-buffer-window (marker-buffer pos))) (goto-char pos) + (move-marker pos nil) (message "Formula editing aborted without installing changes"))) +(defvar org-show-positions nil) + +(defun org-show-reference (&optional local) + "Show the location/value of the $ expression at point." + (interactive) + (org-table-remove-rectangle-highlight) + (catch 'exit + (let ((pos (if local (point) org-pos)) + (face2 'highlight) + (org-inhibit-highlight-removal t) + (win (selected-window)) + (org-show-positions nil) + var name e what match dest) + (if local (org-table-get-specials)) + (setq what (cond + ((org-at-regexp-p org-table-range-regexp2) 'range) + ((org-at-regexp-p "\\$[a-zA-Z][a-zA-Z0-9]*") 'name) + ((org-at-regexp-p "\\$[0-9]+") 'column) + ((not local) nil) + (t (error "No reference at point"))) + match (and what (match-string 0))) + (when (and match (not (equal (match-beginning 0) (point-at-bol)))) + (org-table-add-rectangle-overlay (match-beginning 0) (match-end 0) + 'secondary-selection)) + (org-add-hook 'before-change-functions + 'org-table-remove-rectangle-highlight) + (if (eq what 'name) (setq var (substring match 1))) + (when (eq what 'range) + (or (equal (string-to-char match) ?@) (setq match (concat "@" match))) + (setq match (org-table-formula-substitute-names match))) + (unless local + (save-excursion + (beginning-of-line 1) + (when (looking-at "\\(\\$[0-9a-zA-Z]+\\|@[0-9]+\\$[0-9]+\\)=") + (setq dest (match-string 1)) + (org-table-add-rectangle-overlay + (match-beginning 1) (match-end 1) face2)))) + (if (and (markerp pos) (marker-buffer pos)) + (if (get-buffer-window (marker-buffer pos)) + (select-window (get-buffer-window (marker-buffer pos))) + (switch-to-buffer-other-window (get-buffer-window + (marker-buffer pos))))) + (goto-char pos) + (org-table-force-dataline) + (when dest + (setq name (substring dest 1)) + (cond + ((string-match "^\\$[a-zA-Z][a-zA-Z0-9]*" dest) + (setq e (assoc name org-table-named-field-locations)) + (goto-line (nth 1 e)) + (org-table-goto-column (nth 2 e))) + ((string-match "^@\\([0-9]+\\)\\$\\([0-9]+\\)" dest) + (let ((l (string-to-number (match-string 1 dest))) + (c (string-to-number (match-string 2 dest)))) + (goto-line (aref org-table-dlines l)) + (org-table-goto-column c))) + (t (org-table-goto-column (string-to-number name)))) + (move-marker pos (point)) + (org-table-highlight-rectangle nil nil face2)) + (cond + ((equal dest match)) + ((not match)) + ((eq what 'range) + (condition-case nil + (save-excursion + (org-table-get-range match nil nil 'highlight)) + (error nil))) + ((setq e (assoc var org-table-named-field-locations)) + (goto-line (nth 1 e)) + (org-table-goto-column (nth 2 e)) + (org-table-highlight-rectangle (point) (point)) + (message "Named field, column %d of line %d" (nth 2 e) (nth 1 e))) + ((setq e (assoc var org-table-column-names)) + (org-table-goto-column (string-to-number (cdr e))) + (org-table-highlight-rectangle (point) (point)) + (goto-char (org-table-begin)) + (if (re-search-forward (concat "^[ \t]*| *! *.*?| *\\(" var "\\) *|") + (org-table-end) t) + (progn + (goto-char (match-beginning 1)) + (org-table-highlight-rectangle) + (message "Named column (column %s)" (cdr e))) + (error "Column name not found"))) + ((eq what 'column) + ;; column number + (org-table-goto-column (string-to-number (substring match 1))) + (org-table-highlight-rectangle (point) (point)) + (message "Column %s" (substring match 1))) + ((setq e (assoc var org-table-local-parameters)) + (goto-char (org-table-begin)) + (if (re-search-forward (concat "^[ \t]*| *\\$ *.*?| *\\(" var "=\\)") nil t) + (progn + (goto-char (match-beginning 1)) + (org-table-highlight-rectangle) + (message "Local parameter.")) + (error "Parameter not found"))) + (t + (cond + ((not var) (error "No reference at point")) + ((setq e (assoc var org-table-formula-constants)) + (message "Constant: $%s=%s in `org-table-formula-constants'." + var (cdr e))) + ((setq e (and (fboundp 'constants-get) (constants-get var))) + (message "Constant: $%s=%s, retrieved from `constants.el'." var e)) + (t (error "Undefined name $%s" var))))) + (goto-char pos) + (when org-show-positions + (push pos org-show-positions) + (let ((min (apply 'min org-show-positions)) + (max (apply 'max org-show-positions))) + (when (or (not (pos-visible-in-window-p min)) + (no t(pos-visible-in-window-p max))) + (goto-char min) + (set-window-start (selected-window) (point-at-bol)) + (goto-char pos)))) + (select-window win)))) + +(defun org-table-force-dataline () + "Make sure the cursor is in a dataline in a table." + (unless (save-excursion + (beginning-of-line 1) + (looking-at org-table-dataline-regexp)) + (let* ((re org-table-dataline-regexp) + (p1 (save-excursion (re-search-forward re nil 'move))) + (p2 (save-excursion (re-search-backward re nil 'move)))) + (cond ((and p1 p2) + (goto-char (if (< (abs (- p1 (point))) (abs (- p2 (point)))) + p1 p2))) + ((or p1 p2) (goto-char (or p1 p2))) + (t (error "No table dataline around here")))))) + +(defun org-table-edit-line-up () + "Move cursor one line up in the window showing the table." + (interactive) + (org-table-edit-move 'previous-line)) + +(defun org-table-edit-line-down () + "Move cursor one line down in the window showing the table." + (interactive) + (org-table-edit-move 'next-line)) + +(defun org-table-edit-backward-field () + "Move cursor one field backward in the window showing the table." + (interactive) + (org-table-edit-move 'org-table-previous-field)) + +(defun org-table-edit-next-field () + "Move cursor one field forward in the window showing the table." + (interactive) + (org-table-edit-move 'org-table-next-field)) + +(defun org-table-edit-move (command) + "Move the cursor in the window shoinw the table. +Use COMMAND to do the motion, repeat if necessary to end up in a data line." + (let ((org-table-allow-automatic-line-recalculation nil) + (pos org-pos) (win (selected-window)) p) + (select-window (get-buffer-window (marker-buffer org-pos))) + (setq p (point)) + (call-interactively command) + (while (and (org-at-table-p) + (org-at-table-hline-p)) + (call-interactively command)) + (or (org-at-table-p) (goto-char p)) + (move-marker pos (point)) + (select-window win))) + +(defun org-table-edit-scroll (N) + (interactive "p") + (let ((other-window-scroll-buffer (marker-buffer org-pos))) + (scroll-other-window N))) + +(defun org-table-edit-scroll-down (N) + (interactive "p") + (org-table-edit-scroll (- N))) + +(defvar org-table-rectangle-overlays nil) + +(defun org-table-add-rectangle-overlay (beg end &optional face) + "Add a new overlay." + (let ((ov (org-make-overlay beg end))) + (org-overlay-put ov 'face (or face 'secondary-selection)) + (push ov org-table-rectangle-overlays))) + +(defun org-table-highlight-rectangle (&optional beg end face) + "Highlight rectangular region in a table." + (setq beg (or beg (point)) end (or end (point))) + (let ((b (min beg end)) + (e (max beg end)) + l1 c1 l2 c2 tmp) + (and (boundp 'org-show-positions) + (setq org-show-positions (cons b (cons e org-show-positions)))) + (goto-char (min beg end)) + (setq l1 (org-current-line) + c1 (org-table-current-column)) + (goto-char (max beg end)) + (setq l2 (org-current-line) + c2 (org-table-current-column)) + (if (> c1 c2) (setq tmp c1 c1 c2 c2 tmp)) + (goto-line l1) + (beginning-of-line 1) + (loop for line from l1 to l2 do + (when (looking-at org-table-dataline-regexp) + (org-table-goto-column c1) + (skip-chars-backward "^|\n") (setq beg (point)) + (org-table-goto-column c2) + (skip-chars-forward "^|\n") (setq end (point)) + (org-table-add-rectangle-overlay beg end face)) + (beginning-of-line 2)) + (goto-char b)) + (add-hook 'before-change-functions 'org-table-remove-rectangle-highlight)) + +(defun org-table-remove-rectangle-highlight (&rest ignore) + "Remove the rectangle overlays." + (unless org-inhibit-highlight-removal + (remove-hook 'before-change-functions 'org-table-remove-rectangle-highlight) + (mapc 'org-delete-overlay org-table-rectangle-overlays) + (setq org-table-rectangle-overlays nil))) + ;;; The orgtbl minor mode ;; Define a minor mode which can be used in other modes in order to @@ -8056,6 +8444,7 @@ to execute outside of tables." ["Edit Formulas" org-table-edit-formulas :active (org-at-table-p) :keys "C-c '"] ["Recalculate line" org-table-recalculate :active (org-at-table-p) :keys "C-c *"] ["Recalculate all" (org-table-recalculate '(4)) :active (org-at-table-p) :keys "C-u C-c *"] + ["Iterate all" (org-table-recalculate '(16)) :active (org-at-table-p) :keys "C-u C-u C-c *"] ["Toggle Recalculate Mark" org-table-rotate-recalc-marks :active (org-at-table-p) :keys "C-c #"] ["Sum Column/Rectangle" org-table-sum :active (or (org-at-table-p) (org-region-active-p)) :keys "C-c +"] @@ -8118,7 +8507,7 @@ overwritten, and the table is not marked as requiring realignment." (defun org-link-expand-abbrev (link) "Apply replacements as defined in `org-link-abbrev-alist." - (if (string-match "^\\([a-zA-Z]+\\)\\(::\\(.*\\)\\)?$" link) + (if (string-match "^\\([a-zA-Z]+\\)\\(::?\\(.*\\)\\)?$" link) (let* ((key (match-string 1 link)) (as (or (assoc key org-link-abbrev-alist-local) (assoc key org-link-abbrev-alist))) @@ -8517,7 +8906,10 @@ is in the current directory or below. With three \\[universal-argument] prefixes, negate the meaning of `org-keep-stored-link-after-insertion'." (interactive "P") - (let (link desc entry remove file (pos (point))) + (let ((region (if (and nil (org-region-active-p)) + (prog1 (buffer-substring (region-beginning) (region-end)) + (delete-region (region-beginning) (region-end))))) + link desc entry remove file (pos (point))) (cond ((save-excursion (skip-chars-forward "^]\n\r") @@ -8561,7 +8953,7 @@ With three \\[universal-argument] prefixes, negate the meaning of (setq org-stored-links (delq (assoc link org-stored-links) org-stored-links))) (setq link (if entry (nth 1 entry) link) - desc (or desc (nth 2 entry))))) + desc (or region desc (nth 2 entry))))) (if (string-match org-plain-link-re link) ;; URL-like link, normalize the use of angular brackets. @@ -8630,7 +9022,6 @@ With three \\[universal-argument] prefixes, negate the meaning of "The window configuration before following a link. This is saved in case the need arises to restore it.") -;; FIXME: IN-EMACS is used for many purposes, maybe rename this argument??? (defun org-open-at-point (&optional in-emacs) "Open link at or after point. If there is no link at point, this function will search forward up to @@ -8739,7 +9130,8 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." path (cond ((equal in-emacs '(4)) 'occur) ((equal in-emacs '(16)) 'org-occur) - (t nil)))) + (t nil)) + pos)) ((string= type "file") (if (string-match "::\\([0-9]+\\)\\'" path) @@ -8874,14 +9266,14 @@ the window configuration before `org-open-at-point' was called using: (set-window-configuration org-window-config-before-follow-link)") -(defun org-link-search (s &optional type) +(defun org-link-search (s &optional type avoid-pos) "Search for a link search option. When S is a CamelCaseWord, search for a target, or for a sentence containing the words. If S is surrounded by forward slashes, it is interpreted as a regular expression. In org-mode files, this will create an `org-occur' sparse tree. In ordinary files, `occur' will be used to list matches. If the current buffer is in `dired-mode', grep will be used to search -in all files." +in all files. If AVOID-POS is given, ignore matches near that position." (let ((case-fold-search t) (s0 (mapconcat 'identity (org-split-string s "[ \t\r\n]+") " ")) (pos (point)) @@ -9092,7 +9484,7 @@ onto the ring." (defun org-follow-bbdb-link (name) "Follow a BBDB link to NAME." (require 'bbdb) - (let ((inhibit-redisplay t) + (let ((inhibit-redisplay (not debug-on-error)) (bbdb-electric-p nil)) (catch 'exit ;; Exact match on name @@ -10088,7 +10480,7 @@ be removed." ((eq what 'deadline) org-deadline-string) ((eq what 'closed) org-closed-string)) " ") - (org-insert-time-stamp time nil (eq what 'closed)) + (org-insert-time-stamp time (eq what 'closed) (eq what 'closed)) (end-of-line 1)) (goto-char (point-min)) (widen) @@ -10271,7 +10663,6 @@ look like when opened with hierarchical calls to `org-cycle'." (org-overlay-put ov 'face 'secondary-selection) (push ov org-occur-highlights))) -(defvar org-inhibit-highlight-removal nil) (defun org-remove-occur-highlights (&optional beg end noremove) "Remove the occur highlights from the buffer. BEG and END are ignored. If NOREMOVE is nil, remove this function @@ -11768,7 +12159,6 @@ the returned times will be formatted strings." (apply 'encode-time (org-parse-time-string te))))) (move-marker ins (point)) (setq ipos (point)) - ;; FIXME: does not yet use org-insert-time-stamp (insert-before-markers "Clock summary at [" (substring (format-time-string (cdr org-time-stamp-formats)) @@ -11882,6 +12272,10 @@ The following commands are available: (if org-startup-truncated (setq truncate-lines t)) (org-add-hook 'post-command-hook 'org-agenda-post-command-hook nil 'local) (org-add-hook 'pre-command-hook 'org-unhighlight nil 'local) + ;; Make sure properties are removed when copying text + (org-set-local 'buffer-substring-filters + (cons (lambda (x) (set-text-properties 0 (length x) nil x) x) + buffer-substring-filters)) (unless org-agenda-keep-modes (setq org-agenda-follow-mode org-agenda-start-with-follow-mode org-agenda-show-log nil)) @@ -12158,7 +12552,7 @@ next use of \\[org-agenda]) restricted to the current file." (bfn (buffer-file-name (buffer-base-buffer))) (restrict-ok (and bfn (org-mode-p))) (custom org-agenda-custom-commands) - c entry key type match lprops header) + c entry key type match lprops) ;; Turn off restriction (put 'org-agenda-files 'org-restrict nil) (setq org-agenda-restrict nil) @@ -12281,8 +12675,7 @@ L Timeline for current buffer # List stuck projects (!=configure) ((equal c ?!) (customize-variable 'org-stuck-projects)) (t (error "Invalid key")))))) -;; FIXME: what is the meaning of WINDOW????? -(defun org-run-agenda-series (series &optional window) +(defun org-run-agenda-series (series) (org-prepare-agenda) (let* ((org-agenda-multi t) (redo (list 'org-run-agenda-series (list 'quote series))) @@ -12544,25 +12937,26 @@ Optional argument FILE means, use this file instead of the current." (rea (concat ":" org-archive-tag ":")) bmp file re) (save-excursion - (while (setq file (pop files)) - (org-check-agenda-file file) - (set-buffer (org-get-agenda-file-buffer file)) - (widen) - (setq bmp (buffer-modified-p)) - (save-excursion - (remove-text-properties (point-min) (point-max) pall) - (when org-agenda-skip-archived-trees + (save-restriction + (while (setq file (pop files)) + (org-check-agenda-file file) + (set-buffer (org-get-agenda-file-buffer file)) + (widen) + (setq bmp (buffer-modified-p)) + (save-excursion + (remove-text-properties (point-min) (point-max) pall) + (when org-agenda-skip-archived-trees + (goto-char (point-min)) + (while (re-search-forward rea nil t) + (if (org-on-heading-p) + (add-text-properties (point-at-bol) (org-end-of-subtree t) pa)))) (goto-char (point-min)) - (while (re-search-forward rea nil t) - (if (org-on-heading-p) - (add-text-properties (point-at-bol) (org-end-of-subtree t) pa)))) - (goto-char (point-min)) - (setq re (concat "^\\*+ +" org-comment-string "\\>")) - (while (re-search-forward re nil t) - (add-text-properties - (match-beginning 0) (org-end-of-subtree t) pc))) - (set-buffer-modified-p bmp))))) - + (setq re (concat "^\\*+ +" org-comment-string "\\>")) + (while (re-search-forward re nil t) + (add-text-properties + (match-beginning 0) (org-end-of-subtree t) pc))) + (set-buffer-modified-p bmp)))))) + (defvar org-agenda-skip-function nil "Function to be called at each match during agenda construction. If this function return nil, the current match should not be skipped. @@ -12732,12 +13126,11 @@ dates." entry date args))) (if (or rtn (equal d today) org-timeline-show-empty-dates) (progn - (insert (calendar-day-name date) " " - (number-to-string (extract-calendar-day date)) " " - (calendar-month-name (extract-calendar-month date)) " " - (number-to-string (extract-calendar-year date)) "\n") - (put-text-property s (1- (point)) 'face - 'org-level-3) + (insert (format-time-string org-agenda-date-format + (calendar-time-from-absolute d 0)) + "\n") + (put-text-property s (1- (point)) 'face 'org-level-3) + (put-text-property s (1- (point)) 'org-date-line t) (if (equal d today) (put-text-property s (1- (point)) 'org-today t)) (and rtn (insert (org-finalize-agenda-entries rtn) "\n")) @@ -12840,7 +13233,7 @@ NDAYS defaults to `org-agenda-ndays'." (d (- nt n1))) (- sd (+ (if (< d 0) 7 0) d))))) (day-numbers (list start)) - (inhibit-redisplay t) + (inhibit-redisplay (not debug-on-error)) s e rtn rtnall file date d start-pos end-pos todayp nd) (setq org-agenda-redo-command (list 'org-agenda-list (list 'quote include-all) start-day ndays)) @@ -12901,15 +13294,11 @@ NDAYS defaults to `org-agenda-ndays'." (setq rtnall (append rtnall rtn)))) (if (or rtnall org-agenda-show-all-dates) (progn - (insert (format "%-9s %2d %s %4d\n" - (calendar-day-name date) - (extract-calendar-day date) - (calendar-month-name (extract-calendar-month date)) - (extract-calendar-year date))) - (put-text-property s (1- (point)) 'face - 'org-level-3) + (insert (format-time-string org-agenda-date-format + (calendar-time-from-absolute d 0)) "\n") + (put-text-property s (1- (point)) 'face 'org-level-3) + (put-text-property s (1- (point)) 'org-date-line t) (if todayp (put-text-property s (1- (point)) 'org-today t)) - (if rtnall (insert (org-finalize-agenda-entries (org-agenda-add-time-grid-maybe @@ -14127,6 +14516,7 @@ With prefix ARG, go back that many times `org-agenda-ndays'." (org-agenda-set-mode-name) (message "Switched to day view")) +;; FIXME: this no longer works if user make date format that starts with a blank (defun org-agenda-next-date-line (&optional arg) "Jump to the next line indicating a date in agenda buffer." (interactive "p") @@ -14262,6 +14652,7 @@ and by additional input from the age of a schedules or deadline entry." (defun org-agenda-kill () "Kill the entry or subtree belonging to the current agenda entry." (interactive) + (or (eq major-mode 'org-agenda-mode) (error "Not in agenda")) (let* ((marker (or (get-text-property (point) 'org-marker) (org-agenda-error))) (hdmarker (get-text-property (point) 'org-hd-marker)) @@ -14294,12 +14685,11 @@ and by additional input from the age of a schedules or deadline entry." (defun org-agenda-archive () "Kill the entry or subtree belonging to the current agenda entry." (interactive) + (or (eq major-mode 'org-agenda-mode) (error "Not in agenda")) (let* ((marker (or (get-text-property (point) 'org-marker) (org-agenda-error))) - (hdmarker (get-text-property (point) 'org-hd-marker)) (buffer (marker-buffer marker)) - (pos (marker-position marker)) - dbeg dend txt n conf) + (pos (marker-position marker))) (org-with-remote-undo buffer (with-current-buffer buffer (if (org-mode-p) @@ -14651,8 +15041,7 @@ the tags of the current headline come last." (defun org-agenda-show-new-time (marker stamp) "Show new date stamp via text properties." ;; We use text properties to make this undoable - (let ((buffer-read-only nil) - ovs ov) + (let ((buffer-read-only nil)) (setq stamp (concat " => " stamp)) (save-excursion (goto-char (point-max)) @@ -17470,9 +17859,9 @@ The XOXO buffer is named *xoxo-<source buffer name>*" (define-key org-mode-map "\C-c\C-a" 'show-all) ; in case allout messed up. (define-key org-mode-map "\C-c\C-r" 'org-reveal) (define-key org-mode-map "\C-xns" 'org-narrow-to-subtree) -(define-key org-mode-map "\C-c\C-x\C-s" 'org-archive-subtree) -(define-key org-mode-map "\C-c\C-x\C-a" 'org-toggle-archive-tag) (define-key org-mode-map "\C-c$" 'org-archive-subtree) +(define-key org-mode-map "\C-c\C-x\C-s" 'org-advertized-archive-subtree) +(define-key org-mode-map "\C-c\C-x\C-a" 'org-toggle-archive-tag) (define-key org-mode-map "\C-c\C-xb" 'org-tree-to-indirect-buffer) (define-key org-mode-map "\C-c\C-j" 'org-goto) (define-key org-mode-map "\C-c\C-t" 'org-todo) @@ -17957,6 +18346,8 @@ See the individual commands for more information." "--" ["Recalculate line" org-table-recalculate (org-at-table-p)] ["Recalculate all" (lambda () (interactive) (org-table-recalculate '(4))) :active (org-at-table-p) :keys "C-u C-c *"] + ["Iterate all" (lambda () (interactive) (org-table-recalculate '(16))) :active (org-at-table-p) :keys "C-u C-u C-c *"] + "--" ["Toggle Recalculate Mark" org-table-rotate-recalc-marks (org-at-table-p)] "--" ["Sum Column/Rectangle" org-table-sum @@ -18013,8 +18404,8 @@ See the individual commands for more information." ["Convert to odd/even levels" org-convert-to-oddeven-levels t]) ("Archive" ["Toggle ARCHIVE tag" org-toggle-archive-tag t] - ["Check and Tag Children" (org-toggle-archive-tag (4)) - :active t :keys "C-u C-c C-x C-a"] +; ["Check and Tag Children" (org-toggle-archive-tag (4)) +; :active t :keys "C-u C-c C-x C-a"] ["Sparse trees open ARCHIVE trees" (setq org-sparse-tree-open-archived-trees (not org-sparse-tree-open-archived-trees)) @@ -18026,9 +18417,10 @@ See the individual commands for more information." (setq org-agenda-skip-archived-trees (not org-agenda-skip-archived-trees)) :style toggle :selected (not org-agenda-skip-archived-trees)] "--" - ["Move Subtree to Archive" org-archive-subtree t] - ["Check and Move Children" (org-archive-subtree '(4)) - :active t :keys "C-u C-c $"]) + ["Move Subtree to Archive" org-advertized-archive-subtree t] + ; ["Check and Move Children" (org-archive-subtree '(4)) + ; :active t :keys "C-u C-c C-x C-s"] + ) "--" ("TODO Lists" ["TODO/DONE/-" org-todo t] @@ -18338,6 +18730,28 @@ return nil." (setq string (replace-match rpl t t string)))) string)) +(defun org-sublist (list start end) + "Return a section of LIST, from START to END. +Counting starts at 1." + (let (rtn (c start)) + (setq list (nthcdr (1- start) list)) + (while (and list (<= c end)) + (push (pop list) rtn) + (setq c (1+ c))) + (nreverse rtn))) + +(defun org-at-regexp-p (regexp) + "Is point inside a match of REGEXP in the current line?" + (catch 'exit + (save-excursion + (let ((pos (point)) (end (point-at-eol))) + (beginning-of-line 1) + (while (re-search-forward regexp end t) + (if (and (<= (match-beginning 0) pos) + (>= (match-end 0) pos)) + (throw 'exit t))) + nil)))) + ;;; Paragraph filling stuff. ;; We want this to be just right, so use the full arsenal. ;; FIXME: configure filladapt for XEmacs @@ -18626,7 +19040,7 @@ Show the heading too, if it is currently invisible." A repeat cookie looks like REPEAT(+1m) and causes deadlines and schedules to repeat themselves shifted by a certain amount of time, each time an entry is marked DONE." - :group 'org??? + :group 'org; FIXME ??? :type 'boolean) (defun org-auto-repeat-maybe () @@ -18674,4 +19088,5 @@ This function should be run in the `org-after-todo-state-change-hook'." ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here -
\ No newline at end of file + + Binary files differ@@ -3,7 +3,7 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.61 +@set VERSION 4.62 @set DATE January 2007 @dircategory Emacs @@ -35,7 +35,7 @@ @copying This manual is for Org-mode (version @value{VERSION}). -Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation +Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation @quotation Permission is granted to copy, distribute and/or modify this document @@ -122,19 +122,19 @@ Tables * Built-in table editor:: Simple tables * Narrow columns:: Stop wasting space in tables -* Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode -* table.el:: Complex tables +* The spreadsheet:: The table editor has spreadsheet capabilities. -Calculations in tables +The spreadsheet -* Formula syntax:: How to write a formula -* Lisp formulas:: An alternative way to write formulas -* Column formulas:: Formulas valid for all fields in a column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debuggung formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields * 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 Hyperlinks @@ -171,7 +171,7 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format -* Repeating items:: +* Repeating items:: Deadlines that come back again and again * Progress logging:: Documenting when what work was done. Creating timestamps @@ -342,21 +342,22 @@ Org-mode 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-mode can be used on different levels and in different ways, for -example: +example as: @example -@r{@bullet{} as an outline extension with visibility cycling and structure editing} -@r{@bullet{} as an ASCII system and table editor for taking structured notes} -@r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities} -@r{@bullet{} as a TODO list editor} -@r{@bullet{} as a full agenda and planner with deadlines and work scheduling} -@r{@bullet{} as an environment to implement David Allen's GTD system} -@r{@bullet{} as a simple hypertext system, with HTML export} -@r{@bullet{} as a publishing tool to create a set of interlinked webpages} +@r{@bullet{} outline extension with visibility cycling and structure editing} +@r{@bullet{} ASCII system and table editor for taking structured notes} +@r{@bullet{} ASCII table editor with spreadsheet-like capabilities} +@r{@bullet{} TODO list editor} +@r{@bullet{} full agenda and planner with deadlines and work scheduling} +@r{@bullet{} environment to implement David Allen's GTD system} +@r{@bullet{} simple hypertext system, with HTML export} +@r{@bullet{} publishing tool to create a set of interlinked webpages} @end example -Org-mode's automatic, context sensitive table editor can be integrated -into any major mode by activating the minor Orgtbl-mode. +Org-mode's automatic, context sensitive table editor with spreadsheet +capabilities can be integrated into any major mode by activating the +minor Orgtbl-mode. @cindex FAQ There is a website for Org-mode which provides links to the newest @@ -371,9 +372,9 @@ questions (FAQ), links to tutorials etc. This page is located at @cindex installation @cindex XEmacs -@b{Important:} If Org-mode is part of the Emacs distribution or an +@b{Important:} @i{If Org-mode is part of the Emacs distribution or an XEmacs package, please skip this section and go directly to -@ref{Activation}. +@ref{Activation}.} If you have downloaded Org-mode from the Web, you must take the following steps to install it: Go into the Org-mode distribution @@ -425,6 +426,13 @@ make install-info @cindex global keybindings @cindex keybindings, global +@iftex +@b{Important:} @i{If you use copy-and-paste to copy lisp code from the +PDF documentation to your .emacs file, the single quote character comes +out incorrectly and the code will not work. You need to fix the single +quotes by hand, or copy from Info documentation.} +@end iftex + Add the following lines to your @file{.emacs} file. The last two lines define @emph{global} keys for the commands @command{org-store-link} and @command{org-agenda} - please choose suitable keys yourself. @@ -1053,9 +1061,8 @@ Emacs @file{calc} package. @menu * Built-in table editor:: Simple tables * Narrow columns:: Stop wasting space in tables -* Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode -* table.el:: Complex tables +* The spreadsheet:: The table editor has spreadsheet capabilities. @end menu @node Built-in table editor, Narrow columns, Tables, Tables @@ -1211,42 +1218,6 @@ above. @tsubheading{Calculations} @cindex formula, in tables @cindex calculations, in tables -@kindex C-c = -@item C-c = -Install a new formula for the current column and replace current field -with the result of the formula. - -@kindex C-u C-c = -@item C-u C-c = -Install a new formula for the current field, which must be a named -field. Evaluate the formula and replace the field content with the -result. - -@kindex C-c ' -@item C-c ' -Edit all formulas associated with the current table in a separate -buffer. Use @kbd{C-u C-u C-c =} to edit the formula directly in the -current field, to allow checking complex references with @kbd{C-c ?}. - -@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 calculation mark in first column through the states -@samp{}, @samp{#}, @samp{*}, @samp{!}, @samp{$}. For the meaning of -these marks see @ref{Advanced features}. When there is an active -region, change all marks in the region. - -@kindex C-c ? -@item C-c ? -Display line and column number of current field in echo area. If the -cursor is currently editing a formula, the field or range referenced by -the expression at point will be highlighted. @cindex region, active @cindex active region @@ -1304,7 +1275,7 @@ it off with @noindent Then the only table command that still works is @kbd{C-c C-c} to do a manual re-align. -@node Narrow columns, Table calculations, Built-in table editor, Tables +@node Narrow columns, orgtbl-mode, Built-in table editor, Tables @section Narrow columns @cindex narrow columns in tables @@ -1318,6 +1289,7 @@ re-align will then set the width of this column to no more than this value. @example +@group |---+------------------------------| |---+--------| | | | | | <6> | | 1 | one | | 1 | one | @@ -1325,6 +1297,7 @@ value. | 3 | This is a long chunk of text | ----/ | 3 | This=> | | 4 | four | | 4 | four | |---+------------------------------| |---+--------| +@end group @end example @noindent @@ -1348,65 +1321,117 @@ on a per-file basis with: #+STARTUP: noalign @end example -@node Table calculations, orgtbl-mode, Narrow columns, Tables -@section Calculations in tables +@node orgtbl-mode, The spreadsheet, Narrow columns, 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 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 mail mode, use + +@lisp +(add-hook 'mail-mode-hook 'turn-on-orgtbl) +@end lisp + +@node The spreadsheet, , orgtbl-mode, Tables +@section The spreadsheet @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. 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. - +derive fields from other fields. @menu -* Formula syntax:: How to write a formula -* Lisp formulas:: An alternative way to write formulas -* Column formulas:: Formulas valid for all fields in a column +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debuggung formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields * 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, Lisp formulas, Table calculations, Table calculations -@subsection Formula syntax -@cindex formula syntax -@cindex syntax, of formulas +@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet +@subsection References +@cindex references -A formula can be any algebraic expression understood by the Emacs -@file{calc} package. Note that @file{calc} has the slightly -non-standard convention that @samp{/} has lower precedence than -@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. Before -evaluation by @code{calc-eval} (@pxref{Calling Calc from -Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU -Emacs Calc Manual}), -variable substitution takes place: +To compute fields in the table from other fields, formulas must +reference other fields or ranges. In Org-mode, 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. + +@subsubheading Field references +@cindex field references +@cindex references, to fields +Formulas can reference the value of another field with the operator @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} +@@row$column @end example -@cindex vectors, in table calculations -The range vectors can be directly fed into the calc vector functions -like @samp{vmean} and @samp{vsum}. +Column references can be absolute like @samp{1}, @samp{2},...@samp{N}, +or relative to the current column like @samp{+1} or @samp{-2}. + +The row specification only counts data lines and ignores horizontal +separator lines (hlines). You can use absolute row numbers +@samp{1}...@samp{N}, and row numbers relative to the current row like +@samp{+3} or @samp{-1}. Or specify the row relative to one of the +hlines: @samp{I} refers to the first hline, @samp{II} to the second etc. +@samp{-I} refers to the first such line above the current line, +@samp{+I} to the first such line below the current line. You can also +write @samp{III+2} which is the second data line after the third hline +in the table. Relative row numbers like @samp{-3} will not cross hlines +if the current line is too close to the hline. Instead, the value +directly at the hline is used. + +@samp{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. Here are a few examples: + +@example +@@2$3 @r{2nd row, 3rd column} +$5 @r{column 5 in the current row} +@@2 @r{current column, row 2} +@@-1$-3 @r{the field one row up, three columns to the left} +@@-I$2 @r{field just under hline above current row, column 2} +@end example + +@subsubheading Range references +@cindex range references +@cindex references, to ranges + +You may reference a rectangular range of fields by specifying two field +references connected by two dots @samp{..}. If both fields are in the +current row, you may simply use @samp{$2..$7}, but if at least one field +is in a different row, you need to use the general @code{@@row$column} +format at least for the first field (i.e the reference must start with +@samp{@@} in order to be interpreted correctly). Examples: + +@example +$1..$3 @r{First three fields in the current row.} +$P..$Q @r{Range, using column names (see under Advanced)} +@@2$1..@@4$3 @r{6 fields between these two fields.} +@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row} +@end example + +@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 @samp{E} mode switch below). If there are no non-empty fields, +@samp{[0]} is returned to avoid syntax errors in formulas. +@subsubheading Named references +@cindex named references +@cindex references, named @cindex name, of column or field @cindex constants, in calculations + @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 @@ -1416,21 +1441,46 @@ constant, and 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}. +@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet +@subsection Formula syntax for Calc +@cindex formula syntax, Calc +@cindex syntax, of formulas + +A formula can be any algebraic expression understood by the Emacs +@file{Calc} package. Note that @file{calc} has the slightly +non-standard convention that @samp{/} has lower precedence than +@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. Before +evaluation by @code{calc-eval} (@pxref{Calling Calc from +Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU +Emacs Calc Manual}), +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 @samp{vmean} and @samp{vsum}. + @cindex format specifier @cindex mode, for @file{calc} 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). The display format, -however, 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 fixed 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: +string consists of flags to influence Calc and other modes during +execution. By default, Org-mode uses the standard calc modes (precision +12, angular units degrees, fraction and symbolic modes off. The display +format, however, 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}. + +@example +p20 @r{switch the internal precision to 20 digits} +n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format} +D R @r{angle modes: degrees, radians} +F S @r{fraction and symbolic modes} +N @r{interpret all fields as numbers, use 0 for non-numbers} +T @r{force text interpretation} +E @r{keep empty fields in ranges} +@end example + +@noindent +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} @@ -1442,74 +1492,226 @@ $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, up to here} +vmean($2..$7);EN @r{Same, but treat empty fields as 0} taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree} @end example -@node Lisp formulas, Column formulas, Formula syntax, Table calculations +@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet @subsection Emacs Lisp forms as formulas @cindex Lisp forms, as table formulas -It is also possible to write a formula in Emacs lisp; this can be useful +It is also possible to write a formula in Emacs Lisp; this can be useful for string manipulation and control structures. 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 provide a -format specifier after a semicolon. A few examples: +or a number. Just as with @file{calc} formulas, you can specify modes +and a printf format after a semicolon. A reference will be replaced +with a string (in double quotes) containing the field. If you provide +the @samp{N} mode switch, all referenced elements will be numbers. +Ranges are inserted as space-separated fields, so you can embed them in +list or vector syntax. A few examples, note how the @samp{N} mode is +used when we do computations in lisp. @example -@r{swap the first two characters of the content of column 1} -'(concat (substring "$1" 1 2) (substring "$1" 0 1) (substring "$1" 2)) -@r{Add columns 1 and 2, equivalent to the calc's @code{$1+$2}} -'(+ $1 $2) +@r{Swap the first two characters of the content of column 1} + '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) +@r{Add columns 1 and 2, equivalent to the Calc's @code{$1+$2}} + '(+ $1 $2);N +@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} + '(apply '+ '($1..$4));N @end example -@node Column formulas, Advanced features, Lisp formulas, Table calculations +@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet +@subsection Field formulas +@cindex field formula +@cindex formula, for individual table field + +To assign a formula to a particular field, type it directly into the +field, preceded by @samp{=:}, for example @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 this field, +evaluated, and the current field replaced with the result. + +Formulas are stored in a special line starting with @samp{#+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 +@samp{@@3$2=$1+$2}. When inserting/deleting/swapping column and rows +with the appropriate commands, @i{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 go and +fix equations yourself. + +Instead of typing an equation into the field, you may also use the +following command + +@table @kbd +@kindex C-u C-c = +@item C-u C-c = +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. +@end table + +@node Column formulas, Editing and debuggung formulas, Field formulas, The spreadsheet @subsection Column formulas @cindex column formula @cindex formula, for table column -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 +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-mode allows to assign a single formula to an entire +column. + +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-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. +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 only remember the most recently +used formula. In the @samp{TBLFM:} line, column formulas will look like +@samp{$4=$1+$2}. 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 -consecutive fields in the current column. +following command: + +@table @kbd +@kindex C-c = +@item C-c = +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 numerical prefix (e.g. @kbd{C-5 C-c =}) +will apply it to that many consecutive fields in the current column. +@end table + + +@node Editing and debuggung formulas, Updating the table, Column formulas, The spreadsheet +@subsection Editing and Debugging formulas +@cindex formula editing +@cindex editing, of table formulas + +You can edit individual formulas in the minibuffer or directly in the +field. Org-mode can also prepare a special buffer with all active +formulas of a table. + +@table @kbd +@kindex C-c = +@kindex C-u C-c = +@item C-c = +@itemx C-u C-c = +Edit the formula associated with the current column/field in the +minibuffer. See @ref{Column formulas} and @ref{Field formulas}. +@kindex C-u C-u C-c = +@item C-u C-u C-c = +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-c ? +@item C-c ? +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 ' +@item C-c ' +Edit all formulas for the current table in a special buffer, where the +formulas will be displayed one per line. +While inside the special buffer, Org-mode will automatically highlight +any field or range reference at the cursor position. You may edit, +remove and add formulas, and use the following commands: +@table @kbd +@kindex C-c C-c +@item C-c C-c +Exit the buffer and store the modified formulas. With @kbd{C-u} prefix, +also apply the new formulas to the entire table. +@kindex C-c C-q +@item C-c C-q +Exit the buffer without installing changes. +@kindex S-@key{up} +@kindex S-@key{down} +@item S-@key{up}/@key{down} +Move the reference line in the Org-mode buffer up and down. This is +important for highlighting the references of column formulas for +different rows. +@kindex M-@key{up} +@kindex M-@key{down} +@item M-@key{up}/@key{down} +Scroll the window displaying the table. +@end table +@end table + +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. +@subsubheading Debugging formulas +@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 @code{Tbl} menu and repeat the +calculation, for example by pressing @kbd{C-c = @key{RET}} in a field. +Detailed information will be displayed. + +@node Updating the table, Advanced features, Editing and debuggung formulas, The spreadsheet +@subsection Updating the Table @cindex recomputing table fields -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 +@cindex updating, table + +Recalculation of a table is normally not automatic, but needs to be +triggered by a command. See @ref{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: + +@table @kbd +@kindex C-c * +@item C-c * +Recalculate the current row by first applying the stored column formulas +from left to right, and all field formulas in the current row. + +@kindex C-u C-c * +@item C-u C-c * +@kindex C-u C-c C-c +@itemx 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-u C-c * +@item C-u C-u C-c * +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 @i{later} in the calculation sequence. +@end table + + +@node Advanced features, , Updating the table, The spreadsheet @subsection Advanced features -If you 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: +If you want the recalculation of fields to happen automatically, or if +you want to be able to assign @i{names} to fields and columns, you need +to reserve the first column of the table for special marking characters. +@table @kbd +@kindex C-# +@item C-# +Rotate the calculation mark in first column through the states @samp{}, +@samp{#}, @samp{*}, @samp{!}, @samp{$}. The meaning of these characters +is discussed below. When there is an active region, change all marks in +the region. +@end table + +Here is an example of a table that collects exam results of students and +makes use of these features: @example @group @@ -1528,14 +1730,15 @@ features: | ^ | | | | | at | | | $ | max=50 | | | | | | |---+---------+--------+--------+--------+-------+------| -#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f +#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f @end group @end example @noindent @b{Important}: Please note that for these special tables, -recalculating the table with @kbd{C-u C-c *} will only affect rows -that are marked @samp{#} or @samp{*}, and named fields. The column -formulas are not applied in rows with empty first field. +recalculating the table with @kbd{C-u C-c *} will only affect rows that +are marked @samp{#} or @samp{*}, 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: @@ -1546,8 +1749,8 @@ refer to a column as @samp{$Tot} instead of @samp{$6}. @item ^ 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, named fields can have their own formula -associated with them. +the value @samp{10}. Also, if you assign a formula to a names field, it +will be stored as @samp{$name=...}. @item _ Similar to @samp{^}, but defines names for the fields in the row @emph{below}. @@ -1556,8 +1759,7 @@ 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. +a per-table basis. @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 @@ -1573,67 +1775,10 @@ 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 -@cindex named field formula -@cindex formula, for named table field - -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 into 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 -@cindex formula editing -@cindex editing, of table formulas - -To edit a column or field formula, 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, where 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, -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 whet 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 :-) +Finally, just to whet your appetite on what can be done with the +fantastic @file{calc} package, here is a table that computes the Taylor +series of degree @code{n} at location @code{x} for a couple of functions +(homework: try that with Excel :-) @example @group @@ -1651,51 +1796,6 @@ for a couple of functions (homework: try that with Excel :-) @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 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 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, @file{table.el} -@cindex @file{table.el} - -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}, -and also part of Emacs 22). -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-mode-related commands, leave the table. - -@table @kbd -@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 -@code{org-convert-table} for the restrictions under which this is -possible. -@end table - @node Hyperlinks, TODO items, Tables, Top @chapter Hyperlinks @cindex hyperlinks @@ -1934,15 +2034,17 @@ all links stored during the current session can be accessed@footnote{After insertion of a stored link, the link will be removed from the list of stored links. To keep it in the list later use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the -option @code{org-keep-stored-link-after-insertion}.}. The link -will be inserted into the buffer, along with a descriptive text. Note -that you don't have to use this command to insert a link. Links in -Org-mode are plain text, and you can type or paste them straight into -the buffer. By using this command, the links are automatically enclosed -in double brackets, and you will be asked for the optional descriptive -text. If the link is a @samp{file:} link and the linked file is located -in the same directory as the current file or a subdirectory of it, the -path of the file will be inserted relative to the current directory. +option @code{org-keep-stored-link-after-insertion}.}. The link will be +inserted into the buffer, along with a descriptive text. If some text +was selecten when this command is called, the selected text becomes the +default description.@* Note that you don't have to use this command to +insert a link. Links in Org-mode are plain text, and you can type or +paste them straight into the buffer. By using this command, the links +are automatically enclosed in double brackets, and you will be asked for +the optional descriptive text. If the link is a @samp{file:} link and +the linked file is located in the same directory as the current file or +a subdirectory of it, the path of the file will be inserted relative to +the current directory. @kindex C-u C-c C-l @cindex file name completion @@ -2898,7 +3000,7 @@ One unusual property of these repeating items is that only one instance of each exist at any given time. So if you look back or ahead in the agenda, you will not find past and future instances, only the current one will show up. Use a cyclic diary entry if you need all past and -future instances to be visible in the angenda. +future instances to be visible in the agenda. @node Progress logging, , Repeating items, Timestamps @section Progress Logging @@ -3307,7 +3409,7 @@ case it must be enclosed in curly braces. For example, You can also require a headline to be of a certain level, by writing instead of any TAG an expression like @samp{LEVEL=3}. For example, a search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that -have the tag BOSS and are @emph{not} marked witht the todo keyword DONE. +have the tag BOSS and are @emph{not} marked with the todo keyword DONE. @node Agenda views, Embedded LaTeX, Tags, Top @chapter Agenda Views @@ -3331,7 +3433,7 @@ a @emph{TODO list} that covers all unfinished action items, @item a @emph{tags view}, showings headlines based on -the tags associated them, +the tags associated with them, @item a @emph{timeline view} that shows all events in a single Org-mode file, in time-sorted view, @@ -3390,7 +3492,9 @@ the front. With prefix arg, file is added/moved to the end. @item C-c ] Remove current file from the list of agenda files. @kindex C-, +@kindex C-' @item C-, +@itemx C-' Cycle through agenda file list, visiting one file after the other. @end table @@ -3929,7 +4033,7 @@ priority character. If you reply with @key{SPC}, the priority cookie is removed from the entry. @kindex P -@item p +@item P Display weighted priority of current item. @kindex + @@ -5237,12 +5341,14 @@ force publishing of all files by giving a prefix argument. @cindex completion, of option keywords @cindex completion, of CamelCase links @cindex completion, of tags +@cindex completion, of link abbreviations @cindex @TeX{} symbol completion @cindex TODO keywords completion @cindex dictionary word completion @cindex option keyword completion @cindex CamelCase link completion @cindex tag completion +@cindex link abbreviations, completion of Org-mode supports in-buffer completion. This type of completion does not make use of the minibuffer. You simply type a few letters into @@ -5389,7 +5495,7 @@ end of the file. The first such line also applies to any entries before it. This line sets the archive location for the agenda file. It applies for 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. -The correspoinding variable is @code{org-archive-location}. +The corresponding variable is @code{org-archive-location}. @item #+TBLFM: This line contains the formulas for the table directly above the line. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: @@ -5597,7 +5703,7 @@ with other code out there. @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 +functionality in its tables (@pxref{The spreadsheet}). 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 @@ -5606,7 +5712,7 @@ packages is using calc for embedded calculations. @xref{Embedded Mode, , Embedded Mode, calc, GNU Emacs Calc Manual}. @cindex @file{constants.el} @item @file{constants.el} by Carsten Dominik -In a table formula (@pxref{Table calculations}), it is possible to use +In a table formula (@pxref{The spreadsheet}), it is possible to use names for natural constants or units. Instead of defining your own constants in the variable @code{org-table-formula-constants}, install the @file{constants} package which defines a large number of constants @@ -5626,8 +5732,34 @@ Org mode cooperates with remember, see @ref{Remember}. @file{Remember.el} is not part of Emacs, find it on the web. @cindex @file{table.el} @item @file{table.el} by Takaaki Ota -Org mode cooperates with table.el, see @ref{table.el}. @file{table.el} -is part of Emacs 22. +@kindex C-c C-c +@cindex table editor, @file{table.el} +@cindex @file{table.el} + +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}, +and also part of Emacs 22). +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-mode-related commands, leave the table. + +@table @kbd +@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 +@code{org-convert-table} for the restrictions under which this is +possible. +@end table +@file{table.el} is part of Emacs 22. @end table @node Conflicts, , Cooperation, Interaction @@ -5833,7 +5965,7 @@ tag anywhere in the project tree. Let's further assume that you have marked all tree headings that define a project with the todo keyword PROJECT. In this case you would run a todo search for the keyword PROJECT, but skip the match unless there is a WAITING tag anywhere in -the subtree belonging to the project line.. +the subtree belonging to the project line. To achieve this, you must write a function that searches the subtree for the tag. If the tag is found, the function must return @code{nil} to @@ -5851,7 +5983,7 @@ search should continue from there. @end lisp Furthermore you must write a command that uses @code{let} to temporarily -puts this function into the variable @code{org-agenda-skip-function}, +put this function into the variable @code{org-agenda-skip-function}, sets the header string for the agenda buffer, and calls the todo-list generator while asking for the specific TODO keyword PROJECT. The function must also accept one argument MATCH, but it can choose to diff --git a/orgcard.pdf b/orgcard.pdf Binary files differindex 715f71b..6cbcd40 100644 --- a/orgcard.pdf +++ b/orgcard.pdf diff --git a/orgcard.tex b/orgcard.tex index 9d858e9..9313519 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,6 +1,6 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.61} -\def\year{2006} +\def\orgversionnumber{4.62} +\def\year{2007} % %**start of header \newcount\columnsperpage @@ -318,7 +318,7 @@ are preserved on all copies. \metax{mark fully done children}{C-u C-c C-x C-a} \key{force cycling of an ARCHIVEd tree}{C-TAB} \key{move subtree to archive file}{C-c C-x C-s} -\key{move all fully done children}{C-u C-c C-x C-s} +\metax{move all fully done children}{C-u C-c C-x C-s} To set archive location for current file, add a line like$^2$: \vskip -1mm \beginexample% @@ -367,8 +367,7 @@ Outside of tables, the same keys may have other functionality. \key{move the current row down}{M-DOWN} \key{kill the current row or horizontal line}{M-S-UP} \key{insert new row above the current row}{M-S-DOWN} -\key{insert horizontal line below the current row}{C-c -} -\key{insert horizontal line above the current row}{C-u C-c -} +\key{insert hline below (\kbd{C-u} : above) current row}{C-c -} \key{sort lines in region}{C-c \^{}} {\bf Regions} @@ -381,10 +380,11 @@ Outside of tables, the same keys may have other functionality. {\bf Calculations} (in combination with Emacs \kbd{calc} package) \key{set and eval column formula}{C-c =} -\key{set and eval named-field formula}{C-u C-c =} +\key{set and eval field formula}{C-u C-c =} \key{edit formulas in separate buffer}{C-c '} \key{re-apply all stored equations to current line}{C-c *} \key{re-apply all stored equations to entire table}{C-u C-c *} +\key{iterate table to stability}{C-u C-u C-c *} %\kbd{TAB}, \kbd{RET} and \kbd{C-c C-c} trigger automatic recalculation %in lines starting with: {\tt | \# |}. @@ -402,7 +402,7 @@ formula, \kbd{:=} a named-field formula. \key{Example: Add Col1 and Col2}{=\$1+\$2} \key{... with printf format specification}{=\$1+\$2;\%.2f} \key{... with constants from constants.el}{=\$1/\$c/\$cm} -\key{sum from 3rd hline above to here}{:=vsum(\&III)} +\metax{sum from 2nd to 3rd hline}{:=vsum(@II..@III)} \key{apply current column formula}{=} {\bf Miscellaneous} |