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.
.SH NAME 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:
.SH OPTIONS The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-'). .PP 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.
.SH OPTIONS .TP .B \-f, \-\-force Force the execution of the specified command.
.SH FILES .TP .I ~/.foobar Per user configuration file.
To create more than one intended paragraph the .IP macro can be used.
.TP .B \-f, \-\-force Force the execution of the specified command. .IP 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\&>
