Re: debian how-to

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.

Do you need help?

In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software: Learn more about Pantek's Technical Support offerings Place an order for 24/7/365 Technical Support here Learn more about Pantek, who we are, and what we do Chat with a Live Operator Related lists.debian.org Links debian-announce debian-apache debian-arm-changes debian-beowulf debian-boot debian-cd debian-cd-vendors debian-changes debian-changes-digest debian-isp debian-kde debian-laptop debian-mirrors-announce debian-news debian-security debian-security-announce debian-testing debian-user debian-user-digest Request more information about Pantek

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.

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