groff is a document formatting system relying on a typesetting concept named roff. It offers extensions and macros to typeset the traditional man page format.

From the roff concept derive many utilities such as troff, nroff, ditroff and namely groff, which features everything roff does, This post is an overview of the syntax that has to be used to format online manual pages.

1 How Do I Render My Manual?

Say you wrote your manual page in a file called mycommand.1 (1 standing for “section one”). You can do either man ./mycommand.1 or make your manual available system-wide by copying it deep into /usr/share/man/man1 (because your wrote a .1 kind of manual). It will thereafter be available with a firm man yourcommand.

2 Manual Header (and Footer)

Let's start right away with the very beginning of the file:

.TH "Your command" 1 "October 2005" "Your command" "User Commands"

With such a line, the formatted title header of the manual will have Your command(1) on the top right and left of the page, User Commands in the middle. The footer will have again Your command(1) on the bottom right and left; the middle will hold October 2005. You understood that the (1) next to Your commands is the section number. More generally:

.TH title section [extra1] [extra2] [extra3]

3 Line Breaks and Paragraphs

To break a line, simply use .br To create a new paragraph, use .LP, .PP or .P which are all synonyms. This will break a line and make a vertical space below it.

4 Unnumbered (Sub)sections

Traditionally, this goes:

.SH NAME OF THE SECTION

... for a section header. Secondary sections are also available with .SS.

5 Font Styles

You can typeset text with bold or italic styles (which respectively may map to blue and magenta, for instance, if the terminal can't do better). Two ways to handle this:

• A natural way is to use \fB (bold), \fI (italic) or \fR (roman, i.e. normal plain style). The style will be used until you change it. Example:

  This is some roman text and \fB here comes some bold that I switch
  into \fI some italic and then \fR back to roman.

  ... would produce:

  This is some roman text and here comes some bold that I switch into some italic and then back to roman.

• A more technical way would, unlike the previous one, not apply the style until you change it but until the line ends. In addition to this, the markup must be written at the beginning of a line to work. To get a bold line, use .B and .I for italic. An interesting trick happens when using either .BI, .IB, .RI, .IR, .BR or .RB. They all alternate two styles; for instance, .BI alternates bold and italic. Space acts as a delimiter, so you must control styles with double quotes (have a careful look at the spaces near the quotes):

  .BI␣"This is bold "␣"and this is italic..."

6 Indents and Lists

Suppose you want to list the options of your command with an indented paragraph describing their purpose next to them. You'd typically write:

.TP 15
.B -o
Specifies the output file. But more notably illustrates the use of the TP
markup for the groff typesetting system and blah, blah, blah, ...

.TP
.B -t
Here comes another list item.

We used .TP here, standing for tabulated paragraph. The 15 specifies how far the indent goes. If you do not mention this, it will take the last value given to .TP, .IP or .HP. Let's make an itemized paragraph:

.IP \(bu 4
This is my first itemized line...

This produces a list with a bullet (\(bu – see more Special Characters) as designator. The 4 tells how much to indent and behaves the same way .TP does if it is not mentioned. Lastly, a hanging paragraph:

.HP 15
And here comes some sample text with some nonsense in it.

Here, all the lines are indented 15 units except for the first one. If the indent value is not specified, the same rule described above applies.

7 Special Characters

A complete list of these is available in man groff_man. They are given as \[xx] but must be written \(xx.

8 References

A man man lead me on my way to the understanding of manual pages formatting. The SEE ALSO section took me to the manuals of groff. Then the section regarding man under Macro Packages suggested a glance at the groff_man manual, explaining properly the main aspects of the syntax.

Besides, I read the source of the ls manual pages from /usr/share/man (which was automatically generated by the help2man utility), which taught me a couple of other handy syntaxes.

Nowadays, you may be interested in writing manual pages in Markdown instead, wielding the power of Pandoc.