Hosting Provided By

Re: debian how-to

From: Daniel Burrows <dburrows(at)debian.org>
Date: Mon Dec 31 2007 - 16:49:25 EST

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

Do you need help?

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

-- 
To UNSUBSCRIBE, email to debian-user-REQUEST@lists.debian.org 
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Received on Mon Dec 31 17:30:33 2007

Do you need more help?

This message: [ Message body ]
Next message: dave N: "Re: debian how-to"
Previous message: David: "Re: wine - resource hog"
In reply to: Manoj Srivastava: "Re: debian how-to"
Next in thread: Douglas A. Tutty: "Re: debian how-to"
Maybe reply: Raquel: "Fw: Re: debian how-to"
Reply: Douglas A. Tutty: "Re: debian how-to"
Reply: Chris Lale: "Re: debian how-to"

Contemporary messages sorted: [ By Date ] [ By Thread ] [ By Subject ] [ By Author ] [ By messages with attachments ]

This archive was generated by hypermail 2.1.8 : Fri Feb 29 2008 - 15:55:38 EST