Re: PROPOSAL: complete list of documentation files, "man <packagename>", all man pages refer to said doc list in "See Also" section
Jim Lynch wrote:
> I THEREFORE PROPOSE:
Shouldn't you be posting to debian-policy? I've redirected this there.
> (1) each package should list the fully qualified path to every documentation
> file it installs. This list would be kept in /usr/share/doc/<packagename>.
In the message you replied to when making this proposal, Kirrily said
that "However, before this week I was looking in manual pages and local
documentation in preference to the Debian website." At no time did
Kirrily indicate that she was not aware of the convention of placing
documentation in /usr/doc/. Her problem was in fact that she didn't know
what package to look in to find the documentation.
Your proposal seems to me to be circular, irrevelant, bloating, and rather
useless. Irrevelant because it does not address Kirrilly's actual
problem. Circular because it professes to address the problem of people
not knowing to look in /usr/doc for information, and proposes to solve
this by putting more files in /usr/doc! Useless and bloating because it
increases the size of each package with what is effectively the output
of "dpkg -L package |egrep 'usr/share/doc|usr/share/info|usr/share/man'".
> (2) each package should install a man page in some section (I dunno which
> one, but sect 1 is probably not a good idea) named such that one can
> type "man <packagename>" or "man <theSect> <packagename>".
>
> The job of this man page is to introduce the package, enumerate its
> executables, refer to its special dirs (if any), refer to the
> documentation directory /usr/share/doc/<packagename> and the list of
> doc files (as in (1)) and give a heads-up if there is anything special
> about the package (maybe it has a /etc/init.d/<packagename> file).
Perhaps you are not aware of dpkg -s ("introduce the package"),
dpkg -L |grep /bin ("enumerate its executables"), and dpkg -L in
general?
This proposal has been made before. It failed. Please review why it
failed, and address all previous ojections before making it again.
> (3) every file documenting the package should refer to the list of docs
> (as in (1) above) in a "see also" section.
You're scrambling to plaster Debian with rather useless pointers to
documentation, when this is not the solution to either the real problem
Kirrily raised, or your preceived problem that people do not know of
/usr/doc.
Yuck.
> (4) Some packages are documented in material not installed with the package.
> If the package maintainer is aware of such material (as (s)he would be
> if said outside docs were used in installing or configuring the package),
> then the maintainer would have two choices:
>
> (a) the package could be altered to include the material; or
> (b) the documentation list (as in (1)) could be altered to refer
> to the material, either by URL or other absolute pointer,
> such as an ISBN number for a book.
This is already done to some degree. To absolutly require it places
unacceptable demands on the debian maintainer. I should not have to
contact the Library of Congress to get a list of all ISBN's related to a
package, before packaging it.
> The list of documentation files for the package would act as a
> clearinghouse for sources of info about the package. Because all docs
> would refer to it, no one would be at a loss when trying to find the
> docs to read. I know that complaints about not being able to find docs
> prevail, even from maintainers.
>
> I have heard many say "It's easy already" but when maintainers say "where
> are the docs??"
I haven't heard them.
We have a far simpler solution to your perceived problem of people not
being aware of the existence of /usr/doc. Take a look at /etc/motd on
any new debian install. I don't have the exact text handy, as I am in
transit right now, but it essentially points the user to /usr/doc. It is
displayed every time a user logs in. This is *enough*.
Addressing Kirrily's real problem, new and prospective developers often
have a hard time finding packages such as developers-reference. Kirrilly
has pointed out that although we do make it promenent on the web site,
this isn't any help if you are interested in helping Debian and are
trying to find docs to do so on your own computer.
Kirrily provided several solutions, which you ignored. Here they are
again:
| Yeah, I've since found the packaging-manual (and others) on the website.
| It would be nice if the dpkg manual pages pointed to it, though, as
| that's where I started looking.
dpkg(1) actually points the user to several nonexistant info
pages. I have filed a bug on dpkg to have this corrected and make it
point to something that actually exists.
| Is there any naming convention for debian-specific documentation
| packages? I would have expected such things to be called debian-blah,
| similar to debian-policy.
What do folks think?
--
see shy jo
Reply to: