[oclug]manpage advocacy

[Michael P. Soulier]

On 26/03/03 David F. Skoll did speaketh:

> <rant>
> XML is a misdesigned-by-committee mess.  Have you ever tried to write
> real documentaion in XML using a plain old text editor?  I don't envy
> you.

    I do DocBook in Vim now and then, and I don't use any macros to help me.
It's not really designed to be author-friendly. I prefer LaTeX in the end
really. DocBook was actually written originally as a way of producing multiple
output forms, including print, html and troff for manpages. I'm in favour of
that, but it's too much. Perl's POD approach is much better, once combined
with pod2man, you don't even need to know troff. 

> Why muck about with XML when the Perl community already has the right
> idea?  Man pages are part of the Perl modules; you write them in POD
> (which is readable even without any formatting tool), and you get
> nicely-generated, nicely-categorized man pages.

    Ah. See above. :) Yes, I like POD. 

> Nice in concept, but let's talk about reality.  Commercial UNIXes
> have decent man pages.  FreeBSD has decent man pages.  Linux has
> spotty man pages.  GNOME and KDE have no man pages to speak of.  That
> means if I want to run GNOME or KDE on Linux, I need to read man pages
> *and* KDE's help system *and* GNOME's help system *and* the GNU
> `info' system...

    Yes, this is my point exactly. I should be able to glean documentation on
damn-near anything, remotely in a simple terminal. 

> As for content-sensitive help, I find nothing beats "apropos"... unless
> you're on a system without decent man pages.
> 
> I would much rather have well-written manuals than flashy 21st-century
> ones.  Hell, if I really need to learn something, I use a book, which
> is probably 16th-century technology.

    There's room for improvement in apropos too. I find I often get a lot of
hits that don't really apply. Options for scanning the entire page for
keywords, and not just the headers, would really help. 
    And yes, just because something is old doesn't mean that there's anything
wrong with it. That is an elitist, useless attitude. Change something if it
needs changing, but if it ain't broke...

    Mike

-- 
Michael P. Soulier <msoulier at digitaltorque.ca>, GnuPG pub key: 5BC8BE08
"...the word HACK is used as a verb to indicate a massive amount
of nerd-like effort."  -Harley Hahn, A Student's Guide to Unix
HTML Email Considered Harmful: http://expita.com/nomime.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://tux.oclug.on.ca/pipermail/oclug/attachments/20030326/a58fa152/attachment.bin