geqn and gtbl

by Tim Parker

IN THIS CHAPTER

• geqn

• gtbl

Now that you are comfortable with groff, you can look at two useful add-ons for groff: geqn and gtbl. In this chapter, you learn the following:

• What are geqn and gtbl?

• How to create complex equations easily

• How to format tables for groff documents

In the last chapter, you saw how groff can be used to produce formatted documents to both screen and printer. Unfortunately, groff is not the easiest package to work with for complex problems such as tables and equations, so a set of macros for these tasks was developed.

The utilities gtbl and geqn are preprocessors, which means that you write the source code as usual, but then the gtbl and geqn programs scan through and replace their specific commands with groff commands. Except for the specific commands changed, no other changes to the text or groff commands are performed.

The geqn preprocessor is designed for formatting complex equations and printing special symbols. You need only use geqn if you are using groff to create a document with these kinds of characters embedded within them.

Although groff has enough power to provide simple equations, it is not particularly friendly, or powerful enough for more than single-line material. On the other hand, geqn is quite easy to work with. Most aspects of geqn are designed to look like equivalent English commands or words.

You can quickly move through a set of the important parts of geqn. As you will see, it is remarkably easy to work with.

The geqn preprocessor is invoked before the groff formatter. Usually, this is accomplished with a simple pipe command:

geqn filename | groff

This processes filename through geqn, which converts geqn commands to equivalent groff commands and then sends the result to groff for processing.

The command

geqn file1 file2 file3 | groff

processes three files and sends them all to groff.

Remember that many consoles can't display equations properly because they are not bitmapped and don't have the character set available. You may have to output the results to a printer to see any exercises you try. Or if you are running X Window, you can have groff output Postscript and view it on-screen with Ghostscript.

You must tell geqn where equations begin and end by using the commands .EQ (equation start) and .EN (equation end). Within the two commands, anything typed is treated as an equation. For example, the command

.EQ

b=c*(d+x)

.EN

is formatted to the equation

b=c*(d+x)

If you try that line without the equation indicators, feeding it straight to groff, you don't receive the same output because groff can't interpret the characters properly.

You can number equations, as is often required in technical documents, by placing a number after the .EQ command. For example, the command

.EQ 15

b=c*(d+x)

.EN

places the number 15 in the left margin next to the equation.

To place superscripts and subscripts in an equation, use the commands sup and sub. The words sup and sub must be surrounded by spaces. For example, the command

E=mc sup 2

produces Einstein's most famous equation.

To indicate the end of a subscript or superscript and continue with normal characters, use a space or a tilde (~) character. For example, the command

x=(z sup 2)+1

gives you the finished output

x=(z2)+1

which is probably not what you wanted. Instead, use one of the following commands:

x=(z sup 2 )+1



x=(z sup 2~)+1

In these commands, the space or the tilde indicates the end of the superscript. This gives you the following output:

x=(z2)+1

You can subscript subscripts, and superscript superscripts, simply by combining the formats:

y sub x sub 3

You can also produce both subscript and superscript on the same character using the two commands together:

x sub y sup 3

Because a space is used to indicate the end of a subscript or superscript, this can cause a problem when you want spaces either as part of the equation, or to separate words to be converted. To get around this problem, use braces to enclose the subscript or superscript:

w sup {x alpha y}

This shows that the Greek letters are also available, as they are within groff. You can have braces within braces, as well:

omega sub { 2 pi r sup { 2 + rho }}

Try these commands for yourself, and experiment to see the output.

To create a proper-looking fraction, use the keyword over. The geqn preprocessor automatically adjusts the length of the line separating the parts. For example, the command

a = 2b over {3c alpha}

produces an equation with a horizontal line separating the two components, just as if you were writing the equation out on paper.

You can, of course, combine all the other elements of geqn to create more complex-looking equations:

{alpha + beta * gamma sup 3} over {3 sub {4 + alpha}}

When you are combining sup and sub with over, geqn processes sup and sub first, and then it does over, much as you would when writing the equation.

To draw a square root symbol, use the keyword sqrt, and geqn ensures that the square root symbol is properly drawn to enclose all parts of the equation that are indicated as belonging to the square root. Very large square root signs that cover a lot of material on many lines, for example, do not look particularly good when printed. You should consider using the superscript 0.5 instead.

You can use sqrt quite easily. For example, the command

sqrt a+c - 1 over sqrt {alpha + beta}

has the first square root sign over a+c, and the second over the part in braces.

To produce a summation, use the keyword sum and the keywords from and to to show the upper and lower parts of the command. For example, use the command

sum from x=1 to x=100 x sup 2

to create the formula for summing x squared over the range 1 to 100. If you want to use a special word, use braces:

sum from x=1 to {x= inf} x sup 2

This is the same command, except summing from 1 to infinity. The braces ensure that the to component is properly interpreted. If no from or to component is specified, they are not printed.

To use integrals, the keyword int is used, and can again take a from argument:

lim from n=1 xy sup 3 = 9

Other reserved words for geqn are used with set theory. You can use the keywords union and inter for the union and intersect of sets.

As equations get more complicated, you need to use more brackets and braces. You can generate brackets ([]), braces ({}), and parentheses (()) as needed by using the left and right commands:

left { b over d+1} = left ( alpha over {beta + gamma} )

This produces large braces, and parentheses are required to surround the terms. You can nest these, of course, with geqn adjusting the sizes properly. Braces are usually bigger than brackets and parentheses.

For floor and ceiling characters, use the left floor, right floor, left ceiling, and right ceiling commands. For example,

left ceiling x over alpha right ceiling > left floor beta over 2 right floor

