dhelp

What's dhelp?

dhelp is an online help system for Debian GNU/Linux. A Debian package can register its HTML documents and dhelp builds an index of all documents. The user doesn't need a WWW server to browse the HTML tree.

How to use dhelp

If you have installed a WWW server on your system simply browse

http://localhost/doc/HTML/index.html

If you haven't installed a WWW server use the dhelp command:

$ dhelp

The .dhelp file

Programs supporting dhelp have to install a .dhelp file in every directory under /usr/share/doc. For every HTML file that should appear in the dhelp index the .dhelp file have to contain the following section:

<item>
<directory>: Defines in which section of the index the document should be linked. I suggest that you use the same names like in Section: in control. For example for a game you would use games. A German document should linked to de/games and so on. You can find all supported sections in .dhelp. You can create additional sections if necessary.
<dirtitle>: Defines the title of a new section.
<linkname>: This short text appears as link text in the index. This is typical the filename without the .html suffix.
<filename>: The filename of the HTML file with a path relative to the .dhelp file. If your document is called /usr/share/doc/dhelp/test.html and the .dhelp is installed in /usr/share/doc/dhelp you must use test.html.
<description> ... </description>: A long description of the content of the document (optional).
</item>

You can have only one tag per line! Something like the following will not work:

<item><directory>de/foo
  <dirtitle>The foo section
  <linkname>foo
 <filename>foo.html
<descrip>foo foo foo</descrip></item>

You have to use this:

<item>
<directory>de/foo
<dirtitle>The foo section
<linkname>foo
<filename>foo.html
<descrip>
foo foo foo
</descrip>
</item>

You can have several <item> sections in one .dhelp file.

Add a .dhelp file to the index

To add a .dhelp file to the document index you have to call dhelp_parse:

# dhelp_parse -a /usr/share/doc/directory

I would suggest to add the following to your package postinst script:

if [ -f /usr/sbin/dhelp_parse ]; then
  /usr/sbin/dhelp_parse -a /usr/share/doc/directory
fi

In prerm you should use:

if [ -f /usr/sbin/dhelp_parse ]; then
  /usr/sbin/dhelp_parse -d /usr/share/doc/directory
fi

Or you can use the script dh_dhelp. This script installs the debian/dhelp file in /usr/share/doc/package and creates the postinst and prerm scripts of all .dhelp files found in /usr/share/doc.

Scripts for .dhelp file

sgml2dhelp

If the HTML files were produced by the sgml-tools (linuxdoc-sgml) you can use the script sgml2dhelp.pl. This script produces a .dhelp, a .dwww-index, and a index.html file.

Run this script in every directory containing HTML files. You have to call the script with to options:

sgml2dhelp <dhelp section> <dwww section>

If your documents should go in the German HOWTO section for example, you have to enter:

# dhelp.build de/HOWTO general

dhelp2dwww

If you have written a .dhelp, you can convert it to a .dwww-index file with the script dhelp2dwww.pl.

dhelp2dwww <dwww section>

What can I do for dhelp?

If you like dhelp please ask maintainers of Debian packages including HTML documentation to add dhelp support.

If you have any comments or problems please feel free to send an email to the dhelp package maintainer: dhelp@packages.debian.org