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


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

Relevant Pages

  • Re: Finding installed package files
    ... > you appear to want is a file that lists executables and documentation. ... contains links to the most important information about the installation. ... > doubt others could finesse the command. ... I do understand that rpm has many options that tell me about a package. ...
    (alt.os.linux.redhat)
  • Re: debian how-to
    ... today I wanted to read up on git hook scripts. ... because there is no "git" package. ... So I check the source package for git-core to see if the docs got ... I think the biggest problem is that documentation is organized by ...
    (Debian-User)
  • Re: Several beginners questions
    ... manual or documentation using the wrapfig package but found none. ... That is, a full latex file that compiles, that would not show the problem anymore if you removed any line. ... The \graphicspath command may be helpful to save you some tedious typing, if you store your images in a special directory. ...
    (comp.text.tex)
  • Re: Javadoc question re Eclipse
    ... The documentation seems to be saying that I should put this file in my source tree under the package being documented. ... I tried creating a Class named package-info in Package Explorer within the ... Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. ...
    (comp.lang.java.programmer)
  • Re: debian how-to
    ... The documentation for this package is in the foo-doc package since ... The dpkg -S trick should be in the debian installation manual under how ... easily access all the documentation related to a command; PDF viewers ...
    (Debian-User)