Typesetting with groff Macros

“Reports of troff's death are greatly exaggerated.” —W. Richard Stevens, 1998
Pseudo-Arrays and Real Loops

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.

Page Layout and Traps

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!

______________________

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState