Typesetting with groff Macros

Listing 1 demonstrates an obligatory “Hello, world!” program implemented with groff macros. In it we can see that groff offers commands for creating user-defined variables of type number and string, and that these can be used within the macros we develop. Note the addition of more command aliases and number registers in this more practical example:

Listing 1. “Hello World Program”

.\"(this is a traditional troff comment).\"
\# (this is a gnu and improved comment!)
\#
\# define additional aliases:
.ALIAS   BRKFILL     br
.ALIAS   SKIP        sp
.ALIAS   NEED        ne
.ALIAS   TINDENT     ti
\#
\# define number registers:
.NUMBER  #PARINDENT  0.5i
.NUMBER  #PARSKIP    0.8v
.NUMBER  #ORPHANS    2
\#
\# define user interface
\# tag for a new paragraph:
.MACRO  <p>   __END__
.  BRKFILL \" break and spread pending output
.  SKIP    \\n[#PARSKIP]u       \" paragraph prespace
.  NEED    \\n[#ORPHANS]v-1v+1u \" orphan control
.  TINDENT \\n[#PARINDENT]u     \" indent 1st line
.__END__

As may be clear from our selection of alias names and in-line comments, the macro definition of <p> provides a markup tag for a new paragraph with the following features when formatted by groff:

Usage of the new paragraph macro in a document file would look like:

.<p>This is my new paragraph. Notice how groff
lets me create HTML-like tags.
.<p>
Here is my next paragraph...

Although this example is simplified from a final implementation, it demonstrates how we can export a user interface built up from basic groff macros and create structured markup tags for our documents. Notice also that another macro file could alternatively define the <p> macro when publishing the same document to the Web:

.MACRO    <p>    __END__<p>
.__END__

A macro name can be any string of any characters, and groff is case sensitive. In our example named <p>, the angle brackets have no special meaning; they are just part of the macro name we have devised to simulate an HTML-like tag.

We should, however, expand the definition of the macro given above. Recall that the .MACRO command itself is an alias we have given to the raw groff request .de. This command accepts two arguments: the first is the name of the macro (here <p>); the second is an optional termination label (here END). Any arbitrary string may be used to mark the end of a macro definition. We use END in these examples, but one could also use <<< or *****, or any other convention that helps to improve the readability of a collection of macro commands in a file.

The macro also demonstrates different forms of comments. The first form (.\“) with a period in the first column actually functions as an undefined request, with the effect that the entire line is silently ignored. The second form (\#) is a GNU groff extension and ignores everything on the line beyond the comment including the new_line. The third form (\") can be used on the same line as groff commands and ignores everything on the line beyond the comment, not including the new_line. If one were to use this last form of comment (\") on a line by itself, and without a period in the first column, groff would interpret the new_line and generally convert it into a space or new line (depending on fill mode) in the output. Unintended spaces and blank lines can be a source of misery and anguish, especially to the novice macro developer trying to figure out why extra space is creeping into the document. Generally, the GNU form of comment is preferable for single-line comments, while the traditional form is required for comments following on the same line as groff commands.

Finally, you probably noticed that while groff command syntax requires a period in the first column, the name of the command itself may be indented to any level on the same line. By using logically indented source code, together with comments, you will greatly improve the readability of the code for yourself and others in future generations of groff users to come. (The preceding comment is a public service announcement as required by the Surgeon General of Computer Science and is based on extensive scientific evidence that such conventions will prolong the life expectancy of your source code.)