Web based School

Red Hat Linux rhl18

geqn
gtbl
Summary

18

geqn and 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.

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=(z²)+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 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:


italics "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 guide 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
[lb]	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 italic (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.

as the lines in the macro.

Make sure that you don't define a macro with the name of a reserved groff command, or the macro will not be executed.

Using mm

The mm (memorandum macros) package is not really part of nroff or troff, although both can use it. The mm program reads a source file much as groff does and translates it to output. Many of the mm macros are used for man pages. Indeed, many users find the nroff and troff commands too awkward or complicated, whereas mm is fully able to meet all their basic formatting needs.

To add mm commands, you use the period in the first column as with groff. The mm macros are usually quite simple, and easy to work with and use. We can look at the most important of them here.

Like groff, mm runs text together when reformatting, regardless of line breaks in the source file. To force a new paragraph, use the .P command. It forces a line break and adds a blank line to the output. Paragraphs are usually formatted so that they are flush left.

Headings are created with the .H command. For example, the command

.H This is a Heading

will create a break, output the heading text in bold, and leave a bit of a space between the heading and the text that follows it.

There can be seven levels of headings; 1 is the highest and 7 is the lowest. To specify the heading level, add the number as the first argument after the .H command:

.H 2 This is a level 2 heading

The mm heading macro will number the headings automatically, although you can suppress the numbering with the .HU (heading unnumbered) command. To reset the numbering (at a section break, for example), use the .nr (number register) command followed by the heading level and the number to use. For example, the command


.nr H2 1

will restart the numbering of second-level headings at 1.

Lists

Lists are easily created in mm with the .LI (list) command and the .LE (list end) command. This creates a bulleted list. For example, the command


.LI

thing 1

.LI

thing 2

.LE

thing 3

creates a bulleted list of the three bits of text. You can create a list with dashes instead of bullets using the .DL (dash list) command. The mark list command, .ML, creates a list with the character of your choice.

If you want a numbered list, use the .AL (automatic list) command. Lists with no arguments are created with Arabic numbers. To create an alphabetical list (A, B, C, and so on), use the macro command .AL A. Roman numerals (i, ii, iii, iv, v, and so on) can be used with the .AL I command.

You can nest list types as necessary. For example, the command


.AL I

.LI

groff

.AL

.LI

macros

.LI

mm

.LE

.LI

gtbl

.LI

geqn

.LE

will create output that looks like this:


I. groff

1. macros

2. mm

II. gtbl

III. geqn

You have to be careful when terminating each list with an .LE command to ensure that you terminate the proper one. Experimentation and practice help you get the hang of this. You may have noticed that it takes a lot of commands to make a little list!

Font Changes

Changing fonts with mm is quite simple. When working from a period command, the command .B (bold) creates bold text until an .R (restore) command, while .I (italic) does the same until an .R command. If you want to bold or italicize only one word, you can do it after the period command, as this example shows:

This is normal text

.B

This is bold.

So is this.

.R

This is normal.

This is a single


.Bbold

word, though.

When you change only one word, you don't need a .R command.

Changes can be performed within text in the same manner as with groff:


This is an \fIitalics set of words\fR until here.

Footnotes

To create a footnote, use the .FS (footnote start) and .FE (footnote end) commands. Every footnote on a single page will be collected and printed at the bottom. Footnotes are automatically numbered unless you specify another character:


This is normal text.

.FS

This is a footnote with its proper number in front of it.


.FE

This is more normal text.

.FS *

But this is a footnote marked with an asterisk.

.FE

This is even more normal text. At the bottom of the page

will be a numbered footnote and an asterisked footnote.

You can use any valid character for the optional footnote mark, including special characters supported by groff.

Summary

As you might expect, there is a lot to both groff and mm that we haven't looked at. Because groff is seldom used these days, we covered only the most important aspects. As I said earlier, if you want to learn more about groff or mm, find a good reference guide on the subject.