htab() is a GNU Octave function to produce nice lay-outs of tables in html and Latex.
array package is assumed
at default, but in addition one can apply the longtable and/or
booktabs packages.Below a complete list of all directives (or styling commands) sorted by feature is given.
Function htab is called like this:
r = htab(tbl);
or:
r = htab(tbl,opt);
Note that in this documentation a "string" is always synonym to a "row vector of characters", in GNU Octave terms.
The first input argument tbl contains information on the
table(s). We can think of it as either:
tbl = stbl;
where stbl is a string.
Table cells and styling directives are distinguished in the following way
by the default tags in string stbl:
<htab>
<tabsty>...</tabsty>
<colsty>...<csep>...<csep>...</colsty>
cell data 1,1<csep>cell data 1,2<sty>...</sty><csep>cell data 1,3<rsep>
cell data 2,1<csep>cell data 2,2 <csep>cell data 2,3<rsep>
</htab>
Table cells within a row are separated by <csep>. The
number of columns in a table is defined by the row which has the largest number
of instances of <csep>. If this row has N instances of
<csep>, the table has N+1 columns.
When a cell spans over several columns, no <csep> may be
skipped (contrary to html or Latex coding)! If the cell in column K on a
particular row has the directive that it spans over M columns, data in
the cells K+1, K+2, ... and K+M-1 will be ignored and
instances of <csep> will be expected between cells K+1
and K+2, between cells K+2 and K+3, ... and (if cell
K+M-1 is not in the last column of the table:) between cells K+M-1
and K+M.
Table rows are separated by <rsep>. If there are no
characters, or just whitespace characters, between the last
<rsep> and the final tag </htab>, no new
row is assumed.
The fields <tabsty>...</tabsty> and
<colsty>...</colsty> are optional. They may only
appear in the first table cell!
The field <sty>...</sty> is issued in a table cell
to indicate directives. There are no tags to explicitly indicate cell content
data. Leading and trailing whitespace in the cell contents will be removed.
The three dots ... in the above code are to be replaced by styling directives. The coding of the directives is explained below.
or:
ctbl = { ... s, ..., rtbl, ... };
tbl = ctbl;
where one-dimensional cell array ctbl has an arbitrary number
of elements. Each element is either:
s. Such a string may not contain a table. The
string simply contains text before or after a table, or between tables;
or:
rtbl. Such a struct must contain a table defined by
the following fields:
Content data may have any value. Strings will not be converted. Integers, reals, booleans will be converted into obvious text representations. Also cell arrays and struct's are converted into text representations (in json form).
If a particular table cell contains a nested table, the fields
"cellsty" and "celldat" of the particular table cell contain the directive
"nested-table" and a one-dimensional cell array of the same type as
ctbl, respectively.
The optional seconde input argument opt contains a struct, which
may have one or more of the following fields:
opt.tagsigils.outer = {"<",">"};
opt.tagsigils.single = {"",""};
opt.tagsigils.pair = {"","","/",""};
So, with the defaults, the tags in "<htab>...<csep>...<rsep>...</htab>"
are recognised.
If one would set for example:
opt.tagsigils.outer = {"[","]"};
opt.tagsigils.single = {"@",""};
opt.tagsigils.pair = {"-","","","-"};
the tags in "[-htab]...[@csep]...[@rsep]...[htab-]"
are recognised.
Of course, one has to choose sigils by which tags are distinctive. Function
htab does not provide for much error checking.
htab,
tabsty,
colsty,
sty,
csep,
rsep,
space,
semicolon,
empty, and
contents.
For example, to have "<tab>" (with the default tag
sigils) instead of the default "<csep>", one issues:
opt.tagrenaming.csep = "tab";
The output argument r is a struct, which has the following fields:
<style> and </style>
elements within the header in a html file;
The following input (as a string):
<htab>
<tabsty> default-vert-sep single; default-hor-sep single </tabsty>
<colsty>
col-width 30 %<csep>
col-width 10 %; col-double .; col-right-sep none; <csep>
col-width 10 %<csep>
col-width 30 %<csep>
col-width 20 %; col-hor-align center
</colsty>
cell 1,1<csep>cell 1,2
<sty>col-span 2; hor-align left</sty>
<csep>cell 1,3<csep>cell 1,4<csep>cell 1,5<rsep>
cell 2,1<csep>123.456 <csep>cell 2,3<csep>cell 2,4<csep>cell 2,5<rsep>
cell 3,1<csep>1.23456 <csep>cell 3,3<csep>cell 3,4<csep>cell 3,5<rsep>
cell 4,1 This cell contains much text to show wrapping. Of course, this
also depends on the size of the applied font.
<csep>cell 4,2<csep>cell 4,3<csep>cell 4,4<csep>cell 4,5<rsep>
cell 5,1 <sty>col-span 4; hor-align center</sty>
<csep>cell 5,2<csep>cell 5,3<csep>cell 5,4<csep>cell 5,5<rsep>
cell 6,1<csep>cell 6,2<csep>cell 6,3<csep>cell 6,4
<htab>
C-1-1<csep>C-1-2<rsep>
C-2-1<csep>C-2-2<rsep>
C-3-1<csep>C-3-2<rsep>
</htab>
<csep>cell 6,5<rsep>
cell 7,1<csep>cell 7,2<csep>cell 7,3<csep>cell 7,4<csep>cell 7,5
<sty>html-style font-weight:<space>bold;
latex-style {\bf<space><contents>}
</sty>
<rsep>
</htab>
results to this lay-out in html:
| cell 1,1 | cell 1,2 | cell 1,4 | cell 1,5 | |||||||
| cell 2,1 | 123 | .456 | cell 2,4 | cell 2,5 | ||||||
| cell 3,1 | 1 | .23456 | cell 3,4 | cell 3,5 | ||||||
| cell 4,1 This cell contains much text to show wrapping. Of course, this also depends on the size of the applied font. | cell 4,2 | cell 4,4 | cell 4,5 | |||||||
| cell 5,1 | cell 5,5 | |||||||||
| cell 6,1 | cell 6,2 | cell 6,4
|
cell 6,5 | |||||||
| cell 7,1 | cell 7,2 | cell 7,4 | cell 7,5 | |||||||
Some remarks on this example:
Here, the input tbl is a cell array organised like
ctbl explained above:
rtbl = struct();
rtbl.tabsty = "default-vert-sep single; default-hor-sep single; default-number-format %1.8e";
rtbl.rowsty = {};
rtbl.rowsty{4} = "row-number-format %2.2e";
rtbl.rowsty{7} = "row-number-format %2.1e";
rtbl.cellsty = {};
rtbl.cellsty{1,2} = "col-double .; col-right-sep none";
rtbl.cellsty{4,2} = "number-format %2.3e";
rtbl.cellsty{5,2} = "number-format %1.0f";
c54 = [0.5*pi pi 2*pi];
c64 = {"p", "q", 3, 4};
c74 = struct();
c74.a = 1;
c74.b = [2 3];
rtbl.celldat = { ...
"cell 1,1", "cell 1,2", "cell 1,3", "cell 1,4";
"cell 2,1", "1.2345e-6", "", "1.2345e-6";
"cell 3,1", 1.2345e-6, "", 1.2345e-6;
"cell 4,1", 1.2345e-6, "", 1.2345e-6;
"cell 5,1", 1.2345e3, "", c54;
"cell 6,1", 1.2345e3, "", c64;
"cell 7,1", 1.2345e3, "", c74;
};
tbl = {rtbl};
After processing by htab(tbl), we get this result in html:
| cell 1,1 | cell 1,2 | cell 1,4 | |
| cell 2,1 | 1 | .2345 × 10-6 | 1.2345 × 10-6 |
| cell 3,1 | 1 | .23450000 × 10-6 | 1.23450000 × 10-6 |
| cell 4,1 | 1 | .234 × 10-6 | 1.23 × 10-6 |
| cell 5,1 | 1234 | [ 1.57079633, 3.14159265, 6.28318531 ] | |
| cell 6,1 | 1 | .23450000 × 103 | [ "p", "q", 3.00000000, 4.00000000 ] |
| cell 7,1 | 1 | .2 × 103 | { "a" : 1.0, "b" : [ 2.0, 3.0 ] } |
Some remarks on this example:
Also in this example, the input tbl is a cell array organised like
ctbl explained above:
rtbl = struct();
rtbl.tabsty = "default-wrap off; html-table-width auto";
rtbl.rowsty = {};
rtbl.rowsty{1} = "row-top-sep top";
rtbl.rowsty{3} = "row-top-sep mid";
rtbl.rowsty{10} = "row-bottom-sep bottom";
rtbl.cellsty = {};
rtbl.cellsty{1,2} = "col-span 3";
rtbl.cellsty{2,2} = "top-sep span";
rtbl.cellsty{2,3} = "top-sep span";
rtbl.cellsty{2,4} = "top-sep span";
rtbl.celldat = { ...
"unit", "symbol", "", "", "exact definition";
"", "htab", "Latex", "html", "";
"inch", "", "in", "in", "1 inch = 2.54 centimeters";
"css point", "pt", "bp", "pt", "1 css point = (1/72) inches";
"css pica", "", "", "pc", "1 css pica = 12 css points";
"css pixel", "", "", "px", "1 css pixel = 0.75 css points = (1/96) inches";
"TeX point", "pt", "pt", "", "1 TeX point = (1/72.27) inches";
"TeX pica", "", "pc", "", "1 TeX pica = 12 TeX points";
"x-height", "ex", "ex", "ex", "height of small \"x\" in the actual font";
"M-width", "em", "em", "em", "width of capital \"M\" in the actual font";
};
tbl = {rtbl};
After processing by htab(tbl), we get this result in html:
| unit | symbol | exact definition | ||
| htab | Latex | html | ||
| inch | in | in | 1 inch = 2.54 centimeters | |
| css point | pt | bp | pt | 1 css point = (1/72) inches |
| css pica | pc | 1 css pica = 12 css points | ||
| css pixel | px | 1 css pixel = 0.75 css points = (1/96) inches | ||
| TeX point | pt | pt | 1 TeX point = (1/72.27) inches | |
| TeX pica | pc | 1 TeX pica = 12 TeX points | ||
| x-height | ex | ex | ex | height of small "x" in the actual font |
| M-width | em | em | em | width of capital "M" in the actual font |
Some remarks on this example:
See the next two sections for complete lists of directives.
We distinguish "table directives", "column directives", "row directives" and "cell directives", because each directive belongs to a single category or level. This means that a directive applies either to (the styling of) the whole table, a particular column, a particular row, or a particular cell.
If a styling property is set by several directives, the directive at a lower level overrules the one at a higher level. The four levels are: "table" (highest) – "column" – "row" – "cell" (lowest).
Note that directives may be placed at a lower level. The htab
program will anyhow assign such "misplaced" directives to their intrinsic
categories or levels. Thus, within <sty>...</sty> and
within "cellsty" fields, directives of all categories are accepted. Within
<colsty>...</colsty> and within "colsty" fields, both
column and table directives are accepted, but no row directives (however) and no
cell directives. Within <tabsty>...</tabsty> and within
"tabsty" fields, only table directives are accepted.
If the same directive is issued on several places, the last read instance will eventualy define the styling.
Table directives are inherited by the nested table from the containing table.
A directive consists of a directive name and zero or more arguments. Directives can be given as:
dir1 arg1; dir2".
One can issue multiple directives by inserting a semicolon between them.
Some directives have one or more arguments, which are separated by spaces. Tags
are used to encode a semicolon, space or an empty string in arguments; the
default forms of these tags are <semicolon>,
<space> and <empty>, respectively.
or:
d.("dir1")={"arg1"}; d.("dir2")={};.
The struct may contain zero or more directives, as it may contain as much fields. The field name contains a directive name; the field value contains a one dimensional cell array, of which each element is a string for the respective argument of the directive.
category : table
Thickness (and colour code) of horizontal rules of type "bottom".
This type is translated into \bottomrule[thickness] in Latex and this Latex code is defined by the booktabs package.
The colour is only applied in html; the colour code must be recognised in html/css.
category : cell
Row separator type below the actual cell. The default is defined by directive "default-hor-sep".
category : column
The contents in the cells of the actual column is splitted just before the text given in the argument. The first part is printed in the actual column; the second part is transferred to the cell in the next column. Moreover, the horizontal alignment of actual column is set to "right", and the alignment in next column is set to "left".
Splitting and transfering is applied only if the contents of the cell consists of text (given as such), or a number (given as such). In the latter case, the splitting is applied after the number is converted to text.
At default, no such splitting and transfering are applied.
category : column
Horizontal alignment in the cells of the actual column. The default is defined by directive "default-hor-align".
category : column
Left-side padding width in the cells of the actual column. At default, \tabcolsep is used in Latex, but no css style is set in html. This means that the default padding width is 6 pt in Latex and (perhaps) 1 px in html.
There are no versions of this directive to set the left-side padding width per row or per cell, because this is rather complicated to implement in Latex.
category : column
Left-side separator type in the cells of the actual column. The default is defined by directive "default-vert-sep".
This directive will overrule the possibly issued directive "col-right-sep" in the previous column, because collapse of separators is applied.
category : column
The argument contains a template as used by the sprintf() series of functions to translate a real or integer (given as such data) into text. Data which has been given as text, is not affected by this translation.
The translation is applied to the cells in the actual column.
category : column
Right-side padding width in the cells of the actual column. At default, \tabcolsep is used in Latex, but no css style is set in html. This means that the default padding width is 6 pt in Latex and (perhaps) 1 px in html.
There are no versions of this directive to set the right-side padding width per row or per cell, because this is rather complicated to implement in Latex.
category : column
Right-side separator type in the cells of the actual column. The default is defined by directive "default-vert-sep".
category : cell
Span the actual cell over a number of columns. If "*" is given, span until the last column.
At default, no spanning is applied.
category : column
Width of the actual column.
category : column
Wrap long lines in the cells of the actual column. The default is defined by directive "default-wrap".
category : table
Switch the exponent format for numbers according directives "default-html-exponent-format" and "default-latex-exponent-format" on or off.
If the switch is off, the ordinary computer notation of exponents by "e" (e.g. 1e3 for one thousand) is left unchanged.
category : table
Horizontal alignment within each table cell.
category : table
Horizontal separator type. Horizontal separators may appear between rows and to the top and bottom sides of the table.
One can choose between horizontal rules of different function/position. The function/position not only defines a thickness, but also vertical spacing in Latex. The thickness of types "top", "mid", "span" and "bottom" can be defined by directives "*-hor-rule".
The types "single" and "double" reflect the horizontal rules coded as \hline and \hline \hline in Latex; their thickness is defined by \arrayrulewidth (0.4 pt at default) in Latex.
category : table
The first argument contains the html code between mantissa and the exponent, the second argument the html code after the exponent.
These codes are only applied if the argument of directive "default-exponent-format" is "on".
In that case, these codes are applied to each real or integer (given as such data, to be translated into text due to the number format directives) and each string (given as such data, containing the ordinary computer notation of exponents by "e") are prone.
Note that the first argument starts with an space, to obtain correct spacing.
category : table
The first argument contains the Latex code between mantissa and the exponent, the second argument the Latex code after the exponent.
These codes are only applied if the argument of directive "default-exponent-format" is "on".
In that case, these codes are applied to each real or integer (given as such data, to be translated into text due to the number format directives) and each string (given as such data, containing the ordinary computer notation of exponents by "e") are prone.
Note that the default latex code \pot{...} is not defined in standard Latex. It may be defined by: \newcommand{\pot}[1]{\ensuremath{\times}space 10\ensuremath{^{#1}}}. Because of this definition, the first argument starts with an space.
category : table
The argument contains a template as used by the sprintf() series of functions to translate a real or integer (given as such data) into text. Data which has been given as text, is not affected by this translation.
The translation is applied to each table cell.
category : table
Vertical separator type. Vertical separators may appear between columns and to the left and right sides of the table.
One can choose between vertical rules of different thickness. The thickness of types "thick", "medium" and "thin" can be defined by directives "*-vert-rule".
The types "single" and "double" reflect the vertical rules coded as "|" and "||" in Latex; their thickness is defined by \arrayrulewidth (0.4 pt at default) in Latex.
category : table
Wrap long lines in each table cell.
category : cell
Horizontal alignment in the actual cell. The default is defined by directive "default-hor-align".
category : table
If set to "on", html classes are used to define rules and alignment in cells. These classes are defined within the <style> element within the <head> element in the html file.
If set to "off", rules and alignment are defined directly by style attributes in each table cell. It is recommended to say "html-classes off" in nested tables when e.g. rule types in the nested table have a different thickness, because html class names are "global" names and are not different for individual tables.
category : cell
Extra html/css style code for the actual cell. This code is appended to the end of the series of style codes within the style attribute of the <td> element. With the extra code one can thus overrule any prior html/css class or style in the actual cell.
category : table
Table width in html code.
At default, the table width in html is set to 100 %: the table will thus take the whole width of the containing html element. This is probably practical for most cases, especially for tables nested in a table. Say "html-table-width auto", so that the table width will depend on the width of the contents.
category : cell
Extra Latex code for the actual cell. The code is inserted just around the contents. The code should therefore contain a special tag which is a placeholder of the cell contents; at default, the tag is: <contents>.
category : table
Name of the environment by which the table is laid-out in Latex: \begin{env-name}...\end{env-name}.
category : table
Table width in Latex code.
category : table
Thickness (and colour code) of vertical rules of type "medium".
The colour is only applied in html; the colour code must be recognised in html/css.
category : table
Thickness (and colour code) of horizontal rules of type "mid".
This type is translated into \midrule[thickness] in Latex and this Latex code is defined by the booktabs package.
The colour is only applied in html; the colour code must be recognised in html/css.
category : cell
The data in the actual cell contains a nested table.
This directive is given, if the nested table is given as a cell array ctbl.
category : cell
The argument contains a template as used by the sprintf() series of functions to translate a real or integer (given as such data) into text. Data which has been given as text, is not affected by this translation.
The translation is applied to the actual cell.
category : row
Row separator type below the actual row. The default is defined by directive "default-hor-sep".
category : row
Horizontal alignment in the cells of the actual row. The default is defined by directive "default-hor-align".
category : row
The argument contains a template as used by the sprintf() series of functions to translate a real or integer (given as such data) into text. Data which has been given as text, is not affected by this translation.
The translation is applied to the cells in the actual row.
category : row
Row separator type above the actual row. The default is defined by directive "default-hor-sep".
This directive will overrule the possibly issued directive "row-bottom-sep" on the previous row, because collapse of separators is applied.
category : table
Thickness (and colour code) of horizontal rules of type "span".
This type is translated into \cmidrule[thickness] in Latex and this Latex code is defined by the booktabs package.
The colour is only applied in html; the colour code must be recognised in html/css.
category : table
Thickness (and colour code) of vertical rules of type "thick".
The colour is only applied in html; the colour code must be recognised in html/css.
category : table
Thickness (and colour code) of vertical rules of type "thin".
The colour is only applied in html; the colour code must be recognised in html/css.
category : table
Thickness (and colour code) of horizontal rules of type "top".
This type is translated into \toprule[thickness] in Latex and this Latex code is defined by the booktabs package.
The colour is only applied in html; the colour code must be recognised in html/css.
category : cell
Row separator type above the actual cell. The default is defined by directive "default-hor-sep".
This directive will overrule the possibly issued directive "bottom-sep" on the previous row, because collapse of separators is applied.