Bug#39830: PROPOSED]: get rid of undocumented(7) symlinks

[Chris Waters <xtifr@dsp.net>]

Jim Lynch <jim@laney.edu> writes:

> If it is decided to keep undocumented(7), howbout we make dpkg -L
> report on symlinks to it?

Riiight.  We'll just file a bug against dpkg.  That'll get some
action!  :-)

Anyway, that doesn't address the issue of people who seem to think
their job is done the moment they use the undocumented link.  Policy's
apparent blessing of the undocumented(7) link seems to be having a
seriously negative effect on our goal of providing man pages for all
programs.  Try "ls -lR /usr/man | grep undocumented | wc -l" to see
what I mean.

To Manoj and others who have objected to this proposal, I'd like to
point out that it can remain possible for people to *use* the
undocumented(7) symlink.  It was a bug to use it, and it'll remain a
bug to use it, it'll just be a little more *clear* that it's a bug if
we remove the blessing of policy.  (Note to man-db maintainer, this
probably means you shouldn't remove the undocumented(7) page.)

Perhaps we can mention undocumented(7) in the packaging manual,
instead of in policy.  And there it would seem more appropriate to
have editorial commentary, like, "it's not hard to make a two line man
page that points to the actual documentation, so undocumented(7)
should only be used in cases of extreme duress."  Or something like
that.  :-)
-- 
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.