share/doc/usd/22.trofftut/tt09

   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 .\"     @(#)tt09        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 Titles, Pages and Numbering
  46 .PP
  47 This is an area where things get tougher,
  48 because nothing is done for you automatically.
  49 Of necessity, some of this section is a cookbook,
  50 to be copied literally until you get some experience.
  51 .PP
  52 Suppose you want a title at the top of each page,
  53 saying just
  54 .sp 3p
  55 .lt 2.8i
  56 .tl 'left top'center top'right top'
  57 .lt
  58 .sp 3p
  59 In
  60 .UL roff ,
  61 one can say
  62 .P1 2
  63 ^he 'left top'center top'right top'
  64 ^fo 'left bottom'center bottom'right bottom'
  65 .P2
  66 to get headers and footers automatically on every page.
  67 Alas, this doesn't work so easily in
  68 .UL troff ,
  69 a serious hardship for the novice.
  70 Instead you have to do a lot of specification (or use
  71 a macro package, which makes it effortless).
  72 .PP
  73 You have to say what the actual title is (easy);
  74 when to print it (easy enough);
  75 and what to do at and around the title line (harder).
  76 Taking these in reverse order,
  77 first we define a macro
  78 .BD .NP
  79 (for `new page') to process
  80 titles and the like at the end of one page
  81 and the beginning of the next:
  82 .P1
  83 ^de NP
  84 \(fmbp
  85 \(fmsp 0.5i
  86 \&.tl 'left top'center top'right top'
  87 \(fmsp 0.3i
  88 ^^
  89 .P2
  90 To make sure we're at the top of a page,
  91 we issue a `begin page' command
  92 .BD \(fmbp ,
  93 which causes a skip to top-of-page
  94 (we'll explain the
  95 .BD \(fm
  96 shortly).
  97 Then we space down half an inch,
  98 print the title
  99 (the use of
 100 .BD .tl
 101 should be self explanatory; later we will discuss parameterizing the titles),
 102 space another 0.3 inches,
 103 and we're done.
 104 .PP
 105 To ask for
 106 .BD .NP
 107 at the bottom of each page,
 108 we have to say something like
 109 `when the text is within an inch
 110 of the bottom of the page,
 111 start the processing
 112 for a new page.'
 113 This is done with a `when' command
 114 .BD .wh :
 115 .P1
 116 ^wh  \-1i  NP
 117 .P2
 118 (No `.' is used before NP;
 119 this is simply the name of a macro, not a macro call.)
 120 The minus sign means
 121 `measure up from the bottom of the page',
 122 so
 123 `\-1i' means `one inch from the bottom'.
 124 .PP
 125 The
 126 .BD .wh
 127 command appears in the input outside the definition of
 128 .BD .NP ;
 129 typically the input would be
 130 .P1
 131 ^de NP
 132 ^^^
 133 ^^
 134 ^wh \-1i NP
 135 .P2
 136 .PP
 137 Now what happens?
 138 As text is actually being output,
 139 .UL troff
 140 keeps track of its vertical position on the page,
 141 and after a line is printed within one inch from the bottom,
 142 the
 143 .BD .NP
 144 macro is activated.
 145 (In the jargon, the
 146 .BD .wh
 147 command sets a
 148 .ul
 149 trap
 150 at the specified place,
 151 which is `sprung' when that point is passed.)
 152 .BD .NP
 153 causes a skip to the top of the next page
 154 (that's what the
 155 .BD \(fmbp
 156 was for),
 157 then prints the title with the appropriate margins.
 158 .PP
 159 Why
 160 .BD \(fmbp
 161 and
 162 .BD \(fmsp
 163 instead of
 164 .BD .bp
 165 and
 166 .BD .sp ?
 167 The answer is that
 168 .BD .sp
 169 and
 170 .BD .bp ,
 171 like several other commands,
 172 cause a
 173 .ul
 174 break
 175 to take place.
 176 That is, all the input text collected but not yet printed
 177 is flushed out as soon as possible,
 178 and the next input line is guaranteed to start
 179 a new line of output.
 180 If we had used
 181 .BD .sp
 182 or
 183 .BD .bp
 184 in the
 185 .BD .NP
 186 macro,
 187 this would cause a break in the middle
 188 of the current output line when a new page is started.
 189 The effect would be to print the left-over part of that line
 190 at the top of the page, followed by the next input line on a new output line.
 191 This is
 192 .ul
 193 not
 194 what we want.
 195 Using
 196 .BD \(fm
 197 instead of
 198 .BD .
 199 for a command
 200 tells
 201 .UL troff
 202 that
 203 no break is to take place _
 204 the output line
 205 currently being filled
 206 should
 207 .ul
 208 not
 209 be forced out before the space or new page.
 210 .PP
 211 The list of commands that cause a break
 212 is short and natural:
 213 .P1
 214 ^bp   ^br   ^ce   ^fi   ^nf   ^sp   ^in   ^ti
 215 .P2
 216 All others cause
 217 .ul
 218 no
 219 break,
 220 regardless of whether you use a
 221 .BD .
 222 or a
 223 .BD \(fm .
 224 If you really need a break, add a
 225 .BD .br
 226 command at the appropriate place.
 227 .PP
 228 One other thing to beware of _
 229 if you're changing fonts or point sizes a lot,
 230 you may find that
 231 if you cross a page boundary
 232 in an unexpected font or size,
 233 your titles come out in that size and font
 234 instead of what you intended.
 235 Furthermore, the length of a title is independent of the current line length,
 236 so titles will come out at the default length of 6.5 inches
 237 unless you change it,
 238 which is done with the
 239 .BD .lt
 240 command.
 241 .PP
 242 There are several ways to fix the problems of point sizes
 243 and fonts in titles.
 244 For the simplest applications, we can change
 245 .BD .NP
 246 to set the proper size and font for the title,
 247 then restore the previous values, like this:
 248 .P1 2
 249 .ta .8i
 250 ^de NP
 251 \(fmbp
 252 \(fmsp 0.5i
 253 ^ft R   \e" set title font to roman
 254 ^ps 10  \e" and size to 10 point
 255 ^lt 6i  \e" and length to 6 inches
 256 ^tl 'left'center'right'
 257 ^ps     \e" revert to previous size
 258 ^ft P   \e" and to previous font
 259 \(fmsp 0.3i
 260 ^^
 261 .P2
 262 .PP
 263 This version of
 264 .BD .NP
 265 does
 266 .ul
 267 not
 268 work if the fields in the
 269 .BD .tl
 270 command contain size or font changes.
 271 To cope with that
 272 requires
 273 .UL troff 's
 274 `environment' mechanism,
 275 which we will discuss in Section 13.
 276 .PP
 277 To get a footer at the bottom of a page,
 278 you can modify
 279 .BD .NP
 280 so it does
 281 some processing before
 282 the
 283 .BD \(fmbp
 284 command,
 285 or split the job into a footer macro invoked
 286 at the bottom margin and a header macro invoked
 287 at the top of the page.
 288 These variations are left as exercises.
 289 .WS
 290 .PP
 291 Output page numbers are computed automatically
 292 as each page is produced (starting at 1),
 293 but no numbers are printed unless you ask for them explicitly.
 294 To get page numbers printed,
 295 include the character
 296 .BD %
 297 in the
 298 .BD .tl
 299 line at
 300 the position where you want the number to appear.
 301 For example
 302 .P1
 303 ^tl ''- % -''
 304 .P2
 305 centers the page number inside hyphens, as on this page.
 306 You can set the page number at any time
 307 with either
 308 .BD .bp\ n ,
 309 which immediately starts a new page numbered
 310 .BD n ,
 311 or with
 312 .BD .pn\ n ,
 313 which sets the page number for the next page
 314 but doesn't cause a skip to the new page.
 315 Again,
 316 .BD .bp\ +n
 317 sets the page number to
 318 .BD n
 319 more than its current value;
 320 .BD .bp
 321 means
 322 .BD .bp\ +1 .