Re: policy summary

[Chris Waters <xtifr@dsp.net>]

Matthew Vernon <matthew@sel.cam.ac.uk> writes:

> Chris Waters writes:

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

> I'm not sure I agree with your argument that undocumented(7) is a
> disincentive to write a proper manpage, but that would just be
> argument by repeated assertion, so I won't go there. 

I'm not going to say that it's a disincentive in *every* case, but
it's clearly a disincentive in *some* cases, and I know this because I
*was* such a case.  The fact that some packages have been using
undocumented(7) for several *years* tends to suggest that I'm far from
alone.

> maybe we should encourage people to check the BTS and submit a bug
> report, or simply "do submit this as a bug if there isn't an
> appropriate one open", since it seems that there often isn't the bug
> open that undocumented(7) currently says there is.

That's a good idea.  Not enough to answer my complaints, but better
than the existing situation.

My main objection to undocumented(7) *is* that people treat it as a
bug fix when use of it *is* still a bug!  If we can convince people to
start providing real man pages (even just quick-and-dirty ones that
point to the real documentation, which is what I ended up creating),
then I'll be perfectly happy to keep undocumented(7) around for those
rare cases where the maintainer hasn't yet had time to whip something
up.  But the present case where people use undocumented(7) and leave
it for years *must* change IMO.

I'll leave the following to ponder:

   ~ $ for f in /usr{,/share,/X11R6}/man/man*                  
   >   do  ls -l $f/*
   >   done | grep undocumented | wc -l
       395
   ~ $ 

That is simply too many to excuse, esp. since I have very few
brand-new, just-released packages installed.

cheers
-- 
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.