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?

This question appears to be too broad. It has only succeeded in attracting a bunch of link-only answers and a few unsupported opinions. — 200_success, Oct 15 '14 at 08:57

Dennis Williamson · Accepted Answer · 2013-09-04T10:45:05.370

13

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

A couple of useful tools:

edited Sep 04 '13 at 10:45

answered Feb 04 '10 at 13:12

Dennis Williamson

60,515
14
113
148

score 6 · Answer 2 · answered Feb 04 '10 at 14:15

6

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.

answered Feb 04 '10 at 14:15

Tobu

4,367
1
23
31

"dsl" == "domain specific language"? – Dennis Williamson Feb 04 '10 at 16:23
yes (da. si. 15 chars.) – Tobu Feb 04 '10 at 16:46
1

Another good option is [ronn](http://rtomayko.github.io/ronn/ronn.1.html), which reads the more-widely-used Markdown text markup language. – poolie Aug 10 '13 at 06:07

score 5 · Answer 3 · edited Oct 15 '14 at 07:55

5

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/

edited Oct 15 '14 at 07:55

Igor

103
2

answered Nov 04 '11 at 03:51

Nathan Osman

2,705
7
31
46

4

It'd be helpful if you could at least summarize the article here -- links alone are worthless once the linked page inevitably moves or disappears. – Caleb Jun 26 '13 at 16:09
I do not agree with Caleb. This is the web. The web is based on links, and stackexchange does not carry any special exception to this. Copying content is counterproductive. Whatever bad thing can happen to *that* page or document can also happen to *this* one. We cannot hoard scraped copies of all content just because the rest of the web might disappear. (Leave that job to sites like the wayback machine). – Kaz Oct 09 '13 at 21:23
Kaz, you may not agree, but Caleb's comment is definitely ServerFault best-practice. – MadHatter Oct 15 '14 at 08:03

score 2 · Answer 4 · answered Feb 04 '10 at 09:49

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

score 2 · Answer 5 · answered Oct 06 '13 at 19:08

2

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

answered Oct 06 '13 at 19:08

Bruno Polaco

345
2
9

How do I write man pages?

5 Answers5