diff options
Diffstat (limited to 'contrib/groff/man')
| -rw-r--r-- | contrib/groff/man/Makefile.sub | 9 | ||||
| -rw-r--r-- | contrib/groff/man/groff.man | 2785 | ||||
| -rw-r--r-- | contrib/groff/man/groff_char.man | 18 | ||||
| -rw-r--r-- | contrib/groff/man/groff_font.man | 37 | ||||
| -rw-r--r-- | contrib/groff/man/roff.man | 520 |
5 files changed, 3358 insertions, 11 deletions
diff --git a/contrib/groff/man/Makefile.sub b/contrib/groff/man/Makefile.sub index 9b87114..020d20f 100644 --- a/contrib/groff/man/Makefile.sub +++ b/contrib/groff/man/Makefile.sub @@ -1,2 +1,7 @@ -MAN5=groff_font.n groff_out.n -MAN7=groff_char.n +MAN5=\ + groff_font.n \ + groff_out.n +MAN7=\ + groff_char.n \ + groff.n \ + roff.n diff --git a/contrib/groff/man/groff.man b/contrib/groff/man/groff.man new file mode 100644 index 0000000..73c9188 --- /dev/null +++ b/contrib/groff/man/groff.man @@ -0,0 +1,2785 @@ +.\" st -*- nroff -*- +.ig +groff.7 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2000 Free Software Foundation, Inc. +written by Bernd Warken <bwarken@mayn.de> + +Last update: 17 May 2000 + +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 +.\" -------------------------------------------------------------------- +. +.if n \{\ +. mso tmac.tty-char +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \{\ +. ftr CB CW +.\} +. +.\" a comment macro which does nothing +.de c +.. +. +.\" a tab string +.ds t "\t +. +.eo +. +.c text lines in macro definitions or bracketed sections \{...\} +.de text +. if 1 \&\$*\& +.. +. +.de option +. ds @tmp@ \f(CB\$1\fP +. shift 1 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.als shellcommand option +. +.c --------- characters --------- +. +.de character +. ds @tmp@ \f(CB\$1\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de 'char +. ds @tmp@ \(oq\f(CB\$1\fP\(cq +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de ''char +. ds @tmp@ \(lq\f(CB\$1\fP\(rq +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.c --------- requests --------- +. +.c request synopsis +.de REQ +. ds @tmp@ \&\$1 +. shift 1 +. IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n +. rm @tmp@ +.. +. +.de request +. ds @tmp@ \f(CB\$1\fP +. shift 1 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.c --------- macro or function arguments --------- +. +.de argument +. ds @tmp@ \f(CI\$1\fP +. shift 1 +. while (\n[.$] >= 2) \{\ +. as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP +. shift 2 +. \} +. if \n[.$] .as @tmp@ \/\f(CR\$1\fP +. text \*[@tmp@] +. rm @tmp@ +.. +. +.c argument followed by a numerical expression +.de argterm +. ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.c --------- numerical elements --------- +. +.de number +. ds @tmp@ \f(CR\$1\fP +. shift 1 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de prefixednumber +. ds @tmp@ \&\$1\ \f(CR\$2\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.als scaleindicator request +. +.de scalednumber +. ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de operator +. ds @tmp@ \(oq\f(CB\$1\fP\(cq +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.c --------- escape sequences --------- +. +.de esc[arg] +. ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de esc(arg +. ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de escarg +. ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP +. shift 2 +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de esc[] +. ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de esc( +. ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de esc +. ds @tmp@ \f(CB\(rs\$1\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de (esc +. ds @tmp@ \f(CB\(rs(\$1\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.de [esc] +. ds @tmp@ \f(CB\(rs[\$1]\fP +. shift +. text \*[@tmp@]\$* +. rm @tmp@ +.. +. +.c escape sequence synopsis +.de ESC +. ds @tmp@ \&\$1 +. shift 1 +. IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP" +. rm @tmp@ +.. +. +.c synopsis for escape sequences with a long name +.de ESC[] +. ds @arg1@ \&\$1 +. ds @arg2@ \&\$2 +. shift 2 +. IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP" +. rm @arg1@ +. rm @arg2@ +.. +. +.c synopsis escape sequence with quoted argument +. de ESCq +. ds @tmp@ \&\$1 +. shift 1 +. IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP" +. rm @tmp@ +.. +. +.c synopsis for 2-escapes (special characters) +.de ESc +. ds @tmp@ \$1 +. TP 14n +. text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP +. shift 1 +. text \$*. +. rm @tmp@ +.. +. +.c --------- registers --------- +. +.c synopsis for registers +.de REG +. TP 10n +. text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP +. shift 1 +.if \n[.$] \&\$* +.. +. +.als register request +. +.c --------- warnings --------- +. +.als warning request +. +.c description of warnings +.de Warning +. ne (2v + 1) +. TP 12n +. text \f(CB\$1\fP +. text \f(CI\$2\fP +. br +.. +. +.ec +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +. +.TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff \- a short reference for the GNU roff language +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +.I groff +stands for +.I GNU roff +and is the free implementation of the roff type-setting system. +See +.BR roff (@MAN7EXT@) +for a survey and the background of the groff system. +.LP +This document gives only short descriptions of the predefined roff +language elements as used in groff. +Both the classical features and the groff extensions are provided. +.LP +Historically, the +.I roff language +was called +.IR troff . +.I groff +is compatible with the classical system and provides proper extensions. +So in GNU, the terms +.IR roff , +.IR troff , +and +.I groff language +could be used as synonyms. +However +.I troff +slightly tends to refer more to the classical aspects, whereas +.I groff +emphasizes the GNU extensions, and +.I roff +is the general term for the language. +.LP +This file is only a short version of the complete documentation that is +found in the +.I groff +.BR info (1) +file, which contains more detailed, actual, and concise information. +.LP +The general syntax for writing groff documents is relatively easy, but +writing extensions to the roff language can be a bit harder. +.LP +The roff language is line-oriented. +There are only two kinds of lines, control lines and text lines. +The control lines start with a control character, by default a period +.''char . +or a single quote +.''char ' ; +all other lines are text lines. +.LP +.B Control lines +represent commands, optionally with arguments. +They have the following syntax. +The leading control character can be followed by a command name; +arguments, if any, are separated by blanks from the command name and +among themselves, for example, +.RS +.LP +\&\.command_name arg1 arg2 +.RE +.LP +For indentation, any number of space or tab characters can be inserted +between the leading control character and the command name, but the control +character must be on the first position of the line. +.LP +.B Text lines +represent the parts that will be printed. +They can be modified by escape sequences, which are recognized by a +leading backslash +.'char \(rs . +These are in-line or even in-word formatting elements or functions. +Some of these take arguments separated by single quotes +.''char ' , +others are regulated by a length encoding introduced by an open +parenthesis +.'char ( +or enclosed in brackets +.'char [ +and +.'char ] . +.LP +The roff language provides flexible instruments for writing language +extension, such as macros. +When interpreting macro definitions, the roff system enters a special +operating mode, called the +.BR "copy mode" . +.LP +The copy mode behavior can be quite tricky, but there are some rules +that ensure a safe usage. +.IP 1. +Printable backslashes must be denoted as +.esc e . +To be more precise, +.esc e +represents the current escape character. +To get a backslash glyph, use +.esc (rs . +.IP 2. +Double all backslashes. +.IP 3. +Begin all text lines with the special non-spacing character +.esc & . +.LP +This does not produce the most efficient code, but it should work as a +first measure. +For better strategies, see the groff info file and +.BR groff_tmac (@MAN5EXT@). +.LP +Reading roff source files is easier, just reduce all double backslashes +to a single one in all macro definitions. +. +.\" -------------------------------------------------------------------- +.SH "GROFF ELEMENTS" +.\" -------------------------------------------------------------------- +The roff language elements add formatting information to a text file. +The fundamental elements are predefined commands and variables that make +roff a full-blown programming language. +.LP +There are two kinds of roff commands, possibly with arguments. +.B Requests +are written on a line of their own starting with a dot +.'char . +or a +.''char ' , +whereas +.B Escape sequences +are in-line functions and in-word formatting elements starting with a +backslash +.'char \(rs . +.LP +The user can define her own formatting commands using the +.request .de +request. These commands are called +.BR macros , +but they are used exactly like requests. Macro packages are pre-defined +sets of macros written in the groff language. +A user's possibilities to create escape sequences herself is very +limited, only special characters can be mapped. +.LP +The groff language provides several kinds of variables with +different interfaces. +There are pre-defined variables, but the user can define her own +variables as well. +.LP +.B String +variables store character sequences. +They are set with the +.request .ds +request and retrieved by the +.esc * +escape sequences. +.LP +.B Register +variables can store numerical values, numbers with a scale unit, and +occasionally string-like objects. +They are set with the +.request .nr +request and retrieved by the +.esc n +escape sequences. +.LP +.B Environments +allow the user to temporarily store global formatting parameters like +line length, font size, etc. for later reuse. +This is done by the +.request .ev +request. +.LP +.B Fonts +are identified either by a name or by an internal number. +The current font is chosen by the +.request .ft +request or by the +.esc f +escape sequences. +Each device has special fonts, but the following fonts are available for +all devices. +.B R +is the standard font Roman. +.B B +is its +.B bold +counterpart. +The +.I italic +font is called +.B I +is everywhere available, but on text devices, it is displayed as an +underlined Roman font. +For the graphical output devices, there exist constant-width pendants of +these font, +.BR CR , +.BR CI , +and +.BR CB . +On text devices, all characters have a constant width anyway. +.LP +Moreover, there are some advanced roff elements. +A +.B diversion +stores information into a macro for later usage. +A +.B trap +is a positional condition like a certain number of lines from page top +or in a diversion or in the input. +Some action can be prescribed to be run automatically when the condition +is met. +.LP +More detailed information can be found in the groff info file. +. +.\" -------------------------------------------------------------------- +.SH "CONTROL CHARACTERS" +.\" -------------------------------------------------------------------- +There is a small set of characters that have a special controlling task +in certain conditions. +.TP +.character . +A dot is only special at the beginning of a line or after the +condition in the requests +.request .if , +.request .ie , +.request .el , +and +.request .while . +There it is the control character that introduces a request (or macro). +The special behavior can be delayed by using the +.esc . +escape. +By using the +.request .cc +request, the control character can be set to a different character, +making the dot +.'char . +a non-special character. +.IP "" +In all other positions, it just means a dot character. +In text paragraphs, it is advantageous to start each sentence at a line +of its own. +.TP +.character ' +The single quote has two controlling tasks. At the beginning of a line +and in the conditional requests it is the non-breaking control +character. +That means that it introduces a request like the dot, but with the +additional property that this request doesn't cause a linebreak. +By using the +.request .c2 +request, the non-break control character can be set to a different +character. +.IP "" +As a second task, it is the most commonly used argument separator in +some functional escape sequences (but any pair of characters not part +of the argument will work). +In all other positions, it denotes the single quote or apostrophe +character. +Groff provides a printable representation with the +.esc (cq +escape sequence. +.TP +.character \(dq +The double quote is used to enclose arguments in requests and macros. +The escaped double quote +.esc \(dq +introduces a comment. +Otherwise, it is not special. +Groff provides a printable representation with the +.esc (dq +escape sequence. +.TP +.character \(rs +The backslash usually introduces an escape sequence (this can be +changed with the +.request ec +request). +A printed version of the escape character is the +.esc e +escape; a backslash glyph can be obtained by +.esc (rs . +.TP +.character ( +The open parenthesis is only special in escape sequences when +introducing an escape name or argument consisting of exactly two +characters. +In groff, this behavior can be replaced by the \f(CB[]\fP construct. +.TP +.character [ +The opening bracket is only special in groff escape sequences; there it +is used to introduce a long escape name or long escape argument. +Otherwise, it is non-special, e.g. in macro calls. +.TP +.character ] +The closing bracket is only special in groff escape sequences; there it +terminates a long escape name or long escape argument. +Otherwise, it is non-special. +.TP +\f(CIspace\fP +Space characters are only functional characters. They separate the +arguments in requests or macros, and the words in text lines. +They are subject to groff's horizontal spacing calculations. +To get a defined space width, escape sequences like +.'char "\(rs\ " +(this is the escape character followed by a space), +.esc | , +.esc ^ , +or +.esc h +should be used. +.IP \f(CInewline\fP +In text paragraphs, newlines mostly behave like space characters. +Continuation lines can be specified by an escaped newline, i.e., by +specifying a backslash +.'char \(rs +as the last character of a line. +.IP \f(CItab\fP +If a tab character occurs during text the interpreter makes a horizontal +jump to the next pre-defined tab position. +There is a sophisticated interface for handling tab positions. +. +.\" -------------------------------------------------------------------- +.SH "NUMERICAL EXPRESSIONS" +.\" -------------------------------------------------------------------- +A +.B numerical value +is a signed or unsigned integer or float with or without an appended +scale indicator. +A +.B scale indicator +is a one-character abbreviation for a unit of measurement. +A number followed by a scale indicator signifies a size value. +By default, numerical values do not have a scale indicator, i.e., they are +normal numbers. +.LP +The roff language defines the following scale indicators. +.LP +.na +.nh +.TS +center, tab(@); +LfCB Lw(4i). +c@Centimeter +i@Inch +P@Pica\ \(eq\ 1/6\ inch +p@Point\ \(eq\ 1/72\ inch +m@T{ +Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR') +T} +M@100th \fRof an \f(CREm +n@En\ \(eq\ Em/2 +u@\fRBasic unit for actual output device +v@\fRVertical line space in basic units +z@T{ +scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in +font \fIDESC\fP file) +T} +.TE +.LP +.ad +.hy +.B Numerical expressions +are combinations of the numerical values defined above with +the arithmetical operators +.operator + , +.operator \- , +.operator * , +.operator / , +.operator % +.RI ( modulo ), +the comparative operators +.operator == +(this is the same as +.operator = ), +.operator <= , +.operator >= , +.operator < , +.operator > , +the logical operators +.operator & +.RI ( and ), +.operator : +.RI ( or ), +.operator ! +.RI ( not ), +and the parentheses +.operator ( +and +.operator ) . +.LP +Moreover, +.I groff +added the following operators for numerical expressions: +.LP +.na +.nh +.TS +center, tab(@); +LfCB Lw(4i). +e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP. +e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP. +\f(CB(\fPc\f(CB;\fPe\f(CB)@T{ +Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling +indicator. +T} +.TE +.LP +.ad +.hy +For details see the groff info file. +. +.\" -------------------------------------------------------------------- +.SH CONDITIONS +.\" -------------------------------------------------------------------- +.B Conditions +occur in tests raised by the +.request .if , +.request .ie , +and the +.request .while +requests. +The following table characterizes the different types of conditions. +.LP +.na +.nh +.TS +center, tab(@); +LfCB Lw(4i). +\f(CIN\fP@T{ +A numerical expression \f(CIN\fP yields true if its value +is\ \f(CR>0\fP. +T} +!\f(CIN\fP@T{ +True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP. +T} +\&'\f(CIs1\fP'\f(CIs2\fP'@T{ +True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP. +T} +!'\f(CIs1\fP'\f(CIs2\fP'@T{ +True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP. +T} +c\f(CIch@T{ +True if there is a character\ \f(CIch\fP available. +T} +d\f(CIname@T{ +True if there is a string, macro, diversion, or request +called \f(CIname\fP. +T} +e@Current page number is even. +o@Current page number is odd. +n@Formatter is \fBnroff\fP. +r\f(CIreg@T{ +True if there is a register named \f(CIreg\fP. +T} +t@Formatter is \fBtroff\fR. +.TE +.LP +.ad +.hy +. +.\" -------------------------------------------------------------------- +.SH REQUESTS +.\" -------------------------------------------------------------------- +This section provides a short reference for the predefined requests. +In groff, request and macro names can be arbitrarily long. +No bracketing or marking of long names is needed. +.LP +Most requests take one or more arguments. +The arguments are separated by space characters (no tabs!); there is no +inherent limit for their length or number. +An argument can be enclosed by a pair of double quotes: This is very handy +if an argument contains space characters, e.g., +.argument "\(dqarg\ with\ space\(dq" +denotes a single argument. +.LP +Some requests have optional arguments with a different behaviour. +Not all of these details are outlined here. +Refer to the groff info file for all details. +.LP +In the following request specifications, most argument names were chosen +to be descriptive. +Only the following denotations need clarification. +.LP +.na +.nh +.TS +center, tab(@); +LfCI Lw(4i). +c@denotes a single character. +font@T{ +a font either specified as a font name or a font number. +T} +anything@T{ +all characters up to the end of the line or within \f(CB\(rs{\fP +and \f(CB\(rs}\fP. +T} +n@T{ +is a numerical expression that evaluates to an integer value. +T} +N@T{ +is an arbitrary numerical expression, signed or unsigned. +T} +\(+-N@T{ +has three meanings depending on its sign, described below. +T} +.TE +.LP +.ad +.hy +If an expression defined as +.argument \(+-N +starts with a +.operator + +sign the resulting value of the expression will be added to an already +existing value inherent to the related request, e.g. adding to a number +register. +If the expression starts with a +.operator - +the value of the expression will be subtracted from the request value. +.LP +Without a sign, +.argument N +replaces the existing value directly. +To assign a negative number either prepend\ \c +.number 0 +or enclose the negative number in parentheses. +. +.\" -------------------------------------------------------------------- +.SS "REQUEST SHORT REFERENCE" +.\" -------------------------------------------------------------------- +.PD 0 +. +.REQ . +Empty line, ignored. Useful for structuring documents. +. +.REQ .\(rs\(dq anything +Complete line is a comment. +. +.REQ .ab string +Print +.argument string +on standard error, exit program. +. +.REQ .ad +Begin line adjustment for output lines in current adjust mode. +. +.REQ .ad c +Start line adjustment in mode +.argument c +(\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP). +. +.REQ .af register c +Assign format +.argument c +to +.argument register +(\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP). +. +.REQ .aln alias register +Create alias name for +.argument register . +. +.REQ .als alias object +Create alias name for request, string, macro, or diversion +.argument object . +. +.REQ .am macro +Append to +.argument macro +until +.request .. +is called. +. +.REQ .am macro end +Append to +.argument macro +until +.request .end +is called. +. +.REQ .as stringvar anything +Append +.argument anything +to +.argument stringvar . +. +.REQ .asciify diversion +Unformat special ASCII characters in +.argument diversion . +. +.REQ .backtrace +Print a backtrace of the input on stderr. +. +.REQ .bd font N +Embolden +.argument font +by +.argterm N -1 +units. +. +.REQ .bd S font N +Embolden Special Font +.argument S +when current font is +.argument font . +. +.REQ .bp +Eject current page and begin new page. +. +.REQ .bp \(+-N +Eject current page; next page number +.argument \(+-N . +. +.REQ .blm macro +Set the blank line macro to +.argument macro . +. +.REQ .br +Line break. +. +.REQ .break +Break out of a while loop. +. +.REQ .c2 +Reset no-break control character to +.''char ' . +. +.REQ .c2 c +Set no-break control character to +.argument c . +. +.REQ .cc +Reset control character to +.'char . . +. +.REQ .cc c +Set control character to +.argument c . +. +.REQ .ce +Center the next input line. +. +.REQ .ce N +Center following +.argument N +input lines. +. +.REQ .cf filename +Copy contents of file +.argument filename +unprocessed to stdout or to the diversion. +. +.REQ .cflags mode c1 c2 ... +Treat characters +.argument c1 , +.argument c2 , +.argument ... +according to +.argument mode +number. +. +.REQ .ch trap N +Change +.argument trap +location +to +.argument N . +. +.REQ .char c anything +Define character +.argument c +to string +.argument anything . +. +.REQ .chop object +Chop the last character off macro, string, or diversion +.argument object . +. +.REQ .close stream +Close the +.argument stream . +. +.REQ .continue +Finish the current iteration of a while loop. +. +.REQ .cp +Enable compatibility mode. +. +.REQ .cp N +If +.I N +is zero disable compatibility mode, otherwise enable it. +. +.REQ .cs font N M +Set constant character width mode for +.argument font +to +.argterm N /36 +ems with em +.argument M . +. +.REQ .cu N +Continuous underline in nroff, like +.request .ul +in troff. +. +.REQ .da macro +Divert and append to +.argument macro . +. +.REQ .de macro +Define or redefine +.argument macro +until +.request .. +is called. +. +.REQ .de macro end +Define or redefine +.argument macro +until +.request .end +is called. +. +.REQ .di +End current diversion. +. +.REQ .di macro +Divert to +.argument macro . +. +.REQ .do name +Interpret +.request .name +with compatibility mode enabled. +. +.REQ .ds stringvar anything +Set +.argument stringvar +to +.argument anything . +. +.REQ .dt N trap +Set diversion trap to position +.argument N +(default scale indicator\ \c +.scaleindicator v ). +. +.REQ .ec +Reset escape character to +.'char \(rs . +. +.REQ .ec c +Set escape character to +.argument c . +. +.REQ .el anything +Else part for if-else (\c +.argument .ie ) +request. +. +.REQ .em macro +The +.argument macro +will be run after the end of input. +. +.REQ .eo +Turn off escape character mechanism. +. +.REQ .ev +Switch to previous environment. +. +.REQ .ev env +Push down environment number or name +.argument env +and switch to it. +. +.REQ .evc env +Copy the contents of environment +.argument env +to the current environment. +No pushing or popping. +. +.REQ .ex +Exit from roff processing. +. +.REQ .fam name +Set the current font family to +.argument name . +. +.REQ .fc +Disable field mechanism. +. +.REQ .fc a +Set field delimiter to +.argument a +and pad character to space. +.REQ .fc a b +Set field delimiter to +.argument a +and pad character to +.argument b . +. +.REQ .fi +Fill output lines. +. +.REQ .fl +Flush output buffer. +. +.REQ .fp n font +Mount +.argument font +on position +.argument n . +. +.REQ .fp n internal external +Mount font with long +.argument external +name to short +.argument internal +name on position +.argument n . +. +.REQ .fspecial font s1 s2... +When the current font is +.argument font , +then the fonts +.argument s1 , +.argument s2 , +.argument ... +will be special. +. +.REQ .ft +Return to previous font. +Same as +.request \(rsfP . +.REQ .ft font +Change to font name or number +.argument font ; +same as +.esc[arg] f font +escape sequence. +. +.REQ .ftr font1 font2 +Translate +.argument font1 +to +.argument font2 . +. +.REQ .hc +Remove additional hyphenation indicator character. +. +.REQ .hc c +Set up additional hyphenation indicator character\ \c +.argument c . +. +.REQ .hcode c1 code1 c2 code2 ... +Set the hyphenation code of character +.argument c1 +to +.argument code1 , +that of +.argument c2 +to +.argument code2 , +etc. +. +.REQ .hla lang +Set the current hyphenation language to +.argument lang . +. +.REQ .hlm n +Set the maximum number of consecutive hyphenated lines to +.argument n . +. +.REQ .hpf file +Read hyphenation patterns from +.argument file . +. +.REQ .hw words +List of +.argument words +with exceptional hyphenation. +. +.REQ .hy N +Switch to hyphenation mode +.argument N . +. +.REQ .hym n +Set the hyphenation margin to +.argument n +(default scale indicator\ \c +.scaleindicator m ). +. +.REQ .hys n +Set the hyphenation space to +.argument n . +. +.REQ .ie cond anything +If +.argument cond +then +.argument anything +else goto +.request .el . +. +.REQ .if cond anything +If +.argument cond +then +.argument anything ; +otherwise do nothing. +. +.REQ .ig +Ignore text until +.request .. +is called. +. +.REQ .ig end +Ignore text until +.request .end . +. +.REQ .in +Change to previous indent value. +. +.REQ .in \(+-N +Change indent according to +.argument \(+-N +(default scale indicator\ \c +.scaleindicator m ). +. +.REQ .it N trap +Set an input-line count trap at position +.argument N . +. +.REQ .kern +Enable pairwise kerning. +. +.REQ .kern n +If +.argument n +is zero, disable pairwise kerning, otherwise enable it. +. +.REQ .lc +Remove leader repetition character. +. +.REQ .lc c +Set leader repetition character to\ \c +.argument c . +. +.REQ .length register anything +Write the length of the string +.argument anything +in +.argument register . +. +.REQ .lf N file +Set input line number to +.argument N +and filename to +.argument file . +. +.REQ .lg N +Ligature mode on if +.argterm N >0 . +. +.REQ .ll +Change to previous line length. +. +.REQ .ll \(+-N +Set line length according to +.argument \(+-N +(default size +.scalednumber 6.5 i , +default scale indicator\ \c +.scaleindicator m ). +. +.REQ .ls +Change to the previous value of additional intra-line skip. +. +.REQ .ls N +Set additional intra-line skip value to +.argument N , +i.e., +.argterm N -1 +blank lines are inserted after each text output line. +. +.REQ .lt \(+-N +Length of title (default scale indicator\ \c +.scaleindicator m ). +. +.REQ .mc +Margin character off. +. +.REQ .mc c +Print character +.argument c +after each text line at actual distance from right margin. +. +.REQ .mc c N +Set margin character to +.argument c +and distance to +.argument N +from right margin (default scale indicator\ \c +.scaleindicator m ). +. +.REQ .mk register +Mark current vertical position in +.argument register . +. +.REQ .mso file +The same as the .so request except that +.I file +is also searched in the tmac directories. +. +.REQ .na +No output-line adjusting. +. +.REQ .ne +Need a one-line vertical space. +. +.REQ .ne N +Need +.argument N +vertical space (default scale indicator\ \c +.scaleindicator v ). +. +.REQ .nf +No filling or adjusting of output-lines. +. +.REQ .nh +No hyphenation. +. +.REQ .nm +Number mode off. +. +.REQ .nm \(+-N M S I +In line number mode, set number, multiple, spacing, and indent. +. +.REQ .nn +Do not number next line. +. +.REQ .nn N +Do not number next +.argument N +lines. +. +.REQ .nr register \(+-N M +Define or modify +.argument register +using +.argument \(+-N +with auto-increment +.argument M . +. +.REQ .nroff +Make the built-in condition +.B n +true and +.B t +false. +. +.REQ .ns +Turn no-space mode on. +. +.REQ .nx filename +Next file. +. +.REQ .open stream filename +Open +.register filename +for writing and associate the stream named +.register stream +with it. +. +.REQ .opena stream filename +Like +.request .open +but append to it. +. +.REQ .os +Output vertical distance that was saved by the +.request .sv +request. +. +.REQ .pc +Reset page number character to\ \c +.'char % . +. +.REQ .pc c +Page number character. +. +.REQ .pi program +Pipe output to +.argument program +(nroff only). +. +.REQ .pl +Set page length to default +.scalednumber 11 i . +The current page length is stored in +.register .p . +. +.REQ .pl \(+-N +Change page length to +.argument \(+-N +(default scale indicator\ \c +.scaleindicator v ). +. +.REQ .pm +Print macro names and sizes (number of blocks of 128 bytes). +. +.REQ ".pm t" +Print only total of sizes of macros (number of 128 bytes blocks). +. +.REQ .pn \(+-N +Next page number +.argument N . +. +.REQ .pnr +Print the names and contents of all currently defined number registers +on stderr. +. +.REQ .po +Change to previous page offset. The current page offset is available in +.register .o . +. +.REQ .po \(+-N +Page offset +.argument N . +. +.REQ .ps +Return to previous point-size. +.REQ .ps \(+-N +Point size; same as +.esc[arg] s \(+-N . +. +.REQ .psbb filename +Get the bounding box of a PostScript image +.argument filename . +. +.REQ .pso command +This behaves like the +.request .so +request except that input comes from the standard output of +.argument command . +. +.REQ .ptr +Print the names and positions of all traps (not including input line +traps and diversion traps) on stderr. +. +.REQ .rchar c1 c2... +Remove the definitions of characters +.argument c1 , +.argument c2 , +.argument ... +. +.REQ .rd prompt +Read insertion. +. +.REQ .rj n +Right justify the next +.argument n +input lines. +. +.REQ .rm name +Remove request, macro, or string +.argument name . +. +.REQ .rn old new +Rename request, macro, or string +.argument old +to +.argument new . +. +.REQ .rnn reg1 reg2 +Rename register +.argument reg1 +to +.argument reg2 . +. +.REQ .rr register +Remove +.argument register . +. +.REQ .rs +Restore spacing; turn no-space mode off. +. +.REQ .rt \(+-N +Return +.I (upward only) +to marked vertical place (default scale indicator\ \c +.scaleindicator v ). +. +.REQ .shc +Reset soft hyphen character to +.esc (hy . +. +.REQ .shc c +Set the soft hyphen character to +.argument c . +. +.REQ .shift n +In a macro, shift the arguments by +.argument n \ \c +positions. +. +.REQ .so filename +Include source file. +. +.REQ .sp +Skip one line vertically. +. +.REQ .sp N +Space vertical distance +.argument N +up or down according to sign of +.argument N +(default scaling indicator\ \c +.scaleindicator v ). +. +.REQ .special s1 s2 ... +Fonts +.argument s1 , +.argument s2 , +etc. are special and will be searched for characters not in the current font. +. +.REQ .ss N +Space-character size set to +.argument N /12 +of the spacewidth in the current font. +. +.REQ .ss N M +Space-character size set to +.argterm N /12 +and sentence space size set to +.argterm M /12 +of the spacewidth in the current font (\f(CR\(eq1/3 em\fP). +. +.REQ .sty n style +Associate +.argument style +with font position +.argument n . +. +.REQ .substring register n1 n2 +Replace the string in +.argument register +with the substring defined by the indices +.argument n1 +and +.argument n2 . +. +.REQ .sv +Save +.scalednumber 1 v +of vertical space. +. +.REQ .sv N +Save the vertical distance +.argument N +for later output with +.request .os +request. +. +.REQ .sy command-line +Execute program +.argument command-line . +. +.REQ ".ta T" N +Set tabs after every position that is a multiple of +.argument N +(default scaling indicator\ \c +.scaleindicator m ). +.REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn +Set tabs at positions +.argument n1 , +.argument n2 , +\&..., +.argument nn , +then set tabs at +.argument nn + r1 , +.argument nn + r2 , +\&..., +.argument nn + rn , +then at +.argument nn + rn + r1 , +.argument nn + rn + r2 , +\&..., +.argument nn + rn + rn , +and so on. +. +.\".REQ .tar +.\"Restore internally saved tab positions. +.\". +.\".REQ .tas +.\"Save tab positions internally. +. +.REQ .tc +Remove tab repition character. +.REQ .tc c +Set tab repetition character to\ \c +.argument c . +. +.REQ .ti \(+-N +Temporary indent next line (default scaling indicator\ \c +.scaleindicator m ). +. +.REQ .tkf font s1 n1 s2 n2 +Enable track kerning for +.argument font . +. +.REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP +Three-part title. +. +.REQ .trf filename +Transparently output the contents of file +.argument filename . +. +.REQ .tm anything +Print +.argument anything +on terminal (UNIX standard message output). +. +.REQ .tr abcd.... +Translate +.argument a +to +.argument b , +.argument c +to +.argument d , +etc. on output. +. +.REQ .trnt abcd.... +This is the same as the +.request .tr +request except that the translations do not apply to text that is +transparently throughput into a diversion with +.esc ! . +. +.REQ .troff +Make the built-in condition +.B t +true and +.B n +false. +. +.REQ .uf font +Underline font set to +.argument font +(to be switched to by +.request .ul ). +. +.REQ .ul N +Underline (italicize in troff) +.argument N +input lines. +. +.REQ .vpt n +Enable vertical position traps if +.argument n +is non-zero, disable them otherwise. +. +.REQ .vs +Change to previous vertical base line spacing. +. +.REQ .vs N +Set vertical base line spacing to +.argument N . +Default value is +.scalednumber 12 p . +. +.REQ .warn n +Set warnings code to +.argument n . +. +.REQ .wh N trap +Set location trap; negative means from page bottom. +. +.REQ .while cond anything +While condition +.argument cond +is true, accept +.argument anything +as input. +. +.REQ .write stream anything +Write +.argument anything +to the stream named +.argument stream . +. +.PD +.LP +Besides these standard groff requests, there might be further macro +calls. +They can originate from a macro package (see +.BR roff (@MAN7EXT@) +for an overview) or from a preprocessor. +.LP +Preprocessor macros are easy to be recognized. They enclose their code +into a pair of characteristic macros. +.LP +.TS +box, center, tab (@); +c | c | c +CfCB | CfCB | CfCB. +preprocessor@start macro@ end macro += +eqn@.PS@.PE +grap@.G1@.G2 +grn@.GS@.GE +pic@.PS@.PE +refer@.R1@.R2 +soelim@\fInone@\fInone +tbl@.TS@.TE +.TE +.LP +. +.\" -------------------------------------------------------------------- +.SH "ESCAPE SEQUENCES" +.\" -------------------------------------------------------------------- +. +Escape sequences are in-line language elements usually introduced by +a backslash +.'char \(rs +and followed by an escape name and sometimes by a required argument. +Input processing is continued directly after the escaped character or +the argument resp. without an intervening separation character. +So there must be a way to determine the end of the escape name and the end +of the argument. +.LP +This is done by enclosing names (escape name and arguments consisting of +a variable name) by a pair of brackets +.esc[] name +and constant arguments (number expressions and characters) by apostrophes +(ASCII 0x27) like +.IR \(cqconstant\(cq . +.LP +There are abbreviations for short names. +Two character escape names can be specified by an opening parenthesis like +.esc( xy +without a closing counterpart. +And all one-character names different from the special characters +.'char [ +and +.'char ( +can even be specified without a marker in the form +.esc \fP\f(CIc . +.LP +Constant arguments of length +.number 1 +can omit the marker apostrophes, too, but there is no two-character +analogue. +.LP +While 1-character escape sequences are mainly used for in-line functions +and system related tasks, the 2-letter names following the +.esc( "" +construct are used for special characters predefined by the roff system. +Names with more than two characters +.esc[] name +mostly denote user defined named characters (see the +.request .char +request). +. +.\" -------------------------------------------------------------------- +.SS "SINGLE CHARACTER ESCAPES" +.\" -------------------------------------------------------------------- +. +.PD 0 +. +.\" --------- comments --------- +. +.ESC \(dq +Beginning of a comment. +Everything up to the end of the line is ignored. +. +.ESC # +Everything up to and including the next newline is ignored. +This is interpreted in copy mode. +This is like +.esc \(dq +except the ignoring of the terminating newline. +. +.\" --------- strings --------- +. +.ESC * s +The string stored in the string variable with 1-character name +.argument s . +. +.ESC *( st +The string stored in the string variable with 2-character name +.argument st . +. +.ESC[] * stringvar +The string stored in the string variable with arbitrary length name +.argument stringvar . +. +.\" --------- macro arguments --------- +. +.ESC $0 +The name by which the current macro was invoked. The +.request .als +request can make a macro have more than one name. +. +.ESC $ x +Macro argument with 1-place number +.argument x , +where +.argument x +is a digit between 1 and 9. +. +.ESC $( xy +Macro argument with 2-digit number +.argument xy . +. +.ESC[] $ nexp +Macro argument with number +.argument nexp , +where +.argument nexp +is a numerical expression evaluating to an integer \(>=1. +. +.ESC $* +In a macro, the concatenation of all the arguments separated by spaces. +. +.ESC $@ +In a macro, the concatenation of all the arguments with each surrounded +by double quotes, and separated by spaces. +. +.\" --------- escaped characters --------- +. +.ESC \(rs +reduces to a single backslash; useful to delay its interpretation as +escape character in copy mode. +For a printable backslash, use +.esc e . +. +.ESC \(cq +The acute accent \(aa; same as +.esc( aa . +Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27). +. +.ESC ` +The grave accent \(ga; same as +.esc( ga . +Unescaped: left quote, backquote (ASCII 0x60). +. +.ESC \- +The \- sign in the current font. +. +.ESC . +An uninterpreted dot (period), even at start of line. +. +.ESC % +Default optional hyphenation character. +. +.ESC ! +Transparent line indicator. +. +.ESC ? anything\fB?\fP +In a diversion, this will transparently embed +.argument anything +in the diversion. +.argument anything +is read in copy mode. +See also the escape sequences +.esc ! +and +.esc ? . +. +. +.\" --------- spacing --------- +. +.ESC \& space +Unpaddable space-size space character (no line break). +. +.ESC 0 +Digit width. +. +.ESC | +1/6\ em narrow space character; zero width in nroff. +. +.ESC ^ +1/12\ em half-narrow space character; zero width in nroff. +. +.ESC & +Non-printable, zero width character. +. +.ESC ) +Like +.esc & +except that it behaves like a character declared with the cflags +request to be transparent for the purposes of end of sentence +recognition. +. +.ESC / +Increases the width of the preceding character so that the spacing +between that character and the following character will be correct if +the following character is a roman character. +. +.ESC , +Modifies the spacing of the following character so that the spacing +between that character and the preceding character will correct if the +preceding character is a roman character. +. +.ESC ~ +Unbreakable space that stretches like a normal inter-word space when a +line is adjusted. +. +.ESC \& newline +Ignored newline, for continuation lines. +. +.\" --------- structuring --------- +. +.ESC { +Begin conditional input. +. +.ESC } +End conditional input. +. +.\" --------- longer escape names --------- +. +.ESC ( st +The special character with 2-character name +.argument st , +see section +.BR "SPECIAL CHARACTERS" . +. +.ESC[] \& name +The named character with arbitrary length name +.argument name . +. +.\" --------- alphabetical escapes --------- +. +.ESC a +Non-interpreted leader character. +. +.ESCq A anything +If +.argument anything +acceptable as name of a string, macro, diversion, register, +environment or font it is +.number 1 +otherwise +.number 0 . +. +.ESCq b abc... +Bracket building function. +. +.ESC c +Interrupt text processing. +. +.ESCq C char +The character called +.argument char ; +same as +.esc[] char , +but compatible to other roff versions. +. +.ESC d +Forward (down) 1/2 em vertical unit (1/2 line in nroff). +. +.ESCq D charseq +Draw a graphical element defined by the characters in +.argument charseq ; +see groff info file for details. +. +.ESC e +Printable version of the current escape character. +. +.ESC E +Equivalent to an escape character, but is not interpreted in copy-mode. +. +.ESC f F +Change to font with 1-character name or 1-digit number +.argument F . +. +.ESC f( fo +Change to font with 2-characer name or 2-digit number +.argument fo . +. +.ESC[] f font +Change to font with arbitrary length name or number expression +.argument font . +. +.ESC[] g reg +Return format of register with name +.argument reg +suitable for +.request .af . +Alternative forms +.esc(arg g xy +and +.escarg g x . +. +.ESCq h N +Local horizontal motion; move right +.argument N +(left if negative). +. +.ESCq H N +Set height of current font to +.argument N . +. +.ESC[] k reg +Mark horizontal input place in register with arbitrary length name +.argument reg . +Alternative forms +.esc(arg k xy +and +.escarg k x . +. +.ESCq l Nc +Horizontal line drawing function (optionally using character +.argument c ). +. +.ESCq L Nc +Vertical line drawing function (optionally using character +.argument c ). +. +.ESC n r +The numerical value stored in the register variable with the 1-character +name +.argument r . +. +.ESC n( re +The numerical value stored in the register variable with the 2-character +name +.argument re . +. +.ESC[] n reg +The numerical value stored in the register variable with arbitrary +lenght name +.argument reg . +. +.ESCq N n +Typeset the character with code +.argument n +in the current font, no special fonts are searched. Useful for adding +characters to a font using the +.request .char +request. +. +.ESCq o abc... +Overstrike characters +.argument a , +.argument b , +.argument c , +etc. +. +.ESC p +Break and spread output line. +. +.ESC r +Reverse 1\ em vertical motion (reverse line in nroff). +. +.ESCq R name \(+-n +The same as +.request .nr +.argument name +.argument \(+-n . +. +.ESC[] s \(+-N +Set the point size to +.I N +scaled points. Note the alternative forms +.BI \(rss \(+- [ N ]\c +, +.BI \(rss' \(+-N '\c +, +.BI \(rss \(+- ' N '\c +, +.esc(arg s \(+-xy , +.BI \(rss \(+- ( xy\c +, +.escarg s \(+-x . +Same as +.request .ps +request. +. +.ESCq S N +Slant output +.argument N +degrees. +. +.ESC t +Non-interpreted horizontal tab. +. +.ESC u +Reverse (up) 1/2 em vertical motion (1/2 line in nroff). +. +.ESCq v N +Local vertical motion; move down +.argument N +(up if negative). +. +.ESC[] V env +The contents of the environment variable +.argument env . +Alternative forms +.esc(arg V xy +and +.escarg V x . +. +.ESCq w string +The width of the character sequence +.argument string . +. +.ESCq x N +Extra line-space function (negative before, positive after). +. +.ESCq X string +Output +.argument string +as device control function. +. +.ESC[] Y name +Output string variable or macro +.argument name +uninterpreted as device control function. +Alternative forms +.esc(arg Y xy +and +.escarg Y x . +. +.ESC z c +Print +.argument c +with zero width (without spacing). +. +.ESCq Z anything +Print +.argument anything +and then restore the horizontal and vertical position; +.argument anything +may not contain tabs or leaders. +.PD +.LP +The escape sequences +.esc e , +.esc . , +.esc \(dq , +.esc $ , +.esc * , +.esc a , +.esc n , +.esc t , +.esc g , +and +.escarg \& newline +are interpreted in copy mode. +.LP +Escape sequences starting with +.esc ( +or +.esc [ +do not represent single character escape sequences, but introduce escape +names with two or more characters. +.LP +If a backslash is followed by a character that does not constitute a +defined escape sequence the backslash is silently ignored and the +character maps to itself. +. +.\" -------------------------------------------------------------------- +.SS "SPECIAL CHARACTERS" +.\" -------------------------------------------------------------------- +Common special characters are predefined by escape sequences of the form +.(esc \fP\f(CIxy +with characters +.argument x +and +.argument y . +Some of these exist in the usual font while most of them are only +available in the special font. Below you'll find a selection of the most +important glyphs; a complete list can be found in +.BR groff_char (@MAN7EXT@). +.RS +.LP +.PD 0 +. +.ESc bu Bullet sign +.ESc co Copyright +.ESc ct Cent +.ESc dd Double dagger +.ESc de Degree +.ESc dg Dagger +.ESc em Em-dash +.ESc hy Hyphen +.ESc rg Registered sign +.ESc sc Section sign +.ESc ul Underline character +.ESc == Identical +.ESc >= Larger or equal +.ESc <= Less or equal +.ESc != Not equal +.ESc -> Right arrow +.ESc <- Left arrow +.ESc +- Plus-minus sign +.PD +.RE +. +.\" -------------------------------------------------------------------- +.SH REGISTERS +.\" -------------------------------------------------------------------- +Registers are variables that store a value. +In groff, most registers store numerical values (see section +.B NUMERICAL EXPRESSIONS +above), but some can also hold a string value. +.LP +Each register is given a name. +Arbitrary registers can be defined and set with the request +.request .nr +.argument register . +.LP +The value stored in a register can be retrieved by the escape sequences +introduced by +.esc n . +.LP +Most useful are predefined registers. +In the following the notation +.argument name +is used to refer to a register called +.register name +to make clear that we speak about registers. +Please keep in mind that the +.esc en[] +decoration is not part of the register name. +. +.\" -------------------------------------------------------------------- +.SS "READ-ONLY REGISTERS" +.\" -------------------------------------------------------------------- +The following registers have predefined values that should not be +modified by the user (usually, registers starting with a dot a read-only). +Mostly, they provide information on the current settings or store results +from request calls. +.LP +.PD 0 +.REG .$ Number of arguments in the current macro. +.REG .A +Set to +.number 1 +in +.B troff +if option +.B \-A +is used; always +.number 1 +in +.BR nroff . +.REG .H Available horizontal resolution in basic units. +.REG .T +Set to +.number 1 +if option +.B \-T +is used. +.REG .V Available vertical resolution in basic units. +.REG .a +Post-line extra line-space most recently utilized using +.escarg x 'N' . +.REG .C 1 if compatibility mode is in effect, 0 otherwise. +.REG .c Current input line number. +.REG .cdp +The depth of the last character added to the current environment. +It is positive if the character extends below the baseline. +.REG .ce +The number of lines remaining to be centered, as set by the +.request .ce +request. +.REG .cht +The height of the last character added to the current environment. +It is positive if the character extends above the baseline. +.REG .csk +The skew of the last character added to the current environment. +The skew of a character is how far to the right of the center of a character +the center of an accent over that character should be placed. +.REG .d +Current vertical place in current diversion; equal to register +.register nl . +.REG .ev The name or number of the current environment (string-valued). +.REG .f Current font number. +.REG .fam The current font family (string-valued). +.REG .fp The number of the next free font position. +.REG .g +Always 1 in GNU troff. +Macros should use it to test if running under groff. +.REG .h Text base-line high-water mark on current page or diversion. +.REG .hla +The current hyphenation language as set by the +.B .hla +request. +.REG .hlc +The number of immediately preceding consecutive hyphenated lines. +.REG .hlm +The maximum allowed number of consecutive hyphenated lines, as set by +the +.request .hlm +request. +.REG .hy +The current hyphenation flags (as set by the +.request .hy +request). +.REG .hym +The current hyphenation margin (as set by the +.request .hym +request). +.REG .hys +The current hyphenation space (as set by the +.request .hys +request). +.REG .i Current ident. +.REG .in The indent that applies to the current output line. +.REG .kern +.number 1 +if pairwise kerning is enabled, +.number 0 +otherwise. +.REG .l Current line length. +.REG .lg +The current ligature mode (as set by the +.request .lg +request). +.REG .ll The line length that applies to the current output line. +.REG .lt +The title length (as set by the +.request .lt +request). +.REG .n Length of text portion on previous output line. +.REG .ne +The amount of space that was needed in the last +.request .ne +request that caused a trap to be sprung. +Useful in conjunction with +.register .trunc . +.REG .o Current page offset. +.REG .p Current page length. +.REG .pn +The number of the next page: either the value set by a +.request .pn +request, or the number of the current page plus\ 1. +.REG .ps The current pointsize in scaled points. +.REG .psr The last-requested pointsize in scaled points. +.REG .rj +The number of lines to be right-justified as set by the rj request. +.REG .s Current point size as a decimal fraction. +.REG .sr +The last requested pointsize in points as a decimal fraction +(string-valued). +.REG .t Distance to the next trap. +.REG .tabs +A string representation of the current tab settings suitable for use as +an argument to the +.request .ta +request. +.REG .trunc +The amount of vertical space truncated by the most recently sprung +vertical position trap, or, if the trap was sprung by a +.request .ne +request, minus the amount of vertical motion produced by +.request .ne . +request. +In other words, at the point a trap is sprung, it represents the difference +of what the vertical position would have been but for the trap, and what the +vertical position actually is. +Useful in conjunction with the +.register .ne +register. +.REG .ss +The value of the parameters set by the first argument of the +.request .ss +request. +.REG .sss +The value of the parameters set by the second argument of the +.request .ss +request. +.REG .u Equal to 1 bin fill mode and 0 in nofill mode. +.REG .v Current vertical line spacing. +.REG .vpt +.number 1 +if vertical position traps are enabled, +.number 0 +otherwise. +.REG .w Width of previous character. +.REG .warn +The sum of the number codes of the currently enabled warnings. +.REG .x The major version number. +.REG .y The minor version number. +.REG .Y The revision number of groff. +.REG .z Name of current diversion. +.REG llx +Lower left x-coordinate (in PostScript units) of a given PostScript +image (set by +.request .psbb ). +.REG lly +Lower left y-coordinate (in PostScript units) of a given PostScript +image (set by +.request .psbb ). +.REG rsb Like +.register sb , +but takes account of the heights and depths of characters. +.REG rst +Like +.register st , +but takes account of the heights and depths of characters. +.REG sb +Depth of string below base line (generated by width function +.esc w ). +.REG skw +Right skip width from the center of the last character in the +.esc w +argument. +.REG ssc +The amount of horizontal space (possibly negative) that should be added +to the last character before a subscript (generated by width function +.esc w ). +.REG st +Height of string above base line (generated by width function +.esc w ). +.REG urx +Upper right x-coordinate (in PostScript units) of a given PostScript +image (set by +.request .psbb ). +.REG ury +Upper right y-coordinate (in PostScript units) of a given PostScript +image (set by +.request .psbb ). +.PD +. +.\" -------------------------------------------------------------------- +.SS "WRITABLE REGISTERS" +.\" -------------------------------------------------------------------- +The following registers can be read and written by the user. +They have predefined default values, but these can be modified for +customizing a document. +.LP +.PD 0 +.REG % Current page number. +.REG c. Current input line number. +.REG ct Character type (set by width function +.esc w ). +.REG dl Maximal width of last completed diversion. +.REG dw Current day of week (1-7). +.REG dy Current day of month (1-31). +.REG hp Current horizontal position at input line. +.REG ln Output line number. +.REG mo Current month (1-12). +.REG nl Vertical position of last printed text base-line. +.REG slimit +If greater than 0, the maximum number of objects on the input stack. +If \(<=0 there is no limit, i.e., recursion can continue until virtual +memory is exhausted. +.REG systat +The return value of the +.I system() +function executed by the last +.request .sy +request. +.REG year The current year (year 2000 compliant). +.REG yr +Current year minus 1900. For Y2K compliance use register +.register year +instead. +.PD +. +.\" -------------------------------------------------------------------- +.SH WARNINGS +.\" -------------------------------------------------------------------- +Each warning generated by groff is identified by a name and a code +number. The codes are powers of 2 to allow bit-encoding with a single +integer. There are also names that can be used to refer to groups of +warnings. +.LP +The name associated with a warning is used by the +.option \-w +and +.option \-W +options; +the number code is used by the +.request .warn +request and by the +.esc[arg] n warn +register. +.LP +.PD 0 +.Warning all group +All warnings except +.warning di , +.warning mac +and +.warning reg . +Intended to cover all warnings with traditional macro packages. +.Warning break 4 +In fill mode, lines which could not be broken so that their length was +less than the line length. This is enabled by default. +.Warning char 1 +Non-existent characters. This is enabled by default. +.Warning delim 8 +Missing or mismatched closing delimiters. +.Warning di 256 +Use of +.request .di +or +.request .da +without an argument when there is no current diversion. +.Warning el 16 +Use of the +.request .el +request with no matching +.request .ie +request. +.Warning escape 32768 +Unrecognized escape sequence. Then the escape character is ignored. +.Warning font 131072 +Non-existent fonts. This is enabled by default. +.Warning ig 262144 +Illegal escapes in text ignored with the +.request \.ig +request. These are conditions that are errors when they occur outside +of ignored text. +.Warning mac 512 +Use of undefined strings, macros, and diversions. Automatically handled +as empty. Usually, only one warning per name. +.Warning missing 8192 +Request that is missing non-optional arguments. +.Warning input 16384 +Illegal input character. +.Warning number 2 +Invalid numeric expressions. This is enabled by default. +.Warning range 64 +Out of range arguments. +.Warning reg 1024 +Use of undefined number register. Automatically defined as having +value 0. Usually, only one warning per name. +.Warning right-brace 4096 +Use of +.esc } +where a number was expected. +.Warning scale 32 +Meaningless scaling indicators. +.Warning space 65536 +Missing space between a request or macro and its argument. Then no +macro is automatically defined. This is enabled by default. This +warning will never occur in compatibility mode. +.Warning syntax 128 +Dubious syntax in numeric expressions. +.Warning tab 2048 +Inappropriate use of a tab character (either in an unquoted macro +argument or where a number was expected). +.Warning w group +All warnings. +.PD +.LP +.TS +tab(@), box, expand; +c c c | c c c | c c c +R RI CB | R RI CB | R RI CB. +Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning +_ +0@1@char@8@256@di@16@65536@space +1@2@number@9@512@mac@17@131072@font +2@4@break@10@1024@reg@18@262144@ig +3@8@delim@11@2048@tab +4@16@el@12@4096@right-brace +5@32@scale@13@8192@missing +6@64@range@14@16384@input +7@128@syntax@15@32768@escape +.TE +.LP +. +.\" -------------------------------------------------------------------- +.SH COMPATIBILITY +.\" -------------------------------------------------------------------- +.I groff +provides a +.B compatibility mode +that allows to process roff code written for classical +.troff +or for other implementations of roff in a consistent way. +.LP +Compatibility mode can be turned on with the +.option \-C +command line option, and turned on or off with the +.request .cp +request. The number register +.esc(arg n .C +is +.number 1 +if compatibility mode is on, +.number 0 +otherwise. +.LP +This became necessary because the GNU concept for long names causes some +incompatibilities. +.I Classical troff +will interpret +.IP +.B +\&.dsabcd +.LP +as defining a string +.B ab +with contents +.BR cd . +Normally, +.I groff +will interpret this as a call of a macro named +.request dsabcd . +.LP +Also +.I classical troff +will interpret +.esc *[ +or +.esc n[ +as references to a string or number register called +.register [ . +In +.I GNU native +.IR mode , +however, this will normally be interpreted as the start of a long name. +.LP +In +.I compatibility +.IR mode , +groff will interpret these things in the traditional way, but long names +are not recognized. +.LP +On the other hand, groff in +.I GNU native mode +does not allow to use the escape sequences +.esc e , +.esc | , +.esc ^ , +.esc & , +.esc } , +.esc { , +.esc "\ " (space), +.esc ' , +.esc ` , +.esc - , +.esc _ , +.esc ! , +.esc % , +and +.esc c +in names of strings, macros, diversions, number registers, fonts or +environments, whereas +.I classical troff +does. The +.esc A +escape sequence can be helpful in avoiding these escape sequences in +names. +.LP +Fractional pointsizes cause one noteworthy incompatibility. +In +.I classical +.IR troff , +the +.request .ps +request ignores scale indicators and so +.RS +.LP +.B .ps\ 10u +.RE +.LP +will set the pointsize to 10 points, whereas in groff native mode the +pointsize will be set to 10 scaled points. +.LP +In +.I groff +mode, there is a fundamental difference between unformatted input +characters, and formatted output characters. +Everything that affects how an output character will be output is stored +with the character; once an output character has been constructed it is +unaffected by any subsequent requests that are executed, including the +.request .bd , +.request .cs , +.request .tkf , +.request .tr , +or +.request .fp +requests. +.LP +Normally output characters are constructed from input characters at the +moment immediately before the character is added to the current output +line. +Macros, diversions and strings are all, in fact, the same type of object; +they contain lists of input characters and output characters in any +combination. +.LP +An output character does not behave like an input character for the +purposes of macro processing; it does not inherit any of the special +properties that the input character from which it was constructed might +have had. +The following example will make things clearer. +.LP +.RS +.nf +.ft B +\&.di x +\(rs\(rs\(rs\(rs +\&.br +\&.di +\&.x +.ft +.fi +.RE +.LP +In +.I GNU mode +this will be printed as +.esc \(rs . +So each pair of input backslashes +.'char \(rs\(rs +is turned into a single output backslash +.'char \(rs +and the resulting output backslashes are not interpreted as escape +characters when they are reread. +.LP +.I Classical troff +would interpret them as escape characters when they were reread and +would end up printing a single backslash +.'char \(rs . +.LP +The correct way to get a printable +.'char \(rs +is to use the +.esc e +escape sequence. This will always print a single instance of the +current escape character, regardless of whether or not it is used in a +diversion. It will also work in both GNU mode and compatibility mode. +.LP +To store an escape sequence in a diversion that will be interpreted when +the diversion is reread, either the traditional +.esc ! +transparent output facility or the +new +.esc ? +escape sequence can be used. +. +.\" -------------------------------------------------------------------- +.SH BUGS +.\" -------------------------------------------------------------------- +At the moment, the documentation of the groff system is in a state of +change and evolution. It is possible that there are small +inconsistencies between different documents temporarily. +.LP +The +.B WARNINGS +section belongs to +.BR troff (@MAN1EXT@). +. +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +This document is part of groff, the GNU roff distribution. It was +written by Bernd Warken <bwarken@mayn.de>. +.LP +It 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 under +.RS +.LP +.IR http://www.gnu.org/copyleft/fdl.html . +.RE +.LP +Formerly, the extensions of the groff language were kept in the manual +page +.BR troff (@MAN1EXT@). +This document contains the essential parts of that documentation, but +the gory details are found in the groff info file. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +The main source of information for the groff language is the +.B groff +.BR info (1) +file. +.LP +For a survey of roff and the groff system and further documentation +pointers see +.BR roff (@MAN7EXT@). +.LP +The formatter programs are described in +.BR groff (@MAN1EXT@) +and +.BR troff (@MAN1EXT@); +a complete of all predefined glyph names can be found in +.BR groff_char (@MAN7EXT@). +.LP +The classical +.I troff +documentation is available on-line at +.RS +.LP +.I http://cm.bell-labs.com/cm/cs/cstr.html +.RE +and +.RS +.IR http://www.kohala.com/start/troff/ . diff --git a/contrib/groff/man/groff_char.man b/contrib/groff/man/groff_char.man index 18085dc..fd9f4ce 100644 --- a/contrib/groff/man/groff_char.man +++ b/contrib/groff/man/groff_char.man @@ -1,5 +1,5 @@ .ig \"-*- nroff -*- -Copyright (C) 1989-1995 Free Software Foundation, Inc. +Copyright (C) 1989-2000 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -45,7 +45,9 @@ This manual page lists the standard .B groff input characters. Only the characters that are available for the device that -is being used to print this manual page will be displayed. +is being used to print or view this manual page will be +.ie \n(.g displayed (the device currently used is `\*(.T'). +.el displayed. The .I "Input code" column applies to characters which can be @@ -379,6 +381,7 @@ Output Input Input PostScript Notes .C2 OK \& "check mark, tick" .C2 Of ordfeminine .C2 Om ordmasculine +.C2 pc periodcentered .C2 S1 onesuperior .C2 S2 twosuperior .C2 S3 threesuperior @@ -399,7 +402,7 @@ Output Input Input PostScript Notes .C2 br br "box rule with traditional troff metrics" .C2 ru ru "baseline rule" .C2 ul ul "underline with traditional troff metrics" -.C2 bv bv "bold vertical" +.C2 bv bv "bar vertical" .C2 bs bell .C2 ci circle .C2 bu bullet @@ -436,7 +439,9 @@ Output Input Input PostScript Notes .C2 lq quotedblleft .C2 rq quotedblright .C2 oq quoteleft "single open quote" +.C2 cq quoteright "single closing quote (ASCII 39)" .C2 aq quotesingle "apostrophe quote" +.C2 dq quotedbl "double quote (ASCII 34)" .C2 or bar .C2 at at .C1 - minus "minus sign from current font" @@ -533,6 +538,9 @@ Output Input Input PostScript Notes .C2 ib reflexsubset .C2 ip reflexsuperset .C2 ap similar +.C2 is integral +.C2 sr radical "square root" +.C2 rn \& overline .C2 pd partialdiff "partial differentiation sign" .C2 c* circlemultiply "multiply sign in a circle" .C2 c+ circleplus "plus sign in a circle" @@ -549,8 +557,8 @@ Output Input Input PostScript Notes .C2 CR carriagereturn "carriage return symbol" .C2 st suchthat .C2 /_ angle -.C2 << "" "much less" -.C2 >> "" "much greater" +.C2 << \& "much less" +.C2 >> \& "much greater" .C2 wp weierstrass "Weierstrass p" .C2 lz lozenge .C2 an arrowhorizex "horizontal arrow extension" diff --git a/contrib/groff/man/groff_font.man b/contrib/groff/man/groff_font.man index 97b6480..8b9e3b4 100644 --- a/contrib/groff/man/groff_font.man +++ b/contrib/groff/man/groff_font.man @@ -130,6 +130,16 @@ will cause no font to be mounted on the corresponding font position. The default font family is .IR fam . .TP +.B use_charnames_in_special +This command indicates that troff should encode named characters inside +special commands. +.TP +.B pass_filenames +requests that troff tells the driver the source file name being processed. +This is achieved by another tcommand: +.B F +.IR filename . +.TP .B charset This line and everything following in the file are ignored. It is allowed for the sake of backwards compatibility. @@ -139,6 +149,13 @@ Other commands are ignored by .B troff but may be used by postprocessors to store arbitrary information about the device in the DESC file. +.LP +Here a list of obsolete keywords which are recognized by +.B groff +but completely ignored: +.BR spare1 , +.BR spare2 , +.BR biggestfont . .SS Font file format A font file has two sections. The first section is a sequence of lines each containing a sequence of blank delimited @@ -165,7 +182,8 @@ Characters are ligatures; possible ligatures are .BR ff , .BR fi , -.BR fl +.BR fl , +.B ffi and .BR ffl . For backwards compatibility, the list of ligatures may be terminated @@ -209,8 +227,10 @@ Each line gives information for one character. A line comprises a number of fields separated by blanks or tabs. The format is .IP -.I -name metrics type code comment +.I name metrics type code +.RI [ entity_name ] +.RB [ -- +.IR comment ] .LP .I name identifies the character: @@ -279,7 +299,16 @@ or .B 0X it will be intepreted as hexadecimal. .LP -Anything on the line after the code field will be ignored. +The +.I entity_name +field gives an ascii string identifying the glyph which the postprocessor +uses to print the character. +This field is optional and has been introduced so that the html device driver +can encode its character set. +For example, the character `\e[Po]' is represented as `£' in html 4.0. +.LP +Anything on the line after the encoding field resp. after `-\&-' will +be ignored. .LP The .I metrics diff --git a/contrib/groff/man/roff.man b/contrib/groff/man/roff.man new file mode 100644 index 0000000..793ce61 --- /dev/null +++ b/contrib/groff/man/roff.man @@ -0,0 +1,520 @@ +.\" -*- nroff -*- +.ig +roff.7 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2000 Free Software Foundation, Inc. +written by Bernd Warken <bwarken@mayn.de> + +Last update: 17 May 2000 + +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 +.\" -------------------------------------------------------------------- +. +.if n \{\ +. mso tmac.tty-char +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.\" text lines in macro definitions or bracketed sections \{...\} +.de text +. if 1 \&\\$*\& +.. +. +.de option +. ds @tmp@ \f(CB\\$1\fP +. shift 1 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de 'char +. ds @tmp@ `\f(CB\\$1\fP' +. shift +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de esc +. ds @tmp@ \f(CB\e\\$1\fP +. shift +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de argname +. ds @tmp@ \f(CI\\$1\fP +. shift 1 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de prefixednumber +. ds @tmp@ \&\\$1\ \f(CR\\$2\fP +. shift 2 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +.TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +roff \- a survey of the roff typesetting system +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +.I roff +is the general name for a set of type-setting programs, known under +names like +.IR troff , +.IR nroff , +.IR groff , +etc. +.LP +The roff type-setting system consists of a formatting language, macro +packages, preprocessors, postprocessors for output devices, user +front-end programs, and conversion tools. +.LP +The most common roff system today is the free software implementation +.I groff +(from `GNU\ roff'). +The pre-groff implementations are referred to as `classical' (dating +back as long as 1973). +.LP +.I groff +is backward-compatible to its classical ancestors, but has many +extensions, and is still evolving. +As it is available for almost every computer system it is the de-facto +roff standard today. +.LP +In spite of its age, roff is in wide use today, e.g., the manual pages +on UNIX systems +.RI ( man-pages ) +are written in roff. +The roff output for text devices is still unmatched, and its graphical +output has the same quality as the other free type-setting programs and +is better than some of the commercial systems. +.LP +This document gives only an overview and provides pointers to further +documentation. + +This document is not maintained and might be out of date. For the real +documentation refer to the groff info file that contains the detailed, +actual and concise reference information. +.\" -------------------------------------------------------------------- +.SH "FORMATTING LANGUAGE" +.\" -------------------------------------------------------------------- +There are three terms that refer to the language of the +.I roff +system. +The term +.I troff language +is used when the classical aspects of +.I roff +are stressed, the term +.I groff language +includes the GNU extensions, whereas +.I roff language +is the general term. +.LP +The main source of documentation for all aspects of the +.I groff language +is the groff info file. The manual page +.BR groff (@MAN7EXT@) +gives a short description of all predefined language elements. +.LP +Documents using roff are normal text files decorated by formatting +elements. +It is very easy to write high-quality documents by using one of the +macro packages. +These are like high-level programming languages, while the bare roff +language compares to a low-level language like C or assembler. +.LP +The roff language is a full programming language providing low-level +requests, definition of macros, escape sequences, string variables, +number or size registers, and C-like flow controls. +.ig / +In the 1980s, it was even possible to write the common utilities for +system administration by only using troff. +There were contests on writing the most unreadable program fake by +exclusively using troff. +Because of security impacts, these dangerous features were removed in +.IR groff . +./ +.LP +Some clarification on the language elements seems to be wanted. +Requests are basic formatting commands defined by programming languages +like C, C++, etc., whereas macros are formatting commands that are +written in the roff language. +A document writer will not note any difference in usage for requests or +macros, both are written on a line on their own starting with a dot +.'char . . +But the user may define her own macros if desired. +.LP +Escape sequences are in-line elements starting with a backslash +.'char \e . +They are used to implement various features, including the insertion of +non-ASCII characters with +.esc ( , +the content of strings with +.esc * +and register variables with +.esc n , +font changes with +.esc f , +in-line comments with +.esc \(dq , +the escaping of special control characters like +.esc \e , +and many other features. +.\" -------------------------------------------------------------------- +.SH FORMATTERS +.\" -------------------------------------------------------------------- +Formatters are the front-end programs that analyze a groff document and +translate it into a form that is suitable for a special device. +The traditional +.I roff +had two formatters, +.B nroff +for text devices and +.B troff +for graphical devices. +.LP +These programs still exist in the +.I groff +implementation, but usually they are accessed through a program called +.BR groff . +This combined and extended the old functionality into a single program. +It has many command-line options, most of them herited from +.BR troff . +To ease the option jungle, the user-friendly utility +.B grog +(from `groff guess') was created. +It tries to guess from the document which arguments should be used and +displays a suitable command line. +Though not being perfect, it is a good starting point. +.\" -------------------------------------------------------------------- +.SH PREPROCESSORS +.\" -------------------------------------------------------------------- +The classical preprocessors that are still available in groff. +.RS +.LP +.PD 0 +.TP +.I eqn +for including mathematical equations. +.TP +.I grap +for constructing graphical elements (this preprocessor doesn't come with +groff; it is an extra package). +.TP +.I grn +for including gremlin pictures. +.TP +.I pic +for creating diagrams. +.TP +.I refer +for bibliographic references. +.TP +.I soelim +for including other roff files. +.TP +.I tbl +for rectangular tables. +.PD +.RE +.LP +Each of these preprocessors defines its own language that is translated +into roff code when run through the preprocessor program. +So parts written in these languages may be included within a roff +document. +Such an enhanced document is run through one or more corresponding +preprocessors before it is fed into the actual formatter. +.LP +The preprocessor programs extract and transform the document parts +determined for them. +They can be called either in a UNIX pipeline with their program name or +automatically with a groff option. +.LP +.TS +center, box, tab (@); +C | C +CfCB | CfCB. +preprocessor@groff option += +eqn@\-e +grap@\-G +grn@\-g +pic@\-p +refer@\-R +tbl@\-r +soelim@\-s +.TE +.LP +. +.\" -------------------------------------------------------------------- +.SH "MACRO PACKAGES" +.\" -------------------------------------------------------------------- +Macro packages are collections of macros that are suitable to format a +special kind of documents in a convenient way. +This greatly eases the usage of roff. +The macro definitions of a package are kept in a file called +.BI tmac. name +where +.I name +is the internal roff name for this package. +All tmac files are stored in a single or few directories at standard +positions. +.LP +A macro package that is used in a document is specified by the command line +option +.option \-m +for the formatter like +.option "troff\ \-m" +.argname name +or +.option "groff\ \-m" +.argname name . +General details on the naming of macro packages and their placement is +found in +.BR tmac (@MAN5EXT@). +.LP +Famous classical macro packages are +.IR man , +.IR mandoc , +and +.I mdoc +for manual pages and +.IR me , +.IR ms , +and +.I mm +for books, articles, and letters. +Besides these collections, groff provides an increasing number of new +macro packages for various applications, for example integration of or +conversion into other file formats. +.\" -------------------------------------------------------------------- +.SH "FILE NAME EXTENSIONS" +.\" -------------------------------------------------------------------- +Manual pages (man-pages) take the section number as a file name +extension, e.g., the filename for this document is +.IR roff.7 , +i.e., it is kept in +.prefixednumber section 7 +of the man-pages. +.LP +The classical macro packages take the package name as an extension, e.g. +.IB file. me +for a document using the +.I me +macro package, +.IB file. mm +for +.IR mm , +.IB file. ms +for +.IR ms , +.IB file. pic +for +.I pic +files, +etc. +.ig +.LP +But there is no general naming scheme for roff documents, though +.IB file. roff +or +.IB file. rof +seems to be a good choice. +.LP +File name extensions can be very handy in conjunction with the +.BR less (1) +pager. +It provides the possibility to feed all input into a command-line pipe that +is specified in the shell environment variable +.B LESSOPEN +This process is not well documented, so here an example +.B LESSOPEN='|lesspipe %s' +where +.B lesspipe +is either a system supplied command or a shell script of your own. +.. +.\" -------------------------------------------------------------------- +.SH EDITING +.\" -------------------------------------------------------------------- +Most text editors provide support for editing documents using roff. +Especially useful is the +.B nroff-mode +in all flavors of the Emacs editor. +.\" -------------------------------------------------------------------- +.SH ENVIRONMENT +.\" -------------------------------------------------------------------- +.TP +.SM +.B GROFF_TMAC_PATH +A colon separated list of directories in which to search for +macro files, see +.BR tmac (@MAN5EXT@). +.TP +.SM +.B GROFF_TYPESETTER +Default device. +.TP +.SM +.B GROFF_FONT_PATH +A colon separated list of directories in which to search for the +.BI dev name +directory. +.B troff +will search in directories given in the +.option \-F +option before these, and in standard directories +.RB ( .:/usr/local/share/groff/font:/usr/lib/font ) +after these. +.\" -------------------------------------------------------------------- +.SH FILES +.\" -------------------------------------------------------------------- +By default, +.I groff +installs all of its library files in a directory tree under +.IR /usr/local/share/groff . +This location might vary for different systems. +In the following, this directory is referred to as +.IR <groff_dir> . +.LP +.TP +.IB <groff_dir> /tmac/troffrc +Initialization file for troff. +.TP +.IB <groff_dir> /tmac/tmac. name +Macro files. +.TP +.IB <groff_dir> /font/dev name /DESC +Device description file for device +.IR name . +.TP +.IB <groff_dir> /font/dev name / F +Font file for font +.I F +of device +.IR name . +.\" -------------------------------------------------------------------- +.SH BUGS +.\" -------------------------------------------------------------------- +The groff documentation is in evolution at the moment. +It is possible that small inconsistencies between different documents exist +temporarily. +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +This document is part of groff, the GNU roff distribution. It was +written by Bernd Warken <bwarken@mayn.de>. +.LP +It 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 under +.RS +.LP +.IR <http://www.gnu.org/copyleft/fdl.html> . +.RE +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +The main source of information is the +.I groff +.BR info (1) +file. +.LP +The predefined elements of the +.I groff +language are also documented in the manual page +.BR groff (@MAN7EXT@). +.LP +Formatters and their wrappers: +.BR groff (@MAN1EXT@), +.BR grog (@MAN1EXT@), +.BR nroff (@MAN1EXT@), +and +.BR troff (@MAN1EXT@). +.LP +Postprocessors for the output devices: +.BR grodvi (@MAN1EXT@), +.BR grohtml (@MAN1EXT@), +.BR grolbp (@MAN1EXT@), +.BR grolj4 (@MAN1EXT@), +.BR grops (@MAN1EXT@), +and +.BR grotty (@MAN1EXT@). +.LP +Standard preprocessors: +.BR eqn (@MAN1EXT@), +.BR grn (@MAN1EXT@), +.BR grap (1), +.BR pic (@MAN1EXT@), +.BR refer (@MAN1EXT@), +.BR soelim (@MAN1EXT@), +and +.BR tbl (@MAN1EXT@). +.LP +The man pages for macro packages include +.BR groff_tmac (@MAN5EXT@), +.BR groff_man (@MAN7EXT@), +.BR groff_markup (@MAN7EXT@), +.BR groff_mdoc (@MAN7EXT@), +.BR groff_mdoc.samples (@MAN7EXT@), +.BR groff_me (@MAN7EXT@), +.BR groff_mm (@MAN7EXT@), +.BR groff_mmroff (@MAN7EXT@), +.BR groff_ms (@MAN7EXT@), +and +.BR groff_msafer (@MAN7EXT@). +.LP +The following utilities are available: +.BR addftinfo (@MAN1EXT@), +.BR afmtodif (@MAN1EXT@), +.BR hpftodit (@MAN1EXT@), +.BR indxbib (@MAN1EXT@), +.BR lookbib (@MAN1EXT@), +.BR pfbtops (@MAN1EXT@), +.BR tfmtodit (@MAN1EXT@), +and +.BR gxditview (@MAN1EXT@). +.LP +For details on the GNU implementation of the +.I roff +system see +.BR groff_char (@MAN7EXT@), +.BR groff_font (@MAN7EXT@), +.BR groff_out (@MAN7EXT@), +and the file +.I README +in the main directory of the groff source distribution. +These also give details on how to contact or join the +.I groff +developer group. +.LP +Many classical +.troff +documents are still available on-line. +Especially informative are the original Bell Labs proceedings for the old, +free UNIX 7 found at +.I http://cm.bell-labs.com/cm/cs/cstr.html +and the collection of the late Richard S. Stevens at +.IR http://www.kohala.com/start/troff/ . |
