Return to m4 CVS log

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

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

1.1     ! root        1: .\"    @(#)m4  6.2 (Berkeley) 4/21/86
        !             2: .\"
        !             3: .tr |
        !             4: .mh
        !             5: Hyphenation.
        !             6: .pg
        !             7: The automatic hyphenation may be switched off and on.
        !             8: When switched on with \fBhy\fR,
        !             9: several variants may be set.
        !            10: A \fIhyphenation indicator\fR character may be imbedded in a word to
        !            11: specify desired hyphenation points,
        !            12: or may be prepended to suppress hyphenation.
        !            13: In addition,
        !            14: the user may specify a small exception word list.
        !            15: .pg
        !            16: Only words that consist of a central alphabetic string
        !            17: surrounded by (usually null) non-alphabetic strings
        !            18: are considered candidates for automatic hyphenation.
        !            19: Words that were input containing hyphens
        !            20: (minus),
        !            21: em-dashes (\fB\e(em\fR),
        !            22: or hyphenation indicator characters\
        !            23: \(emsuch as mother-in-law\(em\
        !            24: are \fIalways\fR subject to splitting after those characters,
        !            25: whether or not automatic hyphenation is on or off.
        !            26: .h1
        !            27: .bt
        !            28: \fB&nh\fR      hyphenate       -       E       \
        !            29: Automatic hyphenation is turned off.
        !            30: .bt
        !            31: \fB&hy\fIN\fR  on,\fIN=\fR1    on,\fIN=\fR1    E       \
        !            32: Automatic hyphenation is turned on
        !            33: for \fIN\fR\|\(>=1, or off for \fIN=\fR\|0.
        !            34: If \fIN=\fR\|2, \fIlast\fR lines (ones that will cause a trap)
        !            35: are not hyphenated.
        !            36: For \fIN=\fR\|4 and 8, the last and first two characters
        !            37: respectively of a word are not split off.
        !            38: These values are additive;
        !            39: i.|e. \fIN=\fR\|14 will invoke all three restrictions.
        !            40: .bt
        !            41: \fB&hc\fI|c\fR \fB\e%  \e%\fR  E       Hyphenation indicator character is set
        !            42: to \fIc\fR or to the default \fB\e%\fR.
        !            43: The indicator does not appear in the output.
        !            44: .bt
        !            45: \fB&hw\fI|word1|...\fR         ignored -       Specify hyphenation points in words
        !            46: with imbedded minus signs.
        !            47: Versions of a word with terminal \fIs\fR are implied;
        !            48: i.|e. \fIdig\-it\fR implies \fIdig\-its\fR.
        !            49: This list is examined initially \fIand\fR after
        !            50: each suffix stripping.
        !            51: The space available is small\(emabout 128 characters.
        !            52: .mh
        !            53: Three Part Titles.
        !            54: .pg
        !            55: The titling function \fBtl\fR provides for automatic placement
        !            56: of three fields at the left, center, and right of a line
        !            57: with a title-length
        !            58: specifiable with \fBlt\fR.
        !            59: \fBtl\fR may be used anywhere, and is independent of the
        !            60: normal text collecting process.
        !            61: A common use is in header and footer macros.
        !            62: .h1
        !            63: .bt
        !            64: \fB&tl\fI|\'left\|\'center\|\'right\|\'\fR     -       -       \
        !            65: The strings \fIleft\fR, \fIcenter\fR, and \fIright\fR are
        !            66: respectively left-adjusted, centered, and right-adjusted
        !            67: in the current title-length.
        !            68: Any of the strings may be empty,
        !            69: and overlapping is permitted.
        !            70: If the page-number character (initially \fB%\fR) is found within any of the fields it is replaced
        !            71: by the current page number having the format assigned to register \fB%\fR.
        !            72: Any character may be used as the string delimiter.
        !            73: .bt
        !            74: \fB&pc\fI|c\fR \fB%\fR off     -       The page number character is set to \fIc\fR,
        !            75: or removed.
        !            76: The page-number register remains \fB%\fR.
        !            77: .bt
        !            78: \fB&lt\fI|\(+-N\fR     6.5\|in previous        E,\fBm\fR       Length of title set to \fI\(+-N\fR.
        !            79: The line-length and the title-length are \fIindependent\fR.
        !            80: Indents do not apply to titles; page-offsets do.
        !            81: .mh
        !            82: Output Line Numbering.
        !            83: .pg
        !            84: .ll -\w'0000'u
        !            85: .nm 1 3
        !            86: Automatic sequence numbering of output lines may be
        !            87: requested with \fBnm\fR.
        !            88: When in effect,
        !            89: a three-digit, arabic number plus a digit-space
        !            90: is prepended to output text lines.
        !            91: The text lines are thus offset by four digit-spaces,
        !            92: and otherwise retain their line length;
        !            93: a reduction in line length may be desired to keep the right margin
        !            94: aligned with an earlier margin.
        !            95: Blank lines, other vertical spaces, and lines generated by \fBtl\fR
        !            96: are \fInot\fR numbered.
        !            97: Numbering can be temporarily suspended with \fBnn\fR,
        !            98: or with an \fB.nm\fR followed by a later \fB.nm|+0\fR.
        !            99: In addition,
        !           100: a line number indent \fII\fR, and the number-text separation \fIS\fR
        !           101: may be specified in digit-spaces.
        !           102: Further, it can be specified that only those line numbers that are
        !           103: multiples of some number \fIM\fR are to be printed (the others will appear
        !           104: as blank number fields).
        !           105: .br
        !           106: .nm
        !           107: .ll
        !           108: .h1
        !           109: .bt
        !           110: \fB&nm\fI|\(+-N|M|S|I\fR       off     E       \
        !           111: Line number mode.
        !           112: If \fI\(+-N\fR is given,
        !           113: line numbering is turned on,
        !           114: and the next output line numbered is numbered \fI\(+-N\fR.
        !           115: Default values are \fIM=\fR\|1, \fIS=\fR\|1, and \fII=\fR\|0.
        !           116: Parameters corresponding to missing arguments are unaffected;
        !           117: a non-numeric argument is considered missing.
        !           118: In the absence of all arguments, numbering is turned off;
        !           119: the next line number is preserved for possible further use
        !           120: in number register \fBln\fR.
        !           121: .bt
        !           122: \fB&nn\fI|N\fR -       \fIN=\fR1       E       The next \fIN\fR text output lines are not
        !           123: numbered.
        !           124: .pg
        !           125: .ll -\w'0000'u
        !           126: .nm +0
        !           127: As an example, the paragraph portions of this section
        !           128: are numbered with \fIM=\fR\|3:
        !           129: \&\fB.nm|1|3\fR was placed at the beginning;
        !           130: \&\fB.nm\fR was placed at the end of the first paragraph;
        !           131: and \fB.nm|+0\fR was placed in front of this paragraph;
        !           132: and \fB.nm\fR finally placed at the end.
        !           133: Line lengths were also changed (by \fB\ew\'0000\'u\fR) to keep the right side aligned.
        !           134: Another example is
        !           135: \&\fB.nm|+5|5|x|3\fR which turns on numbering with the line number of the next
        !           136: line to be 5 greater than the last numbered line,
        !           137: with \fIM=\fR\|5, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3.
        !           138: .br
        !           139: .ll
        !           140: .nm
        !           141: .mh
        !           142: Conditional Acceptance of Input
        !           143: .pg
        !           144: In the following,
        !           145: \fIc\fR is a one-character, built-in \fIcondition\fR name,
        !           146: \fB!\fR signifies \fInot\fR,
        !           147: \fIN\fR is a numerical expression,
        !           148: \fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character \fInot\fR in the strings,
        !           149: and
        !           150: \fIanything\fR represents what is conditionally accepted.
        !           151: .h1
        !           152: .bt
        !           153: \fB&if\fI|c|anything\fR        -       -       If condition \fIc\fR true, accept \fIanything\fR as input;
        !           154: in multi-line case use \fI\e{anything\|\e}\fR.
        !           155: .bt
        !           156: \fB&if|!\fIc|anything\fR       -       -       If condition \fIc\fR false, accept \fIanything\fR.
        !           157: .bt
        !           158: \fB&if\fI|N|anything\fR        -       \fBu\fR If expression \fIN\fR > 0, accept \fIanything\fR.
        !           159: .bt
        !           160: \fB&if|!\fIN|anything\fR       -       \fBu\fR If expression \fIN\fR \(<= 0, accept \fIanything\fR.
        !           161: .bt
        !           162: \fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR       -       If \fIstring1\fR identical to \fIstring2\fR,
        !           163: accept \fIanything\fR.
        !           164: .bt
        !           165: \fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR      -       If \fIstring1\fR not identical to \fIstring2\fR,
        !           166: accept \fIanything\fR.
        !           167: .bt
        !           168: \fB&ie\fI|c|anything\fR        -       \fBu\fR If portion of if-else; all above forms (like \fBif\fR).
        !           169: .bt
        !           170: \fB&el\fI|anything\fR          -       -       Else portion of if-else.
        !           171: .pg
        !           172: The built-in condition names are:
        !           173: .TS
        !           174: center box;
        !           175: c2|c2
        !           176: c2|c2
        !           177: c2|l2.
        !           178: Condition
        !           179: Name   True If
        !           180: _
        !           181: \fBo\fR        Current page number is odd
        !           182: \fBe\fR        Current page number is even
        !           183: \fBt\fR        Formatter is \*(TR
        !           184: \fBn\fR        Formatter is \*(NR
        !           185: .TE
        !           186: If the condition \fIc\fR is \fItrue\fR, or if the number \fIN\fR is greater than zero,
        !           187: or if the strings compare identically (including motions and character size and font),
        !           188: \fIanything\fR is accepted as input.
        !           189: If a \fB!\fR precedes the condition, number, or string comparison,
        !           190: the sense of the acceptance is reversed.
        !           191: .pg
        !           192: Any spaces between the condition and the beginning of \fIanything\fR are skipped over.
        !           193: The \fIanything\fR can be either a single input line (text, macro, or whatever)
        !           194: or a number of input lines.
        !           195: In the multi-line case,
        !           196: the first line must begin with a left delimiter \fB\e{\fR and
        !           197: the last line must end with a right delimiter \fB\e}\fR.
        !           198: .pg
        !           199: The request \fBie\fR (if-else) is identical to \fBif\fR
        !           200: except that the acceptance state is remembered.
        !           201: A subsequent and matching \fBel\fR (else) request then uses the reverse sense of that state.
        !           202: \fBie\fR|-|\fBel\fR pairs may be nested.
        !           203: .pg
        !           204: Some examples are:
        !           205: .x1
        !           206: .ftB
        !           207: .ne 1
        !           208: &if e .tl \'\|Even Page %\'\'\'
        !           209: .ftR
        !           210: .x2
        !           211: which outputs a title if the page number is even; and
        !           212: .x1
        !           213: .ftB
        !           214: .ne 3.1
        !           215: &ie \en%>1 \e{\e
        !           216: \&\'sp 0.5i
        !           217: &tl \'\|Page %\'\'\'
        !           218: \&\'sp ~\|1.2i|\e}
        !           219: &el .sp ~\|2.5i
        !           220: .ftR
        !           221: .x2
        !           222: which treats page 1 differently from other pages.
        !           223: .mh
        !           224: Environment Switching.
        !           225: .pg
        !           226: A number of the parameters that
        !           227: control the text processing are gathered together into an
        !           228: \fIenvironment\fR, which can be switched by the user.
        !           229: The environment parameters are those associated
        !           230: with requests noting E in their \fINotes\fR column;
        !           231: in addition, partially collected lines and words are in the environment.
        !           232: Everything else is global; examples are page-oriented parameters,
        !           233: diversion-oriented parameters, number registers, and macro and string definitions.
        !           234: All environments are initialized with default parameter values.
        !           235: .h1
        !           236: .bt
        !           237: \fB&ev\fI|N\fR \fIN\(eq\fR0    previous        -       Environment switched to
        !           238: environment 0\(<=\fIN\fR\(<=2.
        !           239: Switching is done in push-down fashion so that
        !           240: restoring a previous environment \fImust\fR be done with \fB.ev\fR
        !           241: rather than specific reference.
        !           242: .mh
        !           243: Insertions from the Standard Input
        !           244: .pg
        !           245: The input can be temporarily switched to the system \fIstandard input\fR
        !           246: with \fBrd\fR,
        !           247: which will switch back when \fItwo\fR newlines
        !           248: in a row are found (the \fIextra\fR blank line is not used).
        !           249: This mechanism is intended for insertions in form-letter-like documentation.
        !           250: On \s-1UNIX\s+1, the \fIstandard input\fR can be the user's keyboard,
        !           251: a \fIpipe\fR, or a \fIfile\fR.
        !           252: .h1
        !           253: .bt
        !           254: \fB&rd\fI|prompt\fR    -       \fIprompt=\fR\s-1BEL\s+1        \
        !           255: Read insertion from the standard input until two newlines in a row are found.
        !           256: If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1)
        !           257: is written onto the user's terminal.
        !           258: \fBrd\fR behaves like a macro,
        !           259: and arguments may be placed after \fIprompt\fR.
        !           260: .bt
        !           261: \fB&ex\fR      -       -       -       Exit from \*(NR\(sl\*(TR.
        !           262: Text processing is terminated exactly as if all input had ended.
        !           263: .pg
        !           264: If insertions are to be
        !           265: taken from the terminal keyboard \fIwhile\fR output is being printed
        !           266: on the terminal, the command line option \fB\-q\fR will turn off the echoing
        !           267: of keyboard input and prompt only with \s-1BEL\s+1.
        !           268: The regular input and insertion input \fIcannot\fR
        !           269: simultaneously come from the standard input.
        !           270: .pg
        !           271: As an example,
        !           272: multiple copies of a form letter may be prepared by entering the insertions
        !           273: for all the copies in one file to be used as the standard input,
        !           274: and causing the file containing the letter to reinvoke itself using \fBnx\fR (\(sc19);
        !           275: the process would ultimately be ended by an \fBex\fR in the insertion file.
        !           276: .mh
        !           277: Input\(slOutput File Switching
        !           278: .pg
        !           279: The (read-only) number register \fB.c\fR contains the input line number in
        !           280: the current input file.  The number register \fBc.\fR is a general register
        !           281: serving the same purpose.
        !           282: .h1
        !           283: .bt
        !           284: \fB&so\fI|filename\fR          -       -       Switch source file.
        !           285: The top input (file reading) level is switched to \fIfilename\fR.
        !           286: The effect of an \fBso\fR encountered in a macro
        !           287: occurs immediately.
        !           288: When the new file ends,
        !           289: input is again taken from the original file.
        !           290: \fBso\fR's may be nested.
        !           291: .bt
        !           292: \fB&nx\fI|filename\fR          end-of-file     -       Next file is \fIfilename\fR.
        !           293: The current file is considered ended, and the input is immediately switched
        !           294: to \fIfilename\fR.
        !           295: .bt
        !           296: \fB&pi\fI|program\fR           -       -       Pipe output to \fIprogram\fR (\*(NR only).
        !           297: This request must occur \fIbefore\fR any printing occurs.
        !           298: No arguments are transmitted to \fIprogram\fR.
        !           299: .mh
        !           300: Miscellaneous
        !           301: .pg
        !           302: .h1
        !           303: .bt
        !           304: .mc \s12\(br\s0
        !           305: \fB&mc\fI|c|N\fR       -       off     E,\fBm\fR       \
        !           306: Specifies that a \fImargin\fR character \fIc\fR appear a distance
        !           307: \fIN\fR to the right of the right margin
        !           308: after each non-empty text line (except those produced by \fBtl\fR).
        !           309: If the output line is too-long (as can happen in nofill mode)
        !           310: the character will be appended to the line.
        !           311: If \fIN\fR is not given, the previous \fIN\fR is used; the initial \fIN\fR is
        !           312: 0.2|inches in \*(NR and 1\|em in \*(TR.
        !           313: The margin character used with this paragraph was a 12-point box-rule.
        !           314: .br
        !           315: .mc
        !           316: .bt
        !           317: \fB&tm\fI|string\fR    -       newline -       \
        !           318: After skipping initial blanks, \fIstring\fR (rest of the line) is read in \fIcopy mode\fR
        !           319: and written on the user's terminal. (see \(sc21).
        !           320: .bt
        !           321: \fB&ig\fI|yy\fR        -       \fI.yy=\fB..\fR -       Ignore \
        !           322: input lines.
        !           323: \fBig\fR behaves exactly like \fBde\fR (\(sc7) except that the
        !           324: input is discarded.
        !           325: The input is read in \fIcopy mode\fR, and any auto-incremented
        !           326: registers will be affected.
        !           327: .bt
        !           328: \fB&pm\fI|t\fR -       all     -       \
        !           329: Print macros.
        !           330: The names and sizes of all of the defined macros and strings are printed
        !           331: on the user's terminal;
        !           332: if \fIt\fR is given, only the total of the sizes is printed.
        !           333: The sizes is given in \fIblocks\fR
        !           334: of 128 characters.
        !           335: .bt
        !           336: \fB&ab\fI|string\fR    -       -       -       \
        !           337: Print \fIstring\fR on standard error and terminate immediately.  The
        !           338: default \fIstring\fR is "User Abort". Does not cause a break.  Only output
        !           339: preceding the last break is written.
        !           340: .bt
        !           341: .lg0
        !           342: \fB&fl\fR      -       -       B       \c
        !           343: .lg
        !           344: Flush output buffer.
        !           345: Used in interactive debugging to force output.
        !           346: .mh
        !           347: Output and Error Messages.
        !           348: .pg
        !           349: The output from \fBtm\fR, \fBpm\fR, \fBab\fR and the prompt from \fBrd\fR,
        !           350: as well as various \fIerror\fR messages are written onto
        !           351: \s-1UNIX\s+1's \fIstandard error\fR output.
        !           352: The latter is different from the \fIstandard output\fR,
        !           353: where \*(NR formatted output goes.
        !           354: By default, both are written onto the user's terminal,
        !           355: but they can be independently redirected.
        !           356: .pg
        !           357: Various \fIerror\fR conditions may occur during
        !           358: the operation of \*(NR and \*(TR.
        !           359: Certain less serious errors having only local impact do not
        !           360: cause processing to terminate.
        !           361: Two examples are \fIword overflow\fR, caused by a word that is too large
        !           362: to fit into the word buffer (in fill mode), and
        !           363: \fIline overflow\fR, caused by an output line that grew too large
        !           364: to fit in the line buffer;
        !           365: in both cases, a message is printed, the offending excess
        !           366: is discarded,
        !           367: and the affected word or line is marked at the point of truncation
        !           368: with a \(** in \*(NR and a \(lh in \*(TR.
        !           369: The philosophy is to continue processing, if possible,
        !           370: on the grounds that output useful for debugging may be produced.
        !           371: If a serious error occurs, processing terminates,
        !           372: and an appropriate message is printed.
        !           373: Examples are the inability to create, read, or write files,
        !           374: and the exceeding of certain internal limits that
        !           375: make future output unlikely to be useful.

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