aboutsummaryrefslogtreecommitdiff
path: root/share/doc/usd/22.trofftut/tt11
diff options
context:
space:
mode:
Diffstat (limited to 'share/doc/usd/22.trofftut/tt11')
-rw-r--r--share/doc/usd/22.trofftut/tt11233
1 files changed, 233 insertions, 0 deletions
diff --git a/share/doc/usd/22.trofftut/tt11 b/share/doc/usd/22.trofftut/tt11
new file mode 100644
index 000000000000..538fac77920d
--- /dev/null
+++ b/share/doc/usd/22.trofftut/tt11
@@ -0,0 +1,233 @@
+.\" 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.