Re: Bug#39830: debian-policy: [PROPOSED]: get rid of undocumented(7) symlinks
Manoj Srivastava <srivasta@debian.org> writes:
> And I get mad if I do man binary and I get nothing, after a
> long time searching. I prefer that I see a page that tells me that
> the developer is aware of this bug.
I think "long time searching" is a bit hyperbolic. Anway, I find both
equally abhorrent. Between the two, I find myself reluctant to use
man at all. But there are drawbacks to undocumented(7) that you are
overlooking.
> If there is no man page, most people would file identical bug
> reopirts about ti, the undocumented man page is to prevent multiple
> reports about a known problem.
The new proposal addresses this. It requires that the maintainer
describe the situation wrt man pages in TODO.Debian.
In any case, if you follow policy, you are not allowed to use
undocumented(7) until a bug has been filed, but you can't really file
a bug until the package exists in the archives. So the result is that
you have to upload a package without any man page, file a bug report
(meanwhile, people are downloading this package), and then turn around
and reupload a "fixed" version that has no changes except the
undocumented(7) link (and now all the users have to download the
package a second time, for no real gain). And the second upload
doesn't even close any bugs....
> Chris> Not having a man page is a bug. Using undocumented(7) is a
> Chris> bug, but a bug blessed by policy. The idea that policy
> Chris> should bless a bug just seems wrong.
> The policy does not say it is not a bug. The policy indeed
> says you may *NOT* close any bug reported about this.
I didn't say "not a bug", I said, "bug blessed by policy". If you
don't think this lowers the motivation to address the problem, then
you don't understand human nature.
Much better to persuade them to offer a two-line man page that simply
tells you where the real documentation is. The existence of
undocumented(7) is a distinct disincentive to create even a two-line
man page for a program. Much as I hate to admit it, I must confess
that I am speaking from personal experience here.
> The idea was to recognize that it may not always be simple to
> write a man page,
But that's not true. It may not be simple to write a complete,
thorough man page, but it's the work of a couple of minutes to whip up
a two-liner that points to the real documentation.
> or the maintainer maybe presssed for time
If the maintainer is too pressed for time to whip up a two-liner, he's
too pressed for time to create the package in the first place.
Yes, the proposal before the board is to require the creation of
nearly-useless man pages instead of using the *completely* useless
undocumented(7) link. :-)
> I must confess I never though that peole would wait for dpkg -L
> rather than just go man blah.
Going man blah assumes that you know what blah is named, which isn't
alway obvious from the package name. I *always* do a dpkg -L after
installing a new package, just to see what might be lurking in there.
Furthermore, going "man blah" requires some confidence that you will
receive useful information. Which I do not have at this point.
~ $ ls -lR /usr/man | grep undocumented | wc -l
241
And that's without even looking in /usr/X11R6/man.
The rampant and widespread use of undocumented(7) is, IMO, starting to
create a disincentive for users to even bother with man at all! I
hope that's not the result that was originally intended.
--
Chris Waters xtifr@dsp.net | I have a truly elegant proof of the
or xtifr@debian.org | above, but it is too long to fit into
http://www.dsp.net/xtifr | this .signature file.
Reply to: