Hey, Emacs, edit this file in -*- nroff-fill -*- mode!
 This module is believed to contain source code proprietary to AT&T.
 Use and redistribution is subject to the Berkeley Software License
 Agreement and your Software Agreement with AT&T (Western Electric).

 @(#)tt01 8.1 (Berkeley) 6/8/93
 Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code and documentation must retain the above
 copyright notice, this list of conditions and the following
 disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 All advertising materials mentioning features or use of this software
 must display the following acknowledgement:
 
 This product includes software developed or owned by Caldera
 International, Inc. Neither the name of Caldera International, Inc.
 nor the names of other contributors may be used to endorse or promote
 products derived from this software without specific prior written
 permission.
 
 USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
 INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
 FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 $FreeBSD$

Introduction
.tr ^.


 troff [1]
is a text-formatting program,
written originally by J. F. Ossanna,
for producing
high-quality printed output from the phototypesetter
on the
C UNIX operating system.
This document is an example of
 troff output.


The single most important rule
of using
 troff is
not to use it directly, but through some intermediary.
In many ways,
 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.


For two special applications, there are programs that provide
an interface to
 troff for the majority of users.
 eqn  [2]
provides an easy to learn language for typesetting mathematics;
the 
 eqn user
need know no 
 troff whatsoever
to typeset mathematics.
 tbl [3]
provides the same convenience for producing tables of arbitrary
complexity.


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 
 troff . In particular, the `-ms'
[4], 
PWB/MM [5], and `-me' [6]
packages
for internal memoranda and external papers
provide most of the facilities needed
for a wide range of document preparation.\(dg
.FS
\(dg Most Berkeley Unix sites only have -ms and -me.
.FE
(This memo was prepared with `-ms'.)
There are also packages for viewgraphs,
for simulating the older
 roff formatters,
and for other special applications.
Typically you will find these packages easier to use
than
 troff once you get beyond the most trivial operations;
you should always consider them first.


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
 troff instructions from scratch, but to make small changes
to adapt packages that already exist.
.WS


In accordance with this philosophy of letting someone else
do the work,
the part of
 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:

\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


The
 troff described here is the C-language version supplied with 
C UNIX Version 7 and 32V as documented in [1].
.WS


To use
 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
 roff will find the approach familiar.)
For
 troff the text
and
the formatting information are often intertwined quite intimately.
Most commands to
 troff are placed on a line separate from the text itself,
beginning with a period (one command per line).
For example,

1
Some text.
^ps 14
Some more text.

2
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:

1


Some text.
Some more text.

2


Occasionally, though,
something special occurs in the middle of a line _
to produce

1
Area = \(*pr\|\s8\u2\d\s0

2
you have to type

1
Area = \e(*p\efIr\efR\e\^|\^\es8\eu2\ed\es0

2
(which we will explain shortly).
The backslash character
 \e 
is used 
to introduce
 troff commands and special characters within a line of text.