How do I write man pages?

Question

How do I write a man page?

Where can I find a reference of all formatting codes?

Are there any good tutorials on writing man pages?

What is the most convenient way to write a man page? Should I enter it directly in a text editor? Are there WYSIWYG editors? Or should I write it in a different format and then convert?

What rules should a good man page follow?

Answer 1

Here are a few web pages that will help get you started:

• Creating and Formatting Man Pages
• Creating Your Own MAN Page
• Create Your own Man Page
• How to Write a Man Page
• What you need to know to write man pages

A couple of useful tools:

• txt2man
• help2man

Answer 2

There are tools for writing man pages that bypass troff formatting. manpages are a small, well delimited language and easy to target.

Two popular tools are:

• xmltoman, a small and well structured xml language that can generate manpages and html. It is used by Lennart Poettering's projects, syrep and pulseaudio for example.
• asciidoc, used by git for example.

yodl and zoem seem to be other nice formats in this space.

All in all I'd recommend xmltoman because it's a very manpage specific dsl that will guide you closely.

Answer 3

I have written a rather extensive blog article about the topic, which you can find here:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

Answer 4

I do not know of any IDEs or tutorials, but you can start by copying an existing man page and modify it to suit your needs.

For a reference of the groff language with MAN macros (which is what is used by a man page) consult the groff_man man page, or read it online here

Answer 5

Take a look at the ronn project. Its a markdown to man page generator. It can also generate the man pages in html, like this.

I like the idea of writing all my software documentation in one format. Markdown IMO is a good choice