Re: Making documentation easier to find (was: Re: exim mail routing...)
On Wed, 24 May 2000, David Henningsson wrote:
> >what i mean, is, the reason newbies don't FIND the documentation
> >is because it is an ORDEAL to do so. apprentice-guru status is
> >required to know to search /usr/doc via zgrep AND /usr/share/doc
> >AND info pages AND man pages AND apropos...
>
> You're quite right.
>
> Could this be a solution? A new Debian utility called documentationview or
> something, tree-organized like dselect. The first thing you do is to select
> a category. And then you get maybe an HOWTO and a FAQ from there, and a
> list of available programs/packages. If you select a package, available
> help files from within that package is shown. Manuals, getting started
> stuff, etc. And maybe links to configuration scripts? If you select one of
> them, it could start up man, info, less, mozilla/lynx, or whatever is
> appropriate.
If you are running KDE, and have kpackage installed, you are most of the
way to what you describe. kpackage gives you a tree view of Debian
packages, and a list of all files in a package; clicking on a file will
call kfm, which will figure out what the file is and call the
appropriate viewer (default app).
> I haven't read the .deb specs, since I'm not much more than a newbie yet,
> but maybe there could be a possibility to include this therein. As I see,
> there are at least two problems with this:
> 1) Somebody has to write the program
Or hack an existing prog... like maybe a filter for kpackage so that it
only displays doc files in the per package file lists; or a new option
for one of the existing progs (dhelp, etc.) so that it constructs an
index of all docs, instead of just registered documents.
> 2) All the debian package maintainers have to use it.
All the info needed is already in the dpkg DB, you just have to parse
/var/lib/dpkg/info/<package>.list (via "dpkg -L <package>", maybe) and
extract the locations of anything that profiles like a doc file.
Figuring out what is a doc file, and what kind it is (Manual, FAQ,
ReadMe, Examples, etc.) is the tricky part... but probably not so tough
as getting maintainers to register docs. :)
later,
Bruce
Reply to: