config root man

.\" 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: release/9.1.0/share/doc/usd/22.trofftut/tt11 96897 2002-05-19 03:37:41Z grog $
.\"
.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.