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!

About these ads

4 Comments

Filed under Uncategorized

4 responses to “pod2man, a great way to write Unix man pages

  1. Alastair

    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.

    http://www.methods.co.nz/asciidoc

    Alastair

    • rich

      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.

  2. Pingback: Man page for transmision-remote-cli « Yevlempy’s Blog

  3. Pingback: WTFM (Write the Fine Manual) with Pod2man text-converter | Linux Tidbits

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s