Best way to author man pages?

Question

What's the best way to author man pages? Should I write using the standard man macros, or is there some clever package available now that takes some kind of XML-ified source and can output man pages, HTML, ASCII, and what not?

Thanks

Answer 1

For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown like syntax. I am extremely happy with it.

atinout(1) -- Send AT commands to modem, capturing the response
===============================================================

## SYNOPSIS

`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>

## DESCRIPTION

**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...

see the whole page here.

Answer 2

I have previously used the GNU version of nroff called groff to write man pages.

Nice intro article on it here:

http://www.linuxjournal.com/article/1158

Answer 3

Doxygen is what you are looking for. Keep in mind that it is designed to document source code but you could easily adapt it.

It can generate html, pdf, and latex documentation too.

Answer 4

If you are looking at writing once and generating different output formats such as manpages, HTML, plain txt, or even PDF, then docbook should work best.

Answer 5

A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly.