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