>Someone working in a shell may or may not have quick and easy access to
>a web browser. Even if they do, searching, and cutting and pasting
>examples is much harder, since at the very least, you have to switch
>apps out of your shell and back. That probably involves touching the
>rodent for most people too.

FWIW, I spend most of my time in a shell (with the display in text
mode, no less), never touch the mouse, frequently look at current
Netpbm program manuals, and cut and paste from them about as easily as
when I use traditional man.  I can barely tell the difference between
doing this for Netpbm and doing it for conventional Unix programs,
except that the Netpbm stuff is in color and the other stuff isn't.

As others have noted, there is a cost to setting a system up to work
that way.  But for me, it's a clear win.  I don't just do Netpbm this
way; I now use the HTML documentation for all programs that have it,
even where they also have nroff.

This has come up about a dozen times since I chose to stop offering
nroff updates to the world, and every time I get the distinct
impression that people are fighting against imaginary chains.  I've
been trying to address that with better communication about the
documentation options (there are tons of them, and only the laziest of
them all involves the "sorry, no man page here" man page), and
satisfaction has gone up quite a bit.  But yes, I realize large
numbers of people actually aren't getting what they want from me, all
misunderstandings aside.

>_no one_ likes the current state of the NetPBM docs.

And yet, no one is willing to work into changing it.  I for one am
willing to put a little work into it, but not as much as the proposals
I've heard would require.

This discussion is timely, because Eric Raymond has recently offered
to help and, unlike a half dozen false starts over the years, he
actually seems to be coming through with something.  I doubt it will
satisfy everyone -- Eric's take on the ideal direction for Unix
documentation isn't the 1980s man page method either.  But it looks
like he has something that can be used with very little effort to
create decent nroff out of the stuff I write for the non-nroff people.


BTW, if anyone has any idea how to make the snooty "go to this URL"
man pages less so, I'd love to fix it.  I don't want to offend anyone;
I just want to give information.  I did try it once _without_ the
paragraph that says there are other ways to install documentation;
that was worse.  People don't read installation instructions.  They
don't find out until they type 'man' that current Netpbm doesn't come
with the Unix documentation they're used to.

-- 
Bryan Henderson                                    Phone 408-621-2000
San Jose, California