Re: Thoughts on dhelp
Chris Tillman <tillman@azstarnet.com> writes:
> After taking a look at dhelp, dwww, and doc-central, I have a few
> observations.
>
> 1) dwww and doc-central both depend on installation of a cgi-capable
> webserver.
>
> 2) dwww and dhelp try to give access to all the documentation
> available, man, info, and usr/share/doc. More effort seems to have
> been put into dwww than either dhelp or doc-base.
>
> 3) dwww and doc-central both derive their main menu from the debian
> menu, which seems like a good approach. But it also straightjackets
> packages in a way, and since menu is really a hierarchy of
> functions, it doesn't always correspond to a good hierarchy for
> documentation. Some documentation falls outside the explanation of
> functions. The doc-base manual lists a ddh document hierarchy as
> one of the TODO items, and apparently Marcus Brinkman did quite a
> bit of work on it 42 months ago (in the doc-base cvs
> directory). But apparently it fell by the wayside, or no one else
> was interested.
>
> 4) dhelp wants its index files installed in each package
> directory. This is not a good thing, it causes several issues
> because the ownership of each directory becomes shared instead of
> exclusive. It's like imposing a tax. dhelp should read directly
> from doc-base files, which was the intent of doc-base in any case.
> dwww dropped support for individual files some time ago, probably
> because of the same issues.
There is no real reason to have these .dhelp files cluttered allover
this place. Anyhow, to solve this the interface between doc-base
and dhelp should be improved.
>
> 5) dwww and doc-base both offer a search entry form, but they do not
> have a preindexed search tree. doc-base uses python's compiled
> regexp search to look through each document in its list, and dwww
> uses dpkg -s and/or grep to look for program names. dhelp's index
> approach is unique so far for debian.
>
> 6) dsearch brings up docs from multiple languages. None of these
> programs have anything regarding alternate-language
> documentation, utf-8, respecting $LANG variable, etc.
>
> 7) dhelp uses a quasi-xml representation of document metadata;
> doc-base uses a dpkg-like flat file approach. XML is a standard,
> but uses some extra space in the metadata file. If XML were used,
> the result would be exportable to other modules and other systems.
After releasing woody we should basically rewrite dhelp from scratch,
because the current implementation sucks anyway. We can use Perl
than as programming language, so there is easy access to XML modules.
Storing stuff in XML is a good idea IMHO.
>
> The unique features dhelp has to offer thus far are: a customizable
> hierarchy, a presearch index database, and presentation of docs
> without necessity for cgi.
>
> Maybe we should take advantage of dwww's work. dhelp could pass
> control to dwww for presenting things via cgi, and running man2html /
> info2www type conversion work. Then dhelp could concentrate on
> indexing, and exporting a searchable database interface which could be
> used by dwww, and presenting docs without using cgi. dhelp should also
> be taught to read doc-base rather than .dhelp files.
OK.
>
> Somewhere along the way, translations and lang preferences should be
> addressed.
>
> What are your thoughts?
I like your thoughts. I cc'ed this to the debian-doc mailing list,
which is IMHO more appropriate for this discussion.
Ciao
Racke
--
For projects and other business stuff please refer to COBOLT NetServices
(URL: http://www.cobolt.net; Email: info@cobolt.net; Phone: 0041-1-3884400)
Reply to: