On Mon, Dec 31, 2007 at 01:15:48PM -0600, Manoj Srivastava <[EMAIL PROTECTED]> was heard to say: > On Mon, 31 Dec 2007 08:13:31 -0500, <[EMAIL PROTECTED]> 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[9] for more details about each hook. ... 9. hooks hooks.html 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 about dpkg -S $(which git) which tells me that git is in the "git-core" package. So I check there: [EMAIL PROTECTED]:~$ 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: [EMAIL PROTECTED]:~$ apt-cache showsrc git-core Package: 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 lives: [EMAIL PROTECTED]:~$ ls /usr/share/doc/git-doc/hooks.html /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 at: * 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 * HTML * PDF * PostScript * DVI * Manpages * 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. Daniel -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]