share/doc/usd/22.trofftut/tt08

   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 .\"     @(#)tt08        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 Introduction to Macros
  46 .PP
  47 Before we can go much further in
  48 .UL troff ,
  49 we need to learn a bit about the
  50 macro
  51 facility.
  52 In its simplest form, a macro is just a shorthand notation
  53 quite similar to a string.
  54 Suppose we want every paragraph to start
  55 in exactly the same way _
  56 with a space and a temporary indent of two ems:
  57 .P1
  58 ^sp
  59 ^ti +2m
  60 .P2
  61 Then to save typing, we would like to collapse these into
  62 one shorthand line,
  63 a
  64 .UL troff
  65 `command' like
  66 .P1
  67 ^PP
  68 .P2
  69 that would be treated by
  70 .UL troff
  71 exactly as
  72 .P1
  73 ^sp
  74 ^ti +2m
  75 .P2
  76 .BD .PP
  77 is called a
  78 .ul
  79 macro.
  80 The way we tell
  81 .UL troff
  82 what
  83 .BD .PP
  84 means is to
  85 .ul
  86 define
  87 it with the
  88 .BD .de
  89 command:
  90 .P1
  91 ^de PP
  92 ^sp
  93 ^ti +2m
  94 ^^
  95 .P2
  96 The first line names the macro
  97 (we used
  98 .BD .PP ' `
  99 for `paragraph',
 100 and upper case so it wouldn't conflict with
 101 any name that
 102 .UL troff
 103 might
 104 already know about).
 105 The last line
 106 .BD ..
 107 marks the end of the definition.
 108 In between is the text,
 109 which is simply inserted whenever
 110 .UL troff
 111 sees the `command'
 112 or macro call
 113 .P1
 114 ^PP
 115 .P2
 116 A macro
 117 can contain any mixture of text and formatting commands.
 118 .PP
 119 The definition of
 120 .BD .PP
 121 has to precede its first use;
 122 undefined macros are simply ignored.
 123 Names are restricted to one or two characters.
 124 .PP
 125 Using macros for commonly occurring sequences of commands
 126 is critically important.
 127 Not only does it save typing,
 128 but it makes later changes much easier.
 129 Suppose we decide that the paragraph indent is too small,
 130 the vertical space is much too big,
 131 and roman font should be forced.
 132 Instead of changing the whole document,
 133 we need only change the definition of
 134 .BD .PP
 135 to
 136 something like
 137 .P1
 138 ^de PP  \e" paragraph macro
 139 ^sp 2p
 140 ^ti +3m
 141 ^ft R
 142 ^^
 143 .P2
 144 and the change takes
 145 effect everywhere we used
 146 .BD .PP .
 147 .PP
 148 .BD \e"
 149 is a
 150 .UL troff
 151 command that causes the rest of the line to be ignored.
 152 We use it here to add comments to the macro
 153 definition
 154 (a wise idea once definitions get complicated).
 155 .PP
 156 As another example of macros,
 157 consider these two which start and end a block of offset,
 158 unfilled text, like most of the examples in this paper:
 159 .P1
 160 ^de BS  \e" start indented block
 161 ^sp
 162 ^nf
 163 ^in +0.3i
 164 ^^
 165 ^de BE  \e" end indented block
 166 ^sp
 167 ^fi
 168 ^in \(mi0.3i
 169 ^^
 170 .P2
 171 Now we can surround text like
 172 .P1
 173 Copy to
 174 John Doe
 175 Richard Roberts
 176 Stanley Smith
 177 .P2
 178 by the commands
 179 .BD .BS
 180 and
 181 .BD .BE ,
 182 and it will come out as it did above.
 183 Notice that we indented by
 184 .BD .in\ +0.3i
 185 instead of
 186 .BD .in\ 0.3i .
 187 This way we can nest our uses of
 188 .BD .BS
 189 and
 190 .BD BE
 191 to get blocks within blocks.
 192 .PP
 193 If later on we decide that the indent
 194 should be 0.5i, then it is only necessary to
 195 change the definitions of
 196 .BD .BS
 197 and
 198 .BD .BE ,
 199 not the whole paper.