UNIX offers a selection of commands and utilities for printing. In addition, your system probably has a number of home-grown commands. Be guided by your colleagues and system administrator. If they always use a weird little shell script called prinnumup
to send their files to the printer, you'd better use prinnumup too.
This chapter attempts to find a safe ground somewhere between no information at all and a lot of information that won't work on your system. If you get tired of reading "ask your system administrator," think how tired I got of typing it.
The truth is that systems differ. Printers differ. And new models as well as entirely new printers are popping up all over the place. This chapter should guide you through the basics and give you an understanding of what happens to your file from the
time you type troff until the neat, white pages emerge from your printer.
This section covers the basics of printing with nroff and troff. As it explains the ins and outs of how nroff and troff work, it shows the command lines for printing files that contain only troff primitives.
nroff enables you to format your file on the screen instead of (or before) you format it on a printer. (You can do this with troff, too, if you have a graphics terminal with windowing or layering capabilities, and if your local system provides this
To nroff a file containing only troff primitives to the standard output device (screen), use one of these commands:
The choice between piping to pg or to more really depends on your system. Sometimes more produces just a single line of additional text rather than a new screenful.
Printed files will look different, depending on whether they are formatted with nroff or troff. In general, nroffed files exhibit the following characteristics: All values are treated as a number of character positions (spaces) or line spaces. Vertical
space is in multiples of a full linespace. Tabs are set every 8 characters by default. Certain troff requests are not available (for example, .fp, .lg, .ss). Text in italic font is underlined; text in bold font is emboldened by overstriking. Point size and
vertical space requests (.ps and .vs) are ignored. Right-margin justification is turned off for the mm macros.
The options shown in Table 29.1 are available with current versions of nroff and (device-independent) troff:
Table 29.1. nroff/troff Options
(nroff only) produces equally spaced words in adjusted lines instead of using multiples of space character
(nroff only) uses output tabs (instead of spaces) during horizontal spacing to spread output and reduce output character count; tab settings are assumed to be every 8 characters
reads from standard input after files are exhausted
prepends the macro file /usr/lib/tmac.name to the input filein other words, uses the macros in filename
numbers the first output page N
prints only the pages specified in list; use commas to separate page numbers; use hyphens (-) to indicate page range; -12 prints all the pages up to and including page 12; 12- prints page 12 and all subsequent pages in the file (example:
invokes the simultaneous input/output of the .rd primitive; that is, the file to be processed contains at least one .rd primitive
sets register a to value N; DWB (version 3.1) documentation states that register name can be no more than 1 character
(nroff only) stops printing every N pages (default is N=1); this lets you add or change paper; to resume printing, use a linefeed (a newline also works if no pipeline is involved)
(troff only) prepares output for typesetter/printer specified as name; default is post
(nroff only) prepares output for terminal (printer) specified as type; the following types should be known to any system:
Hewlett-Packard 2631 printer in regular mode
Hewlett-Packard 2631 printer in compressed mode
Hewlett-Packard 2631 printer in expanded mode
DASI-300 terminal set to 12 pitch (12 cpi)
DASI 300s printer
DASI-300s printer set to 12 pitch
Teletype Model 37 terminal (default)
Trendata 4000a terminal
DASI-450 (Diablo Hyterm) printer
DASI-450 terminal set to 12 pitch
Anderson Jacobson 832 terminal
generic name for printers that can underline and tab; all text using reverse line feeds (such as files having tables) that is sent to lp must be processed with col.
GE Terminet 300 terminal
(nroff only) sets the emboldening factor (number of character overstrikes) to N, or to 0 if N is not specified
prints only messages generated by the .tm primitive; useful for debugging or, if you are using .tm, to generate a list of some kind
You can use either nroff or troff to process files formatted with the standard macro packages, mm, ms, me, and man.
CAUTION: You cannot use two macro packages to format one file. The urge to do so usually arises when you want to put a manpage in a text file. It can't be done. Make separate files; better yet, put the
manpage in an appendix and refer to it in your text.
Both nroff and troff expect to find a pointer to the appropriate macro package in the /usr/lib/tmac directory and to find the macro file in the /usr/lib./macro directory.
Files that use the mm macros can be printed by using nroff or troff, or by using either of two commands developed specifically for the mm macros. These are mm (which nroffs your file) and mmt (which troffs your file).
A complete listing of nroff and troff options can be found in Table 29.1.
mm uses number registers to keep track of indents, list item numbers and letters, and a host of information related to page layout (page offset, line length, paragraph style, and so forth).
The -r option to nroff/troff lets you set certain number registers on the command line. This initializes the registers because it is done before the macro package is called. Only registers with one-character names can be initialized this way.
NOTE: To initialize a number register, you must set it before the macro package is called. You can initialize registers with two-character names by doing the following:
1. Set the registers in the first lines of your text file:
.nr XX 0
.nr YY 1
.nr ZZ 3
2. Source in the mm macros right after you initialize the number registers:
3. Invoke nroff or troff without the -m option:
Table 29.2 lists the registers that can be initialized with the -r option to nroff/troff.
Table 29.2. Registers That Can Be Initialized on the nroff/troff Command Line
Modifies the first page for memos and letters. If A is set to any nonzero number, the letterhead block is suppressed to accommodate personal stationery.
Sets the type of copy as follows:
OFFICIAL FILE COPY
DATE FILE COPY
DRAFT with single spacing, default paragraph style
DRAFT with double spacing, 10 en paragraph indent
double spacing with 10 en paragraph indent
Sets debug mode. (Formatter will continue processing even if mm detects errors that would otherwise cause processing to stop.)
Controls the font of the subject/date/from fields on memos and letters. If D is 1, these fields are emboldened; if D is 0, the fields are printed in normal font.
Sets the length of the physical page to N (default 11 inches). Specify units with this option since N is scaled.
Specifies page numbering style as follows:
All pages include header
Header replaces footer on page 1; all other pages have a header
Page 1 has no header; all other pages have a header
All pages use section-page as footer
No header on page 1; header on other pages only if .PH is defined
Same as 3, but section-figure
Sets page offset (left margin) to N where N is a scaled value.
Specifies that pages are to be numbered starting with N.
Sets point size and vertical spacing for document. By default point size is 10, vertical spacing is 12.
Sets page width to N where N is a scaled value (default 6i).
The -r option is useful if you have a file that will be printed somewhat differently over the course of its life. As an example, assume the first draft of your document has to be double spaced and have the word "DRAFT" at the bottom of every
page. Set the C register to 4 on your command line:
troff -mm -rC4 docname
As the document nears completion, you have to print it single spaced, but you still want the word "DRAFT" at the bottom of every page:
troff -mm -rC3 docname
When the document is complete, you can use -rC1 to print "OFFICIAL FILE COPY" at the bottom of each page, or you can use -rC0 to omit that line entirely.
The mm macros are the macros of choice throughout much of AT&T. This may explain why mm has been singled out for special treatment. Only mm has its own set of processing commands: mm, to process files with nroff, and mmt, to process files with
NOTE: If your system users always use troff and never use nroff, your system administrator may not have mounted the mm (for nroff) command and may have named the troff version mm (instead of mmt). I know
this sounds loony, but I've seen it happen.
To format a file with mm or mmt, use a command of this form:
mm options filenames
mmt options filenames
NOTE: If you specify a hyphen (-) instead of a filename or filenames on the command line, mm and mmt read standard input instead of files.
As is the case with the nroff and troff commands, the options must precede the filename(s).
The mm and mmt commands have their own set of options; however, they can pass arguments to nroff and troff, so you can use any nroff/troff option as an option to mm/mmt.
mm and mmt can initialize the number registers that can be initialized by the nroff and troff commands. (See Table 29.2.)
You can use either nroff or troff to process files that use the me, ms, or man macros. All of the options shown in Table 29.1 can be used; however, the -r option has limited use because all predefined number registers in me and ms have two-character
Most of man's predefined number registers also have two-character names. You can set register s to 1 to reduce the page size from 8 1/2 by 11 to 5 1/2 by 8.
Error messages are largely self explanatory. They can be generated by the system (if you type torff instead of troff), by nroff or troff, by the macro package, or by the preprocessors. (Chapter 23, Formatting Tables with tbl," Chapter 24,
"Formatting Equations with eqn," Chapter 25, "Drawing Pictures with pic," and Chapter 26, "Creating Graphs with grap" contain information about error messages generated by the proprocessors.
It doesn't really matter whether troff or mm generates a message; you have to correct the error. Errors usually fall into one of the following categories:
Order: Memo type macros for mm or ms are in the wrong order.
Missing one of bracketed pair: You have a .TS but no .TE (or vice versa).
(mm only) No list active: You have a .LI, but no .BL.
Bad or no argument: You've omitted an argument after a .VL or you've specified an impossible number as an argument (5 for .SA, for example).
The one thing to remember is that the line number, helpfully supplied by troff, is the troff output line number. So it's not uncommon to be told that you have an error in line 1500 when your text file is 600 lines long. mm attempts to give you the
source file line number. Don't wager a large amount on its accuracy.
Sometimes documentation customers want electronic files as well as hard copy. If they can't handle troff, they may request ASCII files from you. There's a simple way of complying with this requestuse deroff.
deroff removes all troff requests, macros, and backslash constructs. It also removes tbl commands (that is, everything between the .TS and the .TE), equation commands (everything between the .EQ and the .EN or between the defined eqn delimiters). It can
follow a chain of included files, so if you've sourced in a file with .so or .nx, deroff operates on those files, too. This feature can be suppressed with the -i option, which simply removes the .so and .nx lines from your file.
Other options are -mm and -ml. -mm completely deletes any line that starts with a macro. This means all your headings will be gone. The -ml option invokes -mm and removes all lists.
This may be just as well. deroff doesn't do well with nested lists.
deroff, like nroff and troff, can process multiple files.
To use deroff, enter the following:
$ deroff options inputfilename > outputfilename
Don't forget to redirect the output to a file. You don't really want to see your denuded, deroffed file streaking across your screen, do you?
Printing is no easier than anything else within the UNIX system, but there are powerful tools to enable you to print just about anything you can imagine. From the simplest print command (lp) to the complexities of preprocessors, troff, and
postprocessors, you can control the process and achieve outstanding results.
Make sure that you're in the draft3 directorythat is, the directory for the new file.
List the files in draft3:
$ ls > difflist
3. Create the following shell script:
for i in 'cat difflist'
diffmk ../draft2/$i $i ../diffdir/d$i
The man command consults a database of stored UNIX system commandsbasically everything that is in the system reference manualsand nroffs it to your screen. If you don't have all that documentation on a shelf in your office, the man command
can save the day.
man is simple to use:
The output is far from beautiful, and it's slow. It's paged to your screen, so you press Enter when you're ready to go on to the next page. You can't backtrack, though. Once you leave the first screenthat is, the one with the command syntax on
itthe only way you can see it again is to run the man command a second time.
If your terminal has windowing or layering capabilities, man can is more useful, because you can look at it and type on your command line at the same time.
You can also print the output from man, but you may not know which printer the output is going to. If you work in a multi-printer environment, this can be a nuisance. Check with your system administrator.
Although the Source Code Control SystemSCCS for shortwas written to keep track of program code, it also makes a good archiving tool for documentation. It saves each version of a text filecode, troff input, and so onand
essentially enables only the owner to change the contents of the file. SCCS is described in detail in Chapter 30, "SCCS Version Control." You can use SCCS to control versions of a document that you often revise. You can also use SCCS on drafts of
a document. If you work with a publications group and your group doesn't have a good archiving and document control system, look into SCCS.