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
--
* [EMAIL PROTECTED] * http://www.spinnaker.de/ *
