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

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 2

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 3

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.