diff options
Diffstat (limited to 'contrib/groff/man')
| -rw-r--r-- | contrib/groff/man/Makefile.sub | 5 | ||||
| -rw-r--r-- | contrib/groff/man/ditroff.man | 199 | ||||
| -rw-r--r-- | contrib/groff/man/groff.man | 3067 | ||||
| -rw-r--r-- | contrib/groff/man/groff_char.man | 939 | ||||
| -rw-r--r-- | contrib/groff/man/groff_diff.man | 3650 | ||||
| -rw-r--r-- | contrib/groff/man/groff_font.man | 441 | ||||
| -rw-r--r-- | contrib/groff/man/groff_tmac.man | 1124 | ||||
| -rw-r--r-- | contrib/groff/man/roff.man | 1544 |
8 files changed, 8936 insertions, 2033 deletions
diff --git a/contrib/groff/man/Makefile.sub b/contrib/groff/man/Makefile.sub index 020d20f..86c4aea 100644 --- a/contrib/groff/man/Makefile.sub +++ b/contrib/groff/man/Makefile.sub @@ -1,7 +1,10 @@ MAN5=\ groff_font.n \ - groff_out.n + groff_out.n \ + groff_tmac.n MAN7=\ + ditroff.n \ groff_char.n \ + groff_diff.n \ groff.n \ roff.n diff --git a/contrib/groff/man/ditroff.man b/contrib/groff/man/ditroff.man new file mode 100644 index 0000000..0867f3d0 --- /dev/null +++ b/contrib/groff/man/ditroff.man @@ -0,0 +1,199 @@ +.ig +ditroff.man + +Last update: 4 Jan 2002 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2001, 2002 Free Software Foundation, Inc. +written by Bernd Warken <bwarken@mayn.de> +maintained by Werner Lemberg <wl@gnu.org> + +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 AUTHORS, 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 +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \ +. ftr CB CW +. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +. +.TH DITROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +ditroff \- classical device independent roff +. +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +The name +.I ditroff +once marked a development level of the +.I troff +text processing system. +. +In actual +.BR roff (@MAN7EXT@) +systems, the name +.I troff +is used as a synonym for +.IR ditroff . +. +.P +The first roff system was written by Joe Osanna around 1973. +. +It supported only two output devices, the +.B nroff +program produced text oriented tty output, while the +.B troff +program generated graphical output for exactly one output device, the Wang +.I Graphic Systems CAT +typesetter. +. +.P +In 1979, Brian Kernighan rewrote troff to support more devices by +creating an intermediate output format for troff that can be fed into +postprocessor programs which actually do the printout on the device. +. +Kernighan's version marks what is known as +.I classical troff +today. +. +In order to distinguish it from Osanna's original mono-device version, +it was called +.I ditroff +.RI ( d\/ evice\~ i\/ ndependent\~ troff\/ ) +on some systems, though this naming isn't mentioned in the classical +documentation. +. +.P +Today, any existing roff system is based on Kernighan's multi-device +troff. +. +The distinction between +.I troff +and +.I ditroff +isn't necessary any longer, for each modern +.I troff +provides already the complete functionality of +.IR ditroff . +. +On most systems, the name +.I troff +is used to denote +.IR ditroff . +. +.P +The easiest way to use ditroff is the GNU roff system, +.IR groff . +The +.BR groff (@MAN1EXT@) +program is a wrapper around +.I (di)troff +that automatically handles postprocessing. +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +.TP +.I [CSTR\~#54] +The 1992 revision of the +.I Nroff/Troff User's Manual +by +.I J. F. Osanna +and +.IR "Brian Kernighan" , +see +.br +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz \ + "Bell Labs CSTR\~#54" . +. +.TP +.I [CSTR\~#97] +.I A Typesetter-independent TROFF +by +.I Brian Kernighan +is the original documentation of the first multi-device troff +.RI ( ditroff\/ ), +see +.br +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz \ + "Bell Labs CSTR\~#97" . +. +.TP +.BR roff (@MAN7EXT@) +This document gives details on the history and concepts of roff. +. +.TP +.BR @g@troff (@MAN1EXT@) +The actual implementation of +.IR ditroff . +. +.TP +.BR groff (@MAN1EXT@) +The GNU roff program and pointers to all documentation around groff. +. +.TP +.BR groff_out (@MAN5EXT@) +The groff version of the intermediate output language, the basis for +multi-devicing. +. +. +.\" -------------------------------------------------------------------- +.SH "AUTHORS" +.\" -------------------------------------------------------------------- +. +Copyright (C) 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.MTO bwarken@mayn.de "Bernd Warken" +and is maintained by +.MTO wl@gnu.org "Werner Lemberg" . +. +. +.\" -------------------------------------------------------------------- +.\" Emacs settings +.\" -------------------------------------------------------------------- +.\" +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/contrib/groff/man/groff.man b/contrib/groff/man/groff.man index c20cf07..1e9128d 100644 --- a/contrib/groff/man/groff.man +++ b/contrib/groff/man/groff.man @@ -1,16 +1,19 @@ '\" t .ig -groff.7 +groff.man + +Last update: 29 June 2002 This file is part of groff, the GNU roff type-setting system. -Copyright (C) 2000, 2001 Free Software Foundation, Inc. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. written by Bernd Warken <bwarken@mayn.de> +maintained by Werner Lemberg <wl@gnu.org> 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 +Invariant Sections being this .ig-section and AUTHORS, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the Free Documentation License is included as a file called @@ -21,6 +24,8 @@ FDL in the main directory of the groff source package. .\" Setup .\" -------------------------------------------------------------------- . +.mso www.tmac +. .if n \{\ . mso tty-char.tmac . ftr CR R @@ -32,243 +37,281 @@ FDL in the main directory of the groff source package. . ftr CB CW .\} . -.\" a comment macro which does nothing -.de c -.. -. -.\" a tab string -.ds t "\t . +.\" -------------------------------------------------------------------- +.\" start of macro definitions .eo . -.c text lines in macro definitions or bracketed sections \{...\} -.de text -. if 1 \&\$*\& +.de c .. . -.de option -. ds @tmp@ \f(CB\$1\fP -. shift 1 -. text \*[@tmp@]\$* -. rm @tmp@ +.de TPx +. TP 10n +.. +.c --------------------------------------------------------------------- +.c .Text anything ... +.c +.c All arguments are printed as text. +.c +.de Text +. nop \)\$* +.. +.c --------------------------------------------------------------------- +.c .ExecFF macro font1 font2 text1 text2 text1 text2 ... +.c +.c Concat text arguments using alternating fonts and feed into macro. +.c For a trailing punctuation, terminate the call with \c. +.c +.de ExecFF +. if (\n[.$] < 4) \ +. return +. ds @a\" +. ds @m \$1\" +. ds @f1 \$2\" +. ds @f2 \$3\" +. shift 3 +. ds @s\" +. while 1 \{\ +. if (\n[.$] = 0) \ +. break +. ds @a \$1\" +. as @s \f[\*[@f1]]\*[@a]\f[]\" +. shift +. if (\n[.$] = 0) \ +. break +. ds @a \$1\" +. as @s \f[\*[@f2]]\*[@a]\f[]\" +. shift +. \} +. \*[@m] "\*[@s]\f[R]" +. ft P \" to make \c happy +. rm @m +. rm @s +. rm @a +. rm @f1 +. rm @f2 .. . -.als shellcommand option +.c --------- command line option --------- +. +.de option +. Text \f[CB]\$* +. ft P +.. . .c --------- characters --------- . .de character -. ds @tmp@ \f(CB\$1\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +. ExecFF Text CB R \$* .. -. -.de 'char -. ds @tmp@ \(oq\f(CB\$1\fP\(cq +.de squoted_char +. ds @1 \$1\" . shift -. text \*[@tmp@]\$* -. rm @tmp@ +. ExecFF Text R CB \[oq] \*[@1] "\[cq]\$*" +. rm @1 .. -. -.de ''char -. ds @tmp@ \(lq\f(CB\$1\fP\(rq +.de dquoted_char +. ds @1 \$1\" . shift -. text \*[@tmp@]\$* -. rm @tmp@ +. ExecFF Text R CB \[lq] \*[@1] "\[rq]\$*" +. rm @1 .. -. .c --------- requests --------- . -.c request synopsis +.c synopsis of a request .de REQ -. ds @tmp@ \&\$1 +. if (\n[.$] = 0) \ +. return +. ds @1 \$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 +. ie (\n[.$] = 0) \{\ +. TP 10n +. Text \f[CB]\*[@1]\f[] . \} -. if \n[.$] .as @tmp@ \/\f(CR\$1\fP -. text \*[@tmp@] -. rm @tmp@ +. el \{\ +. TP 10n +. Text \f[CB]\*[@1]\~\f[]\f[I]\$*\f[] +. \} +. rm @1 .. -. -.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 reference of a request +.de request +. BR \$* .. . .c --------- numerical elements --------- . -.de number -. ds @tmp@ \f(CR\$1\fP -. shift 1 -. text \*[@tmp@]\$* -. rm @tmp@ +.c number with a trailing unit +.de scalednumber +. Text \$1\^\f[CB]\$2\f[]\$3\f[R] +. ft P .. . -.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@ +.c representation of units within the text +.de scaleindicator +. Text \f[CB]\$1\f[]\$2\f[R] +. ft P .. . +.c representation of mathematical operators within the text .de operator -. ds @tmp@ \(oq\f(CB\$1\fP\(cq -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +. squoted_char \$@ .. . -.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@ -.. +.c --------- escape sequences --------- . -.de esc(arg -. ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP -. shift 2 -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .ESC name [arg] +.c +.c Synopsis of an escape sequence, optionally with argument +.c Args : 1 or 2; `name' obligatory, `arg' optional +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary word +.c Result : prints \namearg, where `name' is in CB, `arg' in I +.c +.de ESC +. if (\n[.$] < 1) +. ab .ESC needs 1 or 2 arguments. +. ExecFF IP CB I "\[rs]\$1" "\,\$2\/" .. -. -.de escarg -. ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP -. shift 2 -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .ESC[] name arg +.c +.c Synopsis for escape sequence with a bracketed long argument +.c Args : 2 obligatory +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary text +.c Result : prints \name[arg], where `name' is in CB, `arg' in I +.c +.de ESC[] +. if !(\n[.$] = 2) \ +. ab .ESC[] needs exactly 2 arguments. +. ExecFF IP CB I "\[rs]\$1\[lB]" "\h'-0.2m'\$2\h'-0.15m'" \[rB] .. -. -.de esc[] -. ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .ESCq name arg +.c +.c Synopsis for escape sequence with a bracketed long argument +.c Args : 2 obligatory +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary text +.c Result : prints \name'arg', where `name' is in CB, `arg' in I +.c +.de ESCq +. if !(\n[.$] = 2) \ +. ab .ESCq needs exactly 2 argument. +. ExecFF IP CB I "\[rs]\$1\[cq]" "\h'-0.3m'\$2" \[cq] .. -. -.de esc( -. ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .ESC? arg +.c +.c Synopsis for escape sequence with a bracketed long argument +.c Args : 1 obligatory +.c arg : arbitrary text +.c Result : prints `\?arg?', where the `?' are in CB, `arg' in I +.c +.de ESC? +. if !(\n[.$] = 1) \ +. ab .ESC? needs exactly 1 arguments. +. ExecFF IP CB I \[rs]? "\$1" ? .. -. +.c --------------------------------------------------------------------- +.c .esc name [punct] +.c +.c Reference of an escape sequence (no args), possibly punctuation +.c Args : 1 obligatory +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c punct : arbitrary +.c Result : prints \name, where `name' is in B, `punct' in R +.c .de esc -. ds @tmp@ \f(CB\(rs\$1\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +. if (\n[.$] < 1) \ +. ab .esc needs 1 or 2 arguments. +. BR "\[rs]\$1" \$2 .. -. -.de (esc -. ds @tmp@ \f(CB\(rs(\$1\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .escarg name arg [punct] +.c +.c Reference of an escape sequence (no args) +.c Args : 1 obligatory, 1 optional +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary word +.c Result : prints \namearg, where +.c `name' is in B, `arg' in I +.c +.de escarg +. if (\n[.$] < 2) \ +. ab .esc needs 2 or 3 arguments. +. Text \f[B]\[rs]\$1\f[]\f[I]\$2\f[]\$3 .. -. -.de [esc] -. ds @tmp@ \f(CB\(rs[\$1]\fP -. shift -. text \*[@tmp@]\$* -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .esc[] name arg [punct] +.c +.c Reference for escape sequence with a bracketed long argument +.c Args : 2 obligatory +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary text +.c Result : prints \name[arg], where `name' is in CB, `arg' in CI +.c +.de esc[] +. if (\n[.$] < 2) \ +. ab .esc[] needs 2 or 3 arguments. +. Text \f[B]\[rs]\$1\[lB]\f[]\f[I]\$2\f[]\f[B]\[rB]\f[]\$3 .. . -.c escape sequence synopsis -.de ESC -. ds @tmp@ \&\$1 -. shift 1 -. IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP" -. rm @tmp@ +.c --------------------------------------------------------------------- +.c .escq name arg +.c +.c Reference for escape sequence with a bracketed long argument +.c Args : 2 obligatory +.c name : suitable name for an escape sequence (c, (xy, [long]) +.c arg : arbitrary text +.c Result : prints \name'arg', where `name' is in CB, `arg' in CI +.c +.de escq +. if (\n[.$] < 2) \ +. ab .escq needs 2 arguments. +. Text \f[B]\[rs]\$1\[cq]\f[]\f[I]\$2\f[]\f[B]\[cq]\f[]\$3 .. . -.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 --------- strings --------- . -.c synopsis escape sequence with quoted argument -. de ESCq -. ds @tmp@ \&\$1 +.c synopsis for string, with \*[] +.de STRING +. ds @1 \$1\" . shift 1 -. IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP" -. rm @tmp@ +. TP 10n +. ExecFF Text R CB \[rs]*[ \*[@1]\f[]\f[R]] \$* +. rm @1 .. -. -.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 synopsis for a long string +.de string +. if (\n[.$] = 0) \ +. return +. Text \f[CB]\[rs]*\[lB]\$1\[rB]\f[]\$2 .. . +. .c --------- registers --------- . -.c synopsis for registers +.c synopsis for registers, with \n[] .de REG -. TP 10n -. text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP +. ds @1 \$1\" . shift 1 -.if \n[.$] \&\$* +. TP 10n +. ExecFF Text R CB \[rs]n[ \*[@1]\f[]\f[R]] \$* +. rm @1 .. -. -.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 +.c reference of a register, without decoration +.de register +. Text register +. BR \$* .. . .ec +.\" end of macro definitions +. . .\" -------------------------------------------------------------------- .\" Title @@ -278,33 +321,43 @@ FDL in the main directory of the groff source package. .SH NAME groff \- a short reference for the GNU roff language . +. .\" -------------------------------------------------------------------- .SH DESCRIPTION .\" -------------------------------------------------------------------- +. +The name .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 +. +.P 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 +. +.P Historically, the .I roff language was called .IR troff . .I groff -is compatible with the classical system and provides proper extensions. +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 @@ -312,255 +365,329 @@ slightly tends to refer more to the classical aspects, whereas 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 +. +.P +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 +. +.P The general syntax for writing groff documents is relatively easy, but writing extensions to the roff language can be a bit harder. -.LP +. +.P 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 . +.dquoted_char . or a single quote -.''char ' ; +.dquoted_char ' ; all other lines are text lines. -.LP +. +.P .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 +. +.P +.Text .command_name arg1 arg2 .RE -.LP +. +.P 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 +between the leading control character and the command name, but the +control character must be on the first position of the line. +. +.P .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 . +.squoted_char \[rs] . These are in-line or even in-word formatting elements or functions. +. Some of these take arguments separated by single quotes -.''char ' , +.dquoted_char ' , others are regulated by a length encoding introduced by an open parenthesis -.'char ( +.squoted_char ( or enclosed in brackets -.'char [ +.squoted_char [ and -.'char ] . -.LP +.squoted_char ] . +. +.P 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 +. +.P 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 . +.esc (rs +or +.esc [rs] . .IP 2. Double all backslashes. .IP 3. Begin all text lines with the special non-spacing character .esc & . -.LP +. +.P 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 +. +.P 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 +. +The fundamental elements are predefined commands and variables that +make roff a full-blown programming language. +. +.P 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 . +.squoted_char . or a -.''char ' , +.dquoted_char ' , whereas .B Escape sequences are in-line functions and in-word formatting elements starting with a backslash -.'char \(rs . -.LP +.squoted_char \[rs] . +. +.P The user can define her own formatting commands using the -.request .de -request. These commands are called +.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. +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 +. +.P 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 +. +.P .B String variables store character sequences. +. They are set with the -.request .ds +.request ds request and retrieved by the .esc * escape sequences. -.LP +. +Strings can have variables. +. +.P .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 nr request and retrieved by the .esc n escape sequences. -.LP +. +.P .B Environments allow the user to temporarily store global formatting parameters like -line length, font size, etc. for later reuse. +line length, font size, etc.\& for later reuse. +. This is done by the -.request .ev +.request ev request. -.LP +. +.P .B Fonts are identified either by a name or by an internal number. +. The current font is chosen by the -.request .ft +.request ft request or by the .esc f escape sequences. -Each device has special fonts, but the following fonts are available for -all devices. +. +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 +and is available everywhere, 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, +. +For the graphical output devices, there exist constant-width pendants +of these fonts, .BR CR , .BR CI , and .BR CB . On text devices, all characters have a constant width anyway. -.LP +. +.P 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. +. +Some action can be prescribed to be run automatically when the +condition is met. +. +.P +More detailed information and examples 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. +. +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 , +.request if , +.request ie , +.request el , and -.request .while . +.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 cc request, the control character can be set to a different character, making the dot -.'char . +.squoted_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. +. +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. +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 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. In -the -.request .ds +.character \[dq] +The double quote is used to enclose arguments in requests, macros, and +strings. +. +In the +.request ds and -.request .as +.request as requests, a leading double quote in the argument will be stripped off, -making everything else afterwards the string to be defined (enabling leading -whitespace). +making everything else afterwards the string to be defined (enabling +leading whitespace). +. The escaped double quote -.esc \(dq +.esc \[dq] introduces a comment. +. Otherwise, it is not special. +. Groff provides a printable representation with the .esc (dq escape sequence. +. .TP -.character \(rs +.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 @@ -570,261 +697,435 @@ escape; a backslash glyph can be obtained by 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. +. +In groff, this behavior can be replaced by the \f[CB][]\f[] 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. +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. +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. +\f[CI]space\f[] +Space characters are only functional characters. +. +They separate the arguments in requests, macros, and strings, 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\ " +.squoted_char "\[rs]\ " (this is the escape character followed by a space), .esc | , .esc ^ , or .esc h should be used. -.IP \f(CInewline\fP +. +.IP \f[CI]newline\f[] 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 +.squoted_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. +.IP \f[CI]tab\f[] +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. +scaling indicator. +. A -.B scale indicator +.B scaling 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 +. +A number followed by a scaling indicator signifies a size value. +. +By default, numerical values do not have a scaling indicator, i.e., they +are normal numbers. +. +.P +The +.I roff +language defines the following scaling indicators. +. +. +.P +.PD 0 +.RS +. +.TPx +.B c +Centimeter +. +.TPx +.B i +Inch +. +.TPx +.B P +Pica\ \[eq]\ 1/6\ inch +. +.TPx +.B p +Point\ \[eq]\ 1/72\ inch +. +.TPx +.B m +Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]') +. +.TPx +.B M +100\^th \f[R]of an \f[CR]Em +. +.TPx +.B n +En\ \[eq]\ Em/2 +. +.TPx +.B u +Basic unit for actual output device +. +.TPx +.B v +Vertical line space in basic units +scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in +font \f[I]DESC\f[] file) +. +.TPx +.B f +Scale by 65536. +.RE +.PD +. +.P .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 +are combinations of the numerical values defined above with the +following arithmetical operators already defined in classical troff. +. +.P +.PD 0 +.RS +. +.TPx +.B + +Addition +. +.TPx +.B \- +Subtraction +. +.TPx +.B * +Multiplication +. +.TPx +.B / +Division +. +.TPx +.B % +Modulo +. +.TPx +.B = +Equals +. +.TPx +.B == +Equals +. +.TPx +.B < +Less than +. +.TPx +.B > +Greater than +. +.TPx +.B <= +Less or equal +. +.TPx +.B >= +Greater or equal +. +.TPx +.B & +Logical and +. +.TPx +.B : +Logical or +. +.TPx +.B ! +Logical not +. +.TPx +.B ( +Grouping of expressions +. +.TPx +.B ) +Close current grouping +. +.RE +.PD +. +.P 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 +. +.P +.PD 0 +.RS +. +.TPx +.ExecFF Text I CB e1 >? e2 +The maximum of +.I e1 +and +.IR e2 . +. +.TPx +.ExecFF Text I CB e1 <? e2 +The minimum of +.I e1 +and +.IR e2 . +. +.TPx +.ExecFF Text CB I ( c ; e ) +Evaluate +.I e +using +.I c +as the default scaling indicator. +. +.RE +.PD +. +.P For details see the groff info file. . +. .\" -------------------------------------------------------------------- .SH CONDITIONS .\" -------------------------------------------------------------------- +. .B Conditions occur in tests raised by the -.request .if , -.request .ie , +.request if , +.request ie , and the -.request .while +.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 +. +.P +.PD 0 +.RS +. +.TPx +.I N +A numerical expression +.I N +yields true if its value is greater than\~0. +. +.TPx +.BI ! N +True if the value of +.I I +is\~0. +. +.TPx +.BI ' s1 ' s2 ' +True if string\~\c +.I s1 +is identical to string\~\c +.IR s2 . +. +.TPx +.BI !' s1 ' s2 ' +True if string\~\c +.I s1 +is not identical to string\~\c +.IR s2 . +. +.TPx +.BI c ch +True if there is a character\~\c +.I ch +available. +. +.TPx +.BI d name +True if there is a string, macro, diversion, or request called +.IR name . +. +.TPx +.B e +Current page number is even. +. +.TPx +.B o +Current page number is odd. +. +.TPx +.BI m name +True if there is a color called +.IR name . +. +.TPx +.B n +Formatter is +.BR nroff . +. +.TPx +.BI r reg +True if there is a register named +.IR reg . +. +.TPx +.B t +Formatter is +.BR troff . +. +.RE +.PD +. . .\" -------------------------------------------------------------------- .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 +. +.P 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" +. +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., +.RI \[dq] "arg with space" \[dq] denotes a single argument. -.LP +. +.P 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. +. +Refer to the groff info file and +.BR groff_diff (@MAN7EXT@) +for all details. +. +.P +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{ +. +.P +.PD 0 +.RS +. +.TPx +.I c +denotes a single character. +. +.TPx +.I font 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{ +. +.TPx +.I anything +all characters up to the end of the line or within +.esc { +and +.esc } . +. +.TPx +.I n is a numerical expression that evaluates to an integer value. -T} -N@T{ +. +.TPx +.I N is an arbitrary numerical expression, signed or unsigned. -T} -\(+-N@T{ +. +.TPx +.I \[+-]N has three meanings depending on its sign, described below. -T} -.TE -.LP -.ad -.hy +. +.RE +.PD +. +.P If an expression defined as -.argument \(+-N +.I \[+-]N starts with a -.operator + +.squoted_char + 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 +existing value inherent to the related request, e.g.\& adding to a number register. +. If the expression starts with a -.operator - +.squoted_char - the value of the expression will be subtracted from the request value. -.LP +. +.P Without a sign, -.argument N +.I N replaces the existing value directly. -To assign a negative number either prepend\ \c -.number 0 -or enclose the negative number in parentheses. +. +To assign a negative number either prepend\~0 or enclose the negative +number in parentheses. +. . .\" -------------------------------------------------------------------- -.SS "REQUEST SHORT REFERENCE" +.SS "Request Short Reference" .\" -------------------------------------------------------------------- +. .PD 0 . .REQ . -Empty line, ignored. Useful for structuring documents. +Empty line, ignored. . -.REQ .\(rs\(dq anything +Useful for structuring documents. +. +.REQ .\[rs]\[dq] anything Complete line is a comment. . .REQ .ab string Print -.argument string +.I string on standard error, exit program. . .REQ .ad @@ -832,38 +1133,53 @@ 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). +.I c +(\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]). . .REQ .af register c Assign format -.argument c +.I c to -.argument register -(\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP). +.I register +(\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]). . .REQ .aln alias register Create alias name for -.argument register . +.IR register . . .REQ .als alias object Create alias name for request, string, macro, or diversion -.argument object . +.IR object . . .REQ .am macro Append to -.argument macro +.I macro until -.request .. -is called. +.B ..\& +is encountered. . .REQ .am macro end Append to -.argument macro +.I macro until .request .end is called. . +.REQ .ami macro +Append to a macro whose name is contained in the string register +.I macro +until +.B ..\& +is encountered. +. +.REQ .ami macro end +Append to a macro indirectly. +.I macro +and +.I end +are string registers whose contents are interpolated for the macro name +and the end macro, respectively. +. .REQ .am1 macro Same as .request .am @@ -876,43 +1192,48 @@ but with compatibility mode switched off during macro expansion. . .REQ .as stringvar anything Append -.argument anything +.I anything to -.argument stringvar . +.IR stringvar . . .REQ .asciify diversion Unformat ASCII characters, spaces, and some escape sequences in -.argument diversion . +.IR diversion . +. +.REQ .as1 stringvar anything +Same as +.request .as +but with compatibility mode switched off during string expansion. . .REQ .backtrace Print a backtrace of the input on stderr. . .REQ .bd font N Embolden -.argument font +.I font by -.argterm N -1 +.IR N -1 units. . .REQ .bd S font N Embolden Special Font -.argument S +.I S when current font is -.argument font . +.IR font . . .REQ .blm Unset the blank line macro. . .REQ .blm macro Set the blank line macro to -.argument macro . +.IR macro . . .REQ .box End current diversion. . .REQ .box macro Divert to -.argument macro , +.IR macro , omitting a partially filled line. . .REQ .boxa @@ -920,15 +1241,15 @@ End current diversion. . .REQ .boxa macro Divert and append to -.argument macro , +.IR macro , omitting a partially filled line. . .REQ .bp Eject current page and begin new page. . -.REQ .bp \(+-N +.REQ .bp \[+-]N Eject current page; next page number -.argument \(+-N . +.IR \[+-]N . . .REQ .br Line break. @@ -943,62 +1264,70 @@ Break out of a while loop. . .REQ .c2 Reset no-break control character to -.''char ' . +.dquoted_char ' . . .REQ .c2 c Set no-break control character to -.argument c . +.IR c . . .REQ .cc Reset control character to -.'char . . +.squoted_char . . . .REQ .cc c Set control character to -.argument c . +.IR c . . .REQ .ce Center the next input line. . .REQ .ce N Center following -.argument N +.I N input lines. . .REQ .cf filename Copy contents of file -.argument filename +.I filename unprocessed to stdout or to the diversion. . -.REQ .cflags mode c1 c2 ... +.REQ .cflags mode c1 c2 .\|.\|.\& Treat characters -.argument c1 , -.argument c2 , -.argument ... +.IR c1 , +.IR c2 , +.I .\|.\|.\& according to -.argument mode +.I mode number. . .REQ .ch trap N Change -.argument trap +.I trap location to -.argument N . +.I N . . .REQ .char c anything Define character -.argument c -to string -.argument anything . +.I c +as string +.IR anything . . .REQ .chop object Chop the last character off macro, string, or diversion -.argument object . +.IR object . . .REQ .close stream Close the -.argument stream . +.IR stream . +. +.REQ .color +Enable colors. +. +.REQ .color N +If +.I N +is zero disable colors, otherwise enable them. . .REQ .continue Finish the current iteration of a while loop. @@ -1013,11 +1342,11 @@ is zero disable compatibility mode, otherwise enable it. . .REQ .cs font N M Set constant character width mode for -.argument font +.I font to -.argterm N /36 +.IR N /36 ems with em -.argument M . +.IR M . . .REQ .cu N Continuous underline in nroff, like @@ -1029,18 +1358,18 @@ End current diversion. . .REQ .da macro Divert and append to -.argument macro . +.IR macro . . .REQ .de macro Define or redefine -.argument macro +.I macro until -.request .. -is called. +.B ..\& +is encountered. . .REQ .de macro end Define or redefine -.argument macro +.I macro until .request .end is called. @@ -1055,18 +1384,41 @@ Same as .request .de but with compatibility mode switched off during macro expansion. . +.REQ .defcolor color scheme component +Define or redefine a color with name +.IR color . +.I scheme +can be +.BR rgb , +.BR cym , +.BR cymk , +.BR gray , +or +.BR grey . +.I component +can be single components specified as fractions in the range 0 to 1 +(default scaling indicator\~\c +.scaleindicator f ), +as a string of two-digit hexadecimal color components with a leading +.BR # , +or as a string of four-digit hexadecimal components with two leading +.BR # . +The color +.B default +can't be redefined. +. .REQ .dei macro Define or redefine a macro whose name is contained in the string register -.argument macro +.I macro until -.request .. -is called. +.B ..\& +is encountered. . .REQ .dei macro end Define or redefine a macro indirectly. -.argument macro +.I macro and -.argument end +.I end are string registers whose contents are interpolated for the macro name and the end macro, respectively. . @@ -1075,7 +1427,7 @@ End current diversion. . .REQ .di macro Divert to -.argument macro . +.I macro . . .REQ .do name Interpret @@ -1084,23 +1436,28 @@ with compatibility mode disabled. . .REQ .ds stringvar anything Set -.argument stringvar +.I stringvar to -.argument anything . +.IR anything . +. +.REQ .ds1 stringvar anything +Same as +.request .ds +but with compatibility mode switched off during string expansion. . .REQ .dt N trap Set diversion trap to position -.argument N -(default scale indicator\ \c +.I N +(default scaling indicator\~\c .scaleindicator v ). . .REQ .ec Reset escape character to -.'char \(rs . +.squoted_char \[rs] . . .REQ .ec c Set escape character to -.argument c . +.IR c . . .REQ .ecr Restore escape character saved with @@ -1111,12 +1468,12 @@ Save current escape character. . .REQ .el anything Else part for if-else (\c -.argument .ie ) +.request ie ) request. . .REQ .em macro The -.argument macro +.I macro will be run after the end of input. . .REQ .eo @@ -1127,12 +1484,12 @@ Switch to previous environment. . .REQ .ev env Push down environment number or name -.argument env +.I env and switch to it. . .REQ .evc env Copy the contents of environment -.argument env +.I env to the current environment. No pushing or popping. . @@ -1144,20 +1501,27 @@ Return to previous font family. . .REQ .fam name Set the current font family to -.argument name . +.IR name . . .REQ .fc Disable field mechanism. . .REQ .fc a Set field delimiter to -.argument a +.I a and pad character to space. +. .REQ .fc a b Set field delimiter to -.argument a +.I a and pad character to -.argument b . +.IR b . +. +.REQ .fchar c anything +Define fallback character +.I c +as string +.IR anything . . .REQ .fi Fill output lines. @@ -1167,112 +1531,123 @@ Flush output buffer. . .REQ .fp n font Mount -.argument font +.I font on position -.argument n . +.IR n . . .REQ .fp n internal external Mount font with long -.argument external +.I external name to short -.argument internal +.I internal name on position -.argument n . +.IR n . . -.REQ .fspecial font s1 s2... +.REQ .fspecial font s1 s2 .\|.\|.\& When the current font is -.argument font , +.IR font , then the fonts -.argument s1 , -.argument s2 , -.argument ... +.IR s1 , +.IR s2 , +.I .\|.\|.\& will be special. . .REQ .ft Return to previous font. Same as -.request \(rsfP . +.request \[rs]f[] +or +.request \[rs]fP . +. .REQ .ft font Change to font name or number -.argument font ; +.IR font ; same as -.esc[arg] f font +.esc[] f font escape sequence. . .REQ .ftr font1 font2 Translate -.argument font1 +.I font1 to -.argument font2 . +.IR font2 . . .REQ .hc Remove additional hyphenation indicator character. . .REQ .hc c -Set up additional hyphenation indicator character\ \c -.argument c . +Set up additional hyphenation indicator character\~\c +.IR c . . -.REQ .hcode c1 code1 c2 code2 ... +.REQ .hcode c1 code1 c2 code2 .\|.\|.\& Set the hyphenation code of character -.argument c1 +.I c1 to -.argument code1 , +.IR code1 , that of -.argument c2 +.I c2 to -.argument code2 , +.IR code2 , etc. . .REQ .hla lang Set the current hyphenation language to -.argument lang . +.IR lang . . .REQ .hlm n Set the maximum number of consecutive hyphenated lines to -.argument n . +.IR n . . .REQ .hpf file Read hyphenation patterns from -.argument file . +.IR file . +. +.REQ .hpfa file +Append hyphenation patterns from +.IR file . +. +.REQ .hpfcode file +Set input mapping for +.request .hpf . . .REQ .hw words List of -.argument words +.I words with exceptional hyphenation. . .REQ .hy N Switch to hyphenation mode -.argument N . +.IR N . . .REQ .hym n Set the hyphenation margin to -.argument n -(default scale indicator\ \c +.I n +(default scaling indicator\~\c .scaleindicator m ). . .REQ .hys n Set the hyphenation space to -.argument n . +.IR n . . .REQ .ie cond anything If -.argument cond +.I cond then -.argument anything +.I anything else goto .request .el . . .REQ .if cond anything If -.argument cond +.I cond then -.argument anything ; +.IR anything ; otherwise do nothing. . .REQ .ig Ignore text until -.request .. -is called. +.B ..\& +is encountered. . .REQ .ig end Ignore text until @@ -1281,36 +1656,44 @@ Ignore text until .REQ .in Change to previous indent value. . -.REQ .in \(+-N +.REQ .in \[+-]N Change indent according to -.argument \(+-N -(default scale indicator\ \c +.I \[+-]N +(default scaling indicator\~\c .scaleindicator m ). . .REQ .it N trap -Set an input-line count trap at position -.argument N . +Set an input-line count trap for the next +.I N +lines. +. +.REQ .itc N trap +Same as +.request .it +but count lines interrupted with +.esc c +as one line. . .REQ .kern Enable pairwise kerning. . .REQ .kern n If -.argument n +.I 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 . +Set leader repetition character to\~\c +.IR c . . .REQ .length register anything Write the length of the string -.argument anything +.I anything in -.argument register . +.IR register . . .REQ .linetabs Enable line-tabs mode (i.e., calculate tab positions relative to output @@ -1318,28 +1701,28 @@ line). . .REQ .linetabs n If -.argument n +.I n is zero, disable line-tabs mode, otherwise enable it. . .REQ .lf N file Set input line number to -.argument N +.I N and filename to -.argument file . +.IR file . . .REQ .lg N Ligature mode on if -.argterm N >0 . +.IR N >0. . .REQ .ll Change to previous line length. . -.REQ .ll \(+-N +.REQ .ll \[+-]N Set line length according to -.argument \(+-N +.I \[+-]N (default size .scalednumber 6.5 i , -default scale indicator\ \c +default scaling indicator\~\c .scaleindicator m ). . .REQ .ls @@ -1347,13 +1730,13 @@ Change to the previous value of additional intra-line skip. . .REQ .ls N Set additional intra-line skip value to -.argument N , +.IR N , i.e., -.argterm N -1 +.IR N -1 blank lines are inserted after each text output line. . -.REQ .lt \(+-N -Length of title (default scale indicator\ \c +.REQ .lt \[+-]N +Length of title (default scaling indicator\~\c .scaleindicator m ). . .REQ .mc @@ -1361,20 +1744,20 @@ Margin character off. . .REQ .mc c Print character -.argument c +.I c after each text line at actual distance from right margin. . .REQ .mc c N Set margin character to -.argument c +.I c and distance to -.argument N -from right margin (default scale indicator\ \c +.I N +from right margin (default scaling indicator\~\c .scaleindicator m ). . .REQ .mk register Mark current vertical position in -.argument register . +.IR register . . .REQ .mso file The same as the .so request except that @@ -1389,8 +1772,8 @@ Need a one-line vertical space. . .REQ .ne N Need -.argument N -vertical space (default scale indicator\ \c +.I N +vertical space (default scaling indicator\~\c .scaleindicator v ). . .REQ .nf @@ -1402,7 +1785,7 @@ No hyphenation. .REQ .nm Number mode off. . -.REQ .nm \(+-N M S I +.REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP In line number mode, set number, multiple, spacing, and indent. . .REQ .nn @@ -1410,20 +1793,20 @@ Do not number next line. . .REQ .nn N Do not number next -.argument N +.I N lines. . .REQ .nop anything Always execute -.argument anything . +.IR anything . . -.REQ .nr register \(+-N M +.REQ .nr register \[+-]N M Define or modify -.argument register +.I register using -.argument \(+-N +.I \[+-]N with auto-increment -.argument M . +.IR M . . .REQ .nroff Make the built-in condition @@ -1435,6 +1818,9 @@ false. .REQ .ns Turn no-space mode on. . +.REQ .nx +Immediately jump to end of current file. +. .REQ .nx filename Next file. . @@ -1452,19 +1838,28 @@ but append to it. . .REQ .os Output vertical distance that was saved by the -.request .sv +.request sv request. . +.REQ .output string +Emit +.I string +directly to intermediate output, allowing leading whitespace if +.I string +starts with +.character \[dq] +(which will be stripped off). +. .REQ .pc -Reset page number character to\ \c -.'char % . +Reset page number character to\~\c +.squoted_char % . . .REQ .pc c Page number character. . .REQ .pi program Pipe output to -.argument program +.I program (nroff only). . .REQ .pl @@ -1473,10 +1868,10 @@ Set page length to default The current page length is stored in .register .p . . -.REQ .pl \(+-N +.REQ .pl \[+-]N Change page length to -.argument \(+-N -(default scale indicator\ \c +.I \[+-]N +(default scaling indicator\~\c .scaleindicator v ). . .REQ .pm @@ -1485,47 +1880,58 @@ 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 +.REQ .pn \[+-]N Next page number -.argument N . +.IR 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 +Change to previous page offset. +. +The current page offset is available in .register .o . . -.REQ .po \(+-N +.REQ .po \[+-]N Page offset -.argument N . +.IR N . . .REQ .ps Return to previous point-size. -.REQ .ps \(+-N +.REQ .ps \[+-]N Point size; same as -.esc[arg] s \(+-N . +.esc[] s \[+-]N . . .REQ .psbb filename Get the bounding box of a PostScript image -.argument filename . +.IR filename . . .REQ .pso command This behaves like the -.request .so +.request so request except that input comes from the standard output of -.argument command . +.IR 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... +.REQ .pvs +Change to previous post-vertical line spacing. +. +.REQ .pvs \[+-]N +Change post-vertical line spacing according to +.I \[+-]N +(default scaling indicator\~\c +.scaleindicator p ). +. +.REQ .rchar c1 c2 .\|.\|.\& Remove the definitions of characters -.argument c1 , -.argument c2 , -.argument ... +.IR c1 , +.IR c2 , +.I .\|.\|.\& . .REQ .rd prompt Read insertion. @@ -1535,36 +1941,36 @@ Return from a macro. . .REQ .rj n Right justify the next -.argument n +.I n input lines. . .REQ .rm name Remove request, macro, or string -.argument name . +.IR name . . .REQ .rn old new Rename request, macro, or string -.argument old +.I old to -.argument new . +.IR new . . .REQ .rnn reg1 reg2 Rename register -.argument reg1 +.I reg1 to -.argument reg2 . +.IR reg2 . . .REQ .rr register Remove -.argument register . +.IR register . . .REQ .rs Restore spacing; turn no-space mode off. . -.REQ .rt \(+-N +.REQ .rt \[+-]N Return .I (upward only) -to marked vertical place (default scale indicator\ \c +to marked vertical place (default scaling indicator\~\c .scaleindicator v ). . .REQ .shc @@ -1573,13 +1979,20 @@ Reset soft hyphen character to . .REQ .shc c Set the soft hyphen character to -.argument c . +.IR c . . .REQ .shift n In a macro, shift the arguments by -.argument n \ \c +.IR n \~\c positions. . +.REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP +Set available font sizes similar to the +.B sizes +command in a +.B DESC +file. +. .REQ .so filename Include source file. . @@ -1588,43 +2001,53 @@ Skip one line vertically. . .REQ .sp N Space vertical distance -.argument N +.I N up or down according to sign of -.argument N -(default scaling indicator\ \c +.I N +(default scaling indicator\~\c .scaleindicator v ). . -.REQ .special s1 s2 ... +.REQ .special s1 s2 .\|.\|.\& Fonts -.argument s1 , -.argument s2 , -etc. are special and will be searched for characters not in the current font. +.IR s1 , +.IR s2 , +etc.\& are special and will be searched for characters not in the +current font. +. +.REQ .spreadwarn +Toggle the spread warning on and off without changing its value. +. +.REQ .spreadwarn limit +Emit a warning if each space in an output line is widened by +.I limit +or more (default scaling indicator\~\c +.scaleindicator m ). . .REQ .ss N Space-character size set to -.argument N /12 +.IR N /12 of the spacewidth in the current font. . .REQ .ss N M Space-character size set to -.argterm N /12 +.IR N /12 and sentence space size set to -.argterm M /12 -of the spacewidth in the current font (\f(CR\(eq1/3 em\fP). +.IR M /12 +of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]). . .REQ .sty n style Associate -.argument style +.I style with font position -.argument n . +.IR n . . -.REQ .substring register n1 n2 -Replace the string in -.argument register +.REQ .substring xx n1 n2 +Replace the string named +.I xx with the substring defined by the indices -.argument n1 +.I n1 and -.argument n2 . +.IR n2 . . .REQ .sv Save @@ -1633,36 +2056,36 @@ of vertical space. . .REQ .sv N Save the vertical distance -.argument N +.I N for later output with -.request .os +.request os request. . .REQ .sy command-line Execute program -.argument command-line . +.IR command-line . . .REQ ".ta T" N Set tabs after every position that is a multiple of -.argument N -(default scaling indicator\ \c +.I N +(default scaling indicator\~\c .scaleindicator m ). -.REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn +.REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn Set tabs at positions -.argument n1 , -.argument n2 , -\&..., -.argument nn , +.IR n1 , +.IR n2 , +.Text .\|.\|., +.IR nn , then set tabs at -.argument nn + r1 , -.argument nn + r2 , -\&..., -.argument nn + rn , +.IR nn + r1 , +.IR nn + r2 , +.Text .\|.\|., +.IR nn + rn , then at -.argument nn + rn + r1 , -.argument nn + rn + r2 , -\&..., -.argument nn + rn + rn , +.IR nn + rn + r1 , +.IR nn + rn + r2 , +.Text .\|.\|., +.IR nn + rn + rn , and so on. . .\".REQ .tar @@ -1674,32 +2097,33 @@ and so on. .REQ .tc Remove tab repition character. .REQ .tc c -Set tab repetition character to\ \c -.argument c . +Set tab repetition character to\~\c +.IR c . . -.REQ .ti \(+-N -Temporary indent next line (default scaling indicator\ \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 . +.IR font . . -.REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP +.REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[] Three-part title. . .REQ .tm anything Print -.argument anything +.I anything on terminal (UNIX standard message output). . .REQ .tm1 anything Print -.argument anything -on terminal (UNIX standard message output), allowing leading whitespace if -.argument anything +.I anything +on terminal (UNIX standard message output), allowing leading +whitespace if +.I anything starts with -.character \(dq +.character \[dq] (which will be stripped off). . .REQ .tmc anything @@ -1707,23 +2131,31 @@ Similar to .request .tm1 without emitting a final newline. . -.REQ .tr abcd.... +.REQ .tr abcd.\|.\|.\& Translate -.argument a +.I a to -.argument b , -.argument c +.IR b , +.I c to -.argument d , -etc. on output. +.IR d , +etc.\& on output. . .REQ .trf filename Transparently output the contents of file -.argument filename . +.IR filename . +. +.REQ .trin abcd.\|.\|.\& +This is the same as the +.request tr +request except that the +.B asciify +request will use the character code (if any) before the character +translation. . -.REQ .trnt abcd.... +.REQ .trnt abcd.\|.\|.\& This is the same as the -.request .tr +.request tr request except that the translations do not apply to text that is transparently throughput into a diversion with .esc ! . @@ -1737,63 +2169,88 @@ false. . .REQ .uf font Underline font set to -.argument font +.I font (to be switched to by .request .ul ). . .REQ .ul N Underline (italicize in troff) -.argument N +.I N input lines. . .REQ .unformat diversion Unformat space characters and tabs, preserving font information in -.argument diversion . +.IR diversion . .REQ .vpt n Enable vertical position traps if -.argument n +.I 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 . +.REQ .vs \[+-]N +Set vertical base line spacing according to +.I \[+-]N +(default scaling indicator\~\c +.scaleindicator p ). Default value is .scalednumber 12 p . . .REQ .warn n Set warnings code to -.argument n . +.IR n . +. +.REQ .warnscale si +Set scaling indicator used in warnings to +.IR si . +. +.REQ .wh N +Remove (first) trap at position +.IR N . . .REQ .wh N trap Set location trap; negative means from page bottom. . .REQ .while cond anything While condition -.argument cond +.I cond is true, accept -.argument anything +.I anything as input. . .REQ .write stream anything Write -.argument anything +.I anything +to the stream named +.IR stream . +. +.REQ .writec stream anything +Similar to +.request .write +without emitting a final newline. +. +.REQ .writem stream xx +Write contents of macro or string +.I xx to the stream named -.argument stream . +.IR stream . . .PD -.LP +. +.P 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 +. +.P +Preprocessor macros are easy to be recognized. +. +They enclose their code into a pair of characteristic macros. +. +.P .TS box, center, tab (@); c | c | c @@ -1805,138 +2262,163 @@ grap@.G1@.G2 grn@.GS@.GE pic@.PS@.PE refer@.R1@.R2 -soelim@\fInone@\fInone +soelim@\f[I]none@\f[I]none tbl@.TS@.TE .TE -.LP +.P +. . .\" -------------------------------------------------------------------- .SH "ESCAPE SEQUENCES" .\" -------------------------------------------------------------------- . -Escape sequences are in-line language elements usually introduced by -a backslash -.'char \(rs +Escape sequences are in-line language elements usually introduced by a +backslash +.squoted_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 +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. +. +.P +This is done by enclosing names (escape name and arguments consisting +of a variable name) by a pair of brackets +.BI \[lB] name \[rB] +and constant arguments (number expressions and characters) by +apostrophes (ASCII 0x27) like +.BI \[cq] constant \[cq] \f[R]. +. +.P There are abbreviations for short names. -Two character escape names can be specified by an opening parenthesis like -.esc( xy +. +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 [ +.squoted_char [ and -.'char ( +.squoted_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( "" +.esc c . +. +.P +Constant arguments of length\~1 can omit the marker apostrophes, too, +but there is no two-character analogue. +. +.P +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 +. +Escapes sequences with names of more than two characters +.esc[] "" name +denote user defined named characters (see the +.request char request). . +. .\" -------------------------------------------------------------------- -.SS "SINGLE CHARACTER ESCAPES" +.SS "Single Character Escapes" .\" -------------------------------------------------------------------- . .PD 0 . .\" --------- comments --------- . -.ESC \(dq +.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. +.esc \[dq] +except that the terminating newline is ignored as well. . .\" --------- strings --------- . -.ESC * s +.ESC *\f[I]s\f[] The string stored in the string variable with 1-character name -.argument s . +.IR s . . -.ESC *( st +.ESC *(\f[I]st\f[] The string stored in the string variable with 2-character name -.argument st . +.IR st . . -.ESC[] * stringvar +.ESC[] * "stringvar arg1 arg2 .\|.\|." The string stored in the string variable with arbitrary length name -.argument stringvar . +.IR stringvar , +taking +.IR arg1 , +.IR arg2 , +.I .\|.\|.\& +as arguments. . .\" --------- macro arguments --------- . .ESC $0 -The name by which the current macro was invoked. The -.request .als +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 , +Macro or string argument with 1-place number +.IR x , where -.argument x +.I x is a digit between 1 and 9. . .ESC $( xy -Macro argument with 2-digit number -.argument xy . +Macro or string argument with 2-digit number +.IR xy . . .ESC[] $ nexp -Macro argument with number -.argument nexp , +Macro or string argument with number +.IR nexp , where -.argument nexp -is a numerical expression evaluating to an integer \(>=1. +.I nexp +is a numerical expression evaluating to an integer \[>=]1. . .ESC $* -In a macro, the concatenation of all the arguments separated by spaces. +In a macro or string, 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. +In a macro or string, the concatenation of all the arguments with each +surrounded by double quotes, and separated by spaces. . .\" --------- escaped characters --------- . -.ESC \(rs +.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 e , +or even better +.esc [rs] , +to be independent from the current escape character. . -.ESC \(cq -The acute accent \(aa; same as -.esc( aa . +.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 . +The grave accent \[ga]; same as +.esc (ga . Unescaped: left quote, backquote (ASCII 0x60). . .ESC \- @@ -1951,12 +2433,13 @@ Default optional hyphenation character. .ESC ! Transparent line indicator. . -.ESC ? anything\fB?\fP +.ESC? anything In a diversion, this will transparently embed -.argument anything +.I anything in the diversion. -.argument anything +.I anything is read in copy mode. +. See also the escape sequences .esc ! and @@ -2006,7 +2489,7 @@ Inserts a zero-width break point (similar to .esc % but without a soft hyphen character). . -.ESC \& newline +.ESC "" newline Ignored newline, for continuation lines. . .\" --------- structuring --------- @@ -2019,15 +2502,15 @@ End conditional input. . .\" --------- longer escape names --------- . -.ESC ( st +.ESC ( sc The special character with 2-character name -.argument st , +.IR sc , see section -.BR "SPECIAL CHARACTERS" . +.BR "Special Characters" . . -.ESC[] \& name +.ESC[] "" name The named character with arbitrary length name -.argument name . +.IR name . . .\" --------- alphabetical escapes --------- . @@ -2036,34 +2519,27 @@ Non-interpreted leader character. . .ESCq A anything If -.argument anything +.I anything is acceptable as a name of a string, macro, diversion, register, -environment or font it expands to -.number 1 , -and -.number 0 -otherwise. +environment or font it expands to\~1, and to\~0 otherwise. . -.ESCq b abc... +.ESCq b abc.\|.\|.\& Bracket building function. . .ESCq B anything If -.argument anything -is acceptable as a valid numeric expression it expands to -.number 1 , -and -.number 0 -otherwise. +.I anything +is acceptable as a valid numeric expression it expands to\~1, and +to\~0 otherwise. . .ESC c Interrupt text processing. . .ESCq C char The character called -.argument char ; +.IR char ; same as -.esc[] char , +.esc[] "" char , but compatible to other roff versions. . .ESC d @@ -2071,7 +2547,7 @@ 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 ; +.IR charseq ; see groff info file for details. . .ESC e @@ -2082,114 +2558,174 @@ 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 . +.IR F . +. +.ESC fP +Switch back to previous font. . .ESC f( fo -Change to font with 2-characer name or 2-digit number -.argument fo . +Change to font with 2-character name or 2-digit number +.IR fo . . .ESC[] f font Change to font with arbitrary length name or number expression -.argument font . +.IR font . +. +.ESC[] f "" +Switch back to previous font. +. +.ESC F f +Change to font family with 1-character name +.IR f . +. +.ESC F( fm +Change to font family with 2-character name +.IR fm . +. +.ESC[] F fam +Change to font family with arbitrary length name +.IR fam . +. +.ESC[] F "" +Switch back to previous font family. . .ESC[] g reg Return format of register with name -.argument reg +.I reg suitable for .request .af . +. Alternative forms -.esc(arg g xy +.escarg g( xy and .escarg g x . . .ESCq h N Local horizontal motion; move right -.argument N +.I N (left if negative). . .ESCq H N Set height of current font to -.argument N . +.IR N . . .ESC[] k reg Mark horizontal input place in register with arbitrary length name -.argument reg . +.IR reg . Alternative forms -.esc(arg k xy +.escarg k( xy and .escarg k x . . .ESCq l Nc Horizontal line drawing function (optionally using character -.argument c ). +.IR c ). . .ESCq L Nc Vertical line drawing function (optionally using character -.argument c ). +.IR c ). +. +.ESC[] m color +Change to color +.IR color . +. +Alternative forms +.escarg m( co +and +.escarg m c . +. +.ESC[] m "" +Switch back to previous color. +. +.ESC[] M color +Change filling color for closed drawn objects to color +.IR color . +. +Alternative forms +.escarg M( co +and +.escarg M c . +. +.ESC[] M "" +Switch to previous fill color. . .ESC n r -The numerical value stored in the register variable with the 1-character -name -.argument r . +The numerical value stored in the register variable with the +1-character name +.IR r . . .ESC n( re -The numerical value stored in the register variable with the 2-character -name -.argument re . +The numerical value stored in the register variable with the +2-character name +.IR re . . .ESC[] n reg The numerical value stored in the register variable with arbitrary -lenght name -.argument reg . +length name +.IR 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 +.I 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... +.ESCq o abc.\|.\|.\& Overstrike characters -.argument a , -.argument b , -.argument c , +.IR a , +.IR b , +.IR c , etc. . +.ESC O 0 +Disable glyph output. +. +Mainly for internal use. +. +.ESC O 1 +Enable glyph output. +. +Mainly for internal use. +. .ESC p Break and spread output line. . .ESC r Reverse 1\ em vertical motion (reverse line in nroff). . -.ESCq R name \(+-n +.ESCq R "name\~\[+-]n" The same as .request .nr -.argument name -.argument \(+-n . +.I name +.IR \[+-]n . . -.ESC[] s \(+-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 +scaled points. +. +Note the alternative forms +.BI \[rs]s \[+-] [ N ]\c , -.escarg s \(+-x . +.BI \[rs]s' \[+-]N '\c +.Text , +.BI \[rs]s \[+-] ' N '\c +.Text , +.escarg s( \[+-]xy\c +.Text , +.BI \[rs]s \[+-] ( xy\c +.Text , +.escarg s \[+-]x . Same as -.request .ps +.request ps request. . .ESCq S N Slant output -.argument N +.I N degrees. . .ESC t @@ -2200,55 +2736,58 @@ Reverse (up) 1/2 em vertical motion (1/2 line in nroff). . .ESCq v N Local vertical motion; move down -.argument N +.I N (up if negative). . .ESC[] V env The contents of the environment variable -.argument env . +.IR env . +. Alternative forms -.esc(arg V xy +.escarg V( xy and .escarg V x . . .ESCq w string The width of the character sequence -.argument string . +.IR string . . .ESCq x N Extra line-space function (negative before, positive after). . .ESCq X string Output -.argument string +.I string as device control function. . .ESC[] Y name Output string variable or macro -.argument name +.I name uninterpreted as device control function. +. Alternative forms -.esc(arg Y xy +.escarg Y( xy and .escarg Y x . . .ESC z c Print -.argument c +.I c with zero width (without spacing). . .ESCq Z anything Print -.argument anything +.I anything and then restore the horizontal and vertical position; -.argument anything +.I anything may not contain tabs or leaders. +. .PD -.LP +.P The escape sequences .esc e , .esc . , -.esc \(dq , +.esc \[dq] , .esc $ , .esc * , .esc a , @@ -2258,669 +2797,643 @@ The escape sequences and .escarg \& newline are interpreted in copy mode. -.LP +. +.P Escape sequences starting with .esc ( or .esc [ do not represent single character escape sequences, but introduce escape names with two or more characters. -.LP +. +.P 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" +.SS "Special Characters" .\" -------------------------------------------------------------------- -Common special characters are predefined by escape sequences of the form -.(esc \fP\f(CIxy +. +Common special characters are predefined by escape sequences of the +form +.BI \[rs]( xy with characters -.argument x +.I x and -.argument y . +.IR 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 +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 +.P .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 +.ESC (bu +Bullet sign +.ESC (co +Copyright +.ESC (ct +Cent +.ESC (dd +Double dagger +.ESC (de +Degree +.ESC (dg +Dagger +.ESC (rs +Printable double quote +.ESC (em +Em-dash +.ESC (hy +Hyphen +.ESC (rg +Registered sign +.ESC (rs +Printable backslash character +.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 . +. +.\" -------------------------------------------------------------------- +.SS "Strings" +.\" -------------------------------------------------------------------- +. +Strings are defined by the +.request ds +request and can be retrieved by the +.esc * +escape sequence. +. +.P +Strings share their name space with macros. +. +So strings and macros without arguments are roughly equivalent; it is +possible to call a string like a macro and vice-versa, but this often +leads to unpredictable results. +. +The following strings are predefined in groff. +. +.STRING .T +The name of the current output device as specified by the +.option -T +command line option. +. +. .\" -------------------------------------------------------------------- .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 +. +.P Each register is given a name. Arbitrary registers can be defined and set with the request -.request .nr -.argument register . -.LP +.request nr +.IR register . +. +.P The value stored in a register can be retrieved by the escape sequences introduced by .esc n . -.LP +. +.P Most useful are predefined registers. +. In the following the notation -.argument name +.I 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[] +.esc[] n "" decoration is not part of the register name. . +. .\" -------------------------------------------------------------------- -.SS "READ-ONLY REGISTERS" +.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 +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. +. +.P .PD 0 -.REG .$ Number of arguments in the current macro. +. +.REG .$ +Number of arguments in the current macro or string. +. .REG .a Post-line extra line-space most recently utilized using -.escarg x 'N' . +.escq x N . +. .REG .A -Set to -.number 1 -in +Set to\~1 in .B troff if option .B \-A -is used; always -.number 1 -in +is used; always\~1 in .BR nroff . -.REG .c Current input line number. -.REG .C 1 if compatibility mode is in effect, 0 otherwise. +. +.REG .c +Current input line number. +. +.REG .C +1\~if compatibility mode is in effect, 0\~otherwise. +. .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 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 .color +1\~if colors are enabled, 0\~otherwise. +. .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 .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 .fn +The current (internal) real font name (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 .H Available horizontal resolution in basic units. +. +.REG .h +Text base-line high-water mark on current page or diversion. +. +.REG .H +Available horizontal resolution in basic units. +. .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 hlm request. +. .REG .hy The current hyphenation flags (as set by the -.request .hy +.request hy request). +. .REG .hym The current hyphenation margin (as set by the -.request .hym +.request hym request). +. .REG .hys The current hyphenation space (as set by the -.request .hys +.request hys request). -.REG .i Current ident. -.REG .in The indent that applies to the current output line. +. +.REG .i +Current ident. +. +.REG .in +The indent that applies to the current output line. +. .REG .int Positive if last output line contains .esc c . +. .REG .kern -.number 1 -if pairwise kerning is enabled, -.number 0 -otherwise. -.REG .l Current line length. +1\~if pairwise kerning is enabled, 0\~otherwise. +. +.REG .l +Current line length. +. .REG .lg The current ligature mode (as set by the -.request .lg +.request lg request). +. .REG .linetabs The current line-tabs mode (as set by the -.request .linetabs +.request linetabs request). -.REG .ll The line length that applies to the current output line. +. +.REG .ll +The line length that applies to the current output line. +. .REG .lt The title length (as set by the -.request .lt +.request lt request). -.REG .n Length of text portion on previous output line. +. +.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 ne request that caused a trap to be sprung. +. Useful in conjunction with .register .trunc . +. .REG .ns -.number 1 -if in no-space mode, -.number 0 -otherwise. -.REG .o Current page offset. -.REG .p Current page length. +1\~if in no-space mode, 0\~otherwise. +. +.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 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 .ps +The current pointsize in scaled points. +. +.REG .psr +The last-requested pointsize in scaled points. +. +.REG .pvs +The current post-vertical line spacing. +. .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 .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 .t +Distance to the next trap. +. .REG .T -Set to -.number 1 +Set to\~1 if option .B \-T is used. +. .REG .tabs -A string representation of the current tab settings suitable for use as -an argument to the -.request .ta +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 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. +. +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 ss request. +. .REG .sss The value of the parameters set by the second argument of the -.request .ss +.request ss request. -.REG .u Equal to 1 bin fill mode and 0 in nofill mode. -.REG .v Current vertical line spacing. -.REG .V Available vertical resolution in basic units. +. +.REG .u +Equal to 1 bin fill mode and 0 in nofill mode. +. +.REG .v +Current vertical line spacing. +. +.REG .V +Available vertical resolution in basic units. +. .REG .vpt -.number 1 -if vertical position traps are enabled, -.number 0 -otherwise. -.REG .w Width of previous character. +1\~ if vertical position traps are enabled, 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 .x +The major version number. +. +.REG .y +The minor version number. +. +.REG .Y +The revision number of groff. +. +.REG .z +Name of current diversion. .PD . +. .\" -------------------------------------------------------------------- -.SS "WRITABLE REGISTERS" +.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 +. +.P .PD 0 -.REG % Current page number. -.REG c. Current input line number. -.REG ct Character type (set by width function +.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 dn Height 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 dl +Maximal width of last completed diversion. +. +.REG dn +Height of last completed diversion. +. +.REG dw +Current day of week (1-7). +. +.REG dy +Current day of month (1-31). +. +.REG hours +The number of hours past midnight. +. +Initialized at start-up. +. +.REG hp +Current horizontal position at input line. +. .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 ln Output line number. -.REG mo Current month (1-12). -.REG nl Vertical position of last printed text base-line. -.REG rsb Like +. +.REG ln +Output line number. +. +.REG minutes +The number of minutes after the hour. +. +Initialized at start-up. +. +.REG mo +Current month (1-12). +. +.REG nl +Vertical position of last printed text base-line. +. +.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 seconds +The number of seconds after the minute. +. +Initialized at start-up. +. .REG skw Right skip width from the center of the last character in the .esc w argument. +. .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 +. +If \[<=]0 there is no limit, i.e., recursion can continue until virtual memory is exhausted. +. .REG ssc -The amount of horizontal space (possibly negative) that should be added -to the last character before a subscript (generated by width function +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 systat The return value of the .I system() function executed by the last -.request .sy +.request sy request. +. .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 ). -.REG year The current year (year 2000 compliant). +. +.REG year +The current year (year 2000 compliant). +. .REG yr -Current year minus 1900. For Y2K compliance use register +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. +. +The differences of the groff language in comparison to classical troff +as defined by +.I [CSTR\~#54] +are documented in +.BR groff_diff (@MAN7EXT@). +. +.P +The groff system provides a compatibility mode, see +.BR groff (@MAN1EXT@) +on how to invoke this. +. . .\" -------------------------------------------------------------------- .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@). +. +Report bugs to the +.MTO bug-groff@gnu.org "groff bug mailing list" . +Include a complete, self-contained example that will allow the bug to +be reproduced, and say which version of groff you are using. +. . .\" -------------------------------------------------------------------- -.SH AUTHOR +.SH AUTHORS .\" -------------------------------------------------------------------- -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. +. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.MTO bwarken@mayn.de "Bernd Warken" ; +it is maintained by +.MTO wl@gnu.org "Werner Lemberg" . +. . .\" -------------------------------------------------------------------- .SH "SEE ALSO" .\" -------------------------------------------------------------------- +. +.P 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 +. +Besides the gory details, it contains many examples. +. +.TP .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/ . +the usage of the groff program and pointers to the documentation and +availability of the groff system. +. +.TP +.BR groff_diff (@MAN7EXT@) +the differences of the groff language as compared to classical roff. +. +This is the authoritative document for the predefined language +elements that are specific to groff. +. +.TP +.BR groff_char (@MAN7EXT@) +the predefined groff characters (glyphs). +. +.TP +.BR groff_font (@MAN5EXT@) +the specification of fonts and the DESC file. +. +.TP +.BR roff (@MAN7EXT@) +the history of roff, the common parts shared by all roff systems, and +pointers to further documentation. +. +.TP +.I [CSTR\~#54] +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \ + "Nroff/\:Troff User's Manual by Osanna & Kernighan" +\[em] the bible for classical troff. +. +. +.\" -------------------------------------------------------------------- +.\" Emacs Setup +.\" -------------------------------------------------------------------- . .\" Local Variables: .\" mode: nroff diff --git a/contrib/groff/man/groff_char.man b/contrib/groff/man/groff_char.man index 74f442d..be73941 100644 --- a/contrib/groff/man/groff_char.man +++ b/contrib/groff/man/groff_char.man @@ -1,150 +1,385 @@ +.TH GROFF_CHAR @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_char \- groff character names +.SH DESCRIPTION +.\" The lines above were designed to satisfy `apropos'. +. +.\" For best results, format this document with `groff' (GNU roff). +. +. +.\" -------------------------------------------------------------------- +.\" Legalize +.\" -------------------------------------------------------------------- +. .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +groff_char(7) + +This file is part of groff (GNU roff). -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +File position: <groff_src_top>/man/groff_char.man +Last update: 20 July 2002 -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. +Copyright (C) 1989-2000, 2001, 2002 Free Software Foundation, Inc. +written by Werner Lemberg <wl@gnu.org> +with additions by Bernd Warken <bwarken@mayn.de> -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English. +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. .. -.\" For best results, print this with groff. +. +.\" -------------------------------------------------------------------- +.\" Setup Part 1 +.\" -------------------------------------------------------------------- +. +.\" groff only +.if \n(.g .mso www.tmac +.\".if \n(.g .ne 2v +.\".if \n(.g .sv 2v +. .ds aq \(aq -.ie !\n(.g .if '\(aq'' .ds aq \' -.el \{\ -. tr \(aq\(aq -. if !c\(aq .ds aq \' -.\} +. +.\" non-groff +.if !\n(.g .if '\(aq'' .ds aq \' +. +.\" groff +.if !\n(.g .ig +. tr \[aq]\[aq] +. if !c\[aq] \ +. ds aq \' +. \" This is very special. The standard devdvi fonts don't have a +. \" real `aq' glyph; it is defined with .char to be ' instead. +. \" The .tr request below in the definition of the C macro maps +. \" the apostrophe ' onto the `aq' glyph which would cause a +. \" recursive loop. gtroff prevents this within the .char +. \" request, trying to access glyph `aq' directly from the font. +. \" Consequently, we get a warning, and nothing is printed. +. \" +. \" The following line prevents this. +. if '\*[.T]'dvi' \ +. if !r ECFONTS \ +. ds aq \' +. \" The same is true for X +. ds dev \*[.T] +. substring dev 0 0 +. if '\*[dev]'X' .ds aq \' +. ig +.. +.\" -------------------------------------------------------------------- +.\" .Ac accented-char accent char (groff) .if !\n(.g .ig -.\" .Ac accented-char accent char .de Ac -.char \\$1 \\$3\ -\k[acc]\ -\h'(u;-\w'\\$2'-\w'\\$3'/2+\\\\n[skw]+(\w'x'*0)-\\\\n[skw])'\ -\v'(u;\w'x'*0+\\\\n[rst]+(\w'\\$3'*0)-\\\\n[rst])'\ -\\$2\ -\v'(u;\w'x'*0-\\\\n[rst]+(\w'\\$3'*0)+\\\\n[rst])'\ -\h'|\\\\n[acc]u' -.hcode \\$1\\$3 +. char \\$1 \\$3\ +\k[acc]\h'(u;-\w'\\$2'-\w'\\$3'/2+\\\\n[skw]+(\w'x'*0)-\\\\n[skw])'\ +\v'(u;\w'x'*0+\\\\n[rst]+(\w'\\$3'*0)-\\\\n[rst])'\\$2\ +\v'(u;\w'x'*0-\\\\n[rst]+(\w'\\$3'*0)+\\\\n[rst])'\h'|\\\\n[acc]u' +. hcode \\$1 \\$3 .. .Ac \(vc \(ah c .Ac \(vC \(ah C -.TH GROFF_CHAR @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" -.SH NAME -groff_char \- groff character names -.SH DESCRIPTION -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 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 -input with a single character, and gives the ISO Latin-1 code -of that input character. -The -.I "PostScript name\" -column gives the usual PostScript name of the output character. -.LP -The ISO Latin-1 no-break space (code 0240 octal) is equivalent to -.BR \e (space). -All other ISO Latin-1 characters print as themselves with the following -exceptions: -.B \` -prints as `, -.B \*(aq -prints as '; -the corresponding ISO Latin-1 characters can be obtained with -.B \e` -and -.BR \e(aq . -The ISO Latin-1 `Hyphen, Minus Sign' (code 45) prints as a hyphen; -a minus sign can be obtained with -.BR \e- . -The ISO Latin-1 `Tilde' (code 126) prints as ~; -the larger glyph can be obtained with -.BR \e(ti . -The ISO Latin-1 `Circumflex Accent' (code 94) prints as ^; -a larger glyph can be obtained with -.BR \e(ha . -.sp -'nf +. +. +.\" -------------------------------------------------------------------- +.\" Setup Part 2 +.\" -------------------------------------------------------------------- +. .nr Sp 3n -.ta \w'\fIOutput'u+\n(Spu +\w'\fIInput'u+\n(Spu +\w'\fIInput'u+\n(Spu \ -+\w'periodcentered'u+\n(Spu +.ta \w'\fIOutput'u+\n(Spu \ + +\w'\fIInput'u+\n(Spu \ + +\w'\fIInput'u+\n(Spu \ + +\w'periodcentered'u+\n(Spu +. +.\" -------------------------------------------------------------------- .de C0 -.C \\$1 "" \\$1 \\$2 "\\$3" +. C \\$1 "" \\$1 \\$2 "\\$3" .. +. +.\" -------------------------------------------------------------------- .de C1 -.C \e\\$1 "" \\\\\\$1 \\$2 "\\$3" +. C \e\\$1 "" \\\\\\$1 \\$2 "\\$3" .. +. +.\" -------------------------------------------------------------------- +.\" .C2/.CN (groff) +.if !\n(.g .ig +.de CN +. C \e[\\$1] "" \[\\$1] \\$2 "\\$3" +.. +.if \n(.g .als C2 CN +. +.\" -------------------------------------------------------------------- +.\" .C2 (non-groff) +.if \n(.g .ig .de C2 -.C \e(\\$1 "" \\(\\$1 \\$2 "\\$3" +. C \e(\\$1 "" \\(\\$1 \\$2 "\\$3" .. +. +.\" -------------------------------------------------------------------- +.\" .CD (groff) .if !\n(.g .ig .de CD -.C \[char\\$1] \\$1 \[char\\$1] \\$2 "\\$3" +. C \[char\\$1] \\$1 \[char\\$1] \\$2 "\\$3" .. -.do fspecial CR R +. +.\" -------------------------------------------------------------------- +.do if !r ECFONTS .do fspecial CR R +. +.\" -------------------------------------------------------------------- .\" input-name decimal-code output-name ps-name description +.\" .C (groff) .if !\n(.g .ig .de C -.if c\\$3 \{\ -.ft CR -.tr `\`'\*(aq -.in 0 -.di CH -\&\\$1 -.br -.di -.in -.ft -.ds CH \\*(CH\ -.tr ``'' -\&\\$3\t\\*(CH\t\\$2\t\\$4\t\\$5 -.\} +. if c\\$3 \{\ +. ft CR +. tr `\`'\*[aq] +. in 0 +. di CH +. nop \&\\$1 +. br +. di +. in +. ft +. ds CH \\*[CH]\ +. tr ``'' +. nop \&\\$3\t\\*[CH]\t\\$2\t\\$4\t\\$5 +. \} .. +. +.\" -------------------------------------------------------------------- +.\" .C (non-groff) .if \n(.g .ig .de C -.if !'\\$3'' \{\ -.ft B -.tr `\`'\*(aq -.in 0 -.di CH +. if !'\\$3'' \{\ +. ft B +. tr `\`'\*(aq +. in 0 +. di CH \&\\$1 -.br -.di -.in -.ft -.ds CH \\*(CH\ -.tr ``'' +. br +. di +. in +. ft +. ds CH \\*(CH\ +. tr ``'' \&\\$3\t\\*(CH\t\\$2\t\\$4\t\\$5 -.\} +. \} .. -.if !\n[cR] .wh \n(nlu+\n(.tu-\n(.Vu Fo +. +.\" -------------------------------------------------------------------- .de Fo 'bp .He .. +. +.\" -------------------------------------------------------------------- .de He +.P +'nf .ft I Output Input Input PostScript Notes name code name .ft -.LP -'nf +.P .. +. +.\" -------------------------------------------------------------------- +.\" .SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +This manual page lists the standard +.B groff +input characters. +. +The output characters in this document will look different depending +on which output device was chosen (with option +.B \-T +for the +.BR man (1) +program or the roff formatter). +. +Only the characters that are available for the device that +is being used to print or view this manual page will be +.ie \n(.g displayed (the device currently used is `\*(.T'). +.el displayed. +. +. +.P +In the actual version, +.B groff +provides only 8-bit characters for direct input and named characters +for further glyphs. +. +On ASCII platforms, character codes in the range 0 to 127 (decimal) +represent the usual 7-bit ASCII characters, while codes between 127 +and 255 are interpreted as the corresponding characters in the +.I Latin-1 +.RI ( ISO-8859-1 ) +code set. +. +On EBCDIC platforms, only the code page +.B cp1047 +is supported (which contains the same characters as Latin-1). +. +It is rather straightforward (for the experienced user) to set up other +8bit encodings like +.IR Latin-2 ; +since +.B groff +will use Unicode in the next major version, no additional encodings +are provided. +. +. +.P +All roff systems provide the concept of named characters. +. +In traditional roff systems, only names of length\ 2 were used, while +groff also provides support for longer names. +. +It is strongly suggested that only named characters are used for all +characters outside of the 7-bit ASCII range. +. +. +.P +Some of the predefined groff escape sequences (with names of length\ 1) +also produce single characters; these exist for historical reasons or +are printable versions of syntactical characters. +. +They include +.BR \e\e , +.BR \e' , +.BR \e` , +.BR \e- , +.BR \e. , +and +.BR \ee ; +see +.BR groff (@MAN7EXT@). +. +. +.P +In groff, all of these different types of characters can be tested +positively with the +.B .if\ c +conditional. +. +. +.\" -------------------------------------------------------------------- +.SH REFERENCE +.\" -------------------------------------------------------------------- +. +In this section, the characters in groff are specified in tabular +form. +. +The meaning of the columns is as follows. +. +. +.TP +.I "Output" +shows how the character is printed for the current device; although +this can have quite a different shape on other devices, it always +represents the same glyph. +. +. +.TP +.I "Input name" +specifies how the character is input either directly by a key on the +keyboard, or by a groff escape sequence. +. +. +.TP +.I "Input code" +applies to characters which can be input with a single character, and +gives the ISO Latin-1 decimal code of that input character. +. +Note that this code is equivalent to the lowest 256 Unicode characters; +(including 7-bit ASCII in the range 0 to\ 127). +. +. +.TP +.I "PostScript name" +gives the usual PostScript name of the output character. +. +. +.\" -------------------------------------------------------------------- +.SS "ASCII Characters" +.\" -------------------------------------------------------------------- +. +These are the basic characters having 7-bit ASCII code values. +. +These are identical to the first 127 characters of the character +standards ISO-8859-1 (Latin-1) and Unicode (range +.IR "C0 Controls and Basic Latin" ). +. +To save space, not every code has an entry in the following because +the following code ranges are well known. +. +.TP +0\-32 +Control characters (print as themselves). +. +.TP +48\-57 +Decimal digits 0 to 9 (print as themselves). +. +.TP +65\-90 +Upper case letters A\-Z (print as themselves). +. +.TP +97\-122 +Lower case letters a\-z (print as themselves). +. +.TP +127 +Control character (prints as itself). +. +.P +The remaining ranges constitute the printable, non-alphanumeric ASCII +characters; only these are listed below. +. +As can be seen in the table below, most of these characters print as +themselves; the only exceptions are the following characters: +. +.TP +.B \` +the ISO Latin-1 `Grave Accent' (code\ 96) prints as `, a left single +quotation mark, +. +.TP +.B \*(aq +the ISO Latin-1 `Apostrophe' (code\ 39) prints as ', a right single +quotation mark; the corresponding ISO Latin-1 characters can be obtained +with +.B \e` +and +.BR \e(aq . +. +.TP +.B - +the ISO Latin-1 `Hyphen, Minus Sign' (code\ 45) prints as a hyphen; a +minus sign can be obtained with +.BR \e- . +. +.TP +.B ~ +the ISO Latin-1 `Tilde' (code\ 126); a larger glyph can be obtained +with +.BR \e(ti . +. +.TP +.B ^ +the ISO Latin-1 `Circumflex Accent' (code\ 94); a larger glyph can be +obtained with +.BR \e(ha . +. +. +.P +.if !\n[cR] .wh \n(nlu+\n(.tu-\n(.Vu Fo .He .CD 33 exclam .CD 34 quotedbl @@ -178,7 +413,60 @@ Output Input Input PostScript Notes .CD 124 bar .CD 125 braceright .CD 126 tilde "tilde accent" -.CD 161 exclamdown +.ch Fo +. +. +.\" -------------------------------------------------------------------- +.SS "Latin-1 Special Characters" +.\" -------------------------------------------------------------------- +. +These characters have character codes between 128 and\ 255. +. +They are interpreted as characters according to the +.I Latin-1 +.RI ( iso-8859-1 ) +code set, being identical to the Unicode range +.IR "C1 Controls and Latin-1 Supplement" . +. +.TP +128\-159 +. +the C1 Controls; they print as themselves, but the effect is mostly +undefined. +. +.TP +160 +. +the ISO Latin-1 +.I no-break space +is mapped to +.BR `\e\ ' , +the escaped space character. +. +.TP +173 +. +the soft hyphen control character (prints as itself). +. +groff never use this character for output (thus it is omitted in the table +below); the input character\ 173 is mapped onto +.BR \e% . +. +. +.P +The remaining ranges (161\-172, 174\-255), called the +.I Latin-1 Supplement +in Unicode, are printable characters that print as themselves. +. +Although they can be specified directly with the keyboard on systems +with a Latin-1 code page, it is better to use their named character +equivalent; see next section. +. +. +.P +.if !\n[cR] .wh \n(nlu+\n(.tu-\n(.Vu Fo +.He +.CD 161 exclamdown "inverted exclamation mark" .CD 162 cent .CD 163 sterling .CD 164 currency @@ -190,7 +478,6 @@ Output Input Input PostScript Notes .CD 170 ordfeminine .CD 171 guillemotleft .CD 172 logicalnot -.CD 173 hyphen .CD 174 registered .CD 175 macron .CD 176 degree @@ -198,7 +485,7 @@ Output Input Input PostScript Notes .CD 178 twosuperior .CD 179 threesuperior .CD 180 acute "acute accent" -.CD 181 mu +.CD 181 mu "micro sign" .CD 182 paragraph .CD 183 periodcentered .CD 184 cedilla @@ -273,17 +560,103 @@ Output Input Input PostScript Notes .CD 253 yacute .CD 254 thorn .CD 255 ydieresis +.ch Fo +. +. +.\" -------------------------------------------------------------------- +.SS "Named Characters" +.\" -------------------------------------------------------------------- +. +The named character idiom is the standard way to specify special +characters in roff systems. +. +They can be embedded into the document text by using escape sequences. +. +.BR groff (@MAN7EXT@) +describes how these escape sequences look. +. +The character names can consist of quite arbitrary characters from the +ASCII or Latin-1 code set, not only alphanumeric characters. +. +Here some examples: +. +.TP +.BI \e c +named character having the name +.IR c , +which consists of a single character (length\ 1). +. +.TP +.BI \e( ch +named character having the 2-character name +.IR ch . +. +.TP +.BI \e[ char_name ] +named character having the name +.I char_name +(having length 1, 2, 3, .\|.\|.). +. +. +.P +In groff, each 8bit input character can also referred to by the construct +.BI \en[char n ] +where +.I n +is the decimal code of the character, a number between 0 and\ 255 +without leading zeros. +. +They are mapped onto glyph entities using the +.B .trin +request. +. +Moreover, new character names can be created by the +.B .char +request; see +.BR groff (@MAN7EXT@). +. +. +.P +.\" we don't use the third column +.ta \w'\fIOutput'u+\n(Spu \ + +\w'\fIInput'u+\n(Spu-1n \ + +1n \ + +\w'periodcentered'u+\n(Spu +.if !\n[cR] .wh \n(nlu+\n(.tu-\n(.Vu Fo +.de He +.P +'nf +.ft I +Output Input PostScript Notes + name name +.ft +.P +.. +.He .C2 -D Eth "Icelandic uppercase eth" .C2 Sd eth "Icelandic lowercase eth" .C2 TP Thorn "Icelandic uppercase thorn" .C2 Tp thorn "Icelandic lowercase thorn" +.C2 ss germandbls "German sharp s" +. +.P +.I Ligatures +.C2 ff ff "ff ligature" +.C2 fi fi "fi ligature" +.C2 fl fl "fl ligature" +.C2 Fi ffi "ffi ligature" +.C2 Fl ffl "ffl ligature" .C2 AE AE .C2 ae ae .C2 OE OE .C2 oe oe .C2 IJ IJ "Dutch IJ ligature" .C2 ij ij "Dutch ij ligature" -.C2 ss germandbls +.C2 .i dotlessi "i without a dot (Turkish)" +.C2 .j dotlessj "j without a dot" +. +.P +.I Accented Characters .C2 'A Aacute .C2 'C Cacute .C2 'E Eacute @@ -298,7 +671,7 @@ Output Input Input PostScript Notes .C2 'o oacute .C2 'u uacute .C2 'y yacute -.C2 :A Adieresis +.C2 :A Adieresis "A with umlaut" .C2 :E Edieresis .C2 :I Idieresis .C2 :O Odieresis @@ -344,11 +717,14 @@ Output Input Input PostScript Notes .C2 ,c ccedilla .C2 /L Lslash "Polish L with a slash" .C2 /l lslash "Polish l with a slash" -.C2 /O Oslash -.C2 /o oslash +.C2 /O Oslash "Scandinavic slashed O" +.C2 /o oslash "Scandinavic slashed o" .C2 oA Aring .C2 oa aring -.C2 a" hungarumlaut "Hungarian umlaut" +. +.P +.I Accents +.C2 a" hungarumlaut "Hungarian umlaut"\"" .C2 a- macron "macron or bar accent" .C2 a. dotaccent "dot accent" .C2 a^ circumflex "circumflex accent" @@ -361,98 +737,195 @@ Output Input Input PostScript Notes .C2 ao ring "ring or circle accent" .C2 a~ tilde "tilde accent" .C2 ho ogonek "hook or ogonek accent" -.C2 .i dotlessi "i without a dot" -.C2 .j dotlessj "j without a dot" -.C2 Cs currency "Scandinavian currency sign" -.C2 Do dollar -.C2 Po sterling -.C2 Ye yen -.C2 Fn florin -.C2 ct cent +.C2 ha asciicircum "\s-2ASCII\s+2 circumflex, hat, caret" +.C2 ti asciitilde "\s-2ASCII\s0 tilde, large tilde" +. +.P +.I Quotes +.C2 Bq quotedblbase "low double comma quote" +.C2 bq quotesinglbase "low single comma quote" +.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 Fo guillemotleft .C2 Fc guillemotright .C2 fo guilsinglleft .C2 fc guilsinglright +. +.P +.I Punctuation .C2 r! exclamdown .C2 r? questiondown -.C2 ff ff "ff ligature" -.C2 fi fi "fi ligature" -.C2 fl fl "fl ligature" -.C2 Fi ffi "ffi ligature" -.C2 Fl ffl "ffl ligature" -.C2 OK \& "check mark, tick" -.C2 Of ordfeminine -.C2 Om ordmasculine -.C2 pc periodcentered -.C2 S1 onesuperior -.C2 S2 twosuperior -.C2 S3 threesuperior +.C2 em emdash "em dash" +.C2 en endash "en dash" +.C2 hy hyphen +. +.P +.I Brackets +.C2 lB bracketleft +.C2 rB bracketright +.C2 lC braceleft +.C2 rC braceright +.C2 la angleleft "left angle bracket" +.C2 ra angleright "right angle bracket" +. +.P +.I Arrows .C2 <- arrowleft .C2 -> arrowright .C2 <> arrowboth "horizontal double-headed arrow" .C2 da arrowdown .C2 ua arrowup -.C2 va \& "vertical double-headed arrow" +.C2 va arrowupdn "vertical double-headed arrow" .C2 lA arrowdblleft .C2 rA arrowdblright .C2 hA arrowdblboth "horizontal double-headed double arrow" .C2 dA arrowdbldown .C2 uA arrowdblup .C2 vA \& "vertical double-headed double arrow" +.C2 an arrowhorizex "horizontal arrow extension" +. +.P +.I Lines +.C2 -h hbar +.C2 or bar .C2 ba bar -.C2 bb brokenbar .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 "bar vertical" -.C2 bs bell +.C2 bb brokenbar +.C2 sl slash +.C2 rs backslash +. +.P +.I Text markers .C2 ci circle .C2 bu bullet -.C2 co copyright -.C2 rg registered -.C2 tm trademark .C2 dd daggerdbl "double dagger sign" .C2 dg dagger +.C2 lz lozenge +.C2 sq square .C2 ps paragraph .C2 sc section -.C2 de degree -.C2 em emdash "em dash" -.C2 en endash "en dash" -.C2 %0 perthousand "per thousand, per mille sign" -.C2 12 onehalf -.C2 14 onequarter -.C2 34 threequarters -.C2 f/ fraction "bar for fractions" -.C2 fm minute "footmark, prime" -.C2 sd second -.C2 ha asciicircum "\s-2ASCII\s+2 circumflex, hat, caret" -.C2 ti asciitilde "\s-2ASCII\s0 tilde, large tilde" -.C2 hy hyphen -.C2 lB bracketleft -.C2 rB bracketright -.C2 lC braceleft -.C2 rC braceright -.C2 la angleleft "left angle bracket" -.C2 ra angleright "right angle bracket" .C2 lh handleft .C2 rh handright -.C2 Bq quotedblbase "low double comma quote" -.C2 bq quotesinglbase "low single comma quote" -.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" .C2 sh numbersign -.C2 sl slash -.C2 rs backslash -.C2 sq square +.C2 CR carriagereturn "carriage return symbol" +.C2 OK a19 "check mark, tick" +. +.P +.I Legalize +.C2 co copyright +.C2 rg registered +.C2 tm trademark +.C2 bs bell "AT&T Bell Labs logo (not used in groff)" +. +.P +.I Currency symbols +.C2 Do dollar +.C2 ct cent +.C2 eu \& "official Euro symbol" +.C2 Eu Euro "font-specific Euro glyph variant" +.C2 Ye yen +.C2 Po sterling "British currency sign" +.C2 Cs currency "Scandinavian currency sign" +.C2 Fn florin "Dutch currency sign" +. +.P +.I Units +.C2 de degree +.C2 %0 perthousand "per thousand, per mille sign" +.C2 fm minute "footmark, prime" +.C2 sd second +.C2 mc mu "micro sign" +.C2 Of ordfeminine +.C2 Om ordmasculine +. +.P +.I Logical Symbols +.C2 AN logicaland +.C2 OR logicalor +.C2 no logicalnot +.C2 te existential "there exists, existential quantifier" +.C2 fa universal "for all, universal quantifier" +.C2 st suchthat .C2 3d therefore .C2 tf therefore +. +.P +.I Mathematical Symbols +.C2 12 onehalf +.C2 14 onequarter +.C2 34 threequarters +.C2 S1 onesuperior +.C2 S2 twosuperior +.C2 S3 threesuperior +. +.C2 pl plusmath "plus sign in special font" +.C1 - minus "minus sign from current font" +.C2 -+ minusplus +.C2 +- plusminus +.CN t+- plusminus "text variant of `+-'" +.C2 pc periodcentered "multiplication dot" +.C2 md dotmath +.C2 mu multiply +.CN tmu multiply "text variant of `mu'" +.C2 c* circlemultiply "multiply sign in a circle" +.C2 c+ circleplus "plus sign in a circle" +.C2 di divide "division sign" +.CN tdi divide "text variant of `di'" +.C2 f/ fraction "bar for fractions" +.C2 ** asteriskmath +. +.C2 <= lessequal +.C2 >= greaterequal +.C2 << \& "much less" +.C2 >> \& "much greater" +.C2 != notequal +.C2 eq equalmath "equals sign in special font" +.C2 == equivalence +.C2 =~ congruent +.C2 ap similar +.C2 ~~ approxequal +.C2 ~= approxequal +.C2 pt proportional +. +.C2 es emptyset +.C2 mo element +.C2 nm notelement +.C2 nb notsubset +.C2 nc notpropersuperset +.C2 ne notequivalence +.C2 sb propersubset +.C2 sp propersuperset +.C2 ib reflexsubset +.C2 ip reflexsuperset +.C2 ca intersection "intersection, cap" +.C2 cu union "union, cup" +. +.C2 /_ angle +.C2 pp perpendicular +.C2 is integral +.CN sum sum +.CN product product +.C2 gr gradient +.C2 sr radical "square root" +.C2 rn \& overline "continuation of square root" +. +.C2 if infinity +.C2 Ah aleph +.C2 Im Ifraktur "Gothic I, imaginary" +.C2 Re Rfraktur "Gothic R, real" +.C2 wp weierstrass "Weierstrass p" +.C2 pd partialdiff "partial differentiation sign" +. +.P +.I Greek characters .C2 *A Alpha .C2 *B Beta .C2 *C Xi @@ -505,73 +978,77 @@ Output Input Input PostScript Notes .C2 *y eta .C2 *z zeta .C2 ts sigma1 "terminal sigma" -.C2 ~~ approxequal -.C2 ~= approxequal -.C2 != notequal -.C2 ** asteriskmath -.C2 -+ minusplus -.C2 +- plusminus -.C2 <= lessequal -.C2 == equivalence -.C2 =~ congruent -.C2 >= greaterequal -.C2 AN logicaland -.C2 OR logicalor -.C2 no logicalnot -.C2 te existential "there exists, existential quantifier" -.C2 fa universal "for all, universal quantifier" -.C2 Ah aleph -.C2 Im Ifraktur "Fraktur I, imaginary" -.C2 Re Rfraktur "Fraktur R, real" -.C2 if infinity -.C2 md dotmath -.C2 mo element -.C2 mu multiply -.C2 nb notsubset -.C2 nc notpropersuperset -.C2 ne notequivalence -.C2 nm notelement -.C2 pl plusmath "plus sign in special font" -.C2 eq equalmath "equals sign in special font" -.C2 pt proportional -.C2 pp perpendicular -.C2 sb propersubset -.C2 sp propersuperset -.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" -.C2 ca intersection "intersection, cap" -.C2 cu union "union, cup" -.C2 di divide "division sign" -.C2 -h hbar -.C2 gr gradient -.C2 es emptyset +. +.P +.I Card symbols .C2 CL club "club suit" .C2 SP spade "spade suit" .C2 HE heart "heart suit" .C2 DI diamond "diamond suit" -.C2 CR carriagereturn "carriage return symbol" -.C2 st suchthat -.C2 /_ angle -.C2 << \& "much less" -.C2 >> \& "much greater" -.C2 wp weierstrass "Weierstrass p" -.C2 lz lozenge -.C2 an arrowhorizex "horizontal arrow extension" .ch Fo +. +. +.\" -------------------------------------------------------------------- +.SH "AUTHOR" +.\" -------------------------------------------------------------------- +. +Copyright \(co 1989-2000, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.ie \n(.g \ +. URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +.el GNU copyleft site <http://www.gnu.org/copyleft/fdl.html>. +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.ie \n(.g \ +. MTO jjc@jclark.com "James Clark" +.el James Clark <jjc@jclark.com> +with additions by +.ie \n(.g \ +. MTO wl@gnu.org "Werner Lemberg" +.el Werner Lemberg <wl@gnu.org> +and +.ie \n(.g \ +. MTO bwarken@mayn.de "Bernd Warken" . +.el Bernd Warken <bwarken@mayn.de>. +. +. +.\" -------------------------------------------------------------------- .SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +.TP .BR groff (@MAN1EXT@) -.br +the GNU roff formatter. +. +.TP +.BR groff (@MAN7EXT@) +a short reference of the groff formatting language. +. +. +.P .IR "An extension to the troff character set for Europe" , -E.G. Keizer, K.J. Simonsen, J. Akkerhuis, -EUUG Newsletter, Volume 9, No. 2, Summer 1989 +E.G. Keizer, K.J. Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, +No. 2, Summer 1989 +. +. +.P +.ie \n(.g .URL http://\:www.unicode.org "The Unicode Standard" +.el The Unicode Standard <http://www.unicode.org> . +.\" -------------------------------------------------------------------- +.\" Emacs settings +.\" -------------------------------------------------------------------- .\" Local Variables: .\" mode: nroff .\" End: diff --git a/contrib/groff/man/groff_diff.man b/contrib/groff/man/groff_diff.man new file mode 100644 index 0000000..c6c1c23 --- /dev/null +++ b/contrib/groff/man/groff_diff.man @@ -0,0 +1,3650 @@ +'\" e +.\" The above line should force the use of eqn as a preprocessor +.ig +groff_diff.man + +Last update : 05 July 2002 + +This file is part of groff, the GNU roff type-setting system. +It is the source of the man-page groff_diff(7). + +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. +written by James Clark + +modified by Werner Lemberg <wl@gnu.org> + Bernd Warken <bwarken@mayn.de> + +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 AUTHORS, 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 +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \ +. ftr CB CW +. +.\" define a string tx for the TeX logo +.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el .ds tx TeX +. +. +.\" -------------------------------------------------------------------- +.\" start of macro definitions +. +.eo +. +.de c +.. +. +.de TQ +. br +. ns +. TP \$1 +.. +.de Text +. RI "\$*" +.. +.de Topic +. TP 2m +. Text \[bu] +.. +.de squoted +. ds @arg1 \$1 +. shift +.\" Text \[oq]\f[CB]\*[@arg1]\f[]\[cq]\$* +. Text \[oq]\f[B]\*[@arg1]\f[]\[cq]\$* +. rm @arg1 +.. +.c A shell command line +.de ShellCommand +. br +. IR "shell#" "\h'1m'\f[CB]\$*\f[]\/" +.. +.c reference of a request or macro +.de request +. ds @arg1 \$1 +. shift 1 +.\" Text \f[CB]\*[@arg1]\f[]\$* +. Text \f[B]\*[@arg1]\f[]\$* +. rm @arg1 +.. +.als option request +. +.c representation of an escape sequence +.de esc +. ds @arg1 \$1 +. shift +.\" Text \f[CB]\[rs]\*[@arg1]\f[]\$* +. Text \f[B]\[rs]\*[@arg1]\&\f[]\$* +. rm @arg1 +.. +.ec +.\" end of macro definitions +. +.\" from old groff_out.man +.ie \n(.g \ +. ds ic \/ +.el \ +. ds ic \^ +. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +. +.TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_diff \- differences between GNU troff and classical troff +. +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +This manual page describes the language differences between +.IR groff , +the GNU +.I roff +text processing system and the classical +.I roff +formatter of the freely available Unix\~7 of the 1970s, documented in +the +.I Troff User's Manual +by +.I Osanna +and +.IR Kernighan . +This inludes the roff language as well as the intermediate output +format (troff output). +. +.P +The section +.I SEE ALSO +gives pointers to both the classical +.I roff +and the modern +.I groff +documentation. +. +.P +At the moment, this document is the place of the most actual +documentation within the +.I groff +system. +. +This might change in the future. +. +Actually, all novelties of the groff language are first described here +and will pervade into the other documents only at a later stage. +. +. +.\" -------------------------------------------------------------------- +.SH "GROFF LANGUAGE" +.\" -------------------------------------------------------------------- +. +In this section, all additional features of +.I groff +compared to the classical Unix\~7 +.I troff +are described in detail. +. +. +.\" -------------------------------------------------------------------- +.SS "Long names" +.\" -------------------------------------------------------------------- +. +The names of number registers, fonts, strings/\:macros/\:diversions, +special characters, and colors can be of any length. +. +In escape sequences, additionally to the classical +.BI ( xx +construction for a two character name, you can use +.BI [ xxx ] +for a name of arbitrary length, for example in +. +.TP \w'\[rs]f[xxx]'u+3n +.BI \[rs][ xxx ] +Print the special character called +.IR xxx . +. +.TP +.BI \[rs]f[ xxx ] +Set font +.IR xxx . +. +Additionally, +.B \[rs]f[] +is a new syntax equal to +.BR \[rs]fP , +i.e., to return to the previous font. +. +.TP +.BI \[rs]*[ "xxx arg1 arg2 .\|.\|." ] +Interpolate string +.IR xxx , +taking +.IR arg1 , +.IR arg2 , +.I .\|.\|.\& +as arguments. +. +.TP +.BI \[rs]n[ xxx ] +Interpolate number register +.IR xxx . +. +. +.\" -------------------------------------------------------------------- +.SS "Fractional pointsizes" +.\" -------------------------------------------------------------------- +. +A +.I scaled point +is equal to +.B 1/sizescale +points, where +.B sizescale +is specified in the +.B DESC +file (1 by default). +. +There is a new scale indicator +.B z +that has the effect of multiplying by sizescale. +. +Requests and escape sequences in troff interpret arguments that +represent a pointsize as being in units of scaled points, but they +evaluate each such argument using a default scale indicator of +.BR z . +Arguments treated in this way are the argument to the +.B ps +request, the third argument to the +.B cs +request, the second and fourth arguments to the +.B tkf +request, the argument to the +.B \[rs]H +escape sequence, and those variants of the +.B \[rs]s +escape sequence that take a numeric expression as their argument. +. +.P +For example, suppose sizescale is 1000; then a scaled point will be +equivalent to a millipoint; the call +.B .ps\ 10.25 +is equivalent to +.B .ps\ 10.25z +and so sets the pointsize to 10250 scaled points, which is equal to +10.25 points. +. +.P +The number register +.B \[rs]n[.s] +returns the pointsize in points as decimal fraction. +. +There is also a new number register +.B \[rs]n[.ps] +that returns the pointsize in scaled points. +. +.P +It would make no sense to use the +.B z +scale indicator in a numeric expression whose default scale indicator +was neither +.B u +nor +.BR z , +and so +.B troff +disallows this. +. +Similarly it would make no sense to use a scaling indicator other than +.B z +or +.B u +in a numeric expression whose default scale indicator was +.BR z , +and so +.B troff +disallows this as well. +. +.P +There is also new scale indicator\~\c +.B s +which multiplies by the number of units in a scaled point. +. +So, for example, +.B \[rs]n[.ps]s +is equal to +.BR 1m . +Be sure not to confuse the +.B s +and +.B z +scale indicators. +. +. +.\" -------------------------------------------------------------------- +.SS "Numeric expressions" +.\" -------------------------------------------------------------------- +. +Spaces are permitted in a number expression within parentheses. +. +.P +.B M +indicates a scale of 100ths of an em. +.B f +indicates a scale of 65536 units, providing fractions for color +definitions with the +.B defcolor +request. +. +For example, 0.5f = 32768u. +. +.TP +.IB e1 >? e2 +The maximum of +.I e1 +and +.IR e2 . +. +.TP +.IB e1 <? e2 +The minimum of +.I e1 +and +.IR e2 . +. +.TP +.BI ( c ; e ) +Evaluate +.I e +using +.I c +as the default scaling indicator. +. +If +.I c +is missing, ignore scaling indicators in the evaluation of +.IR e . +. +. +.\" -------------------------------------------------------------------- +.SS "New escape sequences" +.\" -------------------------------------------------------------------- +. +.TP +.BI \[rs]A' anything ' +This expands to +.B 1 +or +.B 0 +resp., depending on whether +.I anything +is or is not acceptable as the name of a string, macro, diversion, number +register, environment, font, or color. +It will return\~\c +.B 0 +if +.I anything +is empty. +. +This is useful if you want to lookup user input in some sort of +associative table. +. +.TP +.BI \[rs]B' anything ' +This expands to +.B 1 +or +.B 0 +resp., depending on whether +.I anything +is or is not a valid numeric expression. +. +It will return\~\c +.B 0 +if +.I anything +is empty. +. +.TP +.BI \[rs]C' xxx ' +Typeset character named +.IR xxx . +Normally it is more convenient to use +.BI \[rs][ xxx ]\f[R]. +But +.B \[rs]C +has the advantage that it is compatible with recent versions of +.SM UNIX +and is available in compatibility mode. +. +.TP +.B \[rs]E +This is equivalent to an escape character, but it is not interpreted in +copy-mode. +. +For example, strings to start and end superscripting could be defined +like this +. +.RS +.IP +.ft CB +.Text .ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u' +.br +.Text .ds } \[rs]s0\[rs]v'.3m' +.ft +. +.P +The use of +.B \[rs]E +ensures that these definitions will work even if +.B \[rs]*{ +gets interpreted in copy-mode (for example, by being used in a macro +argument). +.RE +. +.TP +.BI \[rs]F f +.TQ +.BI \[rs]F( fm +.TQ +.BI \[rs]F[ fam ] +Change font family. +. +This is the same as the +.B fam +request. +. +.B \[rs]F[] +switches back to the previous color (note that +.B \[rs]FP +won't work; it selects font family `P' instead). +. +.TP +.BI \[rs]m x +.TQ +.BI \[rs]m( xx +.TQ +.BI \[rs]m[ xxx ] +Set drawing color. +.B \[rs]m[] +switches back to the previous color. +. +.TP +.BI \[rs]M x +.TQ +.BI \[rs]M( xx +.TQ +.BI \[rs]M[ xxx ] +Set background color for filled objects drawn with the +.BI \[rs]D' .\|.\|. ' +commands. +.B \[rs]M[] +switches back to the previous color. +. +.TP +.BI \[rs]N' n ' +Typeset the character with code +.I n +in the current font. +.I n +can be any integer. +. +Most devices only have characters with codes between 0 and 255. +. +If the current font does not contain a character with that code, +special fonts will +.I not +be searched. +. +The +.B \[rs]N +escape sequence can be conveniently used in conjunction with the +.B char +request, for example +. +.RS +.ft CB +.IP +.Text .char \[rs][phone] \[rs]f(ZD\[rs]N'37' +.ft +.RE +. +.IP +The code of each character is given in the fourth column in the font +description file after the +.B charset +command. +. +It is possible to include unnamed characters in the font description +file by using a name of +.BR \-\-\- ; +the +.B \[rs]N +escape sequence is the only way to use these. +. +.TP +.BI \[rs]O n +.TQ +.BI \[rs]O[ n ] +Suppressing troff output. +. +The escapes +.BR \[rs]02 , +.BR \[rs]O3 , +.BR \[rs]O4 , +and +.B \[rs]O5 +are intended for internal use by +.BR \%grohtml . +. +.RS +.TP +.B \[rs]O0 +Disable any ditroff glyphs from being emitted to the device driver, +provided that the escape occurs at the outer level (see +.B \[rs]O3 +and +.BR \[rs]O4 ). +. +.TP +.B \[rs]O1 +Enable output of glyphs, provided that the escape occurs at the outer +level. +.IP +.B \[rs]O0 +and +.B \[rs]O1 +also reset the registers +.BR \[rs]n[opminx] , +.BR \[rs]n[opminy] , +.BR \[rs]n[opmaxx] , +and +.B \[rs]n[opmaxy] +to\~-1. +. +These four registers mark the top left and bottom right hand corners +of a box which encompasses all written glyphs. +. +.TP +.B \[rs]O2 +Provided that the escape occurs at the outer level, enable output of +glyphs and also write out to stderr the page number and four registers +encompassing the glyphs previously written since the last call to +.BR \[rs]O . +. +.TP +.B \[rs]O3 +Begin a nesting level. +. +At start-up, +.B troff +is at outer level. +. +This is really an internal mechanism for +.B \%grohtml +while producing images. +. +They are generated by running the troff source through +.B troff +to the postscript device and +.B ghostscript +to produce images in PNG format. +. +The +.B \[rs]O3 +escape will start a new page if the device is not html (to reduce the +possibility of images crossing a page boundary). +. +.TP +.B \[rs]O4 +End a nesting level. +. +.TP +.BI \[rs]O5[ Pfilename ] +This escape is +.B \%grohtml +specific. +. +Provided that this escape occurs at the outer nesting level, write +.I filename +to stderr. +. +The position of the image, +.IR P , +must be specified and must be one of l, r, c, or i (left, right, +centered, inline). +. +.I filename +will be associated with the production of the next inline image. +.RE +. +.TP +.BI \[rs]R' name\ \[+-]n ' +This has the same effect as +. +.RS +.IP +.BI .nr\ name\ \[+-]n +.RE +. +.TP +.BI \[rs]s( nn +.TQ +.BI \[rs]s\[+-]( nn +Set the point size to +.I nn +points; +.I nn +must be exactly two digits. +. +.TP +.BI \[rs]s[\[+-] n ] +.TQ +.BI \[rs]s\[+-][ n ] +.TQ +.BI \[rs]s'\[+-] n ' +.TQ +.BI \[rs]s\[+-]' n ' +Set the point size to +.I n +scaled points; +.I n +is a numeric expression with a default scale indicator of\~\c +.BR z . +. +.TP +.BI \[rs]V x +.TQ +.BI \[rs]V( xx +.TQ +.BI \[rs]V[ xxx ] +Interpolate the contents of the environment variable +.IR xxx , +as returned by +.BR getenv (3). +.B \[rs]V +is interpreted in copy-mode. +. +.TP +.BI \[rs]Y x +.TQ +.BI \[rs]Y( xx +.TQ +.BI \[rs]Y[ xxx ] +This is approximately equivalent to +.BI \[rs]X'\[rs]*[ xxx ]'\f[R]. +However the contents of the string or macro +.I xxx +are not interpreted; also it is permitted for +.I xxx +to have been defined as a macro and thus contain newlines (it is not +permitted for the argument to +.B \[rs]X +to contain newlines). +. +The inclusion of newlines requires an extension to the UNIX troff +output format, and will confuse drivers that do not know about this +extension. +. +.TP +.BI \[rs]Z' anything ' +Print anything and then restore the horizontal and vertical position; +.I anything +may not contain tabs or leaders. +. +.TP +.B \[rs]$0 +The name by which the current macro was invoked. +. +The +.B als +request can make a macro have more than one name. +. +.TP +.B \[rs]$* +In a macro or string, the concatenation of all the arguments separated +by spaces. +. +.TP +.B \[rs]$@ +In a macro or string, the concatenation of all the arguments with each +surrounded by double quotes, and separated by spaces. +. +.TP +.BI \[rs]$( nn +.TQ +.BI \[rs]$[ nnn ] +In a macro or string, this gives the +.IR nn -th +or +.IR nnn -th +argument. +. +Macros and strings can have an unlimited number of arguments. +. +.TP +.BI \[rs]? anything \[rs]? +When used in a diversion, this will transparently embed +.I anything +in the diversion. +.I anything +is read in copy mode. +. +When the diversion is reread, +.I anything +will be interpreted. +.I anything +may not contain newlines; use +.B \[rs]!\& +if you want to embed newlines in a diversion. +. +The escape sequence +.B \[rs]?\& +is also recognised in copy mode and turned into a single internal +code; it is this code that terminates +.IR anything . +Thus +. +.RS +.IP +.ne 14v+\n(.Vu +.ft CB +.nf +.Text .nr x 1 +.Text .nf +.Text .di d +.Text \[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c +.Text \[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]? +.Text .di +.Text .nr x 2 +.Text .di e +.Text .d +.Text .di +.Text .nr x 3 +.Text .di f +.Text .e +.Text .di +.Text .nr x 4 +.Text .f +.fi +.ft +.RE +. +.IP +will print\~\c +.BR 4 . +. +.TP +.B \[rs]/ +This 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. +. +.if t \{\ +. nop For example, if an italic f is immediately followed by a roman +. nop right parenthesis, then in many fonts the top right portion of +. nop the f will overlap the top left of the right parenthesis +. nop producing \f[I]f\f[R])\f[R], which is ugly. +. nop Inserting +. B \[rs]/ +. nop produces +. ie \n(.g \f[I]f\/\f[R])\f[R] +. el \f[I]f\|\f[R])\f[R] +. nop and avoids this problem. +.\} +It is a good idea to use this escape sequence whenever an italic +character is immediately followed by a roman character without any +intervening space. +. +.TP +.B \[rs], +This 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. +. +.if t \{\ +. nop For example, inserting +. B \[rs], +. nop between the parenthesis and the f changes +. nop \f[R](\f[I]f\f[R] to +. ie \n(.g \f[R](\,\f[I]f\f[R]. +. el \f[R](\^\f[I]f\f[R]. +.\} +It is a good idea to use this escape sequence whenever a roman +character is immediately followed by an italic character without any +intervening space. +. +.TP +.B \[rs]) +Like +.B \[rs]& +except that it behaves like a character declared with the +.B cflags +request to be transparent for the purposes of end-of-sentence +recognition. +. +.TP +.B \[rs]~ +This produces an unbreakable space that stretches like a normal +inter-word space when a line is adjusted. +. +.TP +.B \[rs]: +This causes the insertion of a zero-width break point. +. +It is equal to +.B \[rs]% +within a word but without insertion of a soft hyphen character. +. +.TP +.B \[rs]# +Everything up to and including the next newline is ignored. +. +This is interpreted in copy mode. +. +It is like +.B \[rs]" +except that +.B \[rs]" +does not ignore the terminating newline. +. +. +.\" -------------------------------------------------------------------- +.SS "New requests" +.\" -------------------------------------------------------------------- +. +.TP +.BI .aln\ xx\ yy +Create an alias +.I xx +for number register object named +.IR yy . +The new name and the old name will be exactly equivalent. +. +If +.I yy +is undefined, a warning of type +.B reg +will be generated, and the request will be ignored. +. +.TP +.BI .als\ xx\ yy +Create an alias +.I xx +for request, string, macro, or diversion object named +.IR yy . +. +The new name and the old name will be exactly equivalent (it is +similar to a hard rather than a soft link). +. +If +.I yy +is undefined, a warning of type +.B mac +will be generated, and the request will be ignored. +. +The +.BR de , +.BR am , +.BR di , +.BR da , +.BR ds , +and +.B as +requests only create a new object if the name of the macro, diversion +or string diversion is currently undefined or if it is defined to be a +request; normally they modify the value of an existing object. +. +.TP +.BI .ami\ xx\ yy +Append to macro indirectly. +. +See the +.B dei +request below for more information. +. +.TP +.BI .am1\ xx\ yy +Similar to +.BR .am , +but compatibility mode is switched off during execution. +. +To be more precise, a `compatibility save' token is inserted at the +beginning of the macro addition, and a `compatibility restore' token at +the end. +. +As a consequence, the requests +.BR am , +.BR am1 , +.BR de , +and +.B de1 +can be intermixed freely since the compatibility save/\:restore tokens +only affect the macro parts defined by +.B .am1 +and +.BR .ds1 . +. +.TP +.BI .asciify\ xx +This request `unformats' the diversion +.I xx +in such a way that +.SM ASCII +and space characters (and some escape sequences) that were formatted +and diverted into +.I xx +will be treated like ordinary input characters when +.I xx +is reread. +Useful for diversions in conjunction with the +.B .writem +request. +. +It can be also used for gross hacks; for example, this +. +.RS +.IP +.ne 7v+\n(.Vu +.ft CB +.nf +.Text .tr @. +.Text .di x +.Text @nr n 1 +.Text .br +.Text .di +.Text .tr @@ +.Text .asciify x +.Text .x +.fi +.ft +.RE +. +.IP +will set register\~\c +.B n +to\~1. +. +Note that glyph information (font, font size, etc.) is not preserved; +use +.B .unformat +instead. +. +.TP +.BI .as1\ xx\ yy +Similar to +.BR .as , +but compatibility mode is switched off during expansion. +. +To be more precise, a `compatibility save' token is inserted at the +beginning of the string, and a `compatibility restore' token at the end. +. +As a consequence, the requests +.BR as , +.BR as1 , +.BR ds , +and +.B ds1 +can be intermixed freely since the compatibility save/\:restore tokens +only affect the (sub)strings defined by +.B as1 +and +.BR ds1 . +. +.TP +.B .backtrace +Print a backtrace of the input stack on stderr. +. +.TP +.BI .blm\ xx +Set the blank line macro to +.IR xx . +If there is a blank line macro, it will be invoked when a blank line +is encountered instead of the usual troff behaviour. +. +.TP +.BI .box\ xx +.TQ +.BI .boxa\ xx +These requests are similar to the +.B di +and +.B da +requests with the exception that a partially filled line will not +become part of the diversion (i.e., the diversion always starts with a +new line) but restored after ending the diversion, discarding the +partially filled line which possibly comes from the diversion. +. +.TP +.B .break +Break out of a while loop. +. +See also the +.B while +and +.B continue +requests. +. +Be sure not to confuse this with the +.B br +request. +. +.TP +.B .brp +This is the same as +.BR \[rs]p . +. +.TP +.BI .cflags\ n\ c1\ c2\|.\|.\|.\& +Characters +.IR c1 , +.IR c2 ,\|.\|.\|.\& +have properties determined by +.IR n , +which is ORed from the following: +. +.RS +.IP 1 +The character ends sentences (initially characters +.B .?!\& +have this property). +. +.IP 2 +Lines can be broken before the character (initially no characters have +this property); a line will not be broken at a character with this +property unless the characters on each side both have non-zero +hyphenation codes. +. +.IP 4 +Lines can be broken after the character (initially characters +.B \-\[rs](hy\[rs](em +have this property); a line will not be broken at a character with +this property unless the characters on each side both have non-zero +hyphenation codes. +. +.IP 8 +The character overlaps horizontally (initially characters +.B \[rs](ul\[rs](rn\[rs](ru +have this property). +. +.IP 16 +The character overlaps vertically (initially character +.B \[rs](br +has this property). +. +.IP 32 +An end-of-sentence character followed by any number of characters with +this property will be treated as the end of a sentence if followed by +a newline or two spaces; in other words the character is transparent +for the purposes of end-of-sentence recognition; this is the same as +having a zero space factor in \*[tx] (initially characters +.B \[dq]')]*\[rs](dg\[rs](rq +have this property). +.RE +. +.TP +.BI .char\ c\ string +Define character +.I c +to be +.IR string . +Every time character +.I c +needs to be printed, +.I string +will be processed in a temporary environment and the result will be +wrapped up into a single object. +. +Compatibility mode will be turned off and the escape character will be +set to +.B \[rs] +while +.I string +is being processed. +. +Any emboldening, constant spacing or track kerning will be applied to +this object rather than to individual characters in +.IR string . +. +.IP +A character defined by this request can be used just like a normal +character provided by the output device. +. +In particular other characters can be translated to it with the +.B tr +request; it can be made the leader character by the +.B lc +request; repeated patterns can be drawn with the character using the +.B \[rs]l +and +.B \[rs]L +escape sequences; words containing the character can be hyphenated +correctly, if the +.B hcode +request is used to give the character a hyphenation code. +. +.IP +There is a special anti-recursion feature: use of character within the +character's definition will be handled like normal characters not +defined with +.BR char . +.IP +A character definition can be removed with the +.B rchar +request. +. +.TP +.BI .chop\ xx +Chop the last character off macro, string, or diversion +.IR xx . +This is useful for removing the newline from the end of diversions +that are to be interpolated as strings. +. +.TP +.BI .close\ stream +Close the stream named +.IR stream ; +.I stream +will no longer be an acceptable argument to the +.B write +request. +. +See the +.B open +request. +. +.TP +.B .continue +Finish the current iteration of a while loop. +. +See also the +.B while +and +.B break +requests. +. +.TP +.BI .color\ n +If +.I n +is non-zero or missing, enable colors (this is the default), otherwise +disable them. +. +.TP +.BI .cp\ n +If +.I n +is non-zero or missing, enable compatibility mode, otherwise disable +it. +. +In compatibility mode, long names are not recognised, and the +incompatibilities caused by long names do not arise. +. +.TP +.BI .defcolor\ xxx\ scheme\ color_components +Define color. +.I scheme +can be one of the following values: +.B rgb +(three components), +.B cym +(three components), +.B cmyk +(four components), and +.B gray +or +.B grey +(one component). +. +Color components can be given either as a hexadecimal string or as +positive decimal integers in the range 0-65535. +. +A hexadecimal string contains all color components concatenated; it +must start with either +.B # +or +.BR ## . +The former specifies hex values in the range 0-255 (which are +internally multiplied by\~257), the latter in the range 0-65535. +. +Examples: #FFC0CB (pink), ##ffff0000ffff (magenta). +. +A new scaling indicator\~\c +.B f +has been introduced which multiplies its value by\~65536; this makes +it convenient to specify color components as fractions in the range 0 +to\~1. +. +Example: +. +.RS +.IP +.ft CB +.Text .defcolor darkgreen rgb 0.1f 0.5f 0.2f +.br +.ft +.RE +. +.IP +Note that +.B f +is the default scaling indicator for the +.B defcolor +request, thus the above statement is equivalent to +. +.RS +.IP +.ft CB +.Text .defcolor darkgreen rgb 0.1 0.5 0.2 +.br +.ft +.RE +. +.IP +The color named +.B default +(which is device-specific) can't be redefined. +. +It is possible that the default color for +.esc M +and +.esc m +is not the same. +. +.TP +.BI .dei\ xx\ yy +Define macro indirectly. +. +The following example +. +.RS +.IP +.ne 2v+\n(.Vu +.ft CB +.nf +.Text .ds xx aa +.Text .ds yy bb +.Text .dei xx yy +.fi +.ft +.RE +. +.IP +is equivalent to +. +.RS +.IP +.ft CB +.Text .de aa bb +.br +.ft +.RE +. +.TP +.BI .de1\ xx\ yy +Similar to +.BR .de , +but compatibility mode is switched off during execution. +. +On entry, the current compatibility mode is saved and restored at exit. +. +.TP +.BI .do\ xxx +Interpret +.I .xxx +with compatibility mode disabled. +. +For example, +. +.RS +. +.IP +.ft CB +.Text .do fam T +.br +.ft +. +.P +would have the same effect as +. +.IP +.ft CB +.Text .fam T +.br +.ft +. +.P +except that it would work even if compatibility mode had been enabled. +. +Note that the previous compatibility mode is restored before any files +sourced by +.I xxx +are interpreted. +. +.RE +. +.TP +.BI .ds1\ xx\ yy +Similar to +.BR .ds , +but compatibility mode is switched off during expansion. +. +To be more precise, a `compatibility save' token is inserted at the +beginning of the string, and a `compatibility restore' token at the end. +. +.TP +.B .ecs +Save current escape character. +. +.TP +.B .ecr +Restore escape character saved with +.BR ecs . +Without a previous call to +.BR ecs , +.RB ` \[rs] ' +will be the new escape character. +. +.TP +.BI .evc\ xx +Copy the contents of environment +.I xx +to the current environment. +. +No pushing or popping of environments will be done. +. +.TP +.BI .fam\ xx +Set the current font family to +.IR xx . +The current font family is part of the current environment. +If +.I xx +is missing, switch back to previous font family. +. +The value at start-up is `T'. +. +See the description of the +.B sty +request for more information on font families. +. +.TP +.BI .fchar\ c\ string +Define fallback character +.I c +to be +.IR string . +The syntax of this request is the same as the +.B char +request; the only difference is that a character defined with +.B char +hides the glyph with the same name in the current font, whereas a +character defined with +.B fchar +is checked only if the particular glyph isn't found in the current font. +. +This test happens before checking special fonts. +. +.TP +.BI .fspecial\ f\ s1\ s2\|.\|.\|.\& +When the current font is +.IR f , +fonts +.IR s1 , +.IR s2 ,\|.\|.\|.\& +will be special, that is, they will searched for characters not in +the current font. +. +Any fonts specified in the +.B special +request will be searched after fonts specified in the +.B fspecial +request. +. +.TP +.BI .ftr\ f\ g +Translate font +.I f +to +.IR g . +Whenever a font named +.I f +is referred to in an +.B \[rs]f +escape sequence, or in the +.BR ft , +.BR ul , +.BR bd , +.BR cs , +.BR tkf , +.BR special , +.BR fspecial , +.BR fp , +or +.BR sty +requests, font +.I g +will be used. +If +.I g +is missing, or equal to +.I f +then font +.I f +will not be translated. +. +.TP +.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\& +Set the hyphenation code of character +.I c1 +to +.I code1 +and that of +.I c2 +to +.IR code2 . +A hyphenation code must be a single input character (not a special +character) other than a digit or a space. +. +Initially each lower-case letter \%a-z has a hyphenation code, which is +itself, and each upper-case letter \%A-Z has a hyphenation code which is +the lower-case version of itself. +. +See also the +.B hpf +request. +. +.TP +.BI .hla\ lang +Set the current hyphenation language to +.IR lang . +Hyphenation exceptions specified with the +.B hw +request and hyphenation patterns specified with the +.B hpf +request are both associated with the current hyphenation language. +. +The +.B hla +request is usually invoked by the +.B troffrc +file. +. +.TP +.BI .hlm\ n +Set the maximum number of consecutive hyphenated lines to\~\c +.IR n . +If +.I n +is negative, there is no maximum. +. +The default value is\~\-1. +. +This value is associated with the current environment. +. +Only lines output from an environment count towards the maximum +associated with that environment. +. +Hyphens resulting from +.B \[rs]% +are counted; explicit hyphens are not. +. +.TP +.BI .hpf\ file +Read hyphenation patterns from +.IR file ; +this will be searched for in the same way that +.IB name .tmac +is searched for when the +.BI \-m name +option is specified. +. +It should have the same format as (simple) \*[tx] patterns files. +. +More specifically, the following scanning rules are implemented. +. +.RS +.IP \[bu] +A percent sign starts a comment (up to the end of the line) even if +preceded by a backslash. +. +.IP \[bu] +No support for `digraphs' like +.BR \[rs]$ . +. +.IP \[bu] +.BI ^^ xx +.RI ( x +is 0-9 or a-f) and +.BI ^^ x +(character code of\~\c +.I x +in the range 0-127) are recognized; other use of +.B ^ +causes an error. +. +.IP \[bu] +No macro expansion. +. +.IP \[bu] +.B hpf +checks for the expression +.B \[rs]patterns{.\|.\|.} +(possibly with whitespace before and after the braces). +. +Everything between the braces is taken as hyphenation patterns. +. +Consequently, +.B { +and +.B } +are not allowed in patterns. +. +.IP \[bu] +Similarly, +.B \[rs]hyphenation{.\|.\|.} +gives a list of hyphenation exceptions. +. +.IP \[bu] +.B \[rs]endinput +is recognized also. +. +.IP \[bu] +For backwards compatibility, if +.B \[rs]patterns +is missing, the whole file is treated as a list of hyphenation patterns +(only recognizing the +.BR % \~\c +character as the start of a comment). +.RE +. +.IP +Use the +.B hpfcode +request to map the encoding used in hyphenation patterns files to +.BR groff 's +input encoding. +.IP +The set of hyphenation patterns is associated with the current language +set by the +.B hla +request. +. +The +.B hpf +request is usually invoked by the +.B troffrc +file; a second call replaces the old patterns with the new ones. +. +.TP +.BI .hpfa\ file +The same as +.B hpf +except that the hyphenation patterns from +.I file +are appended to the patterns already loaded in the current language. +. +.TP +.BI .hpfcode\ a\ b\ c\ d\ .\|.\|. +After reading a hyphenation patterns file with the +.B hpf +or +.B hpfa +request, convert all characters with character code\~\c +.I a +in the recently read patterns to character code\~\c +.IR b , +character code\~\c +.I c +to\~\c +.IR d , +etc. +. +Initially, all character codes map to themselves. +. +The arguments of +.B hpfcode +must be integers in the range 0 to\~255. +. +Note that it is even possible to use character codes which are invalid in +.B groff +otherwise. +. +.TP +.BI .hym\ n +Set the +.I hyphenation margin +to\~\c +.IR n : +when the current adjustment mode is not\~\c +.BR b , +the line will not be hyphenated if the line is no more than +.I n +short. +. +The default hyphenation margin is\~0. +. +The default scaling indicator for this request is\~\c +.IR m . +The hyphenation margin is associated with the current environment. +. +The current hyphenation margin is available in the +.B \[rs]n[.hym] +register. +. +.TP +.BI .hys\ n +Set the +.I hyphenation space +to\~\c +.IR n : +when the current adjustment mode is\~\c +.B b +don't hyphenate the line if the line can be justified by adding no +more than +.I n +extra space to each word space. +. +The default hyphenation space is\~0. +. +The default scaling indicator for this request is\~\c +.BR m . +The hyphenation space is associated with the current environment. +. +The current hyphenation space is available in the +.B \[rs]n[.hys] +register. +. +.TP +.BI .itc\ n\ macro +Variant of +.B .it +for which a line interrupted with +.B \[rs]c +counts as one input line. +. +.TP +.BI .kern\ n +If +.I n +is non-zero or missing, enable pairwise kerning, otherwise disable it. +. +.TP +.BI .length\ xx\ string +Compute the length of +.I string +and return it in the number register +.I xx +(which is not necessarily defined before). +. +.TP +.BI .linetabs\ n +If +.I n +is non-zero or missing, enable line-tabs mode, otherwise disable it +(which is the default). +. +In line-tabs mode, tab distances are computed relative to the +(current) output line. +. +Otherwise they are taken relative to the input line. +. +For example, the following +. +.RS +.IP +.ne 6v+\n(.Vu +.ft CB +.nf +.Text .ds x a\[rs]t\[rs]c +.Text .ds y b\[rs]t\[rs]c +.Text .ds z c +.Text .ta 1i 3i +.Text \[rs]*x +.Text \[rs]*y +.Text \[rs]*z +.fi +.ft +.RE +. +.IP +yields +. +.RS +.IP +a b c +.RE +. +.IP +In line-tabs mode, the same code gives +. +.RS +.IP +a b c +.RE +. +.IP +Line-tabs mode is associated with the current environment; the +read-only number register +.B \\[rs]n[.linetabs] +is set to\~1 if in line-tabs mode, and 0 otherwise. +. +.TP +.BI .mso\ file +The same as the +.B so +request except that +.I file +is searched for in the same directories as macro files for the the +.B \-m +command line option. +. +If the file name to be included has the form +.IB name .tmac +and it isn't found, +.B mso +tries to include +.BI tmac. name +instead and vice versa. +. +.TP +.BI .nop \ anything +Execute +.IR anything . +This is similar to `.if\ 1'. +. +.TP +.B .nroff +Make the +.B n +built-in condition true and the +.B t +built-in condition false. +. +This can be reversed using the +.B troff +request. +. +.TP +.BI .open\ stream\ filename +Open +.I filename +for writing and associate the stream named +.I stream +with it. +. +See also the +.B close +and +.B write +requests. +. +.TP +.BI .opena\ stream\ filename +Like +.BR open , +but if +.I filename +exists, append to it instead of truncating it. +. +.TP +.BI .output\ string +Emit +.I string +directly to the intermediate output (subject to copy-mode interpretation); +this is similar to +.B \[rs]! +used at the top level. +. +An initial double quote in +.I string +is stripped off to allow initial blanks. +. +.TP +.B .pnr +Print the names and contents of all currently defined number registers +on stderr. +. +.TP +.BI .psbb \ filename +Get the bounding box of a PostScript image +.IR filename . +This file must conform to Adobe's Document Structuring Conventions; +the command looks for a +.B \%%%BoundingBox +comment to extract the bounding box values. +. +After a successful call, the coordinates (in PostScript units) of the +lower left and upper right corner can be found in the registers +.BR \[rs]n[llx] , +.BR \[rs]n[lly] , +.BR \[rs]n[urx] , +and +.BR \[rs]n[ury] , +respectively. +. +If some error has occurred, the four registers are set to zero. +. +.TP +.BI .pso \ command +This behaves like the +.B so +request except that input comes from the standard output of +.IR command . +. +.TP +.B .ptr +Print the names and positions of all traps (not including input line +traps and diversion traps) on stderr. +. +Empty slots in the page trap list are printed as well, because they +can affect the priority of subsequently planted traps. +. +.TP +.BI .pvs \ \[+-]n +Set the post-vertical line space to +.IR n ; +default scale indicator is\~\c +.BR p . +. +This value will be added to each line after it has been output. +. +With no argument, the post-vertical line space is set to its previous +value. +. +.IP +The total vertical line spacing consists of four components: +.B .vs +and +.B \[rs]x +with a negative value which are applied before the line is output, and +.B .pvs +and +.B \[rs]x +with a positive value which are applied after the line is output. +. +.TP +.BI .rchar\ c1\ c2\|.\|.\|.\& +Remove the definitions of characters +.IR c1 , +.IR c2 ,\|.\|.\|. +This undoes the effect of a +.B char +request. +. +.TP +.B .return +Within a macro, return immediately. +. +No effect otherwise. +. +.TP +.B .rj +.TQ +.BI .rj \~n +Right justify the next +.IR n \~\c +input lines. +. +Without an argument right justify the next input line. +. +The number of lines to be right justified is available in the +.B \[rs]n[.rj] +register. +. +This implicitly does +.BR .ce \~0 . +The +.B ce +request implicitly does +.BR .rj \~0 . +. +.TP +.BI .rnn \ xx\ yy +Rename number register +.I xx +to +.IR yy . +. +.TP +.BI .shc\ c +Set the soft hyphen character to +.IR c . +If +.I c +is omitted, the soft hyphen character will be set to the default +.BR \[rs](hy . +The soft hyphen character is the character which will be inserted when +a word is hyphenated at a line break. +. +If the soft hyphen character does not exist in the font of the +character immediately preceding a potential break point, then the line +will not be broken at that point. +. +Neither definitions (specified with the +.B char +request) nor translations (specified with the +.B tr +request) are considered when finding the soft hyphen character. +. +.TP +.BI .shift\ n +In a macro, shift the arguments by +.I n +positions: argument\~\c +.I i +becomes argument +.IR i \- n ; +arguments 1 to\~\c +.I n +will no longer be available. +. +If +.I n +is missing, arguments will be shifted by\~1. +. +Shifting by negative amounts is currently undefined. +. +.TP +.BI .sizes\ s1\ s2\|.\|.\|.\|sn\ [0] +This command is similar to the +.B sizes +command of a +.B DESC +file. +. +It sets the available font sizes for the current font to +.IR s1 , +.IR s2 ,\|.\|.\|.\|,\~ sn +scaled points. +. +The list of sizes can be terminated by an optional\~\c +.BR 0 . +. +Each +.I si +can also be a range of sizes +.IR m - n . +. +Contrary to the font file command, the list can't extend over more +than a single line. +. +.TP +.BI .special\ s1\ s2\|.\|.\|.\& +Fonts +.IR s1 , +.IR s2 , +are special and will be searched for characters not in the current +font. +. +.TP +.BI .spreadwarn\ limit +Make +.B troff +emit a warning if the additional space inserted for each space between +words in an output line is larger or equal to +.IR limit . +. +A negative value is changed to zero; no argument toggles the warning on +and off without changing +.IR limit . +. +The default scaling indicator is\~\c +.BR m . +. +At startup, +.B spreadwarn +is deactivated, and +.I limit +is set to 3m. +. +For example, +.B .spreadwarn\ 0.2m +will cause a warning if +.B troff +must add 0.2m or more for each interword space in a line. +. +This request is active only if text is justified to both margins (using +.BR .ad\ b ). +. +.TP +.BI .sty\ n\ f +Associate style\~\c +.I f +with font position\~\c +.IR n . +A font position can be associated either with a font or with a style. +. +The current font is the index of a font position and so is also either +a font or a style. +. +When it is a style, the font that is actually used is the font the +name of which is the concatenation of the name of the current family +and the name of the current style. +. +For example, if the current font is\~1 and font position\~1 is +associated with style\~\c +.B R +and the current font family is\~\c +.BR T , +then font +.BR TR +will be used. +. +If the current font is not a style, then the current family is ignored. +. +When the requests +.BR cs , +.BR bd , +.BR tkf , +.BR uf , +or +.B fspecial +are applied to a style, then they will instead be applied to the +member of the current family corresponding to that style. +. +The default family can be set with the +.B \-f +option. +. +The +.B styles +command in the +.SM DESC +file controls which font positions (if any) are initially associated +with styles rather than fonts. +. +.TP +.BI .substring\ xx\ n1\ [ n2 ] +Replace the string named +.I xx +with the substring defined by the indices +.I n1 +and +.IR n2 . +The first character in the string has index\~0. +. +If +.I n2 +is omitted, it is taken to be equal to the string's length. +. +If the index value +.I n1 +or +.I n2 +is negative, it will be counted from the end of the string, +going backwards: +. +The last character has index\~-1, the character before the last +character has index\~-2, etc. +. +.TP +.BI .tkf\ f\ s1\ n1\ s2\ n2 +Enable track kerning for font +.IR f . +When the current font is +.I f +the width of every character will be increased by an amount between +.I n1 +and +.IR n2 ; +when the current point size is less than or equal to +.I s1 +the width will be increased by +.IR n1 ; +when it is greater than or equal to +.I s2 +the width will be increased by +.IR n2 ; +when the point size is greater than or equal to +.I s1 +and less than or equal to +.I s2 +the increase in width is a linear function of the point size. +. +.TP +.BI .tm1\ string +Similar to the +.B tm +request, +.I string +is read in copy mode and written on the standard error, but an initial +double quote in +.I string +is stripped off to allow initial blanks. +. +.TP +.BI .tmc\ string +Similar to +.B tm1 +but without writing a final newline. +. +.TP +.BI .trf\ filename +Transparently output the contents of file +.IR filename . +Each line is output as if preceded by +.BR \[rs]! ; +however, the lines are not subject to copy-mode interpretation. +. +If the file does not end with a newline, then a newline will be added. +. +For example, you can define a macro\~\c +.I x +containing the contents of file\~\c +.IR f , +using +. +.RS +.IP +.ne 2v+\n(.Vu +.ft CB +.nf +.Text .di x +.Text .trf f +.Text .di +.fi +.ft +.RE +. +.IP +Unlike with the +.B cf +request, the file cannot contain characters such as +.SM NUL +that are not legal troff input characters. +. +.TP +.BI .trin\ abcd +This is the same as the +.B tr +request except that the +.B asciify +request will use the character code (if any) before the character +translation. +. +Example: +. +.RS +.IP +.nf +.ft CB +.Text .trin ax +.Text .di xxx +.Text a +.Text .br +.Text .di +.Text .xxx +.Text .trin aa +.Text .asciify xxx +.Text .xxx +.fi +.ft +.RE +. +.IP +The result is +.BR x\ a . +. +Using +.BR tr , +the result would be +.BR x\ x . +. +.TP +.BI .trnt\ abcd +This is the same as the +.B tr +request except that the translations do not apply to text that is +transparently throughput into a diversion with +.BR \[rs]! . +For example, +. +.RS +.IP +.nf +.ft CB +.Text .tr ab +.Text .di x +.Text \[rs]!.tm a +.Text .di +.Text .x +.fi +.ft +.RE +. +.IP +will print\~\c +.BR b ; +if +.B trnt +is used instead of +.B tr +it will print\~\c +.BR a . +.RE +. +.TP +.B .troff +Make the +.B n +built-in condition false, and the +.B t +built-in condition true. +. +This undoes the effect of the +.B nroff +request. +. +.TP +.BI .unformat\ xx +This request `unformats' the diversion +.IR xx . +Contrary to the +.B .asciify +request, which tries to convert formatted elements of the diversion +back to input tokens as much as possible, +.B .unformat +will only handle tabs and spaces between words (usually caused by +spaces or newlines in the input) specially. +. +The former are treated as if they were input tokens, and the latter +are stretchable again. +. +Note that the vertical size of lines is not preserved. +. +Glyph information (font, font size, space width, etc.) is retained. +. +Useful in conjunction with the +.B .box +and +.B .boxa +requests. +. +.TP +.BI .vpt\ n +Enable vertical position traps if +.I n +is non-zero, disable them otherwise. +. +Vertical position traps are traps set by the +.B wh +or +.B dt +requests. +. +Traps set by the +.B it +request are not vertical position traps. +. +The parameter that controls whether vertical position traps are +enabled is global. +. +Initially vertical position traps are enabled. +. +.TP +.BI .warn\ n +Control warnings. +.I n +is the sum of the numbers associated with each warning that is to be +enabled; all other warnings will be disabled. +. +The number associated with each warning is listed in +.BR @g@troff (@MAN1EXT@). +. +For example, +.B .warn\~0 +will disable all warnings, and +.B .warn\~1 +will disable all warnings except that about missing characters. +. +If +.I n +is not given, all warnings will be enabled. +. +.TP +.BI .warnscale\ si +Set the scaling indicator used in warnings to +.IR si . +. +Valid values for +.I si +are +.BR u , +.BR i , +.BR c , +.BR p , +and +.BR P . +. +At startup, it is set to\~\c +.BR i . +. +.TP +.BI .while \ c\ anything +While condition\~\c +.I c +is true, accept +.I anything +as input; +.IR c \~\c +can be any condition acceptable to an +.B if +request; +.I anything +can comprise multiple lines if the first line starts with +.B \[rs]{ +and the last line ends with +.BR \[rs]} . +See also the +.B break +and +.B continue +requests. +. +.TP +.BI .write\ stream\ anything +Write +.I anything +to the stream named +.IR stream . +.I stream +must previously have been the subject of an +.B open +request. +.I anything +is read in copy mode; +a leading\~\c +.B \[dq] +will be stripped. +. +.TP +.BI .writec\ stream\ anything +Similar to +.B write +but without writing a final newline. +. +.TP +.BI .writem\ stream\ xx +Write the contents of the macro or string +.I xx +to the stream named +.IR stream . +.I stream +must previously have been the subject of an +.B open +request. +.I xx +is read in copy mode. +. +. +.\" -------------------------------------------------------------------- +.SS "Extended requests" +.\" -------------------------------------------------------------------- +. +.TP +.BI .cf\ filename +When used in a diversion, this will embed in the diversion an object +which, when reread, will cause the contents of +.I filename +to be transparently copied through to the output. +. +In UNIX troff, the contents of +.I filename +is immediately copied through to the output regardless of whether +there is a current diversion; this behaviour is so anomalous that it +must be considered a bug. +. +.TP +.BI .ev\ xx +If +.I xx +is not a number, this will switch to a named environment called +.IR xx . +The environment should be popped with a matching +.B ev +request without any arguments, just as for numbered environments. +. +There is no limit on the number of named environments; they will be +created the first time that they are referenced. +. +.TP +.BI .ss\ m\ n +When two arguments are given to the +.B ss +request, the second argument gives the +.IR "sentence space size" . +If the second argument is not given, the sentence space size +will be the same as the word space size. +. +Like the word space size, the sentence space is in units of +one twelfth of the spacewidth parameter for the current font. +. +Initially both the word space size and the sentence +space size are\~12. +. +Contrary to UNIX troff, GNU troff handles this request in nroff mode +also; a given value is then rounded down to the nearest multiple +of\~12. +. +The sentence space size is used in two circumstances. +. +If the end of a sentence occurs at the end of a line in fill mode, +then both an inter-word space and a sentence space will be added; if +two spaces follow the end of a sentence in the middle of a line, then +the second space will be a sentence space. +. +Note that the behaviour of UNIX troff will be exactly that exhibited +by GNU troff if a second argument is never given to the +.B ss +request. +. +In GNU troff, as in UNIX troff, you should always follow a sentence +with either a newline or two spaces. +. +.TP +.BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn +Set tabs at positions +.IR n1 , +.IR n2 ,\|.\|.\|.\|, +.I nn +and then set tabs at +.IR nn + r1 , +.IR nn + r2 ,\|.\|.\|.\|, +.IR nn + rn +and then at +.IR nn + rn + r1 , +.IR nn + rn + r2 ,\|.\|.\|.\|, +.IR nn + rn + rn , +and so on. +For example, +. +.RS +.IP +.ft CB +.Text .ta T .5i +.br +.ft +. +.P +will set tabs every half an inch. +.RE +. +. +.\" -------------------------------------------------------------------- +.SS "New number registers" +.\" -------------------------------------------------------------------- +. +The following read-only registers are available: +. +.TP +.B \[rs]n[.C] +1\~if compatibility mode is in effect, 0\~otherwise. +. +.TP +.B \[rs]n[.cdp] +The depth of the last character added to the current environment. +. +It is positive if the character extends below the baseline. +. +.TP +.B \[rs]n[.ce] +The number of lines remaining to be centered, as set by the +.B ce +request. +. +.TP +.B \[rs]n[.cht] +The height of the last character added to the current environment. +. +It is positive if the character extends above the baseline. +. +.TP +.B \[rs]n[.color] +1\~if colors are enabled, 0\~otherwise. +. +.TP +.B \[rs]n[.csk] +The skew of the last character added to the current environment. +. +The +.I 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. +. +.TP +.B \[rs]n[.ev] +The name or number of the current environment. +. +This is a string-valued register. +. +.TP +.B \[rs]n[.fam] +The current font family. +. +This is a string-valued register. +. +.TP +.B \[rs]n[.fn] +The current (internal) real font name. +. +This is a string-valued register. +. +If the current font is a style, the value of +.B \[rs]n[.fn] +is the proper concatenation of family and style name. +. +.TP +.B \[rs]n[.fp] +The number of the next free font position. +. +.TP +.B \[rs]n[.g] +Always\~1. +. +Macros should use this to determine whether they are running under GNU +troff. +. +.TP +.B \[rs]n[.hla] +The current hyphenation language as set by the +.B hla +request. +. +.TP +.B \[rs]n[.hlc] +The number of immediately preceding consecutive hyphenated lines. +. +.TP +.B \[rs]n[.hlm] +The maximum allowed number of consecutive hyphenated lines, as set by +the +.B hlm +request. +. +.TP +.B \[rs]n[.hy] +The current hyphenation flags (as set by the +.B hy +request). +. +.TP +.B \[rs]n[.hym] +The current hyphenation margin (as set by the +.B hym +request). +. +.TP +.B \[rs]n[.hys] +The current hyphenation space (as set by the +.B hys +request). +. +.TP +.B \[rs]n[.in] +The indent that applies to the current output line. +. +.TP +.B \[rs]n[.int] +Set to a positive value if last output line is interrupted (i.e., if +it contains +.IR \[rs]c ). +. +.TP +.B \[rs]n[.kern] +1\~if pairwise kerning is enabled, 0\~otherwise. +. +.TP +.B \[rs]n[.lg] +The current ligature mode (as set by the +.B lg +request). +. +.TP +.B \[rs]n[.linetabs] +The current line-tabs mode (as set by the +.B linetabs +request). +. +.TP +.B \[rs]n[.ll] +The line length that applies to the current output line. +. +.TP +.B \[rs]n[.lt] +The title length as set by the +.B lt +request. +. +.TP +.B \[rs]n[.ne] +The amount of space that was needed in the last +.B ne +request that caused a trap to be sprung. +. +Useful in conjunction with the +.B \[rs]n[.trunc] +register. +. +.TP +.B \[rs]n[.ns] +1\~if no-space mode is active, 0\~otherwise. +. +.TP +.B \[rs]n[.pn] +The number of the next page, either the value set by a +.B pn +request, or the number of the current page plus\~1. +. +.TP +.B \[rs]n[.ps] +The current pointsize in scaled points. +. +.TP +.B \[rs]n[.psr] +The last-requested pointsize in scaled points. +. +.TP +.B \[rs]n[.pvs] +The current post-vertical line space as set with the +.B pvs +request. +. +.TP +.B \[rs]n[.rj] +The number of lines to be right-justified as set by the +.B rj +request. +. +.TP +.B \[rs]n[.sr] +The last requested pointsize in points as a decimal fraction. +. +This is a string-valued register. +. +.TP +.B \[rs]n[.ss] +.TQ +.B \[rs]n[.sss] +These give the values of the parameters set by the first and second +arguments of the +.B ss +request. +. +.TP +.B \[rs]n[.tabs] +A string representation of the current tab settings suitable for use +as an argument to the +.B ta +request. +. +.TP +.B \[rs]n[.trunc] +The amount of vertical space truncated by the most recently sprung +vertical position trap, or, if the trap was sprung by a +.B ne +request, minus the amount of vertical motion produced by the +.B 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 +.B \[rs]n[.ne] +register. +. +.TP +.B \[rs]n[.vpt] +1\~if vertical position traps are enabled, 0\~otherwise. +. +.TP +.B \[rs]n[.warn] +The sum of the numbers associated with each of the currently enabled +warnings. +. +The number associated with each warning is listed in +.BR @g@troff (@MAN1EXT@). +. +.TP +.B \[rs]n[.x] +The major version number. +. +For example, if the version number is 1.03, then +.B \[rs]n[.x] +will contain\~1. +. +.TP +.B \[rs]n[.y] +The minor version number. +. +For example, if the version number is 1.03, then +.B \[rs]n[.y] +will contain\~03. +. +.TP +.B \[rs]n[.Y] +The revision number of groff. +. +.TP +.B \[rs]n[llx] +.TQ +.B \[rs]n[lly] +.TQ +.B \[rs]n[urx] +.TQ +.B \[rs]n[ury] +These four registers are set by the +.B .psbb +request and contain the bounding box values (in PostScript units) of a +given PostScript image. +. +.P +The following read/write registers are set by the +.B \[rs]w +escape sequence: +. +.TP +.B \[rs]n[rst] +.TQ +.B \[rs]n[rsb] +Like the +.B st +and +.B sb +registers, but take account of the heights and depths of characters. +. +.TP +.B \[rs]n[ssc] +The amount of horizontal space (possibly negative) that should be +added to the last character before a subscript. +. +.TP +.B \[rs]n[skw] +How far to right of the center of the last character in the +.B \[rs]w +argument, the center of an accent from a roman font should be placed +over that character. +. +.P +Other available read/write number registers are: +. +.TP +.B \[rs]n[c.] +The current input line number. +.B \[rs]n[.c] +is a read-only alias to this register. +. +.TP +.B \[rs]n[hours] +The number of hours past midnight. +. +Initialized at start-up. +. +.TP +.B \[rs]n[hp] +The current horizontal position at input line. +. +.TP +.B \[rs]n[minutes] +The number of minutes after the hour. +. +Initialized at start-up. +. +.TP +.B \[rs]n[seconds] +The number of seconds after the minute. +. +Initialized at start-up. +. +.TP +.B \[rs]n[systat] +The return value of the system() function executed by the last +.B sy +request. +. +.TP +.B \[rs]n[slimit] +If greater than\~0, the maximum number of objects on the input stack. +. +If less than or equal to\~0, there is no limit on the number of +objects on the input stack. +. +With no limit, recursion can continue until virtual memory is +exhausted. +. +.TP +.B \[rs]n[year] +The current year. +. +Note that the traditional +.B troff +number register +.B \[rs]n[yr] +is the current year minus 1900. +. +. +.\" -------------------------------------------------------------------- +.SS Miscellaneous +.\" -------------------------------------------------------------------- +. +.B @g@troff +predefines a single (read/write) string-based register, +.BR \[rs]*(.T , +which contains the argument given to the +.B -T +command line option, namely the current output device (for example, +.I latin1 +or +.IR ascii ). +Note that this is not the same as the (read-only) number register +.B \[rs]n[.T] +which is defined to be\~1 if +.B troff +is called with the +.B -T +command line option, and zero otherwise. +. +This behaviour is different to UNIX troff. +. +.P +Fonts not listed in the +.SM DESC +file are automatically mounted on the next available font position +when they are referenced. +. +If a font is to be mounted explicitly with the +.B fp +request on an unused font position, it should be mounted on the first +unused font position, which can be found in the +.B \[rs]n[.fp] +register; although +.B troff +does not enforce this strictly, it will not allow a font to be mounted +at a position whose number is much greater than that of any currently +used position. +. +.P +Interpolating a string does not hide existing macro arguments. +. +Thus in a macro, a more efficient way of doing +. +.IP +.BI . xx\ \[rs]\[rs]$@ +.P +is +. +.IP +.BI \[rs]\[rs]*[ xx ]\[rs]\[rs] +. +.P +If the font description file contains pairwise kerning information, +characters from that font will be kerned. +. +Kerning between two characters can be inhibited by placing a +.B \[rs]& +between them. +. +.P +In a string comparison in a condition, characters that appear at +different input levels to the first delimiter character will not be +recognised as the second or third delimiters. +. +This applies also to the +.B tl +request. +. +In a +.B \[rs]w +escape sequence, a character that appears at a different input level +to the starting delimiter character will not be recognised as the +closing delimiter character. +. +The same is true for +.BR \[rs]A , +.BR \[rs]b , +.BR \[rs]B , +.BR \[rs]C , +.BR \[rs]l , +.BR \[rs]L , +.BR \[rs]o , +.BR \[rs]X , +and +.BR \[rs]Z . +. +When decoding a macro or string argument that is delimited by double +quotes, a character that appears at a different input level to the starting +delimiter character will not be recognised as the closing delimiter +character. +. +The implementation of +.B \[rs]$@ +ensures that the double quotes surrounding an argument will appear the +same input level, which will be different to the input level of the +argument itself. +. +In a long escape name +.B ] +will not be recognized as a closing delimiter except when it occurs at +the same input level as the opening +.BR ] . +. +In compatibility mode, no attention is paid to the input-level. +. +.P +There are some new types of condition: +. +.TP +.BI .if\ r xxx +True if there is a number register named +.IR xxx . +. +.TP +.BI .if\ d xxx +True if there is a string, macro, diversion, or request named +.IR xxx . +. +.TP +.BI .if\ m xxx +True if there is a color named +.IR xxx . +. +.TP +.BI .if\ c ch +True if there is a character +.IR ch +available; +.I ch +is either an +.SM ASCII +character or a special character +.BI \[rs]( xx +or +.BI \[rs][ xxx ]\f[R]; +the condition will also be true if +.I ch +has been defined by the +.B char +request. +. +.P +The +.B tr +request can now map characters onto +.BR \[rs]~ . +. +.P +It is now possible to have whitespace between the first and second dot +(or the name of the ending macro) to end a macro definition. +. +Example: +. +.IP +.ne 6v+\n(.Vu +.ft CB +.nf +.Text .de foo +.Text . nop Hello, I'm `foo'. +.Text . nop I will now define `bar'. +.Text . de bar +.Text . nop Hello, I'm `bar'. +.Text . . +.Text . nop Done. +.Text .. +.Text .foo +.Text .bar +.fi +. +. +.\" -------------------------------------------------------------------- +.SH "INTERMEDIATE OUTPUT FORMAT" +.\" -------------------------------------------------------------------- +. +This section describes the format output by GNU troff. +. +The output format used by GNU troff is very similar to that used +by Unix device-independent troff. +. +Only the differences are documented here. +. +. +.\" -------------------------------------------------------------------- +.SS "Units" +.\" -------------------------------------------------------------------- +. +The argument to the +.B s +command is in scaled points (units of +.RI points/ n , +where +.I n +is the argument to the +.B sizescale +command in the DESC file). +. +The argument to the +.B x\ Height +command is also in scaled points. +. +. +.\" -------------------------------------------------------------------- +.SS "Text Commands" +.\" -------------------------------------------------------------------- +. +.TP +.BI N n +Print character with index\~\c +.I n +(a non-negative integer) of the current font. +. +.P +If the +.B tcommand +line is present in the DESC file, troff will use the following two +commands. +. +.TP +.BI t xxx +.I xxx +is any sequence of characters terminated by a space or a newline; the +first character should be printed at the current position, the current +horizontal position should be increased by the width of the first +character, and so on for each character. +. +The width of the character is that given in the font file, +appropriately scaled for the current point size, and rounded so that +it is a multiple of the horizontal resolution. +. +Special characters cannot be printed using this command. +. +.TP +.BI u n\ xxx +This is same as the +.B t +command except that after printing each character, the current +horizontal position is increased by the sum of the width of that +character and +.IR n . +. +.P +Note that single characters can have the eighth bit set, as can the +names of fonts and special characters. +. +.P +The names of characters and fonts can be of arbitrary length; drivers +should not assume that they will be only two characters long. +. +.P +When a character is to be printed, that character will always be +in the current font. +. +Unlike device-independent troff, it is not necessary for drivers to +search special fonts to find a character. +. +.P +For color support, some new commands have been added: +. +.TP +.Text \f[B]mc \f[I]cyan magenta yellow\f[R] +.TQ +.Text \f[B]md\f[R] +.TQ +.Text \f[B]mg \f[I]gray\f[R] +.TQ +.Text \f[B]mk \f[I]cyan magenta yellow black\f[R] +.TQ +.Text \f[B]mr \f[I]red green blue\f[R] +Set the color components of the current drawing color, using various +color schemes. +. +.B md +resets the drawing color to the default value. +. +The arguments are integers in the range 0 to 65536. +. +.P +The +.B x +device control command has been extended. +. +.TP +.Text \f[B]x u \f[I]n\f[R] +If +.I n +is\~1, start underlining of spaces. +. +If +.I n +is\~0, stop underlining of spaces. +. +This is needed for the +.B cu +request in nroff mode and is ignored otherwise. +. +. +.\" -------------------------------------------------------------------- +.SS "Drawing Commands" +.\" -------------------------------------------------------------------- +. +The +.B D +drawing command has been extended. +. +These extensions will not be used by GNU pic if the +.B \-n +option is given. +. +.TP +.Text \f[B]Df \f[I]n\f[R]\*[ic]\[rs]n +Set the shade of gray to be used for filling solid objects to +.IR n ; +.I n +must be an integer between 0 and 1000, where 0 corresponds solid white +and 1000 to solid black, and values in between correspond to +intermediate shades of gray. +. +This applies only to solid circles, solid ellipses and solid +polygons. +. +By default, a level of 1000 will be used. +. +Whatever color a solid object has, it should completely obscure +everything beneath it. +. +A value greater than 1000 or less than 0 can also be used: this means +fill with the shade of gray that is currently being used for lines and +text. +. +Normally this will be black, but some drivers may provide a way of +changing this. +. +.TP +.Text \f[B]DC \f[I]d\f[R]\*[ic]\[rs]n +Draw a solid circle with a diameter of +.I d +with the leftmost point at the current position. +. +.TP +.Text \f[B]DE \f[I]dx dy\f[R]\*[ic]\[rs]n +Draw a solid ellipse with a horizontal diameter of +.I dx +and a vertical diameter of +.I dy +with the leftmost point at the current position. +.EQ +delim $$ +.EN +. +.TP +.Text \f[B]Dp\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n +Draw a polygon with, for $i = 1 ,..., n+1$, the +.IR i -th +vertex at the current position +. +$+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. +. +At the moment, GNU pic only uses this command to generate triangles +and rectangles. +. +.TP +.Text \f[B]DP\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n +. +Like +.B Dp +but draw a solid rather than outlined polygon. +. +.TP +.Text \f[B]Dt \f[I]n\f[R]\*[ic]\[rs]n +Set the current line thickness to +.I n +machine units. +. +Traditionally Unix troff drivers use a line thickness proportional to +the current point size; drivers should continue to do this if no +.B Dt +command has been given, or if a +.B Dt +command has been given with a negative value of +.IR n . +A zero value of +.I n +selects the smallest available line thickness. +. +.P +A difficulty arises in how the current position should be changed after +the execution of these commands. +. +This is not of great importance since the code generated by GNU pic +does not depend on this. +. +Given a drawing command of the form +.IP +\f[B]\[rs]D\[fm]\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\[fm] +. +.P +where +.I c +is not one of +.BR c , +.BR e , +.BR l , +.BR a , +or +.BR ~ , +Unix troff will treat each of the $x sub i$ as a horizontal quantity, +and each of the $y sub i$ as a vertical quantity and will assume that +the width of the drawn object is $sum from i=1 to n x sub i$, +and that the height is $sum from i=1 to n y sub i$. +. +(The assumption about the height can be seen by examining the +.B st +and +.B sb +registers after using such a +.B D +command in a \[rs]w escape sequence). +. +This rule also holds for all the original drawing commands with the +exception of +.BR De . +For the sake of compatibility GNU troff also follows this rule, even +though it produces an ugly result in the case of the +.BR Dt , +and, to a lesser extent, +.B DE +commands. +. +Thus after executing a +.B D +command of the form +.IP +\f[B]D\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ \c +$x sub n$ $y sub n$\[rs]n +. +.P +the current position should be increased by +. +$( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$. +. +.P +Another set of extensions is +. +.TP +.Text \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DFd\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DFg \f[I]gray\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n +Set the color components of the filling color similar to the +.B m +commands above. +. +.P +Note that +.B Df +is now mapped onto +.BR DFg . +The current position isn't changed by those colour commands. +. +. +.\" -------------------------------------------------------------------- +.SS "Device Control Commands" +.\" -------------------------------------------------------------------- +. +There is a continuation convention which permits the argument to the +.B x\ X +command to contain newlines: when outputting the argument to the +.B x\ X +command, GNU troff will follow each newline in the argument with a +.B + +character (as usual, it will terminate the entire argument with a +newline); thus if the line after the line containing the +.B x\ X +command starts with +.BR + , +then the newline ending the line containing the +.B x\ X +command should be treated as part of the argument to the +.B x\ X +command, the +.B + +should be ignored, and the part of the line following the +.B + +should be treated like the part of the line following the +.B x\ X +command. +. +.P +The first three output commands are guaranteed to be: +.IP +.BI x\ T\ device +.br +.BI x\ res\ n\ h\ v +.br +.B x init +. +. +.\" -------------------------------------------------------------------- +.SH INCOMPATIBILITIES +.\" -------------------------------------------------------------------- +. +In spite of the many extensions, groff has retained compatibility to +classical troff to a large degree. +. +For the cases where the extensions lead to collisions, a special +compatibility mode with the restricted, old functionality was created +for groff. +. +. +.\" -------------------------------------------------------------------- +.SS "Groff Language" +.\" -------------------------------------------------------------------- +. +.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. +. +.P +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 n(.C +is\~1 if compatibility mode is on, 0\~otherwise. +. +.P +This became necessary because the GNU concept for long names causes +some incompatibilities. +.I Classical troff +interprets +.IP +.request .dsabcd +. +.P +as defining a string +.B ab +with contents +.BR cd . +In +.IR groff +mode, this will be considered as a call of a macro named +.request dsabcd . +. +.P +Also +.I classical troff +interprets +.esc *[ +or +.esc n[ +as references to a string or number register called +.request [ +while +.I groff +takes this as the start of a long name. +. +.P +In +.IR "compatibility mode" , +groff interprets these things in the traditional way; so long +names are not recognized. +. +.P +On the other hand, groff in +.I GNU native mode +does not allow to use the single-character escapes +.esc \[rs] +(backslash), +.esc | +(vertical bar), +.esc ^ +(caret), +.esc & +(ampersand), +.esc { +(opening brace), +.esc } +(closing brace), +.squoted "\[rs]\ " +(space), +.esc ' +(single quote), +.esc ` +(backquote), +.esc \- +(minus), +.esc _ +(underline), +.esc ! +(bang), +.esc % +(percent), +and +.esc c +(character c) in names of strings, macros, diversions, number +registers, fonts or environments, whereas +.I classical troff +does. +. +.P +The +.esc A +escape sequence can be helpful in avoiding these escape sequences in +names. +. +.P +Fractional pointsizes cause one noteworthy incompatibility. +. +In +.I classical +.IR troff , +the +.request ps +request ignores scale indicators and so +.RS +.P +.B .ps\~10u +.RE +. +.P +will set the pointsize to 10\~points, whereas in groff native mode the +pointsize will be set to 10\~scaled points. +. +.P +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. +. +.P +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. +. +.P +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. +. +.P +.RS +.nf +.ft CB +.Text .di x +.Text \[rs]\[rs]\[rs]\[rs] +.Text .br +.Text .di +.Text .x +.ft +.fi +.RE +. +.P +In +.I GNU mode +this will be printed as +.esc \[rs] . +So each pair of input backslashes +.squoted \[rs]\[rs] +is turned into a single output backslash +.squoted \[rs] +and the resulting output backslashes are not interpreted as escape +characters when they are reread. +. +.P +.I Classical troff +would interpret them as escape characters when they were reread and +would end up printing a single backslash +.squoted \[rs] . +. +.P +In GNU, the correct way to get a printable version of the backslash +character +.squoted \[rs] +is the +.esc (rs +escape sequence, but classical troff does not provide a clean feature +for getting a non-syntactical backslash. +. +A close method is the printable version of the current escape +character using the +.esc e +escape sequence; this works if the current escape character is not +redefined. +. +It works in both GNU mode and compatibility mode, while dirty tricks +like specifying a sequence of multiple backslashes do not work +reliably; for the different handling in diversions, macro definitions, +or text mode quickly leads to a confusion about the necessary number of +backslashes. +. +.P +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. +. +. +.\" -------------------------------------------------------------------- +.SS "Intermediate Output" +.\" -------------------------------------------------------------------- +. +The groff intermediate output format is in a state of evolution. +. +So far it has some incompatibilities, but it is intended to establish +a full compatibility to the classical troff output format. +. +Actually the following incompatibilities exist: +. +.Topic +The positioning after the drawing of the polygons conflicts with the +classical definition. +. +.Topic +The intermediate output cannot be rescaled to other devices as +classical "device-independent" troff did. +. +. +.\" -------------------------------------------------------------------- +.SH AUTHORS +.\" -------------------------------------------------------------------- +. +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +This document was written by James Clark, with modifications by +.MTO wl@gnu.org "Werner Lemberg" +and +.MTO bwarken@mayn.de "Bernd Warken" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +Formerly, the contents of this document was kept in the manual +page +.BR @g@troff (@MAN1EXT@). +Only the parts dealing with the language aspects of the different +.I roff +systems were carried over into this document. +. +The +.I troff +command line options and warnings are still documented in +.BR @g@troff (@MAN1EXT@). +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +The +.I groff info +.IR file , +cf.\& +.BR info (1) +presents all groff documentation within a single document. +. +.TP +.BR groff (@MAN1EXT@) +A list of all documentation around +.IR groff . +. +.TP +.BR groff (@MAN7EXT@) +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 using +. +.IP +.ShellCommand man\~7\~groff +. +.TP +.BR roff (@MAN7EXT@) +A survey of +.I roff +systems, including pointers to further historical documentation. +. +.TP +.RI [ CSTR\~#54\/ ] +The +.I Nroff/\:Troff User's Manual +by +.I J.\& F.\& Osanna +of 1976 in the revision of +.I Brian Kernighan +of 1992, being the +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz \ + "classical troff documentation" . +. +. +.\" -------------------------------------------------------------------- +.\" Emacs variables +.\" -------------------------------------------------------------------- +. +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/contrib/groff/man/groff_font.man b/contrib/groff/man/groff_font.man index 17821b8..07fe520 100644 --- a/contrib/groff/man/groff_font.man +++ b/contrib/groff/man/groff_font.man @@ -1,5 +1,5 @@ .ig -Copyright (C) 1989-1995, 2001 Free Software Foundation, Inc. +Copyright (C) 1989-1995, 2001, 2002 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -16,29 +16,37 @@ versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English. .. +. .de TQ .br .ns .TP \\$1 .. +. .\" Like TP, but if specified indent is more than half .\" the current line-length - indent, use the default indent. .de Tp .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP .el .TP "\\$1" .. +. +. .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@" +. +. .SH NAME groff_font \- format of groff device and font description files +. +. .SH DESCRIPTION The groff font format is roughly a superset of the ditroff font format. -Unlike the ditroff font format, there is no associated binary -format. +. The font files for device .I name are stored in a directory .BI dev name. +. There are two types of file: a device description file called .B DESC @@ -46,131 +54,243 @@ and for each font .I F a font file called .IR F . +. These are text files; +unlike the ditroff font format, there is no associated binary format. +. +. .SS DESC file format -The DESC file can contain the following types of line: +. +The DESC file can contain the following types of line as shown below. +. +Later entries in the file override previous values. +. .TP -.BI res\ n -There are -.I n -machine units per inch. +.B charset +This line and everything following in the file are ignored. +. +It is allowed for the sake of backwards compatibility. +. +.TP +.BI family\ fam +The default font family is +.IR fam . +. +.TP +.BI fonts\ n\ F1\ F2\ F3\|.\|.\|.\|Fn +Fonts +.I F1\|.\|.\|.\|Fn +will be mounted in the font positions +.IR m +1,\|.\|.\|., m + n +where +.I m +is the number of styles. +. +This command may extend over more than one line. +. +A font name of +.B 0 +will cause no font to be mounted on the corresponding font position. +. .TP .BI hor\ n The horizontal resolution is .I n machine units. +. .TP -.BI vert\ n -The vertical resolution is -.I n -machine units. +.BI paperheight\ n +The physical vertical dimension of the output medium in machine units. +. +This isn't used by +.B troff +itself; currently, only +.B grops +uses it. +. .TP -.BI sizescale\ n -The scale factor for pointsizes. -By default this has a value of 1. -One -.I -scaled point -is equal to -one -.RI point/ n . -The arguments to the -.B unitwidth +.BI paperwidth\ n +The physical horizontal dimension of the output medium in machine units. +. +This isn't used by +.BR troff . +. +Currently, only the +.B grolbp +output device uses it. +. +.TP +.BI papersize\ string +Select a paper size. +. +Valid values for +.I string +are the ISO paper types A0-A7, B0-B7, C0-C7, D0-D7, DL, and the US paper +types letter, legal, tabloid, ledger, statement, executive, com10, and +monarch. +. +Case is not significant for +.IR string +if it holds predefined paper types. +. +Alternatively, +.I string +can be a file name (e.g.\& `/etc/papersize'); if the file can be opened, +.B groff +reads the first line and tests for the above paper sizes. +. +Finally, +.I string +can be a custom paper size in the format +.IB length , width +(no spaces before and after the comma). +. +Both +.I length and -.B sizes -commands are given in scaled points. +.I width +must have a unit appended; valid values are `i' for inches, `c' for +centimeters, `p' for points, and `P' for picas. +. +Example: +.BR 12c,235p . +. +An argument which starts with a digit is always treated as a custom paper +format. +. +.B papersize +sets both the vertical and horizontal dimension of the output medium. +. +.IP +More than one argument can be specified; +.B groff +scans from left to right and uses the first valid paper specification. +. +. .TP -.BI unitwidth\ n -Quantities in the font files are given in machine units -for fonts whose point size is -.I n -scaled points. +.B pass_filenames +Make troff tell the driver the source file name being processed. +. +This is achieved by another tcommand: +.B F +.IR filename . +. +.TP +.BI postpro\ program +Use +.I program +as the postprocessor. +. .TP .BI prepro\ program Call .I program as a preprocessor. +. .TP -.BI postpro\ program +.BI print\ program Use .I program -as the postprocessor. -.TP -.B tcommand -This means that the postprocessor can handle the -.B t +as the spooler program for printing. +. +If omitted, the +.B \-l and -.B u -output commands. +.B \-L +options of +.B groff +are ignored. +. +.TP +.BI res\ n +There are +.I n +machine units per inch. +. .TP .BI sizes\ s1\ s2\|.\|.\|.\|sn\ 0 This means that the device has fonts at .IR s1 , .IR s2 ,\|.\|.\|.\| sn scaled points. +. The list of sizes must be terminated by a .BR 0 . +. Each -.BI s i +.I si can also be a range of sizes .IR m \- n . +. The list can extend over more than one line. +. +.TP +.BI sizescale\ n +The scale factor for pointsizes. +. +By default this has a value of 1. +. +One +.I +scaled point +is equal to +one +.RI point/ n . +. +The arguments to the +.B unitwidth +and +.B sizes +commands are given in scaled points. +. .TP .BI styles\ S1\ S2\|.\|.\|.\|Sm The first .I m font positions will be associated with styles .IR S1\|.\|.\|.\|Sm . +. .TP -.BI fonts\ n\ F1\ F2\ F3\|.\|.\|.\|Fn -Fonts -.I F1\|.\|.\|.\|Fn -will be mounted in the font positions -.IR m +1,\|.\|.\|., m + n -where -.I m -is the number of styles. -This command may extend over more than one line. -A font name of -.B 0 -will cause no font to be mounted on the corresponding font position. +.B tcommand +This means that the postprocessor can handle the +.B t +and +.B u +output commands. +. .TP -.BI family\ fam -The default font family is -.IR fam . +.BI unitwidth\ n +Quantities in the font files are given in machine units +for fonts whose point size is +.I n +scaled points. +. .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. -.TP -.BI print\ program -Use -.I program -as the spooler program for printing. -If omitted, the -.B \-l -and -.B \-L -options of -.B groff -are ignored. +.BI vert\ n +The vertical resolution is +.I n +machine units. +. .LP -The res, unitwidth, fonts and sizes lines are compulsory. +The +.BR res , +.BR unitwidth , +.BR fonts , +and +.B sizes +lines are compulsory. +. 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 @@ -178,29 +298,21 @@ 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 +. +A font file has two sections. +The first section is a sequence of lines each containing a sequence of blank delimited words; the first word in the line is a key, and subsequent words give a value for that key. -.TP -.BI name\ F -The name of the font is -.IR F . -.TP -.BI spacewidth\ n -The normal width of a space is -.IR n . -.TP -.BI slant\ n -The characters of the font have a slant of -.I n -degrees. (Positive means forward.) +. .TP .BI ligatures\ lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR] Characters .IR lig1 , -.IR lig2 ,\|.\|.\|., lign +.IR lig2 ,\ \|.\|.\|.,\ lign are ligatures; possible ligatures are .BR ff , .BR fi , @@ -208,10 +320,31 @@ are ligatures; possible ligatures are .B ffi and .BR ffl . +. For backwards compatibility, the list of ligatures may be terminated with a .BR 0. +. The list of ligatures may not extend over more than one line. +. +.TP +.BI name\ F +The name of the font is +.IR F . +. +.TP +.BI slant\ n +The characters of the font have a slant of +.I n +degrees. +. +(Positive means forward.) +. +.TP +.BI spacewidth\ n +The normal width of a space is +.IR n . +. .TP .B special The font is @@ -219,40 +352,54 @@ The font is this means that when a character is requested that is not present in the current font, it will be searched for in any special fonts that are mounted. +. .LP Other commands are ignored by .B troff but may be used by postprocessors to store arbitrary information about the font in the font file. +. .LP The first section can contain comments which start with the .B # character and extend to the end of a line. +. .LP The second section contains one or two subsections. +. It must contain a .I charset subsection and it may also contain a .I kernpairs subsection. +. These subsections can appear in any order. +. Each subsection starts with a word on a line by itself. +. .LP The word .B charset starts the charset subsection. +. The .B charset line is followed by a sequence of lines. +. Each line gives information for one character. +. A line comprises a number of fields separated -by blanks or tabs. The format is +by blanks or tabs. +. +The format is +. .IP .I name metrics type code .RI [ entity_name ] .RB [ -- .IR comment ] +. .LP .I name identifies the character: @@ -263,55 +410,73 @@ is a single character then it corresponds to the groff input character .IR c ; if it is of the form -.BI \e c +.BI \[rs] c where c is a single character, then it -corresponds to the groff input character -.BI \e c\fR; +corresponds to the special character +.BI \[rs][ c ]\fR; otherwise it corresponds to the groff input character -.BI \e[ name ] -(if it is exactly two characters +.BI \[rs][ name ]\fR. +. +If it is exactly two characters .I xx it can be entered as -.BI \e( xx\fR). -Groff supports eight bit characters; however some utilities -has difficulties with eight bit characters. +.BI \[rs]( xx\fR. +. +Note that single-letter special characters can't be accessed as +.BI \[rs] c\fR; +the only exception is `\[rs]-' which is identical to `\[rs][-]'. +. +The name +.B \-\-\- +is special and indicates that the character is unnamed; +such characters can only be used by means of the +.B \[rs]N +escape sequence in +.BR troff . +. +.LP +Groff supports eight-bit characters; however some utilities +have difficulties with eight-bit characters. +. For this reason, there is a convention that the name .BI char n is equivalent to the single character whose code is -.I n . +.IR n . +. For example, .B char163 would be equivalent to the character with code 163 which is the pounds sterling sign in ISO Latin-1. -The name -.B \-\-\- -is special and indicates that the character is unnamed; -such characters can only be used by means of the -.B \eN -escape sequence in -.BR troff . +. .LP The .I type field gives the character type: +. .TP 1 -means the character has an descender, for example, p; +means the character has a descender, for example, p; +. .TP 2 means the character has an ascender, for example, b; +. .TP 3 means the character has both an ascender and a descender, for example, (. +. .LP The .I code field gives the code which the postprocessor uses to print the character. +. The character can also be input to groff using this code by means of the -.B \eN +.B \[rs]N escape sequence. +. The code can be any integer. +. If it starts with a .B 0 it will be interpreted as octal; @@ -320,40 +485,60 @@ if it starts with or .B 0X it will be intepreted as hexadecimal. +. +Note, however, that the +.B \[rs]N +escape sequence only accepts a decimal integer. +. .LP 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. +. +For example, the character `\[rs][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 -field has the form: +field has the form (in one line; it is broken here for the sake of +readability): +. .IP -.IR width [\fB, height [\fB, depth [\fB, italic_correction [\fB, \ -left_italic_correction [\fB, subscript_correction ]]]]] +.IR width [\fB, height [\fB, depth [\fB, italic-correction +.br +.RI [\fB, left-italic-correction [\fB, subscript-correction ]]]]] +. .LP There must not be any spaces between these subfields. +. Missing subfields are assumed to be 0. +. The subfields are all decimal integers. +. Since there is no associated binary format, these values are not required to fit into a variable of type .B char as they are in ditroff. +. The .I width subfields gives the width of the character. +. The .I height subfield gives the height of the character (upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative height. +. The .I depth subfield gives the depth of the character, that is, the distance @@ -361,39 +546,49 @@ below the lowest point below the baseline to which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be given a zero depth, rather than a negative depth. +. The -.I italic_correction +.I italic-correction subfield gives the amount of space that should be added after the character when it is immediately to be followed by a character from a roman font. +. The -.I left_italic_correction +.I left-italic-correction subfield gives the amount of space that should be added before the character when it is immediately to be preceded by a character from a roman font. +. The -.I subscript_correction +.I subscript-correction gives the amount of space that should be added after a character before adding a subscript. +. This should be less than the italic correction. +. .LP A line in the charset section can also have the format +. .IP .I name \fB" +. .LP This indicates that .I name is just another name for the character mentioned in the preceding line. +. .LP The word .B kernpairs starts the kernpairs section. +. This contains a sequence of lines of the form: +. .IP -.I -c1 c2 n +.I c1 c2 n +. .LP This means that when character .I c1 @@ -401,20 +596,28 @@ appears next to character .I c2 the space between them should be increased by .IR n . +. Most entries in kernpairs section will have a negative value for .IR n . +. +. .SH FILES +. .Tp \w'@FONTDIR@/devname/DESC'u+3n .BI @FONTDIR@/dev name /DESC Device description file for device .IR name . +. .TP .BI @FONTDIR@/dev name / F Font file for font .I F of device .IR name . +. +. .SH "SEE ALSO" +. .BR groff_out (@MAN5EXT@), .BR @g@troff (@MAN1EXT@). . diff --git a/contrib/groff/man/groff_tmac.man b/contrib/groff/man/groff_tmac.man new file mode 100644 index 0000000..c0d3421 --- /dev/null +++ b/contrib/groff/man/groff_tmac.man @@ -0,0 +1,1124 @@ +. +.TH GROFF_TMAC @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_tmac \- macro files in the roff typesetting system +.SH DESCRIPTION +.\" The .SH was moved to this place to make `apropos' happy. +. +. +.\" -------------------------------------------------------------------- +.\" Legalize +.\" -------------------------------------------------------------------- +. +.ig +groff_tmac.5 + +File position: <groff-source>/man/groff_tmac.man + +Last update: 21 Aug 2002 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. +written by Bernd Warken <bwarken@mayn.de> and Werner Lemberg +<wl@gnu.org> + +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 +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.ds Ellipsis \&.\|.\|.\&\" +. +.\" Global static variables for inter-macro communication +.rr @+Example_font +. +.\" -------------------------------------------------------------------- +.\" setup for the macro definitions below +.\" +.\" naming: namespace:cathegory_macro.variable_name (experimental) +. +.\" -------------------------------------------------------------------- +.\" configuration of prompt for `.Shell_cmd'* macros +.ds groffer:Shell_cmd.prompt_text sh#\" prompt for shell commands +.ds groffer:Shell_cmd+.prompt_text >\" prompt on continuation lines +.ds groffer:Shell_cmd_base.prompt_font I\" font for prompts +. +.\" automatically determine setup from the configuration above +.als @f groffer:Shell_cmd_base.prompt_font\" +.als @t groffer:Shell_cmd.prompt_text\" +.als @t+ groffer:Shell_cmd+.prompt_text\" +.ds groffer:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed +.ds groffer:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed +.nr @w \w'\*[groffer:Shell_cmd.prompt]'\" +.nr @w+ \w'\*[groffer:Shell_cmd+.prompt]'\" +.ft \*[@f] +.\" Full prompt width is maximum of texts plus 1m +.nr groffer:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed +.ft +.rm @f +.rm @f+ +.rm @t +.rm @t+ +.rr @w +.rr @w+ +. +.\"-------------------------------------------------------------------- +.\" Ignore all arguments like a comment, even after a .eo call. +.de c +.. +.c -------------------------------------------------------------------- +.de BIR +. ie (\\n[.$] < 3) \ +. BI \\$@ +. el \{\ +. ds @tmp@ \fB\\$1\f[]\fI\\$2\f[] +. shift 2 +. Text \\*[@tmp@]\fR\\$*\f[] +. rm @tmp@ +. \} +.. +.c -------------------------------------------------------------------- +.c .Env_var (<env_var_name> [<punct>]) +.c +.c Display an environment variable, with optional punctuation. +.c +.de Env_var +. nh +. SM +. Text \f[CB]\\$1\f[]\\$2 +. hy +.. +.c -------------------------------------------------------------------- +.c .Error (<text>...) +.c +.c Print error message to terminal and abort. +.c +.de Error +. tm \\$* +. ab +.. +.c -------------------------------------------------------------------- +.de Example +. if r@+Example_font \ +. Error previous .Example was not terminated by a ./Example +. nr @+Example_font \\n[.f] +. nh +. nf +. RS +. ft CR +.. +.c -------------------------------------------------------------------- +.de /Example +. if !r@+Example_font \ +. Error no previous call to .Example +. ft \\n[@+Example_font] +. RE +. fi +. hy +. rr @+Example_font +.. +. +.c -------------------------------------------------------------------- +.c .Shell_cmd (<CR> [<CI>] ...) +.c +.c A shell command line; display args alternating in fonts CR and CI. +.c +.c Examples: +.c .Shell_cmd "groffer --dpi 100 file" +.c result: `sh# groffer --dpi 100 file' +.c with 'sh#' in font I, the rest in CR +.c +.c .Shell_cmd groffer\~--dpi\~100\~file +.c result: the same as above +.c +.c .Shell_cmd "groffer --dpi=" value " file" +.c result: sh# groffer --dpi=value file +.c with `groffer --dpi=' and `file' in CR; `value' in CI +.c +.c .Shell_cmd groffer\~--dpi= value \~file +.c result: the same as the previous example +.c +.de Shell_cmd +. groffer:Shell_cmd_base "\*[groffer:Shell_cmd.prompt]" \\$@ +.. +.c -------------------------------------------------------------------- +.c .Shell_cmd+ (<CR> [<CI>] ...) +.c +.c A continuation line for .Shell_cmd. +.c +.de Shell_cmd+ +. groffer:Shell_cmd_base "\*[groffer:Shell_cmd+.prompt]" \\$@ +.. +.c -------------------------------------------------------------------- +.c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...]) +.c +.c A shell command line; display args alternating in fonts CR and CI. +.c Internal, do not use directly. +.c +.c Globals: read-only register @.Shell_cmd_width +.c +.de groffer:Shell_cmd_base +. if (\\n[.$] <= 0) \ +. return +. nr @+font \\n[.f]\" +. ds @prompt \\$1\" +. ft CR +. c gap between prompt and command +. nr @+gap \\n[groffer:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" +. ds @res \\*[@prompt]\h'\\n[@+gap]u'\" +. shift +. ds @cf CR\" +. while (\\n[.$] > 0) \{\ +. as @res \\f[\\*[@cf]]\\$1\" +. shift +. ie '\\*[@cf]'CR' \ +. ds @cf I\" +. el \ +. ds @cf CR\" +. \} +. br +. ad l +. nh +. nf +. Text \\*[@res]\" +. fi +. hy +. ad +. br +. ft \\n[@+font] +. rr @+font +. rr @+gap +. rm @cf +. rm @res +.. +.c -------------------------------------------------------------------- +.c .Text (<text>...) +.c +.c Treat the arguments as text, no matter how they look. +.c +.de Text +. if (\\n[.$] == 0) \ +. return +. nop \)\\$*\) +.. +.c -------------------------------------------------------------------- +.c .Topic ([<indent>]) +.c +.c A bulleted paragraph +.c +.de Topic +. ie (\\n[.$] = 0) \ +. ds @indent 2m\" +. el \ +. ds @indent \\$1\" +. TP \\*[@indent] +. Text \[bu] +. rm @indent +.. +.c -------------------------------------------------------------------- +.c .TP+ () +.c +.c Continuation line for .TP header. +.c +.de TP+ +. br +. ns +. TP \\$1 +.. +.c -------------------------------------------------------------------- +.de 'char +. ds @tmp@ `\f(CR\\$1\f[]' +. shift +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de option +. ds @tmp@ \f(CB\\$1\f[] +. shift 1 +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de argument +. ds @tmp@ \f(CI\\$1\f[] +. shift 1 +. Text \\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de request +. ds @tmp@ \f(CB\\$1\f[] +. shift 1 +. Text .\\*[@tmp@]\\$* +. rm @tmp@ +.. +.c -------------------------------------------------------------------- +.de escape +. ds @tmp@ \f[CB]\\$1\f[] +. shift 1 +. Text \[rs]\\*[@tmp@]\\$* +. rm @tmp@ +.. +.\" -------------------------------------------------------------------- +.\" SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +The +.BR roff (@MAN7EXT@) +type-setting system provides a set of macro packages suitable for +special kinds of documents. +. +Each macro package stores its macros and definitions in a file called +the package's +.BR "tmac file" . +The name is deduced from +.RB ` T\c +.IB roff MAC\c +.IR ros '. +. +.P +The tmac files are normal roff source documents, except that they +usually contain only definitions and setup commands, but no text. +. +All tmac files are kept in a single or a small number of directories, +the +.B tmac +directories. +. +. +.\" -------------------------------------------------------------------- +.SH "GROFF MACRO PACKAGES" +.\" -------------------------------------------------------------------- +. +.I groff +provides all classical macro packages, some more full packages, and +some secondary packages for special purposes. +. +. +.\" -------------------------------------------------------------------- +.SS "Man\~Pages" +.\" -------------------------------------------------------------------- +. +.TP +.B man +This is the classical macro package for UNIX manual pages +(man\~pages); it is quite handy and easy to use; see +.BR groff_man (@MAN7EXT@). +. +.TP +.B doc +.TP+ +.B mdoc +An alternative macro package for man\~pages mainly used in BSD +systems; it provides many new features, but it is not the standard for +man\~pages; see +.BR groff_mdoc (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS "Full Packages" +.\" -------------------------------------------------------------------- +. +The packages in this section provide a complete set of macros for +writing documents of any kind, up to whole books. +. +They are similar in functionality; it is a matter of taste which one +to use. +. +. +.TP +.B me +The classical +.I me +macro package; see +.BR groff_me (@MAN7EXT@). +. +. +.TP +.B mm +The semi-classical +.I mm +macro package; see +.BR groff_mm (@MAN7EXT@). +. +. +.TP +.B mom +The new +.I mom +macro package, only available in groff. +. +As this is not based on other packages, it can be freely designed. +. +So it is expected to become quite a nice, modern macro package. +. +See +.BR groff_mom (@MAN7EXT@). +. +. +.TP +.B ms +The classical +.I ms +macro package; see +.BR groff_ms (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS "Special Packages" +.\" -------------------------------------------------------------------- +. +The macro packages in this section are not intended for stand-alone +usage, but can be used to add special functionality to any other +macro package or to plain groff. +. +. +.TP +.B tty-char +Overrides the definition of standard troff characters and some groff +characters for tty devices. +. +The optical appearance is intentionally inferior compared to that of +normal tty formatting to allow processing with critical equipment. +. +. +.TP +.B www +Additions of elements known from the html format, as being used in the +internet (World Wide Web) pages; this includes URL links and mail +addresses; see +.BR groff_www (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SH NAMING +.\" -------------------------------------------------------------------- +. +In classical roff systems, there was a funny naming scheme for macro +packages, due to a simplistic design in option parsing. +. +Macro packages were always included by option +.option -m; +when this option was directly followed by its argument without an +intervening space, this looked like a long option preceded by a single +minus \[em] a sensation in the computer stone age. +. +To make this optically working for macro package names, all classical +macro packages choose a name that started with the letter +.'char m , +which was omitted in the naming of the macro file. +. +. +.P +For example, the macro package for the man pages was called +.IR man , +while its macro file +.IR tmac.an . +So it could be activated by the argument +.I an +to option +.option -m , +or +.option -man +for short. +. +. +.P +For similar reasons, macro packages that did not start with an +.'char m +had a leading +.'char m +added in the documentation and in talking; for example, the package +corresponding to +.I tmac.doc +was called +.I mdoc +in the documentation, although a more suitable name would be +.IR doc . +For, when omitting the space between the option and its argument, the +command line option for activating this package reads +.option "-mdoc" . +. +. +.P +To cope with all situations, actual versions of +.BR groff (@MAN1EXT@) +are smart about both naming schemes by providing two macro files +for the inflicted macro packages; one with a leading +.'char m , +the other one without it. +. +So in +.IR groff , +the +.I man +macro package may be specified as on of the following four methods: +. +.IP +.Shell_cmd "groff\~\-m\~man" +.Shell_cmd "groff\~\-man" +.Shell_cmd "groff\~\-mman" +.Shell_cmd "groff\~\-m\~an" +. +. +.P +Recent packages that do not start with +.'char m +do not use an additional +.'char m +in the documentation. +. +For example, the +.I www +macro package may be specified only as one of the two methods: +. +.IP +.Shell_cmd "groff\~\-m\~www" +.Shell_cmd "groff\~\-mwww" +. +. +.P +Obviously, variants like +.I -mmwww +would not make much sense. +. +. +.P +A second strange feature of classical troff was to name macro files +according to +.BIR tmac. name . +In modern operating systems, the type of a file is specified as +postfix, the file name extension. +. +Again, groff copes with this situation by searching both +.IB anything .tmac +and +.BI tmac. anything +if only +.I anything +is specified. +. +. +.P +The easiest way to find out which macro packages are available on a +system is to check the man\~page +.BR groff (@MAN1EXT@), +or the contents of the +.I tmac +directories. +. +. +.P +In +.IR groff , +most macro packages are described in\~man pages called +.BR groff_\f[I]name\f[] (@MAN7EXT@), +with a leading +.'char m +for the classical packages. +. +. +.\" -------------------------------------------------------------------- +.SH INCLUSION +.\" -------------------------------------------------------------------- +. +There are several ways to use a macro package in a document. +. +The classical way is to specify the troff/groff option +.option \-m +.argument name +at run-time; this makes the contents of the macro package +.I name +available. +. +In groff, the file +.IB name .tmac +is searched within the tmac path; if not found, +.BI tmac. name +will be searched for instead. +. +. +.P +Alternatively, it is also possible to include a macro file by adding +the request +.request so +.I filename +into the document; the argument must be the full file name of an +existing file, possibly with the directory where it is kept. +. +In groff, this was improved by the similar request +.request mso +.IR package , +which added searching in the tmac path, just like option +.option -m +does. +. +. +.P +Note that in order to resolve the +.request so +and +.request mso +requests, the roff preprocessor +.BR soelim (@MAN1EXT@) +must be called if the files to be included need preprocessing. +. +This can be done either directly by a pipeline on the command line or +by using the troff/groff option +.option \-s . +. +.I man +calls soelim automatically. +. +. +.P +For example, suppose a macro file is stored as +.I @MACRODIR@/macros.tmac +and is used in some document called +.IR docu.roff . +. +. +.P +At run-time, the formatter call for this is +. +.IP +.Shell_cmd "groff\~\-m\~" "macrofile\~document.roff" +. +. +.P +To include the macro file directly in the document either +. +.IP +.Example +. Text .mso macrofile.tmac +./Example +. +.P +is used or +. +.IP +.Example +. Text .so @MACRODIR@/macros.tmac +./Example +. +. +.P +In both cases, the formatter is called with +.IP +.Shell_cmd "troff\~\-s\~" docu.roff +. +. +.P +If you want to write your own groff macro file, call it +.IB whatever .tmac +and put it in some directory of the tmac path, see section +.BR FILES . +Then documents can include it with the +.request mso +request or the option +.option -m . +. +. +.ig +.\" -------------------------------------------------------------------- +.SH CONVENTION +.\" -------------------------------------------------------------------- +. +.\" This section does not fit into the framework of this document. +. +There is a convention that is supported by many modern roff +type-setters and +.BR man (1) +programs, the +.I preprocessor word +described in the following. +. +.P +If the first line in a document is a comment, the first word (after the +comment characters and a blank) constitutes the +.B preprocessor +.BR word . +That means that the letters of this word are interpreted as +abbreviations for those preprocessor commands that should be run +when formatting the document. +. +Mostly, only the letters corresponding to the options for the +preprocessors are recognized, +.'char e +(for +.BR eqn ), +.\" 'char G , +.\" 'char g , +.'char p , +(for +.BR pic ), +.'char R +(for +.BR refer ), +.'char s +(for +.BR soelim ), +and +.'char t +(for +.BR tbl ). +(see +.BR roff (@MAN7EXT@)). +. +. +.P +Besides being a good reminder for the user, some formatters (like the +.BR man (1) +program) are even able to automatically start the preprocessors +specified in the preprocessor word, but do not bet on this. +. +. +.P +The +.I man +program handles some preprocessors automatically, such that in +man\~pages only the following characters should be used: +.'char e , +.'char p , +and +.'char t . +. +. +.. +.\" -------------------------------------------------------------------- +.SH "WRITING MACROS" +.\" -------------------------------------------------------------------- +. +A +.BR roff (@MAN7EXT@) +document is a text file that is enriched by predefined formatting +constructs, such as requests, escape sequences, strings, numeric +registers, and macros from a macro package. +. +These elements are described in +.BR roff (@MAN7EXT@). +. +. +.P +To give a document a personal style, it is most useful to extend the +existing elements by defining some macros for repeating tasks; the best +place for this is near the beginning of the document or in a separate +file. +. +. +.P +Macros without arguments are just like strings. +. +But the full power of macros reveals when arguments are passed with a +macro call. +. +Within the macro definition, the arguments are available as the escape +sequences +.BR $1 , +\*[Ellipsis], +.BR $9 , +.BR $[ \*[Ellipsis] ] , +.BR $* , +and +.BR $@ , +the name under which the macro was called is in +.BR $0 , +and the number of arguments is in register +.BR \n[.$] ; +see +.BR groff (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SS "Copy-in Mode" +.\" -------------------------------------------------------------------- +. +The phase when groff reads a macro is called +.I "copy-in mode" +in roff-talk. +. +This is comparable to the C\~preprocessing phase during the development +of a program written in the C\~language. +. +. +.P +In this phase, groff interprets all backslashes; that means that all +escape sequences in the macro body are interpreted and replaced by +their value. +. +For constant expression, this is wanted, but strings and registers +that might change between calls of the macro must be protected from +being evaluated. +. +This is most easily done by doubling the backslash that introduces the +escape sequence. +. +This doubling is most important for the positional parameters. +. +For example, to print information on the arguments that were passed to +the macro to the terminal, define a macro named `.print_args', +say. +. +. +.P +.ds @1 \[rs]f[I]\[rs]\[rs]$0\[rs]f[]\" +.ds @2 arguments:\" +.Example +. Text .ds midpart was called with +. Text .de print_args +. Text .\~\~tm\~\*[@1]\~\[rs]\[rs]*[midpart]\~\[rs]\[rs]n[.$]\~\*[@2] +. Text .\~\~tm\~\[rs]\[rs]$* +. Text .. +./Example +.rm @1 +.rm @2 +. +. +.P +When calling this macro by +.P +.Example +. Text .print_args arg1 arg2 +./Example +.P +the following text is printed to the terminal: +.Example +. Text \f[CI]print_args\f[] was called with the following 2 arguments: +arg1 arg2 +./Example +. +. +.P +Let's analyze each backslash in the macro definition. +. +As the positional parameters and the number of arguments will change +with each call of the macro their leading backslash must be doubled, +which results in +.I \[rs]\[rs]$* +and +.IR \[rs]\[rs][.$] . +The same applies to the macro name because it could be called with an +alias name, so +.IR \[rs]\[rs]$0 . +. +. +.P +On the other hand, +.I midpart +is a constant string, it will not change, so no doubling for +.IR \[rs]*[midpart] . +The +.I \[rs]f +escape sequences are predefined groff elements for setting the font +within the text. +. +Of course, this behavior will not change, so no doubling with +.I \[rs]f[I] +and +.IR \[rs]f[] . +. +. +.\" -------------------------------------------------------------------- +.SS "Draft Mode" +.\" -------------------------------------------------------------------- +. +Writing groff macros is easy when the escaping mechanism is temporarily +disabled. +. +In groff, this is done by enclosing the macro definition(s) into a +pair of +.B .eo +and +.B .ec +requests. +. +Then the body in the macro definition is just like a normal part of +the document \[em] text enhanced by calls of requests, macros, +strings, registers, etc. +. +For example, the code above can be written in a simpler way by +. +. +.P +.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\" +.ds @2 arguments:\" +.Example +. Text .eo +. Text .ds midpart was called with +. Text .de print_args +. Text .\~\~tm\~\*[@1]\~\[rs]*[midpart]\~\[rs]n[.$]\~\*[@2] +. Text .\~\~tm\~\[rs]$* +. Text .. +. Text .ec +./Example +.rm @1 +.rm @2 +. +. +.P +Unfortunately, draft mode cannot be used universally. +. +Although it is good enough for defining normal macros, draft mode +will fail with advanced applications, such as indirectly defined +strings, registers, etc. +. +An optimal way is to define and test all macros in draft mode and then +do the backslash doubling as a final step; do not forget to remove the +.I .eo +request. +. +. +.\" -------------------------------------------------------------------- +.SS "Tips for Macro Definitions" +.\" -------------------------------------------------------------------- +. +.Topic +Start every line with a dot, for example, by using the groff request +.B .nop +for text lines, or write your own macro that handles also text lines +with a leading dot. +. +.IP +.Example +. Text .de Text +. Text .\~\~if (\[rs]\[rs]n[.$] == 0)\~\[rs] +. Text .\~\~\~\~return +. Text .\~nop\~\[rs])\[rs]\[rs]$*[rs]\) +. Text .. +./Example +. +.Topic +Write a comment macro that works both for copy-in and draft mode; for +as escaping is off in draft mode, trouble might occur when normal +comments are used. +. +For example, the following macro just ignores its arguments, so it +acts like a comment line: +. +.IP +.Example +. Text .de\~c +. Text .. +. Text .c\~This\~is\~like\~a\~comment\~line. +./Example +. +.Topic +In long macro definitions, make ample use of comment lines or empty +lines for a better structuring. +. +.Topic +To increase readability, use groff's indentation facility for requests +and macro calls (arbitrary whitespace after the leading dot). +. +. +.\" -------------------------------------------------------------------- +.SS "Diversions" +.\" -------------------------------------------------------------------- +. +Diversions can be used to realize quite advanced programming +constructs. +. +They are comparable to pointers to large data structures in the +C\~programming language, but their usage is quite different. +. +. +.P +In their simplest form, diversions are multi-line strings, but +they get their power when diversions are used dynamically within macros. +. +The information stored in a diversion can be retrieved by calling the +diversion just like a macro. +. +. +.P +Most of the problems arising with diversions can be avoided if you are +conscious about the fact that diversions always deal with complete +lines. +. +If diversions are used when the line buffer has not been flashed, +strange results are produced; not knowing this, many people get +desperate about diversions. +. +To ensure that a diversion works, line breaks should be added at the +right places. +. +To be on the secure side, enclose everything that has to do with +diversions into a pair of line breaks; for example, by amply using +.B .br +requests. +. +This rule should be applied to diversion definition, both inside and +outside, and to all calls of diversions. +. +This is a bit of overkill, but it works nicely. +. +. +.P +[If you really need diversions which should ignore the current partial +line, use environments to save the current partial line and/\:or use the +.B .box +request.] +. +. +.P +The most powerful feature using diversions is to start a diversion +within a macro definition and end it within another macro. +. +Then everything between each call of this macro pair is stored within +the diversion and can be manipulated from within the macros. +. +. +.\" -------------------------------------------------------------------- +.SH FILES +.\" -------------------------------------------------------------------- +. +All macro names must be named +.IB name .tmac +to fully use the tmac mechanism. +. +.BI tmac. name +as with classical packages is possible as well, but deprecated. +. +. +.P +The macro files are kept in the +.IR "tmac directories" ; +a colon separated list of these constitutes the +.IR "tmac path" . +. +. +.P +The search sequence for macro files is (in that order): +. +.Topic +the directories specified with troff/groff's +.B \-M +command line option +. +.Topic +the directories given in the +.Env_var $GROFF_TMAC_PATH +environment variable +. +.Topic +the current directory (only if in unsafe mode, which is enabled by the +.B \-U +command line switch) +. +.Topic +the home directory +. +.Topic +a platform-specific directory, being +.B @SYSTEMMACRODIR@ +in this installation +. +.Topic +a site-specific (platform-independent) directory, being +.B @LOCALMACRODIR@ +in this installation +. +.Topic +the main tmac directory, being +.B @MACRODIR@ +in this installation +. +. +.\" -------------------------------------------------------------------- +.SH ENVIRONMENT +.\" -------------------------------------------------------------------- +. +.TP +.Env_var $GROFF_TMAC_PATH +A colon separated list of additional tmac directories in which to search +for macro files. +. +See the previous section for a detailed description. +. +. +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.MTO bwarken@mayn.de "Bernd Warken" ; +it is maintained by +.MTO wl@gnu.org "Werner Lemberg" . +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +A complete reference for all parts of the groff system is found in the +groff +.BR info (1) +file. +. +.TP +.BR groff (@MAN1EXT@) +an overview of the groff system. +. +.TP +.BR groff_man (@MAN7EXT@), +.TP+ +.BR groff_mdoc (@MAN7EXT@), +.TP+ +.BR groff_me (@MAN7EXT@), +.TP+ +.BR groff_mm (@MAN7EXT@), +.TP+ +.BR groff_mom (@MAN7EXT@), +.TP+ +.BR groff_ms (@MAN7EXT@), +.TP+ +.BR groff_www (@MAN7EXT@). +the groff tmac macro packages. +. +.TP +.BR groff (@MAN7EXT@) +the groff language. +. +. +.P +The Filesystem Hierarchy Standard is available at the +.URL http://\:www.pathname.com/\:fhs/ "FHS web site" . +. +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/contrib/groff/man/roff.man b/contrib/groff/man/roff.man index 2897ac0..5a9c5b5 100644 --- a/contrib/groff/man/roff.man +++ b/contrib/groff/man/roff.man @@ -1,16 +1,18 @@ -'\" t .ig -roff.7 +roff.man + +Last update: 22 Apr 2002 This file is part of groff, the GNU roff type-setting system. -Copyright (C) 2000, 2001 Free Software Foundation, Inc. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. written by Bernd Warken <bwarken@mayn.de> +maintained by Werner Lemberg <wl@gnu.org> 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 +Invariant Sections being this .ig-section and AUTHORS, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the Free Documentation License is included as a file called @@ -21,6 +23,8 @@ FDL in the main directory of the groff source package. .\" Setup .\" -------------------------------------------------------------------- . +.mso www.tmac +. .if n \{\ . mso tty-char.tmac . ftr CR R @@ -28,304 +32,888 @@ FDL in the main directory of the groff source package. . ftr CB B .\} . -.\" text lines in macro definitions or bracketed sections \{...\} -.de text -. if 1 \&\\$*\& +.if '\*[.T]'dvi' \{\ +. ftr CB CW +.\} +. +. +.\" -------------------------------------------------------------------- +.\" String definitions +. +.\" Final `\""' comments are used to make Emacs happy, sic \"" +. +.\" The `-' sign for options. +.ie t \{\ +. ds @- \-\" +. ds @-- \-\-\" +.\} +.el \{\ +. ds @- -\" +. ds @-- --\" +.\} +. +.ds Comment \.\[rs]\[dq]\" +.ds Ellipsis \.\|.\|.\&\" +. +. +.\" -------------------------------------------------------------------- +.\" Begin of macro definitions +. +.de c +.\" this is like a comment request when escape mechanism is off .. . -.de option -. ds @tmp@ \f(CB\\$1\fP -. shift 1 -. text \\*[@tmp@]\\$* -. rm @tmp@ +.eo +. +.c --------------------------------------------------------------------- +. +.de Text +. nop \)\$* .. . -.de 'char -. ds @tmp@ `\f(CB\\$1\fP' +.de CodeSkip +. ie t \ +. sp 0.2v +. el \ +. sp +.. +. +.de Esc +. ds @1 \$1\" . shift -. text \\*[@tmp@]\\$* -. rm @tmp@ +. Text \f[B]\[rs]\*[@1]\f[]\$* +. rm @1 .. . -.de esc -. ds @tmp@ \f(CB\e\\$1\fP +.de QuotedChar +. ds @1 \$1 . shift -. text \\*[@tmp@]\\$* -. rm @tmp@ +. nop `\f[B]\*[@1]\f[]'\$* +. rm @1 .. . -.de argname -. ds @tmp@ \f(CI\\$1\fP -. shift 1 -. text \\*[@tmp@]\\$* -. rm @tmp@ +.c -------------------------------------------------------------------- +. +.c a shell command line +.de ShellCommand +. br +. ad l +. nh +. Text \f[I]sh#\h'1m'\f[]\f[CR]\$*\f[]\&\" +. ft R +. ft P +. hy +. ad .. . -.de prefixednumber -. ds @tmp@ \&\\$1\ \f(CR\\$2\fP -. shift 2 -. text \\*[@tmp@]\\$* -. rm @tmp@ +.c -------------------------------------------------------------------- +. +.c ShortOpt ([c [punct]]) +.c +.c `-c' somewhere in the text. +.c The second argument is some trailing punctuation. +.c +.de ShortOpt +. ds @1 \$1\" +. shift +. nh +. Text \f[CB]\*[@-]\f[]\f[B]\*[@1]\f[]\/\$* +. hy +. rm @1 +.. +. +.de TP+ +. br +. ns +. TP \$1 .. . -.de TQ -.br -.ns -.TP \\$1 +.c -------------------------------------------------------------------- +. +.c Topic +.c +.de Topic +. TP 2m +. Text \[bu] .. . +.ec +.\" End of macro definitions +. +. .\" -------------------------------------------------------------------- .\" Title .\" -------------------------------------------------------------------- +. .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" .SH NAME -roff \- a survey of the roff typesetting system +roff \- concepts and history of roff typesetting +. +. .\" -------------------------------------------------------------------- .SH DESCRIPTION .\" -------------------------------------------------------------------- +. .I roff is the general name for a set of type-setting programs, known under names like .IR troff , .IR nroff , +.IR ditroff , .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 +. +A roff type-setting system consists of an extensible text formatting +language and a set of programs for printing and converting to other +text formats. +. +Traditionally, it is the main text processing system of Unix; every +Unix-like operating system still distributes a roff system as a core +package. +. +.P The most common roff system today is the free software implementation +.IR "GNU roff", +.BR groff (@MAN1EXT@). +. +The pre-groff implementations are referred to as +.I classical +(dating back as long as 1973). +. .I groff -(from `GNU\ roff'). -The pre-groff implementations are referred to as `classical' (dating -back as long as 1973). -.LP +implements the look-and-feel and functionality of its classical +ancestors, but has many extensions. +. +As .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. +is the only roff system that is available for every (or almost every) +computer system it is the de-facto roff standard today. +. +.P +In some ancient Unix systems, there was a binary called +.B roff +that implemented the even more ancient +.B runoff +of the +.I Multics +operating system, cf. section +.BR HISTORY . +The functionality of this program was very restricted even in +comparison to ancient troff; it is not supported any longer. +. +Consequently, in this document, the term +.I roff +always refers to the general meaning of +.IR "roff system" , +not to the ancient roff binary. +. +.P +In spite of its age, roff is in wide use today, for example, the manual +pages on UNIX systems +.RI ( man\~pages\/ ), +many software books, system documentation, standards, and corporate +documents 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. +output has the same quality as other free type-setting programs and is +better than some of the commercial systems. +. +.P +The most popular application of roff is the concept of +.I manual pages +or shortly +.IR "man pages" ; +this is the standard documentation system on many operating systems. +. +.P +This document describes the historical facts around the development +of the +.IR "roff system" ; +some usage aspects common to all roff versions, details on the roff +pipeline, which is usually hidden behind front-ends like +.BR groff (@MAN1EXT@); +an general overview of the formatting language; some tips for editing +roff files; and many pointers to further readings. +. +. .\" -------------------------------------------------------------------- -.SH "FORMATTING LANGUAGE" +.SH "HISTORY" .\" -------------------------------------------------------------------- -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 +. +The .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. +text processing system has a very long history, dating back to the +1960s. +. +The roff system itself is intimately connected to the Unix operating +system, but its roots go back to the earlier operating systems CTSS +and Multics. +. +. .\" -------------------------------------------------------------------- -.SH FORMATTERS +.SS "The Predecessor runoff" .\" -------------------------------------------------------------------- -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 +. +.P +The evolution of .I roff -had two formatters, +is intimately related to the history of the operating systems. +. +Its predecessor +.B runoff +was written by +.I Jerry Saltzer +on the +.I CTSS +operating system +.RI ( "Compatible Time Sharing System" ) +as early as 1961. +. +When CTTS was further developed into the operating system +.URL http://\:www.multicians.org "Multics" , +the famous predecessor of Unix from 1963, +.I runoff +became the main format for documentation and text processing. +. +Both operating systems could only be run on very expensive computers +at that time, so they were mostly used in research and for official +and military tasks. +. +.P +The possibilities of the +.I runoff +language were quite limited as compared to modern roff. +. +Only text output was possible in the 1960s. +. +This could be implemented by a set of requests of length\~2, many of +which are still identically used in roff. +. +The language was modelled according to the habits of typesetting in +the pre-computer age, where lines starting with a dot were used in +manuscripts to denote formatting requests to the person who would +perform the typesetting manually later on. +. +.P +The runoff program was written in the +.I PL/1 +language first, later on in +.IR BCPL , +the grandmother of the +.IR C \~\c +programming language. +. +In the Multics operating system, the help system was handled by +runoff, similar to roff's task to manage the Unix manual pages. +. +There are still documents written in the runoff language; for examples +see Saltzer's home page, cf. section +.BR "SEE ALSO" . +. +. +.\" -------------------------------------------------------------------- +.SS "The Classical nroff/troff System" +.\" -------------------------------------------------------------------- +. +In the 1970s, the Multics off-spring +.I Unix +became more and more popular because it could be run on affordable +machines and was easily available for universities at that time. +. +At MIT (the Massachusetts Institute of Technology), there was a need to +drive the Wang +.I Graphic Systems CAT +typesetter, a graphical output device from a PDP-11 computer running +Unix. +. +As runoff was too limited for this task it was further developed into +a more powerful text formatting system by +.IR "Josef F. Osanna" , +a main developer of the Multics operating system and programmer of +several runoff ports. +. +.P +The name +.I runoff +was shortened to +.IR roff . +The greatly enlarged language of Osanna's concept included already all +elements of a full +.IR "roff system" . +. +All modern roff systems try to implement compatibility to this system. +. +So Joe Osanna can be called the father of all roff systems. +. +.P +This first +.I roff system +had three formatter programs. +. +.TP +.B troff +.RI ( "typesetter roff\/" ) +generated a graphical output for the +.I CAT +typesetter as its only device. +. +.TP .B nroff -for text devices and +produced text output suitable for terminals and line printers. +. +.TP +.B roff +was the reimplementation of the former runoff program with its limited +features; this program was abandoned in later versions. +. +Today, the name +.I roff +is used to refer to a troff/\:nroff sytem as a whole. +. +.P +Osanna first version was written in the PDP-11 assembly language and +released in 1973. +. +.I Brian Kernighan +joined the +.I roff +development by rewriting it in the C\~programming language. +. +The C\~version was released in 1975. +. +.P +The syntax of the formatting language of the +.BR nroff / troff +programs was documented in the famous +.IR "Troff User's Manual [CSTR\~#54]" , +first published in 1976, with further revisions up to 1992 by Brian +Kernighan. +. +This document is the specification of the +.IR "classical troff" . +All later +.I roff +systems tried to establish compatibility with this specification. +. +.P +After Osanna had died in 1977 by a heart-attack at the age of about\~50, +Kernighan went on with developing troff. +. +The next milestone was to equip troff with a general interface to +support more devices, the intermediate output format and the +postprocessor system. +. +This completed the structure of a +.I "roff system" +as it is still in use today; see section +.BR "USING ROFF" . +. +In 1979, these novelties were described in the paper +.IR "[CSTR\~#97]" . +This new troff version is the basis for all existing newer troff +systems, including +.IR groff . +. +On some systems, this +.I device independent troff +got a binary of its own, called +.BR ditroff (@MAN7EXT@). +. +All modern .B troff -for graphical devices. -.LP -These programs still exist in the +programs already provide the full ditroff capabilities automatically. +. +. +.\" -------------------------------------------------------------------- +.SS "Commercialization" +.\" -------------------------------------------------------------------- +. +A major degradation occurred when the easily available Unix\~7 +operating system was commercialized. +. +A whole bunch of divergent operating systems emerged, fighting each +other with incompatibilities in their extensions. +. +Luckily, the incompatibilities did not fight the original troff. +. +All of the different commercial roff systems made heavy use of +Osanna/\:Kernighan's open source code and documentation, but sold them +as \[lq]their\[rq] system \[em] with only minor additions. +. +.P +The source code of both the ancient Unix and classical troff weren't +available for two decades. +. +Fortunately, Caldera bought SCO UNIX in 2001. +. +In the following, Caldera made the ancient source code accessible +on-line for non-commercial use, cf. section +.BR "SEE ALSO" . +. +. +.\" -------------------------------------------------------------------- +.SS "Free roff" +.\" -------------------------------------------------------------------- +. +None of the commercial roff systems could attain the status of a +successor for the general roff development. +. +Everyone was only interested in their own stuff. +. +This led to a steep downfall of the once excellent +Unix operating system during the 1980s. +. +.P +As a counter-measure to the galopping commercialization, AT&T Bell +Labs tried to launch a rescue project with their +.I Plan\~9 +operating system. +. +It is freely available for non-commercial use, even the source code, +but has a proprietary license that empedes the free development. +. +This concept is outdated, so Plan\~9 was not accepted as a platform to +bundle the main-stream development. +. +.P +The only remedy came from the emerging free operatings systems +(386BSD, GNU/\:Linux, etc.) and software projects during the 1980s and +1990s. +. +These implemented the ancient Unix features and many extensions, such +that the old experience is not lost. +. +In the 21st century, Unix-like systems are again a major factor in +computer industry \[em] thanks to free software. +. +.P +The most important free roff project was the GNU port of troff, +created by James Clark and put under the +.URL http://\:www.gnu.org/\:copyleft "GNU Public License" . +. +It was called .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. +.RI ( "GNU roff" ). +See +.BR groff (@MAN1EXT@) +for an overview. +. +.P +The groff system is still actively developed. +. +It is compatible to the classical troff, but many extensions were +added. +. +It is the first roff system that is available on almost all operating +systems \[em] and it is free. +. +This makes groff the de-facto roff standard today. +. +. +.\" -------------------------------------------------------------------- +.SH "USING ROFF" +.\" -------------------------------------------------------------------- +. +Most people won't even notice that they are actually using roff. +. +When you read a system manual page (man page) roff is working in the +background. +. +Roff documents can be viewed with a native viewer called +.BR xditview (1x), +a standard program of the X window distribution, see +.BR X (7x). +. +But using roff explicitly isn't difficult either. +. +.P +Some roff implementations provide wrapper programs that make it easy +to use the roff system on the shell command line. +. +For example, the GNU roff implementation +.BR groff (@MAN1EXT@) +provides command line options to avoid the long command pipes of +classical troff; a program +.BR grog (@MAN1EXT@) +tries to guess from the document which arguments should be used for a +run of groff; people who do not like specifying command line options +should try the +.BR groffer (@MAN1EXT@) +program for graphically displaying groff files and man pages. +. +. +.\" -------------------------------------------------------------------- +.SS "The roff Pipe" +.\" -------------------------------------------------------------------- +. +Each roff system consists of preprocessors, roff formatter programs, +and a set of device postprocessors. +. +This concept makes heavy use of the +.I piping +mechanism, that is, a series of programs is called one after the other, +where the output of each program in the queue is taken as the input +for the next program. +. +.CodeSkip +. +.ds @1 "cat \f[I]file\f[P] |\"" +.ds @2 "\*[Ellipsis] | \f[I]preproc\f[P] | \*[Ellipsis] |\"" +.ds @3 "troff \f[I]options\f[P] | \f[I]postproc\f[P]\"" +. +.ShellCommand "\*[@1] \*[@2] \*[@3]" +. +.rm @1 +.rm @2 +.rm @3 +.P +The preprocessors generate roff code that is fed into a roff formatter +(e.g. troff), which in turn generates +.I intermediate output +that is fed into a device postprocessor program for printing or final +output. +. +.P +All of these parts use programming languages of their own; each +language is totally unrelated to the other parts. +. +Moreover, roff macro packages that were tailored for special purposes +can be included. +. +.P +Most roff documents use the macros of some package, intermixed with +code for one or more preprocessors, spiced with some elements from the +plain roff language. +. +The full power of the roff formatting language is seldom needed by +users; only programmers of macro packages need to know about the gory +details. +. +. +. +.\" -------------------------------------------------------------------- +.SS "Preprocessors" +.\" -------------------------------------------------------------------- +. +A roff preprocessor is any program that generates output that +syntactically obeys the rules of the roff formatting language. +. +Each preprocessor defines a language of its own that is translated +into roff code when run through the preprocessor program. +. +Parts written in these languages may be included within a roff +document; they are identified by special roff requests or macros. +. +Each document that is enhanced by preprocessor code must be run +through all corresponding preprocessors before it is fed into the +actual roff formatter program, for the formatter just ignores all +alien code. +. +The preprocessor programs extract and transform only the document +parts that are determined for them. +. +.P +There are a lot of free and commercial roff preprocessors. +. +Some of them aren't available on each system, but there is a small +set of preprocessors that are considered as an integral part of each +roff system. +. +The classical preprocessors are +. + +.de @TP +.\" local indent for .TP +.TP \\w'\\f[B]soelim\\f[P]'u+2n +.. +.P .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. +.@TP +.B tbl +for tables +.@TP +.B eqn +for mathematical formul\[ae] +.@TP +.B pic +for drawing diagrams +.@TP +.B refer +for bibliographic references +.@TP +.B soelim +for including macro files from standard locations .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" +. +.P +Other known preprocessors that are not available on all systems +include +. +.P +.RS +.PD 0 +.@TP +.B chem +for drawing chemical formul\[ae]. +.@TP +.B grap +for constructing graphical elements. +.@TP +.B grn +for including +.BR gremlin (1) +pictures. +.PD +.RE +. +.rm @TP +. +.\" -------------------------------------------------------------------- +.SS "Formatter Programs" .\" -------------------------------------------------------------------- +. +A +.I roff formatter +is a program that parses documents written in the roff formatting +language or uses some of the roff macro packages. +. +It generates +.IR "intermediate output" , +which is intended to be fed into a single device postprocessor that +must be specified by a command-line option to the formatter program. +. +The documents must have been run through all necessary preprocessors +before. +. +.P +The output produced by a roff formatter is represented in yet another +language, the +.IR "intermediate output format" +or +.IR "troff output" . +This language was first specified in +.IR "[CSTR\~#97]" ; +its GNU extension is documented in +.BR groff_out (@MAN5EXT@). +. +The intermediate output language is a kind of assembly language +compared to the high-level roff language. +. +The generated intermediate output is optimized for a special device, +but the language is the same for every device. +. +.P +The roff formatter is the heart of the roff system. +. +The traditional roff had two formatters, +.B nroff +for text devices and +.B troff +for graphical devices. +. +.P +Often, the name +.I troff +is used as a general term to refer to both formatters. +. +. +.\" -------------------------------------------------------------------- +.SS "Devices and Postprocessors" +.\" -------------------------------------------------------------------- +. +Devices are hardware interfaces like printers, text or graphical +terminals, etc., or software interfaces such as a conversion into a +different text or graphical format. +. +.P +A roff postprocessor is a program that transforms troff output into a +form suitable for a special device. +. +The roff postprocessors are like device drivers for the output target. +. +.P +For each device there is a postprocessor program that fits the device +optimally. +. +The postprocessor parses the generated intermediate output and +generates device-specific code that is sent directly to the device. +. +.P +The names of the devices and the postprocessor programs are not fixed +because they greatly depend on the software and hardware abilities of +the actual computer. +. +For example, the classical devices mentioned in +.I [CSTR\~#54] +have greatly changed since the classical times. +. +The old hardware doesn't exist any longer and the old graphical +conversions were quite imprecise when compared to their modern +counterparts. +. +.P +For example, the Postscript device +.I post +in classical troff had a resolution +of 720, while groff's +.I ps +device has 72000, a refinement of factor 100. +. +.P +Today the operating systems provide device drivers for most +printer-like hardware, so it isn't necessary to write a special +hardware postprocessor for each printer. +. +. +.\" -------------------------------------------------------------------- +.SH "ROFF PROGRAMMING" +.\" -------------------------------------------------------------------- +. +Documents using roff are normal text files decorated by roff +formatting elements. +. +The roff formatting language is quite powerful; it is almost a full +programming language and provides elements to enlarge the language. +. +With these, it became possible to develop macro packages that are +tailored for special applications. +. +Such macro packages are much handier than plain roff. +. +So most people will choose a macro package without worrying about the +internals of the roff language. +. +. +.\" -------------------------------------------------------------------- +.SS "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 .IB name .tmac -(or +(classically .BI tmac. name\c -) where -.I name -is the internal roff name for this package. -All tmac files are stored in a single or few directories at standard +). +. +All tmac files are stored in one or more directories at standardized 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 +. +Details on the naming of macro packages and their placement is found +in .BR groff_tmac (@MAN5EXT@). -.LP +. +.P +A macro package that is to be used in a document can be announced to +the formatter by the command line option +.ShortOpt m , +see +.BR troff (@MAN1EXT@), +or it can be specified within a document using the file inclusion +requests of the roff language, see +.BR groff (@MAN7EXT@). +. +.P Famous classical macro packages are -.IR man , -.IR mandoc , -and +.I man +for traditional man pages, .I mdoc -for manual pages and -.IR me , -.IR ms , +for BSD-style manual pages; +the macro sets for books, articles, and letters are +.I me +(probably from the first name of its creator +.I Eric +Allman), +.I ms +(from +.IR "Manuscript Macros\/" ), 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. +(from +.IR "Memorandum Macros\/" ). +. +. +.\" -------------------------------------------------------------------- +.SS "The roff Formatting Language" +.\" -------------------------------------------------------------------- +. +The classical roff formatting language is documented in the +.I Troff User's Manual +.IR "[CSTR\~#54]" . +. +The roff language is a full programming language providing requests, +definition of macros, escape sequences, string variables, number or +size registers, and flow controls. +. +.P +.I Requests +are the predefined basic formatting commands similar to the commands +at the shell prompt. +. +The user can define request-like elements using predefined roff +elements. +. +These are then called +.IR macros . +. +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. +. +.P +.I Escape sequences +are roff elements starting with a backslash +.QuotedChar \[rs] . +They can be inserted anywhere, also in the midst of text in a line. +. +They are used to implement various features, including the insertion of +non-ASCII characters with +.Esc ( , +font changes with +.Esc f , +in-line comments with +.Esc \[dq] , +the escaping of special control characters like +.Esc \[rs] , +and many other features. +. +.P +.I Strings +are variables that can store a string. +. +A string is stored by the +.B .ds +request. +. +The stored string can be retrieved later by the +.B \[rs]* +escape sequence. +. +.P +.I Registers +store numbers and sizes. +. +A register can be set with the request +.B .nr +and its value can be retrieved by the escape sequence +.BR "\[rs]n" . +. +. .\" -------------------------------------------------------------------- .SH "FILE NAME EXTENSIONS" .\" -------------------------------------------------------------------- -Manual pages (man-pages) take the section number as a file name +. +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 +i.e., it is kept in section\~7 +of the man pages. +. +.P The classical macro packages take the package name as an extension, e.g. .IB file. me for a document using the @@ -342,201 +930,347 @@ for .I pic files, etc. -.ig -.LP +. +.P 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 +.IB file. tr +for +.I troff file +is seen now and then. +. +Maybe there should be a standardization for the filename extensions of +roff files. +. +.P 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' +. +It provides the possibility to feed all input into a command-line pipe +that is specified in the shell environment variable +.BR LESSOPEN . +This process is not well documented, so here an example: +. +.CodeSkip +.ShellCommand LESSOPEN='|lesspipe %s' +.CodeSkip +. where .B lesspipe is either a system supplied command or a shell script of your own. -.. +. +. +.\" -------------------------------------------------------------------- +.SH "EDITING ROFF" +.\" -------------------------------------------------------------------- +. +The best program for editing a roff document is Emacs (or Xemacs), see +.BR emacs (1). +It provides an +.I nroff +mode that is suitable for all kinds of roff dialects. +. +This mode can be activated by the following methods. +. +.P +When editing a file within Emacs the mode can be changed by typing +.RI ` "M-x nroff-mode" ', +where +.B M-x +means to hold down the +.B Meta +key (or +.BR Alt ) +and hitting the +.BR x\~ key +at the same time. +. +.P +But it is also possible to have the mode automatically selected when +the file is loaded into the editor. +. +.Topic +The most general method is to include the following 3 comment lines at +the end of the file. +. +.CodeSkip +.nf +.B \*[Comment] Local Variables: +.B \*[Comment] mode: nroff +.B \*[Comment] End: +.fi +. +.Topic +There is a set of file name extensions, e.g. the man pages that +trigger the automatic activation of the nroff mode. +. +.Topic +Theoretically, it is possible to write the sequence +.CodeSkip +.B \*[Comment] \%-*-\ nroff\ -*- +.CodeSkip +as the first line of a file to have it started in nroff mode when +loaded. +. +Unfortunately, some applications such as the +.B man +program are confused by this; so this is deprecated. +. +.P +All roff formatters provide automated line breaks and horizontal and +vertical spacing. +. +In order to not disturb this, the following tips can be helpful. +. +.Topic +Never include empty or blank lines in a roff document. +. +Instead, use the empty request (a line consisting of a dot only) or a +line comment +.B \*[Comment] +if a structuring element is needed. +. +.Topic +Never start a line with whitespace because this can lead to +unexpected behavior. +. +Indented paragraphs can be constructed in a controlled way by roff +requests. +. +.Topic +Start each sentence on a line of its own, for the spacing after a dot +is handled differently depending on whether it terminates an +abbreviation or a sentence. +. +To distinguish both cases, do a line break after each sentence. +. +.Topic +To additionally use the auto-fill mode in Emacs, it is best to insert +an empty roff request (a line consisting of a dot only) after each +sentence. +. +.P +The following example shows how optimal roff editing could look. +. +.IP +.nf +This is an example for a roff document. +.Text . +This is the next sentence in the same paragraph. +.Text . +This is a longer sentence stretching over several +lines; abbreviations like `cf.' are easily +identified because the dot is not followed by a +line break. +.Text . +In the output, this will still go to the same +paragraph. +.fi +. +.P +Besides Emacs, some other editors provide nroff style files too, e.g.\& +.BR vim (1), +an extension of the +.BR vi (1) +program. +. +. +.\" -------------------------------------------------------------------- +.SH BUGS .\" -------------------------------------------------------------------- -.SH EDITING +. +.I UNIX\[rg] +is a registered trademark of the Open Group. +. +But things have improved considerably after Caldera had bought SCO +UNIX in 2001. +. +. .\" -------------------------------------------------------------------- -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 "SEE ALSO" .\" -------------------------------------------------------------------- -.SH ENVIRONMENT +. +There is a lot of documentation on roff. +. +The original papers on classical troff are still available, and all +aspects of groff are documented in great detail. +. +. .\" -------------------------------------------------------------------- +.SS "Internet sites" +.\" -------------------------------------------------------------------- +. .TP -.SM -.B GROFF_TMAC_PATH -A colon separated list of directories in which to search for -macro files, see -.BR groff_tmac (@MAN5EXT@). +troff.org +.URL http://\:www.troff.org "The historical troff site" +provides an overview and pointers to all historical aspects of roff. +. +This web site is under construction; once, it will be the major source +for roff history. +. .TP -.SM -.B GROFF_TYPESETTER -Default device. +Multics +.URL http://\:www.multicians.org "The Multics site" +contains a lot of information on the MIT projects, CTSS, Multics, +early Unix, including +.IR runoff ; +especially useful are a glossary and the many links to ancient +documents. +. .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 first search in directories given with the -.option \-F -command line option, then in -.BR GROFF_FONT_PATH , -and finally in the standard directories -.RB ( @FONTPATH@ ). +Unix Archive +.URL http://\:www.tuhs.org/\:Archive/ \ + "The Ancient Unixes Archive" +. +provides the source code and some binaries of the ancient Unixes +(including the source code of troff and its documentation) that were +made public by Caldera since 2001, e.g. of the famous Unix version\~7 +for PDP-11 at the +.URL http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7 \ + "Unix V7 site" . +. +.TP +Developers at AT&T Bell Labs +.URL http://\:cm.bell-labs.com/\:cm/\:index.html \ + "Bell Labs Computing and Mathematical Sciences Research" +. +provides a search facility for tracking information on the early +developers. +. +.TP +Plan 9 +.URL http://\:plan9.bell-labs.com "The Plan\~9 operating system" +. +by AT&T Bell Labs. +. +.TP +runoff +.URL http://web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html \ +"Jerry Saltzer's home page" +. +stores some documents using the ancient runoff formatting language. +. +.TP +CSTR Papers +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \ + "The Bell Labs CSTR site" +. +stores the original troff manuals (CSTR #54, #97, #114, #116, #122) +and famous historical documents on programming. +. +.TP +GNU roff +.URL http://\:www.gnu.org/\:software/\:groff "The groff web site" +provides the free roff implementation groff, the actual standard roff. +. +. .\" -------------------------------------------------------------------- -.SH FILES +.SS "Historical roff Documentation" .\" -------------------------------------------------------------------- -By default, -.I groff -installs all of its data files in subdirectories of -.I @FONTDIR@ -and in -.I @MACRODIR@ -(except wrapper files for system-specific macro packages which will be -in -.IR @SYSTEMMACRODIR@ ). -These locations might vary for different systems. -In the following, the former is referred to as -.IR <groff_font_dir> , -the latter as -.IR <groff_macro_dir> . +. +Many classical +.troff +documents are still available on-line. +. +The two main manuals of the troff language are +. .TP -.IB <groff_macro_dir> /troffrc -Initialization file for troff. +[CSTR\~#54] +J. F. Osanna, +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \ + "\fINroff/\:Troff User's Manual\fP" ; +. +Bell Labs, 1976; revised by Brian Kernighan, 1992. + +. .TP -.IB <groff_macro_dir> / name .tmac -.TQ -.IB <groff_macro_dir> /tmac. name -Macro files. +[CSTR\~#97] +Brian Kernighan, +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps \ + "\fIA Typesetter-independent TROFF\fP" , +. +Bell Labs, 1981, revised March 1982. +. +.P +The "little language" roff papers are +. .TP -.IB <groff_font_dir> /dev name /DESC -Device description file for device -.IR name . +[CSTR\~#114] +Jon L. Bentley and Brian W. Kernighan, +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:114.ps \ + "\fIGRAP \(em A Language for Typesetting Graphs\fP" ; +. +Bell Labs, August 1984. +. .TP -.IB <groff_font_dir> /dev name / F -Font file for font -.I F -of device -.IR name . -.LP -Finally, a local macro directory -.I @LOCALMACRODIR@ -is provided for site-specific macros and packages; by default, it will be -searched before the main macro directory. +[CSTR\~#116] +Brian W. Kernighan, +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:116.ps \ + "\fIPIC -- A Graphics Language for Typesetting\fP" ; +. +Bell Labs, December 1984. +. +.TP +[CSTR\~#122] +J. L. Bentley, L. W. Jelinski, and B. W. Kernighan, +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:122.ps \ +"\fICHEM \(em A Program for Typesetting Chemical Structure Diagrams, \ +Computers and Chemistry\fP" ; +. +Bell Labs, April 1986. +. +. .\" -------------------------------------------------------------------- -.SH BUGS +.SS "Manual Pages" .\" -------------------------------------------------------------------- -The groff documentation is in evolution at the moment. -It is possible that small inconsistencies between different documents exist -temporarily. +. +Due to its complex structure, a full roff system has many man pages, +each describing a single aspect of roff. +. +Unfortunately, there is no general naming scheme for the +documentation among the different roff implementations. +. +.P +In +.IR groff , +the man page +.BR groff (@MAN1EXT@) +contains a survey of all documentation available in groff. +. +.P +On other systems, you are on your own, but +.BR troff (1) +might be a good starting point. +. +. .\" -------------------------------------------------------------------- -.SH AUTHOR +.SH AUTHORS .\" -------------------------------------------------------------------- -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 +. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document 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 at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It was written by +.MTO bwarken@mayn.de "Bernd Warken" ; +it is maintained by +.MTO wl@gnu.org "Werner Lemberg". +. +. .\" -------------------------------------------------------------------- -.SH "SEE ALSO" +.\" Emacs setup .\" -------------------------------------------------------------------- -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@), -and -.BR groff_ms (@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/ . . .\" Local Variables: .\" mode: nroff |
