Return to m5 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 24.troff

Annotation of 43BSDReno/share/doc/usd/24.troff/m5, revision 1.1

1.1     ! root        1: .\"    @(#)m5  6.1 (Berkeley) 4/17/86
        !             2: .\"
        !             3: .pn 28
        !             4: .ds H T
        !             5: .tr |
        !             6: .tr ~|
        !             7: .de x1
        !             8: .xx
        !             9: .ftB
        !            10: .in .2i
        !            11: .nf
        !            12: .ne 2.1
        !            13: .ta 1i
        !            14: ..
        !            15: .de x2
        !            16: .fi
        !            17: .in0
        !            18: .ftR
        !            19: .xx
        !            20: ..
        !            21: .br
        !            22: .ce
        !            23: .ftB
        !            24: .rs
        !            25: .sp 0.5i
        !            26: TUTORIAL EXAMPLES
        !            27: .ftR
        !            28: .sp2
        !            29: .nr p 0
        !            30: .2C
        !            31: .ns
        !            32: .mh
        !            33: .mk
        !            34: Introduction
        !            35: .pg
        !            36: Although \*(NR and \*(TR
        !            37: have by design a syntax reminiscent
        !            38: of earlier text processors*
        !            39: .fn
        !            40: .xx
        !            41: *For example:
        !            42: P.|A.|Crisman, Ed.,
        !            43: .ul
        !            44: The Compatible Time-Sharing System,
        !            45: MIT Press, 1965, Section|AH9.01
        !            46: (Description of RUNOFF program on MIT's CTSS system).
        !            47: .ef
        !            48: with the intent of easing their use,
        !            49: it is almost always necessary to
        !            50: prepare at least a small set of macro definitions
        !            51: to describe most documents.
        !            52: Such common formatting needs
        !            53: as page margins and footnotes
        !            54: are deliberately not built into \*(NR and \*(TR.
        !            55: Instead,
        !            56: the macro and string definition, number register, diversion,
        !            57: environment switching, page-position trap, and conditional input mechanisms
        !            58: provide the basis for user-defined implementations.
        !            59: .pg
        !            60: The examples to be discussed are intended to be useful and somewhat realistic,
        !            61: but won't necessarily cover all relevant contingencies.
        !            62: Explicit numerical parameters are used
        !            63: in the examples
        !            64: to make them easier to read and to
        !            65: illustrate typical values.
        !            66: In many cases, number registers would really be used
        !            67: to reduce the number of places where numerical
        !            68: information is kept,
        !            69: and to concentrate conditional parameter initialization
        !            70: like that which depends on whether \*(TR or \*(NR is being used.
        !            71: .mh
        !            72: Page Margins
        !            73: .pg
        !            74: As discussed in \(sc3,
        !            75: \fIheader\fR and \fIfooter\fR macros are usually defined
        !            76: to describe the top and bottom page margin areas respectively.
        !            77: A trap is planted at page position 0 for the header, and at
        !            78: \fI\-N\fR (\fIN\fR from the page bottom) for the footer.
        !            79: The simplest such definitions might be
        !            80: .x1
        !            81: &de hd \e"define header
        !            82: \'sp 1i
        !            83: &&     \e"end definition
        !            84: &de fo \e"define footer
        !            85: \'bp
        !            86: &&     \e"end definition
        !            87: &wh 0 hd
        !            88: &wh \-1i fo
        !            89: .x2
        !            90: which provide blank 1|inch top and bottom margins.
        !            91: The header will occur on the \fIfirst\fR page,
        !            92: only if the definition and trap exist prior to
        !            93: the initial pseudo-page transition (\(sc3).
        !            94: In fill mode, the output line that springs the footer trap
        !            95: was typically forced out because some part or whole word didn't fit on it.
        !            96: If anything in the footer and header that follows causes a \fIbreak\fR,
        !            97: that word or part word will be forced out.
        !            98: In this and other examples,
        !            99: requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
        !           100: the \fIno-break\fR control character \fB\'\fR
        !           101: to avoid this.
        !           102: When the header\(slfooter design contains material
        !           103: requiring independent text processing, the
        !           104: environment may be switched, avoiding
        !           105: most interaction with the running text.
        !           106: .pg
        !           107: A more realistic example would be
        !           108: .x1
        !           109: &de hd \e"header
        !           110: &if t .tl \'\|\e(rn\'\'\e(rn\'  \e"troff cut mark
        !           111: &if \e\en%>1 \e{\e
        !           112: \'sp ~\|0.5i\-1        \e"tl base at 0.5i
        !           113: &tl \'\'\- % \-\'\'    \e"centered page number
        !           114: &ps    \e"restore size
        !           115: &ft    \e"restore font
        !           116: &vs  \e}       \e"restore vs
        !           117: \'sp ~\|1.0i   \e"space to 1.0i
        !           118: &ns    \e"turn on no-space mode
        !           119: &&
        !           120: &de fo \e"footer
        !           121: &ps 10 \e"set footer\(slheader size
        !           122: &ft R  \e"set font
        !           123: &vs 12p        \e"set base-line spacing
        !           124: &if \e\en%=1 \e{\e
        !           125: \'sp ~\|\e\en(.pu\-0.5i\-1  \e"tl base 0.5i up
        !           126: &tl \'\'\- % \-\'\' \e}  \e"first page number
        !           127: \'bp
        !           128: &&
        !           129: &wh 0 hd
        !           130: &wh \-1i fo
        !           131: .x2
        !           132: which sets the size, font, and base-line spacing for the
        !           133: header\(slfooter material, and ultimately restores them.
        !           134: The material in this case is a page number at the bottom of the
        !           135: first page and at the top of the remaining pages.
        !           136: If \*(TR is used, a \fIcut mark\fR is drawn in the form
        !           137: of \fIroot-en\fR's at each margin.
        !           138: The \fBsp\fR's refer to absolute positions to avoid
        !           139: dependence on the base-line spacing.
        !           140: Another reason for this in the footer
        !           141: is that the footer is invoked by printing a line whose
        !           142: vertical spacing swept past the trap position by possibly
        !           143: as much as the base-line spacing.
        !           144: The \fIno-space\fR mode is turned on at the end of \fBhd\fR
        !           145: to render ineffective
        !           146: accidental occurrences of \fBsp\fR at the top of the running text.
        !           147: .pg
        !           148: The above method of restoring size, font, etc. presupposes
        !           149: that such requests (that set \fIprevious\fR value) are \fInot\fR
        !           150: used in the running text.
        !           151: A better scheme is save and restore both the current \fIand\fR
        !           152: previous values as shown for size in the following:
        !           153: .x1
        !           154: &de fo
        !           155: &nr s1 \e\en(.s        \e"current size
        !           156: &ps
        !           157: &nr s2 \e\en(.s        \e"previous size
        !           158: &  --- \e"rest of footer
        !           159: &&
        !           160: &de hd
        !           161: &  --- \e"header stuff
        !           162: &ps \e\en(s2   \e"restore previous size
        !           163: &ps \e\en(s1   \e"restore current size
        !           164: &&
        !           165: .x2
        !           166: Page numbers may be printed in the bottom margin
        !           167: by a separate macro triggered during the footer's
        !           168: page ejection:
        !           169: .x1
        !           170: &de bn \e"bottom number
        !           171: &tl \'\'\- % \-\'\'    \e"centered page number
        !           172: &&
        !           173: &wh \-0.5i\-1v bn       \e"tl base 0.5i up
        !           174: .x2
        !           175: .mh
        !           176: Paragraphs and Headings
        !           177: .pg
        !           178: The housekeeping
        !           179: associated with starting a new paragraph should be collected
        !           180: in a paragraph macro
        !           181: that, for example,
        !           182: does the desired preparagraph spacing,
        !           183: forces the correct font, size, base-line spacing, and indent,
        !           184: checks that enough space remains for \fImore than one\fR line,
        !           185: and
        !           186: requests a temporary indent.
        !           187: .x1
        !           188: &de pg \e"paragraph
        !           189: &br    \e"break
        !           190: &ft R  \e"force font,
        !           191: &ps 10 \e"size,
        !           192: &vs 12p        \e"spacing,
        !           193: &in 0  \e"and indent
        !           194: &sp 0.4        \e"prespace
        !           195: &ne 1+\e\en(.Vu        \e"want more than 1 line
        !           196: &ti 0.2i       \e"temp indent
        !           197: &&
        !           198: .x2
        !           199: The first break in \fBpg\fR
        !           200: will force out any previous partial lines,
        !           201: and must occur before the \fBvs\fR.
        !           202: The forcing of font, etc. is
        !           203: partly a defense against prior error and
        !           204: partly to permit
        !           205: things like section heading macros to
        !           206: set parameters only once.
        !           207: The prespacing parameter is suitable for \*(TR;
        !           208: a larger space, at least as big as the output device vertical resolution, would be
        !           209: more suitable in \*(NR.
        !           210: The choice of remaining space to test for in the \fBne\fR
        !           211: is the smallest amount greater than one line
        !           212: (the \fB.V\fR is the available vertical resolution).
        !           213: .pg
        !           214: A macro to automatically number section headings
        !           215: might look like:
        !           216: .x1
        !           217: &de sc \e"section
        !           218: &  --- \e"force font, etc.
        !           219: &sp 0.4        \e"prespace
        !           220: &ne 2.4+\e\en(.Vu \e"want 2.4+ lines
        !           221: .lg 0
        !           222: &fi
        !           223: .lg
        !           224: \e\en+S.
        !           225: &&
        !           226: &nr S 0 1      \e"init S
        !           227: .x2
        !           228: The usage is \fB.sc\fR,
        !           229: followed by the section heading text,
        !           230: followed by \fB.pg\fR.
        !           231: The \fBne\fR test value includes one line of heading,
        !           232: 0.4 line in the following \fBpg\fR, and
        !           233: one line of the paragraph text.
        !           234: A word consisting of the next section number and a period is
        !           235: produced to begin the heading line.
        !           236: The format of the number may be set by \fBaf\fR (\(sc8).
        !           237: .pg
        !           238: Another common form is the labeled, indented paragraph,
        !           239: where the label protrudes left into the indent space.
        !           240: .x1
        !           241: &de lp \e"labeled paragraph
        !           242: &pg
        !           243: &in 0.5i       \e"paragraph indent
        !           244: &ta 0.2i 0.5i  \e"label, paragraph
        !           245: &ti 0
        !           246: \et\e\e$1\et\ec        \e"flow into paragraph
        !           247: &&
        !           248: .x2
        !           249: The intended usage is "\fB.lp\fR \fIlabel\fR\|";
        !           250: \fIlabel\fR will begin at 0.2\|inch, and
        !           251: cannot exceed a length of 0.3\|inch without intruding into
        !           252: the paragraph.
        !           253: The label could be right adjusted against 0.4\|inch by
        !           254: setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
        !           255: The last line of \fBlp\fR ends with \fB\ec\fR so that
        !           256: it will become a part of the first line of the text
        !           257: that follows.
        !           258: .mh
        !           259: Multiple Column Output
        !           260: .pg
        !           261: The production of multiple column pages requires
        !           262: the footer macro to decide whether it was
        !           263: invoked by other than the last column,
        !           264: so that it will begin a new column rather than
        !           265: produce the bottom margin.
        !           266: The header can initialize a column register that
        !           267: the footer will increment and test.
        !           268: The following is arranged for two columns, but
        !           269: is easily modified for more.
        !           270: .x1
        !           271: &de hd \e"header
        !           272: &  ---
        !           273: &nr cl 0 1     \e"init column count
        !           274: &mk    \e"mark top of text
        !           275: &&
        !           276: &de fo \e"footer
        !           277: &ie \e\en+(cl<2 \e{\e
        !           278: &po +3.4i      \e"next column; 3.1+0.3
        !           279: &rt    \e"back to mark
        !           280: &ns \e}        \e"no-space mode
        !           281: &el \e{\e
        !           282: &po \e\enMu    \e"restore left margin
        !           283: &  ---
        !           284: \'bp \e}
        !           285: &&
        !           286: &ll 3.1i       \e"column width
        !           287: &nr M \e\en(.o \e"save left margin
        !           288: .x2
        !           289: Typically a portion of the top of the first page
        !           290: contains full width text;
        !           291: the request for the narrower line length,
        !           292: as well as another \fB.mk\fR would
        !           293: be made where the two column output was to begin.
        !           294: .mh
        !           295: Footnote Processing
        !           296: .pg
        !           297: The footnote mechanism to be described is used by
        !           298: imbedding the footnotes in the input text at the
        !           299: point of reference,
        !           300: demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
        !           301: .x1
        !           302: &fn
        !           303: \fIFootnote text and control lines...\fP
        !           304: &ef
        !           305: .x2
        !           306: In the following,
        !           307: footnotes are processed in a separate environment and diverted
        !           308: for later printing in the space immediately prior to the bottom
        !           309: margin.
        !           310: There is provision for the case where the last collected
        !           311: footnote doesn't completely fit in the available space.
        !           312: .x1
        !           313: &de hd \e"header
        !           314: &  ---
        !           315: &nr x 0 1      \e"init footnote count
        !           316: &nr y 0\-\e\enb        \e"current footer place
        !           317: &ch fo \-\e\enbu       \e"reset footer trap
        !           318: &if \e\en(dn .fz       \e"leftover footnote
        !           319: &&
        !           320: &de fo \e"footer
        !           321: &nr dn 0       \e"zero last diversion size
        !           322: &if \e\enx \e{\e
        !           323: &ev 1  \e"expand footnotes in ev1
        !           324: &nf    \e"retain vertical size
        !           325: &FN    \e"footnotes
        !           326: &rm FN \e"delete it
        !           327: &if "\e\en(.z"fy" .di   \e"end overflow diversion
        !           328: &nr x 0        \e"disable fx
        !           329: &ev  \e}       \e"pop environment
        !           330: &  ---
        !           331: \'bp
        !           332: &&
        !           333: &de fx \e"process footnote overflow
        !           334: &if \e\enx .di fy      \e"divert overflow
        !           335: &&
        !           336: &de fn \e"start footnote
        !           337: &da FN \e"divert (append) footnote
        !           338: &ev 1  \e"in environment 1
        !           339: &if \e\en+x=1 .fs       \e"if first, include separator
        !           340: .lg0
        !           341: &fi    \e"fill mode
        !           342: .lg
        !           343: &&
        !           344: &de ef \e"end footnote
        !           345: &br    \e"finish output
        !           346: &nr z \e\en(.v \e"save spacing
        !           347: &ev    \e"pop ev
        !           348: &di    \e"end diversion
        !           349: &nr y \-\e\en(dn       \e"new footer position,
        !           350: &if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
        !           351:        \e"uncertainty correction
        !           352: &ch fo \e\enyu \e"y is negative
        !           353: &if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
        !           354: &ch fo \e\en(nlu+1v     \e"it didn't fit
        !           355: &&
        !           356: &de fs \e"separator
        !           357: \el\'\|1i\'    \e"1 inch rule
        !           358: &br
        !           359: &&
        !           360: &de fz \e"get leftover footnote
        !           361: &fn
        !           362: &nf    \e"retain vertical size
        !           363: &fy    \e"where fx put it
        !           364: &ef
        !           365: &&
        !           366: &nr b 1.0i     \e"bottom margin size
        !           367: &wh 0 hd       \e"header trap
        !           368: &wh 12i fo     \e"footer trap, temp position
        !           369: &wh \-\e\enbu fx       \e"fx at footer position
        !           370: &ch fo \-\e\enbu       \e"conceal fx with fo
        !           371: .x2
        !           372: The header \fBhd\fR initializes a footnote count register \fBx\fR,
        !           373: and sets both the current footer trap position register \fBy\fR and
        !           374: the footer trap itself to a nominal position specified in
        !           375: register \fBb\fR.
        !           376: In addition, if the register \fBdn\fR indicates a leftover footnote,
        !           377: \fBfz\fR is invoked to reprocess it.
        !           378: The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
        !           379: and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
        !           380: is interpolated.
        !           381: The separator is kept in a separate macro to permit user redefinition.
        !           382: The footnote end macro \fBef\fR restores
        !           383: the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
        !           384: \fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
        !           385: then on the first footnote, \fBy\fR is further decremented by the difference
        !           386: in vertical base-line spacings of the two environments, to
        !           387: prevent the late triggering the footer trap from causing the last
        !           388: line of the combined footnotes to overflow.
        !           389: The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
        !           390: plus one line, to allow for printing the reference line.
        !           391: If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
        !           392: in environment 1,
        !           393: and deletes \fBFN\fR.
        !           394: If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
        !           395: the overflow into \fBfy\fR,
        !           396: and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
        !           397: Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
        !           398: that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
        !           399: The footer then terminates the overflow diversion, if necessary, and
        !           400: zeros \fBx\fR to disable \fBfx\fR,
        !           401: because the uncertainty correction
        !           402: together with a not-too-late triggering of the footer can result
        !           403: in the footnote rereading finishing before reaching the \fBfx\fR trap.
        !           404: .pg
        !           405: A good exercise for the student is to combine the multiple-column and footnote mechanisms.
        !           406: .mh
        !           407: The Last Page
        !           408: .pg
        !           409: After the last input file has ended, \*(NR and \*(TR
        !           410: invoke the \fIend macro\fR (\(sc7), if any,
        !           411: and when it finishes, eject the remainder of the page.
        !           412: During the eject, any traps encountered are processed normally.
        !           413: At the \fIend\fR of this last page, processing terminates
        !           414: \fIunless\fR a partial line, word, or partial word remains.
        !           415: If it is desired that another page be started, the end-macro
        !           416: .x1
        !           417: &de en \e"end-macro
        !           418: \ec
        !           419: \'bp
        !           420: &&
        !           421: &em en
        !           422: .x2
        !           423: will deposit a null partial word,
        !           424: and effect another last page.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.