Typesetting with groff Macros

We have shown above that the groff syntax for evaluating a number register with names of arbitrary length is

\n[anyname]

Similarly, the syntax for evaluating other registers is

\*[anyname]    string\f[anyname]    font
\[anyname]     special character

groff only has scalar variables, lacking compound structures or subscripted arrays. But it is possible to combine definitions and numeric variables in such a way as to fake the effects of compound data types. Here, we will demonstrate a “pseudo-array” that may come in handy for your bag of macro tricks.

Consider the following string definitions for days of the week:

.STRING  $DAYNAME1   Sunday.STRING  $DAYNAME2   Monday
\# etcetera
.STRING  $DAYNAME7   Saturday

groff provides a number register representing the current day of the week as a numeric value 1 through 7, and, of course, we alias it again to fit in with our scheme:

.ALIASNR  _DOW    dw

Now, we can initialize a variable with the current dayname using the pseudo-array of strings we defined above as follows:

.STRING  $TODAY  \*[$DAYNAME\n[_DOW]]

Anytime we need the name of the current day in a macro or document, we need only use the string variable $TODAY:

.<p>Thank goodness it's \*[$TODAY].

Human reaction to this message will likely be most favorable when the _DOW variable evaluates to 6.

groff also has an extension that enables the use of looping constructs within macros. Together with pseudo-arrays, this feature gives you considerably more power and flexibility over traditional troff, which only has if/else branching logic. Following the example above, if you needed a macro to create a header for a list of tab-separated columns for each weekday, (Monday through Friday) you might cobble up something like the following:

.ALIAS  TABSET    ta.ALIAS  WHILE     while
.MACRO  <weekdays>    __END__
.  NUMBER  IX  1 1
.  NOFILL
.  TABSET  T  .75iC
.  WHILE  \\n[IX]<6  \{\
        \\*[$DAYNAME\\n+[IX]]\c
.  \}
.  FILL
.__END__

In the example above, the TABSET command makes use of groff's “T” extension for repeating tabs, set here every 3/4 of an inch. The loop test variable, “IX”, demonstrates the auto-increment syntax with a number register (the “+” sign in the \\n+[IX] expression). This has the effect of preincrementing the variable, so the first time through the loop IX will evaluate as 2, printing “Monday” from the pseudo-array $DAYNAME. Finally, the printed line is terminated with the \c escape sequence, to continue output on the current line without inserting the new line that would otherwise be inserted in nofill mode.

groff's implementation of “while loops” includes .break and .continue statements. These give groff more of the flow-of-control facilities of a complete programming language. Although you probably won't be using groff for solving multiple regression problems, groff's while loops do make it easier to write macros for, say, printing columns of address labels on precut forms, without using an external processor.

The basic page layout model for groff is in keeping with groff's minimalism. The only dimensions groff requires are the vertical length of the page, the hard left margin and the horizontal length available for printable lines. Each of these dimensions is set with its own request that we alias below:

.ALIAS    PGLENGTH    pl.ALIAS    PGOFFSET    po
.ALIAS    LNLENGTH    ll

Usually, though, we need a document to have other layout parameters, such as a top and bottom margin, possibly with running headers and/or footers. All these may be configured using groff's trap mechanism in combination with additional parameters and macros for the page transition that we devise.

Let's imagine that we would like a top and bottom margin of one inch for our main body text and a centered page number one-half inch from the bottom of every page. In addition, we want to define these parameters so they will work whether we are using letter, legal or A4 sized paper. The first step is to define our own set of number registers to hold all of our layout parameters:

\# parameters with default settings:.NUMBER    #PAGELENGTH   11.0i
.NUMBER    #PAGEWIDTH     8.5i
.NUMBER    #LEFTMARGIN    1.0i
.NUMBER    #RIGHTMARGIN   1.0i
.NUMBER    #TOPMARGIN     1.0i
.NUMBER    #BOTMARGIN     1.0i
.NUMBER    #FOOTMARGIN    0.5i
\#
\# layout initialization macro:
.MACRO  SET_LAYOUT    __END__
.    PGLENGTH  \\n[#PAGELENGTH]u
.    PGOFFSET  \\n[#LEFTMARGIN]u
.    LNLENGTH \
\\n[#PAGEWIDTH]u-\\n[#LEFTMARGIN]u-\\n[#RIGHTMARGIN]u
.__END__
\#
\# initialize layout with defaults:
.SET_LAYOUT

The next step is to write our page transition macros and put them into position with the trap mechanism. The following snippet demonstrates:

\# some more aliases:.ALIAS  CENTER    ce
.ALIAS  RIGHT     rj
.ALIAS  NEWPAGE   bp
.ALIAS  SETTRAP   wh
\#
\# macro for header:
.MACRO  MYHEADER    __END__
'    SKIP  |\\n[#TOPMARGIN]u
.__END__
\#
\# macro for footer:
.MACRO  MYFOOTER    __END__
'    SKIP  |(\\n[#PAGELENGTH]u -
\\n[#FOOTMARGIN]u)
.    CENTER
\\n[_PAGE]
'    NEWPAGE
.__END__
\#
\# position to invoke header/footer:
.SETTRAP  0                  MYHEADER
.SETTRAP  0-\n[#BOTMARGIN]u  MYFOOTER

The example shows two macros, MYHEADER and MYFOOTER, which define the actions taken at the top of the page (position 0) and at the bottom margin (-1.0i). The syntax in these macros shows the deferred break control character, the apostrophe, ', used with groff commands that would otherwise cause the output to be immediately forced out.

The page layout parameters are defined with default values, but here we will create a user-interface for changing the papersize:

.MACRO  <papersize:>    __END__.    IFELSE  "\\$1"letter"  \{\
.        NUMBER #PAGELENGTH  792p
.        NUMBER #PAGEWIDTH   612p
.    \}
.    ELSE .IFELSE  "\\$1"a4"  \{\
.        NUMBER #PAGELENGTH  842p
.        NUMBER #PAGEWIDTH   595p
.    \}
.    ELSE .IFELSE  "\\$1"legal"  \{\
.        NUMBER #PAGELENGTH  1008p
.        NUMBER #PAGEWIDTH    612p
.    \}
.    ELSE  \{\
.        MESSAGE \
Missing or unrecognized papersize,\
file \\n[_FILE], line \\n[_LINE]
.    \}
.    \" re-initialize layout:
.    SET_LAYOUT
.__END__

The enduser can now set the paper size of the document, which initializes the margins accordingly. Putting together the elements we have looked at so far, we have defined an interface to groff that allows the enduser to create a document that looks like this:

.<papersize:>  a4.<fontsize:>   11.5p
.<parskip:>     0.8v
.<p>
This document is typeset by groff!