xref: /freebsd/share/doc/usd/21.troff/m1 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

Redistributions of source code and documentation must retain the above
copyright notice, this list of conditions and the following
disclaimer.

Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

All advertising materials mentioning features or use of this software
must display the following acknowledgement:

This product includes software developed or owned by Caldera
International, Inc. Neither the name of Caldera International, Inc.
nor the names of other contributors may be used to endorse or promote
products derived from this software without specific prior written
permission.

USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

@(#)m1 8.1 (Berkeley) 8/14/93

$FreeBSD$
.nr p 0 1 .tr | .tr ~|

.rs .sp1.0i
REFERENCE MANUAL .mh General Explanation .sc Form of input. Input consists of text lines, which are destined to be printed, interspersed with control lines, which set parameters or otherwise control subsequent processing. Control lines begin with a control character\(em\ normally . (period) or \' (acute accent)\(em\ followed by a one or two character name that specifies a basic request or the substitution of a user-defined macro in place of the control line. The control character \' suppresses the break function\(em\ the forced output of a partially filled line\(em\ caused by certain requests. The control character may be separated from the request/macro name by white space (spaces and/or tabs) for \(aesthetic reasons. Names must be followed by either space or newline. Control lines with unrecognized names are ignored. .pg Various special functions may be introduced anywhere in the input by means of an escape character, normally \e. For example, the function \enR causes the interpolation (insertion in place) of the contents of the number register R in place of the function; here R is either a single character name as in \enx, or left-parenthesis-introduced, two-character name as in \en(xx. .sc Formatter and device resolution. \*(TR internally uses 432 units\(slinch, (for historical reasons, corresponding to the Graphic Systems phototypesetter which had a horizontal resolution of 1\(sl432 inch and a vertical resolution of 1\(sl144 inch.) \*(NR internally uses 240 units\(slinch, corresponding to the least common multiple of the horizontal and vertical resolutions of various typewriter-like output devices. \*(TR rounds horizontal\(slvertical numerical parameter input to its own internal horizontal\(slvertical resolution. \*(NR similarly rounds numerical input to the actual resolution of the output device indicated by the -T option (default Model 37 Teletype). .sc Numerical parameter input. Both \*(NR and \*(TR accept numerical input with the scale indicator suffixes shown in the following table, where S is the current type size in points, V is the current vertical line spacing in basic units, and C is a nominal character width in basic units.

Scale Number of basic units
Indicator Meaning \*(TR \*(NR
i Inch 432 240
c Centimeter 432\(mu50\(sl127 240\(mu50\(sl127
P Pica = 1\(sl6 inch 72 240\(sl6
m Em = S points 6\(muS C
n En = Em\(sl2 3\(muS C, same as Em
p Point = 1\(sl72 inch 6 240\(sl72
u Basic unit 1 1
v Vertical line space V V
none Default, see below
In \*(NR, both the em and the en are taken to be equal to the C, which is output-device dependent; common values are 1\(sl10 and 1\(sl12 inch. Actual character widths in \*(NR need not be all the same and constructed characters such as -> (\(->) are often extra wide. The default scaling is ems for the horizontally-oriented requests and functions ll, in, ti, ta, lt, po, mc, \eh, and \el; V\^s for the vertically-oriented requests and functions pl, wh, ch, dt, sp, sv, ne, rt, \ev, \ex, and \eL; p for the vs request; and u for the requests nr, if, and ie. All other requests ignore any scale indicators. When a number register containing an already appropriately scaled number is interpolated to provide numerical input, the unit scale indicator u may need to be appended to prevent an additional inappropriate default scaling. The number, N, may be specified in decimal-fraction form but the parameter finally stored is rounded to an integer number of basic units. .pg The absolute position indicator ~ may be prefixed to a number N to generate the distance to the vertical or horizontal place N. For vertically-oriented requests and functions, ~\|N becomes the distance in basic units from the current vertical place on the page or in a diversion (\(sc7.4) to the vertical place N. For all other requests and functions, ~\|N becomes the distance from the current horizontal place on the input line to the horizontal place N. For example, .x1 \fB.sp ~\|3.2c .x2 will space in the required direction to 3.2 centimeters from the top of the page. .sc .tr && Numerical expressions. Wherever numerical input is expected, an expression involving parentheses, the arithmetic operators \(pl, -, \(sl, \(**, % (mod), and the logical operators <, >, <\(eq, >\(eq, \(eq (or \(eq\(eq), & (and), : (or) may be used. Except where controlled by parentheses, evaluation of expressions is left-to-right; there is no operator precedence. In the case of certain requests, an initial \(pl or - is stripped and interpreted as an increment or decrement indicator respectively. In the presence of default scaling, the desired scale indicator must be attached to every number in an expression for which the desired and default scaling differ. For example, if the number register x contains 2 and the current point size is 10, then

.tr &. .x1 .ll (4.25i\(pl\enxP\(pl3)\(sl2u .x2 will set the line length to 1\(sl2 the sum of 4.25 inches \(pl 2 picas \(pl 30 points. .sc Notation. Numerical parameters are indicated in this manual in two ways. \(+-N means that the argument may take the forms N, \(plN, or -N and that the corresponding effect is to set the affected parameter to N, to increment it by N, or to decrement it by N respectively. Plain N means that an initial algebraic sign is not an increment indicator, but merely the sign of N. Generally, unreasonable numerical input is either ignored or truncated to a reasonable value. For example, most requests expect to set parameters to non-negative values; exceptions are sp, wh, ch, nr, and if. The requests ps, ft, po, vs, ls, ll, in, and lt restore the previous parameter value in the absence of an argument. .pg Single character arguments are indicated by single lower case letters and one/two character arguments are indicated by a pair of lower case letters. Character string arguments are indicated by multi-character mnemonics. .mh Font and Character Size Control .sc Character set. The \*(TR character set consists of a typesetter-dependent basic character set plus a Special Mathematical Font character set\(emeach having 102 characters. An example of these character sets is shown in the Appendix Table|I. All printable \s-1ASCII\s+1 characters are included, with some on the Special Font. With three exceptions, these \s-1ASCII\s+1 characters are input as themselves, and non-\s-1ASCII\s+1 characters are input in the form \e(xx where xx is a two-character name given in the Appendix Table|II. The three \s-1ASCII\s+1 exceptions are mapped as follows:

\s-1ASCII\s+1 Input Printed by \*(TR
Character Name Character Name
\' acute accent ' close quote
\` grave accent ` open quote
- minus - hyphen
.tr ~~ The characters \', \`, and - may be input by \e\', \e\`, and \e- respectively or by their names (Table II). The \s-1ASCII\s+1 characters @, #, ", \(aa, \(ga, <, >, \e, {, }, ~, ^, and \(ul exist only on the Special Font and are printed as a 1-em space if that font is not mounted. .pg .tr ~| \*(NR understands the entire \*(TR character set, but can in general print only \s-1ASCII\s+1 characters, additional characters as may be available on the output device, such characters as may be able to be constructed by overstriking or other combination, and those that can reasonably be mapped into other printable characters. The exact behavior is determined by a driving table prepared for each device. The characters \', \`, and \(ul print as themselves. .sc Fonts. The default mounted fonts are Times Roman (R), Times Italic (I), Times Bold (B), and the Special Mathematical Font (S) on physical typesetter positions 1, 2, 3, and 4 respectively. These fonts are used in this document. The current font, initially Roman, may be changed (among the mounted fonts) by use of the ft request, or by imbedding at any desired point either \efx, \ef(xx, or \efN where x and xx are the name of a mounted font and N is a numerical font position. It is not necessary to change to the Special Font; characters on that font are automatically handled. A request for a named but not-mounted font is ignored. \*(TR can be informed that any particular font is mounted by use of the fp request. The list of known fonts is installation dependent. In the subsequent discussion of font-related requests, F represents either a one\(sltwo-character font name or the numerical font position, 1-4. The current font is available (as numerical position) in the read-only number register .f. .pg \*(NR understands font control and normally underlines Italic characters (see \(sc10.5). .sc Character size. Character point sizes available are typesetter dependent, but often include 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. This is a range of 1\(sl12 inch to 1\(sl2 inch. The ps request is used to change or restore the point size. Alternatively the point size may be changed between any two characters by imbedding a \esN at the desired point to set the size to N, or a \es\(+-N (1\(<=N\(<=9) to increment\(sldecrement the size by N; \es0 restores the previous size. Requested point size values that are between two valid sizes yield the larger of the two. The current size is available in the .s register. \*(NR ignores type size control. .h1 * .fn .xx *Notes are explained at the end of the Summary and Index above. .ef .bt &ps|\(+-N 10\|point previous E Point size set to \(+-N. Alternatively imbed \esN or \es\(+-N. Any positive size value may be requested; if invalid, the next larger valid size will result, with a maximum of 36. A paired sequence \(plN,\|-N will work because the previous requested value is also remembered. Ignored in \*(NR. .bt &fz|F|\(+-N off - E The characters in font F will be adjusted to be in size \(+-N. Characters in the Special Font encountered during the use of font F will have the same size modification. (Use the &fz S request if different treatment of Special Font characters is required). &fz must follow any &fp request for the position. .bt &fz|S|F|\(+-N off - E The characters in the Special Font will be in size \(+-N independent of previous &fz requests. .bt &ss|N 12\(sl36\|em ignored E Space-character size is set to N\(sl36\|ems. This size is the minimum word spacing in adjusted text. Ignored in \*(NR. .bt &cs|F\|N\|M off - P Constant character space (width) mode is set on for font F (if mounted); the width of every character will be taken to be N\(sl36 ems. If M is absent, the em is that of the character's point size; if M is given, the em is M-points. All affected characters are centered in this space, including those with an actual width larger than this space. Special Font characters occurring while the current font is F are also so treated. If N is absent, the mode is turned off. The mode must be still or again in effect when the characters are physically printed. Ignored in \*(NR. .bt &bd|F|N off - P The characters in font F will be artificially emboldened by printing each one twice, separated by N\^-1 basic units. A reasonable value for N is 3 when the character size is in the vicinity of 10 points. If N is missing the embolden mode is turned off. The column heads above were printed with .bd|I|3. The mode must be still or again in effect when the characters are physically printed. Ignored in \*(NR. .bt &bd|S|F|N off - P The characters in the Special Font will be emboldened whenever the current font is F. This manual was printed with .bd\|S\|B\|3. The mode must be still or again in effect when the characters are physically printed. .bt &ft|F Roman previous E Font changed to F. Alternatively, imbed \efF. The font name P is reserved to mean the previous font. .bt &fp|N|F R,I,B,S ignored - Font position. This is a statement that a font named F is mounted on position N (1-4). It is a fatal error if F is not known. The phototypesetter has four fonts physically mounted. Each font consists of a film strip which can be mounted on a numbered quadrant of a wheel. The default mounting sequence assumed by \*(TR is R, I, B, and S on positions 1, 2, 3 and 4. .mh Page control .pg Top and bottom margins are not automatically provided; it is conventional to define two macros and to set traps for them at vertical positions 0 (top) and -N (N from the bottom). See \(sc7 and Tutorial Examples \(scT2. A pseudo-page transition onto the first page occurs either when the first break occurs or when the first non-diverted text processing occurs. Arrangements for a trap to occur at the top of the first page must be completed before this transition. In the following, references to the current diversion (\(sc7.4) mean that the mechanism being described works during both ordinary and diverted output (the former considered as the top diversion level). .pg The usable page width on the Graphic Systems phototypesetter was about 7.54|inches, beginning about 1\(sl27|inch from the left edge of the 8|inch wide, continuous roll paper, but these characteristics are typesetter- dependent. The physical limitations on \*(NR output are output-device dependent. .h1 .bt &pl|\(+-N 11\|in 11\|in v Page length set to \(+-N. The internal limitation is about 75|inches in \*(TR and about 136|inches in \*(NR. The current page length is available in the .p register. .bt &bp|\(+-N N\(eq1 - B*,v Begin page. .fn .xx *The use of " \' " as control character (instead of ".") suppresses the break function. .ef The current page is ejected and a new page is begun. If \(+-N is given, the new page number will be \(+-N. Also see request ns. .bt &pn|\(+-N N\(eq1 ignored - Page number. The next page (when it occurs) will have the page number \(+-N. A pn must occur before the initial pseudo-page transition to affect the page number of the first page. The current page number is in the % register. .bt &po|\(+-N 0;|26\(sl27\|in\(dg previous v Page offset. .fn .xx \(dgValues separated by ";" are for \*(NR and \*(TR respectively. .ef The current left margin is set to \(+-N. The \*(TR initial value provides about 1|inch of paper margin including the physical typesetter margin of 1\(sl27|inch. In \*(TR the maximum (line-length)+(page-offset) is about 7.54 inches. See \(sc6. The current page offset is available in the .o register. .bt &ne|N - N\(eq1\|V D,v Need N vertical space. If the distance, D, to the next trap position (see \(sc7.5) is less than N, a forward vertical space of size D occurs, which will spring the trap. If there are no remaining traps on the page, D is the distance to the bottom of the page. If D\|<\|V, another line could still be output and spring the trap. In a diversion, D is the distance to the diversion trap, if any, or is very large. .bt &mk|R none internal D Mark the current vertical place in an internal register (both associated with the current diversion level), or in register R, if given. See rt request. .bt &rt|\(+-N none internal D,v Return upward only to a marked vertical place in the current diversion. If \(+-N (w.r.t. current place) is given, the place is \(+-N from the top of the page or diversion or, if N is absent, to a place marked by a previous mk. Note that the sp request (\(sc5.3) may be used in all cases instead of rt by spacing to the absolute place stored in an explicit register; e.|g. using the sequence .mk|R ... .sp|~\|\enRu. .mh Text Filling, Adjusting, and Centering .sc Filling and adjusting. Normally, words are collected from input text lines and assembled into an output text line until some word doesn't fit. An attempt is then made to hyphenate the word to assemble a part of it into the output line. The spaces between the words on the output line are then increased to spread out the line to the current line length minus any current indent. A word is any string of characters delimited by the space character or the beginning/end of the input line. Any adjacent pair of words that must be kept together (neither split across output lines nor spread apart in the adjustment process) can be tied together by separating them with the unpaddable space character "\e " (backslash-space). The adjusted word spacings are uniform in \*(TR and the minimum interword spacing can be controlled with the ss request (\(sc2). In \*(NR, they are normally nonuniform because of quantization to character-size spaces; however, the command line option -e causes uniform spacing with full output device resolution. Filling, adjustment, and hyphenation (\(sc13) can all be prevented or controlled. The text length on the last line output is available in the .n register, and text base-line position on the page for this line is in the nl register. The text base-line high-water mark (lowest place) on the current page is in the .h register. The .k register (read-only) contains the horizontal size of the text portion (without indent) of the current partially-collected output line (if any) in the current environment. .pg An input text line ending with .\^, ?, or ! is taken to be the end of a sentence, and an additional space character is automatically provided during filling. Multiple inter-word space characters found in the input are retained, except for trailing spaces; initial spaces also cause a break. .pg When filling is in effect, a \ep may be imbedded or attached to a word to cause a break at the end of the word and have the resulting output line spread out to fill the current line length. .pg .tr && A text input line that happens to begin with a control character (\(sc10.4) can be made to not look like a control line by preceding it by the non-printing, zero-width filler character \e&. Still another way is to specify output translation of some convenient character into the control character using tr (\(sc10.5). .tr &. .sc Interrupted text. The copying of an input line in nofill (non-fill) mode can be interrupted by terminating the partial line with a \ec. The next encountered input text line will be considered to be a continuation of the same line of input text. Similarly, a word within filled text may be interrupted by terminating the word (and line) with \ec; the next encountered text will be taken as a continuation of the interrupted word. If the intervening control lines cause a break, any partial line will be forced out along with any partial word. .h1 .bt &br - - B Break. The filling of the line currently being collected is stopped and the line is output without adjustment. Text lines beginning with space characters and empty text lines (blank lines) also cause a break. .bt .lg 0 &fi \(fill|on - B,E Fill subsequent output lines. .lg The register .u is 1 in fill mode and 0 in nofill mode. .bt &nf fill|on - B,E Nofill. Subsequent output lines are neither filled nor adjusted. Input text lines are copied directly to output lines without regard for the current line length. .bt &ad|c adj,both adjust E \ Line adjustment is begun. If fill mode is not on, adjustment will be deferred until fill mode is back on. If the type indicator c is present, the adjustment type is changed as shown in the following table. The type indicator can also be a value saved from the read-only .j number register, which is set to contain the current adjustment mode and type.
Indicator Adjust Type
l adjust left margin only
r adjust right margin only
c center
b or n adjust both margins
absent unchanged
.bt &na adjust - E Noadjust. Adjustment is turned off; the right margin will be ragged. The adjustment type for ad is not changed. Output line filling still occurs if fill mode is on. .bt &ce|N off N\(eq1 B,E Center the next N input text lines within the current (line-length minus indent). If N\(eq\^0, any residual count is cleared. A break occurs after each of the N input lines. If the input line is too long, it will be left adjusted. .mh Vertical Spacing .sc Base-line spacing. The vertical spacing (V) between the base-lines of successive output lines can be set using the vs request with a resolution of 1\(sl144\|inch\|\(eq\|1\(sl2|point in \*(TR, and to the output device resolution in \*(NR. V must be large enough to accommodate the character sizes on the affected output lines. For the common type sizes (9-12 points), usual typesetting practice is to set V to 2 points greater than the point size; \*(TR default is 10-point type on a 12-point spacing (as in this document). The current V is available in the .v register. Multiple-V\| line separation (e.\|g. double spacing) may be requested with ls. .sc Extra line-space. If a word contains a vertically tall construct requiring the output line containing it to have extra vertical space before and\(slor after it, the extra-line-space function \ex\'N\|\|\' can be imbedded in or attached to that word. In this and other functions having a pair of delimiters around their parameter (here \'\|), the delimiter choice is arbitrary, except that it can't look like the continuation of a number expression for N. If N is negative, the output line containing the word will be preceded by N extra vertical space; if N is positive, the output line containing the word will be followed by N extra vertical space. If successive requests for extra space apply to the same line, the maximum values are used. The most recently utilized post-line extra line-space is available in the .a register. .sc Blocks of vertical space. A block of vertical space is ordinarily requested using sp, which honors the no-space mode and which does not space past a trap. A contiguous block of vertical space may be reserved using sv. .h1 .bt &vs|N 1\(sl6in;12pts previous E,p Set vertical base-line spacing size V. Transient extra vertical space available with \ex\'N\|\|\' (see above). .bt &ls|N N\(eq\^1 previous E Line spacing set to \(+-N. N-1 V\^s (blank lines) are appended to each output text line. The (read-only) number register .L is set to contain the current line-spacing value. Appended blank lines are omitted, if the text or previous appended blank line reached a trap position. .bt &sp|N - N\(eq1V B,v Space vertically in either direction. If N is negative, the motion is backward (upward) and is limited to the distance to the top of the page. Forward (downward) motion is truncated to the distance to the nearest trap. If the no-space mode is on, no spacing occurs (see ns, and rs below). .bt &sv|N - N\(eq1V v Save a contiguous vertical block of size N. If the distance to the next trap is greater than N, N vertical space is output. No-space mode has no effect. If this distance is less than N, no vertical space is immediately output, but N is remembered for later output (see os). Subsequent sv requests will overwrite any still remembered N. .bt &os - - - Output saved vertical space. No-space mode has no effect. Used to finally output a block of vertical space requested by an earlier sv request. .bt &ns space - D No-space mode turned on. When on, the no-space mode inhibits sp requests and bp requests without a next page number. The no-space mode is turned off when a line of output occurs, or with rs. .bt &rs space - D Restore spacing. The no-space mode is turned off. .bt Blank|text|line. - B Causes a break and outputs a blank line just like sp|1.