Re: debian how-to

["Douglas A. Tutty" <dtutty@porchlight.ca>]

On Mon, Dec 31, 2007 at 01:49:25PM -0800, Daniel Burrows wrote:
> On Mon, Dec 31, 2007 at 01:15:48PM -0600, Manoj Srivastava <srivasta@ieee.org> was heard to say:
 
>   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.

Perhaps it should be policy that if the documentation isn't in the usual
/usr/share/doc/[package-name] that there be a note there with a pointer
(i.e. The documentation for this package is in the foo-doc package since
it is so big.) or (The documentation for this package is under a license
that does not meet the debian free software guidelines.  You can find
the documentation {in the non-free package foo-doc | at the following
URL}, preferably the non-free package option.

Also, perhaps it should be policy that the man page for each command
list the package from which it comes and therefore where the further
docs are.

The dpkg -S trick should be in the debian installation manual under how
to find documentation, which should also point to the debian-reference,
and the other sources of documentation we've discussed in this thread.

 
>   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 think that pdf is the biggest issue.  I don't normally put a pdf
reader on all my boxes and I often don't have X.  I usually have mc and
lynx.  If I need info, I'll use pinfo although I don't like the info
format.

I also dislike huge long man pages.  To me, man pages should be for a
bit more help than foo --help; a summary.  The main doc should be in
plain html for viewing with lynx or something.  


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

I could never figure it out in the time I had to spend on figuring it
out.  It was far easier just to do what we've discussed here.

Doug.