Re: policy summary

[Roland Rosenfeld <roland@spinnaker.de>]

On Wed, 05 Jan 2000, Chris Waters wrote:

> > So you are saying that packers are omitting an EXISTING manpage,
> > and instead putting a link to the undocumented.7 page?

> No, what he's saying is that people *routinely* use undocumented(7)
> *without* any bug report on file.

That's exactly the point.  Before I wrote the above proposal, I filed
a mass of bug reports against all packages installed on my system with
undocumented.7 links and without a corresponding bug report.  I was
shocked to receive some flames of package maintainers, who thought
that the link to undocumented.7 was enough...

I fear that most maintainers simply create the symlink because it's
the easiest way to stop lintian complaining about the missing man page
and dh_undocumented(1) is a very easy way to implement the symlink.

> > However, what about the more common case where there IS no
> > manpage?  Then, I believe it is useful.

A little man page, which mentions where to find the documentation
would be much more useful and can be written in 10 minutes.  In
contrast to undocumented(7) such a specific man page can tell the user
which documentation is available and where it is located in the
filesystem. 
 
> Furthermore (and to me, this is the big one), many many MANY people
> seem to think that all they have to do is link to undocumented(7)
> and their job is done.  The existence of undocumented(7) may
> actually be *hindering* the creation of man pages.

That's exactly the problem, I also see.
In addition to this, it is annoying to me (as a user) when I'm looking
for documentation.  I don't know how others do this, I personally try
to find the documentation of a package with dpkg -L or dlocate -L.
With this I see, that there seems to be a man page, but when I look
into this man page, it's only undocumented(7).  This doesn't help me
finding the real documentation but only takes time...

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

As a first step it may be a good idea to add a test to lintian which
mentions undocumented.7 links as errors.  That should be acceptable,
because policy says that there should be a bug report for missing man
pages (including those with undocumented.7 symlinks).  It's a bug, so
it's okay to let lintian report this bug until someone provides a real
man page.

Ciao

        Roland

-- 
 * roland@spinnaker.de * http://www.spinnaker.de/ *