[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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"

  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'

    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)

  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

Colin Watson                                  [cjwatson@flatline.org.uk]

Reply to: