Handhelds.org - Open source for handheld devices

UserPreferences

GpeHelpSystem

GPE Help system

All help is stored in /usr/share/doc/gpe (well that is the preferred location anyway). When an application has help available normally there will be a help button visible. If one presses on the help button the help will be displayed in a window of another application. (by preference the gpe-helpviewer) The possible applications are hardcoded in libgpewidget and are in the following order : gpe-helpviewer gpe-mini-browser dillo minimo .

If you press on the home button in the gpe-helpviewer this will take you to the index of all available help on your device. This is /usr/share/doc/gpe/help-index.html and can be regenerated as root with gpe-helpindex (part of the gpe-helpviewer package).

GPE User Documentation file format

We should use docbook/XML as master file format to produce doc in any format we wish,

Docbook/XML is also used by GNOME Documentation Project. See for reference,

Some help might be immediately available from the wiki-pages etc... in pure html.

Previous thoughts about help file formats

I'd suggest to use some different data format for help files, this has two reasons:

- PDF is a language that describes pages of a fixed format. We have devices that differ in screensize very much.

- PDF files are large.

We should use plain HTML or Plucker for help.

The advantage of HTML is that it has not much overhead, there is usually a HTML browser installed and it performs well on changing display sizes. A disadvantage is that images need to be included in separate files.

Plucker files contain all data, but i don't know how good it works on different screen sizes.

GPE help viewer

A bitbake file for the gpe-helpviewer can be found in the OpenEmbedded tree, the source is in GPE cvs.

Adding help to GPE (documentation and/or adding help to an application)

This will be done with as example gpe-edit. First you need some text/contents to write up a decent help page. Preferably you do that while testing out all the options of the program you want to document. Preferably you generate a docbook file (see higher), but the minimum requirement is a simple html page.

Next thing to do is edit the application interface to add a help button. The best thing to do is using the stock help symbol, so that all applications have the same help button making it easier on the user. Of course we will only display the button if there really is help (to spare screen estate and not confuse the user)

example : (look into gpe-edit/main.c)

if(gpe_check_for_help(appname) != NULL)

The gpe_check_for_help function takes a pointer to a string. In this gpe-edit example this is const char *appname = "gpe-edit"; . This function returns a string containing the filename (but does not test if it really exists) so if the return value is different from NULL, there is some help registered. (Registered help has an entry in /etc/gpe/gpe-help.conf, but this will be addressed later).

Next thing to do is actually show the help when the button is pressed :

We have registered a callback in the previous code called show_help. This will make sure that a press on the help button will execute the show_help function in our application code that is in it easiest form :

static void
show_help (void)
{

}

This will call the gpe_show_help function with two parameters were the second one is optional. Like in this case were the help is so small no topics are needed (thus this string is set to NULL). gpe_show_help will return FALSE if the help file actually exists and is readable by the user. Then it will check for the help-viewer applications in the following order : gpe-helpviewer gpe-mini-browser dillo minimo and call the first one with the correct url to make it display the help.

If there is an error. Like the help file is not readable, there is no application to display the help, ... we warn the user by popping up an error box.

*WARNING* : Do not forget to include gpe/gpe-help.h !

Ok now the application is prepared we just need to add the correct post-install and post-rm scripts to the bb file of the application. (for more info about bb files check out OpenEmbedded). This is the bb file for gpe-edit with the post-install and post-rm scripts in it. Also we make sure that the help html file gets in the gpe-edit-doc package by placing it in a doc dir in the root of the source dir.

LICENSE = "GPL"
inherit gpe

DEPENDS = "gtk+ libdisplaymigration libgpewidget"
MAINTAINER = "Phil Blundell <pb@handhelds.org>"
SECTION = "gpe"
DESCRIPTION = "Editor for the GPE Palmtop Environment"

pkg_postinst_${PN}-doc () {

}

pkg_postrm_${PN}-doc () {

}

In both scripts we test for the existance of the help config file, if it is not there we will create it in the post-install script. Then we either add or remove the entry (or entries) for our application. This makes sure that our help has been registered. Registered help has an entry in /etc/gpe/gpe-help.conf as follows app-name = full/path/to/application/help. For our example (and if the gpe-edit help is the only help installed) /etc/gpe/gpe-help.conf would look like this:

[Help]
gpe-edit = /usr/share/doc/gpe/gpe-edit.html

As a last step we generate the index for the helpviewer after having tested if we actually have the gpe-helpindex program that comes with gpe-helpviewer.