[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: PROPOSAL: complete list of documentation files, "man <packagename>", all man pages refer to said doc list in "See Also" section

Jim Lynch wrote:


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
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: