Use and redistribution is subject to the Berkeley Software License
Agreement and your Software Agreement with AT&T (Western Electric).
@(#)tt08 8.1 (Berkeley) 6/8/93
Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
Redistributions of source code and documentation must retain the above
copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed or owned by Caldera
International, Inc. Neither the name of Caldera International, Inc.
nor the names of other contributors may be used to endorse or promote
products derived from this software without specific prior written
permission.
USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$FreeBSD: releng/10.2/share/doc/usd/22.trofftut/tt08 96897 2002-05-19 03:37:41Z grog $
Introduction to Macros
Before we can go much further in troff , we need to learn a bit about the macro facility. In its simplest form, a macro is just a shorthand notation quite similar to a string. Suppose we want every paragraph to start in exactly the same way _ with a space and a temporary indent of two ems:
1 ^sp ^ti +2m
2 Then to save typing, we would like to collapse these into one shorthand line, a troff `command' like
1 ^PP
2 that would be treated by troff exactly as
1 ^sp ^ti +2m
2 .PP is called a .ul macro. The way we tell troff what .PP means is to .ul define it with the .de command:
1 ^de PP ^sp ^ti +2m ^^
2 The first line names the macro (we used .PP ' ` for `paragraph', and upper case so it wouldn't conflict with any name that troff might already know about). The last line .. marks the end of the definition. In between is the text, which is simply inserted whenever troff sees the `command' or macro call
1 ^PP
2 A macro can contain any mixture of text and formatting commands.
The definition of .PP has to precede its first use; undefined macros are simply ignored. Names are restricted to one or two characters.
Using macros for commonly occurring sequences of commands is critically important. Not only does it save typing, but it makes later changes much easier. Suppose we decide that the paragraph indent is too small, the vertical space is much too big, and roman font should be forced. Instead of changing the whole document, we need only change the definition of .PP to something like
1 ^de PP \e" paragraph macro ^sp 2p ^ti +3m ^ft R ^^
2 and the change takes effect everywhere we used .PP .
\e" is a troff command that causes the rest of the line to be ignored. We use it here to add comments to the macro definition (a wise idea once definitions get complicated).
As another example of macros, consider these two which start and end a block of offset, unfilled text, like most of the examples in this paper:
1 ^de BS \e" start indented block ^sp ^nf ^in +0.3i ^^ ^de BE \e" end indented block ^sp ^fi ^in -0.3i ^^
2 Now we can surround text like
1 Copy to John Doe Richard Roberts Stanley Smith
2 by the commands .BS and .BE , and it will come out as it did above. Notice that we indented by .in +0.3i instead of .in 0.3i . This way we can nest our uses of .BS and BE to get blocks within blocks.
If later on we decide that the indent should be 0.5i, then it is only necessary to change the definitions of .BS and .BE , not the whole paper.