From 420d73ead30535db7499dd3b8ecd6b1c2ad33d56 Mon Sep 17 00:00:00 2001 From: wlemb Date: Mon, 7 Jan 2002 04:05:38 +0000 Subject: * man/groff_diff.man: Revised. --- man/ditroff.man | 8 +- man/groff.man | 10 +- man/groff_diff.man | 2009 +++++++++++++++++++++++++++++++++++----------------- man/roff.man | 132 ++-- 4 files changed, 1432 insertions(+), 727 deletions(-) (limited to 'man') diff --git a/man/ditroff.man b/man/ditroff.man index 28e9433d..da2c405b 100644 --- a/man/ditroff.man +++ b/man/ditroff.man @@ -12,7 +12,7 @@ maintained by Werner Lemberg 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 @@ -166,7 +166,7 @@ multi-devicing. . . .\" -------------------------------------------------------------------- -.SH "AUTHOR" +.SH "AUTHORS" .\" -------------------------------------------------------------------- . Copyright (C) 2001, 2002 Free Software Foundation, Inc. @@ -185,9 +185,9 @@ This document is part of the GNU roff distribution. . It was written by -.URL "Bernd Warken" mailto:bwarken@mayn.de +.URL "Bernd Warken" mailto:\:bwarken@mayn.de and is maintained by -.URL "Werner Lemberg" mailto:wl@gnu.org . +.URL "Werner Lemberg" mailto:\:wl@gnu.org . . . .\" -------------------------------------------------------------------- diff --git a/man/groff.man b/man/groff.man index ab2fb637..c1674fff 100644 --- a/man/groff.man +++ b/man/groff.man @@ -13,7 +13,7 @@ maintained by Werner Lemberg 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 @@ -3182,13 +3182,13 @@ on how to invoke this. .\" -------------------------------------------------------------------- . Report bugs to the -.URL "groff bug mailing list" mailto:bug-groff@gnu.org . +.URL "groff bug mailing list" mailto:\:bug-groff@gnu.org . 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 .\" -------------------------------------------------------------------- . Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. @@ -3207,9 +3207,9 @@ This document is part of the GNU roff distribution. . It was written by -.URL "Bernd Warken" mailto:bwarken@mayn.de ; +.URL "Bernd Warken" mailto:\:bwarken@mayn.de ; it is maintained by -.URL "Werner Lemberg" mailto:wl@gnu.org . +.URL "Werner Lemberg" mailto:\:wl@gnu.org . . . .\" -------------------------------------------------------------------- diff --git a/man/groff_diff.man b/man/groff_diff.man index 8c7df80c..c4f687ce 100644 --- a/man/groff_diff.man +++ b/man/groff_diff.man @@ -1,11 +1,14 @@ +'\" e +.\" The above line should force the use of eqn as a preprocessor .ig groff_diff.man -Last update : 9 Dec 2001 +Last update : 6 Jan 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) 2000, 2001 Free Software Foundation, Inc. +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. written by James Clark modified by Werner Lemberg @@ -14,7 +17,7 @@ modified by Werner Lemberg 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 @@ -27,27 +30,80 @@ FDL in the main directory of the groff source package. . .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 . -.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" -.. +.\" -------------------------------------------------------------------- +.\" start of macro definitions +.eo . +.de TQ +. br +. ns +. TP \$1 +.. .\" Don't use .ne for TTY devices .de NE -.if t .ne \\$1 +. if t \ +. ne \$1 +.. +.de Text +. RI "\$*" +.. +.de Topic +. TP 2m +. Text \[bu] +.. +.de squoted +. ds @arg1 \$1 +. shift +.\" Text \[oq]\f[CB]\*[@arg1]\f[P]\[cq]\$* +. Text \[oq]\f[B]\*[@arg1]\f[P]\[cq]\$* +. rm @arg1 +.. +.\" A shell command line +.de ShellCommand +. br +. IR "shell#" "\h'1m'\f[CB]\$*\f[P]\/" +.. +.\" reference of a request or macro +.de request +. ds @arg1 \$1 +. shift 1 +.\" Text \f[CB]\*[@arg1]\f[P]\$* +. Text \f[B]\*[@arg1]\f[P]\$* +. rm @arg1 .. +.als option request +. +.\" representation of an escape sequence +.de esc +. ds @arg1 \$1 +. shift +.\" Text \f[CB]\[rs]\*[@arg1]\f[P]\$* +. Text \f[B]\[rs]\*[@arg1]\f[P]\$* +. rm @arg1 +.. +.ec +.\" end of macro definitions +. +.\" from old groff_out.man +.ie \n(.g \ +. ds ic \/ +.el \ +. ds ic \^ . . .\" -------------------------------------------------------------------- @@ -69,12 +125,15 @@ the GNU .I roff text processing system and the classical .I roff -formatter of the free Unix\~7 of the 1970s, documented in the +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 @@ -86,17 +145,19 @@ and the modern documentation. . .P -At the moment, this document is the place of the most actual documentation -with the +At the moment, this document is the place of the most actual +documentation within the .I groff system. -All novelties are first described here and will pervade into the other -documents only at a later stage. -This might be changed in the future. +. +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 "NEW FEATURES" +.SH "GROFF LANGUAGE" .\" -------------------------------------------------------------------- . In this section, all additional features of @@ -107,40 +168,41 @@ are described in detail. . . .\" -------------------------------------------------------------------- -.SS Long names +.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'\ef[xxx]'u+3n -.BI \e[ xxx ] +.TP \w'\[rs]f[xxx]'u+3n +.BI \[rs][ xxx ] Print the special character called .IR xxx . . .TP -.BI \ef[ xxx ] +.BI \[rs]f[ xxx ] Set font .IR xxx . . .TP -.BI \e*[ xxx ] +.BI \[rs]*[ xxx ] Interpolate string .IR xxx . . .TP -.BI \en[ xxx ] +.BI \[rs]n[ xxx ] Interpolate number register .IR xxx . . . .\" -------------------------------------------------------------------- -.SS Fractional pointsizes +.SS "Fractional pointsizes" .\" -------------------------------------------------------------------- . A @@ -152,12 +214,14 @@ points, where 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 +. +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 @@ -166,39 +230,41 @@ request, the third argument to the request, the second and fourth arguments to the .B tkf request, the argument to the -.B \eH +.B \[rs]H escape sequence, and those variants of the -.B \es +.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 request -.B .ps\~10.25 +equivalent to a millipoint; the call +.B .ps\ 10.25 is equivalent to -.B .ps\~10.25z +.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 \en[.s] +.B \[rs]n[.s] returns the pointsize in points as decimal fraction. +. There is also a new number register -.B \en[.ps] +.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 +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 @@ -210,11 +276,12 @@ and so disallows this as well. . .P -There is also new scale indicator +There is also new scale indicator\~\c .B s which multiplies by the number of units in a scaled point. +. So, for example, -.B \en[.ps]s +.B \[rs]n[.ps]s is equal to .BR 1m . Be sure not to confuse the @@ -225,7 +292,7 @@ scale indicators. . . .\" -------------------------------------------------------------------- -.SS Numeric expressions +.SS "Numeric expressions" .\" -------------------------------------------------------------------- . Spaces are permitted in a number expression within parentheses. @@ -238,6 +305,7 @@ indicates a scale of 65536 units, providing fractions for color definitions with .B defcolor request. +. For example, 0.5f = 32768u. . .TP @@ -261,6 +329,7 @@ Evaluate using .I c as the default scaling indicator. +. If .I c is missing, ignore scaling indicators in the evaluation of @@ -268,11 +337,11 @@ is missing, ignore scaling indicators in the evaluation of . . .\" -------------------------------------------------------------------- -.SS New escape sequences +.SS "New escape sequences" .\" -------------------------------------------------------------------- . .TP -.BI \eA' anything ' +.BI \[rs]A' anything ' This expands to .B 1 or @@ -286,11 +355,12 @@ It will return\~\c if .I anything is empty. -This is useful if you want to lookup user input in some sort of associative -table. +. +This is useful if you want to lookup user input in some sort of +associative table. . .TP -.BI \eB' anything ' +.BI \[rs]B' anything ' This expands to .B 1 or @@ -298,6 +368,7 @@ or resp., depending on whether .I anything is or is not a valid numeric expression. +. It will return\~\c .B 0 if @@ -305,83 +376,90 @@ if is empty. . .TP -.BI \eC' xxx ' +.BI \[rs]C' xxx ' Typeset character named .IR xxx . Normally it is more convenient to use -.BI \e[ xxx ]\fR. +.BI \[rs][ xxx ]\f[R]. But -.B \eC +.B \[rs]C has the advantage that it is compatible with recent versions of .SM UNIX and is available in compatibility mode. . .TP -.B \eE +.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 +. +For example, strings to start and end superscripting could be defined +like this . .RS .IP -\&.ds { \ev'\-.3m'\es'\eEn[.s]*6u/10u' +.ft CB +.Text .ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u' .br -\&.ds } \es0\ev'.3m' +.Text .ds } \[rs]s0\[rs]v'.3m' +.ft . .P The use of -.B \eE +.B \[rs]E ensures that these definitions will work even if -.B \e*{ +.B \[rs]*{ gets interpreted in copy-mode (for example, by being used in a macro argument). .RE . .TP -.BI \em x +.BI \[rs]m x .TQ -.BI \em( xx +.BI \[rs]m( xx .TQ -.BI \em[ xxx ] +.BI \[rs]m[ xxx ] Set drawing color. -.B \emP +.B \[rs]mP switches back to the previous color. . .TP -.BI \eM x +.BI \[rs]M x .TQ -.BI \eM( xx +.BI \[rs]M( xx .TQ -.BI \eM[ xxx ] +.BI \[rs]M[ xxx ] Set background color for filled objects drawn with the -.BI \eD' .\|.\|. ' +.BI \[rs]D' .\|.\|. ' commands. -.B \eMP +.B \[rs]MP switches back to the previous color. . .TP -.BI \eN' n ' +.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 +. +If the current font does not contain a character with that code, +special fonts will .I not be searched. +. The -.B \eN +.B \[rs]N escape sequence can be conveniently used in conjunction with the .B char request, for example . .RS +.ft CB .IP -.B -\&.char \e[phone] \ef(ZD\eN'37' +.Text .char \[rs][phone] \[rs]f(ZD\[rs]N'37' +.ft .RE . .IP @@ -389,102 +467,111 @@ 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 +. +It is possible to include unnamed characters in the font description +file by using a name of .BR \-\-\- ; the -.B \eN +.B \[rs]N escape sequence is the only way to use these. . .TP -.BI \eO n +.BI \[rs]O n Suppressing troff output. +. The escapes -.BR \e02 , -.BR \eO3 , -.BR \eO4 , +.BR \[rs]02 , +.BR \[rs]O3 , +.BR \[rs]O4 , and -.B \eO5 +.B \[rs]O5 are intended for internal use by -.BR grohtml . +.BR \%grohtml . . +.RS .TP -.B \eO0 -Disable any ditroff glyphs from being emitted to the device driver, provided -that the escape occurs at the outer level (see -.B \eO3 +.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 \eO4 ). +.BR \[rs]O4 ). . .TP -.B \eO1 +.B \[rs]O1 Enable output of glyphs, provided that the escape occurs at the outer level. .IP -.B \eO0 +.B \[rs]O0 and -.B \eO1 +.B \[rs]O1 also reset the registers -.BR \en[opminx] , -.BR \en[opminy] , -.BR \en[opmaxx] , +.BR \[rs]n[opminx] , +.BR \[rs]n[opminy] , +.BR \[rs]n[opmaxx] , and -.B \en[opmaxy] +.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. +. +These four registers mark the top left and bottom right hand corners +of a box which encompasses all written glyphs. . .TP -.B \eO2 -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 \eO . +.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 \eO3 +.B \[rs]O3 Begin a nesting level. +. This is really an internal mechanism for -.B grohtml +.B \%grohtml while producing images. +. They are generated by running the troff source through troff to the postscript device and ghostscript to produce images in PNG format. The -.B \eO3 +.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 \eO4 +.B \[rs]O4 End a nesting level. .TP -.BI \eO5[ Pfilename ] +.BI \[rs]O5[ Pfilename ] This escape is -.B grohtml +.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). +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 \eR' name\ \(+-n ' +.BI \[rs]R' name\ \[+-]n ' This has the same effect as . .RS .IP -.BI .nr\ name\ \(+-n +.BI .nr\ name\ \[+-]n .RE . .TP -.BI \es( nn +.BI \[rs]s( nn .TQ -.BI \es\(+-( nn +.BI \[rs]s\[+-]( nn Set the point size to .I nn points; @@ -492,13 +579,13 @@ points; must be exactly two digits. . .TP -.BI \es[\(+- n ] +.BI \[rs]s[\[+-] n ] .TQ -.BI \es\(+-[ n ] +.BI \[rs]s\[+-][ n ] .TQ -.BI \es'\(+- n ' +.BI \[rs]s'\[+-] n ' .TQ -.BI \es\(+-' n ' +.BI \[rs]s\[+-]' n ' Set the point size to .I n scaled points; @@ -507,45 +594,47 @@ is a numeric expression with a default scale indicator of\~\c .BR z . . .TP -.BI \eV x +.BI \[rs]V x .TQ -.BI \eV( xx +.BI \[rs]V( xx .TQ -.BI \eV[ xxx ] +.BI \[rs]V[ xxx ] Interpolate the contents of the environment variable .IR xxx , as returned by .BR getenv (3). -.B \eV +.B \[rs]V is interpreted in copy-mode. . .TP -.BI \eY x +.BI \[rs]Y x .TQ -.BI \eY( xx +.BI \[rs]Y( xx .TQ -.BI \eY[ xxx ] +.BI \[rs]Y[ xxx ] This is approximately equivalent to -.BI \eX'\e*[ xxx ]'\fR. +.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 \eX +.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. +. +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 \eZ' anything ' +.BI \[rs]Z' anything ' Print anything and then restore the horizontal and vertical position; .I anything may not contain tabs or leaders. . .TP -.B \e$0 +.B \[rs]$0 The name by which the current macro was invoked. . The @@ -553,66 +642,70 @@ The request can make a macro have more than one name. . .TP -.B \e$* +.B \[rs]$* In a macro, the concatenation of all the arguments separated by spaces. . .TP -.B \e$@ -In a macro, the concatenation of all the arguments with each surrounded by -double quotes, and separated by spaces. +.B \[rs]$@ +In a macro, the concatenation of all the arguments with each +surrounded by double quotes, and separated by spaces. . .TP -.BI \e$( nn +.BI \[rs]$( nn .TQ -.BI \e$[ nnn ] +.BI \[rs]$[ nnn ] In a macro, this gives the .IR nn -th or .IR nnn -th argument. +. Macros can have an unlimited number of arguments. . .TP -.BI \e? anything \e? +.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 \e!\& +.B \[rs]!\& if you want to embed newlines in a diversion. +. The escape sequence -.B \e?\& -is also recognised in copy mode and turned into a single internal code; it -is this code that terminates +.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 B +.ft CB .nf -\&.nr x 1 -\&.nf -\&.di d -\e?\e\e?\e\e\e\e?\e\e\e\e\e\e\e\enx\e\e\e\e?\e\e?\e? -\&.di -\&.nr x 2 -\&.di e -\&.d -\&.di -\&.nr x 3 -\&.di f -\&.e -\&.di -\&.nr x 4 -\&.f +.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 @@ -622,75 +715,82 @@ will print\~\c .BR 4 . . .TP -.B \e/ -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. +.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 right -. nop parenthesis, then in many fonts the top right portion of the f will -. nop overlap the top left of the right parenthesis producing \fIf\fR)\fR, -. nop which is ugly. +. 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 \e/ +. B \[rs]/ . nop produces -. ie \n(.g \fIf\/\fR)\fR -. el \fIf\|\fR)\fR +. 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. +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 \e, -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. +.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 \e, +. B \[rs], . nop between the parenthesis and the f changes -. nop \fR(\fIf\fR to -. ie \n(.g \fR(\,\fIf\fR. -. el \fR(\^\fIf\fR. +. 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 \e) +.B \[rs]) Like -.B \e& +.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. +request to be transparent for the purposes of end-of-sentence +recognition. . .TP -.B \e~ -This produces an unbreakable space that stretches like a normal inter-word -space when a line is adjusted. +.B \[rs]~ +This produces an unbreakable space that stretches like a normal +inter-word space when a line is adjusted. . .TP -.B \e: +.B \[rs]: This causes the insertion of a zero-width break point. +. It is equal to -.B \e% +.B \[rs]% but without insertion of a soft hyphen character. . .TP -.B \e# +.B \[rs]# Everything up to and including the next newline is ignored. +. This is interpreted in copy mode. +. It is like -.B \e" +.B \[rs]" except that -.B \e" +.B \[rs]" does not ignore the terminating newline. . . .\" -------------------------------------------------------------------- -.SS New requests +.SS "New requests" .\" -------------------------------------------------------------------- . .TP @@ -700,6 +800,7 @@ Create an alias 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 @@ -712,13 +813,16 @@ 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). +. +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 , @@ -727,15 +831,16 @@ The .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. +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 .am1\ xx\ yy Similar to .BR .am , but compatibility mode is switched off during execution. +. On entry, the current compatibility mode is saved and restored at exit. . .TP @@ -744,8 +849,8 @@ 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 +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 @@ -753,29 +858,33 @@ 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 B +.ft CB .nf -\&.tr @. -\&.di x -\&@nr n 1 -\&.br -\&.di -\&.tr @@ -\&.asciify x -\&.x +.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 +. +Note that glyph information (font, font size, etc.) is not preserved; +use .B .unformat instead. . @@ -798,19 +907,21 @@ 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. +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. @@ -818,13 +929,13 @@ request. .TP .B .brp This is the same as -.BR \ep . +.BR \[rs]p . . .TP -.BI .cflags\ n\ c1\ c2\|.\|.\|. +.BI .cflags\ n\ c1\ c2\|.\|.\|.\& Characters .IR c1 , -.IR c2 ,\|.\|.\|. +.IR c2 ,\|.\|.\|.\& have properties determined by .IR n , which is ORed from the following: @@ -836,25 +947,26 @@ The character ends sentences (initially characters 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. +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 \-\e(hy\e(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. +.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 \e(ul\e(rn\e(ru +.B \[rs](ul\[rs](rn\[rs](ru have this property); . .IP 16 The character overlaps vertically (initially character -.B \e(br +.B \[rs](br has this property); . .IP 32 @@ -862,8 +974,8 @@ 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')]*\e(dg\e(rq +having a zero space factor in \*[tx] (initially characters +.B \[dq]')]*\[rs](dg\[rs](rq have this property). .RE . @@ -877,34 +989,39 @@ 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 \e +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 +. +Any emboldening, constant spacing or track kerning will be applied to +this object rather than to individual characters in .IR string . -A character defined by this request can be used just like a normal character -provided by the output device. +. +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 \el +.B \[rs]l and -.B \eL +.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. +. There is a special anti-recursion feature: use of character within the -character's definition will be handled like normal characters not defined -with +character's definition will be handled like normal characters not +defined with .BR char . A character definition can be removed with the .B rchar @@ -914,8 +1031,8 @@ request. .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. +This is useful for removing the newline from the end of diversions +that are to be interpolated as strings. . .TP .BI .close\ stream @@ -925,6 +1042,7 @@ Close the stream named will no longer be an acceptable argument to the .B write request. +. See the .B open request. @@ -932,6 +1050,7 @@ request. .TP .B .continue Finish the current iteration of a while loop. +. See also the .B while and @@ -942,7 +1061,9 @@ requests. .BI .cp\ n If .I n -is non-zero or missing, enable compatibility mode, otherwise disable it. +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. . @@ -962,26 +1083,33 @@ 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 +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. +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. +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 -.B -\&.defcolor darkgreen rgb 0.1f 0.5f 0.2f +.ft CB +.Text .defcolor darkgreen rgb 0.1f 0.5f 0.2f +.br +.ft .RE . .IP @@ -993,8 +1121,10 @@ request, thus the above statement is equivalent to . .RS .IP -.B -\&.defcolor darkgreen rgb 0.1 0.5 0.2 +.ft CB +.Text .defcolor darkgreen rgb 0.1 0.5 0.2 +.br +.ft .RE . .TP @@ -1006,12 +1136,13 @@ The following example .RS .IP .NE 2v+\n(.Vu -.ft B +.ft CB .nf -\&.ds xx aa -\&.ds yy bb -\&.dei xx yy +.Text .ds xx aa +.Text .ds yy bb +.Text .dei xx yy .fi +.ft .RE . .IP @@ -1019,8 +1150,10 @@ is equivalent to . .RS .IP -.B -\&.de aa bb +.ft CB +.Text .de aa bb +.br +.ft .RE . .TP @@ -1028,6 +1161,7 @@ is equivalent to 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 @@ -1035,24 +1169,34 @@ On entry, the current compatibility mode is saved and restored at exit. Interpret .I .xxx with compatibility mode disabled. +. For example, . .RS +. .IP -.B -\&.do fam T +.ft CB +.Text .do fam T +.br +.ft +. .P would have the same effect as . .IP -.B -\&.fam T +.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 @@ -1065,7 +1209,7 @@ Restore escape character saved with .BR ecs . Without a previous call to .BR ecs , -.RB ` \e ' +.RB ` \[rs] ' will be the new escape character. . .TP @@ -1073,6 +1217,7 @@ will be the new escape character. Copy the contents of environment .I xx to the current environment. +. No pushing or popping of environments will be done. . .TP @@ -1083,6 +1228,7 @@ The current font family is part of the current environment. If .I xx is missing, switch back to previous font family. +. See the description of the .B sty request for more information on font families. @@ -1097,21 +1243,23 @@ 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 +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\|.\|.\|. +.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. +.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 @@ -1127,7 +1275,7 @@ to Whenever a font named .I f is referred to in an -.B \ef +.B \[rs]f escape sequence, or in the .BR ft , .BR ul , @@ -1151,7 +1299,7 @@ then font will not be translated. . .TP -.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|. +.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\& Set the hyphenation code of character .I c1 to @@ -1162,9 +1310,11 @@ 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 has a hyphenation code, which is itself, -and each upper-case letter has a hyphenation code which is the lower case -version of itself. +. +Initially each lower-case letter has a hyphenation code, which is +itself, and each upper-case letter has a hyphenation code which is the +lower case version of itself. +. See also the .B hpf request. @@ -1178,6 +1328,7 @@ Hyphenation exceptions specified with the 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 @@ -1191,12 +1342,16 @@ Set the maximum number of consecutive hyphenated lines to\~\c 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. +. +Only lines output from an environment count towards the maximum +associated with that environment. +. Hyphens resulting from -.B \e% +.B \[rs]% are counted; explicit hyphens are not. . .TP @@ -1208,17 +1363,21 @@ this will be searched for in the same way that is searched for when the .BI \-m name option is specified. -It should have the same format as the argument to the \epatterns primitive -in \*(tx; the letters appearing in this file are interpreted as hyphenation -codes. +. +It should have the same format as the argument to the \[rs]patterns +primitive in \*[tx]; the letters appearing in this file are interpreted +as hyphenation codes. +. A .BR % \~\c -character in the patterns file introduces a comment that continues to the -end of the line. -The set of hyphenation patterns is associated with the current language set -by the +character in the patterns file introduces a comment that continues +to the end of the line. +. +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 @@ -1236,12 +1395,15 @@ when the current adjustment mode is not\~\c 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 \en[.hym] +.B \[rs]n[.hym] register. . .TP @@ -1252,15 +1414,19 @@ 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 +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 \en[.hys] +.B \[rs]n[.hys] register. . .TP @@ -1268,7 +1434,7 @@ register. Variant of .B .it for which a line interrupted with -.B \ec +.B \[rs]c counts as one input line. . .TP @@ -1291,24 +1457,28 @@ 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. +. +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 B +.ft CB .nf -\&.ds x a\et\ec -\&.ds y b\et\ec -\&.ds z c -\&.ta 1i 3i -\e*x -\e*y -\e*z +.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 @@ -1328,9 +1498,9 @@ a b c .RE . .IP -Line-tabs mode is associated with the current environment; the read-only -number register -.B \\en[.linetabs] +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 @@ -1342,6 +1512,7 @@ request except that 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, @@ -1363,6 +1534,7 @@ Make the built-in condition true and the .B t built-in condition false. +. This can be reversed using the .B troff request. @@ -1374,6 +1546,7 @@ Open for writing and associate the stream named .I stream with it. +. See also the .B close and @@ -1390,25 +1563,27 @@ exists, append to it instead of truncating it. . .TP .B .pnr -Print the names and contents of all currently defined number registers on -stderr. +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 +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 \en[llx] , -.BR \en[lly] , -.BR \en[urx] , +. +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 \en[ury] , +.BR \[rs]n[ury] , respectively. +. If some error has occurred, the four registers are set to zero. . .TP @@ -1427,7 +1602,7 @@ Empty slots in the page trap list are printed as well, because they can affect the priority of subsequently planted traps. . .TP -.BI .rchar\ c1\ c2\|.\|.\|. +.BI .rchar\ c1\ c2\|.\|.\|.\& Remove the definitions of characters .IR c1 , .IR c2 ,\|.\|.\|. @@ -1438,19 +1613,23 @@ request. .TP .B .return Within a macro, return immediately. +. No effect otherwise. . .TP .B .rj .TQ -.BI .rj\ n +.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 \en[.rj] +.B \[rs]n[.rj] register. +. This implicitly does .BR .ce \~0 . The @@ -1472,12 +1651,14 @@ Set the soft hyphen character to If .I c is omitted, the soft hyphen character will be set to the default -.BR \e(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. +.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 @@ -1495,13 +1676,15 @@ becomes argument 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 .special\ s1\ s2\|.\|.\|. +.BI .special\ s1\ s2\|.\|.\|.\& Fonts .IR s1 , .IR s2 , @@ -1515,20 +1698,25 @@ Associate style\~\c 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 +. +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 , @@ -1536,11 +1724,13 @@ When the requests .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. +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 styles command in the .SM DESC file controls which font positions (if any) are initially associated @@ -1555,17 +1745,20 @@ with the substring defined by the indices and .IR n2 . The first character in the string has index one. +. 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 or zero, it will be counted from the end of the string, going -backwards: -The last character has index\~0, the character before the last character has -index\~-1, etc. +is negative or zero, it will be counted from the end of the string, +going backwards: +. +The last character has index\~0, the character before the last +character has index\~-1, etc. . .TP .BI .tkf\ f\ s1\ n1\ s2\ n2 @@ -1612,10 +1805,12 @@ but without writing a final newline. .BI .trf\ filename Transparently output the contents of file .IR filename . -Each line is output as it would be preceded by -.BR \e! ; +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 @@ -1625,12 +1820,13 @@ using .RS .IP .NE 2v+\n(.Vu -.ft B +.ft CB .nf -\&.di x -\&.trf f -\&.di +.Text .di x +.Text .trf f +.Text .di .fi +.ft .RE . .IP @@ -1646,18 +1842,18 @@ 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 \e! . +.BR \[rs]! . For example, . .RS .IP .nf -.ft B -\&.tr ab -\&.di x -\e!.tm a -\&.di -\&.x +.ft CB +.Text .tr ab +.Text .di x +.Text \[rs]!.tm a +.Text .di +.Text .x .fi .ft .RE @@ -1671,6 +1867,7 @@ is used instead of .B tr it will print\~\c .BR a . +.RE . .TP .B .troff @@ -1679,6 +1876,7 @@ Make the built-in condition false, and the .B t built-in condition true. +. This undoes the effect of the .B nroff request. @@ -1689,15 +1887,19 @@ 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, +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. +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 @@ -1709,16 +1911,20 @@ requests. 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. +. +The parameter that controls whether vertical position traps are +enabled is global. +. Initially vertical position traps are enabled. . .TP @@ -1727,12 +1933,16 @@ 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 the `Warnings' section. +. +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. @@ -1750,9 +1960,9 @@ can be any condition acceptable to an request; .I anything can comprise multiple lines if the first line starts with -.B \e{ +.B \[rs]{ and the last line ends with -.BR \e} . +.BR \[rs]} . See also the .B break and @@ -1772,7 +1982,7 @@ request. .I anything is read in copy mode; a leading\~\c -.B \(dq +.B \[dq] will be stripped. . .TP @@ -1790,21 +2000,21 @@ is read in copy mode. . . .\" -------------------------------------------------------------------- -.SS Extended requests +.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 +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. +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 @@ -1815,21 +2025,27 @@ is not a number, this will switch to a named environment called 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. +. +There is no limit on the number of named environments; they will be +created the first time that they are referenced. . .TP .BI .fp\ n\ f1\ f2 The .B fp request has an optional third argument. -This argument gives the external name of the font, which is used for finding -the font description file. -The second argument gives the internal name of the font which is used to -refer to the font in troff after it has been mounted. -If there is no third argument then the internal name will be used as the -external name. -This feature allows you to use fonts with long names in compatibility mode. +. +This argument gives the external name of the font, which is used for +finding the font description file. +. +The second argument gives the internal name of the font which is used +to refer to the font in troff after it has been mounted. +. +If there is no third argument then the internal name will be used as +the external name. +. +This feature allows you to use fonts with long names in compatibility +mode. . .TP .BI .ss\ m\ n @@ -1837,24 +2053,33 @@ 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 +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. +. +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 @@ -1864,7 +2089,7 @@ Set tabs at positions .I nn and then set tabs at .IR nn + r1 , -.IR nn + r2 ,\|.\|.\|.\|.\|, +.IR nn + r2 ,\|.\|.\|.\|, .IR nn + rn and then at .IR nn + rn + r1 , @@ -1875,265 +2100,284 @@ For example, . .RS .IP -.B -\&.ta T .5i +.ft CB +.Text .ta T .5i +.br +.ft +. .P will set tabs every half an inch. .RE . . .\" -------------------------------------------------------------------- -.SS New number registers +.SS "New number registers" .\" -------------------------------------------------------------------- . The following read-only registers are available: . .TP -.B \en[.C] +.B \[rs]n[.C] 1\~if compatibility mode is in effect, 0\~otherwise. . .TP -.B \en[.cdp] +.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 \en[.ce] +.B \[rs]n[.ce] The number of lines remaining to be centered, as set by the .B ce request. . .TP -.B \en[.cht] +.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 \en[.csk] +.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. +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 \en[.ev] +.B \[rs]n[.ev] The name or number of the current environment. +. This is a string-valued register. . .TP -.B \en[.fam] +.B \[rs]n[.fam] The current font family. +. This is a string-valued register. . .TP -.B \en[.fn] +.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 \en[.fn] +.B \[rs]n[.fn] is the proper concatenation of family and style name. . .TP -.B \en[.fp] +.B \[rs]n[.fp] The number of the next free font position. . .TP -.B \en[.g] +.B \[rs]n[.g] Always\~1. +. Macros should use this to determine whether they are running under GNU troff. . .TP -.B \en[.hla] +.B \[rs]n[.hla] The current hyphenation language as set by the .B hla request. . .TP -.B \en[.hlc] +.B \[rs]n[.hlc] The number of immediately preceding consecutive hyphenated lines. . .TP -.B \en[.hlm] -The maximum allowed number of consecutive hyphenated lines, as set by the +.B \[rs]n[.hlm] +The maximum allowed number of consecutive hyphenated lines, as set by +the .B hlm request. . .TP -.B \en[.hy] +.B \[rs]n[.hy] The current hyphenation flags (as set by the .B hy request). . .TP -.B \en[.hym] +.B \[rs]n[.hym] The current hyphenation margin (as set by the .B hym request). . .TP -.B \en[.hys] +.B \[rs]n[.hys] The current hyphenation space (as set by the .B hys request). . .TP -.B \en[.in] +.B \[rs]n[.in] The indent that applies to the current output line. . .TP -.B \en[.int] +.B \[rs]n[.int] Set to a positive value if last output line is interrupted (i.e., if it contains -.IR \ec ). +.IR \[rs]c ). . .TP -.B \en[.kern] +.B \[rs]n[.kern] 1\~if pairwise kerning is enabled, 0\~otherwise. . .TP -.B \en[.lg] +.B \[rs]n[.lg] The current ligature mode (as set by the .B lg request). . .TP -.B \en[.linetabs] +.B \[rs]n[.linetabs] The current line-tabs mode (as set by the .B linetabs request). . .TP -.B \en[.ll] +.B \[rs]n[.ll] The line length that applies to the current output line. . .TP -.B \en[.lt] +.B \[rs]n[.lt] The title length as set by the .B lt request. . .TP -.B \en[.ne] +.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 \en[.trunc] +.B \[rs]n[.trunc] register. . .TP -.B \en[.ns] +.B \[rs]n[.ns] 1\~if no-space mode is active, 0\~otherwise. . .TP -.B \en[.pn] +.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 \en[.ps] +.B \[rs]n[.ps] The current pointsize in scaled points. . .TP -.B \en[.psr] +.B \[rs]n[.psr] The last-requested pointsize in scaled points. . .TP -.B \en[.rj] +.B \[rs]n[.rj] The number of lines to be right-justified as set by the .B rj request. . .TP -.B \en[.sr] +.B \[rs]n[.sr] The last requested pointsize in points as a decimal fraction. +. This is a string-valued register. . .TP -.B \en[.tabs] -A string representation of the current tab settings suitable for use as an -argument to the +.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 \en[.trunc] -The amount of vertical space truncated by the most recently sprung vertical -position trap, or, if the trap was sprung by a +.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. +. +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 \en[.ne] +.B \[rs]n[.ne] register. . .TP -.B \en[.ss] -.TQ -.B \en[.sss] -These give the values of the parameters set by the first and second -arguments of the -.B ss -request. -. -.TP -.B \en[.vpt] +.B \[rs]n[.vpt] 1\~if vertical position traps are enabled, 0\~otherwise. . .TP -.B \en[.warn] +.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 the `Warnings' -subsection. +. +The number associated with each warning is listed in +.BR @g@troff (@MAN1EXT@). . .TP -.B \en[.x] +.B \[rs]n[.x] The major version number. +. For example, if the version number is 1.03, then -.B \en[.x] +.B \[rs]n[.x] will contain\~1. . .TP -.B \en[.y] +.B \[rs]n[.y] The minor version number. +. For example, if the version number is 1.03, then -.B \en[.y] +.B \[rs]n[.y] will contain\~03. . .TP -.B \en[.Y] +.B \[rs]n[.Y] The revision number of groff. . .TP -.B \en[llx] +.B \[rs]n[llx] .TQ -.B \en[lly] +.B \[rs]n[lly] .TQ -.B \en[urx] +.B \[rs]n[urx] .TQ -.B \en[ury] +.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. +.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 \ew +.B \[rs]w escape sequence: . .TP -.B \en[rst] +.B \[rs]n[rst] .TQ -.B \en[rsb] +.B \[rs]n[rsb] Like the .B st and @@ -2141,14 +2385,14 @@ and registers, but take account of the heights and depths of characters. . .TP -.B \en[ssc] -The amount of horizontal space (possibly negative) that should be added to -the last character before a subscript. +.B \[rs]n[ssc] +The amount of horizontal space (possibly negative) that should be +added to the last character before a subscript. . .TP -.B \en[skw] +.B \[rs]n[skw] How far to right of the center of the last character in the -.B \ew +.B \[rs]w argument, the center of an accent from a roman font should be placed over that character. . @@ -2156,36 +2400,39 @@ over that character. Other available read/write number registers are: . .TP -.B \en[c.] +.B \[rs]n[c.] The current input line number. -.B \en[.c] +.B \[rs]n[.c] is a read-only alias to this register. . .TP -.B \en[hp] +.B \[rs]n[hp] The current horizontal position at input line. . .TP -.B \en[systat] +.B \[rs]n[systat] The return value of the system() function executed by the last .B sy request. . .TP -.B \en[slimit] +.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. +. +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 \en[year] +.B \[rs]n[year] The current year. . Note that the traditional .B troff number register -.B \en[yr] +.B \[rs]n[yr] is the current year minus 1900. . . @@ -2195,7 +2442,7 @@ is the current year minus 1900. . .B @g@troff predefines a single (read/write) string-based register, -.BR \e*(.T , +.BR \[rs]*(.T , which contains the argument given to the .B -T command line option, namely the current output device (for example, @@ -2203,73 +2450,83 @@ command line option, namely the current output device (for example, or .IR ascii ). Note that this is not the same as the (read-only) number register -.B \en[.T] +.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. +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 \en[.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. +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\ \e\e$@ +.BI . xx\ \[rs]\[rs]$@ .P is . .IP -.BI \e\e*[ xx ]\e\e +.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 \e& +.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. +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 \ew -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. +.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. +. When decoding a macro 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. +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 \e$@ -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. +.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 +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. . @@ -2300,9 +2557,9 @@ available; is either an .SM ASCII character or a special character -.BI \e( xx +.BI \[rs]( xx or -.BI \e[ xxx ]\fR; +.BI \[rs][ xxx ]\f[R]; the condition will also be true if .I ch has been defined by the @@ -2313,159 +2570,613 @@ request. The .B tr request can now map characters onto -.BR \e~ . +.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. +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 B +.ft CB .nf -\&.de foo -\&. nop Hello, I'm `foo'. -\&. nop I will now define `bar'. -\&. de bar -\&. nop Hello, I'm `bar'. -\&. . -\&.. +.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 Incompatibilities +.SH "INTERMEDIATE OUTPUT FORMAT" .\" -------------------------------------------------------------------- . -Long names cause some incompatibilities. +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. . -UNIX troff will interpret +Only the differences are documented here. . +. +.\" -------------------------------------------------------------------- +.SS "Units" +.\" -------------------------------------------------------------------- +. +.P +The argument to the +.B s +command is in scaled points (units of +.IR 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" +.\" -------------------------------------------------------------------- +. +.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, a new command has been added: +. +.TP +.Text \f[B]m \f[I]r g b\f[R] +.TQ +.Text \f[B]m #\f[I]rrggbb\f[R] +.TQ +.Text \f[B]m ##\f[I]rrrrggggbbbb\f[R] +Set the red, green, and blue components of the current drawing color to +.IR r , +.IR g , +and +.I b +(to be specified as fractions in the range 0 to 1), or +.IR rr , +.IR gg , +and +.I bb +(to be specified as hexadecimal values in the range 0 to 0xff), or +.IR rrrr , +.IR gggg , +and +.I bbbb +(to be specified as hexadecimal values in the range 0 to 0xffff). +.B troff +emits only the latest form. +. +.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$ $...$ \c +.Text $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$ $...$ \c +.Text $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 Df , +.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 extension is +. +.TP +.Text \f[B]DF \f[I]r g b\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DF #\f[I]rrggbb\f[R]\*[ic]\[rs]n +.TQ +.Text \f[B]DF ##\f[I]rrrrggggbbbb\f[R]\*[ic]\[rs]n +Set the RGB components of the filling color similar to the +.B m +command above. +. +. +.\" -------------------------------------------------------------------- +.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 -.B -\&.dsabcd +.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" +.\" -------------------------------------------------------------------- +. +.P +.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 . -Normally, GNU troff will interpret this as a call of a macro named -.BR dsabcd . -Also UNIX troff will interpret -.B \e*[ +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 -.B \en[ +.esc n[ as references to a string or number register called -.BR [ . -In GNU troff, however, this will normally be interpreted as the start of a -long name. +.request [ +while +.I groff +takes this as the start of a long name. +. +.P In -.I compatibility mode -GNU troff will interpret these things in the traditional way. -In compatibility mode, however, long names are not recognised. -Compatibility mode can be turned on with the -.B \-C -command line option, and turned on or off with the -.B cp -request. -The number register -.B \en[.C] -is\~1 if compatibility mode is on, 0\~otherwise. +.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 -GNU troff does not allow the use of the escape sequences -.BR \e\e\e|\e^\e&\e}\e{\e (space) \e'\e`\e-\e_\e!\e%\ec -in names of strings, macros, diversions, number registers, fonts or -environments; UNIX troff does. The -.B \eA -escape sequence may be helpful in avoiding use of these escape sequences in +.esc A +escape sequence can be helpful in avoiding these escape sequences in names. . .P Fractional pointsizes cause one noteworthy incompatibility. -In UNIX troff the -.B ps -request ignores scale indicators and so . -.IP -.B .ps\ 10u +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 GNU troff it will set the -pointsize to 10 scaled points. +will set the pointsize to 10\~points, whereas in groff native mode the +pointsize will be set to 10\~scaled points. . .P -In GNU troff 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 -.BR bd , -.BR cs , -.BR tkf , -.BR tr , +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 -.B fp +.request fp requests. -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. -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. -For example, . -.IP -.NE 4v+\n(.Vu -.ft B +.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 -\&.di x -\e\e\e\e -\&.br -\&.di -\&.x +.ft CB +.Text .di x +.Text \[rs]\[rs]\[rs]\[rs] +.Text .br +.Text .di +.Text .x .ft .fi +.RE . .P -will print -.B \e\e -in GNU troff; each pair of input -.BR \e s -is turned into one output -.B \e -and the resulting output -.BR \e s -are not interpreted as escape characters when they are reread. -UNIX troff would interpret them as escape characters when they were reread -and would end up printing one -.BR \e . -The correct way to obtain a printable -.B \e -is to use the -.B \ee -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 troff and UNIX troff. -If you wish for some reason to store in a diversion an escape sequence that -will be interpreted when the diversion is reread, you can either use the -traditional -.B \e!\& -transparent output facility, or, if this is unsuitable, the new -.B \e?\& -escape sequence. +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 AUTHOR +.SH AUTHORS .\" -------------------------------------------------------------------- . -Copyright (C) 1989, 2001 Free Software Foundation, Inc. +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. . .P This document is distributed under the terms of the FDL (GNU Free @@ -2476,36 +3187,43 @@ available on-line at the .URL "GNU copyleft site" http://\:www.gnu.org/\:copyleft/\:fdl.html . . This document was written by James Clark, with modifications by -.URL "Werner Lemberg" mailto:wl@gnu.org +.URL "Werner Lemberg" mailto:\:wl@gnu.org and -.URL "Bernd Warken" mailto:bwarken@mayn.de +.URL "Bernd Warken" mailto:\:bwarken@mayn.de . . .P This document is part of .IR groff , the GNU roff distribution. -Formerly, the informations of this document were kept in the manual page -.BR troff (@MAN1EXT@). +. +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 available in +command line options and warnings are still documented in .BR @g@troff (@MAN1EXT@). . -. .\" -------------------------------------------------------------------- .SH "SEE ALSO" .\" -------------------------------------------------------------------- . +.P +The +.I groff info +.IR file , +cf.\& +.BR info (1) +presents all groff documentation within a single document. +. .TP -.BR roff (@MAN7EXT@) -An overview over -.I groff -and other -.I roff -systems, including pointers to further related documentation. +.BR groff (@MAN1EXT@) +A list of all documentation around +.IR groff . . .TP .BR groff (@MAN7EXT@) @@ -2514,28 +3232,23 @@ A description of the language, including a short, but complete reference of all predefined requests, registers, and escapes of plain .IR groff . -From the command line, this is called by -.BR man\~7\~groff . +From the command line, this is called using . -.P -The -.I groff info -.IR file , -cf.\& -.BR info (@MAN1EXT@), -presents all groff documentation within a single document. +.IP +.ShellCommand man\~7\~groff . -.P -The classical -.I troff -documentation is available on-line at -.URL "Bell Labs CSTR site" http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html . -This includes as -.I CSTR #54 -the +.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 +.I J.\& F.\& Osanna of 1976 in the revision of .I Brian Kernighan of 1992, being the diff --git a/man/roff.man b/man/roff.man index 4295be51..fdd1af8b 100644 --- a/man/roff.man +++ b/man/roff.man @@ -1,7 +1,7 @@ .ig roff.man -Last update: 02 Jan 2002 +Last update: 06 Jan 2002 This file is part of groff, the GNU roff type-setting system. @@ -23,10 +23,6 @@ FDL in the main directory of the groff source package. .\" Setup .\" -------------------------------------------------------------------- . -.if \n[.g] \{\ -. do mso www.tmac -.\} -. .mso www.tmac . .if n \{\ @@ -35,61 +31,55 @@ FDL in the main directory of the groff source package. . ftr CI I . ftr CB B .\} +. .if '\*[.T]'dvi' \{\ . ftr CB CW .\} . -.ds backslash \(rs\" -.ds dquote ""\" -.ds comment \*[backslash]\*[dquote]\" . +.\" -------------------------------------------------------------------- .\" Begin of macro definitions .eo . -.de text +.de Text . nop \)\$* .. .de ellipsis -. text .\|.\|.\&\" -.. -.de argname -. ds @arg1 \$1 -. shift 1 -. nop \fI\*[@arg1]\fP\$* -. rm @arg1 +. Text .\|.\|.\&\" .. .de esc -. ds @arg1 \$1 +. ds @1 \$1\" . shift -. nop \fB\*[backslash]\*[@arg1]\fP\$* -. rm @arg1 +. Text \f[B]\[rs]\*[@1]\f[P]\$* +. rm @1 .. .de option -. ds @arg1 \$1 +. ds @1 \$1\" . shift 1 -. nop \fB\*[@arg1]\fP\$* -. rm @arg1 +. Text \f[B]\*[@1]\f[P]\$* +. rm @1 .. .de quoted_char -. ds @arg1 \$1 +. ds @1 \$1 . shift . nop `\fB\*[@arg1]\fP'\$* -. rm @arg1 -.. -.de TP+ -.br -.ns -.TP \$1 +. rm @1 .. -.\" -------------------------------------------------------------------- -.\" A shell command line .de ShellCommand . br -. IR "shell>" "\h'1m'\f(CB\$*\fP\/" +. IR "shell#" "\h'1m'\f[CB]\$*\f[P]\/" +.. +.de TP+ +. br +. ns +. TP \$1 +.. +.de Topic +. TP 2m +. Text \[bu] .. -.\" -------------------------------------------------------------------- -.\" End of macro definitions .ec +.\" End of macro definitions . . .\" -------------------------------------------------------------------- @@ -148,8 +138,8 @@ 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 other free type-setting programs and -is better than some of the commercial systems. +output has the same quality as other free type-setting programs and is +better than some of the commercial systems. . .P This document gives only an overview and provides pointers to further @@ -259,7 +249,7 @@ 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 +first published in 1976, with further revisions up to 1992 by Brian Kernighan. . The system described therein is referred to as the @@ -279,7 +269,7 @@ postprocessor system. This completed the structure of a .I "roff system" as it is still in use today; see section -.IR "PARTS OF A ROFF SYSTEM" . +.IR "USING ROFF" . . In 1979, these novelties were described in the paper .IR "[CSTR\~#97]" . @@ -288,16 +278,16 @@ systems, including .IR groff . . .P -A major catastrophy occurred when the free Unix\~7 operating system was -commercialized. +A major catastrophy occurred when the freely available Unix\~7 +operating system was commercialized. . A whole bunch of divergent operating systems emerged, fighting each -other with incompatibilities, and finally causing many different roff +other with incompatibilities, finally causing many different roff systems. . All of them used Osanna/Kernighan's free source code and his troff papers as their main documentation, but sold them together with -"their" system \(em with only minor modifications. +"their" system \[em] with only minor modifications. . Though most commercial roff systems added incompatible extensions, all of them try to achieve compatibility with the original, free troff. @@ -325,7 +315,7 @@ Though being compatible with the classical troff, many extensions were added that greatly simplify roff programming. . It is the first roff system that is available on almost all operating -systems \(em and it is free. +systems \[em] and it is free. . This makes groff the de-facto roff standard today. . @@ -355,12 +345,11 @@ 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 +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 +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. . @@ -381,6 +370,7 @@ for the next program. .P .B cat .I file +.B | .ellipsis .B | preproc | .ellipsis @@ -444,7 +434,7 @@ The classical preprocessors are for tables .TP .B eqn -for mathematical formul\(ae +for mathematical formul\[ae] .TP .B pic for drawing diagrams @@ -466,7 +456,7 @@ include .PD 0 .TP .B chem -for drawing chemical formul\(ae. +for drawing chemical formul\[ae]. .TP .B grap for constructing graphical elements. @@ -559,15 +549,14 @@ For example, the classical devices mentioned in have greatly changed since the classical times. . The old hardware doesn't exist any longer and the old graphical -conversions are quite imprecise as compared to their modern +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 -.IR groff 's +of 720, while groff .I ps has 72000, a refinement of factor 100. . @@ -671,14 +660,14 @@ 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 +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 .quoted_char . . . .P .I Escape sequences are roff elements starting with a backslash -.quoted_char \*[backslash] . +.quoted_char \[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 @@ -687,7 +676,7 @@ non-ASCII characters with font changes with .esc f , in-line comments with -.esc \(dq , +.esc \[dq] , the escaping of special control characters like .esc \e , and many other features. @@ -701,7 +690,7 @@ A string is stored by the request. . The stored string can be retrieved later by the -.B \*[backslash]* +.B \[e]* escape sequence. . .P @@ -711,7 +700,7 @@ 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 "\*[backslash]n" . +.BR "\[e]n" . . . .\" -------------------------------------------------------------------- @@ -785,7 +774,7 @@ This mode can be activated by the following methods. . .P When editing a file within Emacs the mode can be changed by typing -.RB ` "M-x nroff mode" ', +.RI ` "M-x nroff-mode" ', where .B M-x means to hold down the @@ -799,6 +788,7 @@ 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 There is a set of file name extensions, e.g. the man pages that trigger the automatic activation of the nroff mode. @@ -811,6 +801,7 @@ in the first line is switched into nroff mode when loaded. But do not use this, it confuses some applications such as the .B man program. +. .Topic The best method is to include the following 3 comment lines at the end of the file. @@ -831,8 +822,9 @@ is to start each sentence on a line of its own without preceding white space. . 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. +an empty roff request (a line consisting of a dot +.quoted_char . +only) after each sentence. . This suits the general roff rule to never use blank lines because they can produce unexpected behavior in the vertical spacing; so each line @@ -846,10 +838,10 @@ The following example shows how optimal roff editing could look. .IP .nf This is a sentence. -.text . +.Text . This is a longer sentence stretching over several lines. -.text . +.Text . etc. .fi . @@ -910,13 +902,13 @@ its standard programs are the papers in the series These also contain the two main documents of the early nroff/troff, being .TP -.I [CSTR #54] -The 1992 revision of Osanna/Kernighan's 1976 paper +.I [CSTR\~#54] +The 1992\~revision of Osanna/Kernighan's 1976\~paper .URL "Nroff/\:Troff User's Manual" \ http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps . .TP -.I [CSTR #97] -Brian Kernighan's 1979 paper +.I [CSTR\~#97] +Brian Kernighan's 1979\~paper .URL "A Typesetter-independent TROFF" \ http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps . . @@ -989,9 +981,9 @@ This document is part of the GNU roff distribution. . It was written by -.MAILTO bwarken@mayn.de "Bernd Warken" ; +.URL "Bernd Warken" mailto:\:bwarken@mayn.de ; it is maintained by -.MAILTO wl@gnu.org "Werner Lemberg" . +.URL "Werner Lemberg" mailto:\:wl@gnu.org . . . .\" -------------------------------------------------------------------- -- cgit v1.2.1