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