Tuesday, September 15, 2009

Writing manual pages in GROFF (1)

I always wanted to write a short howto for Debian package maintainers, how to write a manual page in GROFF. This is useful for short documents (for longer documents, docbook/docbook-xsl can be a good choice). I already have written some parts. However, here is the first part of hints. More might follow later.

The delimiter in the NAME section

The name section is (probably) the only place, where exactly one hypen-minus \- must appear. The hyphen-minus is the delimiter between the command name and one-line description.

foo-bar \- foos the template foo-what-bar

Typical mistakes regarding paragraphs

Using a .PP macro directly following a .SH or .SS macro is useless. This macro should be used between paragraphs:

The program follows the usual GNU command line syntax, with long options starting with
two dashes (`\-').
A summary of options is included below.

Options/File descriptions

To describe options or files it's usually useful to make use of the .TP macro.

.B \-f, \-\-force
Force the execution of the specified command.
.I ~/.foobar
Per user configuration file.

To create more than one intended paragraph the .IP macro can be used.

.B \-f, \-\-force
Force the execution of the specified command.
This option has no effect in conjunction with \fB\-\-foo\fP.

Avoid hyphenation in URLs/URIs/paths

Usually we don't want URLs or URIs to be hyphenated. This can be done using the \% sequence. Typical examples:

A short tutorial is available online at \fI\%http://foo.tld/some/path/here/manual.html\fP.
On a Debian system the complete text of the GNU General Public License
version 2 can be found in the file \fI\%/usr/share/common-licenses/GPL\-2\fP.

Referencing persons and their mail address

The common markup is to write the person name in bold letters and the mail address in roman letters is put into angle brackets. It's usually a good idea to mark where the mail address starts and ends. We can use the \& sequence as shown in the following example:

\fBDaniel Leidert\fP <\&daniel.leidert@wgdd.de\&>