Re: policy summary
Jonathan Walther <krooger@debian.org> writes:
> So you are saying that packers are omitting an EXISTING manpage, and instead
> putting a link to the undocumented.7 page?
No, what he's saying is that people *routinely* use undocumented(7)
*without* any bug report on file. (And a smaller but still noticable
number have a bug report on file but *don't* use undocumented(7).)
> However, what about the more common case where there IS no manpage?
> Then, I believe it is useful.
I would agree *if* it were used properly. But it's not; it's just
plain not doing its job.
Furthermore (and to me, this is the big one), many many MANY people
seem to think that all they have to do is link to undocumented(7) and
their job is done. The existence of undocumented(7) may actually be
*hindering* the creation of man pages.
It is NOT documentation in any meaningful sense, but many people seem
to be treating it as if it were. (It's not even documentation of the
fact that a bug report is on file, because the correspondence between
the use of undocumented(7) and bug reports is so low as to be
lost in the background noise.)
Nevertheless, while I *did* second the proposal, and I still think
it's a good proposal (I think it might inspire us to find solutions
that *do* work), I don't think it's a *necessary* proposal. I won't
weep tears if it's defeated, but I would like to challenge the
opponents to come up with ANOTHER solution to these underlying
problems.
(Note: the mere existence of the proposal was sufficient motivation
for me to write several man pages; now all my packages (except one I
*just* adopted) have man pages. Previously, I had a number of
undocumented(7) links that I'd been all-but-ignoring.)
> Whether a manpage exists or not, that symlink to undocumented.7
> encourages people either to write a manpage or find the existing one
> and add it if they want it enough.
This is the part I strongly disagree with. Speaking just for myself,
I can say that undocumented(7) provided me with a DISincentive to
write a manpage until this proposal came along and reminded me that my
attitude was foolish and inappropriate. I can't say how many other
people are encouraged to NOT provide man pages by the presence of
undocumented(7), but available evidence suggests that it's a fair
number.
We have a *serious* problem here, IMO, and, while this proposal may
not be the best solution, we *need* a solution. I'd like to hear some
alternative proposals if this one is to be discarded.
cheers
(cc'd to the most recent objectors in the probably vain hope that
they'll be able to put their ideas where their mouth is....)
--
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: