Is there a specification for the format used by man pages?

Question

I would like to parse man pages into a more structure form, but I'm unable to find a proper specification for the data format under use by man pages. Should I be looking for troff or nroff or groff or something else? groff(7) says

The groff system has all features of the classical roff, but adds many extensions.

Are these extensions the various preprocessors like tbl or something else?

So far I've found the following resources:

• troff.org - This has historical notes and some tutorials, and some dead links.

• roff(7) (OpenBSD, Linux) - Doesn't really have a specification, only a brief overview and bunch of history.

• man-pages(7) (Linux) - This provides guidelines about sections in man pages (which is useful), but it doesn't talk about the data format.

• A Typesetter-independent TROFF and Troff User's Manual - these are fairly old, so I can't really judge what the differences are between the troff in those papers and in practice.

Is there a clear specification somewhere for the exact format under use by man pages?

Answer 1

There is no single source form.

Some people write manual pages in roff. Almost no-one uses raw roff; but people write manual pages using various sets of roff macros, such as an or mdoc. These macro sets differ extensively from one another. But many people nowadays do not write manual pages in roff at all.

People can also author manual pages in Docbook XML, perl's POD, T_EΧ, T_eχinfo, ASCIIDOC, plain HTML, or other systems.

Some of these, most notably Docbook XML, are quite structured in the first place and the conversion to roff is lossy. You are better off ignoring roff if they are the source, and using the actual source forms directly, which will likely already have the structured form that you are looking for.

Indeed, there is no roff intermediary when viewing some of these forms. (All of the aforementioned can be converted directly to formats such as HTML without going through an intermediate roff stage. Manual pages authored in Docbook XML, again notably, can even be viewed directly as the XML using several WWW browsers, without an HTML intermediary, if Docbook CSS or similar is employed.)

Many of these source forms are themselves standardized, but there is no single universal source form for manual pages.

Examples

• The Docbook XML source of the manual page for systemd's halt command
• The T_eχinfo source of the manual page for GNU gdb
• The POD source of the manual page for POD-Readme
• The ASCIIDOC source of the manual page for the asciidoc command

Answer 2

Yup. Think like HTML... but pre-HTML. Basically a bunch of typesetting macros for groff ...

First, there are some commonly agreed on sections - of course you can add more...

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
BUGS
AUTHOR
SEE ALSO

And for each (and everywhere else) you use the groff typesetting macro syntax.

For example, a TITLE HEADER can be done like so -

.TH [name of program] [section number] [center footer] [left footer] [center header]

Or a SECTION HEADER -

.SH [section name]

And of course, you can bold, italic, underline, etc -

.B = bold
.BI = bold alternating italic
.BR = bold alternating Roman
.I = italic
.IB = italic alternating bold
.IR = italic alternating Roman
.RB = Roman alternating bold
.RI = Roman alternating italic 

And you can even make comments in your text file -

." This is a comment

And then things like paragraphing (like the <p></p> html tag set) with .PP

Don't forget to name the file appropriately, and then gzip it when done.

This info (and more) is from http://www.linuxhowtos.org/System/creatingman.htm