Re: debian how-to
On Mon, Dec 31, 2007 at 01:15:48PM -0600, Manoj Srivastava <firstname.lastname@example.org> was heard to say:
> On Mon, 31 Dec 2007 08:13:31 -0500, <email@example.com> said:
> > Not all the docs are under /usr/share/doc/[package name], some are
> > under usr/share/[package name] with no apparent rhyme nor
> > reason. Then, everything is gzipped, should the user extract these to
> > their home folder or is there a particular method to read these as
> > they stand?
> The files under /usr/share/[package name] are meant to be used
> by the package at run time, and perhaps are part of an online help
> facility. I understand packages which have a built in help often do not
> give out other documentation. But if that is not the case, and the
> primary documentation lives compressed in /usr/shar/package-name; then
> you have found a bug, please report it.
Even when Policy is followed, it isn't necessarily that simple.
For instance, today I wanted to read up on git hook scripts. I
checked the manual page git(1), and saw the note:
Read hooks for more details about each hook.
Being an experienced Debian user, I knew that I needed to look in
/usr/share/doc/git to find the rest of the documentation. Except that's
not right, because there is no "git" package. Luckily, I also know
dpkg -S $(which git)
which tells me that git is in the "git-core" package. So I check
daniel@alpaca:~$ ls /usr/share/doc/git-core/hooks.html
ls: /usr/share/doc/git-core/hooks.html: No such file or directory
So I check the source package for git-core to see if the docs got
split out somehow:
daniel@alpaca:~$ apt-cache showsrc git-core
Binary: git-daemon-run, git-core, git-cvs, gitweb, git-gui, git-email, git-arch, git-svn, git-doc, gitk
Aha, there's a git-doc package! And indeed, that's where hooks.html
daniel@alpaca:~$ ls /usr/share/doc/git-doc/hooks.html
That took me a minute or two. But there are at least four things I
had to know which a new user of Debian won't know.
I think the biggest problem is that documentation is organized by
package and not by command, or at least that there's no interface for
searching *all* the documentation by command. There's also no
consistency in where the documentation ends up, although this may be a
matter of Policy compliance. To take the first three packages I looked
* git-doc places its files in /usr/share/doc/git-doc
* vim-doc places its files in /usr/share/doc/vim-common/html
* aptitude-doc-* places its files in /usr/share/doc/aptitude/html/$LANG
A secondary issue is that there's no consistency in file formats
between different documentation packages. To read documentation, you
need to be able to handle:
* Plain text
* Info documents
* Whatever help file format Gnome and KDE are using nowadays
This wouldn't be as much of an issue if there was a way for a user to
easily access all the documentation related to a command; PDF viewers
are fairly easy to deal with, for instance (although a lot of packages
compress their PDF documentation, which means you have to manually
uncompress it somewhere).
I don't have time to do this, but I think it is something that should
be fixed at some point. doc-base was an effort to at least build a
central documentation registry (in the non-Windows sense :) ), but AFAIK
it's not used much these days.