Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Help Browser Preprocessor

- Introduction
- Syntax
  - AND
  - OR
  - Variable Substitution
- Qtopia Documentation
  - Tags
    - Examples
- hpp script (for compile-time pre-processing)

## Introduction

The Help Browser Preprocessor is an extension to Help Browser that enables the maintenance of a single source of html help files from which device-specific help can be extracted.

The Help Browser Preprocessor is flexible so that different configuations are possible (eg, KEYPAD PDA, CLAMSHELL KEYPAD PHONE). The supported syntax includes AND logic, OR logic and variable substitution.

## Syntax

The Help Browser Preprocessor supports AND and OR logic when including blocks of text. Place the %% (start) tags at the beginning of the section of text that is to be included in that build and the @@ (close) at end of the text.

### AND

    %%tag1%%
    %%tag2%%

Note: Interleaving is not a problem: the tags can be closed in any order and both of the following are valid examples of how to close the above:

    @@tag1@@
    @@tag2@@

    @@tag2@@
    @@tag1@@

Here's an example of complex interleaving (this is not recommended usage, but it is still valid):

    %%CONFIG1%%
    some stuff
    %%FEATURE1%%
    this is for CONFIG1 and FEATURE1
    %%FEATURE2%%
    this is for CONFIG1, FEATURE1 and FEATURE2
    @@CONFIG1@@
    this is for FEATURE1 and FEATURE2
    @@FEATURE1@@
    @@FEATURE2@@

### OR

The OR syntax can be used to indicate that certain text should be present in the PDA and the Touch Phone builds. In this case the pre-processor reads that if PDA or Touch Phone then include this text in the build.

    %%tag1%% %%tag2%%

Note: the closing tags must appear in the same order. The following is valid:

    @@tag1@@ @@tag2@@

The following is not valid:

    @@tag2@@ @@tag1@@

### Variable Substitution

The string $${FOO} is replaced with the value of the variable FOO. You can escape the variable to prevent it from being replaced. \$${FOO} will appear in the output as $${FOO}. The name of a variable must match the regular expression [a-zA-Z0-9._]+.

The syntax for setting a variable is:

    {VarbialeName}={The text to replace it with}

Note: This must be at the start of the line.

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

    %%tag1%%
    {FOO}={Foo}
    @@tag1@@
    %%tag2%%
    {FOO}={Bar}
    @@tag2@@

Note: It is not considered an error to reference a non-existant variable (but it produces no output).

Here is an example of variable substitution in use:

    %%tag1%%
    {FOO}={Foo}
    @@tag1@@
    %%tag2%%
    {FOO}={Bar}
    @@tag2@@

    <p>The button is called $${Foo}</p>

## Qtopia Documentation

### Tags

The following tags are available for Qtopia Documentation:

- PDA - PDA
- Keypad Phone - KEYPAD PHONE
- Touchscreen Phone - TOUCH PHONE

Through the use of these tags it is possible to build the help documentation for the keypad phone and automatically exclude all files and content related exclusively to the touch phone (tag=TOUCH) or the pda (tag=PDA) and all documentation related to both the touch phone and the pda (tags=PDA TOUCH with the appropriate start and close symbols).

#### Examples

    %%PDA%%
    Stuff for the PDA
    @@PDA@@

    %%PDA%% %%TOUCH%%
    Stuff for the PDA or Touchscreen Phone
    %%PDA%%
    Here's some PDA specific stuff in the middle
    @@PDA@@
    Here's some more PDA/Touchscreen stuff
    @@PDA@@ @@TOUCH@@

    %%PHONE%%
    Stuff for any Phone
    %%KEYPAD%%
    Stuff for a Keypad Phone
    @@KEYPAD@@
    @@PHONE@@

## hpp script (for compile-time pre-processing)

Note: The use of hpp is not supported.

To avoid storing excess documentation, you can use the hpp script (in $QPEDIR/scripts) to do the preprocessing before the documentation is installed. The script is run as follows:

    hpp -c "CONFIG VALUES" -o /path/to/store/files/in -i 16 file1.html ... filen.html

The -i tells hpp which size icons to use (in this case, 16x16).

hpp uses the same parsing rules as the runtime help preprocessor so it should produce identical output.