Subject: Re: NetPBM man pages are arrogant, infuriating, nonfunctional. consider downgrading package.
To: None <carton@Ivy.NET,>
From: Bryan Henderson <>
List: tech-pkg
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
  of links.

- 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