2006-05-07 21:00

There is no excuse: your program should have a man page!

I wrote Linux/Unix applications for ten years before I wrote my first man page.

I used all the excuses:

  • My app has interactive help
  • My app is for private use
  • Someone will write it eventually

But of course there are only two reasons not to write man pages.

  • You think the man pages are obsolete.

This is what the FSF thinks. So, they give you info pages. And they put, at the bottom of each manpage some warning about how that may look like the docs, but the real docs are the info pages.

Then they don't provide a decent info reader outside of emacs. But hey, who cares. On KDE, just use a info: URL.

  • You hate writing man pages.

Which is perfectly understandable, since this is how a man page looks like (and yes, I know it's specially ugly example):

.de }1
.ds ]X \&\\*(]B\\
.nr )E 0
.if !"\\$1"" .nr )I \\$1n
.}f
.ll \\n(LLu
.in \\n()Ru+\\n(INu+\\n()Iu
.ti \\n(INu
.ie !\\n()Iu+\\n()Ru-\w^G\\*(]X^Gu-3p \{\\*(]X
.br\}
.el \\*(]X\h^G|\\n()Iu+\\n()Ru^G\c
.}f

And it is even possible that for some man pages you need to write such a thing.

But for the average program? Just take something like txt2man and be happy.

I wrote man pages for each of my qmail-spp plugins in a few minutes. Although they probably are lacking in their man-pageness in matters of style, they are ok.

And they are not hard to write at all (full):

NAME

  authchecks

DESCRIPTION

  This plugin is meant to be used on the AUTH command and does two things:

  1. Logs the user (see LOGGING)

  2. If the user is authenticated, it sets QMAILQUEUE "/var/qmail/bin/simscan-nospam",
  which is probably not what you want, but is what I use right now ;-)

And there is no reason why your program, be it KDE-based or not, should not have such a thing.

Comments

Comments powered by Disqus

Contents © 2000-2019 Roberto Alsina