Re: PROPOSAL: complete list of documentation files, "man <packagename>", all man pages refer to said doc list in "See Also" section
On 21-May-00, 20:23 (CDT), Jim Lynch <jim@laney.edu> wrote:
> The reason I made this proposal is because there exist packages which
> don't put enough documentation in. If you want, I can find them all
> and file documentation bugs against them. (what severity would that
> end up being? Important?)
If the upstream source includes documentation that is not being
included, then the priority should probably be 'normal'. If the
documentation needs to be written, then 'wishlist'.
>I expect enough documentation to use the package. As a maintainer and
>potential non-maintainer uploader, I expect references to any docs the
>maintainer used in the building of the package.
Actually, if there is an INSTALL type document, I usually don't include
it in the package. The user doesn't need to know how to configure and
compile the softwarer -- that's the major point of a Debian package.
I'm *not* arguing against the idea that packages should have sufficient
docs, but I think the problem is at the level of individual packages,
not Debian policy. I also don't think we can dictate the quantity or
quality of documentation available. Yes, it would be nice for packages
that have a lot individual programs to have a summary of what each one
does somewhere, but the most you can do is file a wishlist bug against
the package in question (well, the most you could do is *write* the
summary, and submit it...).
But part of learning to use Unix is learning to use the man command and
the info command, and in the case of Debian, /usr/share/doc. Debian has
a tremendous advantage that 'dpkg -L' is available, so that you can see
all the files installed by a package. If you use dselect (or the other
"high-level" pkg manager frontends), you'll get a "suggests" for the
seperate doc package, if there is one.
Steve
Reply to: