Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Ted Harding]

On 03-May-04 Pete Phillips wrote:
> 
> With all due respect to Eric Raymond, I would like to say a big thank
> you to big man pages.  At least you know you can find the information
> you need, and as long as it is being pumped through a decent pager
> (less is more) you can search and navigate to your hearts content.

Agreed!

> The good thing is that it keeps everything simple - 'man zshall' on
> *any* workstation in our lab and you can find out just about anything
> you need on zsh.  All it relies on is a complete man/groff
> installation. I get really annoyed when I fire up a man page and it
> redirects me to a bl***y info page. Not only do I have to run another
> command, I also have to use info. Now *that* is way too complicated to
> navigate - I can never find what I need (yes I know there are search
> options which will search them all). man+less allows me to use vi
> keystrokes to navigate and search. That's all I want. It has served me
> well since System 5.1 and I *DON'T WANT IT CHANGED*.  Ahem. :-)
> 
> I agree that doesn't detract from the need for a useful HOWTO,
> or even an O'Reilly book (try stopping them, anyway!) but please don't
> let man pages be demoted to second class status!  

Like Pete, I don't get on with info at all, and for me the availability
of information about how to use commands etc. has dwindled since GNU
moved to info rather than man, for increasingly many commands.

Maybe this is a "generation" thing. People who dug their way into
UNIX in the old days developed a facility for mentally linking the
cross-references implicit in the old-style man pages, and working
out the implications. A classic UNIX man page is a case-study in
conciseness and logic, managing to be complete at the same time.

I'm totally with Pete on this one!
Ted.


--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 167 1972
Date: 03-May-04                                       Time: 12:13:31
------------------------------ XFMail ------------------------------