Subject: Re: NetPBM man pages are arrogant, infuriating, nonfunctional. consider downgrading package.
To: None <carton@Ivy.NET, firstname.lastname@example.org>
From: Bryan Henderson <email@example.com>
Date: 07/25/2004 02:05:59
Since I, as Sourceforge Netpbm maintainer, was copied on this email, I
guess I would be remiss in not pointing out areas where this user's
experience is not typical. As the email doesn't really invite
argument, I'll try not to argue anything. In the disputed areas,
other readers of the email can do their own investigation and reach
their own conclusions.
- People do successfully install Netpbm so that they type "man
pnmscale" and Pnmscale documentation pops up, even if they are on an
airplane. I agree that there are drawbacks to doing this the way
the Netpbm instructions suggest, and people do use a variety of
- The Pnmscale manual I see doesn't seem to have anything in common
with what the email describes. It does say Pnmscale is obsolete,
but gives all the information a user of an old Netpbm needs to use
it anyway. It does it partly by reference to the Pamscale manual.
No part of the document is 3 pages long; in my browser, the entire
document is 1.5 pages.
- If for some reason you look for the Pnmscale documentation starting
at the introductory page of the Netpbm manual (as opposed to
e.g. the URL in the un-manpage for Pnmscale that is apparently
installed in FreeBSD), many users would take less than 15 minutes to
find it. The first headings on that page are Overview, The Netpbm
Formats, The Netpbm Library, and The Netpbm Programs. The 2nd
paragraph of the latter section is, "Each of these programs has its
own manual, as linked in the directory below." Under the subheading
"Directory" a page below, it says, "Here is a complete list of all
the Netpbm programs" and there is a hyperlink to a page that lists
them one by one, with hyperlinks.
The first hyperlink on that page is "table of contents" and the table
of contents shows all the above mentioned section titles.
Though this page was designed for someone approaching Netpbm for the
first time, the email made me think it's probably common for someone
interested in one particular program to end up there, so I have moved
"The Netpbm Programs" to second place. I think lots of users would
navigate this fairly quickly.
- There aren't any links to other projects in any table of contents.
There is about 5 pages of material at the end of the top page of the
manual that describes alternatives to Netpbm and they contain a lot
- Many users enjoy reading about features they don't have. In many cases,
they find they could use the feature and download a newer Netpbm.
- Nothing in the instructions suggests wgetting an old version of the
manual to use with an old version of Netpbm. Quite the contrary, it
encourages users to use the latest possible documentation because
50% of the changes to the documentation are as applicable to old
Netpbm as they are to current Netpbm (corrections, clarifications,
added information based on user questions).
- I don't find anything in the manual that qualifies as a rant. But
it does contain lots of technical advice, and I would expect it's
not all 100% noncontroversial.
- If the goal of installing a different Netpbm is to make a statement
about my maintainership, then the 1994 package is the way to go --
it's the newest, most complete version without any of my work in it.
But if all you want is classic Unix manpages, then you can use
Sourceforge Netpbm 9.25. It's 8 years newer and has exactly the
same documentation system as the 1994 package. Except there _are_
some man pages that just tell you the program is obsolete. And
unlike the HTML documentation, those pages often don't tell you how
to use the obsolete program anyway.
Some people use the Netpbm 9.25 man pages with current Netpbm code
and go to the HTML stuff only when the 9.25 pages fail them. Netpbm
has strong backward compatibility, so that works.
- Linux people don't have necktie damage. I'm pretty sure no Linux
user has ever worn one.
Bryan Henderson Phone 408-621-2000
San Jose, California