/share/doc/usd/21.troff/m3

  1.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
  2.\" 
  3.\" Redistribution and use in source and binary forms, with or without
  4.\" modification, are permitted provided that the following conditions are
  5.\" met:
  6.\" 
  7.\" Redistributions of source code and documentation must retain the above
  8.\" copyright notice, this list of conditions and the following
  9.\" disclaimer.
 10.\" 
 11.\" Redistributions in binary form must reproduce the above copyright
 12.\" notice, this list of conditions and the following disclaimer in the
 13.\" documentation and/or other materials provided with the distribution.
 14.\" 
 15.\" All advertising materials mentioning features or use of this software
 16.\" must display the following acknowledgement:
 17.\" 
 18.\" This product includes software developed or owned by Caldera
 19.\" International, Inc.  Neither the name of Caldera International, Inc.
 20.\" nor the names of other contributors may be used to endorse or promote
 21.\" products derived from this software without specific prior written
 22.\" permission.
 23.\" 
 24.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
 25.\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
 26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 27.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 28.\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
 29.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 32.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 33.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 34.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 35.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 36.\" 
 37.\"	@(#)m3	8.1 (Berkeley) 8/14/93
 38.\"
 39.\" $FreeBSD$
 40.tr |
 41.rm mx
 42.mh
 43Tabs, Leaders, and Fields
 44.sc
 45Tabs and leaders.
 46The \s-1ASCII\s+1 horizontal tab character and the \s-1ASCII\s+1
 47\s-1SOH\s+1 (hereafter known as the \fIleader\fR character)
 48can both be used to generate either horizontal motion or
 49a string of repeated characters.
 50The length of the generated entity is governed
 51by internal \fItab stops\fR specifiable
 52with \fBta\fR.
 53The default difference is that tabs generate motion and leaders generate
 54a string of periods;
 55\fBtc\fR and \fBlc\fR
 56offer the choice of repeated character or motion.
 57There are three types of internal tab stops\(em\
 58\fIleft\fR adjusting, \fIright\fR adjusting,
 59and \fIcentering\fR.
 60In the following table:
 61\fID\fR is the distance from the current position on the \fIinput\fR line
 62(where a tab or leader was found)
 63to the next tab stop;
 64\fInext-string\fR consists
 65of the input characters following the tab (or leader) up to the next tab (or leader) or end of line;
 66and
 67\fIW\fR is the width of \fInext-string\fR.
 68.TS
 69center box;
 70c2|c2|c
 71c2|c2|c
 72c2|c2|l.
 73Tab	Length of motion or	Location of
 74type	repeated characters	\fInext-string\fR
 75_
 76Left	\fID\fR	Following \fID\fR
 77Right	\fID\-W\fR	Right adjusted within \fID\fR
 78Centered	\fID\-W\(sl\fR2	Centered on right end of \fID\fR
 79.TE
 80The length of generated motion is allowed to be negative, but
 81that of a repeated character string cannot be.
 82Repeated character strings contain an integer number of characters, and
 83any residual distance is prepended as motion.
 84Tabs or leaders found after the last tab stop are ignored, but may be used
 85as \fInext-string\fR terminators.
 86.pg
 87Tabs and leaders are not interpreted in \fIcopy mode\fR.
 88\fB\et\fR and \fB\ea\fR always generate a non-interpreted
 89tab and leader respectively, and
 90are equivalent to actual tabs and leaders in \fIcopy mode\fR.
 91.sc
 92Fields.
 93A \fIfield\fR is contained between
 94a \fIpair\fR of \fIfield delimiter\fR characters,
 95and consists of sub-strings
 96separated by \fIpadding\fR indicator characters.
 97The field length is the distance on the
 98\fIinput\fR line from the position where the field begins to the next tab stop.
 99The difference between the total length of all the sub-strings
100and the field length is incorporated as horizontal
101padding space that is divided among the indicated
102padding places.
103The incorporated padding is allowed to be negative.
104For example,
105if the field delimiter is \fB#\fR and the padding indicator is \fB^\fR,
106\fB#^\fIxxx\fB^\fIright\|\fB#\fR
107specifies a right-adjusted string with the string \fIxxx\fR centered
108in the remaining space.
109.h1
110.bt
111\fB&ta\fI|Nt|...\fR	8n;|0.5in	none	E,\fBm\fR	\
112Set tab stops and types.
113\fIt=\fBR\fR, right adjusting;
114\fIt=\fBC\fR, centering;
115\fIt\fR absent, left adjusting.
116\*(TR tab stops are preset every 0.5in.;
117\*(NR every 8 character widths.
118The stop values are separated by spaces, and
119a value preceded by \fB+\fR
120is treated as an increment to the previous stop value.
121.bt
122\fB&tc\fI|c\fR	none	none	E	\
123The tab repetition character becomes \fIc\fR,
124or is removed specifying motion.
125.bt
126\fB&lc\fI|c\fR	\fB.\fR	none	E	\
127The leader repetition character becomes \fIc\fR,
128or is removed specifying motion.
129.bt
130\fB&fc\fI|a|b\fR	off	off	-	\
131The field delimiter is set to \fIa\fR;
132the padding indicator is set to the \fIspace\fR character or to
133\fIb\fR, if given.
134In the absence of arguments the field mechanism is turned off.
135.mh
136Input and Output Conventions and Character Translations
137.sc
138Input character translations.
139Ways of inputting the graphic character set were
140discussed in \(sc2.1.
141The \s-1ASCII\s+1 control characters horizontal tab (\(sc9.1),
142\s-1SOH\s+1 (\(sc9.1), and backspace (\(sc10.3) are discussed elsewhere.
143The newline delimits input lines.
144In addition,
145\s-1STX\s+1, \s-1ETX\s+1, \s-1ENQ\s+1, \s-1ACK\s+1, and \s-1BEL\s+1
146are accepted,
147and may be used as delimiters or translated into a graphic with \fBtr\fR (\(sc10.5).
148\fIAll\fR others are ignored.
149.pg
150The \fIescape\fR character \fB\e\fR
151introduces \fIescape sequences\fR\(em\
152causes the following character to mean
153another character, or to indicate
154some function.
155A complete list of such sequences is given in the Summary and Index on page 6.
156\fB\e\fR
157should not be confused with the \s-1ASCII\s+1 control character \s-1ESC\s+1 of the
158same name.
159The escape character \fB\e\fR can be input with the sequence \fB\e\e\fR.
160The escape character can be changed with \fBec\fR,
161and all that has been said about the default \fB\e\fR becomes true
162for the new escape character.
163\fB\ee\fR can be used to print whatever the current escape character is.
164If necessary or convenient, the escape mechanism may be turned off with \fBeo\fR,
165and restored with \fBec\fR.
166.h1
167.bt
168\fB&ec\fI|c\fR	\fB\e\fR	\fB\e\fR	-	\
169Set escape character to \fB\e\fR, or to \fIc\fR, if given.
170.bt
171\fB&eo\fR	on	-	-	Turn escape mechanism off.
172.sc
173Ligatures.
174.lg 0
175Five ligatures are available
176in the current \*(TR character set \(em
177\fB\(fi\fR, \fB\(fl\fR, \fB\(ff\fR, \fB\(Fi\fR, and \fB\(Fl\fR.
178They may be input (even in \*(NR) by
179\fB\e(fi\fR, \fB\e(fl\fR, \fB\e(ff\fR, \fB\e(Fi\fR, and \fB\e(Fl\fR respectively.
180.lg
181The ligature mode is normally on in \*(TR, and \fIautomatically\fR invokes 
182ligatures during input.
183.h1
184.bt
185\fB&lg\fI|N\fR	off;|on	on	-	Ligature mode
186is turned on if \fIN\fR is absent or non-zero,
187and turned off if \fIN\(eq\^\fR0.
188If \fIN\fR\(eq\^2, only the two-character ligatures are automatically invoked.
189Ligature mode is inhibited for
190request, macro, string, register, or file names,
191and in \fIcopy mode\fR.
192No effect in \*(NR.
193.sc
194Backspacing, underlining, overstriking, etc.
195Unless in \fIcopy mode\fR, the \s-1ASCII\s+1 backspace character is replaced
196by a backward horizontal motion having the width of the
197space character.
198Underlining as a form of line-drawing is discussed in \(sc12.4.
199A generalized overstriking function is described in \(sc12.1.
200.pg
201\*(NR automatically underlines
202characters in the \fIunderline\fR font,
203specifiable with \fBuf\fR,
204normally Times Italic on font position 2 (see \(sc2.2).
205In addition to \fBft\fR and \fB\ef\fIF\fR,
206the underline font may be selected by \fBul\fR and \fBcu\fR.
207Underlining is restricted to an output-device-dependent
208subset of \fIreasonable\fR characters.
209.h1
210.bt
211\fB&ul\fI|N\fR	off	\fIN\(eq\fR1	E	\
212Underline in \*(NR (italicize in \*(TR) the next \fIN\fR
213input text lines.
214Actually, switch to \fIunderline\fR font, saving the
215current font for later restoration;
216\fIother\fR font changes within the span of a \fBul\fR
217will take effect,
218but the restoration will undo the last change.
219Output generated by \fBtl\fR (\(sc14) \fIis\fR affected by the
220font change, but does \fInot\fR decrement \fIN\fR.
221If \fIN\fR\^>\^1, there is the risk that
222a trap interpolated macro may provide text
223lines within the span;
224environment switching can prevent this.
225.bt
226\fB&cu\fI|N\fR	off	\fIN\(eq\fR1	E	\
227A variant of \fBul\fR that causes \fIevery\fR character to be underlined in \*(NR.
228Identical to \fBul\fR in \*(TR.
229.bt
230\fB&uf\fI|F\fR	Italic	Italic	-	\
231Underline font set to \fIF\fR.
232In \*(NR,
233\fIF\fR may \fInot\fR be on position 1 (initially Times Roman).
234.sc
235Control characters.
236Both the control character \fB.\fR and the \fIno-break\fR
237control character \fB\'\fR may be changed, if desired.
238Such a change must be compatible with the design
239of any macros used in the span of the change,
240and
241particularly of any trap-invoked macros.
242.h1
243.bt
244\fB&cc\fI|c\fR	\fB.\fR	\fB.\fR	E	\
245The basic control character is set to \fIc\fR,
246or reset to "\fB.\fR".
247.bt
248\fB&c2\fI|c\fR	\fB\'	\'\fR	E	The \fInobreak\fR control character is set
249to \fIc\fR, or reset to "\fB\'\fR".
250.sc
251Output translation.
252One character can be made a stand-in for another character using \fBtr\fR.
253All text processing (e. g. character comparisons) takes place
254with the input (stand-in) character which appears to have the width of the final
255character.
256The graphic translation occurs at the moment of output
257(including diversion).
258.h1
259.bt
260\fB&tr\fI|abcd....\fR	none	-	O	Translate \
261\fIa\fR into \fIb\fR, \fIc\fR into \fId\fR, etc.
262If an odd number of characters is given,
263the last one will be mapped into the space character.
264To be consistent, a particular translation
265must stay in effect from \fIinput\fR to \fIoutput\fR time.
266.sc
267Transparent throughput.
268An input line beginning with a \fB\e!\fR is read in \fIcopy mode\fR and \fItransparently\fR output
269(without the initial \fB\e!\fR);
270the text processor is otherwise unaware of the line's presence.
271This mechanism may be used to pass control information to a post-processor
272or to imbed control lines in a macro created by a diversion.
273.sc
274Comments and concealed newlines.
275An uncomfortably long input line that must stay
276one line (e. g. a string definition, or nofilled text)
277can be split into many physical lines by ending all but
278the last one with the escape \fB\e\fR.
279The sequence \fB\e\fR(newline) is \fIalways\fR ignored\(em\
280except in a comment.
281Comments may be imbedded at the \fIend\fR of any line by
282prefacing them with \fB\e"\fR.
283The newline at the end of a comment cannot be concealed.
284A line beginning with \fB\e"\fR will appear as a blank line and
285behave like \fB.sp|1\fR;
286a comment can be on a line by itself by beginning the line with \fB.\e"\fR.
287.mh
288Local Horizontal and Vertical Motions, and the Width Function
289.sc
290Local Motions.
291The functions \fB\ev\'\fIN\fB\|\'\fR and
292\fB\eh\'\fIN\fB\|\'\fR
293can be used for \fIlocal\fR vertical and horizontal motion respectively.
294The distance \fIN\fR may be negative; the \fIpositive\fR directions
295are \fIrightward\fR and \fIdownward\fR.
296A \fIlocal\fR motion is one contained \fIwithin\fR a line.
297To avoid unexpected vertical dislocations, it is necessary that
298the \fInet\fR vertical local motion within a word in filled text
299and otherwise within a line balance to zero.
300The above and certain other escape sequences providing local motion are
301summarized in the following table.
302.tr ||
303.ds X \0\0\0
304.TS
305center box;
306c2|cs2||c2|cs
307c1|c2c2||c2|c2c.
308Vertical	Effect in	Horizontal	Effect in
309Local Motion	\*(TR	\*(NR	Local Motion	\*(TR	\*(NR
310_
311.sp .4
312.T&
313l2|ls2||l2|ls.
314\fB\*X\ev\'\fIN\|\^\fB\'\fR	Move distance \fIN\fR	\
315\fB\*X\eh\'\fIN\|\^\fB\'\fR	Move distance \fIN\fR
316.T&
317_2|_2_2||l2|ls.
318			\fB\*X\e\fR(space)	Unpaddable space-size space
319.T&
320l2|l2|l2||l2|ls.
321\fB\*X\eu\fR	\(12 em up	\(12 line up	\fB\*X\e0\fR	Digit-size space
322.T&
323l2|l2|l2||_2|_2_.
324\fB\*X\ed\fR	\(12 em down	\(12 line down			
325.T&
326l2|l2|l2||l2|l2|l.
327\fB\*X\er\fR	1 em up	1 line up	\fB\*X\e\||\fR	1\(sl6 em space	ignored
328			\fB\*X\e^\fR	1\(sl12 em space	ignored
329.sp .4
330.TE
331.rm X
332.tr |
333As an example,
334\fBE\s-2\v'-.4m'2\v'.4m'\s+2\fR
335could be generated by the sequence
336\fBE\es\-2\ev\'\-0.4m\'2\ev\'0.4m\'\es+2\fR;
337it should be noted in this example that
338the 0.4|em vertical motions are at the smaller size.
339.sc
340Width Function.
341The \fIwidth\fR function \fB\ew\'\fIstring\fB\|\'\fR
342generates the numerical width of \fIstring\fR (in basic units).
343Size and font changes may be safely imbedded in \fIstring\fR,
344and will not affect the current environment.
345For example,
346\&\fB.ti|\-\\w\'1.|\'u\fR could be used to
347temporarily indent leftward a distance equal to the
348size of the string "\fB1.|\fR".
349.pg
350The width function also sets three number registers.
351The registers \fBst\fR and \fBsb\fR are set respectively to the highest and
352lowest extent of \fIstring\fR relative to the baseline;
353then, for example,
354the total \fIheight\fR of the string is \fB\en(stu\-\en(sbu\fR.
355In \*(TR the number register \fBct\fR is set to a value
356between 0|and|3:
3570 means that all of the characters in \fIstring\fR were short lower
358case characters without descenders (like \fBe\fR);
3591 means that at least one character has a descender (like \fBy\fR);
3602 means that at least one character is tall (like \fBH\fR);
361and 3 means that both tall characters and characters with
362descenders are present.
363.sc
364Mark horizontal place.
365The escape sequence \fB\ek\fIx\fR will cause the \fIcurrent\fR horizontal
366position in the \fIinput line\fR to be stored in register \fIx\fR.
367As an example,
368the construction \fB\ekx\fIword\|\fB\eh\'\|~\|\enxu+2u\'\fIword\fB\fR
369will embolden \fIword\fR by backing up to almost its beginning and overprinting it,
370resulting in \kz\fIword\fR\h'|\nzu+2u'\fIword\fR.
371.mh
372Overstrike, Bracket, Line-drawing, and Zero-width Functions
373.sc
374Overstriking.
375Automatically centered overstriking of up to nine characters
376is provided by the \fIoverstrike\fR function
377\fB\eo\'\fIstring\fB\|\'\fR.
378The characters in \fIstring\fR are overprinted with centers aligned; the total width
379is that of the widest character.
380\fIstring\fR should \fInot\fR contain local vertical motion.
381As examples,
382\fB\eo\'e\e\'\'\fR produces \fB\o'e\''\fR, and
383\fB\eo\'\e(mo\e(sl\'\fR produces \fB\o'\(mo\(sl'\fR.
384.sc
385Zero-width characters.
386The function \fB\ez\fIc\fR will output \fIc\fR without spacing over
387it, and can be used to produce left-aligned overstruck
388combinations.
389As examples,
390\fB\ez\e(ci\e(pl\fR will produce \fB\z\(ci\(pl\fR, and
391\fB\e(br\ez\e(rn\e(ul\e(br\fR will produce the smallest possible
392constructed box \fB\(br\z\(rn\(ul\(br\fR\|.
393.sc
394Large Brackets.
395The Special Mathematical Font contains a number of bracket construction pieces
396(\|\|\|\(lt\|\|\|\(lb\|\|\|\(rt\|\|\|\(rb\|\|\|\(lk\|\|\|\(rk\|\|\|\(bv\|\|\|\(lf\|\|\|\(rf\|\|\|\(lc\|\|\|\(rc\|\|)
397that can be combined into various bracket styles.
398The function \fB\eb\'\fIstring\fB\|\'\fR may be used to pile
399up vertically the characters in \fIstring\fR
400(the first character on top and the last at the bottom);
401the characters are vertically separated by 1|em and the total
402pile is centered 1\(sl2\|em above the current baseline
403(\(12 line in \*(NR).
404For example,
405\fB\eb\'\|\e(lc\e(lf\|\'E\e\|~\|\eb\'\|\e(rc\e(rf\|\'\|\ex\'\|\-0.5m\'\|\ex\'0.5m\'\|\fR
406produces
407\x'-.5m'\x'.5m'\fB\b'\(lc\(lf'E\|\b'\(rc\(rf'\fR.
408.sc
409Line drawing.
410.tr &&
411The function \fB\e\|l\|\'\fINc\fB\|\'\fR will draw a string of repeated \fIc\fR\|'s towards the right for a distance \fIN\fR.
412(\|\fB\el\fR is \fB\e\fR(lower case L).
413If \fIc\fR looks like a continuation of
414an expression for \fIN\fR, it may insulated from \fIN\fR with a \fB\e&\fR.
415If \fIc\fR is not specified, the \fB\(ru\fR (baseline rule) is used
416(underline character in \*(NR).
417If \fIN\fR is negative, a backward horizontal motion
418of size \fIN\fR is made \fIbefore\fR drawing the string.
419Any space resulting from \fIN\fR\|\(sl(size of \fIc\fR) having a remainder is put at the beginning (left end)
420of the string.
421In the case of characters
422that are designed to be connected such as
423baseline-rule\ \fB\(ru\fR\|,
424underrule\ \fB\(ul\fR\|,
425and
426root-en\ \fB\(rn\fR\|,
427the remainder space is covered by over-lapping.
428If \fIN\fR is \fIless\fR than the width of \fIc\fR,
429a single \fIc\fR is centered on a distance \fIN\fR.
430As an example, a macro to underscore a string can be written
431.br
432.tr &.
433.x1
434.ft B
435.ne 2.1
436&de us
437\e\e$1\e\|l\|\'\|~\|0\e(ul\'
438&&
439.ft R
440.x2
441.ne 2.1
442.de xu
443\\$1\l'|0\(ul'
444..
445or one to draw a box around a string
446.x1
447.ft B
448&de bx
449\e(br\e\|~\|\e\e$1\e\|~\|\e(br\e\|l\|\'\|~\|0\e(rn\'\e\|l\|\'\|~\|0\e(ul\'
450&&
451.ft R
452.x2
453.de bx
454\(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul'
455..
456such that
457.x1
458.ft B
459&us "underlined words"
460.ft R
461.x2
462and
463.x1
464.ft B
465&bx "words in a box"
466.ft R
467.x2
468yield
469.xu "underlined words"
470and
471.bx "words in a box"
472\h'-\w'.'u'.
473.pg
474The function \fB\eL\'\|\fINc\fB\|\'\fR will draw a vertical line consisting
475of the (optional) character \fIc\fR stacked vertically apart 1\|em
476(1 line in \*(NR),
477with the first two characters overlapped,
478if necessary, to form a continuous line.
479The default character is the \fIbox rule\fR |\(br| (\fB\|\e(br\fR);
480the other suitable character is the \fIbold vertical\fR \|\(bv\| (\fB\|\e(bv\fR).
481The line is begun without any initial motion relative to the
482current base line.
483A positive \fIN\fR specifies a line drawn downward and
484a negative \fIN\fR specifies a line drawn upward.
485After the line is drawn \fIno\fR compensating
486motions are made;
487the instantaneous baseline is at the \fIend\fR of the line.
488.pg
489.de eb
490.sp -1
491.nf
492\h'-.5n'\L'|\\nzu-1'\l'\\n(.lu+1n\(ul'\L'-|\\nzu+1'\l'|0u-.5n\(ul'
493.fi
494..
495.ne 2i
496.mk z
497The horizontal and vertical line drawing functions may be used
498in combination to produce large boxes.
499The zero-width \fIbox-rule\fR and the \(12-em wide \fIunderrule\fR
500were \fIdesigned\fR to form corners when using 1-em vertical
501spacings.
502For example the macro
503.x1
504.ft B
505\&.de eb
506\&.sp \-1	\e"compensate for next automatic base-line spacing
507\&.nf	\e"avoid possibly overflowing word buffer
508.tr ||
509\&\eh\'\-.5n\'\eL\'\||\|\e\enau\-1\'\el\'\e\en(.lu+1n\e(ul\'\eL\'\-\||\|\e\enau+1\'\el\'\||\|0u\-.5n\e(ul\'    \e"draw box
510.tr |
511.lg 0
512\&.fi
513.lg
514\&..
515.ft R
516.x2
517will draw a box around some text whose beginning vertical place was
518saved in number register \fIa\fR
519(e. g. using \fB.mk|a\fR)
520as done for this paragraph.
521.eb