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 and 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 a one-line description.
.SH NAME foo-bar \- foos the template foo-what-bar
Typical mistakes regarding 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.
To describe options or files it’s usually useful to make use of the
.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\%https://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 <\&firstname.lastname@example.org\&>