Re: Bug#39830: [PROPOSED]: get rid of undocumented(7) symlinks
On Wed, 23 Jun 1999, Manoj Srivastava wrote:
> And I get mad if I do man binary and I get nothing, after a
> long time searching.
I don't see no real the difference between "No manual entry for foo"
and the contents of undocumented(7). Both tell me that there is no man
page, but the former brings less overhead...
> I prefer that I see a page that tells me that the developer is
> aware of this bug.
That's what undocumented(7) is telling you, but that's not the
reality. I recently checked all undocumented.7 symlinks on my system
and filed bug reports where no bug reports were before. Nearly 90% of
the needed bug reports were missing. And then I got lot's of feedback:
Some authors simply flamed me (because I smirched their clean bug
report list), others didn't know that a real man page was needed or
they simply didn't want to write a man page. Only one developer wrote
me, that he is working on a man page.
So this symlink only tells you that the author is aware of this bug,
but the really is, that most developers simply want to stop lintian
warning about the missing man page.
> If there is no man page, most people would file identical bug
> reopirts about ti,
Not really. My check of all the undocumented symlinks on my system
showed, that only 10% of the bugs are really reported. And don't tell
me, that the bugs are not reported only because of this symlink. This
symlink simply means (for most packages), that _nobody_ writes a bug
report and that the developer isn't aware of the problem.
> the undocumented man page is to prevent multiple reports about a
> known problem.
I proposed to mention this in /usr/doc/<package>/TODO.Debian. This is
a much more generic place to place this information. This file allows
you to explain why the man page is missing and what you are doing to
solve this problem. Except this you are able to note other things,
which should be done there.
BTW: Another choice is to write a minimal man page, which only tells
the user that the maintainer is really aware of the problem and that
the documentation can be found in the info system or under /usr/doc
(with explicit noting the locations instead of the templates in
undocumented(7), which doesn't help to find where the documentation
really is).
> Chris> Plus, it may well be causing people to think that they've
> Chris> solved the problem when they provide a link to
> Chris> undocumented(7). "What bug? My package complies with
> Chris> policy."
>
> Then they have not read the policy document. This is a non
> argument.
But this is the reality and undocumented(7) makes it easy to
misunderstand the policy in this point, irrespective of the fact, that
the 2.5.1.0 policy isn't very clear in this point.
> The idea was to recognize that it may not always be simple
> to write a man page,
This a prejudice.
> or the maintainer maybe presssed for time,
This can be noted in TODO.Debian much better (because in a file you
can explain, _why_ this man page is missing).
> and even though a man page is required, the package may still have
> utility (espescially if the binary is not the main or only binary
> in the pages).
Do we need a symlink for this? Aren't there better ways to explain
this?
> I must confess I never though that peole would wait for dpkg -L
> rather than just go man blah.
I normally run dpkg -L when I install a new package and after this I
run man on all available man pages to find out how the programs are
working. And with this it's very annoying to only see undocumented(7)
instead of useful man page or of seeing that there is no man page
available and I have to keep searching for other documentation.
> In the latter case, I do find the presence of a man page
> comforting, even though it says there is no documentation.
"No manual entry for foo" does this, too.
Ciao
Roland
--
* roland@spinnaker.de * http://www.spinnaker.de/ *
PGP: 1024/DD08DD6D 2D E7 CC DE D5 8D 78 BE 3C A0 A4 F1 4B 09 CE AF
Reply to: