KDE Help System README
~~~~~~~~~~~~~~~~~~~~~~
This is an alpha release of the KDE Help system.

The viewer is really just an HTML viewer (based on the KDE HTML widget)
with built-in filters for info and man (including links to other man pages :-).


BUILDING:

1. You will require:
      Qt-1.2          (or greater)
      kdelibs-0.9.02  (or greater)
      khtml-0.5.5     (or greater)
2. Make sure you have QTDIR and KDEDIR environment variables
3. Check install paths in Makefile
4. type make
5. type make install


USAGE:

The viewer may be started using a URL to display a file, e.g:

	kdehelp file:/usr/local/src/qt/html/index.html

URL's have been added for info and man, e.g.

	kdehelp "info:(gcc)G++ and GCC"

	kdehelp "man:strcpy(3)"

		or just

	kdehelp man:strcpy

If no command line parameter is supplied, a nice opening page is displayed
with links to general KDE stuff, KDE application index, man index, and info
index.

Alternatively, a file or URL may be opened using menus or dragged from
Torben's kfm file manager.

Bookmarks support folders, but there is no graphical way to create them at
the moment.  Folders may be created manually - use netscape's bookmarks file
as a guide.  Bookmarks file: $HOME/.kde/kdehelp/bookmarks.html


LAUNCHING FROM YOUR PROGRAM:

To open a kdehelp window, call:

kapp->invokeHTMLHelp( QString aFilename, QString aTopic )

e.g.

kapp->invokeHTMLHelp( "kmyapp/main.html", "saving" );

This will open a new help window if kdehelp is already running or start a new
kdehelp session otherwise.  Only one instance of kdehelp will be run per
user.  It is assumed that the documentation is located in $KDEDIR/doc/HTML/


THE KDE HELP INDEX STUFF

kdehelp uses the [KDE Desktop Entry] method of kpanel to maintain a help
index of KDE applications.  Currently a sample is installed in
 $KDEDIR/apps
It is a simple format:

[KDE Desktop Entry]
Exec=kapp                        ; executable for kpanel
Name=KApp                        ; optional name of application
DocPath=kapp.html                ; help file path relative to $KDEDIR/docs/HTML
Info=Another excellent KDE app   ; a description of the program
Icon=iconname.xpm                ; for kpanel

and install it in the appropriate location, e.g.

$KDEDIR/apps/Productivity/KApp.kdelnk

if DocPath is not specified, no entry will be added in kdehelp.
EVERY KDE application should provide one of these files!!!


TODO:

bookmark manager
more options
help controller (control help from your app)
more accelerators
remote file stuff via kfm
extend search to include info
do a descent info parser
lots of other stuff - what do you want?


Martin Jones
mjones@kde.org

