# kaashif's blog

Programming, software freedom and Unix

## Writing Unix manual pages

### 2014-01-08

There are a few very important things that everyone involved in software (particularly free software) can do to help out. The most important is to file detailed and helpful bug reports, so the developers working on your favourite program can get the problem fixed. Since it is not very hard to write a bug report, and projects generally have their own bug report guidelines, I won't talk about that. The second most important thing you can do is writing guides, manuals and the like, in order to get more people using the software without headaches. Readily-available documentation not only saves the users time, but helps the developers to spread their software, since it might develop a reputation for being easy to learn to use, or any number of other things.

I'm a bit biased, since I'm a Unix user, but I think that a good place to start is to write manual pages. There have been a few times when I was trying to do something with a program, I had trouble, typed man program, saw that there was no manual page, and installed another program, one that did not force me to rely on guides written on blogs and such, which may not be accurate or up to

usually write one in Pod, compile it into groff, and submit it to the devs upstream. It's not hard, in fact, it's very easy.

## What does a manual page look like?

Here is the manual page for write(1), a pretty vanilla Unix command.

WRITE(1)                  BSD General Commands Manual                WRITE(1)

NAME
write -- send a message to another user

SYNOPSIS
write user [tty]

DESCRIPTION
The write utility allows you to communicate with other users, by copying
lines from your terminal to theirs.

When you run the write command, the user you are writing to gets a mes-
sage of the form:

...


Most man pages follow the convention of "NAME", "SYNOPSIS", "DESCRIPTION", "SEE ALSO", and optionally "AUTHOR" and "BUGS".

## What does this look like in Pod?

Pod is very simple and was designed to be used for Perl. Despite that, it is very readable and it should be possible to get the gist of what this Pod markup means just by looking at it:

   =head1 NAME
program -- does something

program [-o I<optional argument>] positional argument

Describes what program does in more detail.

-o, --optional
describes what option does

ls(1), write(1)

Kaashif


\$ pod2man my_first_page.pod

You might not always want to create manual pages, you can use pod2html and pod2latex to create web pages and LaTeX source which can be put into another, longer document. In fact, I could have written this post in Pod (but I didn't), it's very powerful, considering its simplicity.