usr/src/man/man1/troff.1

   1 '\" te
   2 .\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   4 .\" or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add
   5 .\" the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TROFF 1 "Aug 24, 2009"
   7 .SH NAME
   8 troff \- typeset or format documents
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBtroff\fR [\fB-a\fR] [\fB-f\fR] [\fB-F\fR\fIdir\fR] [\fB-i\fR] [\fB-m\fR\fIname\fR] [\fB-n\fR\fIN\fR] [\fB-o\fR\fIlist\fR] [\fB-r\fR\fIaN\fR]
  13      [\fB-s\fR\fIN\fR] [\fB-T\fR\fIdest\fR] [\fB-u\fR\fIN\fR] [\fB-z\fR] [\fIfilename\fR]...
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 \fBtroff\fR formats text in the \fIfilename\fRs for typesetting or laser
  20 printing. Input to \fBtroff\fR is expected to consist of text interspersed with
  21 formatting requests and macros. If no \fIfilename\fR argument is present,
  22 \fBtroff\fR reads standard input. A minus sign (\(mi) as a \fIfilename\fR
  23 indicates that standard input should be read at that point in the list of input
  24 files.
  25 .sp
  26 .LP
  27 The output of \fBtroff\fR is usually piped through \fBdpost\fR(1) to create a
  28 printable postscript file (see \fBEXAMPLES\fR).
  29 .SH OPTIONS
  30 .sp
  31 .LP
  32 The following options are supported. They may appear in any order, but all must
  33 appear before the first \fIfilename\fR.
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fB-a\fR\fR
  38 .ad
  39 .RS 10n
  40 Send an \fBASCII\fR approximation of formatted output to standard output.
  41 (Note: a rough \fBASCII\fR version can also be printed out on ordinary
  42 terminals with an old and rarely used command, \fB/usr/bin/ta\fR.)
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fB-f\fR\fR
  49 .ad
  50 .RS 10n
  51 Do not print a trailer after the final page of output or cause the
  52 postprocessor to relinquish control of the device.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fB-F\fR\fIdir\fR\fR
  59 .ad
  60 .RS 10n
  61 Search directory \fIdir\fR for font width or terminal tables instead of the
  62 system default directory.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fB-i\fR\fR
  69 .ad
  70 .RS 10n
  71 Read standard input after all input files are exhausted.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fB-m\fR\fIname\fR\fR
  78 .ad
  79 .RS 10n
  80 Prepend the macro file \fB/usr/share/lib/tmac/\fR\fIname\fR to the input
  81 \fIfilename\fRs. Note: most references to macro packages include the leading
  82 \fIm\fR as part of the name; for example, the \fBman\fR(5) macros reside in
  83 \fB/usr/share/lib/tmac/an\fR. The macro directory can be changed by setting the
  84 \fBTROFFMACS\fR environment variable to a specific path. Be certain to include
  85 the trailing '\|/\|' (slash) at the end of the path.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fB-n\fR\fIN\fR\fR
  92 .ad
  93 .RS 10n
  94 Number the first generated page \fIN\fR.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fB-o\fR\fIlist\fR\fR
 101 .ad
 102 .RS 10n
 103 Print only pages whose page numbers appear in the comma-separated \fIlist\fR of
 104 numbers and ranges.  A range \fIN\fR\fB\(mi\fR\fIM\fR means pages \fIN\fR
 105 through \fIM\fR; an initial \fB\(mi\fR\fIN\fR means from the beginning to page
 106 \fIN\fR; and a final \fIN\fR\fB\(mi\fR means from \fIN\fR to the end.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB-q\fR\fR
 113 .ad
 114 .RS 10n
 115 Quiet mode in \fBnroff\fR; ignored in \fBtroff\fR.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB-r\fR\fIaN\fR\fR
 122 .ad
 123 .RS 10n
 124 Set register \fIa\fR (one-character names only) to \fIN\fR.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fB-s\fR\fIN\fR\fR
 131 .ad
 132 .RS 10n
 133 Stop the phototypesetter every \fIN\fR pages. On some devices, \fBtroff\fR
 134 produces a trailer so you can change cassettes; resume by pressing the
 135 typesetter's start button.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-T\fR\fIdest\fR\fR
 142 .ad
 143 .RS 10n
 144 Prepare output for typesetter \fIdest\fR. The following values can be supplied
 145 for \fIdest\fR:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBpost\fR\fR
 150 .ad
 151 .RS 8n
 152 A PostScript printer; this is the default value. The output of the \fB-T\fR
 153 option must go through \fBdpost\fR(1) before it is sent to a PostScript printer
 154 to obtain the proper output.
 155 .RE
 156
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fB-u\fR\fIN\fR\fR
 163 .ad
 164 .RS 10n
 165 Set the emboldening factor for the font mounted in position 3 to \fIN\fR. If
 166 \fIN\fR is missing, then set the emboldening factor to 0.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fB-z\fR\fR
 173 .ad
 174 .RS 10n
 175 Suppress formatted output. Only diagnostic messages and messages output using
 176 the \fB\&.tm\fR request are output.
 177 .RE
 178
 179 .SH OPERANDS
 180 .sp
 181 .LP
 182 The following operand is supported:
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fIfilename\fR\fR
 187 .ad
 188 .RS 12n
 189 The file containing text to be processed by \fBtroff\fR.
 190 .RE
 191
 192 .SH EXAMPLES
 193 .LP
 194 \fBExample 1 \fRUsing \fBtroff\fR
 195 .sp
 196 .LP
 197 The following example shows how to print an input text file \fBmytext\fR, coded
 198 with formatting requests and macros. The input file contains equations and
 199 tables and must go through the \fBtbl\fR(1) and \fBeqn\fR(1) preprocessors
 200 before it is formatted by \fBtroff\fR with \fBms\fR macros, processed by
 201 \fBdpost\fR(1), and printed by \fBlp\fR(1):
 202
 203 .sp
 204 .in +2
 205 .nf
 206 tbl mytext | eqn | troff -ms | dpost | lp
 207 .fi
 208 .in -2
 209
 210 .SH FILES
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fB/tmp/trtmp\fR\fR
 215 .ad
 216 .RS 26n
 217 temporary file
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fB/usr/share/lib/tmac/*\fR\fR
 224 .ad
 225 .RS 26n
 226 standard macro files
 227 .RE
 228
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fB/usr/lib/font/*\fR\fR
 233 .ad
 234 .RS 26n
 235 font width tables for alternate mounted \fBtroff\fR fonts
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fB/usr/share/lib/nterm/*\fR\fR
 242 .ad
 243 .RS 26n
 244 terminal driving tables for \fBnroff\fR
 245 .RE
 246
 247 .SH SEE ALSO
 248 .sp
 249 .LP
 250 \fBchecknr\fR(1), \fBcol\fR(1), \fBdpost\fR(1), \fBeqn\fR(1), \fBlp\fR(1),
 251 \fBman\fR(1), \fBnroff\fR(1), \fBtbl\fR(1), \fBattributes\fR(5), \fBman\fR(5),
 252 \fBme\fR(5), \fBms\fR(5)
 253 .SH NOTES
 254 .sp
 255 .LP
 256 \fBtroff\fR is not 8-bit clean because it is by design based on 7-bit
 257 \fBASCII.\fR
 258 .sp
 259 .LP
 260 Previous documentation incorrectly described the numeric register \fByr\fR as
 261 being the \fBLast two digits of current year\fR. \fByr\fR is in actuality the
 262 number of years since 1900. To correctly obtain the last two digits of the
 263 current year through the year 2099, the definition given below of string
 264 register \fByy\fR may be included in a document and subsequently used to
 265 display a two-digit year. Note that any other available one- or two-character
 266 register name may be substituted for \fByy\fR.
 267 .sp
 268 .in +2
 269 .nf
 270 \&.\e" definition of new string register yy--last two digits of year
 271 \&.\e" use yr (# of years since 1900) if it is < 100
 272 \&.ie \en(yr<100 .ds yy \en(yr
 273 \&.el \e{             .\e" else, subtract 100 from yr, store in ny
 274 \&.nr ny \en(yr-100
 275 \&.ie \en(ny>9 \e{     .\e" use ny if it is two digits
 276 \&.ds yy \en(ny
 277 \&.\e" remove temporary number register ny
 278 \&.rr ny \e}
 279 \&.el \e{.ds yy 0
 280 \&.\e" if ny is one digit, append it to 0
 281 \&.as yy \en(ny
 282 \&.rr ny \e} \e}
 283 .fi
 284 .in -2
 285