use man macros to format manual pages. For example, if you create a manual page for a new game called nw, the manual page, called nw.6, may look like the following:

# cat nw.6

.TH Nano-Warrior 6  Games 1/1/98 Linux

.SH NAME

nw - play Nano-Warrior

.SH SYNOPSIS

nw

.B -d

.PP

-d = play deathmatch mode

.SH DESCRIPTION

.PP

The nw command is used to play a game of Nano-Warrior on your Linux

console. Play continues until you are wiped out by hordes of alien

invaders swarming down the screen.

.PP

Don't give up the fight!

.SH FILES

/usr/games/nw

.PP

$HOME/.nw_scores

.SH BUGS

Probably too many.

You can process this manual page and send it to your display with the following:

# groff -Tascii -man nw.6

Nano-Warrior(6)               Linux               Nano-Warrior(6)





NAME

       nw - play Nano-Warrior



SYNOPSIS

       nw -d



       -d = play deathmatch mode



DESCRIPTION

       The  nw  command is used to play a game of Nano-Warrior on

       your Linux console. Play continues until you are wiped out

       by hordes of alien invaders swarming down the screen.



       Don't give up the fight!



FILES

       /usr/games/nw



       $HOME/.nw_scores



BUGS

       Probably too many.

Notice that the man page macros have boldfaced the sections and formatted the following text automatically. A list of these and other manual page macros are found in the man.7 manual page under the /usr/man/man7 directory. You can read this manual page with the following:

# man 7 man

The groff formatting program also comes with other sets of typesetting macros, such as the me, mm, or ms manuscript macros used to format text files. You'll generally need to specify the macro set on the groff command line if you use these commands:

# groff -Tascii -mm myfile.txt

Documentation for several of these macros are in various groff-related manual pages. One of the best documented sets included with your Linux distribution is the mm manuscript macros in the groff_mm manual page. Table 15.1 lists some common macros you can use to produce formatted documents.

Table 15.1. Common groff_mm macros.

Some of the more common commands that don't require a macro set are listed in Table 15.2. Experiment with them to see their effect on your documents before printing.

Table 15.2. Common groff typesetting commands.

When you're ready to produce a formatted document, use the groff command's -T command-line option to produce a document in several different formats. The groff formatter produces PostScript, TeX dvi (discussed next), text, HP printer-control language, or PCL, formats. Look at the following example:

# groff -Tascii -mm myfile.txt >myfile.txt

# groff -Tps -mm myfile.txt >myfile.ps

# groff -Tdvi -mm myfile.txt >myfile.dvi

You can preview these documents before printing by using several different programs, such as ghostview for PostScript, or xdvi, for dvi files.

Formatting Text with TeX

The TeX typesetting system, originally by Donald E. Knuth, is a collection of programs and other utilities used to produce professionally formatted documents. It is a much more sophisticated system than the groff distribution, and includes more than 65 programs, along with related support files, such as libraries, macros, fonts, and documentation.

If you install TeX on your system, you'll need at least 30 megabytes for the main distribution, 10 megabytes for a series of related macros called LaTeX, and eight megabytes

for 50 different fonts. Obviously, describing the entire system and how to use each different program in the TeX system is beyond this hour. But this section shows you how to get started with a sample document.

You'll find documentation for TeX in a variety of places. You can read the manual pages for related files, check the /usr/info directory for TeX info files, and browse to the /usr/lib/texmf/texmf/doc directory. There are 10 different directories of documentation files, but the easiest way to read about your TeX distribution is to use the lynx Web browser with the following:

# lynx /usr/lib/texmf/texmf/doc/index.html

The TeX distribution files are displayed in an organized list, and you can browse through the list to download sample files and guides directly to your home directory. Beginning users should definitely read the TeX Frequently Asked Questions document.

Like the groff program, TeX uses formatting commands inserted in your text files to manipulate how your file looks when printed. You'll create your file, insert appropriate commands or macros to format text, and then process your document through TeX to create an output file, usually in dvi format, that you can preview or print.

To see a sample of TeX using the LaTeX macros, try processing an example file in the TeX directories:

# latex  /usr/lib/texmf/texmf/doc/generic/pstricks/samples.tex

This creates a file called samples.dvi. You should convert the file to PostScript first, then preview the document with the ghostscript program:

# dvips -f <samples.dvi >samples.ps

# ghostview samples.ps

You'll see that you can use TeX to produce complex diagrams and text. But you'll have to make the effort to learn TeX first!