File: groff.info,  Node: Requests and Macros,  Next: Macro Packages,  Prev: Tabs and Leaders,  Up: Text

5.1.7 Requests and Macros
-------------------------

We have now encountered almost all of the syntax there is in the 'roff'
language, with an exception already noted in passing.  A "request" is an
instruction to the formatter that occurs after a "control character",
which is recognized at the beginning of an input line.  The regular
control character is a dot ('.').  Its counterpart, the "no-break
control character", a neutral apostrophe ('''), suppresses the break
that is implied by some requests.  These characters were chosen because
it is uncommon for lines of text in natural languages to begin with
them.  If you require a formatted period or apostrophe (closing single
quotation mark) where GNU 'troff' is expecting a control character,
prefix the dot or neutral apostrophe with the dummy character escape
sequence, '\&'.

   An input line beginning with a control character is called a "control
line".  Every line of input that is not a control line is a "text
line".(1)  (*note Requests and Macros-Footnote-1::)

   Requests often take "arguments", words (separated from the request
name and each other by spaces) that specify details of the action GNU
'troff' is expected to perform.  If a request is meaningless without
arguments, it is typically ignored.

   GNU 'troff''s requests and escape sequences comprise the control
language of the formatter.  Of key importance are the requests that
define macros.  Macros are invoked like requests, enabling the request
repertoire to be extended or overridden.(2)  (*note Requests and
Macros-Footnote-2::)

   A "macro" can be thought of as an abbreviation you can define for a
collection of control and text lines.  When the macro is "called" by
giving its name after a control character, it is replaced with what it
stands for.  The process of textual replacement is known as
"interpolation".(3)  (*note Requests and Macros-Footnote-3::)
Interpolations are handled as soon as they are recognized, and once
performed, a 'roff' formatter scans the replacement for further
requests, macro calls, and escape sequences.

   In 'roff' systems, the 'de' request defines a macro.(4)  (*note
Requests and Macros-Footnote-4::)

     .de DATE
     2020-11-14
     ..

The foregoing input produces no output by itself; all we have done is
store some information.  Observe the pair of dots that ends the macro
definition.  This is a default; you can specify your own terminator for
the macro definition as the second argument to the 'de' request.

     .de NAME ENDNAME
     Heywood Jabuzzoff
     .ENDNAME

   In fact, the ending marker is itself the name of a macro to be
called, or a request to be invoked, if it is defined at the time its
control line is read.

     .de END
     Big Rip
     ..
     .de START END
     Big Bang
     .END
     .START
         => Big Rip Big Bang

In the foregoing example, "Big Rip" printed before "Big Bang" because
its macro was _called_ first.  Consider what would happen if we dropped
'END' from the '.de START' line and added '..' after '.END'.  Would the
order change?

   Let us consider a more elaborate example.

     .de DATE
     2020-10-05
     ..
     .
     .de BOSS
     D.\& Kruger,
     J.\& Peterman
     ..
     .
     .de NOTICE
     Approved:
     .DATE
     by
     .BOSS
     ..
     .
     Insert tedious regulatory compliance paragraph here.

     .NOTICE

     Insert tedious liability disclaimer paragraph here.

     .NOTICE
         => Insert tedious regulatory compliance paragraph here.
         =>
         => Approved: 2020-10-05 by D. Kruger, J. Peterman
         =>
         => Insert tedious liability disclaimer paragraph here.
         =>
         => Approved: 2020-10-05 by D. Kruger, J. Peterman

The above document started with a series of control lines.  Three macros
were defined, with a 'de' request declaring each macro's name, and the
"body" of the macro starting on the next line and continuing until a
line with two dots ''..'' marked its end.  The text proper began only
after the macros were defined; this is a common pattern.  Only the
'NOTICE' macro was called "directly" by the document; 'DATE' and 'BOSS'
were called only by 'NOTICE' itself.  Escape sequences were used in
'BOSS', two levels of macro interpolation deep.

   The advantage in typing and maintenance economy may not be obvious
from such a short example, but imagine a much longer document with
dozens of such paragraphs, each requiring a notice of managerial
approval.  Consider what must happen if you are in charge of generating
a new version of such a document with a different date, for a different
boss.  With well-chosen macros, you only have to change each datum in
one place.

   In practice, we would probably use strings (*note Strings::) instead
of macros for such simple interpolations; what is important here is to
glimpse the potential of macros and the power of recursive
interpolation.

   We could have defined 'DATE' and 'BOSS' in the opposite order;
perhaps less obviously, we could also have defined them _after_
'NOTICE'.  "Forward references" like this are acceptable because the
body of a macro definition is not (completely) interpreted, but stored
instead (*note Copy Mode::).  While a macro is being defined (or
appended to), requests are not interpreted and macros not interpolated,
whereas some commonly used escape sequences _are_ interpreted.  'roff'
systems also support recursive macro calls, as long as you have a way to
break the recursion (*note Conditionals and Loops::).  Maintainable
'roff' documents tend to arrange macro definitions to minimize forward
references.