[unix-history] / usr / doc / trofftut / tt08

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