share/doc/usd/22.trofftut/tt10

   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 .\"     @(#)tt10        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 Number Registers and Arithmetic
  46 .PP
  47 .UL troff
  48 has a facility for doing arithmetic,
  49 and for defining and using variables with numeric values,
  50 called
  51 .ul
  52 number registers.
  53 Number registers, like strings and macros, can be useful in setting up a document
  54 so it is easy to change later.
  55 And of course they serve for any sort of arithmetic computation.
  56 .PP
  57 Like strings, number registers have one or two character names.
  58 They are set by the
  59 .BD .nr
  60 command,
  61 and are referenced anywhere by
  62 .BD \enx
  63 (one character name) or
  64 .BD \en(xy
  65 (two character name).
  66 .PP
  67 There are quite a few pre-defined number registers maintained by
  68 .UL troff ,
  69 among them
  70 .BD %
  71 for the current page number;
  72 .BD nl
  73 for the current vertical position on the page;
  74 .BD dy ,
  75 .BD mo
  76 and
  77 .BD yr
  78 for the current day, month and year; and
  79 .BD .s
  80 and
  81 .BD .f
  82 for the current size and font.
  83 (The font is a number from 1 to 4.)
  84 Any of these can be used in computations like any other register,
  85 but some, like
  86 .BD .s
  87 and
  88 .BD .f ,
  89 cannot be changed with
  90 .BD .nr .
  91 .PP
  92 As an example of the use of number registers,
  93 in the
  94 .BD \-ms
  95 macro package [4],
  96 most significant parameters are defined in terms of the values
  97 of a handful of number registers.
  98 These include the point size for text, the vertical spacing,
  99 and the line and title lengths.
 100 To set the point size and vertical spacing for the following paragraphs, for example, a user may say
 101 .P1
 102 ^nr PS 9
 103 ^nr VS 11
 104 .P2
 105 The paragraph macro
 106 .BD .PP
 107 is defined (roughly) as follows:
 108 .P1
 109 .ta  1i
 110 ^de PP
 111 ^ps \e\en(PS    \e" reset size
 112 ^vs \e\en(VSp   \e" spacing
 113 ^ft R   \e" font
 114 ^sp 0.5v        \e" half a line
 115 ^ti +3m
 116 ^^
 117 .P2
 118 This sets the font to Roman and the point size and line spacing
 119 to whatever values are stored in the number registers
 120 .BD PS
 121 and
 122 .BD VS .
 123 .PP
 124 Why are there two backslashes?
 125 This is the eternal problem of how to quote a quote.
 126 When
 127 .UL troff
 128 originally reads the macro definition,
 129 it peels off one backslash
 130 to see what's coming next.
 131 To ensure that another is left in the definition when the
 132 macro is
 133 .ul
 134 used,
 135 we have to put in two backslashes in the definition.
 136 If only one backslash is used,
 137 point size and vertical spacing will be frozen at the time the macro
 138 is defined, not when it is used.
 139 .PP
 140 Protecting by an extra layer of backslashes
 141 is only needed for
 142 .BD \en ,
 143 .BD \e* ,
 144 .BD \e$
 145 (which we haven't come to yet),
 146 and
 147 .BD \e
 148 itself.
 149 Things like
 150 .BD \es ,
 151 .BD \ef ,
 152 .BD \eh ,
 153 .BD \ev ,
 154 and so on do not need an extra backslash,
 155 since they are converted by
 156 .UL troff
 157 to an internal code immediately upon being seen.
 158 .WS
 159 .PP
 160 Arithmetic expressions can appear anywhere that
 161 a number is expected.
 162 As a trivial example,
 163 .P1
 164 ^nr PS \e\en(PS\-2
 165 .P2
 166 decrements PS by 2.
 167 Expressions can use the arithmetic operators +, \-, *, /, % (mod),
 168 the relational operators >, >=, <, <=, =, and != (not equal),
 169 and parentheses.
 170 .PP
 171 Although the arithmetic we have done so far
 172 has been straightforward,
 173 more complicated things are somewhat tricky.
 174 First,
 175 number registers hold only integers.
 176 .UL troff
 177 arithmetic uses truncating integer division, just like Fortran.
 178 Second, in the absence of parentheses,
 179 evaluation is done left-to-right
 180 without any operator precedence
 181 (including relational operators).
 182 Thus
 183 .P1
 184 7*\-4+3/13
 185 .P2
 186 becomes `\-1'.
 187 Number registers can occur anywhere in an expression,
 188 and so can scale indicators like
 189 .BD p ,
 190 .BD i ,
 191 .BD m ,
 192 and so on (but no spaces).
 193 Although integer division causes truncation,
 194 each number and its scale indicator is converted
 195 to machine units (1/432 inch) before any arithmetic is done,
 196 so
 197 1i/2u
 198 evaluates to
 199 0.5i
 200 correctly.
 201 .PP
 202 The scale indicator
 203 .BD u
 204 often has to appear
 205 when you wouldn't expect it _
 206 in particular, when arithmetic is being done
 207 in a context that implies horizontal or vertical dimensions.
 208 For example,
 209 .P1
 210 ^ll 7/2i
 211 .P2
 212 would seem obvious enough _
 213 3\(12 inches.
 214 Sorry.
 215 Remember that the default units for horizontal parameters like
 216 .BD .ll
 217 are ems.
 218 That's really `7 ems / 2 inches',
 219 and when translated into machine units, it becomes zero.
 220 How about
 221 .P1
 222 ^ll 7i/2
 223 .P2
 224 Sorry, still no good _
 225 the `2' is `2 ems', so `7i/2' is small,
 226 although not zero.
 227 You
 228 .ul
 229 must
 230 use
 231 .P1
 232 ^ll 7i/2u
 233 .P2
 234 So again, a safe rule is to
 235 attach a scale indicator to every number,
 236 even constants.
 237 .PP
 238 For arithmetic done within a
 239 .BD .nr
 240 command,
 241 there is no implication of horizontal or vertical dimension,
 242 so the default units are `units',
 243 and 7i/2 and 7i/2u
 244 mean the same thing.
 245 Thus
 246 .P1
 247 ^nr ll 7i/2
 248 ^ll \e\en(llu
 249 .P2
 250 does just what you want,
 251 so long as you
 252 don't forget the
 253 .BD u
 254 on the
 255 .BD .ll
 256 command.