share/doc/usd/22.trofftut/tt01

   1 .\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode!
   2 .\" This module is believed to contain source code proprietary to AT&T.
   3 .\" Use and redistribution is subject to the Berkeley Software License
   4 .\" Agreement and your Software Agreement with AT&T (Western Electric).
   5 .\"
   6 .\"     @(#)tt01        8.1 (Berkeley) 6/8/93
   7 .\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions are
  11 .\" met:
  12 .\"
  13 .\" Redistributions of source code and documentation must retain the above
  14 .\" copyright notice, this list of conditions and the following
  15 .\" disclaimer.
  16 .\"
  17 .\" Redistributions in binary form must reproduce the above copyright
  18 .\" notice, this list of conditions and the following disclaimer in the
  19 .\" documentation and/or other materials provided with the distribution.
  20 .\"
  21 .\" All advertising materials mentioning features or use of this software
  22 .\" must display the following acknowledgement:
  23 .\"
  24 .\" This product includes software developed or owned by Caldera
  25 .\" International, Inc.  Neither the name of Caldera International, Inc.
  26 .\" nor the names of other contributors may be used to endorse or promote
  27 .\" products derived from this software without specific prior written
  28 .\" permission.
  29 .\"
  30 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  31 .\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  32 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  33 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  34 .\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  35 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  36 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  37 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  38 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  39 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  40 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  41 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  42 .\"
  43 .\" $FreeBSD$
  44 .\"
  45 .NH
  46 Introduction
  47 .tr ^.
  48 .PP
  49 .UL troff
  50 [1]
  51 is a text-formatting program,
  52 written originally by J. F. Ossanna,
  53 for producing
  54 high-quality printed output from the phototypesetter
  55 on the
  56 .UC UNIX
  57 operating system.
  58 This document is an example of
  59 .UL troff
  60 output.
  61 .PP
  62 The single most important rule
  63 of using
  64 .UL troff
  65 is
  66 not to use it directly, but through some intermediary.
  67 In many ways,
  68 .UL troff
  69 resembles an assembly language _
  70 a remarkably powerful and flexible one _
  71 but nonetheless such that many operations must be specified
  72 at a level of detail and in a form that is too hard
  73 for most people to use effectively.
  74 .PP
  75 For two special applications, there are programs that provide
  76 an interface to
  77 .UL troff
  78 for the majority of users.
  79 .UL eqn
  80 [2]
  81 provides an easy to learn language for typesetting mathematics;
  82 the
  83 .UL eqn
  84 user
  85 need know no
  86 .UL troff
  87 whatsoever
  88 to typeset mathematics.
  89 .UL tbl
  90 [3]
  91 provides the same convenience for producing tables of arbitrary
  92 complexity.
  93 .PP
  94 For producing straight text (which may well contain mathematics or tables), there are a number of `macro packages'
  95 that define formatting rules and operations for specific styles
  96 of documents,
  97 and reduce the amount of
  98 direct contact with
  99 .UL troff .
 100 In particular, the `\-ms'
 101 [4],
 102 PWB/MM [5], and `\-me' [6]
 103 packages
 104 for internal memoranda and external papers
 105 provide most of the facilities needed
 106 for a wide range of document preparation.\(dg
 107 .FS
 108 \(dg Most Berkeley Unix sites only have \-ms and \-me.
 109 .FE
 110 (This memo was prepared with `\-ms'.)
 111 There are also packages for viewgraphs,
 112 for simulating the older
 113 .UL roff
 114 formatters,
 115 and for other special applications.
 116 Typically you will find these packages easier to use
 117 than
 118 .UL troff
 119 once you get beyond the most trivial operations;
 120 you should always consider them first.
 121 .PP
 122 In the few cases where existing packages don't do the whole job,
 123 the solution is
 124 .ul
 125 not
 126 to write an entirely new set of
 127 .UL troff
 128 instructions from scratch, but to make small changes
 129 to adapt packages that already exist.
 130 .WS
 131 .PP
 132 In accordance with this philosophy of letting someone else
 133 do the work,
 134 the part of
 135 .UL troff
 136 described here is only a small part of the whole,
 137 although it tries to concentrate on the more useful parts.
 138 In any case, there is no attempt to be complete.
 139 Rather, the emphasis is on showing how to do simple things,
 140 and how to make incremental changes to what already exists.
 141 The contents of the remaining sections are:
 142 .sp
 143 .nf
 144 .in .1i
 145 .ta .3i
 146 \02.    Point sizes and line spacing
 147 \03.    Fonts and special characters
 148 \04.    Indents and line length
 149 \05.    Tabs
 150 \06.    Local motions: Drawing lines and characters
 151 \07.    Strings
 152 \08.    Introduction to macros
 153 \09.    Titles, pages and numbering
 154 10.     Number registers and arithmetic
 155 11.     Macros with arguments
 156 12.     Conditionals
 157 13.     Environments
 158 14.     Diversions
 159         Appendix: Typesetter character set
 160 .sp
 161 .in 0
 162 .fi
 163 The
 164 .UL troff
 165 described here is the C-language version supplied with
 166 .UC UNIX
 167 Version 7 and 32V as documented in [1].
 168 .WS
 169 .PP
 170 To use
 171 .UL troff
 172 you have to prepare not only the actual text you want printed,
 173 but some information that tells
 174 .ul
 175 how
 176 you want it printed.
 177 (Readers who use
 178 .UL roff
 179 will find the approach familiar.)
 180 For
 181 .UL troff
 182 the text
 183 and
 184 the formatting information are often intertwined quite intimately.
 185 Most commands to
 186 .UL troff
 187 are placed on a line separate from the text itself,
 188 beginning with a period (one command per line).
 189 For example,
 190 .P1
 191 Some text.
 192 ^ps 14
 193 Some more text.
 194 .P2
 195 will change the `point size',
 196 that is,
 197 the size of the letters being printed,
 198 to `14 point' (one point is 1/72 inch) like this:
 199 .P1
 200 .fi
 201 Some text.
 202 .ps 14
 203 Some more text.
 204 .ps 10
 205 .P2
 206 .PP
 207 Occasionally, though,
 208 something special occurs in the middle of a line _
 209 to produce
 210 .P1
 211 Area = \(*p\fIr\fR\|\s8\u2\d\s0
 212 .P2
 213 you have to type
 214 .P1
 215 Area = \e(*p\efIr\efR\e\^|\^\es8\eu2\ed\es0
 216 .P2
 217 (which we will explain shortly).
 218 The backslash character
 219 .BD  \e
 220 is used
 221 to introduce
 222 .UL troff
 223 commands and special characters within a line of text.