gtbl

The gtbl routine is designed to help in the preparation of charts, multicolumn lists, and any other material presented in a tabular format. The gtbl commands are not difficult to work with but can be awkward to learn, so studying examples is the best method.

To use gtbl, two special commands are used to indicate to groff that the area between the two commands is to be processed as gtbl instructions. These two key commands are .TS (table start) and .TE (table end). Commands between these two are processed by gtbl first, which converts the gtbl commands to groff commands; then, the source is passed to groff.

Tables are independent of each other with gtbl, meaning that each must contain all the information for formatting the data within the table and can’t rely on a previous format. Tables contain three types of information: text for the table itself, options that control the behavior of gtbl, and formatting commands to lay out the table itself. The general format of a gtbl source code section is as follows:

.TS

options;

format.

data

.TE

Let’s look at the important parts of the gtbl layout first and then see how they are combined to produce finished tables.

Executing gtbl

Because gtbl is a preprocessor, it is invoked on the source file, and then the results are passed to groff. The simplest way to do this is with the command

gtbl filename | groff

in which the gtbl preprocessor runs against the source in filename and then sends the output to groff. If you are processing more than one file at a time, or you need to send the output of gtbl to another preprocessor, such as geqn, you use piping slightly differently. The command

gtbl filename | geqn | groff

sends the output to geqn and then to groff.

Options

There can be a single line of options after a .TS command that affects the entire table. Any options must follow the .TS command. If more than one option is specified, they must be separated by spaces, commas, or tabs, and terminate in a semicolon. gtbl accepts the following options:

When gtbl attempts to lay out a table, it tries to keep the entire table on one page if possible, even if it has to eject the previous page only partially completed. This sometimes causes problems because gtbl can make mistakes estimating the size of the table prior to generating it, especially if there are embedded line commands that affect spacing or point size. To avoid this problem, some users surround the entire table with the display macros .DS (display start) and .DE (display end). You can ignore this for most tables, unless you start embedding commands within the data.

Format

The format section of the table structure indicates how the columns are to be laid out. Each line in the format section corresponds to one line of data in the finished table. If not enough format lines are specified to match all the lines of data, the last format line specified is used for the remainder of the table. This lets you use a specific format for headers and a single format line for the rest of the table. The format section ends with a period.

Each line in the format section contains a keyletter for each column in the table. Keyletters should be separated by spaces or tabs for each column to enhance readability. Keyletters are case-independent (so you can use upper- or lowercase for the keyletters or a mixture of the two, without affecting the layout). Supported gtbl keyletters are as follows:

A sample format section consists of a letter for each column, unless the entry is repeated across the page. A sample format section looks like this:

c    s    s

l    n    n .

In this sample, the first line of the table is formatted with the first, second, and third columns centered (the s repeats the previous entry). The second and subsequent lines have the first entry left-justified and the next two lined up as numbers. The period ends the format section. If you like, you can put all these format keyletters on a single line, using a comma to separate the lines:

c s s, l n n .

A table formatted by this set of commands looks like this (with random numbers inserted to show the lineup):

        Centered_Title

Entry1  12.23  231.23

Entry2   3.23   45.2

Entry3  45     123.2344

Entry4   3.2     2.3

Numeric data is usually aligned so that the decimal places are in a vertical column. However, sometimes you want to override this format by forcing a movement. The special character \& is used to move the decimal point. The special characters disappear when the table is printed. To show the effect of this special character, the following sample shows normal formatting and entries with the special character embedded (the first column is the source input and the second is the generated output):

14.5      14.5

13        13

1.253      1.253

3\&1.21   31.21

53.2      53.2

6\&2.23   62.23