Skip to main content

Ralsina.Me — Roberto Alsina's website

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

I wrote Lin­ux/U­nix ap­pli­ca­tions for ten years be­fore I wrote my first man page.

I used all the ex­cus­es:

  • My app has in­­ter­ac­­tive help

  • My app is for pri­­vate use

  • Some­one will write it even­­tu­al­­ly

But of course there are on­ly two rea­sons not to write man pages.

  • You think the man pages are ob­­so­lete.

This is what the FSF thinks. So, they give you in­fo pages. And they put, at the bot­tom of each man­page some warn­ing about how that may look like the doc­s, but the re­al docs are the in­fo pages.

Then they don't pro­vide a de­cent in­fo read­er out­side of emac­s. But hey, who cares. On KDE, just use a in­fo: URL.

  • You hate writ­ing man pages.

Which is per­fect­ly un­der­stand­able, since this is how a man page looks like (and yes, I know it's spe­cial­ly ug­ly ex­am­ple):

.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 pos­si­ble that for some man pages you need to write such a thing.

But for the av­er­age pro­gram? Just take some­thing like tx­t2­man and be hap­py.

I wrote man pages for each of my qmail-spp plug­ins in a few min­utes. Al­though they prob­a­bly are lack­ing in their man-­pa­ge­ness in mat­ters 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 rea­son why your pro­gram, be it KDE-based or not, should not have such a thing.


Contents © 2000-2024 Roberto Alsina