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