Browse Source

Improve manual and ERT for table formulas

* doc/org.texi (Field coordinates in formulas): Rephrase and add an
example with a Lisp formula to copy from remote table.
* testing/lisp/test-org-table.el (Comments): Adapt comment.
(test-org-table/copy-field): Add reference to
`test-org-table/remote-reference-access'.
(test-org-table/remote-reference-access): Add reference to
`test-org-table/copy-field'.  Differentiate between Lisp formula to
copy and Calc (or Lisp) formula to calculate.
Michael Brand 11 years ago
parent
commit
396b2172e4
2 changed files with 36 additions and 24 deletions
  1. 20 13
      doc/org.texi
  2. 16 11
      testing/lisp/test-org-table.el

+ 20 - 13
doc/org.texi

@@ -2547,21 +2547,28 @@ for Calc}.
 @cindex row, of field coordinates
 @cindex column, of field coordinates
 
-For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to
-get the row or column number of the field where the formula result goes.
-The traditional Lisp formula equivalents are @code{org-table-current-dline}
-and @code{org-table-current-column}.  Examples:
+One of the very first actions during evaluation of Calc formulas and Lisp
+formulas is to substitute @code{@@#} and @code{$#} in the formula with the
+row or column number of the field where the current result will go to.  The
+traditional Lisp formula equivalents are @code{org-table-current-dline} and
+@code{org-table-current-column}.  Examples:
 
-@example
-if(@@# % 2, $#, string(""))   @r{column number on odd lines only}
-$3 = remote(FOO, @@@@#$2)      @r{copy column 2 from table FOO into}
-                             @r{column 3 of the current table}
-@end example
+@table @code
+@item if(@@# % 2, $#, string(""))
+Insert column number on odd rows, set field to empty on even rows.
+@item $2 = '(identity remote(FOO, @@@@#$1))
+Copy text or values of each row of column 1 of the table named @code{FOO}
+into column 2 of the current table.
+@item @@3 = 2 * remote(FOO, @@1$$#)
+Insert the doubled value of each column of row 1 of the table named
+@code{FOO} into row 3 of the current table.
+@end table
 
-@noindent For the second example, table FOO must have at least as many rows
-as the current table.  Note that this is inefficient@footnote{The computation time scales as
-O(N^2) because table FOO is parsed for each field to be copied.} for large
-number of rows.
+@noindent For the second/third example, the table named @code{FOO} must have
+at least as many rows/columns as the current table.  Note that this is
+inefficient@footnote{The computation time scales as O(N^2) because the table
+named @code{FOO} is parsed for each field to be read.} for large number of
+rows/columns.
 
 @subsubheading Named references
 @cindex named references

+ 16 - 11
testing/lisp/test-org-table.el

@@ -20,10 +20,9 @@
 
 ;;;; Comments:
 
-;; Template test file for Org-mode tests.  First the tests that are
-;; also a howto example collection as a user documentation, more or
-;; less all those using `org-test-table-target-expect'.  Then the
-;; internal and more abstract tests.  See also the doc string of
+;; Template test file for Org-mode tests.  Many tests are also a howto
+;; example collection as a user documentation, more or less all those
+;; using `org-test-table-target-expect'.  See also the doc string of
 ;; `org-test-table-target-expect'.
 
 ;;; Code:
@@ -553,7 +552,8 @@ reference (with row).  Mode string N."
 ))
 
 (ert-deftest test-org-table/copy-field ()
-  "Experiments on how to copy one field into another field."
+  "Experiments on how to copy one field into another field.
+See also `test-org-table/remote-reference-access'."
   (let ((target
 	 "
 | 0                | replace |
@@ -772,21 +772,26 @@ reference (with row).  Mode string N."
 ;;    (string= "$3 = remote(FOO, @@#$2)" (org-table-convert-refs-to-rc "C& = remote(FOO, @@#B&)"))))
 
 (ert-deftest test-org-table/remote-reference-access ()
-  "Access to remote reference."
+  "Access to remote reference.
+See also `test-org-table/copy-field'."
   (org-test-table-target-expect
    "
 #+NAME: table
-|   | 42 |
+|   | x   42 |   |
 
-| replace |   |
+| replace | replace |
 "
    "
 #+NAME: table
-|   | 42 |
+|   | x   42 |   |
 
-| 42 |   |
+| x   42 | 84 x |
 "
-   1 "#+TBLFM: $1 = remote(table, @1$2)"))
+   1 (concat "#+TBLFM: "
+	     ;; Copy text without calculation: Use Lisp formula
+	     "$1 = '(identity remote(table, @1$2)) :: "
+	     ;; Do a calculation: Use Calc (or Lisp ) formula
+	     "$2 = 2 * remote(table, @1$2)")))
 
 (ert-deftest test-org-table/org-at-TBLFM-p ()
   (org-test-with-temp-text-in-file