.TH troff "" "" Command
.PC "Extended text-formatting language"
\fBtroff [\fIoption ...\^\fB] [\fIfile ...\^\fB]\fR
.PP
.HS
.SH Options:
.IC "\fB\-D\fR"
Display available fonts
.IC "\fB\-f\fI name\fR"
Write temporary file in file \fIname\fR
.IC "\fB\-i\fR"
Read stdin after each \fIfile\fR has been read
.IC "\fB\-k\fR"
Keep temporary file
.IC "\fB\-l\fR"
Landscape mode
.IC "\fB\-m\fIname\fR"
Read macro package \fB/usr/lib/tmac.\fIname\fR
.IC "\fB\-n\fIN\fR"
Number first page of output \fIN\fR (default, one)
.IC "\fB\-p\fR"
Produce PostScript output
.IC "\fB\-r\fIaN\fR"
Set number register \fIa\fR to value \fIN\fR
.IC "\fB\-r\fIabN\fR"
Set number register \fIab\fR to value \fIN\fR; for obvious reasons,
\fIab\fR cannot contain a digit
.IC "\fB\-v\fR"
Return the number of your version
.IC "\fB\-x\fR"
Do not eject to bottom of final page
.HE
The command
.B troff
is the \*(CO typesetter and text-formatting language.
It performs typeset-quality text formatting, suitable for printing on
either the Hewlett-Packard LaserJet II or III printers, or on any
printer for which the PostScript language has been implemented.
.SH "troff Input"
.B troff
processes each given
.IR file ,
or the standard input if none is specified,
and prints the formatted result on the standard output.
The input must consist of text with formatting commands embedded within it.
.PP
.B troff
provides a full suite of commands
that set line length, page
length and page offset, generate vertical and horizontal motions,
indentation, fill and adjust output lines, and center text.
The great flexibility of
.B troff
lies in its acceptance of
user-defined macros to control almost all higher-level formatting.
For example, the formation of paragraphs, header and footer areas,
and footnotes must all be implemented by the user via macros.
.PP
.B troff
uses a superset of the commands and syntax used by
\fBnroff\fR, the other \*(CO text-formatter:
files prepared for the latter usually can be processed through the former
without requiring any changes.
.B troff
differs from \fBnroff\fR in that
.B nroff
can perform only monospaced formatting, whereas
.B troff
can handle multiple fonts of type, both monospaced and proportionally spaced.
It lets you load font-width tables dynamically, so you can use whatever
fonts you have loaded into your printer at a given time.
.B troff
also lets you move about the page in increments other than sixths
of an inch vertically or tenths of an inch horizontally.
.PP
.B troff
produces output either in the Hewlett-Packard Printer Control Language (PCL)
or PostScript, whichever you prefer.
The former can be printed on the Hewlett-Packard LaserJet
family of laser printer, and can use any PCL bitmapped ``soft font''.
The latter can be printed on any printer that supports the PostScript
language, and can use any font for which you have an Adobe Font Metric
description.
The default is PCL output; to obtain PostScript, use the \fB\-p\fR
command-line option.
See below for information on how to manage downloadable fonts.
.SH "Command-line Options"
Command-line options may be listed in any order.
They are as follows:
.IP "\fB\-d\fR" 0.8i
Debug:
print each request before execution.
This option is very useful when you are writing and debugging new macros.
.IP "\fB\-D\fR" 0.8i
Display the available fonts.
These are all the fonts that have been loaded into
.B troff
with the \fB.lf\fR primitive (described below).
.IP "\fB\-f \fIname\fR"
Write the temporary file into file \fIname\fR.
.IP "\fB\-i \fIfiles\fR"
Read from the standard input after reading the given
.IR files .
.IP \fB\-k\fR
Keep: do not erase the temporary file.
.IP \fB\-l\fR
Landscape mode:
output is rotated 90 degrees,
with default size 11 by 8.5 inches rather than 8.5 by 11 inches.
.IP "\fB\-m\fIname\fR"
Include the macro file
.BI /usr/lib/tmac. name
in the input stream.
.IP "\fB\-n\fIN\fR"
Number
the first page of output
.IR N .
.IP "\fB\-p\fR"
Produce output for a PostScript printer
rather than for a HP-compatible printer.
.IP "\fB\-r\fIaN\fR"
Set number register
.I a
to the value
.IR N .
.IP "\fB\-r\fIabN\fR"
Set number register \fIab\fR to value \fIN\fR.
For obvious reasons, \fIab\fR cannot contain a digit.
.IP "\fB\-v\fR"
Return the number of your version.
.IP \fB\-x\fR
Do not eject to the bottom of the last page when text ends.
This option lets you use \fBtroff\fR interactively, which is especially
useful when debugging macros.
.PP
If the environmental variable
.B TROFF
is set when
.B troff
is invoked, its contents are
prefixed to the list of command-line arguments.
This allows the user to set commonly used
options once in the environment rather than on each
.B troff
command line.
.SH "troff Primitives"
As noted earlier,
.BR troff 's
command set is a superset of that used by
.BR nroff :
see the Lexicon entry on
.B nroff
for information on the commands and escape sequences shared by
.B troff
and
.BR nroff .
This article describes the
primitives that
.B troff
does \fInot\fR share with \fBnroff\fR.
.PP
Please note that the basic
.B troff
unit is one-tenth of a point.
A printer's point is 1/12 of a pica, which is in turn one-sixth of an inch;
therefore, there are 72 points and 720
.B troff
units in an inch.
.IP "\fB.co \fIendmark\fR"
Copy input to output file directly, with no processing.
If
.I endmark
argument is present,
.B troff
copies input until it finds a line containing
.I endmark
followed by \fB\en\fR.
If no
.I endmark
is given,
.B troff
copies input until it finds a line containing
\fB.co\en\fR.
This directive is useful for embedding PostScript commands
in an input file.
.IP "\fB.cs \fIXX N M\fR"
Set font
.I XX
to use constant character spacing.
The width of each character is
.I N
divided by 36 ems.
If
.I M
is present, it specifies the width of an em;
otherwise, 
.I N
assumes the point size em for the given font.
.IP "\fB.fd\fR"
Display the currently available fonts.
.IP "\fB.fp \fIN XX\fR"
Associate font name
.I XX
with numeric font position
.IR N .
The given
.I N
should be a number between 1 and 9.
Subsequently, the numeric font position can be used in
an escape sequence \fB\ef\fIN\fR to select the font.
(This nomenclature comes from the
days when phototypesetters used print wheels that were set in fixed
positions on the device.)
The \fBnroff\fR primitive \fB.rf\fR performs a similar task, and is
more flexible in its syntax.
.IP "\fB.fz \fIXX N\fR"
Fix the point size of font
.I XX
at
.IR N .
The point size of the font will not be affected by
subsequent
.B .ps
commands or \fB\\s\fIN\fR point size escapes.
.IP "\fB.lf \fIXX file \fB[\fIn\fB]\fR"
Load font-width table from
.I file
and use it for font
.IR XX .
If
.I file
is not found,
.B troff
looks for
\fB/usr/lib/roff/troff_pcl/fwt/\fIfile\fR
or
\fB/usr/lib/roff/troff_ps/fwt/\fIfile\fR
(depending on whether the
.B \-p
option is used).
.IP
The optional third argument sets the default point size of the loaded font to
.IR n .
Note that this argument takes effect only if \fBtroff\fR is running in
\fB\-p\fR (PostScript) mode.
.IP
For example, to load the font-width table for the PCL bitmapped font
.B cn090rpn.usp
(which sets Century Roman, nine point, portrait mode)
and name it font
.BR RS ,
use the command:
.DM
	.lf RS cn090rpn.usp
.DE
.IP
To do the same thing under PostScript, use the command:
.DM
	.lf RS Century_R.fwt 9
.DE
.IP
Thereafter, you can reference font
.B RS
with either \fB.ft RS\fR or \fB\ef(RS\fR.
.IP
Note that the second argument to this primitive
must name a font-width table generated by the \*(CO command
.BR fwtable ,
not the font itself, although both may have the same name.
.IP
Please note that \fB.lf\fR is unique to the \*(CO implementation of
.BR troff ,
and cannot be ported to other implementations.
.IP "\fB.ps \fIN\fBp\fR"
Set point size to
.I N
points.
The default point size is 10 point.
.IP "\fB.rb \fIfile\fR"
Read input from
.I file
and copy it to the output without processing.
This directive is useful for including files containing PostScript routines
in the output.
.IP "\fB.ss \fIN\fR"
Set the minimum word spacing to \fIN\fR divided by 36 ems.
.IP "\fB.vs \fIN\^\fBp\fR"
Set the vertical spacing to
.I N
points.
The default vertical spacing for
.B troff
is 11 points.
.SH "Escape Sequences"
.B troff
recognizes the following escape sequences,
in addition to those recognized by
.BR nroff :
.IP \fB\e|\fR
Set a 1/6th-em half-narrow space character.
.IP \fB\e^\fR
Set a 1/12th-em half-narrow space character.
.IP \fB\es\(aa\fIN\fB\(aa\fR
Set the point-size escape sequence to
.IR N .
Like the
.B .ps
primitive, it changes the point size to
.IR N .
The specified
.I N
may have a leading plus or minus sign to make the new
size relative to the current point size.
.IP \fB\eX\fIdd\fR
Output character
.I dd ,
where
.I dd
are two hexadecimal digits.
This is useful for forcing \fBtroff\fR to print characters outside the
normal printable range, e.g., those with the high-order bit set.
.B troff
reserves the following values for its internal use:
.DS
.ie t .ta 0.5i 1.5i 2.0i 2.5i
.el   .ta 0.5i 2.5i 3.0i 3.5i
	<ctrl-space>	0X00	Ignored
	<ctrl-A>	0X01	Leader dots, same as ``\ea''
	<ctrl-I>	0X09	Tab, same as ``\et''
	<ctrl-J>	0X10	Newline
.DE
.IP
The hexadecimal values to which characters map depend upon the character
set that you (or your printer) use.
For example, to print the character `\XFB' using the Hewlett-Packard
Laser-Jet printer and the Pacific Page cartridge, use the escape
sequence \fB\eXFB\fR.
.IP
The escape sequence \fB\eX\fR is unique to the \*(CO implementation of
.B nroff
and
.BR troff .
Code that uses it will behave differently when ported to other implementations.
.SH "Number Registers"
The basic unit of measure under
.B troff
is the decipoint, or one-tenth of a printer's point.
A point is one-tenth of a pica, which in turn is one sixth of an inch;
therefore, there are 72 points in an inch, or 720 decipoints.
All
\fBtroff\fR number registers that hold information about page or type
dimensions hold that information in decipoints.
For this reason, the decipoint is sometimes called the ``machine unit.''
.PP
The following table shows how other units of measure translate into
.B troff
machine units:
.DS
.ie t .ta 0.5i 2.0i
.el   .ta 0.5i 3.5i
	inch:	1\fBi\fR = 720\fBu\fR
	vertical line space:	1\fBv\fR = 110\fBu\fR
	centimeter:	1\fBc\fR = 283\fBu\fR
	em:	1\fBm\fR = 100\fBu\fR
	en:	1\fBn\fR = 50\fBu\fR
	pica:	1\fBP\fR = 120\fBu\fR
	point:	1\fBp\fR = 10\fBu\fR
.DE
.PP
If you are working with PostScript, you must remember to divide the value of a
.B troff
number register by ten before you pass the value to PostScript, or you will
see very strange results on your page \(em or likelier, no results at all.
.SH "Special Characters"
.B troff
includes a set of escape sequences for setting special characters.
These escape sequences are defined in the files
.BR /usr/lib/roff/troff_*/specials.r .
If you have additional fonts or an extended PostScript cartridge on your
printer, you can modify these files to change the current definitions or
add new ones.
.PP
The following shows the escape sequences currently defined in
.BR specials.r ,
and the character each prints:
.nf
.sp \n(pDu
.ie t \{\
.ta 0.5i 1.5i 2.0i 3.0i 3.5i 4.5i 5.0i
\e(em	\(em	\e(hy	\(hy	\e(bu	\(bu	\e(sq	\(sq
\e(ru	\(ru	\e(14	\(14	\e(12	\(12	\e(34	\(34
\e(fi	\(fi	\e(fl	\(fl	\e(ff	\(ff	\e(Fi	\(Fi
\e(Fl	\(Fl	\e(de	\(de	\e(dg	\(dg	\e(fm	\(fm
\e(ct	\(ct	\e(rg	\(rg	\e(co	\(co	\e(tm	\(tm
\e(pl	\(pl	\e(mi	\(mi	\e(eq	\(eq	\e(**	\(**
\e(sc	\(sc	\e(aa	\(aa	\e(ga	\(ga	\e(ul	\(ul
\e(sl	\(sl	\e(*a	\(*a	\e(*b	\(*b	\e(*g	\(*g
\e(*d	\(*d	\e(*e	\(*e	\e(*z	\(*z	\e(*y	\(*y
\e(*h	\(*h	\e(*i	\(*i	\e(*k	\(*k	\e(*l	\(*l
\e(*m	\(*m	\e(*n	\(*n	\e(*c	\(*c	\e(*o	\(*o
\e(*p	\(*p	\e(*r	\(*r	\e(*s	\(*s	\e(ts	\(ts
\e(*t	\(*t	\e(*u	\(*u	\e(*f	\(*f	\e(*x	\(*x
\e(*q	\(*q	\e(*w	\(*w	\e(*A	\(*A	\e(*B	\(*B
\e(*G	\(*G	\e(*D	\(*D	\e(*E	\(*E	\e(*Z	\(*Z
\e(*Y	\(*Y	\e(*H	\(*H	\e(*I	\(*I	\e(*K	\(*K
\e(*L	\(*L	\e(*M	\(*M	\e(*N	\(*N	\e(*C	\(*C
\e(*O	\(*O	\e(*P	\(*P	\e(*R	\(*R	\e(*S	\(*S
\e(*T	\(*T	\e(*U	\(*U	\e(*F	\(*F	\e(*X	\(*X
\e(*Q	\(*Q	\e(*W	\(*W	\e(sr	\(sr	\e(rn	\(rn
\e(>=	\(>=	\e(<=	\(<=	\e(==	\(==	\e(~=	\(~=
\e(ap	\(ap	\e(!=	\(!=	\e(->	\(->	\e(<-	\(<-
\e(ua	\(ua	\e(da	\(da	\e(mu	\(mu	\e(di	\(di
\e(+-	\(+-	\e(cu	\(cu	\e(ca	\(ca	\e(sb	\(sb
\e(sp	\(sp	\e(ib	\(ib	\e(ip	\(ip	\e(in	\(in
\e(pd	\(pd	\e(gr	\(gr	\e(no	\(no	\e(is	\(is
\e(pt	\(pt	\e(es	\(es	\e(mo	\(mo	\e(br	\(br
\e(dd	\(dd	\e(rh	\(rh	\e(lh	\(lh	\e(or	\(or
\e(ci	\(ci	\e(lt	\(lt	\e(lb	\(lb	\e(rt	\(rt
\e(rb	\(rb	\e(lk	\(lk	\e(rk	\(rk	\e(bv	\(bv
\e(lf	\(lf	\e(rf	\(rf	\e(lc	\(lc	\e(rc	\(rc
\}
.el \{\
.ta 0.5i 2.5i 3.0i 5.0i 5.5i
\e(em	\(em	\e(hy	\(hy	\e(bu	\(bu
\e(sq	\(sq	\e(ru	\(ru	\e(14	\(14
\e(12	\(12	\e(34	\(34	\e(fi	\(fi
\e(fl	\(fl	\e(ff	\(ff	\e(Fi	\(Fi
\e(Fl	\(Fl	\e(de	\(de	\e(dg	\(dg
\e(fm	\(fm	\e(ct	\(ct	\e(rg	\(rg
\e(co	\(co	\e(tm	\(tm	\e(pl	\(pl
\e(mi	\(mi	\e(eq	\(eq	\e(**	\(**
\e(sc	\(sc	\e(aa	\(aa	\e(ga	\(ga
\e(ul	\(ul	\e(sl	\(sl	\e(*a	\(*a
\e(*b	\(*b	\e(*g	\(*g	\e(*d	\(*d
\e(*e	\(*e	\e(*z	\(*z	\e(*y	\(*y
\e(*h	\(*h	\e(*i	\(*i	\e(*k	\(*k
\e(*l	\(*l	\e(*m	\(*m	\e(*n	\(*n
\e(*c	\(*c	\e(*o	\(*o	\e(*p	\(*p
\e(*r	\(*r	\e(*s	\(*s	\e(ts	\(ts
\e(*t	\(*t	\e(*u	\(*u	\e(*f	\(*f
\e(*x	\(*x	\e(*q	\(*q	\e(*w	\(*w
\e(*A	\(*A	\e(*B	\(*B	\e(*G	\(*G
\e(*D	\(*D	\e(*E	\(*E	\e(*Z	\(*Z
\e(*Y	\(*Y	\e(*H	\(*H	\e(*I	\(*I
\e(*K	\(*K	\e(*L	\(*L	\e(*M	\(*M
\e(*N	\(*N	\e(*C	\(*C	\e(*O	\(*O
\e(*P	\(*P	\e(*R	\(*R	\e(*S	\(*S
\e(*T	\(*T	\e(*U	\(*U	\e(*F	\(*F
\e(*X	\(*X	\e(*Q	\(*Q	\e(*W	\(*W
\e(sr	\(sr	\e(rn	\(rn	\e(>=	\(>=
\e(<=	\(<=	\e(==	\(==	\e(~=	\(~=
\e(ap	\(ap	\e(!=	\(!=	\e(->	\(->
\e(<-	\(<-	\e(ua	\(ua	\e(da	\(da
\e(mu	\(mu	\e(di	\(di	\e(+-	\(+-
\e(cu	\(cu	\e(ca	\(ca	\e(sb	\(sb
\e(sp	\(sp	\e(ib	\(ib	\e(ip	\(ip
\e(in	\(in	\e(pd	\(pd	\e(gr	\(gr
\e(no	\(no	\e(is	\(is	\e(pt	\(pt
\e(es	\(es	\e(mo	\(mo	\e(br	\(br
\e(dd	\(dd	\e(rh	\(rh	\e(lh	\(lh
\e(or	\(or	\e(ci	\(ci	\e(lt	\(lt
\e(lb	\(lb	\e(rt	\(rt	\e(rb	\(rb
\e(lk	\(lk	\e(rk	\(rk	\e(bv	\(bv
\e(lf	\(lf	\e(rf	\(rf	\e(lc	\(lc
\e(rc	\(rc
\}
.fi
.SH "Printer Configuration"
.B troff
reads several files in directory
.B /usr/lib/roff/troff_pcl
(when generating PCL output)
or
.B /usr/lib/roff/troff_ps
(when generating PostScript)
to find printer-specific information.
It reads special character definitions from file
.BR specials.r .
It reads font loading requests from file
.BR fonts.r .
It copies file
.B .pre
at the beginning of the output.
It copies file
.B .post
at the end of the output.
In landscape mode,
.B troff
looks for files
.B .pre_land
and
.B .post_land
instead.
You can change these files as desired to
include printer-specific commands in
.B troff
output.
.SH "Managing Fonts"
.II PCL
.II "Printer Control Language"
.II PostScript
As noted above,
.B troff
produces output in either of two page-description languages:
the Hewlett-Packard Printer Control Language (PCL), which
is the ``native language'' of Hewlett-Packard's LaserJet printers; or
PostScript.
The \*(CO system also comes with tools that lets you process fonts,
so that you can use with
.B troff
either downloadable soft fonts or the fonts that are on board your printer.
.PP
The following two sections describe how to manage fonts under PCL and
under PostScript.
You should refer to the section that is appropriate to your type of printer.
.SH "PCL Fonts"
.II font^PCL
Before
.B troff
can use a font, it must know the following information:
.IP \(bu 0.3i
What the width of every character of the font is, and
.IS \(bu
How it can tell the printer to print that font.
.PP
Both pieces of information are stored in a file called a
.IR "font-width table" .
Before
.B troff
can use a font, it must read the font-width table for that font.
.PP
To load a font-width table into
.BR troff ,
use the primitive \fB.lf\fR.
Its syntax is as follows:
.DS
	\fB.lf \fIXX file
.DE
.PP
.I XX
gives the name by which you will call the font in your
.B troff
program.
.I file
is the font-width table for this font.
If
.I file
is not a full path name,
.B troff
looks for it in directory
.BR /usr/lib/roff/troff_pcl/fwt .
.PP
\*(CO comes with font-width tables for a number of commonly used fonts.
The following tables are for the fonts built into the Hewlett-Packard
LaserJet III:
.LB
.ta 1.75i
\fITable\fR	\fIDescription\fR
\fBCGTimes_B.fwt\fR	Times Bold, scalable, rotatable
\fBCGTimes_BI.fwt\fR	Times Bold Italic, scalable, rotatable
\fBCGTimes_I.fwt\fR	Times Italic, scalable, rotatable
\fBCGTimes_R.fwt\fR	Times Roman, scalable, rotatable
\fBCour10_B.fwt\fR	Courier Bold, ten point, portrait
\fBCour10_I.fwt\fR	Courier Italic, ten point, portrait
\fBCour10_R.fwt\fR	Courier Roman, ten point, portrait
\fBCour12L_B.fwt\fR	Courier Bold, 12 point, landscape
\fBCour12L_R.fwt\fR	Courier Roman, 12 point, landscape
\fBCour12_B.fwt\fR	Courier Bold, 12 point, portrait
\fBCour12_I.fwt\fR	Courier Italic, 12 point, portrait
\fBCour12_R.fwt\fR	Courier Roman, 12 point, portrait
\fBLinepL_R.fwt\fR	Line Printer, 8.5 point, landscape
\fBLinep_R.fwt\fR	Line Printer, 8.5 point, portrait
\fBUnivers_B.fwt\fR	Univers Bold, scalable, rotatable
\fBUnivers_BI.fwt\fR	Univers Bold Italic, scalable, rotatable
\fBUnivers_I.fwt\fR	Univers Italic, scalable, rotatable
\fBUnivers_R.fwt\fR	Univers Roman, scalable, rotatable
.PP
Note that the scalable Hewlett-Packard fonts are set by default at 250 points
in size \(em that is, about 3.5 inches.
Because you cannot scale PCL fonts when you load them, you must use the
.B .ps
primitive to size the font.
.PP
The following
.B troff
program demonstrates scalable fonts on the
Hewlett-Packard LaserJet III:
.DM
	.lf TR CGTimes_R.fwt
	.lf TB CGTimes_B.fwt
	.lf TI CGTimes_I.fwt
	.lf UR Univers_R.fwt
	.lf UB Univers_B.fwt
	.lf UI Univers_I.fwt
	.vs 14p
	.ps 12p
	\ef(TRThis is Times Roman, 12 point.
	.sp
	\ef(TBThis is Times Bold, 12 point.
	.sp
	\ef(TIThis is Times Italic, 12 point.
	.vs 26p
	.ps 24p
	\ef(URThis is Univers Roman, 24 point.
	.sp
	\ef(UBThis is Univers Bold, 24 point.
	.sp
	\ef(UIThis is Univers Italic, 24 point.
	.br
.DE
.PP	
Note that this program does not run correctly if downloaded to a LaserJet II,
or to any printer that is running PostScript.
.PP
The \*(CO command
.B fwtable
lets you build new font-width tables.
It can build tables for PCL bit-mapped soft fonts,
as well as for fonts that are built into the LaserJet III.
.PP
To manipulate PCL bit-mapped soft fonts, do the following:
.IP \(bu 0.3i
Use the command
.B fwtable
to build a font-width table from the font.
The input to
.B fwtable
should be the soft font itself; and the output of
.B fwtable
should be redirected into an appropriately named file.
See the lists of tables given above for an idea of how to name your
font-width table.
.IP \(bu
Move the newly created font-width table into directory
.BR /usr/lib/roff/troff_pcl/fwt .
.IP \(bu
Move the font itself into directory
.BR /usr/lib/roff/troff_pcl/fonts .
You may need to create this directory if this is the first time you are
using soft fonts.
.IP \(bu
Include the instruction
.B .lf
in your
.B troff
file to load the font-width table and name the font, as shown above.
If you use the same fonts repeatedly, you may wish to put the \fB.lf\fR
primitives into a separate file that you always include on your
.B troff
command line via the environmental variable
.BR TROFF .
.IP \(bu
Before you print your document,
load the soft font into your printer.
If you are using the
.B hp
spooler to spool files to your printer, use the command
.BR "hpr \-f" .
If you are using the MLP spooler, then you must pre-process the
font with the command
.BR pclfont ,
then spool the processed font to device
.BR hpraw .
Both commands are described in detail in their Lexicon entries.
Briefly, to load font
.B tr100bpn.usp
into your printer, use the command
.DM
	hpr -f /usr/lib/roff/troff_pcl/fonts/tr100bpn.usp
.DE
.IP
or the command:
.DM
	pclfont /usr/lib/roff/troff_pcl/fonts/tr100bpn.usp | lp -d hpraw
.DE
.IP
These commands also let you specify what ``slot'' to put the font; you can use
this to help manage fonts in your printer.
By placing the frequently used fonts in the lower slots, you can then load
the less-frequently used fonts into the upper slots, and overwrite just those
fonts when you change fonts for another printing job.
You must do such font management by hand \(em \*(CO does not include a
utility to do it for you.
.IP
You may wish to write the font-loading commands into a script that you
execute before you print a job.
You must reload fonts every time you power up your printer or clear its memory.
.PP
To build a font-width table for a font built into your LaserJet III,
do the following:
.IP \(bu 0.3i
Each font on your printer is described with a \fB.tfm\fR file, which comes
on a disk with your printer.
(If you did not receive such a disk, check with the dealer from which you
purchased your printer, or write to Hewlett-Packard.)
Use the \*(CO command
.B doscp 
to copy the \fB.tfm\fR file for the font that interests you from the disk.
.IP \(bu
Use the command
.B "fwtable \-t"
to build the font-width table.
Its input should be the \fB.tfm\fR file that you just uploaded.
Redirect its output into an appropriate named file.
.IP \(bu
Move the newly created font-width table into directory
.BR /usr/lib/roff/troff_pcl/fwt .
.IP \(bu
Note that because the font is build into your printer, you do not need
to download anything before you can use the font.
When
.B troff
reads the font-width table, it will know how to invoke the font on your
printer.
.SH "PostScript Fonts"
.II font^PostScript
Before
.B troff
can use a font, it must know the following information:
.IP \(bu 0.3i
What the width of every character of the font is, and
.IS \(bu
How it can tell the printer to print that font.
.PP
Both pieces of information are stored in a file called a
.IR "font-width table" .
Before
.B troff
can use a font, it must read the font-width table for that font.
.PP
To load a font into
.BR troff ,
use the primitive \fB.lf\fR.
Its syntax is as follows:
.DS
	\fB.lf \fIXX file \fB[\fIn\fB]\fR
.DE
.PP
.I XX
gives the name by which you will call the font in your
.B troff
program.
.I file
is the font-width table for this font.
If
.I file
is not a full path name,
.B troff
looks for it either in directory
.BR /usr/lib/roff/troff_ps/fwt .
.PP
The optional argument
.B n
lets you size the font.
This applies only to PostScript scalable fonts.
All fonts that are loaded with this option are
.I not
affected by the
.B .ps
primitive.
.PP
For example, the instruction
.DM
	.lf HR	HelvNar_R.fwt  12
.DE
.PP
loads a font for PostScript output.
The font is named
.BR HR .
The font-width table is read from file
.BR /usr/lib/roff/troff_ps/HelvNar_R.fwt ,
which defines the font Helvetica Narrow Roman.
Finally, it sizes the font to 12 points.
Hereafter, the instructions
.B ".ft HR"
or
.B "\ef(HR"
invoke this font.
.PP
\*(CO comes with font-width tables for a number of commonly used fonts.
The following tables are for PostScript fonts.
LaserJet III, and are kept in directory
.BR /usr/lib/roff/troff_pcl/fwt .
All are, of course, scalable and rotatable:
.LB
.ta 1.75i
\fITable\fR	\fIDescription\fR
\fBAvant_B.fwt\fR	Avant-Garde Roman (Gothic Book)
\fBAvant_BI.fwt\fR	Avant-Garde Bold Italic
\fBAvant_I.fwt\fR	Avant-Garde Italic
\fBAvant_R.fwt\fR	Avant-Garde Roman
\fBBookman_B.fwt\fR	Bookman Bold
\fBBookman_BI.fwt\fR	Bookman Bold Italic
\fBBookman_I.fwt\fR	Bookman Italic
\fBBookman_R.fwt\fR	Bookman Roman
\fBCentury_B.fwt\fR	Century Bold
\fBCentury_BI.fwt\fR	Century Bold Italic
\fBCentury_I.fwt\fR	Century Italic
\fBCentury_R.fwt\fR	Century Roman
\fBChancery_I.fwt\fR	Zapf Chancery Italic
\fBCourier_B.fwt\fR	Courier Bold
\fBCourier_BI.fwt\fR	Courier Bold Italic
\fBCourier_I.fwt\fR	Courier Italic
\fBCourier_R.fwt\fR	Courier Roman
\fBDingbats.fwt\fR	Zapf Dingbats
\fBHelvNar_B.fwt\fR	Helvetica Narrow Bold
\fBHelvNar_BI.fwt\fR	Helvetica Narrow Bold Italic
\fBHelvNar_I.fwt\fR	Helvetica Narrow Italic
\fBHelvNar_R.fwt\fR	Helvetica Narrow Roman
\fBHelv_B.fwt\fR	Helvetica Bold
\fBHelv_BI.fwt\fR	Helvetica Bold Italic
\fBHelv_I.fwt\fR	Helvetica Italic
\fBHelv_R.fwt\fR	Helvetica Narrow
\fBPala_B.fwt\fR	Zapf Calligraphic Bold (Palatino)
\fBPala_BI.fwt\fR	Zapf Calligraphic Bold Italic
\fBPala_I.fwt\fR	Zapf Calligraphic Italic
\fBPala_R.fwt\fR	Zapf Calligraphic Roman
\fBSymbol.fwt\fR	Symbols
\fBTimes_B.fwt\fR	Times Bold
\fBTimes_BI.fwt\fR	Times Bold Italic
\fBTimes_I.fwt\fR	Times Italic
\fBTimes_R.fwt\fR	Times Roman
.PP
Note that these tables are designed for the fonts used on the Pacific Page
implementation of the PostScript language.
They may not work correctly with genuine Adobe fonts.
.PP
The following gives an example program to demonstrate the PostScript fonts:
.DM
	.lf HR	HelvNar_R.fwt  12
	.lf HC	Avant_B.fwt    24
	.lf DB	Dingbats.fwt    9
	.vs 14
	.sp
	\ef(HRThis is 12-point Helvetic Narrow Roman
	.vs 26
	.sp
	\ef(HCThis is 24-point Avant-Garde
	.vs 11
	.sp
	\efRA row of dingbats:  \ef(DBa row of dingbats
.DE
.PP
This program will not work unless you format using the \fB\-p\fR option to
.BR troff ,
and print it on a PostScript printer.
Please note that because PostScript is a portable language, you can print
the PostScript output of
.B troff
on any printer that implements PostScript, not just the Hewlett-Packard
LaserJet.
.PP
\*(CO comes with tools with which you can ``cook'' fonts so that you can
use with with
.BR troff ,
whether the fonts are downloadable soft fonts or on board a cartridge.
To cook fonts that are on-board a cartridge in your printer, do the
following:
.IP \(bu 0.3i
First, the PostScript cartridge should come with a set of files that
give font-width information.
These have the suffix \fB.afm\fR; there should be one file for each font
in your cartridge.
If you did not receive such a cartridge, contact the dealer from which you
purchased the cartridge, or contact the cartridge's manufacturer.
Use the command
.B doscp
to copy the \fB.afm\fR files from the disk onto your COHERENT system.
.IP \(bu
Use the command
.B "fwtable -p"
to cook each \fB.afm\fR file into
.BR troff 's
font-width table format.
Each font-width table that you create should have the suffix \fB.fwt\fR,
and should be named so that it appropriate describes the font.
See the above table of font-width tables for examples.
.IP \*(bu
Move the newly created font-width tables into directory
.BR /usr/lib/roff/troff_ps/fwt .
.IP \*(bu
Thereafter, when you write a
.B troff
program, use the
.B \&.lf
primitive to load the font-width table.
You may wish to create a file called
.B fonts.r
that routinely loads all of the font-width tables that you use routinely.
You do
.I not
need to load fonts into your printer; the font-width table includes
the information needed so that
.B troff
can invoke them from your cartridge.
.PP
\*(CO
comes with tools to help you manage download soft fonts under PostScript.
Note that the fonts must be in the Adobe Font Metric (AFM) format.
To manage downloadable AFM fonts, do the following:
.IP \(bu 0.3i
A downloadable AFM font comes in three files:
a file of information about the font, which has the suffix \fB.inf\fR;
a file that contains the font-width table, which has the suffix \fB.afm\fR;
and a file that contains the font itself, which has the suffix \fB.pfb\fR.
You can ignore the \fB.inf\fR file; it is not used in this process.
You should use the \*(CO command
.B "doscp -b"
to copy the \fB.pfb\fR from the floppy disk; and use the command
.B "doscp -a"
to copy the \fB.afm\fR file from floppy disk.
(The options \fB\-b\fR and \fB\-a\fR stand, respectively, for binary
and ASCII modes.)
.IP \(bu
Use the command
.DM
	fwtable -p \fIfontname\fP.afm \fIfontname\fP.fwt
.DE
.IP
to generate the font-width table from the
.B \&.afm
file.
Note that the font-width table should have the suffix \fB.fwt\fR.
By convention, you should give the font-width table the same name as the font,
to help you remember which table goes with which font; this, however, is not
required.
For example, to create the font-width table for the Adobe font Avant Garde
bold, use the following command:
.DM
	fwtable -p avgb____.afm avgb____.fwt
.DE
.IP \(bu
Move the newly created font-width table into directory
.BR /usr/lib/roff/troff_ps/fwt .
.IP \(bu
Next, use the command
.B PSfont
to ``cook'' the \fB.pfb\fR file into a form that can be downloaded to your
printer.
Note that a font can be cooked into either of two forms.
The first form permits the font to stay resident in your printer,
so that you can use it to print an indefinite number of documents.
The second form does not permit the font to stay resident in your printer,
but it does permit you to include the font directly within your
.B troff
output.
The first form is the default output of
.BR PSfont ;
to create the second form, invoke
.B PSfont
with its option
.BR \-s .
For example, to cook the font Avant Garde bold into the first output
format, use the command:
.DM
	PSfont avgb____.pfb avgb____.ps1
.DE
.IP
To it into the second form, use the command:
.DM
	PSfont -s avgb____.pfb avgb____.ps2
.DE
.IP
Note that the suffix \fB.ps1\fR indicates the first (stay-resident) form of
the font, whereas the suffix \fB.ps2\fR indicates the second (includable)
form of the font.
These suffixes are simply conventions, and are not required.
.IP \(bu
Move the newly created fonts into directory
.BR /usr/lib/roff/troff_ps/ps .
Note that you may need to create this directory when you first begin to
process fonts.
.IP \(bu
When you create a
.B troff
program, use the primitive
.B \&.lf
to include the font-width table for this font and size the font,
as described above.
.IP \(bu
If you have processed the fonts into the first (stay-resident) form,
you must load them into your printer before you can print any documents.
To download the font, use either the command
.B "hpr -B"
or the command
\fBlp -d\fIprinter\fR (where \fIprinter\fR names the printer to which the
font is being downloaded).
For example, to download the Avant Garde bold font to printer
.BR hpraw ,
use the command:
.DM
	lp -dhpraw /usr/lib/roff/troff_ps/ps/avgb____.ps1
.DE
.IP
(For more information on the command
.BR lp ,
see its entry in the Lexicon, or see the entry for
.BR printer .)
You may wish to create a script to download the fonts that you use commonly.
Note that you must reload the fonts into your printer every time you either
power up the printer or clear out its memory.
Note, too, that downloading and processing stay-resident fonts may take
several minutes, depending upon your printer's make.
.IP \(bu
To use the ``includable'' form of a font, use the
.B troff
primitive
.B .rb
to load it into the
.BR troff .
For example, to include Avant Garde bold directly within your
.B troff
output, include the following statement in your
.B troff
source:
.DM
	.rb /usr/lib/roff/troff_ps/ps/avgb____.ps2
.DE
.IP
If you use some downloadable fonts commonly, you may wish to include
a set of \fB.rb\fR statements for the fonts in file
.BR fonts.r .
Note that files that include downloadable fonts will be
.I much
larger than those that do not use them.
.SH Files
.nf
\fB/tmp/rof*\fR \(em Temporary files
\fB/usr/lib/tmac.*\fR \(em Standard macro packages
\fB/usr/lib/roff/troff_pcl/\fR \(em Support files directory for PCL
\fB/usr/lib/roff/troff_ps/\fR \(em Support files directory for PostScript
\fB/usr/lib/roff/troff_*/.pre\fR \(em  Output prefix
\fB/usr/lib/roff/troff_*/.pre_land\fR \(em Output prefix, landscape mode
\fB/usr/lib/roff/troff_*/.post\fR \(em Output suffix
\fB/usr/lib/roff/troff_*/.post_land\fR \(em Output suffix, landscape mode
\fB/usr/lib/roff/troff_*/fonts.r\fR \(em Font definitions
\fB/usr/lib/roff/troff_*/fwt/\fR \(em Directory for font width tables
\fB/usr/lib/roff/troff_*/specials.r\fR \(em Special character definitions
.SH "See Also"
.Xr "col," col
.Xr "commands," commands
.Xr "deroff," deroff
.Xr "fwtable," fwtable
.Xr "hpr," hpr
.Xr "lp," lp
.Xr "man," man
.Xr "ms," ms
.Xr "nroff," nroff
.Xr "printer," printer
.Xr "PSfont" psfont
.br
\fInroff, The Text-Formatting Language\fR, tutorial
.sp \n(pDu
Adobe Systems Incorporated:
\fIPostScript Language Reference Manual.\fR
Reading, Mass.:
Addison-Wesley Publishing Company, Inc., 1988.
.sp \n(pDu
Adobe Systems Incorporated:
\fIPostScript Language Tutorial and Cookbook.\fR
Reading, Mass.:
Addison-Wesley Publishing Company, Inc., 1988.
.sp \n(pDu
Emerson, S.L., Paulsell, K.:
\fItroff Typesetting for Unix Systems.\fR
Englewood Cliffs, N.J.:
Prentice-Hall, Inc., 1987 (ISBN 0-13-930959-4).
.sp \n(pDu
Lawson, A.:
\fIPrinting Types:
An Introduction\fR.
Boston: Beacon Press, 1971.
.sp \n(pDu
Lawson, A.:
\fIAnatomy of a Typeface.\fR
Boston: David R. Godine, Publisher, 1990.
.SH Diagnostics
For a list of the error messages that
.B troff
can produce, see the Lexicon entry for
.BR nroff .
.SH Notes
Like \fBnroff\fR, \fBtroff\fR should be used with the macro
packages \fBms\fR, which is found in the file \fB/usr/lib/tmac.s\fR,
and \fBman\fR, which is found in the file \fB/usr/lib/tmac.an\fR.
.PP
\fBtroff\fR output, unlike that of \fBnroff\fR, cannot
be processed through a terminal driver.
If you redirect the output of
.B troff
to a terminal, all you will see is the literal program it outputs.
.PP
Laser printers cannot print on an area near each edge of the output page.
Output sent to the unprintable area will disappear.
On some printers, the
.I "logical page"
does not correspond to the
.IR "physical page" ,
so printed
.B troff
output may be offset from the specified position on the physical page.
