Writing Unix manual pages
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 Date: date. If a program does end up being useful to me, but has no manual page, IT00:00:00 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 firstname.lastname@example.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
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.