From 0e1ed74908e4d764ba4c31b8cea01b3ee840aaac Mon Sep 17 00:00:00 2001 From: grog Date: Sun, 19 May 2002 03:30:02 +0000 Subject: Initial checkin: 4.4BSD version. These files need to be updated with current license information and adapted to the FreeBSD build environment before they will build. --- share/doc/usd/21.troff/m2 | 368 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 share/doc/usd/21.troff/m2 (limited to 'share/doc/usd/21.troff/m2') diff --git a/share/doc/usd/21.troff/m2 b/share/doc/usd/21.troff/m2 new file mode 100644 index 0000000..f572587 --- /dev/null +++ b/share/doc/usd/21.troff/m2 @@ -0,0 +1,368 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" +.\" @(#)m2 8.1 (Berkeley) 8/14/93 +.\" +.\" $FreeBSD$ +.tr | +.rm mx +.br +.mh +Line Length and Indenting +.pg +The maximum line length for fill mode may be set with \fBll\fR. +The indent may be set with \fBin\fR; +an indent applicable to \fIonly\fR the \fInext\fR output line may be set with \fBti\fR. +The line length includes indent space but \fInot\fR +page offset space. +The line-length minus the indent is the basis for centering with \fBce\fR. +The effect of \fBll\fR, \fBin\fR, or \fBti\fR +is delayed, if a partially collected line exists, +until after that line is output. +In fill mode the length of text on an output line is less than or equal to +the line length minus the indent. +The current line length and indent are available in registers \fB.l\fR and \fB.i\fR respectively. +The length of \fIthree-part titles\fR produced by \fBtl\fR +(see \(sc14) is \fIindependently\fR set by \fBlt\fR. +.h1 +.bt +\fB&ll\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Line length is set to \(+-\fIN\fR. +In \*(TR the maximum (line-length)+(page-offset) is about 7.54 inches. +.bt +\fB&in\fI|\(+-N\fR \fIN\(eq\^\fR0 previous B,E,\fBm\fR Indent is set to \fI\(+-N\fR. +The indent is prepended to each output line. +.bt +\fB&ti\fI|\(+-N\fR - ignored B,E,\fBm\fR Temporary indent. +The \fInext\fR output text line will be indented a distance \fI\(+-N\fR +with respect to the current indent. +The resulting total indent may not be negative. +The current indent is not changed. +.mh +Macros, Strings, Diversion, and Position Traps +.sc +Macros and strings. +A \fImacro\fR is a named set of arbitrary \fIlines\fR that may be invoked by name or +with a \fItrap\fR. +A \fIstring\fR is a named string of \fIcharacters\fR, +\fInot\fR including a newline character, +that may be interpolated by name at any point. +Request, macro, and string names share the \fIsame\fR name list. +Macro and string names +may be one or two characters long and may usurp previously defined +request, macro, or string names. +Any of these entities may be renamed with \fBrn\fR +or removed with \fBrm\fR. +Macros are created by \fBde\fR and \fBdi\fR, and appended to by \fBam\fR and \fBda\fR; +\fBdi\fR and \fBda\fR cause normal output to be stored in a macro. +Strings are created by \fBds\fR and appended to by \fBas\fR. +A macro is invoked in the same way as a request; +a control line beginning \fB.\fIxx\fR will interpolate the contents of macro \fIxx\fR. +The remainder of the line may contain up to nine \fIarguments\fR. +The strings \fIx\fR and \fIxx\fR are interpolated at any desired point with +\fB\e\(**\fIx\fR and \fB\e\(**(\fIxx\fR respectively. +String references and macro invocations may be nested. +.sc +Copy mode input interpretation. +During the definition and extension +of strings and macros (not by diversion) +the input is read in \fIcopy mode\fR. +The input is copied without interpretation +\fIexcept\fR that: +.x1 +.ds + \v'-.1m'\s-4\(bu\s+4\v'+.1m' +\(bu The contents of number registers indicated by \fB\en\fR are interpolated. +\(bu Strings indicated by \fB\e\(**\fR are interpolated. +\(bu Arguments indicated by \fB\e$\fR are interpolated. +\(bu Concealed newlines indicated by \fB\e\fR(newline) are eliminated. +\(bu Comments indicated by \fB\e"\fR are eliminated. +\(bu \fB\et\fR and \fB\ea\fR are interpreted as \s-1ASCII\s+1 horizontal tab and \s-1SOH\s+1 respectively (\(sc9). +\(bu \fB\e\e\fR is interpreted as \fB\e\fR. +\(bu \fB\e.\fR is interpreted as "\fB.\fR". +.x2 +These interpretations can be suppressed by +prepending +a \fB\e\fR. +For example, since \fB\e\e\fR maps into a \fB\e\fR, \fB\e\en\fR will copy as \fB\en\fR which +will be interpreted as a number register indicator when the +macro or string is reread. +.sc +Arguments. +When a macro is invoked by name, the remainder of the line is +taken to contain up to nine arguments. +The argument separator is the space character, and arguments +may be surrounded by double-quotes to permit imbedded space characters. +Pairs of double-quotes may be imbedded in double-quoted arguments to +represent a single double-quote. +If the desired arguments won't fit on a line, +a concealed newline may be used to continue on the next line. +.pg +When a macro is invoked the \fIinput level\fR is \fIpushed down\fR and +any arguments available at the previous level become unavailable +until the macro is completely read and the previous level is restored. +A macro's own arguments can be interpolated at \fIany\fR point +within the macro with \fB\e$\fIN\fR, which interpolates the \fIN\fR\^th +argument +(1\(<=\fIN\fR\^\(<=9). +If an invoked argument doesn't exist, +a null string results. +For example, the macro \fIxx\fR may be defined by +.x1 +.ft B +.ta .75i +&de xx \e"begin definition +Today is \e\e$1 the \e\e$2. +&. \e"end definition +.ft R +.x2 +and called by +.x1 +.ft B +&xx Monday 14th +.ft R +.x2 +to produce the text +.x1 +.ft B +Today is Monday the 14th. +.ft R +.x2 +Note that the \fB\e$\fR +was concealed in the definition with a prepended \fB\e\fR. +The number of currently available +arguments is in the \fB.$\fR register. +.pg +No arguments are available at the top (non-macro) level +in this implementation. +Because string referencing is implemented +as a input-level push down, +no arguments are available from \fIwithin\fR a string. +No arguments are available within a trap-invoked macro. +.pg +Arguments are copied in \fIcopy mode\fR onto a stack +where they are available for reference. +The mechanism does not allow an argument to contain +a direct reference to a \fIlong\fR string +(interpolated at copy time) and it is advisable to +conceal string references (with an extra \fB\e\fR\|) +to delay interpolation until argument reference time. +.sc +Diversions. +Processed output may be diverted into a macro for purposes +such as footnote processing (see Tutorial \(scT5) +or determining the horizontal and vertical size of some text for +conditional changing of pages or columns. +A single diversion trap may be set at a specified vertical position. +The number registers \fBdn\fR and \fBdl\fR respectively contain the +vertical and horizontal size of the most +recently ended diversion. +Processed text that is diverted into a macro +retains the vertical size of each of its lines when reread +in \fInofill\fR mode +regardless of the current \fIV\fR. +Constant-spaced (\fBcs\fR) or emboldened (\fBbd\fR) text that is diverted +can be reread correctly only if these modes are again or still in effect +at reread time. +One way to do this is to imbed in the diversion the appropriate +\fBcs\fR or \fBbd\fR requests with the \fItransparent\fR +mechanism described in \(sc10.6. +.pg +Diversions may be nested +and certain parameters and registers +are associated +with the current diversion level +(the top non-diversion level may be thought of as the +0th diversion level). +These are the diversion trap and associated macro, +no-space mode, +the internally-saved marked place (see \fBmk\fR and \fBrt\fR), +the current vertical place (\fB.d\fR register), +the current high-water text base-line (\fB.h\fR register), +and the current diversion name (\fB.z\fR register). +.sc +Traps. +Three types of trap mechanisms are available\(empage traps, a diversion trap, and +an input-line-count trap. +Macro-invocation traps may be planted using \fBwh\fR at any page position including the top. +This trap position may be changed using \fBch\fR. +Trap positions at or below the bottom of the page +have no effect unless or until +moved to within the page or rendered effective by an increase in page length. +Two traps may be planted at the \fIsame\fR position only by first planting them at different +positions and then moving one of the traps; +the first planted trap will conceal the second unless and until the first one is moved +(see Tutorial Examples \(scT5). +If the first one is moved back, it again conceals the second trap. +The macro associated with a page trap is automatically +invoked when a line of text is output whose vertical size \fIreaches\fR +or \fIsweeps past\fR the trap position. +Reaching the bottom of a page springs the top-of-page trap, if any, +provided there is a next page. +The distance to the next trap position is available in the \fB.t\fR register; +if there are no traps between the current position and the bottom of the page, +the distance returned is the distance to the page bottom. +.pg +A macro-invocation trap effective in the current diversion may be planted using \fBdt\fR. +The \fB.t\fR register works in a diversion; if there is no subsequent trap a \fIlarge\fR +distance is returned. +For a description of input-line-count traps, see the \fBit\fR request below. +.h1 +.bt +\fB&de\fI|xx|yy\fR - \fI.yy=\fB..\fR - Define or redefine the macro \fIxx\fR. +The contents of the macro begin on the next input line. +Input lines are copied in \fIcopy mode\fR until the definition is terminated by a +line beginning with \fB.\fIyy\fR, +whereupon the macro \fIyy\fR is called. +In the absence of \fIyy\fR, the definition +is terminated by a +line beginning with "\fB..\fR". +A macro may contain \fBde\fR requests +provided the terminating macros differ +or the contained definition terminator is concealed. +\&"\fB..\fR" can be concealed as +\fB\e\e..\fR which will copy as \fB\e..\fR and be reread as "\fB..\fR". +.bt +\fB&am\fI|xx|yy\fR - \fI.yy=\fB..\fR - Append to macro (append version of \fBde\fR). +.bt +\fB&ds\fI|xx|string\fR - ignored - Define a string +\fIxx\fR containing \fIstring\fR. +Any initial double-quote in \fIstring\fR is stripped off to permit +initial blanks. +.bt +\fB&as\fI|xx|string\fR - ignored - Append +\fIstring\fR to string \fIxx\fR +(append version of \fBds\fR). +.bt +\fB&rm\fI|xx\fR - ignored - Remove +request, macro, or string. +The name \fIxx\fR is removed from the name list and +any related storage space is freed. +Subsequent references will have no effect. +.bt +\fB&rn\fI|xx|yy\fR - ignored - Rename request, macro, or string +\fIxx\fR to \fIyy\fR. +If \fIyy\fR exists, it is first removed. +.bt +\fB&di|\fIxx\fR - end D Divert output to macro \fIxx\fR. +Normal text processing occurs during diversion +except that page offsetting is not done. +The diversion ends when the request \fBdi\fR or \fBda\fR is encountered without an argument; +extraneous +requests of this type should not appear when nested diversions are being used. +.bt +\fB&da|\fIxx\fR - end D Divert, appending to \fIxx\fR +(append version of \fBdi\fR). +.bt +\fB&wh\fI|N|xx\fR - - \fBv\fR Install +a trap to invoke \fIxx\fR at page position \fIN;\fR +a \fInegative N\fR will be interpreted with respect to the +page \fIbottom\fR. +Any macro previously planted at \fIN\fR is replaced by \fIxx\fR. +A zero \fIN\fR refers to the \fItop\fR of a page. +In the absence of \fIxx\fR, the first found trap at \fIN\fR, if any, is removed. +.bt +\fB&ch\fI|xx|N\fR - - \fBv\fR Change +the trap position for macro \fIxx\fR to be \fIN\fR. +In the absence of \fIN\fR, the trap, if any, is removed. +.bt +\fB&dt\fI|N|xx\fR - off D,\fBv\fR Install a diversion trap +at position \fIN\fR in the \fIcurrent\fR diversion to invoke +macro \fIxx\fR. +Another \fBdt\fR will redefine the diversion trap. +If no arguments are given, the diversion trap is removed. +.bt +\fB&it\fI|N|xx\fR - off E Set an input-line-count trap +to invoke the macro \fIxx\fR after \fIN\fR lines of \fItext\fR input +have been read +(control or request lines don't count). +The text may be in-line text or +text interpolated by inline or trap-invoked macros. +.bt +\fB&em\fI|xx\fR none none - The +macro \fIxx\fR will be invoked +when all input has ended. +The effect is the same as if the contents of \fIxx\fR had been at the end +of the last file processed. +.mh +Number Registers +.pg +A variety of parameters are available to the user as +predefined, named \fInumber registers\fR (see Summary and Index, page 7). +In addition, the user may define his own named registers. +Register names are one or two characters long and \fIdo not\fR conflict +with request, macro, or string names. +Except for certain predefined read-only registers, +a number register can be read, written, automatically +incremented or decremented, and interpolated +into the input in a variety of formats. +One common use of user-defined registers is to +automatically number sections, paragraphs, lines, etc. +A number register may be used any time numerical input is expected or desired +and may be used in numerical \fIexpressions\fR (\(sc1.4). +.pg +Number registers are created and modified using \fBnr\fR, which +specifies the name, numerical value, and the auto-increment size. +Registers are also modified, if accessed +with an auto-incrementing sequence. +If the registers \fIx\fR and \fIxx\fR both contain +\fIN\fR and have the auto-increment size \fIM\fR, +the following access sequences have the effect shown: +.TS +center box; +c2|c2|c +c2|c2|c +l2|c2|c +l2|c2|c +l2|l2|c. + Effect on Value +Sequence Register Interpolated +_ +\fB\en\fIx\fR none \fIN\fR +\fB\en(\fIxx\fR none \fIN\fR +\fB\en+\fIx\fR \fIx\fR incremented by \fIM\fR \fIN+M\fR +\fB\en\-\fIx\fR \fIx\fR decremented by \fIM\fR \fIN\-M\fR +\fB\en+(\fIxx\fR \fIxx\fR incremented by \fIM\fR \fIN+M\fR +\fB\en\-(\fIxx\fR \fIxx\fR decremented by \fIM\fR \fIN\-M\fR +.TE +When interpolated, a number register is converted to +decimal (default), +decimal with leading zeros, +lower-case Roman, +upper-case Roman, +lower-case sequential alphabetic, +or +upper-case sequential alphabetic +according to the format specified by \fBaf\fR. +.h1 +.bt +\fB&nr\fI|R|\(+-N|M\fR - - \fBu\fR \ +The number register \fIR\fR is assigned the value \fI\(+-N\fR +with respect to the previous value, if any. +The increment for auto-incrementing is set to \fIM\fR. +.bt +\fB&af\fI|R|c\fR arabic - - Assign format \fIc\fR to register \fIR\fR. +The available formats are: +.TS +center box; +c2|c +c2|c +c2|l. + Numbering +Format Sequence +_ +\fB1\fR 0,1,2,3,4,5,... +\fB001\fR 000,001,002,003,004,005,... +\fBi\fR 0,i,ii,iii,iv,v,... +\fBI\fR 0,I,II,III,IV,V,... +\fBa\fR 0,a,b,c,...,z,aa,ab,...,zz,aaa,... +\fBA\fR 0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,... +.TE +An arabic format having \fIN\fR digits +specifies a field width of \fIN\fR digits (example 2 above). +The read-only registers and the \fIwidth\fR function (\(sc11.2) +are always arabic. +.bt +\fB&rr\fI|R\fR - ignored - Remove register \fIR\fR. +If many registers are being created dynamically, it +may become necessary to remove no longer used registers +to recapture internal storage space for newer registers. -- cgit v1.1