diff options
Diffstat (limited to 'src/roff/troff/troff.1.man')
| -rw-r--r-- | src/roff/troff/troff.1.man | 1047 |
1 files changed, 1047 insertions, 0 deletions
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man new file mode 100644 index 0000000..d83c4a5 --- /dev/null +++ b/src/roff/troff/troff.1.man @@ -0,0 +1,1047 @@ +'\" t +.TH @g@troff @MAN1EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +@g@troff \- GNU +.I roff +typesetter and document formatter +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2021 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, 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. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_troff_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY @g@troff +.RB [ \-abcCEiRUz ] +.RB [ \-d\~\c +.IR ctext ] +.RB [ \-d\~\c +.IB string =\c +.IR text ] +.RB [ \-f\~\c +.IR font-family ] +.RB [ \-F\~\c +.IR font-directory ] +.RB [ \-I\~\c +.IR inclusion-directory ] +.RB [ \-m\~\c +.IR macro-package ] +.RB [ \-M\~\c +.IR macro-directory ] +.RB [ \-n\~\c +.IR page-number ] +.RB [ \-o\~\c +.IR page-list ] +.RB [ \-r\~\c +.IR cnumeric-expression ] +.RB [ \-r\~\c +.IB register =\c +.IR numeric-expression ] +.RB [ \-T\~\c +.IR output-device ] +.RB [ \-w\~\c +.IR warning-category ] +.RB [ \-W\~\c +.IR warning-category ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY @g@troff +.B \-\-help +.YS +. +. +.SY @g@troff +.B \-v +. +.SY @g@troff +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +GNU +.I troff \" GNU +transforms +.MR groff @MAN7EXT@ +language input into the device-independent output format described in +.MR groff_out @MAN5EXT@ ; +.I @g@troff +is thus the heart of the GNU +.I roff +document formatting system. +. +If no +.I file +operands are given on the command line, +or if +.I file +is +.RB \[lq] \- \[rq], +the standard input stream is read. +. +. +.P +GNU +.I troff \" GNU +is functionally compatible with the AT&T +.I troff \" AT&T +typesetter and features numerous extensions. +. +Many people prefer to use the +.MR groff @MAN1EXT@ +command, +a front end which also runs preprocessors and output drivers in the +appropriate order and with appropriate options. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-h +and +.B \-\-help +display a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-a +Generate a plain text approximation of the typeset output. +. +The read-only register +.B .A +is set to\~1. +. +This option produces a sort of abstract preview of the formatted output. +. +. +.RS +.IP \[bu] 2n +Page breaks are marked by a phrase in angle brackets; +for example, +\[lq]<beginning of page>\[rq]. +. +. +.IP \[bu] +Lines are broken where they would be in the formatted output. +. +. +.IP \[bu] +A horizontal motion of any size is represented as one space. +. +Adjacent horizontal motions are not combined. +. +Inter-sentence space nodes +(those arising from the second argument to the +.B .ss +request) +are not represented. +. +. +.IP \[bu] +Vertical motions are not represented. +. +. +.IP \[bu] +Special characters are rendered in angle brackets; +for example, +the default soft hyphen character appears as +\[lq]<hy>\[rq]. +.RE +. +. +.IP +The above description should not be considered a specification; +the details of +.B \-a +output are subject to change. +. +. +.TP +.B \-b +Write a backtrace reporting the state of +.IR @g@troff 's +input parser to the standard error stream with each diagnostic message. +. +The line numbers given in the backtrace might not always be correct, +because +.IR @g@troff 's +idea of line numbers can be confused by requests that append to +.\" strings or (??? strings never contain newlines) +macros. +. +. +.TP +.B \-c +Start with color output disabled. +. +. +.TP +.B \-C +Enable AT&T +.I troff \" AT&T +compatibility mode; +implies +.BR \-c . +. +See +.MR groff_diff @MAN7EXT@ . +. +. +.TP +.BI \-d\~ ctext +.TQ +.BI \-d\~ string = text +Define +.I roff +.RI string\~ c +or +.I string +as +.I text. +. +.IR c \~must +be one character; +.I string +can be of arbitrary length. +. +Such string assignments happen before any macro file is loaded, +including the startup file. +. +Due to +.MR getopt_long 3 +limitations, +.IR c\~ cannot +be, +and +.I string +cannot contain, +an equals sign, +even though that is a valid character in a +.I roff +identifier. +. +. +.TP +.B \-E +Inhibit +.I @g@troff +error messages; +implies +.BR \-Ww . +. +This option does +.I not +suppress messages sent to the standard error stream by documents or +macro packages using +.B tm +or related requests. +. +. +.TP +.BI \-f\~ fam +Use +.I fam +as the default font family. +. +. +.TP +.BI \-F\~ dir +Search in directory +.I dir +for the selected output device's directory of device and font +description files. +. +See the description of +.I GROFF_FONT_PATH +in section \[lq]Environment\[rq] below for the default search locations +and ordering. +. +. +.TP +.B \-i +Read the standard input stream after all named input files have been +processed. +. +. +.TP +.BI \-I\~ dir +Search the directory +.I dir +for files +(those named on the command line; +in +.BR psbb , +.BR so , +and +.B soquiet +requests; +and in +.RB \[lq] "\[rs]X\[aq]ps: import\[aq]" \[rq], +.RB \[lq] "\[rs]X\[aq]ps: file\[aq]" \[rq], +and +.RB \[lq] "\[rs]X\[aq]pdf: pdfpic\[aq]" \[rq] +device control escape sequences). +. +.B \-I +may be specified more than once; +each +.I dir +is searched in the given order. +. +To search the current working directory before others, +add +.RB \[lq] "\-I .\&" \[rq] +at the desired place; +it is otherwise searched last. +. +.B \-I +works similarly to, +and is named for, +the \[lq]include\[rq] +option of Unix C compilers. +. +. +.TP +.BI \-m\~ name +Process the file +.RI name .tmac +prior to any input files. +. +If not found, +.IR tmac. name +is attempted. +. +.I name +(in both arrangements) +is presumed to be a macro file; +see the description of +.I GROFF_TMAC_PATH +in section \[lq]Environment\[rq] below for the default search locations +and ordering. +. +. +.TP +.BI \-M\~ dir +Search directory +.I dir +for macro files. +. +See the description of +.I GROFF_TMAC_PATH +in section \[lq]Environment\[rq] below for the default search locations +and ordering. +. +. +.TP +.BI \-n\~ num +Begin numbering pages at +.I num. +. +The default +.RB is\~ 1 . +. +. +.TP +.BI \-o\~ list +Output only pages in +.I list, +which is a comma-separated list of inclusive page ranges; +.I n +means page +.I n, +.IB m \- n +means every page +.RI between\~ m +.RI and\~ n , +.BI \- n +means every page up +.RI to\~ n , +and +.IB n \- +means every page from +.IR n \~on. +. +.I @g@troff +stops processing and exits after formatting the last page enumerated in +.I list. +. +. +.TP +.BI \-r\~ cnumeric-expression +.TQ +.BI \-r\~ register = numeric-expression +Define +.I roff +.RI register\~ c +or +.I register +as +.I numeric-expression. +. +.IR c \~must +be a one-character name; +.I register +can be of arbitrary length. +. +Such register assignments happen before any macro file is loaded, +including the startup file. +. +Due to +.MR getopt_long 3 +limitations, +.IR c\~ cannot +be, +and +.I register +cannot contain, +an equals sign, +even though that is a valid character in a +.I roff +identifier. +. +. +.TP +.B \-R +Don't load +.I troffrc +and +.IR troffrc\-end . +. +. +.TP +.BI \-T\~ dev +Prepare output for device +.I dev. +. +The default is +.BR @DEVICE@ ; +see +.MR groff @MAN1EXT@ . +. +. +.TP +.B \-U +Operate in +.I unsafe mode, +enabling the +.BR open , +.BR opena , +.BR pi , +.BR pso , +and +.B sy +requests, +which are disabled by default because they allow an untrusted input +document to write to arbitrary file names and run arbitrary commands. +. +This option also adds the current directory to the macro package search +path; +see the +.B \-m +and +.B \-M +options above. +. +. +.TP +.BI \-w\~ name +.TQ +.BI \-W\~ name +Enable +.RB ( \-w ) +or inhibit +.RB ( \-W ) +warnings in category +.I name. +. +See section \[lq]Warnings\[rq] below. +. +. +.TP +.B \-z +Suppress formatted output. +. +. +.\" ==================================================================== +.SH Warnings +.\" ==================================================================== +. +.\" BEGIN Keep parallel with groff.texi node "Warnings". +.\" Caveat: the Texinfo manual sorts them by number, not name. +Warning diagnostics emitted by +.I @g@troff +are divided into named, +numbered categories. +. +The name associated with each warning category is used by the +.B \-w +and +.B \-W +options. +. +Each category is also assigned a power of two; +the sum of enabled category codes is used by the +.B warn +request and the +.B .warn +register. +. +Warnings of each category are produced under the following +circumstances. +. +. +.P +.TS +tab(@), center, box; +c c c | c c c +r rI lB | r rI lB. +Bit@Code@Category@Bit@Code@Category +_ +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 +@@@20@1048576@file +.TE +. +. +.P +.nr x \w'\fBright\-brace'+1n+\w'00000'u +.ta \nxuR +. +. +.TP \nxu+3n +.BR break "\t4" +A filled output line could not be broken such that its length was less +than the output line length +.BR \[rs]n[.l] . +. +This category is enabled by default. +. +. +.TP +.BR char "\t1" +No mounted font defines a glyph for the requested character. +. +This category is enabled by default. +. +. +.TP +.BR color "\t524288" +An undefined color name was selected, +an attempt was made to define a color using an unrecognized color space, +an invalid component in a color definition was encountered, +or an attempt was made to redefine a default color. +. +. +.TP +.BR delim "\t8" +The closing delimiter in an escape sequence was missing or mismatched. +. +. +.TP +.BR di "\t256" +A +.BR di , +.BR da , +.BR box , +or +.B boxa +request was invoked without an argument when there was no current +diversion. +. +. +.TP +.BR el "\t16" +The +.B el +request was encountered with no prior corresponding +.B ie +request. +. +. +.TP +.BR escape "\t32768" +An unsupported escape sequence was encountered. +. +. +.TP +.BR file "\t1048576" +An attempt was made to load a file that does not exist. +. +This category is enabled by default. +. +. +.TP +.BR font "\t131072" +A non-existent font was selected, +or the selection was ignored because a font selection escape sequence +was used after the output line continuation escape sequence on an input +line. +. +This category is enabled by default. +. +. +.TP +.BR ig "\t262144" +An invalid escape sequence occurred in input ignored using the +.B ig +request. +. +This warning category diagnoses a condition that is an error when it +occurs in non-ignored input. +. +. +.TP +.BR input "\t16384" +An invalid character occurred on the input stream. +. +. +.TP +.BR mac "\t512" +An undefined string, +macro, +or diversion was used. +. +When such an object is dereferenced, +an empty one of that name is automatically created. +. +So, +unless it is later deleted, +at most one warning is given for each. +. +. +.IP +This warning is also emitted upon an attempt to move an unplanted trap +macro. +. +In such cases, +the unplanted macro is +.I not +dereferenced, +so it is not created if it does not exist. +. +. +.TP +.BR missing "\t8192" +A request was invoked with a mandatory argument absent. +. +. +.TP +.BR number "\t2" +An invalid numeric expression was encountered. +. +This category is enabled by default. +. +. +.TP +.BR range "\t64" +A numeric expression was out of range for its context. +. +. +.TP +.BR reg "\t1024" +An undefined register was used. +. +When an undefined register is dereferenced, +it is automatically defined with a value of\~0. +. +So, +unless it is later deleted, +at most one warning is given for each. +. +. +.TP +.BR right\-brace "\t4096" +A right brace escape sequence +.B \[rs]} +was encountered where a number was expected. +. +. +.TP +.BR scale "\t32" +A scaling unit inappropriate to its context was used in a numeric +expression. +. +. +.TP +.BR space "\t65536" +A space was missing between a request or macro and its argument. +. +This warning is produced when an undefined name longer than two +characters is encountered and the first two characters of the name +constitute a defined name. +. +No request is invoked, +no macro called, +and an empty macro is not defined. +. +This category is enabled by default. +. +It never occurs in compatibility mode. +. +. +.TP +.BR syntax "\t128" +A self-contradictory hyphenation mode was requested; +an empty or incomplete numeric expression was encountered; +an operand to a numeric operator was missing; +an attempt was made to define a recursive, +empty, +or nonsensical character class; +or a +.I groff +extension conditional expression operator was used while in +compatibility mode. +. +. +.TP +.BR tab "\t2048" +A tab character was encountered where a number was expected, +or appeared in an unquoted macro argument. +. +. +.P +Two warning names group other warning categories for convenience. +. +. +.TP +.B all +All warning categories except +.BR di , +.BR mac , +and +.BR reg . +. +This shorthand is intended to produce all warnings that are useful with +macro packages and documents written for AT&T +.I troff \" AT&T +and its descendants, +which have less fastidious diagnostics than GNU +.IR troff . \" GNU +. +. +.TP +.B w +All warning categories. +. +Authors of documents and macro packages targeting +.I groff +are encouraged to use this setting. +.\" END Keep parallel with groff.texi node "Warnings". +. +. +.\" ==================================================================== +.SH Environment +.\" ==================================================================== +. +.I GROFF_FONT_PATH +and +.I GROFF_TMAC_PATH +each accept a search path of directories; +that is, +a list of directory names separated by the system's path component +separator character. +. +On Unix systems, +this character is a colon (:); +on Windows systems, +it is a semicolon (;). +. +. +.TP +.I GROFF_FONT_PATH +A list of directories in which to seek the selected output device's +directory of device and font description files. +. +.I @g@troff +will scan directories given as arguments to any specified +.B \-F +options before these, +then in a site-specific directory +.RI ( @LOCALFONTDIR@ ), +a standard location +.RI ( @FONTDIR@ ), +and a compatibility directory +.RI ( @LEGACYFONTDIR@ ) +after them. +. +. +.TP +.I GROFF_TMAC_PATH +A list of directories in which to search for macro files. +. +.I @g@troff +will scan directories given as arguments to any specified +.B \-M +options before these, +then the current directory +(only if in unsafe mode), +the user's home directory, +.if !'@COMPATIBILITY_WRAPPERS@'no' \{\ +a platform-specific directory +.RI ( @SYSTEMMACRODIR@ ), +.\} +a site-specific directory +.RI ( @LOCALMACRODIR@ ), +and a standard location +.RI ( @MACRODIR@ ) +after them. +. +. +.TP +.I GROFF_TYPESETTER +Set the default output device. +. +If empty or not set, +.B @DEVICE@ +is used. +. +The +.B \-T +option overrides +.IR \%GROFF_TYPESETTER . +. +. +.TP +.I SOURCE_DATE_EPOCH +A timestamp +(expressed as seconds since the Unix epoch) +to use as the output creation timestamp in place of the current time. +. +The time is converted to human-readable form using +.MR localtime 3 +when the formatter starts up and stored in registers usable by documents +and macro packages. +. +. +.TP +.I TZ +The timezone to use when converting the current time +(or value of +.IR SOURCE_DATE_EPOCH ) +to human-readable form; +see +.MR tzset 3 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I @MACRODIR@/\:\%troffrc +is an initialization macro file loaded before any macro packages +specified with +.B \-m +options. +. +. +.TP +.I @MACRODIR@/\:\%troffrc\-end +is an initialization macro file loaded after all macro packages +specified with +.B \-m +options. +. +. +.TP +.IR @MACRODIR@/\: name \:.tmac +are macro files distributed with +.IR groff . +. +. +.TP +.IR @FONTDIR@/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.TP +.IR @FONTDIR@/\:\%dev name / F +describes the font +.I F +of device +.I name. +. +. +.P +.I troffrc +and +.I troffrc\-end +are sought neither in the current nor the home directory by default for +security reasons, +even if the +.B \-U +option is specified. +. +Use the +.B \-M +command-line option or the +.I GROFF_TMAC_PATH +environment variable to add these directories to the search path if +necessary. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +The GNU version of +.I troff \" generic +was originally written by James Clark; +he also wrote the original version of this document, +which was updated by +.MT wl@\:gnu\:.org +Werner Lemberg +.ME , +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.TP +.MR groff @MAN1EXT@ +offers an overview of the GNU +.I roff +system +and describes its front end executable. +. +. +.TP +.MR groff @MAN7EXT@ +details the +.I groff +language, +including a short but complete reference of all predefined requests, +registers, +and escape sequences. +. +. +.TP +.MR groff_char @MAN7EXT@ +explains the syntax of +.I groff +special character escape sequences, +and lists all special characters predefined by the language. +. +. +.TP +.MR groff_diff @MAN7EXT@ +enumerates the differences between +AT&T device-independent +.I troff \" AT&T +and +.IR groff . +. +. +.TP +.MR groff_font @MAN5EXT@ +covers the format of +.I groff +device and font description files. +. +. +.TP +.MR groff_out @MAN5EXT@ +describes the format of +.IR @g@troff 's +output. +. +. +.TP +.MR groff_tmac @MAN5EXT@ +includes information about macro files that ship with +.IR groff . +. +. +.TP +.MR roff @MAN7EXT@ +supplies background on +.I roff +systems in general, +including pointers to further related documentation. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_troff_1_man_C] +.do rr *groff_troff_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |