About undocumented(7)

[masc@writeme.com]

Chris Waters <xtifr@dsp.net> writes:

> 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?

I personnaly also find it annoying getting the undocumented(7) as an
answer. However it sounds to me like your suggestions could be used for
new versions of manpages to replace undoc(7). In most cases, the reasons
why there isn't a manpage falls in those few groups. I think that an
option should be added to man, so the user could choose if she wanted to
get these manpages as answer or the "no manpages for xxx found" instead.
This should of course be in MANUNDOC=YES/NO or a .noundocman file in ~.

Just my humble opinion
Mikkel Alan Stokkebye Christiansen
masc@writeme.com