kaashif's blog

Programming, software freedom and Unix


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 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.