11.  Macros with arguments

      The next step is to define macros that can change from one use to the next according to parameters supplied as arguments. To make this work, we need two things: first, when we define the macro, we have to indicate that some parts of it will be provided as arguments when the macro is called. Then when the macro is called we have to provide actual arguments to be plugged into the definition.

      Let us illustrate by defining a macro .SMthat will print its argument two points smaller than the surrounding text. That is, the macro call ^SM TROFF
will produce
TROFF.

      The definition of .SMis ^de SM
\s-2\\$1\s+2
^^
Within a macro definition,
the symbol
\\$nrefers to the
nargument
that the macro was called with.
Thus
\\$1is the string to be placed in a smaller point
size when
.SMis called.

      As a slightly more complicated version, the following definition of .SMpermits optional second and third arguments that will be printed in the normal size: ^de SM
\\$3\s-2\\$1\s+2\\$2
^^
Arguments not provided when the macro is called are treated
as empty,
so
^SM TROFF ),
produces
TROFF),
while
^SM TROFF ). (
produces
(TROFF).
It is convenient to reverse
the order of arguments because trailing punctuation
is much more common than leading.

      By the way, the number of arguments that a macro was called with is available in number register .$

      The following macro ^BDis the one used to make the `bold roman' we have been using for troff command names in text. It combines horizontal motions, width computations, and argument rearrangement. .de BD
\&\\$3\f1\\$1\h'-\w'\\$1'u+1u'\\$1\fP\\$2
..
The
\hand
\wcommands need no extra backslash, as we discussed above.
The
\&is there in case the argument begins with a period.

      Two backslashes are needed with the \\$ncommands, though, to protect one of them when the macro is being defined. Perhaps a second example will make this clearer. Consider a macro called .SHwhich produces section headings rather like those in this paper, with the sections numbered automatically, and the title in bold in a smaller size. The use is ^SH "Section title ..."
(If the argument to a macro is to contain blanks,
then it must be
surrounded
by double quotes,
unlike a string, where only one leading quote is permitted.)

      Here is the definition of the .SHmacro: ^nr SH 0 \" initialize section number
^de SH
^sp 0.3i
^ft B
^nr SH \\n(SH+1 \" increment number
^ps \\n(PS-1 \" decrease PS
\\n(SH. \\$1 \" number. title
^ps \\n(PS \" restore PS
^sp 0.3i
^ft R
^^
The section number is kept in number register SH, which is incremented each
time just before it is used.
(A number register may have the same name as a macro
without conflict but a string may not.)

      We used \\n(SHinstead of \n(SHand \\n(PSinstead of \n(PSIf we had used \n(SHwe would get the value of the register at the time the macro was defined, not at the time it was used. If that's what you want, fine, but not here. Similarly, by using \\n(PSwe get the point size at the time the macro is called.

      As an example that does not involve numbers, recall our .NPmacro which had a ^tl 'left'center'right'
We could make these into parameters by using instead
^tl '\\*(LT'\\*(CT'\\*(RT'
so the title comes from three strings called LT, CT and RT.
If these are empty, then the title will be a blank line.
Normally CT would be set with something like
^ds CT - % -
to give just the page number between hyphens (as on the top of this page),
but a user could supply private definitions for
any of the strings.