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:
Is this up for discussion, or a formal proposal?
If formal, send to debian-policy. But it's not thought-out enough
for that.
> (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>
> .
_every_ file? Not just the title file?
$ dpkg -L gri-html-doc | wc
257 256 10884
instead of the index.html file already registered to doc-base
$ dpkg -L gri | grep usr/info | wc
13 13 298
You get the idea.
> (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).
Sounds like the content of /usr/share/doc/<packagename>/README.Debian
for most or all of my packages.
> (3) every file documenting the package should refer to the list of docs
> (as in (1) above) in a "see also" section.
Every file in (1) should list every file in (1) ?
That's a lot of work (and modification of upstream docs).
> I have heard many say "It's easy already" but when maintainers say "where
> are the docs??", that goes far towards disproving the "It's easy" argument.
> Yes, I know /usr/share/doc/<packagename> exists. But most of them contain
> little better than a (required by policy) copyright notice.
Yet you propose to add stuff in /usr/share/doc/<packagename> that
is already in real-done packages in doc-base, man pages, or
/usr/share/doc/<packagename>/README.Debian
Yuck.
--
Peter Galbraith, research scientist <GalbraithP@dfo-mpo.gc.ca>
Maurice Lamontagne Institute, Department of Fisheries and Oceans Canada
P.O. Box 1000, Mont-Joli Qc, G5H 3Z4 Canada. 418-775-0852 FAX: 775-0546
6623'rd GNU/Linux user at the Counter - http://counter.li.org/
Reply to: