Subject: NetPBM man pages are arrogant, infuriating, nonfunctional. consider downgrading package.
To: None <tech-pkg@netbsd.org>
From: Miles Nordin <carton@Ivy.NET>
List: tech-pkg
Date: 07/24/2004 15:16:51
---
$ pnmscale
pnmscale: With no dimension options, you must supply at least one parameter=
:=20
the scale factor.
$ pnmscale --help
pnmscale: Use 'man pnmscale' for help.
$ man pnmscale
[...]
 Netpbm documentation is kept in HTML
format.

Please refer to <http://netpbm.sourceforge.net/doc//pnmscale.html>.
[...]
Note that making the documentation available this way was a choice of the p=
er-
son who installed Netpbm on this system.   It  is  also  possible  to  inst=
all
Netpbm such that you would simply see the documentation instead of the mess=
age
you are reading now.
---

oh, oh _is_ it?
in /usr/pkg/share/doc/netpbm/USERDOC, i'm told:

---
You can get the same quick access to program documentation with this
HTML setup as with traditional man pages, using the Manweb program.
This works whether you use the www copy or a local copy of the HTML
files.  Manweb is distributed with Netpbm.  With Manweb and Netpbm
installed and configured appropriately (see below), you can type

  man netpbm

and get the top level page of the Netpbm user manual (with hyperlinks to
all the other pages), or

  man netpbm pnmtogif
---

so, ``the person who installed netpbm'' could have chosen to replace
man with netpbm-man, and then the manpages would work?  Is this some
kind of April Fools joke that got checked in by mistake?

but FINE i'll PLAY ALONG, cocksucker.
---
$ manweb pnmscale
Can't open configuration file '/etc/manweb.conf'.  No such file or director=
y at /usr/pkg/bin/manweb line 322.
---

hurrah.  fix that problem and i assure you six more pop up.  such as,
there are no local man pages.  such as, YOU CANT GET LOCAL ``man
pages'', if you can even call them that, because there ARE NO
release-marked html ``man pages''---all documentation for netpbm is
now force-updated -current only.  Oceania is at war with Pacifica.
Oceania was always at war with Pacifica.

What's even less acceptable, is that if I play their little VendorDoc
game and whip out an _actual_ web browser (<cough> on my laptop on the
airplane, right), I'm taken to some gigantic chatty page with links to
a dozen other projects besides netpbm.  I've been surfing the netpbm
man pages for fifteen minutes now, and I still haven't stumbled upon a
list of all 250 netpbm programs linked directly to their ``man''
pages.  It just drones on and on about libraries and modules and
position statements.

Actually I did stumble upon the documentation for pnmscale in some
offhanded comment, ``such as pnmscale or gif2pam.''  It said:

---
   pnmscale was obsoleted by pamscale, introduced with Netpbm 10.20 (January
   2004). pamscale is backward compatible with pnmscale, plus adds many[...]
---

It then goes on for three pages explaining what it means for one
program to be obsoleted by another.  It does not explain how to use
pnmscale, although it says pnmscale is still included.

$ pamscale
ksh: pamscale: not found

uh-huh.  wonderful.

Maybe they mean for me to look at the pamscale documentation?  hmmm I
could try that.  Continuing the scavenger hunt for pnmscale docs:

=46rom USERDOC:
---
you should access it there instead of making a local copy.  This
manual is always up to date.  It is not maintained on a release
schedule like the source code is, but rather updated continuously.
The user manual describes past Netpbm function as well as the present,
so you can use the current manual with old Netpbm code.
---

I do not wish to read about features I don't have.  I do not wish the
pnmscale man page to disappear, be replaced with a web page, have the
web page burried under a bunch of Hot Links Bookmarks on some Home
Page, and then have the web page removed and replaced with a pointer
to a pamscale page, which burdens me with reading documentation for
features I don't have, and then I may or may not find out I don't have
the feature I just read about but not until AFTER I'VE READ THE
PARAGRAPH:

---
[five _PAGES_ of discussion of the 2D discrete fourier transform elided]

   ``Resampling (-filter) was new in Netpbm 10.20 (January 2004).''
---

five...PAGES.

now, I only know from wading through hyperlink spaghetti and taking
careful notes that 10.20 was the same time pnmscale was
superceded-but-not-deleted by pamscale, so probably -filter is not in
pnmscale.  But the man page which is really an HTML page doesn't
mention that, and *I HAD TO READ FIVE PAGES BEFORE I REACHED THAT
STATEMENT*!

I want the manual as released with the code I'm using, no changes
after the fact.  Release your manuals, don't blog them.  it is
*IMPOSSIBLE* for me to get that manual, no matter how many hoops I
jump through, because you cannot (as they suggest) 'wget' an old
version of the manual, one which still has manual pages instead of
links to other non-Netpbm projects featured on the top page, one which
has actual documentation for pnmscale rather than a three-page rant
about why I should switch to Netpam.

This bullcrap does not fly in NetBSD.  tron, would you be opposed to
checking in an old version of netpbm to pkgsrc?  I'd be totally happy
with something unfancy, like a package that conflicts with the current
netpbm package. =20

If you have to use this brokeass version because of a mess of Gnome
dependencies and so on, could the new netpbm maybe silently install
outdated, slightly-incorrect documentation from the 1994 netpbm?  Hard
to believe though it is that such a thing is DTRT, that would actually
be a tremendous improvement, as I've demonstrated.  Or the old netpbm
could prefix every command with 'nb'.  nbpnmscale.  fine.  whatev.

It's just that this new guy who's taking over netpbm is a
motherfucking disaster.  the whole point of 250 tools is that each one
has a brief, quickly-accessible man page.  pow pow pow.  image
converted.  Netpbm is no longer a valuable tool because of this Linux
zealot necktie damage and someone who would rather write page after
page of rants <cough>, and burry me in un-revision-controlled
hyperlink spaghetti, than just learn to write nroff like everyone
else.  I guess he's too good to learn nroff like the rest of us.
``man page format is too limiting''.  god damnit who do these people
think they are.  it's supposed to be limiting, so that you are neither
free nor inclined to post 5 pages of hyperlinks to other projects
besides yourself in the table of contents to your documentation, so I
don't have to read all your incestuous interweb surf bum garbage.

and no, I don't want helpful people to post hyperlinks to the ``real''
documentation burried somewhere in that mess.  I spent fifteen minutes
typing 'man pnmscale' and I still have nothing.  You're fired, Bryan.
I'm done.

--=20
Le fascisme est la dictature ouverte de la bourgeoisie.
		-- Georg Dimitrov