Return to tt11 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 25.trofftut

Annotation of 43BSDReno/share/doc/usd/25.trofftut/tt11, revision 1.1

1.1     ! root        1: .\"    @(#)tt11        6.1 (Berkeley) 5/23/86
        !             2: .\"
        !             3: .NH
        !             4: Macros with arguments
        !             5: .PP
        !             6: The next step is to define macros that can change from one
        !             7: use to the next
        !             8: according to parameters supplied as arguments.
        !             9: To make this work, we need two things:
        !            10: first, when we define the macro, we have to indicate that some
        !            11: parts of it will be provided as arguments when the macro is called.
        !            12: Then when the macro is 
        !            13: called
        !            14: we have to provide actual arguments
        !            15: to be plugged into the definition.
        !            16: .PP
        !            17: Let us illustrate by defining a macro
        !            18: .BD .SM
        !            19: that will print its argument two points
        !            20: smaller than the surrounding text.
        !            21: That is, the macro call
        !            22: .P1
        !            23: ^SM TROFF
        !            24: .P2
        !            25: will produce
        !            26: .UC TROFF .
        !            27: .PP
        !            28: The definition of
        !            29: .BD .SM
        !            30: is
        !            31: .P1
        !            32: ^de SM
        !            33: \es\-2\e\e$1\es+2
        !            34: ^^
        !            35: .P2
        !            36: Within a macro definition,
        !            37: the symbol
        !            38: .BD \e\e$n
        !            39: refers to the
        !            40: .BD n th
        !            41: argument
        !            42: that the macro was called with.
        !            43: Thus
        !            44: .BD \e\e$1
        !            45: is the string to be placed in a smaller point
        !            46: size when
        !            47: .BD .SM
        !            48: is called.
        !            49: .PP
        !            50: As a slightly more complicated version, the following definition of
        !            51: .BD .SM
        !            52: permits optional second and third arguments
        !            53: that will be printed in the normal size:
        !            54: .P1
        !            55: ^de SM
        !            56: \e\e$3\es\-2\e\e$1\es+2\e\e$2
        !            57: ^^
        !            58: .P2
        !            59: Arguments not provided when the macro is called are treated
        !            60: as empty,
        !            61: so
        !            62: .P1
        !            63: ^SM  TROFF  ),
        !            64: .P2
        !            65: produces
        !            66: .UC TROFF ),
        !            67: while
        !            68: .P1
        !            69: ^SM  TROFF  ).  (
        !            70: .P2
        !            71: produces
        !            72: .UC TROFF ). (
        !            73: It is convenient to reverse 
        !            74: the order of arguments because trailing punctuation
        !            75: is much more common than leading.
        !            76: .PP
        !            77: By the way, the number of arguments that a macro was called with
        !            78: is available in number register
        !            79: .BD .$ .
        !            80: .PP
        !            81: The following macro
        !            82: .BD ^BD
        !            83: is the one used to make the
        !            84: `bold roman' we have been using for
        !            85: .UL troff
        !            86: command names in text.
        !            87: It combines horizontal motions, width computations,
        !            88: and argument rearrangement.
        !            89: .P1 2
        !            90: \&.de BD
        !            91: \e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2
        !            92: \&..
        !            93: .P2
        !            94: The
        !            95: .BD \eh
        !            96: and
        !            97: .BD \ew
        !            98: commands need no extra backslash, as we discussed above.
        !            99: The
        !           100: .BD \e&
        !           101: is there in case the argument begins with a period.
        !           102: .WS
        !           103: .PP
        !           104: Two backslashes are needed with the
        !           105: .BD \e\e$n
        !           106: commands, though,
        !           107: to protect one of them when the macro is
        !           108: being defined.
        !           109: Perhaps a second example will make this clearer.
        !           110: Consider a macro called
        !           111: .BD .SH
        !           112: which
        !           113: produces section headings rather like those in this paper,
        !           114: with the sections numbered automatically,
        !           115: and the title in bold in a smaller size.
        !           116: The use is
        !           117: .P1
        !           118: ^SH  "Section title ..."
        !           119: .P2
        !           120: (If the argument to a macro is to contain blanks,
        !           121: then it must be
        !           122: .ul
        !           123: surrounded
        !           124: by double quotes,
        !           125: unlike a string, where only one leading quote is permitted.)
        !           126: .PP
        !           127: Here is the definition of the
        !           128: .BD .SH
        !           129: macro:
        !           130: .P1
        !           131: .ta .75i 1.15i
        !           132: ^nr SH 0       \e" initialize section number
        !           133: ^de SH
        !           134: ^sp 0.3i
        !           135: ^ft B
        !           136: ^nr SH \e\en(SH+1      \e" increment number
        !           137: ^ps \e\en(PS\-1        \e" decrease PS
        !           138: \e\en(SH.  \e\e$1      \e" number. title
        !           139: ^ps \e\en(PS           \e" restore PS
        !           140: ^sp 0.3i
        !           141: ^ft R
        !           142: ^^
        !           143: .P2
        !           144: The section number is kept in number register SH, which is incremented each
        !           145: time just before it is used.
        !           146: (A number register may have the same name as a macro
        !           147: without conflict but a string may not.)
        !           148: .PP
        !           149: We used
        !           150: .BD \e\en(SH
        !           151: instead of
        !           152: .BD \en(SH
        !           153: and
        !           154: .BD \e\en(PS
        !           155: instead of
        !           156: .BD \en(PS .
        !           157: If we had used
        !           158: .BD \en(SH ,
        !           159: we would get the value of the register at the time the macro was
        !           160: .ul
        !           161: defined,
        !           162: not at the time it was
        !           163: .ul
        !           164: used.
        !           165: If that's what you want, fine,
        !           166: but not here.
        !           167: Similarly,
        !           168: by using
        !           169: .BD \e\en(PS ,
        !           170: we get the point size at the time the macro is called.
        !           171: .WS
        !           172: .PP
        !           173: As an example that does not involve numbers,
        !           174: recall our
        !           175: .BD .NP
        !           176: macro which had a
        !           177: .P1
        !           178: ^tl 'left'center'right'
        !           179: .P2
        !           180: We could make these into parameters by using instead
        !           181: .P1
        !           182: ^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT'
        !           183: .P2
        !           184: so the title comes from three strings called LT, CT and RT.
        !           185: If these are empty, then the title will be a blank line.
        !           186: Normally CT would be set with something like
        !           187: .P1
        !           188: \&^ds  CT  - % -
        !           189: .P2
        !           190: to give just the page number between hyphens (as on the top of this page),
        !           191: but a user could supply private definitions for
        !           192: any of the strings.

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