Re: debian how-to

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


--
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. ... which tells me that git is in the "git-core" package. ... Perhaps it should be policy that if the documentation isn't in the usual ... easily access all the documentation related to a command; PDF viewers ...
    (Debian-User)
  • 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: 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)
  • [ANNOUNCE] GIT 1.5.4.3
    ... The latest maintenance release GIT 1.5.4.3 is available at the ... you do "yum install git-core". ... git-gui updates to work on OSX and Windows better. ... Avoid hardcoded Windows paths in Cygwin package files ...
    (Linux-Kernel)