org: Translator functions
A.6.3 Translator functions
--------------------------
Orgtbl mode has several translator functions built-in: ‘orgtbl-to-csv’
(comma-separated values), ‘orgtbl-to-tsv’ (TAB-separated values)
‘orgtbl-to-latex’, ‘orgtbl-to-html’, and ‘orgtbl-to-texinfo’. Except
for ‘orgtbl-to-html’(1), these all use a generic translator,
‘orgtbl-to-generic’. For example, ‘orgtbl-to-latex’ itself is a very
short function that computes the column definitions for the ‘tabular’
environment, defines a few field and line separators and then hands
processing over to the generic translator. Here is the entire code:
(defun orgtbl-to-latex (table params)
"Convert the Orgtbl mode TABLE to LaTeX."
(let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
org-table-last-alignment ""))
(params2
(list
:tstart (concat "\\begin{tabular}{" alignment "}")
:tend "\\end{tabular}"
:lstart "" :lend " \\\\" :sep " & "
:efmt "%s\\,(%s)" :hline "\\hline")))
(orgtbl-to-generic table (org-combine-plists params2 params))))
As you can see, the properties passed into the function (variable
PARAMS) are combined with the ones newly defined in the function
(variable PARAMS2). The ones passed into the function (i.e., the ones
set by the ‘ORGTBL SEND’ line) take precedence. So if you would like to
use the LaTeX translator, but wanted the line endings to be ‘\\[2mm]’
instead of the default ‘\\’, you could just overrule the default with
#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
For a new language, you can either write your own converter function
in analogy with the LaTeX translator, or you can use the generic
function directly. For example, if you have a language where a table is
started with ‘!BTBL!’, ended with ‘!ETBL!’, and where table lines are
started with ‘!BL!’, ended with ‘!EL!’, and where the field separator is
a TAB, you could call the generic translator like this (on a single
line!):
#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
:lstart "!BL! " :lend " !EL!" :sep "\t"
Please check the documentation string of the function
‘orgtbl-to-generic’ for a full list of parameters understood by that
function, and remember that you can pass each of them into
‘orgtbl-to-latex’, ‘orgtbl-to-texinfo’, and any other function using the
generic function.
Of course you can also write a completely new function doing
complicated things the generic translator cannot do. A translator
function takes two arguments. The first argument is the table, a list
of lines, each line either the symbol ‘hline’ or a list of fields. The
second argument is the property list containing all parameters specified
in the ‘#+ORGTBL: SEND’ line. The function must return a single string
containing the formatted table. If you write a generally useful
translator, please post it on <emacs-orgmode@gnu.org> so that others can
benefit from your work.
---------- Footnotes ----------
(1) The HTML translator uses the same code that produces tables
during HTML export.