'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
.\" 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
.\" 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
.\" 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]
.TH TROFF 1 "Aug 24, 2009"
.SH NAME
troff \- typeset or format documents
.SH SYNOPSIS
.LP
.nf
\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]
     [\fB-s\fR\fIN\fR] [\fB-T\fR\fIdest\fR] [\fB-u\fR\fIN\fR] [\fB-z\fR] [\fIfilename\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
\fBtroff\fR formats text in the \fIfilename\fRs for typesetting or laser
printing. Input to \fBtroff\fR is expected to consist of text interspersed with
formatting requests and macros. If no \fIfilename\fR argument is present,
\fBtroff\fR reads standard input. A minus sign (\(mi) as a \fIfilename\fR
indicates that standard input should be read at that point in the list of input
files.
.sp
.LP
The output of \fBtroff\fR is usually piped through \fBdpost\fR(1) to create a
printable postscript file (see \fBEXAMPLES\fR).
.SH OPTIONS
.sp
.LP
The following options are supported. They may appear in any order, but all must
appear before the first \fIfilename\fR.
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 10n
Send an \fBASCII\fR approximation of formatted output to standard output.
(Note: a rough \fBASCII\fR version can also be printed out on ordinary
terminals with an old and rarely used command, \fB/usr/bin/ta\fR.)
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 10n
Do not print a trailer after the final page of output or cause the
postprocessor to relinquish control of the device.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fIdir\fR\fR
.ad
.RS 10n
Search directory \fIdir\fR for font width or terminal tables instead of the
system default directory.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 10n
Read standard input after all input files are exhausted.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fIname\fR\fR
.ad
.RS 10n
Prepend the macro file \fB/usr/share/lib/tmac/\fR\fIname\fR to the input
\fIfilename\fRs. Note: most references to macro packages include the leading
\fIm\fR as part of the name; for example, the \fBman\fR(7) macros reside in
\fB/usr/share/lib/tmac/an\fR. The macro directory can be changed by setting the
\fBTROFFMACS\fR environment variable to a specific path. Be certain to include
the trailing '\|/\|' (slash) at the end of the path.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fIN\fR\fR
.ad
.RS 10n
Number the first generated page \fIN\fR.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fIlist\fR\fR
.ad
.RS 10n
Print only pages whose page numbers appear in the comma-separated \fIlist\fR of
numbers and ranges.  A range \fIN\fR\fB\(mi\fR\fIM\fR means pages \fIN\fR
through \fIM\fR; an initial \fB\(mi\fR\fIN\fR means from the beginning to page
\fIN\fR; and a final \fIN\fR\fB\(mi\fR means from \fIN\fR to the end.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 10n
Quiet mode in \fBnroff\fR; ignored in \fBtroff\fR.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fIaN\fR\fR
.ad
.RS 10n
Set register \fIa\fR (one-character names only) to \fIN\fR.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fIN\fR\fR
.ad
.RS 10n
Stop the phototypesetter every \fIN\fR pages. On some devices, \fBtroff\fR
produces a trailer so you can change cassettes; resume by pressing the
typesetter's start button.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fIdest\fR\fR
.ad
.RS 10n
Prepare output for typesetter \fIdest\fR. The following values can be supplied
for \fIdest\fR:
.sp
.ne 2
.na
\fB\fBpost\fR\fR
.ad
.RS 8n
A PostScript printer; this is the default value. The output of the \fB-T\fR
option must go through \fBdpost\fR(1) before it is sent to a PostScript printer
to obtain the proper output.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fIN\fR\fR
.ad
.RS 10n
Set the emboldening factor for the font mounted in position 3 to \fIN\fR. If
\fIN\fR is missing, then set the emboldening factor to 0.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.RS 10n
Suppress formatted output. Only diagnostic messages and messages output using
the \fB\&.tm\fR request are output.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIfilename\fR\fR
.ad
.RS 12n
The file containing text to be processed by \fBtroff\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBtroff\fR
.sp
.LP
The following example shows how to print an input text file \fBmytext\fR, coded
with formatting requests and macros. The input file contains equations and
tables and must go through the \fBtbl\fR(1) and \fBeqn\fR(1) preprocessors
before it is formatted by \fBtroff\fR with \fBms\fR macros, processed by
\fBdpost\fR(1), and printed by \fBlp\fR(1):

.sp
.in +2
.nf
tbl mytext | eqn | troff -ms | dpost | lp
.fi
.in -2

.SH FILES
.sp
.ne 2
.na
\fB\fB/tmp/trtmp\fR\fR
.ad
.RS 26n
temporary file
.RE

.sp
.ne 2
.na
\fB\fB/usr/share/lib/tmac/*\fR\fR
.ad
.RS 26n
standard macro files
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/font/*\fR\fR
.ad
.RS 26n
font width tables for alternate mounted \fBtroff\fR fonts
.RE

.sp
.ne 2
.na
\fB\fB/usr/share/lib/nterm/*\fR\fR
.ad
.RS 26n
terminal driving tables for \fBnroff\fR
.RE

.SH SEE ALSO
.sp
.LP
.BR checknr (1),
.BR col (1),
.BR dpost (1),
.BR eqn (1),
.BR lp (1),
.BR man (1),
.BR nroff (1),
.BR tbl (1),
.BR attributes (7),
.BR man (7),
.BR me (7),
.BR ms (7)
.SH NOTES
.sp
.LP
\fBtroff\fR is not 8-bit clean because it is by design based on 7-bit
\fBASCII.\fR
.sp
.LP
Previous documentation incorrectly described the numeric register \fByr\fR as
being the \fBLast two digits of current year\fR. \fByr\fR is in actuality the
number of years since 1900. To correctly obtain the last two digits of the
current year through the year 2099, the definition given below of string
register \fByy\fR may be included in a document and subsequently used to
display a two-digit year. Note that any other available one- or two-character
register name may be substituted for \fByy\fR.
.sp
.in +2
.nf
\&.\e" definition of new string register yy--last two digits of year
\&.\e" use yr (# of years since 1900) if it is < 100
\&.ie \en(yr<100 .ds yy \en(yr
\&.el \e{             .\e" else, subtract 100 from yr, store in ny
\&.nr ny \en(yr-100
\&.ie \en(ny>9 \e{     .\e" use ny if it is two digits
\&.ds yy \en(ny
\&.\e" remove temporary number register ny
\&.rr ny \e}
\&.el \e{.ds yy 0
\&.\e" if ny is one digit, append it to 0
\&.as yy \en(ny
\&.rr ny \e} \e}
.fi
.in -2