/contrib/groff/src/roff/troff/troff.man

  1'\" t
  2.ig
  3troff.man
  4
  5Last update : 12 Oct 2003
  6
  7This file is part of groff, the GNU roff type-setting system.
  8
  9Copyright (C) 1989, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
 10
 11written by James Clark
 12
 13modified by Werner Lemberg <wl@gnu.org>
 14            Bernd Warken <bwarken@mayn.de>
 15
 16Permission is granted to copy, distribute and/or modify this document
 17under the terms of the GNU Free Documentation License, Version 1.1 or
 18any later version published by the Free Software Foundation; with the
 19Invariant Sections being this .ig-section and AUTHOR, with no
 20Front-Cover Texts, and with no Back-Cover Texts.
 21
 22A copy of the Free Documentation License is included as a file called
 23FDL in the main directory of the groff source package.
 24..
 25.
 26.
 27.\" --------------------------------------------------------------------
 28.\" Setup
 29.\" --------------------------------------------------------------------
 30.
 31.do nr troff_C \n[.C]
 32.cp 0
 33.
 34.mso www.tmac
 35.
 36.if n \{\
 37.  mso tty-char.tmac
 38.  ftr CR R
 39.  ftr CI I
 40.  ftr CB B
 41.\}
 42.
 43.if '\*[.T]'dvi' \
 44.  ftr CB CW
 45.
 46.de TQ
 47.br
 48.ns
 49.TP \\$1
 50..
 51.
 52.\" Like TP, but if specified indent is more than half
 53.\" the current line-length - indent, use the default indent.
 54.de Tp
 55.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
 56.el .TP "\\$1"
 57..
 58.
 59.
 60.\" --------------------------------------------------------------------
 61.\" Title
 62.\" --------------------------------------------------------------------
 63.
 64.TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 65.SH NAME
 66@g@troff \- the troff processor of the groff text formatting system
 67.
 68.
 69.\" --------------------------------------------------------------------
 70.SH SYNOPSIS
 71.\" --------------------------------------------------------------------
 72.
 73.nr a \n(.j
 74.ad l
 75.nr i \n(.i
 76.in +\w'\fB@g@troff 'u
 77.ti \niu
 78.B @g@troff
 79.de OP
 80.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
 81.el .RB "[\ " "\\$1" "\ ]"
 82..
 83.OP \-abcivzCERU
 84.OP \-d cs
 85.OP \-f fam
 86.OP \-F dir
 87.OP \-I dir
 88.OP \-m name
 89.OP \-M dir
 90.OP \-n num
 91.OP \-o list
 92.OP \-r cn
 93.OP \-T name
 94.OP \-w name
 95.OP \-W name
 96.RI "[\ " files\|.\|.\|. "\ ]"
 97.br
 98.ad \na
 99.P
100It is possible to have whitespace between a command line option and
101its parameter.
102.
103.
104.\" --------------------------------------------------------------------
105.SH DESCRIPTION
106.\" --------------------------------------------------------------------
107.
108This manual page describes the GNU version of
109.BR troff .
110It is part of the groff document formatting system.
111.
112It is functionally compatible with UNIX troff, but has many extensions,
113see
114.BR \%groff_diff (@MAN7EXT@).
115Usually it should be invoked using the
116.BR groff (@MAN1EXT@)
117command which will also run preprocessors and postprocessors in the
118appropriate order and with the appropriate options.
119.
120.
121.\" --------------------------------------------------------------------
122.SH OPTIONS
123.\" --------------------------------------------------------------------
124.
125.TP \w'\-dname=s'u+2n
126.B \-a
127Generate an
128.SM ASCII
129approximation of the typeset output.
130.
131.TP
132.B \-b
133Print a backtrace with each warning or error message.
134.
135This backtrace should help track down the cause of the error.
136.
137The line numbers given in the backtrace may not always be correct, for
138.BR @g@troff 's
139idea of line numbers gets confused by
140.B as
141or 
142.B am
143requests.
144.
145.TP
146.B \-c
147Disable color output (always disabled in compatibility mode).
148.
149.TP
150.B \-C
151Enable compatibility mode.
152.
153.TP
154.BI \-d cs
155.TQ
156.BI \-d name = s
157Define
158.I c
159or
160.I name
161to be a string
162.IR s ;
163.I c
164must be a one letter name.
165.
166.TP
167.B \-E
168Inhibit all error messages of
169.BR @g@troff .
170Note that this doesn't affect messages output to standard error by macro
171packages using the
172.B tm
173or
174.B tm1
175requests.
176.
177.TP
178.BI \-f fam
179Use
180.I fam
181as the default font family.
182.
183.TP
184.BI \-F dir
185Search in directory (or directory path)
186.I dir
187for subdirectories
188.BI dev name
189.RI ( name
190is the name of the device) and there for the
191.B DESC
192file and font files.
193.I dir
194is scanned before all other font directories.
195.
196.TP
197.B \-i
198Read the standard input after all the named input files have been
199processed.
200.
201.TP
202.BI \-I dir
203This option may be used to specify a directory to search for
204files (both those on the command line and those named in
205.B \&.psbb
206requests).
207The current directory is always searched first.
208This option may be specified more than once;
209the directories will be searched in the order specified.
210No directory search is performed for files specified using an absolute path.
211.
212.TP
213.BI \-m name
214Read in the file
215.IB name .tmac\fR.
216If it isn't found, try
217.BI tmac. name
218instead.
219.
220It will be first searched for in directories given with the
221.B \-M
222command line option, then in directories given in the
223.B GROFF_TMAC_PATH
224environment variable, then in the current directory (only if in unsafe
225mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and
226@MACRODIR@.
227.
228.TP
229.BI \-M dir
230Search directory (or directory path)
231.I dir
232for macro files.
233.
234This is scanned before all other macro directories.
235.
236.TP
237.BI \-n num
238Number the first page
239.IR num .
240.
241.TP
242.BI \-o list
243Output only pages in
244.IR list ,
245which is a comma-separated list of page ranges;
246.I n
247means print page
248.IR n ,
249.IB m \- n
250means print every page between
251.I m
252and
253.IR n ,
254.BI \- n
255means print every page up to
256.IR n ,
257.IB n \-
258means print every page from
259.IR n .
260.B @g@troff
261will exit after printing the last page in the list.
262.
263.TP
264.BI \-r cn
265.TQ
266.BI \-r name = n
267Set number register
268.I c
269or
270.I name
271to
272.IR n ;
273.I c
274must be a one character name;
275.I n
276can be any troff numeric expression.
277.
278.TP
279.B \-R
280Don't load
281.B troffrc
282and
283.BR troffrc-end .
284.
285.TP
286.BI \-T name
287Prepare output for device
288.IR name ,
289rather than the default
290.BR @DEVICE@ ;
291see
292.BR groff (@MAN1EXT@)
293for a more detailed description.
294.
295.TP
296.B \-U
297Unsafe mode.
298.
299This will enable the following requests:
300.BR open ,
301.BR opena ,
302.BR pso ,
303.BR sy ,
304and
305.BR pi .
306For security reasons, these potentially dangerous requests are disabled
307otherwise.
308.
309It will also add the current directory to the macro search path.
310.
311.TP
312.B \-v
313Print the version number.
314.
315.TP
316.BI \-w name
317Enable warning
318.IR  name .
319Available warnings are described in the section
320.I WARNINGS
321below.
322.
323For example, to enable all warnings, use
324.B \-w
325.BR all .
326Multiple
327.B \-w
328options are allowed.
329.
330.TP
331.BI \-W name
332Inhibit warning
333.IR name .
334Multiple
335.B \-W
336options are allowed.
337.
338.TP
339.B \-z
340Suppress formatted output.
341.
342.
343.\" --------------------------------------------------------------------
344.SH WARNINGS
345.\" --------------------------------------------------------------------
346.
347The warnings that can be given by
348.B @g@troff
349are divided into the following categories.
350.
351The name associated with each warning is used by the
352.B \-w
353and
354.B \-W
355options; the number is used by the
356.B warn
357request, and by the
358.B .warn
359register; it is always a power of 2 to allow bitwise composition.
360.
361.P
362.TS
363tab(@), center, box;
364c c c | c c c
365r rI lB | r rI lB.
366Bit@Code@Warning@Bit@Code@Warning
367_
3680@1@char@10@1024@reg
3691@2@number@11@2048@tab
3702@4@break@12@4096@right-brace
3713@8@delim@13@8192@missing
3724@16@el@14@16384@input
3735@32@scale@15@32768@escape
3746@64@range@16@65536@space
3757@128@syntax@17@131072@font
3768@256@di@18@262144@ig
3779@512@mac@19@524288@color
378.TE
379.
380.P
381.nr x \w'\fBright-brace'+1n+\w'00000'u
382.ta \nxuR
383.
384.TP \nxu+3n
385.BR break "\t4"
386In fill mode, lines which could not be broken so that their length was
387less than the line length.
388.
389This is enabled by default.
390.
391.TP
392.BR char "\t1"
393Non-existent characters.
394.
395This is enabled by default.
396.
397.TP
398.BR color "\t524288"
399Color related warnings.
400.
401.TP
402.BR delim "\t8"
403Missing or mismatched closing delimiters.
404.
405.TP
406.BR di "\t256"
407Use of
408.B di
409or
410.B da
411without an argument when there is no current diversion.
412.
413.TP
414.BR el "\t16"
415Use of the
416.B el
417request with no matching
418.B ie
419request.
420.
421.TP
422.BR escape "\t32768"
423Unrecognized escape sequences.
424.
425When an unrecognized escape sequence is encountered, the escape
426character is ignored.
427.
428.TP
429.BR font "\t131072"
430Non-existent fonts.
431.
432This is enabled by default.
433.
434.TP
435.BR ig "\t262144"
436Invalid escapes in text ignored with the
437.B ig
438request.
439.
440These are conditions that are errors when they do not occur in ignored
441text.
442.
443.TP
444.BR input "\t16384"
445Invalid input characters.
446.
447.TP
448.BR mac "\t512"
449Use of undefined strings, macros and diversions.
450.
451When an undefined string, macro or diversion is used, that string is
452automatically defined as empty.
453.
454So, in most cases, at most one warning will be given for each name.
455.
456.TP
457.BR missing "\t8192"
458Requests that are missing non-optional arguments.
459.
460.TP
461.BR number "\t2"
462Invalid numeric expressions.
463.
464This is enabled by default.
465.
466.TP
467.BR range "\t64"
468Out of range arguments.
469.
470.TP
471.BR reg "\t1024"
472Use of undefined number registers.
473.
474When an undefined number register is used, that register is
475automatically defined to have a value of\~0.
476.
477So, in most cases, at most one warning will be given for use of a
478particular name.
479.
480.TP
481.BR right-brace "\t4096"
482Use of
483.B \[rs]}
484where a number was expected.
485.
486.TP
487.BR scale "\t32"
488Meaningless scaling indicators.
489.
490.TP
491.BR space "\t65536"
492Missing space between a request or macro and its argument.
493.
494This warning will be given when an undefined name longer than two
495characters is encountered, and the first two characters of the name
496make a defined name.
497.
498The request or macro will not be invoked.
499.
500When this warning is given, no macro is automatically defined.
501.
502This is enabled by default.
503.
504This warning will never occur in compatibility mode.
505.
506.TP
507.BR syntax "\t128"
508Dubious syntax in numeric expressions.
509.
510.TP
511.BR tab "\t2048"
512Inappropriate use of a tab character.
513Either use of a tab character where a number was expected, or use of tab
514character in an unquoted macro argument.
515.
516.P
517There are also names that can be used to refer to groups of warnings:
518.
519.TP
520.B all
521All warnings except
522.BR di ,
523.BR mac ,
524and
525.BR reg .
526It is intended that this covers all warnings that are useful with
527traditional macro packages.
528.
529.TP
530.B w
531All warnings.
532.
533.
534.\" --------------------------------------------------------------------
535.SH ENVIRONMENT
536.\" --------------------------------------------------------------------
537.
538.TP
539.SM
540.B GROFF_TMAC_PATH
541A colon separated list of directories in which to search for
542macro files.
543.B @g@troff
544will scan directories given in the
545.B \-M
546option before these, and in standard directories (current directory if
547in unsafe mode, home directory,
548.BR @SYSTEMMACRODIR@ ,
549.BR @LOCALMACRODIR@ ,
550.BR @MACRODIR@ )
551after these.
552.
553.TP
554.SM
555.B GROFF_TYPESETTER
556Default device.
557.
558.TP
559.SM
560.B GROFF_FONT_PATH
561A colon separated list of directories in which to search for the
562.BI dev name
563directory.
564.B @g@troff
565will scan directories given in the
566.B \-F
567option before these, and in standard directories
568.RB ( @LOCALFONTDIR@ ,
569.BR @FONTDIR@ ,
570.BR @LEGACYFONTDIR@ )
571after these.
572.
573.
574.\" --------------------------------------------------------------------
575.SH FILES
576.\" --------------------------------------------------------------------
577.
578.Tp \w'@FONTDIR@/devname/DESC'u+3n
579.B @MACRODIR@/troffrc
580Initialization file (called before any other macro package).
581.
582.TP
583.B @MACRODIR@/troffrc-end
584Initialization file (called after any other macro package).
585.
586.TP
587.BI @MACRODIR@/ name .tmac
588.TQ
589.BI @MACRODIR@/tmac. name
590Macro files
591.
592.TP
593.BI @FONTDIR@/dev name /DESC
594Device description file for device
595.IR name .
596.
597.TP
598.BI @FONTDIR@/dev name / F
599Font file for font
600.I F
601of device
602.IR name .
603.P
604Note that
605.B troffrc
606and
607.B troffrc-end
608are neither searched in the current nor in the home directory by
609default for security reasons (even if the
610.B \-U
611option is given).
612.
613Use the
614.B \-M
615command line option or the
616.B GROFF_TMAC_PATH
617environment variable to add these directories to the search path if
618necessary.
619.
620.
621.\" --------------------------------------------------------------------
622.SH AUTHOR
623.\" --------------------------------------------------------------------
624.
625Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
626.
627.P
628This document is distributed under the terms of the FDL (GNU Free
629Documentation License) version 1.1 or later.
630.
631You should have received a copy of the FDL on your system, it is also
632available on-line at the
633.URL http://www.gnu.org/copyleft/fdl.html "GNU copyleft site" .
634This document was written by James Clark, with modifications from
635.MTO wl@gnu.org "Werner Lemberg"
636and
637.MTO bwarken@mayn.de "Bernd Warken"
638.
639.P
640This document is part of
641.IR groff ,
642the GNU roff distribution.
643.
644.
645.\" --------------------------------------------------------------------
646.SH "SEE ALSO"
647.\" --------------------------------------------------------------------
648.
649.TP
650.BR groff (@MAN1EXT@)
651The main program of the
652.I groff
653system, a wrapper around
654.IR @g@troff .
655.
656.TP
657.BR groff (@MAN7EXT@)
658A description of the
659.I groff
660language, including a short but complete reference of all predefined
661requests, registers, and escapes of plain
662.IR groff .
663From the command line, this is called by
664.RS
665.IP
666.B man 7 groff
667.RE
668.
669.TP
670.BR \%groff_diff (@MAN7EXT@)
671The differences of the
672.I groff
673language and the
674.I classical troff
675language.
676.
677Currently, this is the most actual document of the
678.I groff
679system.
680.
681.TP
682.BR roff (@MAN7EXT@)
683An overview over
684.I groff
685and other
686.I roff
687systems, including pointers to further related documentation.
688.
689.P
690The
691.I groff info
692.IR file ,
693cf.\&
694.BR info (@MAN1EXT@),
695presents all groff documentation within a single document.
696.
697.cp \n[troff_C]
698.
699.\" --------------------------------------------------------------------
700.\" Emacs variables
701.\" --------------------------------------------------------------------
702.
703.\" Local Variables:
704.\" mode: nroff
705.\" End: