234 lines
5.9 KiB
Plaintext
234 lines
5.9 KiB
Plaintext
.\" This module is believed to contain source code proprietary to AT&T.
|
|
.\" Use and redistribution is subject to the Berkeley Software License
|
|
.\" Agreement and your Software Agreement with AT&T (Western Electric).
|
|
.\"
|
|
.\" @(#)tt11 8.1 (Berkeley) 6/8/93
|
|
.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are
|
|
.\" met:
|
|
.\"
|
|
.\" Redistributions of source code and documentation must retain the above
|
|
.\" copyright notice, this list of conditions and the following
|
|
.\" disclaimer.
|
|
.\"
|
|
.\" Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\"
|
|
.\" This product includes software developed or owned by Caldera
|
|
.\" International, Inc. Neither the name of Caldera International, Inc.
|
|
.\" nor the names of other contributors may be used to endorse or promote
|
|
.\" products derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
|
|
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
|
|
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
|
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
|
|
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.NH
|
|
Macros with arguments
|
|
.PP
|
|
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.
|
|
.PP
|
|
Let us illustrate by defining a macro
|
|
.BD .SM
|
|
that will print its argument two points
|
|
smaller than the surrounding text.
|
|
That is, the macro call
|
|
.P1
|
|
^SM TROFF
|
|
.P2
|
|
will produce
|
|
.UC TROFF .
|
|
.PP
|
|
The definition of
|
|
.BD .SM
|
|
is
|
|
.P1
|
|
^de SM
|
|
\es\-2\e\e$1\es+2
|
|
^^
|
|
.P2
|
|
Within a macro definition,
|
|
the symbol
|
|
.BD \e\e$n
|
|
refers to the
|
|
.BD n th
|
|
argument
|
|
that the macro was called with.
|
|
Thus
|
|
.BD \e\e$1
|
|
is the string to be placed in a smaller point
|
|
size when
|
|
.BD .SM
|
|
is called.
|
|
.PP
|
|
As a slightly more complicated version, the following definition of
|
|
.BD .SM
|
|
permits optional second and third arguments
|
|
that will be printed in the normal size:
|
|
.P1
|
|
^de SM
|
|
\e\e$3\es\-2\e\e$1\es+2\e\e$2
|
|
^^
|
|
.P2
|
|
Arguments not provided when the macro is called are treated
|
|
as empty,
|
|
so
|
|
.P1
|
|
^SM TROFF ),
|
|
.P2
|
|
produces
|
|
.UC TROFF ),
|
|
while
|
|
.P1
|
|
^SM TROFF ). (
|
|
.P2
|
|
produces
|
|
.UC TROFF ). (
|
|
It is convenient to reverse
|
|
the order of arguments because trailing punctuation
|
|
is much more common than leading.
|
|
.PP
|
|
By the way, the number of arguments that a macro was called with
|
|
is available in number register
|
|
.BD .$ .
|
|
.PP
|
|
The following macro
|
|
.BD ^BD
|
|
is the one used to make the
|
|
`bold roman' we have been using for
|
|
.UL troff
|
|
command names in text.
|
|
It combines horizontal motions, width computations,
|
|
and argument rearrangement.
|
|
.P1 2
|
|
\&.de BD
|
|
\e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2
|
|
\&..
|
|
.P2
|
|
The
|
|
.BD \eh
|
|
and
|
|
.BD \ew
|
|
commands need no extra backslash, as we discussed above.
|
|
The
|
|
.BD \e&
|
|
is there in case the argument begins with a period.
|
|
.WS
|
|
.PP
|
|
Two backslashes are needed with the
|
|
.BD \e\e$n
|
|
commands, though,
|
|
to protect one of them when the macro is
|
|
being defined.
|
|
Perhaps a second example will make this clearer.
|
|
Consider a macro called
|
|
.BD .SH
|
|
which
|
|
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
|
|
.P1
|
|
^SH "Section title ..."
|
|
.P2
|
|
(If the argument to a macro is to contain blanks,
|
|
then it must be
|
|
.ul
|
|
surrounded
|
|
by double quotes,
|
|
unlike a string, where only one leading quote is permitted.)
|
|
.PP
|
|
Here is the definition of the
|
|
.BD .SH
|
|
macro:
|
|
.P1
|
|
.ta .75i 1.15i
|
|
^nr SH 0 \e" initialize section number
|
|
^de SH
|
|
^sp 0.3i
|
|
^ft B
|
|
^nr SH \e\en(SH+1 \e" increment number
|
|
^ps \e\en(PS\-1 \e" decrease PS
|
|
\e\en(SH. \e\e$1 \e" number. title
|
|
^ps \e\en(PS \e" restore PS
|
|
^sp 0.3i
|
|
^ft R
|
|
^^
|
|
.P2
|
|
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.)
|
|
.PP
|
|
We used
|
|
.BD \e\en(SH
|
|
instead of
|
|
.BD \en(SH
|
|
and
|
|
.BD \e\en(PS
|
|
instead of
|
|
.BD \en(PS .
|
|
If we had used
|
|
.BD \en(SH ,
|
|
we would get the value of the register at the time the macro was
|
|
.ul
|
|
defined,
|
|
not at the time it was
|
|
.ul
|
|
used.
|
|
If that's what you want, fine,
|
|
but not here.
|
|
Similarly,
|
|
by using
|
|
.BD \e\en(PS ,
|
|
we get the point size at the time the macro is called.
|
|
.WS
|
|
.PP
|
|
As an example that does not involve numbers,
|
|
recall our
|
|
.BD .NP
|
|
macro which had a
|
|
.P1
|
|
^tl 'left'center'right'
|
|
.P2
|
|
We could make these into parameters by using instead
|
|
.P1
|
|
^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT'
|
|
.P2
|
|
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
|
|
.P1
|
|
\&^ds CT - % -
|
|
.P2
|
|
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.
|