share/doc/usd/22.trofftut/tt11

   1 .\" This module is believed to contain source code proprietary to AT&T.
   2 .\" Use and redistribution is subject to the Berkeley Software License
   3 .\" Agreement and your Software Agreement with AT&T (Western Electric).
   4 .\"
   5 .\"     @(#)tt11        8.1 (Berkeley) 6/8/93
   6 .\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions are
  10 .\" met:
  11 .\"
  12 .\" Redistributions of source code and documentation must retain the above
  13 .\" copyright notice, this list of conditions and the following
  14 .\" disclaimer.
  15 .\"
  16 .\" Redistributions in binary form must reproduce the above copyright
  17 .\" notice, this list of conditions and the following disclaimer in the
  18 .\" documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" All advertising materials mentioning features or use of this software
  21 .\" must display the following acknowledgement:
  22 .\"
  23 .\" This product includes software developed or owned by Caldera
  24 .\" International, Inc.  Neither the name of Caldera International, Inc.
  25 .\" nor the names of other contributors may be used to endorse or promote
  26 .\" products derived from this software without specific prior written
  27 .\" permission.
  28 .\"
  29 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  30 .\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  31 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  32 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33 .\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  34 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  36 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  37 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  39 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  40 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41 .\"
  42 .\" $FreeBSD$
  43 .\"
  44 .NH
  45 Macros with arguments
  46 .PP
  47 The next step is to define macros that can change from one
  48 use to the next
  49 according to parameters supplied as arguments.
  50 To make this work, we need two things:
  51 first, when we define the macro, we have to indicate that some
  52 parts of it will be provided as arguments when the macro is called.
  53 Then when the macro is
  54 called
  55 we have to provide actual arguments
  56 to be plugged into the definition.
  57 .PP
  58 Let us illustrate by defining a macro
  59 .BD .SM
  60 that will print its argument two points
  61 smaller than the surrounding text.
  62 That is, the macro call
  63 .P1
  64 ^SM TROFF
  65 .P2
  66 will produce
  67 .UC TROFF .
  68 .PP
  69 The definition of
  70 .BD .SM
  71 is
  72 .P1
  73 ^de SM
  74 \es\-2\e\e$1\es+2
  75 ^^
  76 .P2
  77 Within a macro definition,
  78 the symbol
  79 .BD \e\e$n
  80 refers to the
  81 .BD n th
  82 argument
  83 that the macro was called with.
  84 Thus
  85 .BD \e\e$1
  86 is the string to be placed in a smaller point
  87 size when
  88 .BD .SM
  89 is called.
  90 .PP
  91 As a slightly more complicated version, the following definition of
  92 .BD .SM
  93 permits optional second and third arguments
  94 that will be printed in the normal size:
  95 .P1
  96 ^de SM
  97 \e\e$3\es\-2\e\e$1\es+2\e\e$2
  98 ^^
  99 .P2
 100 Arguments not provided when the macro is called are treated
 101 as empty,
 102 so
 103 .P1
 104 ^SM  TROFF  ),
 105 .P2
 106 produces
 107 .UC TROFF ),
 108 while
 109 .P1
 110 ^SM  TROFF  ).  (
 111 .P2
 112 produces
 113 .UC TROFF ). (
 114 It is convenient to reverse
 115 the order of arguments because trailing punctuation
 116 is much more common than leading.
 117 .PP
 118 By the way, the number of arguments that a macro was called with
 119 is available in number register
 120 .BD .$ .
 121 .PP
 122 The following macro
 123 .BD ^BD
 124 is the one used to make the
 125 `bold roman' we have been using for
 126 .UL troff
 127 command names in text.
 128 It combines horizontal motions, width computations,
 129 and argument rearrangement.
 130 .P1 2
 131 \&.de BD
 132 \e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2
 133 \&..
 134 .P2
 135 The
 136 .BD \eh
 137 and
 138 .BD \ew
 139 commands need no extra backslash, as we discussed above.
 140 The
 141 .BD \e&
 142 is there in case the argument begins with a period.
 143 .WS
 144 .PP
 145 Two backslashes are needed with the
 146 .BD \e\e$n
 147 commands, though,
 148 to protect one of them when the macro is
 149 being defined.
 150 Perhaps a second example will make this clearer.
 151 Consider a macro called
 152 .BD .SH
 153 which
 154 produces section headings rather like those in this paper,
 155 with the sections numbered automatically,
 156 and the title in bold in a smaller size.
 157 The use is
 158 .P1
 159 ^SH  "Section title ..."
 160 .P2
 161 (If the argument to a macro is to contain blanks,
 162 then it must be
 163 .ul
 164 surrounded
 165 by double quotes,
 166 unlike a string, where only one leading quote is permitted.)
 167 .PP
 168 Here is the definition of the
 169 .BD .SH
 170 macro:
 171 .P1
 172 .ta .75i 1.15i
 173 ^nr SH 0        \e" initialize section number
 174 ^de SH
 175 ^sp 0.3i
 176 ^ft B
 177 ^nr SH \e\en(SH+1       \e" increment number
 178 ^ps \e\en(PS\-1 \e" decrease PS
 179 \e\en(SH.  \e\e$1       \e" number. title
 180 ^ps \e\en(PS            \e" restore PS
 181 ^sp 0.3i
 182 ^ft R
 183 ^^
 184 .P2
 185 The section number is kept in number register SH, which is incremented each
 186 time just before it is used.
 187 (A number register may have the same name as a macro
 188 without conflict but a string may not.)
 189 .PP
 190 We used
 191 .BD \e\en(SH
 192 instead of
 193 .BD \en(SH
 194 and
 195 .BD \e\en(PS
 196 instead of
 197 .BD \en(PS .
 198 If we had used
 199 .BD \en(SH ,
 200 we would get the value of the register at the time the macro was
 201 .ul
 202 defined,
 203 not at the time it was
 204 .ul
 205 used.
 206 If that's what you want, fine,
 207 but not here.
 208 Similarly,
 209 by using
 210 .BD \e\en(PS ,
 211 we get the point size at the time the macro is called.
 212 .WS
 213 .PP
 214 As an example that does not involve numbers,
 215 recall our
 216 .BD .NP
 217 macro which had a
 218 .P1
 219 ^tl 'left'center'right'
 220 .P2
 221 We could make these into parameters by using instead
 222 .P1
 223 ^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT'
 224 .P2
 225 so the title comes from three strings called LT, CT and RT.
 226 If these are empty, then the title will be a blank line.
 227 Normally CT would be set with something like
 228 .P1
 229 \&^ds  CT  - % -
 230 .P2
 231 to give just the page number between hyphens (as on the top of this page),
 232 but a user could supply private definitions for
 233 any of the strings.