pre-proposal: get rid of undocumented(7)
Christoph Lameter <christoph@lameter.com> writes:
> Sometimes I check for documentation by doing a dpkg -L. I see a manpage
> for a certain command and do a "man xxx". Result is a "undocumented"
> manpage. Very irritating. It would have saved some effort if there simply
> were no manpage.
You know, actually, that's very true. The undocumented(7) link is not
only useless, but actively annoying. The only possible benefit I can
see is that it makes it clear to the user that a bug has been filed.
But it seems that in a lot of cases, nobody has any plans to actually
fix the bug, and the undocumented(7) link just stays there forever.
It's *supposed* to be a bug if you're using undocumented(7), it's just
a policy-compliant bug(?) or some such malarky. :-)
Perhaps the undocumented(7) page has outlived is usefulness? Is it
time to consider better options? Are there better options? The one
advantage I can see to the current setup is that it lets the user know
that someone is aware that there is no man page (which can save a lot
of time -- I hate to say it, but hunting through the BTS can be a pain
sometimes). But surely there are easier ways!
OTOH, changing this would affect a lot of packages. But that fact in
itself just serves to underline how ineffectual undocumented(7) is at
solving the problem of missing man pages.
How about this as an idea: if you have no man page, you have to put a
file in /usr/doc/<package>/no-man-page that describes the situation,
briefly. Something along the lines of "I'm working on it", or "I'm
not working on it because I don't know roff", or "I'm not working on
it because the program is evolving too rapidly for me to track", or
"upstream promised one next release", or whatever seems appropriate.
Unlike undocumented(7), this could actually be somewhat useful, as it
would let the users know exactly what the situation is.
This is even something that lintian could check for, after a fashion.
The only really tricky bit I see with this idea is the transition from
what we have currently.
Comments? Criticism? Cluebats?
--
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: