troff.man revision 104862 
 t
troff.man

Last update : 9 Jan 2002

This file is part of groff, the GNU roff type-setting system.

Copyright (C) 1989, 2000, 2001, 2002 Free Software Foundation, Inc.

written by James Clark

modified by Werner Lemberg <wl@gnu.org>
 Bernd Warken <bwarken@mayn.de>

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being this .ig-section and AUTHOR, with no
Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
..
.
.
 --------------------------------------------------------------------
 Setup
 --------------------------------------------------------------------
.
.mso www.tmac
.
. mso tty-char.tmac
. ftr CR R
. ftr CI I
. ftr CB B
.\}
.
. ftr CB CW
.


.ns

 \\$1
..
.
 Like TP, but if specified indent is more than half
 the current line-length - indent, use the default indent.
..
.
.
 --------------------------------------------------------------------
 Title
 --------------------------------------------------------------------
.

 @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 NAME
@g@troff - the troff processor of the groff text formatting system
.
.
 --------------------------------------------------------------------
 SYNOPSIS
 --------------------------------------------------------------------
.
.nr a \n(.j
.nr i \n(.i
 @g@troff ..
.OP -abcivzCERU
.OP -d cs
.OP -f fam
.OP -F dir
.OP -m name
.OP -M dir
.OP -n num
.OP -o list
.OP -r cn
.OP -T name
.OP -w name
.OP -W name
 "[ " files\|.\|.\|. " ]" 



It is possible to have whitespace between a command line option and
its parameter.
.
.
 --------------------------------------------------------------------
 DESCRIPTION
 --------------------------------------------------------------------
.
This manual page describes the GNU version of
 troff . It is part of the groff document formatting system.
.
It is functionally compatible with UNIX troff, but has many extensions,
see
 \%groff_diff (@MAN7EXT@). Usually it should be invoked using the
 groff (@MAN1EXT@) command which will also run preprocessors and postprocessors in the
appropriate order and with the appropriate options.
.
.
 --------------------------------------------------------------------
 OPTIONS
 --------------------------------------------------------------------
.

 \w'-dname=s'u+2n
 -a Generate an
 ASCII approximation of the typeset output.
.


 -b Print a backtrace with each warning or error message.
.
This backtrace should help track down the cause of the error.
.
The line numbers given in the backtrace may not always be correct, for
 @g@troff 's idea of line numbers gets confused by
 as or 
 am requests.
.


 -c Disable color output (always disabled in compatibility mode).
.


 -C Enable compatibility mode.
.


 -d cs .TQ
 -d name = s Define
 c or
 name to be a string
 s ;  c must be a one letter name.
.


 -E Inhibit all error messages of
 @g@troff . Note that this doesn't affect messages output to standard error by macro
packages using the
 tm or
 tm1 requests.
.


 -f fam Use
 fam as the default font family.
.


 -F dir Search in directory (or directory path)
 dir for subdirectories
 dev name  ( name is the name of the device) and there for the
 DESC file and font files.
 dir is scanned before all other font directories.
.


 -i Read the standard input after all the named input files have been
processed.
.


 -m name Read in the file
 name .tmac. If it isn't found, try
 tmac. name instead.
.
It will be first searched for in directories given with the
 -M command line option, then in directories given in the
 GROFF_TMAC_PATH environment variable, then in the current directory (only if in unsafe
mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and
@MACRODIR@.
.


 -M dir Search directory (or directory path)
 dir for macro files.
.
This is scanned before all other macro directories.
.


 -n num Number the first page
 num . .


 -o list Output only pages in
 list , which is a comma-separated list of page ranges;
 n means print page
 n ,  m - n means print every page between
 m and
 n ,  - n means print every page up to
 n ,  n - means print every page from
 n .  @g@troff will exit after printing the last page in the list.
.


 -r cn .TQ
 -r name = n Set number register
 c or
 name to
 n ;  c must be a one character name;
 n can be any troff numeric expression.
.


 -R Don't load
 troffrc and
 troffrc-end . .


 -T name Prepare output for device
 name , rather than the default
 @DEVICE@ . .


 -U Unsafe mode.
.
This will enable the following requests:
 open ,  opena ,  pso ,  sy , and
 pi . For security reasons, these potentially dangerous requests are disabled
otherwise.
.
It will also add the current directory to the macro search path.
.


 -v Print the version number.
.


 -w name Enable warning
 name . Available warnings are described in the section
 WARNINGS below.
.
For example, to enable all warnings, use
 -w  all . Multiple
 -w options are allowed.
.


 -W name Inhibit warning
 name . Multiple
 -W options are allowed.
.


 -z Suppress formatted output.
.
.
 --------------------------------------------------------------------
 WARNINGS
 --------------------------------------------------------------------
.
The warnings that can be given by
 @g@troff are divided into the following categories.
.
The name associated with each warning is used by the
 -w and
 -W options; the number is used by the
 warn request, and by the
 .warn register; it is always a power of 2 to allow bitwise composition.
.







Bit@Code@Warning@Bit@Code@Warning
0@1@char@10@1024@reg
1@2@number@11@2048@tab
2@4@break@12@4096@right-brace
3@8@delim@13@8192@missing
4@16@el@14@16384@input
5@32@scale@15@32768@escape
6@64@range@16@65536@space
7@128@syntax@17@131072@font
8@256@di@18@262144@ig
9@512@mac@19@524288@color

.


.nr x \w'right-brace'+1n+\w'00000'u
.

 \nxu+3n
 break "\t4" In fill mode, lines which could not be broken so that their length was
less than the line length.
.
This is enabled by default.
.


 char "\t1" Non-existent characters.
.
This is enabled by default.
.


 color "\t524288" Color related warnings.
.


 delim "\t8" Missing or mismatched closing delimiters.
.


 di "\t256" Use of
 di or
 da without an argument when there is no current diversion.
.


 el "\t16" Use of the
 el request with no matching
 ie request.
.


 escape "\t32768" Unrecognized escape sequences.
.
When an unrecognized escape sequence is encountered, the escape
character is ignored.
.


 font "\t131072" Non-existent fonts.
.
This is enabled by default.
.


 ig "\t262144" Invalid escapes in text ignored with the
 ig request.
.
These are conditions that are errors when they do not occur in ignored
text.
.


 input "\t16384" Invalid input characters.
.


 mac "\t512" Use of undefined strings, macros and diversions.
.
When an undefined string, macro or diversion is used, that string is
automatically defined as empty.
.
So, in most cases, at most one warning will be given for each name.
.


 missing "\t8192" Requests that are missing non-optional arguments.
.


 number "\t2" Invalid numeric expressions.
.
This is enabled by default.
.


 range "\t64" Out of range arguments.
.


 reg "\t1024" Use of undefined number registers.
.
When an undefined number register is used, that register is
automatically defined to have a value of\~0.
.
So, in most cases, at most one warning will be given for use of a
particular name.
.


 right-brace "\t4096" Use of
 \[rs]} where a number was expected.
.


 scale "\t32" Meaningless scaling indicators.
.


 space "\t65536" Missing space between a request or macro and its argument.
.
This warning will be given when an undefined name longer than two
characters is encountered, and the first two characters of the name
make a defined name.
.
The request or macro will not be invoked.
.
When this warning is given, no macro is automatically defined.
.
This is enabled by default.
.
This warning will never occur in compatibility mode.
.


 syntax "\t128" Dubious syntax in numeric expressions.
.


 tab "\t2048" Inappropriate use of a tab character.
Either use of a tab character where a number was expected, or use of tab
character in an unquoted macro argument.
.


There are also names that can be used to refer to groups of warnings:
.


 all All warnings except
 di ,  mac , and
 reg . It is intended that this covers all warnings that are useful with
traditional macro packages.
.


 w All warnings.
.
.
 --------------------------------------------------------------------
 ENVIRONMENT
 --------------------------------------------------------------------
.


  GROFF_TMAC_PATH A colon separated list of directories in which to search for
macro files.
 @g@troff will scan directories given in the
 -M option before these, and in standard directories (current directory if
in unsafe mode, home directory,
 @SYSTEMMACRODIR@ ,  @LOCALMACRODIR@ ,  @MACRODIR@ ) after these.
.


  GROFF_TYPESETTER Default device.
.


  GROFF_FONT_PATH A colon separated list of directories in which to search for the
 dev name directory.
 @g@troff will scan directories given in the
 -F option before these, and in standard directories
 ( @LOCALFONTDIR@ ,  @FONTDIR@ ,  @LEGACYFONTDIR@ ) after these.
.
.
 --------------------------------------------------------------------
 FILES
 --------------------------------------------------------------------
.
.Tp \w'@FONTDIR@/devname/DESC'u+3n
 @MACRODIR@/troffrc Initialization file (called before any other macro package).
.


 @MACRODIR@/troffrc-end Initialization file (called after any other macro package).
.


 @MACRODIR@/ name .tmac .TQ
 @MACRODIR@/tmac. name Macro files
.


 @FONTDIR@/dev name /DESC Device description file for device
 name . .


 @FONTDIR@/dev name / F Font file for font
 F of device
 name . 

Note that
 troffrc and
 troffrc-end are neither searched in the current nor in the home directory by
default for security reasons (even if the
 -U option is given).
.
Use the
 -M command line option or the
 GROFF_TMAC_PATH environment variable to add these directories to the search path if
necessary.
.
.
 --------------------------------------------------------------------
 AUTHOR
 --------------------------------------------------------------------
.
Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
.


This document is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later.
.
You should have received a copy of the FDL on your system, it is also
available on-line at the
RL http://www.gnu.org/copyleft/fdl.html "GNU copyleft site" . This document was written by James Clark, with modifications from
.MTO wl@gnu.org "Werner Lemberg"
and
.MTO bwarken@mayn.de "Bernd Warken"
.


This document is part of
 groff , the GNU roff distribution.
.
.
 --------------------------------------------------------------------
 "SEE ALSO"
 --------------------------------------------------------------------
.


 groff (@MAN1EXT@) The main program of the
 groff system, a wrapper around
 @g@troff . .


 groff (@MAN7EXT@) A description of the
 groff language, including a short but complete reference of all predefined
requests, registers, and escapes of plain
 groff . From the command line, this is called by



 man 7 groff 

.


 \%groff_diff (@MAN7EXT@) The differences of the
 groff language and the
 classical troff language.
.
Currently, this is the most actual document of the
 groff system.
.


 roff (@MAN7EXT@) An overview over
 groff and other
 roff systems, including pointers to further related documentation.
.


The
 groff info  file , cf.\&
 info (@MAN1EXT@), presents all groff documentation within a single document.
.
.
 --------------------------------------------------------------------
 Emacs variables
 --------------------------------------------------------------------
.
 Local Variables:
 mode: nroff
 End: