Re: debian how-to

[Daniel Burrows <dburrows@debian.org>]

On Mon, Dec 31, 2007 at 01:15:48PM -0600, Manoj Srivastava <srivasta@ieee.org> was heard to say:
> On Mon, 31 Dec 2007 08:13:31 -0500,   <drn_temp2@rogers.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[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:

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

     daniel@alpaca:~$ 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