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

Help Browser Preprocessor

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:

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:

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.


Copyright © 2009 Nokia Trademarks
Qt Extended 4.4.3