diff --git a/troff/troff-booklet.pdf b/troff/troff-booklet.pdf new file mode 100644 index 0000000..4b13586 Binary files /dev/null and b/troff/troff-booklet.pdf differ diff --git a/troff/troff.1 b/troff/troff.1 new file mode 100644 index 0000000..e10e7b0 --- /dev/null +++ b/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: diff --git a/troff/troff.1.gz b/troff/troff.1.gz new file mode 100644 index 0000000..475a3db Binary files /dev/null and b/troff/troff.1.gz differ diff --git a/troff/troff.pdf b/troff/troff.pdf new file mode 100644 index 0000000..00ddd73 Binary files /dev/null and b/troff/troff.pdf differ