Re: PROPOSAL: complete list of documentation files, "man <packagename>", all man pages refer to said doc list in "See Also" section
On Fri, May 19, 2000 at 03:35:09PM -0500, David Starner wrote:
> On Fri, May 19, 2000 at 12:00:03PM -0700, Jim Lynch wrote:
> > I THEREFORE PROPOSE:
> >
> > (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>.
> >
> > (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>".
>
> cat /var/lib/dpkg/info/packagename.list | less (or | grep bin)
> works well enough for me. Well enough that I don't think any minor
> improvements on it that require duplicating that information
> elsewhere should be taken without a lot of thought.
Certainly works well enough for people who happen to know about
/var/lib/dpkg/info/packagename.list ... but that's not necessarily
true of end-users.
Now, I'm seldom the type to argue that things should be easier for
(l)users, but I think that it's reasonable to expect that users should
be able to reach all documentation for a given package from one, or at
most two, places. Those places, IMO, should be /usr/share/doc/packagename,
and, if the packagename is the name of a command, man packagename. It
doesn't matter if the man page says "see the info page", or if
/usr/share/doc/packagename has a pointer to a web site URL or something,
as long as it exists.
The biggest problems I've experienced occur when:
1) a package contains a number of commands, none related to the actual
packagename. For instance, dpkg-dev contains a bunch of scripts and
stuff, but there is no pointer to them under /usr/share/doc/dpkg-dev or
"man dpkg-dev", only individual manpages for scripts such as
dpkg-buildpackage. In this case, I think there should be a pointer to
the individual man pages either in /usr/share/doc/packagename.
2) documentation for a package is separate from the package itself. A
slightly naive user may install the base package via dselect, and not
notice that the doc is separate. In this case, it is appropriate for
the documentation for the base to point to the related documentation.
3) a basic tool is augmented or extended or in other ways made more
useful by a tool in another package, but there are no pointers from the
basic package to the extended package. This is sometimes the case for
packages which provide administrative tools, development tools, etc. In
this case, I think that pointers to the documentation for the extended
package should probably exist in the base package's documentation. A
(non-free) example of a package that does this is MySQL; a
counter-example, again, is dpkg/dpkg-dev.
You can think of documentation as a network graph which is traversed by
the reader. The reader usually enters from one of a number of points...
manpages for common commands, /usr/doc/packagename, whatever. Imagine
that the entirety of Debian's documentation, including all the docco for
every package, is part of this graph. Now, are there any nodes which
cannot be reached?
Determining what can and can't be reached is a matter of figuring out
what the starting points are, and what intermediate steps are reasonable
to expect of users. For instance, I think that reading shell scripts to
figure out how something works is probably a bit too much to expect of
all users. Likewise, users probably shouldn't have to dig around in
/var/lig/dpkg/blah. Whether or not they should be expected to know
"dpkg -L packagename" is borderline... think of an end-user of a system
administered by someone else... why should they need to know dpkg's
arcana?
Anyway, that's just my thoughts on documentation, as seen by a user and
sometimes administrator of debian systems with very little experience of
debian development. Take them or leave them :)
K.
--
Kirrily Robert -- <skud@netizen.com.au> -- http://netizen.com.au/
Internet and Open Source Development, Consulting and Training
Level 13, 500 Collins St, Melbourne VIC 3000
Phone: +61 3 9614 0949 Fax +61 3 9614 0948
Reply to: