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><directoy>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 .dh