Tag Archives: man page

pod2man, a great way to write Unix man pages

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!

Advertisements

4 Comments

Filed under Uncategorized