Re: fixing up /usr/doc
Hello Debian-devel,
This is one issue that I can't hold back on, and as such have not read the
archives or even familarized myself with the most recent versions of all
the software mentioned. So at the risk of bringing up discarded ideas and
missing something that should be obvious....
On Mon, 28 Dec 1998, Wichert Akkerman wrote:
> The problem here is that it is
> hard for users to locate documentation for packages.
and why is it hard...
> The real solution is to register documentation with a documentation
> system such as dwww or dhelp. That also shows a problem: there are
> multiple systems. Luckily there is doc-base, which allows you to
> register documentation only once and have it show up in both dhelp and
> dwww.
... I see it is also hard for the authors.
> For manpages and infodocuments we already have a lot of tools to view
> them (man, info, man2www, info2html, tkinfo, gnome-help, etc.)
... and for text docs there is more/less/most, PS and PDF have gs/gv, ...
My point is:
There are so many different formats and tools, the average
user could not be bothered to learn how to use them all;
and the typical author is more interested is just getting
the docs written down, than in what format or system they
will be displayed with.
Since computers excel at brainless repetetive tasks, and with a little
effort can be made to appear at least half intelligent... perhaps it is
time to have the computer take over the task of looking for the docs.
We know where the docs are (mainly in /usr/{doc,info,lib,man}), and we
know what they look like (suffix templates and absolute names). All we
need is a UI that users already know how to use, and a system that the
authors don't have to know about. What we don't need is another utility
support system full of shitty little files containing information that can
be gleaned from elsewhere on the HD. We should also avoid the same basic
mistake made by man, info and most (all?) of the others.
The main problem with most of the existing "systems" is that they are
really just format viewers, and as such are prone to being in or out of
favour with different groups of authors or users.
This is what I think a "seedocs" system would do (given: seedocs prg)
- determine what package prg belongs to using dpkg
- find the paths to the docs from /var/lib/dpkg/info/package.list
- spit some HTML, containing links through the appropriate
filters for the various formats, into a temp file
- fire up the default browser or a scaled down version of Lynx
Naturally seedocs would have interactive configuration and be able to
optionally do such thing as: make the temp 'contents' file permanent,
enable/disable classes of documents (based on format or category, e.g.,
root should be able to disable the creation of links to the source for
scripts that reside in a */cgi-bin or */sbin directory), handle docs that
the user has decided to keep off-line...
Once the logic is worked out for such a system the only ongoing
requirement would be to keep a look out for new file formats and hidding
places. In fact, as long as there is a way to track down the docs for a
system (other unices, win, anything on the HD), there is no reason to
prevent "seedocs" from linking to them.
just a thought...
later,
Bruce
Reply to: