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
.ll \\n(LLu
.in \\n()Ru+\\n(INu+\\n()Iu
.ti \\n(INu
.ie !\\n()Iu+\\n()Ru-\w^G\\*(]X^Gu-3p \{\\*(]X
.el \\*(]X\h^G|\\n()Iu+\\n()Ru^G\c

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):




  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.

The fax thing

  • Wrote a whole queu­ing suite for efax. It kin­­da work­s, but not re­al­­ly, be­­cause it's not test­ed at al­l.

  • Rewrote the web app to work with said suite in­­stead of mget­­ty+send­­fax

  • Added sta­­tus and sent pages

  • Im­­ple­­men­t­ed I18N for the web app

Next step: spend­ing some ac­tu­al cents send­ing and re­ceiv­ing fax­es from my home phone line to the guy across the street.

What will hap­pen: I need to do lots of oth­er things, so I will shelve it for a week or so.

Rethinking my fax solution

I de­cid­ed to re­do most of it, be­cause I think I fig­ured out a bet­ter way.

  1. Use efax in­­stead of mget­­ty+send­­fax

Af­ter al­l, efax works with my mo­dem and send­fax does­n't ;-)

  1. Write a gen­er­ic spool­ing thin­ga­­ma­jig for efax (this is easy)

  2. Re­write print­­­fax.­­pl in a sim­­pler way (done)

  3. Sim­­pli­­fy the win­­dows side.

For­get about a Qt ap­p. All that's need­ed is a prog­gie that lis­tens on a port, ac­cepts con­nec­tion­s. The con­nec­tion gives it a URL. It launch­es the de­fault brows­er with that URL.

If any­one read­ing this can write that pro­gram, I would re­al­ly like it. Use VB, use .NET, use Java, I don't care.

  1. Use the web app as the on­­ly in­­ter­­face.

What's miss­ing yet:

  • Writ­ing the queu­ing pro­­gram (should use same for­­mat as mget­­ty+send­­fax's)

  • The win­­dows "clien­t"

  • Mi­nor tweaks to the web app ( ba­si­­cal­­ly a form for the send­ing data)

And that's it.

Oth­er than the win­dows thing, it's about a day's work.

FaxWeb is done

FaxWe­b, a web fron­tend for mget­ty+send­fax is fin­ished. It work­s. It's prob­a­bly close to bugfree ;-)

The miss­ing piece is a nicer reim­ple­men­ta­tion of re­spond (and this one will be cross-­plat­for­m, too) us­ing PyQt, which is 50% done.

I am on­ly miss­ing how to im­ple­ment por­ta­ble systray icon­s. On Mac they make no sense, on Lin­ux I have it work­ing, on Win­dows I have no idea.

Here's the sim­ple in­ter­face for faxwe­b:

It even has a lit­tle AJAXy "the page does­n't reload" niceties cour­tesy of MochiK­it!

Al­so from MochiK­it, the nicer, round­ed look&feel. Com­pare to this old­er, ugli­er one:

I know the new one is not good, ei­ther, but I have de­cid­ed that since I can't aim for awe­some, I should aim for ad­e­quate, and set­tle for bor­ing and harm­less.

Of course, if any CSS/X­HTML gu­ru vol­un­teers for a makeover, I'd be very hap­py, since I use the same CSS ev­ery­where (even on parts of this blog ;-).

All in al­l, a plea­sure to write this thing, thanks to Cher­ryPy!

Open Source Remix

One more thing to love about Open Source/Free Soft­ware:

Maybe each screw does­n't work ex­act­ly as you wan­t. But you can hit them with a big enough ham­mer. And if you have a big enough ham­mer, ev­ery screw is a nail.

Mget­ty+send­fax sucks a lit­tle in some ar­eas. It sup­ports no class1 fax­es (ok, it may do if you re­build with a switch it says does­n't re­al­ly work).

Efax sucks a lit­tle in some ar­eas. It has no spool­ing mech­a­nis­m. It has no way at all to be used de­cent­ly from win­dows clients.

So, remix them!

Take efax's efax com­mand (the one that ac­tu­al­ly sends the fax­es), and mget­ty+send­fax's send­fax com­mand.

They are quite sim­i­lar. So, write a tiny shell wrap­per that makes efax look like send­fax.

And Voilá. Mget­ty+e­fax, which works on class1 fax/­modems ;-)

The wrap­per it­self is left as an ex­er­cise for the read­er.

Contents © 2000-2022 Roberto Alsina