I write quite a bit of code in Perl, and more in C, OCaml and other strange languages, but for writing man pages there’s one thing I always use: POD.
Although POD comes from a Perl background, you can really use it to document any program. All you need is a “foo.pod” file starting with this template:
=encoding utf8 =head1 NAME foo - Foobar your bazfiles =head1 SYNOPSIS foo [bazfile] =head1 DESCRIPTION Write your description here. Use B<for bold>, I<for italic> and C<for inline code>, and a blank line to separate paragraphs. =head1 SEE ALSO L<bar(1)>, L<baz(5)>
See perlpod for the full markup, but the advantage of POD is the markup is deliberately limited and simple.
As well as turning your POD file into a manpage using pod2man, you can also turn them into web pages. The default look for POD-generated web pages is pretty sucky. Nevertheless with only a tiny bit of styling you can make them look great, which is how I make all the libguestfs web pages. Examples: guestfish(1), guestfs(3).
The only thing I haven’t worked out yet with the web pages is how to get inter-manpage links to work properly.
Nevertheless … POD is great and simple. Use it!
4 responses to “pod2man, a great way to write Unix man pages”
Yes, Perl and POD is great. Very easy.
The next step up the ladder is “asciidoc” which also seems to do a great job converting easy text markup to man pages.
I’ve used asciidoc to write several (well, two) documents, and I’m not convinced. I’m not saying it’s not good, but I don’t think it’s as good for writing Unix man pages specifically. It may be a matter of personal preference, but I didn’t like how asciidoc-generated man pages and HTML pages looked.
I will say though that asciidoc is simple and expressive.
Pingback: Man page for transmision-remote-cli « Yevlempy’s Blog
Pingback: WTFM (Write the Fine Manual) with Pod2man text-converter | Linux Tidbits