Bug#51116: Suggestion: Packages should carry a manpage

[Roland Rosenfeld <roland@debian.org>]

Goswin Brederlow schrieb am Dienstag, den 23. November 1999:

> Policy says that any binary must come with a manpage. I would like
> to have the same for packages.

I'm not sure, whether such a general rule is acceptable.  Think for
example about the long list of libstdc++* packages:  Should we write a
man page for every of these packages?  I'm not sure, whether the
effort is worth the work.

> I just looked for a parser generator that outputs C++ code and found
> pccts.  After installation I tried "man pccts", but that failed.

This may be a problem of the actual Debian package.  I didn't upgrade
this package for a long time, so I still have debian version 1.4 of
this package installed.  The 1.4 version was not very lintian clean
(strange version number, man pages not compressed,...), but it
included a man page /usr/man/man1/pccts.1:

NAME
       PCCTS - The Purdue Compiler Construction Tool Set

DESCRIPTION
       PCCTS is a set of public domain software tools designed to
       facilitate  the  implementation  of  compilers  and  other
       translation systems.  These tools currently include antlr,
       dlg and support code.  In many ways, PCCTS is similar to a
[...]

So maybe this page was simply lost when upgrading from 1.4 to
1.33MR20a-0.1...

> /usr/doc/pccts doesn't contain examples, so how do I use the thing?

In 1.4 there are some examples in /usr/lib/pccts/testcpp/*.  I didn't
look at the new version, but maybe these examples are also lost while
upgrading?  Yes, I know, that the examples shouldn't be in
/usr/lib/pccts/testcpp but in /usr/[share/]doc/pccts/examples.

> My suggestion is now, that "man pccts" should eigther point to the
> main binarys manpage or show a page that gives a oneline description
> of the binaries of the package or one that has just relevant "see
> also: xxx" entries.

> What do you think?

The means much work for the developers, because this means that you
have to change nearly every package.  It would be great to have a
generic way to find the documentation, but I'm not sure whether this
is worth the effort (especially when I think, that many Debian
maintainers don't write man pages for all their programs, which means
that there will be many packages without man page).  So dlocate -L (or
dpkg -L) will still be the one and only working way to find out, which
documentation is available.

Tschoeeee

        Roland

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