Added troff

troff/troff.1

@@ -0,0 +1,685 @@
+'\" t
+.TH TROFF 1 "21 March 2020" "groff 1.22.4"
+.SH NAME
+troff \- the troff processor of the groff text formatting system
+.
+.\" troff.man -> troff.1
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018 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.
+.\"
+.\" A copy of the GNU Free Documentation License is also available in this
+.\" Debian package as /usr/share/doc/groff-base/copyright.
+.
+.
+.\" ====================================================================
+.SH SYNOPSIS
+.\" ====================================================================
+.
+.SY troff
+.OP \-abcivzCERU
+.OP \-d cs
+.OP \-f fam
+.OP \-F dir
+.OP \-I 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
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.\" ====================================================================
+.SH DESCRIPTION
+.\" ====================================================================
+.
+This manual page describes the GNU version of
+.BR troff .
+.
+It is part of the groff document formatting system.
+.
+It is functionally compatible with Unix troff, but has many
+extensions, see
+.BR \%groff_diff (7).
+.
+Usually it should be invoked using the
+.BR groff (1)
+command which will also run preprocessors and postprocessors in the
+appropriate order and with the appropriate options.
+.
+.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
+.
+Whitespace is permitted between a command-line option and its argument.
+.
+.
+.TP
+.B \-a
+Generate an ASCII approximation of the typeset output.
+.
+.TP
+.B \-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
+.BR troff 's
+idea of line numbers gets confused by
+.B as
+or
+.B am
+requests.
+.
+.TP
+.B \-c
+Disable color output (always disabled in compatibility mode).
+.
+.TP
+.B \-C
+Enable compatibility mode.
+.
+.TP
+.BI \-d cs
+.TQ
+.BI \-d name = s
+Define
+.I c
+or
+.I name
+to be a string
+.IR s ;
+.I c
+must be a one letter name.
+.
+.TP
+.B \-E
+Inhibit all error messages of
+.BR troff .
+.
+Note that this doesn't affect messages output to standard error by
+macro packages using the
+.B tm
+or
+.B tm1
+requests.
+.
+.TP
+.BI \-f fam
+Use
+.I fam
+as the default font family.
+.
+.TP
+.BI \-F dir
+Search in directory (or directory path)
+.I dir
+for subdirectories
+.IR dev name
+.RI ( name
+is the name of the device) and there for the
+.I DESC
+file and font files.
+.
+.I dir
+is scanned before all other font directories.
+.
+.TP
+.B \-i
+Read the standard input after all the named input files have been
+processed.
+.
+.TP
+.BI \-I dir
+This option may be used to add a directory to the search path for
+files (both those on the command line and those named in
+.B \&.psbb
+requests).
+.
+The search path is initialized with the current directory.
+.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+.
+If you want to make the current directory be read before other
+directories, add
+.B \-I.\&
+at the appropriate place.
+.
+.IP
+No directory search is performed for files with an absolute file name.
+.
+.TP
+.BI \-m name
+Read in the file
+.RI name .tmac .
+.
+If it isn't found, try
+.IR tmac. name
+instead.
+.
+It will be first searched for in directories given with the
+.B \-M
+command-line option, then in directories given in the
+.I GROFF_TMAC_PATH
+environment variable, then in the current directory (only if in unsafe
+mode), the home directory,
+.IR /usr/\:lib/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+and
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
+.
+.TP
+.BI \-M dir
+Search directory (or directory path)
+.I dir
+for macro files.
+.
+This is scanned before all other macro directories.
+.
+.TP
+.BI \-n num
+Number the first page
+.IR num .
+.
+.TP
+.BI \-o list
+Output only pages in
+.IR list ,
+which is a comma-separated list of page ranges;
+.I n
+means print page
+.IR n ,
+.IB m \- n
+means print every page between
+.I m
+and
+.IR n ,
+.BI \- n
+means print every page up to
+.IR n ,
+.IB n \-
+means print every page from
+.IR n .
+.
+.B troff
+will exit after printing the last page in the list.
+.
+.TP
+.BI \-r cn
+.TQ
+.BI \-r name = n
+Set number register
+.I c
+or
+.I name
+to
+.IR n ;
+.I c
+must be a one character name;
+.I n
+can be any troff numeric expression.
+.
+.TP
+.B \-R
+Don't load
+.I troffrc
+and
+.IR troffrc\-end .
+.
+.TP
+.BI \-T name
+Prepare output for device
+.IR name ,
+rather than the default
+.BR ps ;
+see
+.BR groff (1)
+for a more detailed description.
+.
+.TP
+.B \-U
+Unsafe mode.
+.
+This will enable the following requests:
+.BR open ,
+.BR opena ,
+.BR pso ,
+.BR sy ,
+and
+.BR pi .
+For security reasons, these potentially dangerous requests are
+disabled otherwise.
+.
+It will also add the current directory to the macro search path.
+.
+.TP
+.B \-v
+Print the version number.
+.
+.TP
+.BI \-w name
+Enable warning
+.IR  name .
+.
+Available warnings are described in section \(lqWarnings\(rq below.
+.
+To enable most useful warnings use
+.B \-w
+.BR all .
+To enable absolutely all warnings use
+.B \-w w
+instead.
+Multiple
+.B \-w
+options are allowed.
+.
+.TP
+.BI \-W name
+Inhibit warning
+.IR name .
+.
+Multiple
+.B \-W
+options are allowed.
+.
+.TP
+.B \-z
+Suppress formatted output.
+.
+.
+.\" ====================================================================
+.SH WARNINGS
+.\" ====================================================================
+.
+The warnings that can be given by
+.B troff
+are divided into the following categories.
+.
+The name associated with each warning is used by the
+.B \-w
+and
+.B \-W
+options; the number is used by the
+.B warn
+request, and by the
+.B .warn
+register; it is always a power of 2 to allow bitwise composition.
+.
+.P
+.TS
+tab(@), center, box;
+c c c | c c c
+r rI lB | r rI lB.
+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
+@@@20@1048576@file
+.TE
+.
+.P
+.nr x \w'\fBright-brace'+1n+\w'00000'u
+.ta \nxuR
+.
+.TP \nxu+3n
+.BR 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.
+.
+.TP
+.BR char "\t1"
+Non-existent characters.
+.
+This is enabled by default.
+.
+.TP
+.BR color "\t524288"
+Color-related warnings.
+.
+.TP
+.BR delim "\t8"
+Missing or mismatched closing delimiters.
+.
+.TP
+.BR di "\t256"
+Use of
+.B di
+or
+.B da
+without an argument when there is no current diversion.
+.
+.TP
+.BR el "\t16"
+Use of the
+.B el
+request with no matching
+.B ie
+request.
+.
+.TP
+.BR escape "\t32768"
+Unrecognized escape sequences.
+.
+When an unrecognized escape sequence is encountered, the escape
+character is ignored.
+.
+.TP
+.BR file "\t1048576"
+Indicates a missing file for the
+.B mso
+request.
+.
+Enabled by default.
+.
+.TP
+.BR font "\t131072"
+Non-existent fonts.
+.
+This is enabled by default.
+.
+.TP
+.BR ig "\t262144"
+Invalid escapes in text ignored with the
+.B ig
+request.
+.
+These are conditions that are errors when they do not occur in ignored
+text.
+.
+.TP
+.BR input "\t16384"
+Invalid input characters.
+.
+.TP
+.BR 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.
+.
+.TP
+.BR missing "\t8192"
+Requests that are missing non-optional arguments.
+.
+.TP
+.BR number "\t2"
+Invalid numeric expressions.
+.
+This is enabled by default.
+.
+.TP
+.BR range "\t64"
+Out of range arguments.
+.
+.TP
+.BR 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.
+.
+.TP
+.BR right-brace "\t4096"
+Use of
+.B \(rs}
+where a number was expected.
+.
+.TP
+.BR scale "\t32"
+Meaningless scaling indicators.
+.
+.TP
+.BR 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.
+.
+.TP
+.BR syntax "\t128"
+Dubious syntax in numeric expressions.
+.
+.TP
+.BR 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.
+.
+.P
+There are also names that can be used to refer to groups of warnings:
+.
+.TP
+.B all
+All warnings except
+.BR di ,
+.BR mac ,
+and
+.BR reg .
+.
+It is intended that this covers all warnings that are useful with
+traditional macro packages.
+.
+.TP
+.B w
+All warnings.
+.
+.
+.\" ====================================================================
+.SH ENVIRONMENT
+.\" ====================================================================
+.
+.TP
+.I GROFF_TMAC_PATH
+A colon separated list of directories in which to search for
+macro files.
+.
+.B troff
+will scan directories given in the
+.B \-M
+option before these, and in standard directories (current directory if
+in unsafe mode, home directory,
+.IR /usr/\:lib/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:site\-tmac ,
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac )
+after these.
+.
+.TP
+.I GROFF_TYPESETTER
+Default device.
+.
+.TP
+.I GROFF_FONT_PATH
+A colon separated list of directories in which to search for the
+.IR dev name
+directory.
+.
+.B troff
+will scan directories given in the
+.B \-F
+option before these, and in standard directories
+.RI ( /usr/\:share/\:groff/\:site\-font ,
+.IR /usr/\:share/\:groff/\:1.22.4/\:font ,
+.IR /usr/\:lib/\:font )
+after these.
+.
+.
+.\" ====================================================================
+.SH FILES
+.\" ====================================================================
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc
+Initialization file (called before any other macro package).
+.
+.TP
+.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc\-end
+Initialization file (called after any other macro package).
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/ name .tmac
+.TQ
+.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/tmac. name
+Macro files
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name /DESC
+Device description file for device
+.IR name .
+.
+.TP
+.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name / F
+Font file for font
+.I F
+of device
+.IR name .
+.
+.
+.P
+Note that
+.I troffrc
+and
+.I troffrc\-end
+are searched for neither in the current nor the home directory by
+default for security reasons (even if the
+.B \-U
+option is given).
+.
+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
+was originally written by James Clark;
+he also wrote the original version of this document,
+which was modified by
+.MT wl@\:gnu.org
+Werner Lemberg
+.ME
+and
+.MT groff\-bernd.warken\-72@\:web.de
+Bernd Warken
+.ME .
+.
+.
+.\" ====================================================================
+.SH "SEE ALSO"
+.\" ====================================================================
+.
+.TP
+.BR groff (1)
+The main program of the
+.I groff
+system, a wrapper around
+.IR troff .
+.
+.TP
+.BR groff (7)
+A description of the
+.I groff
+language, including a short but complete reference of all predefined
+requests, registers, and escapes of plain
+.IR groff .
+.
+From the command line, this is called by
+.RS
+.IP
+.B man 7 groff
+.RE
+.
+.TP
+.BR \%groff_diff (7)
+The differences of the
+.I groff
+language and the
+.I classical troff
+language.
+.
+Currently, this is the most actual document of the
+.I groff
+system.
+.
+.TP
+.BR roff (7)
+An overview over
+.I groff
+and other
+.I roff
+systems, including pointers to further related documentation.
+.
+.
+.P
+.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 \(lqinfo groff\(rq.
+.
+.
+.\" ====================================================================
+.\" Emacs variables
+.\" ====================================================================
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff: