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
=head1 SYNOPSIS
program [-o I<optional argument>] positional argument
=head1 DESCRIPTION
Describes what program does in more detail.
-o, --optional
describes what option does
=head1 SEE ALSO
ls(1), write(1)
=head1 AUTHOR
Kaashif
=head1 BUGS
Report bugs to rms@gnu.org
As you can see, "=head1" denotes a top level header. This is all we really need for writing a simple manual page. To convert it to groff, you can use the following command:
$ pod2man my_first_page.pod
And a file called "my_first_page.man" will be created with the appropriate groff markup. It is my opinion that Pod is much better than groff if we're just writing a manual page, and this can be verified if you look at the groff output - it's not very readable unless you know your groff.
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.