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:
.\"(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:
completes formatting and forces output of any pending line currently in process
creates vertical prespace for the paragraph to follow by the value in the #PARSKIP variable
controls orphans by keeping a minimum of #ORPHANS lines together
temporarily indents the first line of the paragraph by the value in the #PARINDENT variable
.<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.)
|Using Salt Stack and Vagrant for Drupal Development||May 20, 2013|
|Making Linux and Android Get Along (It's Not as Hard as It Sounds)||May 16, 2013|
|Drupal Is a Framework: Why Everyone Needs to Understand This||May 15, 2013|
|Home, My Backup Data Center||May 13, 2013|
|Non-Linux FOSS: Seashore||May 10, 2013|
|Trying to Tame the Tablet||May 08, 2013|
- Using Salt Stack and Vagrant for Drupal Development
- Making Linux and Android Get Along (It's Not as Hard as It Sounds)
- New Products
- Validate an E-Mail Address with PHP, the Right Way
- Drupal Is a Framework: Why Everyone Needs to Understand This
- A Topic for Discussion - Open Source Feature-Richness?
- Home, My Backup Data Center
- New Products
- RSS Feeds
- New Products
- I like your topic on android
28 min 3 sec ago
- Reply to comment | Linux Journal
49 min 13 sec ago
- This is the easiest tutorial
7 hours 3 min ago
- Ahh, the Koolaid.
12 hours 42 min ago
- git-annex assistant
18 hours 41 min ago
- direct cable connection
19 hours 4 min ago
- Agreed on AirDroid. With my
19 hours 14 min ago
- I just learned this
19 hours 18 min ago
19 hours 48 min ago
- not living upto the mobile revolution
22 hours 40 min ago
Enter to Win an Adafruit Prototyping Pi Plate Kit for Raspberry Pi
It's Raspberry Pi month at Linux Journal. Each week in May, Adafruit will be giving away a Pi-related prize to a lucky, randomly drawn LJ reader. Winners will be announced weekly.
Fill out the fields below to enter to win this week's prize-- a Prototyping Pi Plate Kit for Raspberry Pi.
Congratulations to our winners so far:
- 5-8-13, Pi Starter Pack: Jack Davis
- 5-15-13, Pi Model B 512MB RAM: Patrick Dunn
- Next winner announced on 5-21-13!
Free Webinar: Linux Backup and Recovery
Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.
In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.