Re: Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
On Wed, Nov 13, 2002 at 10:36:58AM +0100, Javier Fern?ndez-Sanguino Pe?a wrote:
> On Wed, Nov 13, 2002 at 10:10:32AM +0100, Stefano Zacchiroli wrote:
> > On Wed, Nov 13, 2002 at 12:14:50AM -0600, Manoj Srivastava wrote:
> > > undocumented(7) man page. The current proposal is included below; it
> > > is not yet the final form; and input of the general community is
> >
> > Even if I really hate writing man pages, I second this proposal.
> >
> > I think that a lot o undocumented man pages exists only because the
> > maintainer has forgetten them or something like that, having bugs in the
> > BTS should increase the number of available manpages and improbe the
> > debian quality even more.
>
> Note that the current policy forces maintainers to bug themselves
> if they use 'undocumented'. So your reason is not a reason (since the
> problem would be solved with current policy).
Indeed. I'll repeat my rationale here for convenience:
The undocumented(7) page itself can continue to exist. As discussed on
IRC, I'm happy to hack man-db so that it can (configurably) point to
further information in addition to the "No manual entry for foo"
message.
The reason why I'm supporting this proposal is because I find the
symlinks to undocumented(7) technically less than ideal in a number of
ways. They lead to a farm of dangling symlinks on machines that don't
have the manpages package installed (#32019, #53214); they have
translation issues that would necessitate some very ugly hacks like not
honouring symlinks in the expected way (#167291); and they cause this
very common complaint due to the symlinks showing up in 'dpkg -L'
output:
17:06 <weasel> you are happy that you finally found some docs, wait
for groff to render it, and what you get is a stupid undocumented(7)
page
Indeed it is useful to have better-than-nothing documentation for
newbies, so let's arrange for the pointer to be kept in a central place,
something like:
No manual entry for foo. Either you mistyped, or there is no
documentation for this feature: try 'man 7 undocumented'.
This policy proposal, however, doesn't mandate any particular
arrangement along these lines: if you'd be happy with *something* like
this in place of the symlink farm then we can sort out the details as
time goes on. As you correctly note, I'd simply like to drop the policy
*requirement* that programs without a man page ship a symlink to
undocumented(7).
--
Colin Watson [cjwatson@flatline.org.uk]
Reply to: