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