1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
.\" This module is believed to contain source code proprietary to AT&T.
.\" 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
.\"
.\" $FreeBSD$
.NH
Introduction to Macros
.PP
Before we can go much further in
.UL 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:
.P1
^sp
^ti +2m
.P2
Then to save typing, we would like to collapse these into
one shorthand line,
a
.UL troff
`command' like
.P1
^PP
.P2
that would be treated by
.UL troff
exactly as
.P1
^sp
^ti +2m
.P2
.BD .PP
is called a
.ul
macro.
The way we tell
.UL troff
what
.BD .PP
means is to
.ul
define
it with the
.BD .de
command:
.P1
^de PP
^sp
^ti +2m
^^
.P2
The first line names the macro
(we used
.BD .PP ' `
for `paragraph',
and upper case so it wouldn't conflict with
any name that
.UL troff
might
already know about).
The last line
.BD ..
marks the end of the definition.
In between is the text,
which is simply inserted whenever
.UL troff
sees the `command'
or macro call
.P1
^PP
.P2
A macro
can contain any mixture of text and formatting commands.
.PP
The definition of
.BD .PP
has to precede its first use;
undefined macros are simply ignored.
Names are restricted to one or two characters.
.PP
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
.BD .PP
to
something like
.P1
^de PP \e" paragraph macro
^sp 2p
^ti +3m
^ft R
^^
.P2
and the change takes
effect everywhere we used
.BD .PP .
.PP
.BD \e"
is a
.UL 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).
.PP
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:
.P1
^de BS \e" start indented block
^sp
^nf
^in +0.3i
^^
^de BE \e" end indented block
^sp
^fi
^in \(mi0.3i
^^
.P2
Now we can surround text like
.P1
Copy to
John Doe
Richard Roberts
Stanley Smith
.P2
by the commands
.BD .BS
and
.BD .BE ,
and it will come out as it did above.
Notice that we indented by
.BD .in\ +0.3i
instead of
.BD .in\ 0.3i .
This way we can nest our uses of
.BD .BS
and
.BD BE
to get blocks within blocks.
.PP
If later on we decide that the indent
should be 0.5i, then it is only necessary to
change the definitions of
.BD .BS
and
.BD .BE ,
not the whole paper.
|
