include problem

[unix-history] / .ref-BSD-3 / usr / doc / trofftut / tt01

.NH
Introduction
.tr ^.
.PP
.UL troff
[1]
is a text-formatting program,
written by J. F. Ossanna,
for producing
high-quality printed output from the phototypesetter
on the
.UC UNIX
and
.UC GCOS
operating systems.
This document is an example of
.UL troff
output.
.PP
The single most important rule
of using
.UL troff
is
not to use it directly, but through some intermediary.
In many ways,
.UL troff
resembles an assembly language _
a remarkably powerful and flexible one _
but nonetheless such that many operations must be specified
at a level of detail and in a form that is too hard 
for most people to use effectively.
.PP
For two special applications, there are programs that provide
an interface to
.UL troff
for the majority of users.
.UL eqn 
[2]
provides an easy to learn language for typesetting mathematics;
the 
.UL eqn
user
need know no 
.UL troff
whatsoever
to typeset mathematics.
.UL tbl
[3]
provides the same convenience for producing tables of arbitrary
complexity.
.PP
For producing straight text (which may well contain mathematics or tables), there are a number of `macro packages'
that define formatting rules and operations for specific styles
of documents,
and reduce the amount of
direct contact with 
.UL troff .
In particular, the `\-ms'
[4]
and PWB/MM [5]
packages
for Bell Labs internal memoranda and external papers
provide most of the facilities needed
for a wide range of document preparation.
(This memo was prepared with `\-ms'.)
There are also packages for viewgraphs,
for simulating the older
.UL roff
formatters on
.UC UNIX
and
.UC GCOS ,
and for other special applications.
Typically you will find these packages easier to use
than
.UL troff
once you get beyond the most trivial operations;
you should always consider them first.
.PP
In the few cases where existing packages don't do the whole job,
the solution is
.ul
not
to write an entirely new set of
.UL troff
instructions from scratch, but to make small changes
to adapt packages that already exist.
.WS
.PP
In accordance with this philosophy of letting someone else
do the work,
the part of
.UL troff
described here is only a small part of the whole,
although it tries to concentrate on the more useful parts.
In any case, there is no attempt to be complete.
Rather, the emphasis is on showing how to do simple things,
and how to make incremental changes to what already exists.
The contents of the remaining sections are:
.sp
.nf
.in .1i
.ta .3i
\02.	Point sizes and line spacing
\03.	Fonts and special characters
\04.	Indents and line length
\05.	Tabs
\06.	Local motions: Drawing lines and characters
\07.	Strings
\08.	Introduction to macros
\09.	Titles, pages and numbering
10.	Number registers and arithmetic
11.	Macros with arguments
12.	Conditionals
13.	Environments
14.	Diversions
	Appendix: Typesetter character set
.sp
.in 0
.fi
The
.UL troff
described here is the C-language version running on
.UC UNIX
at
Murray Hill,
as documented in [1].
.WS
.PP
To use
.UL troff
you have to prepare not only the actual text you want printed,
but some information that tells
.ul
how
you want it printed.
(Readers who use
.UL roff
will find the approach familiar.)
For
.UL troff
the text
and
the formatting information are often intertwined quite intimately.
Most commands to
.UL troff
are placed on a line separate from the text itself,
beginning with a period (one command per line).
For example,
.P1
Some text.
^ps 14
Some more text.
.P2
will change the `point size',
that is,
the size of the letters being printed,
to `14 point' (one point is 1/72 inch) like this:
.P1
.fi
Some text.
.ps 14
Some more text.
.ps 10
.P2
.PP
Occasionally, though,
something special occurs in the middle of a line _
to produce
.P1
Area = \(*p\fIr\fR\|\s8\u2\d\s0
.P2
you have to type
.P1
Area = \e(*p\efIr\efR\e\^|\^\es8\eu2\ed\es0
.P2
(which we will explain shortly).
The backslash character
.BD  \e 
is used 
to introduce
.UL troff
commands and special characters within a line of text.