2 Copyright (C) 2005, 2006, 2008, 2009
3 Free Software Foundation, Inc.
5 Written by Joachim Walsdorff <Joachim.Walsdorff@urz.uni-heidelberg.de>
7 This file is part of groff, the groff.
9 Permission is granted to copy, distribute and/or modify this document
10 under the terms of the GNU Free Documentation License, Version 1.3 or
11 any later version published by the Free Software Foundation; with the
12 Invariant Sections being this .ig-section and AUTHORS, with no
13 Front-Cover Texts, and with no Back-Cover Texts.
15 A copy of the Free Documentation License is included as a file called
16 FDL in the main directory of the groff source package.
21 .TH GROFF_HDTBL @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
25 groff_hdtbl \- groff `hdtbl' macros for generation of tables
29 Some simple formatting macros. Note that we use `.ig' here and not a
30 comment to make `mandb' 2.4.1 (and probably more recent versions also)
31 happy; otherwise the `.char' lines and the stuff which follows is included
32 in the `whatis' database.
36 .char \[lB] \F[\n[.fam]]\f[R][
37 .char \[rB] \F[\n[.fam]]\f[R]]
39 .char \[or] \F[\n[.fam]]\f[R]\||\|
40 .char \[ell] \F[\n[.fam]]\f[R].\|.\|.
42 .char \[oq] \F[\n[.fam]]\f[R]\[oq]
43 .char \[cq] \F[\n[.fam]]\f[R]\[cq]
48 . \" We have to solve the following problem. In this code
54 . \" the space immediately after `bar' should not be taken from the `C'
55 . \" family. At the same time, this
61 . \" should work also. To fulfill both constraints we emit the
62 . \" family changing commands both as escapes and macro calls.
66 . ds old-fam \\\\n[.fam]
68 . \\$2 \&\\\\$*\F[]\F[\\\\*[old-fam]]
79 . ds old-fam \\\\n[.fam]
81 . \\$1 \\\\$@ \F[]\F[\\\\*[old-fam]]
153 . CR "\[oq]\\$1\[cq]"
155 . CR "\[oq]\\$2\[cq]\c"
163 . CR "\[oq]\\$1\[cq]"
165 . CR "\[oq]\\$2\[cq]\c"
175 macros consist of four base and three optional macros, controlled by about
178 The syntax is simple and similar to the
180 table model and nearly as flexible: You can write sequences of tokens (macro
181 calls with their arguments and content data), separated by blanks and
182 beginning with a macro call, into the same line to get compact and cleanly
187 is that the tables are constructed without calling a preprocessor; this
190 full macro capabilities are available.
192 On the other hand, table processing with
194 is much slower than using the
198 A further advantage is that the HTML-like syntax of
200 will be easily converted to HTML; this is not implemented yet.
205 The simplest well-formed table consists of just single calls to the four
206 base table macros in the right order.
208 Here we construct a table with only one cell.
216 .CI contents of the table cell
222 Equivalent to the above is the following notation.
226 .CRI ".TBL .TR .TD " "contents of the table cell" " .ETB"
230 By default, the formatted table is inserted into the surrounding text at the
231 place of its definition.
233 If the vertical space isn't sufficient, it is placed at the top of the next
236 Tables can also be stored for later insertion.
240 .CIR \[oq]row-number * column-number\[cq]
241 as the data for the table cells, a table with two rows and two columns can
248 .CR ". TR .TD 1*1 .TD 1*2"
249 .CR ". TR .TD 2*1 .TD 2*2"
255 Here we see a difference to HTML tables: The number of columns must be
256 explicitly specified using the
257 .CRI \[oq]cols= m\[cq]
258 argument (or indirectly via the
260 argument, see below).
263 The contents of a table cell is arbitrary; for example, it can be another
264 table, without restriction to the nesting depth.
266 A given table layout can be either constructed with suitably nested tables
267 or with proper arguments to
271 , controlling column and row spanning.
273 Note, however, that this table
284 .CR ". TBL cols=2 border="
315 are similar but not identical.
318 Here the latter table in a more compact form.
323 .CR ".TBL cols=2 .TR \[dq].TD colspan=2\[dq] 1*1 1*2"
324 .CR ". TR .TD 2*1 .TD 2*2 .ETB"
329 If a macro has one or more arguments, and it is not starting a line, it must
330 be enclosed in double quotes.
333 .SH MACROS AND ARGUMENTS
335 The order of macro calls and other tokens follows the HTML model.
337 In the following list, valid predecessors and successors of all
339 macros are given, together with the possible arguments.
342 Macro arguments are separated by blanks.
344 The order of arguments is arbitrary; they are of the form
356 .CRI key=\[aq] "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[aq]
360 with the only exception of the optional argument of the macro
362 , which is the string
366 Another possible form is
370 .CRI \[dq]key= "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[dq]
374 However, this is limited to the case where the macro is the first one in the
375 line and not already enclosed in double quotes.
378 Argument values specified below as\~\c
380 are colors predefined by
382 or colors defined by the user with the
388 are decimal numbers with or without decimal point.
396 are numerical values with the usual
400 Some of the arguments are specific to one or two macros, but most of them
401 can be specified with
411 These common arguments are explained in the next subsection.
414 Most of the argument default values can be changed by the user by setting
415 corresponding default registers or strings, as listed below.
417 .\"------------------------------------------------------------------
420 .CBI ".TBL " \[lB]args\[rB]
425 .XB predecessor: .TD .TH .ETB "cell contents"
426 .XB successor: .CPTN .TR
430 .XAA border= \[lB]n\[rB]
431 Thickness of the surrounding box border.
433 .CR \%\[oq]border=\[cq]
434 (no value) means neither a surrounding box border nor any horizontal or
435 vertical separator lines between the table rows and cells.
437 .CR \%\[oq]border=0\[cq]
438 suppresses the surrounding box border, but still allows separator lines
439 between cells and rows.
441 .XDEFR border=.1n t*b
449 Number of table columns.
451 This argument is necessary if more than one column is in the table and no
453 arguments are present.
458 Cell padding, i.e., the extra space between the cell space border and
464 Cell spacing, i.e., the extra space between the table border or
465 vertical or horizontal lines between cells and the cellspace.
469 .XAA tal=l\[or]c\[or]r
470 Horizontal alignment of the table, if it is smaller than the line width.
472 .CR \[oq]tal=l\[cq]\c
475 .CR \[oq]tal=c\[cq]\c
476 : centered alignment.
478 .CR \[oq]tal=r\[cq]\c
483 .XAA "width=\[aq]" "w1 \[lB]w2 \[lB]\[ell]\[rB]\[rB]" \[aq]
484 Widths of table cells.
489 , \[ell] are either numbers of type\~\c
491 or natural numbers with the pseudo-scaling indicator
493 , with the meaning \[lq]percent of the actual line length (or column length
494 for inner tables, respectively)\[rq].
496 If there are less width values than table columns, the last width value is
497 used for the remaining cells.
503 .CR width=\[aq]1.5i 10%\[aq]
507 for example indicates that the first column is 1.5\|inches wide; the
508 remaining columns take 1/10 of the column length each.
511 The table width equals the outer line length or column length; the columns
517 If the table with its contents is lower than\~\c
519 , the last row is stretched to this value.
523 .\"------------------------------------------------------------------
526 .CBI ".CPTN " \[lB]args\[rB]
530 The (optionally numbered) table caption.
537 .XB predecessor: .TBL
543 Vertical alignment of the table caption.
545 .CR \[oq]val=t\[cq]\c
546 : The caption is placed above the table.
548 .CR \[oq]val=b\[cq]\c
549 : The caption is placed below the table.
555 .\"------------------------------------------------------------------
558 .CBI ".TR " \[lB]args\[rB]
559 Begin a new table row.
563 .XB predecessor: .TBL .CPTN .TD .TH .ETB "cell contents"
564 .XB successor: .TD .TH
569 The height of the row.
571 If a cell in the row is higher than\~\c
573 this value is ignored; otherwise the row height is stretched to\~\c
579 .\"------------------------------------------------------------------
582 .CBI ".TD " "\[lB]args \[lB]cell contents\[rB]\[rB]"
583 Begin a table data cell.
585 .CBI ".TH " "\[lB]args \[lB]cell contents\[rB]\[rB]"
586 Begin a table header cell.
589 Arguments and cell contents can be mixed.
593 is not really necessary and differs from
595 only in three default settings, similar to the
599 HTML tags: The contents of
601 is horizontally and vertically centered and typeset in boldface.
605 .XB predecessor: .TR .TD .TH .ETB "cell contents"
606 .XB successor: .TD .TH .TR .ETB "cell contents"
611 The width of this cell is the sum of the widths of the\~\c
613 cells above and below this row.
616 The height of this cell is the sum of the heights of the
618 cells left and right of this column.
622 Overlapping of column and row spanning, as in the following table fragment
623 (the overlapping happens in the second cell in the second row), is invalid
624 and causes incorrect results.
629 .CR ".TR .TD 1*1 \[dq].TD 1*2 rowspan=2\[dq] .TD 1*3"
630 .CR ".TR \[dq].TD 2*1 colspan=2\[dq] .TD 2*3"
636 .\"------------------------------------------------------------------
639 .CB ".ETB \[lB]hold\[rB]"
643 This macro finishes a table.
645 It causes one of the following actions.
651 is given, the table is held until it is freed by calling the macro
653 , which in turn prints the table immediately, either at the current position
654 or at the top of the next page if its height is larger than the remaining
658 Otherwise, if the table is higher than the remaining space on the page,
659 it is printed at the top of the next page.
662 If none of the two above constraints hold, the table is printed immediately
663 at the place of its definition.
668 .XB predecessor: .TD .TH .ETB "cell contents"
669 .XB successor: .TBL .TR .TD .TH .ETB "cell contents"
674 Prevent the table from being printed until it is freed by calling the
679 This argument is ignored for inner (nested) tables.
683 .\"------------------------------------------------------------------
686 .CBI ".t*free " \[lB]n\[rB]
687 Free the next held table or
691 Call this utility macro to print tables which are held by using the
698 .SS Arguments common to \f[CB].TBL\f[], \f[CB].TR\f[], \f[CB].TD\f[], and \f[CB].TH\f[]
700 The arguments described in this section can be specified with the
704 macros, but they are eventually passed on to the table cells.
706 If omitted, the defaults take place, which the user can change by setting
707 the corresponding default registers or strings, as documented below.
709 Setting an argument with the
711 macro has the same effect as setting it for all rows in the table.
713 Setting an argument with a
715 macro has the same effect as setting it for all the
722 .XAA bgc= \[lB]c\[rB]
723 The background color of the table cells.
725 This includes the area specified with the
731 (no value) suppresses a background color; this makes the background
734 .XDEFS bgc=bisque t*bgc
737 The foreground color of the cell contents.
739 .XDEFS fgc=red4 t*fgc
742 The font family for the table.
745 is one of the groff font families, for example
747 for the AvantGarde fonts or
749 for Helvetica-Narrow.
752 The font family found before the table (string
757 The font style for the table.
770 or \f[BI]bold italic\f[], respectively.
777 argument can be used to specify the font family and font style together, for
779 .CR \[oq]fst=HNBI\[cq]
783 .CR \[oq]fst=BI\[cq]\c
787 The font style in use right before the table (string
788 .CR \[oq]t*fst\[cq]\c
791 .XAA "fsz=\[aq]" "d1 \[lB]d2\[rB]" \[aq]
792 A decimal or fractional factor
794 , by which the point size for the table is changed, and
796 , by which the vertical line spacing is changed.
804 .XDEFS "fsz=\[aq]1.0 1.0\[aq]" t*fsz
806 .XAA hal=l\[or]c\[or]b\[or]r
807 Horizontal alignment of the cell contents in the table.
809 .CR \[oq]hal=l\[cq]\c
812 .CR \[oq]hal=c\[cq]\c
813 : centered alignment.
815 .CR \[oq]hal=b\[cq]\c
816 : both (left and right) alignment.
818 .CR \[oq]hal=r\[cq]\c
823 .XAA val=t\[or]m\[or]b
824 Vertical alignment of the cell contents in the table for cells lower
825 than the current row.
827 .CR \[oq]val=t\[cq]\c
828 : alignment below the top of the cell.
830 .CR \[oq]val=m\[cq]\c
831 : alignment in the middle of the cell.
833 .CR \[oq]val=b\[cq]\c
834 : alignment above the cell bottom.
838 .XAA hl=\[lB]s\[or]d\[rB]
839 Horizontal line between the rows.
845 this is a separator line to the cell below.
848 (no value): no separator line.
851 : a single separator line between the rows.
854 : a double separator line.
857 The thickness of the separator lines is the half of the border thickness,
858 but at least 0.1\|inches.
860 The distance between the double lines is equal to the line thickness.
865 .CR \[oq]border=0\[cq]
866 for proper formatting the value of
868 must be at least .05\|inches for single separator lines and .15\|inches for
869 double separator lines.
873 .XAA vl=\[lB]s\[or]d\[rB]
874 Vertical separator line between the cells.
880 this is a separator line to the cell on the right.
883 : a single separator line between the cells.
886 : a double separator line.
889 (no value): no vertical cell separator lines.
891 For more information see the documentation of the
898 .SH HDTBL CUSTOMIZATION
900 A table which does not fit on a partially filled page is printed
901 automatically on the top of the next page if you append the little
904 to the page header macro of your document's main macro package.
923 has built-in page header and page footer macros,
927 If they interfere with your own header and footer macros, simply
937 .MT Joachim.Walsdorff@urz.uni-heidelberg.de
942 .SH BUGS AND SUGGESTIONS
944 Please send your commments to the
948 or directly to the author.
projects / dragonfly.git / blob