Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Help Browser Preprocessor

• Introduction
• Syntax
• Flow Control
• Variable Substitution
• File Inclusion
• Command Execution
• Examples
• Valuespace Integration

Introduction

The Help Browser includes a preprocessor that allows a single source of html help files from which device-specific help can be extracted for presentation to the user. This allows packages to be distributed with on-line help that adapts to the user's actual device.

Syntax

The supported syntax is a subset of Server Side Includes (SSI). This syntax was chosen so that the documentation can alternatively be served by an appropriately-configured web browser.

Flow Control

SSI if-else-endif can be used (but not elif), with the expression being a set of variable references separated by "||". Variables that are non-empty are "true" and variables that are empty (or not defined) are "false".

    <!--#if expr="$CELL || $VOIP"-->
    ...
    <!--#else-->
    ...
    <!--#endif-->

The following variables are pre-defined (or not, depending on configuration) for Qt Extended Documentation:

• VOIP - Device supports VoIP (determined by build time configuration)
• CELL - Device supports cellular telephony (GSM or other) (determined by build time configuration)
• TELEPHONY - Device supports some form of telephony (determined by build time configuration)
• INFRARED - Device supports Infrared beaming (determined by build time configuration)
• BLUETOOTH - Device supports Blueooth beaming (determined by build time configuration)
• TOUCH - Device has a touch screen as the primary input (see Qtopia::mousePreferred())
• KEYPAD - Device has a keypad as the primary input (see Qtopia::mousePreferred())
• FLIP - Device can open/close (if Qt::Key_Flip is available)
• CLIPBOARD - Device supports clipboard functionality (i.e. not configured with -D QT_NO_CLIPBOARD)
• MULTISCREEN - Device supports more than one screen (e.g. primary and secondary displays on a flip phone)
• VPN - Device supports Virtual Private Networking
• USERGUIDE - Not on device - intended for printed manual

Variable Substitution

The string

    <!--#echo var="MYVAR"-->

is replaced with the value of the variable MYVAR.

The syntax for setting a variable is:

    <!--#set var="MYVAR" value="some text"-->

It is usually useful to define variables inside configuration blocks. Like this:

    <!--#if expr="$CELL"-->
     <!--#set var="YOURDEV" value="your cellphone"-->
    <!--#else-->
     <!--#if expr="$TELEPHONY"-->
      <!--#set var="YOURDEV" value="the phone"-->
     <!--#else-->
      <!--#set var="YOURDEV" value="the device"-->
     <!--#endif-->
    <!--#endif-->
    ...
    Do not wash <!--#echo var="YOURDEV"-->!

File Inclusion

The string

    <!--#include file="FILENAME"-->

is replaced with the contents of the file FILENAME, which is recursively processed in the manner described here.

One use for this is device-specific documentation. The Qt Extended help attempts to put anything that might vary between devices into a device-specific file. These files all start with "device-" (such as "device-keys.html" and "device-name.html"). By replacing these files, the Qt Extended help can document a different device.

Command Execution

The string

    <!--#exec cmd="CMD ARGS"-->

is replaced with the output of the command CMD.

For security reasons only a fixed set of built-in commands are permitted:

•      qpe-list-content type

  - list content of a given type (eg. "Applications")

•      qpe-list-help-pages filter

  - list and link help pages (eg. "foo-*.html")

Examples

    <!--#if expr="$CELL"-->
    Stuff for the cell phone...
    <!--#endif-->

    <!--#if expr="$TELEPHONY"-->
    Stuff for any Phone
    <!--#if expr="$KEYPAD"-->
    Stuff for a Keypad Phone
    <!--#endif-->
    <!--#endif-->

    <!--#include file="device-colors.html"-->
    Press the <!--#echo var="color-offswitch"--> button to turn off the device.

Valuespace Integration

The preprocessor can set variables to the result of valuespace expressions. The syntax is:

    <!--#set var="MYVAR" valuespace="1 + 1" value="some text"-->

The valuespace attribute can be any valid QExpressionEvaluator expression.

The value attribute is used by SSI implementations that do not support the valuespace attribute and is not used by the help preprocessor.

The existence of a valuespace keys can be tested for with the syntax:

    <!--#set var="MYVAR" valuespace="exists(@/ValueSpace/path)" value="some text"-->

To minimized the number of files that use nonstandard SSI features a single file should be used to set variables from valuespace expressions. Other help files can make use of these variables by using File Inclusion.