draws the equation with the proper vertical bars and ceiling and floor markers.

To create a pile of elements, use the reserved word pile. The following example shows the usage best:

X = left [ pile { a above b above c } right ]

This produces output with the three elements a, b, and c stacked vertically within big braces.

To make a matrix requires a little more work. You could probably make a matrix using the pile command, but if the elements are not of equal height, they will not line up. For that reason, use the keyword matrix. The general format is

matrix {

 ccol { elements }

 ccol { elements }

in which ccol produces centered columns. For left-adjusted columns, use lcol; rcol produces right-adjusted columns. The elements are specified individually. For example, the command

matrix {

 ccol { x sub 1 above y sub 1 }

 ccol { x sub 2 above y sub 2 }

produces the matrix

x1 x2

y1 y2

All matrices must have the same number of elements in each column or geqn can't process the matrix properly.

Any characters placed within quotation marks are not interpreted by geqn. This is useful for text strings that may contain reserved words, such as the following:

italic "beta" = beta + gamma

Here, the word beta will appear in italic without being converted to the beta character.

You can change font and point size with geqn in much the same way as with groff. The default setting is usually Roman 10 point. If you want to set bold characters, use the keyword bold; italic sets italic font.

x=y bold alpha

You can also use the keyword fat, which widens the character (useful for things such as grad characters). These reserved words affect only what immediately follows, so you must use braces if the area to be changed is more than a single block of characters.

x=y*2 bold {alpha + gamma}

To change the size of characters, use the size keyword:

size 16 {alpha + beta}

This sets the enclosed text in 16 point size. Incremental changes are acceptable.

To affect the entire equation, you can use the gsize (global size) and gfont (global font) commands at the start of the geqn block:

.EQ

gsize 14

gfont H

....

This makes it easy to format the equations however you wish.

As you have seen, geqn is quite friendly and easy to use, especially if you are used to writing out equations longhand. You should play around with the system and learn the different features. There are more commands available within geqn, but the main ones have been shown to you. For more information, check the man pages or a good troff book that includes eqn.

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.

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.

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:

center	Centers the table (default is left-justified).
expand	Makes tables as wide as current line length.
box	Encloses the table in a box.
allbox	Encloses each element of the table in a box.
doublebox	Encloses the table in two boxes.
tab (n)	Uses n instead of a tab to separate data.
linesize (n)	Uses point size n for lines or rules.
delim (mn)	Uses m and n as equation delimiters.

When gtbl tries 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 can sometimes cause 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.

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:

l	Left-justified entry
r	Right-justified entry
c	Centered entry
n	Numeric entries lined up by units
a	Aligned on left so that widest entry is centered
s	Previous column format applies across rest of
	column

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

You can see that the numbers usually line up with the decimal point in a vertical row, except where moved over by the \& characters. Even if a number has no decimal point specified (as in the second line of the example), it is lined up as though one were present after the last digit.

The following are a few additional keyletters that can be used to create special formats and make the tables more attractive:

_	Horizontal line in place of column entry.
=	Double horizontal line in place of column entry.
|	Between column entries, draws a vertical line between columns. Before the first keyletters, draws a line to the left of the table. After the last keyletters, draws a line to the right of the table.
||	Between column entries, draws a double vertical line.
e/E	Sets equal width columns. All columns that have a keyletter followed by e or E are set to the same width.
f/F	Followed by a font name or number, changes the entry to the font specified.
n	Any number following a keyletter. Indicates the amount of separation between columns.
p/P	Followed by a number, changes the point size of the entry to the specified number. Increments acceptable.
t/T	Vertically spanned items begin at the top line. Normally, vertically spanning items (more than one line in the table) are centered in the vertical range.
v/V	Followed by a number, gives vertical line spacing.
w/W	Followed by a number, sets the width.

The order of these characters on the format line is not important, although the spacing between each format identifier must still be respected. Multiple letters can be used. The entry

np14w(2.5i)fi

sets the numeric entry (n) in italics (fi), with a point size of 14 (p14) and a minimum column width of 2.5 inches (w(2.5i)).

You may need to change the format of a table midway through--for example, to present summaries. If you must change the format, use the .T& (table continue) command.

Data for the table is entered after all the format specifications have been completed. Data for columns is separated by tabs or any other character indicated in the tabs option. Each line of data is one line of the table. Long lines of data can be broken over several lines of source by using the backslash character as the last character in a line.

Any line starting with a period and followed by anything other than a number is assumed to be a groff command and is ignored by the preprocessor. If a single line of the data consists of only underscore or equal sign characters (single and double lines), it is treated as extending the entire width of the table.

You can embed a block of text within a table by using the text commands of T{ (start of text) and }T (end of text). This lets you enter something that can't be easily entered as a string separated by tabs.

The best way to understand how to use gtbl is to look at some simple examples. Here's a basic table command:

.TS

doublebox;

c c c, l l n.

Name           Dept           Phone

Joe            8A             7263

Mike           9F             2635

Peter          2R             2152

Yvonne         2B             2524

.TE

All of the entries in the data section are separated by tabs. This produces a table with three columns, the first line of which is centered text. The rest of the table has the first and second column left-justified, and the last column aligned by decimal point (there are none in this case). The entire table is surrounded by two boxes.

A slightly more complex example uses a table title, followed by a row of column headings, and then the data. Separate each element in the table by a box in this case:

.TS

allbox;

c s s

c c c

n n n .

Division Results

East           West           North

15             12             14

12             12             18

36             15             24

.TE

Try typing in these examples, or create your own, to see what effect the different commands have. When you've started using gtbl, it isn't that difficult.