ch18
Trochę ciekawostek – na weekend (czego to ludzie nie wymyślą ...
geqn and gtbl
- 18 -
geqn and gtbl
geqn
Executing geqn
Equations
Subscripts and Superscripts
Fractions
Square Roots
Summations, Set Theory, and Integrals
Brackets, Bars, and Piles
Matrices
Quoted Text
Character Changes
Using geqn
gtbl
Executing gtbl
Options
Format
Data
Examples
Summary
- 18 -
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.
geqn
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.
Executing geqn
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.
Equations
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.
Subscripts and Superscripts
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.
Fractions
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.
Square Roots
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.
Summations, Set Theory,
and Integrals
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.
Brackets, Bars,
and Piles
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.
Matrices
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.
Quoted Text
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.
Character Changes
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.
Using geqn
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.
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:
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.
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:
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
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.
Examples
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.
Summary
Although word processors have made utilities such as geqn and gtbl
less popular than they used to be, some diehard UNIX people still like to use them.
There are times when you might not be able to produce an equation the way you want
with your favorite word processor, so you might have to return to the basics. Also,
because word processors capable of fancy formulas tend to be expensive, utilities
such as geqn and gtbl are ideal for the occasional user who doesn't
want to spend a lot of money on a seldom-used tool.