# Aleppo example projects

## Contents

- Overview
- About the example projects
- Help project configuration

- Standard directory structure
- Aleppo source files — Boss Puzzle

- Inserting new topics
- Formatting text using style marking
- Graphics within topics
- Changing the topic display order
- Improved topic searching using synonym style-marking
- Customising the appearance of topic text
- Compiling help databases
- Delivering help databases

## Overview

This section describes the configuration of a typical project, including directory structure and source files. Furthermore, it demonstrates how styles are used to create new topics, format topic text, insert graphics and set keywords for topic searching.

The chapter makes use of examples from the Boss Puzzle and Aleppo Help EPOC Help projects, which are located in the directory `\aleppo\projdir\`.

## About the example projects

The Boss Puzzle game was popularised in the late 1800s by the American businessman Samuel Lloyd. It consists of a 4x4 grid of tiles, one of which is missing. The object of the game is to correctly re-order the 15 tiles (in the original form, tiles 14 and 15 were swapped round).

  Boss ordered board

The Boss puzzle game is the application developed in the EPOC Tutorial. The example help project, `BossPuzzle.hlp`, is its supporting help database.

The Aleppo Help database (`AleppoHelp.hlp`) is an EPOC based guide for using `aleppo`, which will run on either the Emulator or a target device. It contains useful information on how to configure `aleppo` source files, and can be used as an additional reference by help authors. Unlike most help files, it is not directly associated with an EPOC application.

The rich-text, project, customisation, and order source files for both projects are stored in the project directory `\aleppo\projdir\`. The files should be used as a further reference of `aleppo` project source documents, and/or as the basis for new projects. In addition, compiled reference help files are provided, and are located in the directory `\aleppo\projdir\releases\`.

## Help project configuration

Section Contents

- Standard directory structure
- Aleppo source files — Boss Puzzle

- Project source file
- Rich-Text source file

### Standard directory structure

Aleppo Help projects are built on a PC under Windows. Every help project must be contained within a project directory (e.g. `projdir\`), which should be located in the `\aleppo\` directory.

  aleppo project directory structure

As shown in the preceding figure, it is good practice for `projdir\` to contain the three sub-directories:

- `Pictures\` - contains the pictures used in the help file (`.mbm` files).
- `Releases\` - contains generated help files.
- `Temp\` - for holding aleppo working files.

The project’s source files are typically stored in the `projdir\` directory. They consist of the Project File, Order File, Customisation file and RTF Source files.

### Aleppo source files — Boss Puzzle

The mandatory source files needed to generate the Boss Puzzle help database are the project file `Boss.alp`, and the rich-text source file `BossPuzzle.rtf`. The order (`BossPuzzle.order`) and customisation files (`uk.alc`) are optional, and are hence discussed under the relevant sections (see Changing the topic display order and Customising the appearance of topic text, respectively).

#### Project source file

`Boss.alp` project file, shown below, defines the location of all resources used by the project. The Boss Puzzle help project follows the standard structure (e.g. the project is contained in the directory `\aleppo\projdir\`, which itself contains `temp\`, `releases\`, and `pictures\` directories). `Boss.alp` is the second parameter passed to `aleppo` when the boss puzzle help database is compiled (see topic Compiling help databases).

        inputdirectory \aleppo\projdir\
        outputdirectory \aleppo\projdir\releases\
        outputfile BossPuzzle.hlp
        sourcefile BossPuzzle
        orderfile BossPuzzle.order
        graphicsdirectory \aleppo\projdir\
        workingdirectory \aleppo\projdir\temp\
        customizationfile \aleppo\projdir\uk.alc

The project file syntax is described in the topic Project files.

#### Rich-Text source file

The rich-text source files used for `aleppo` development are based on the `EPOCHelp.dot` MSWord template. The template has been set up to mimic the appearance of the output help database on the series 5. This aids previewing during development, and highlights the constraints imposed by limited screen size.

The following example shows a segment of the `BossHelp.rtf` rich-text source file, which is based on the `EPOCHelp.dot` MSWord template. The styles applied to each section of text are shown in the left hand column. The first lines of text form an introduction to the document (`Comment` style). Text marked in the `Comment` style is not converted by `aleppo`, so the document introduction does not appear in the final database.

The text marked with `Heading 1` and `Heading 2` styles are the application and topic names, respectively. In a stand-alone help database the application name need not be defined, however in a database containing topics for several applications, the name can be used to group each application’s topics. The text marked in `Normal` style forms the main body text for the topic.

The `Hypertext Anchor` style is used to mark a topic’s order-name (see topic Changing the topic display order) while the `Graphic Link` style indicates to `aleppo` that a picture is to be inserted in the output database (see topic Graphics within topics).

The file fragment, when compiled, appears in EPOC as below:

## Inserting new topics

Topics have mandatory heading and body fields, and optional order and synonym fields. To create a new topic requires only that the author mark the title text with the `Heading 2` style. The body text is then all following text up until the next topic title (excluding text marked in the `Hypertext Anchor` or `Synonym` styles).

Topic title fields must occupy a single paragraph. A title field of multiple paragraphs defines empty topics (e.g. in the code below, Topic Title 1 is an empty topic).

Selecting New Topic from the EPOC menu on the `EPOCHelp.dot` template automatically inserts the fields for a new topic, including the optional topic name for sorting (order-name) and synonym fields.

## Formatting text using style marking

Styles are applied by selecting the text to be marked, and then applying a format from the template’s style-list. It is important to note that except for bold, italic, subscript and superscript, styles that are not in the style-list are not converted by `aleppo`. An implication of this is that, for example, bullets created using the `List Bullet` style are compiled, while those created using the MSWord bullet button are not.

E.g. to produce a bulleted list, use the style-marking:

to produce:

The `EPOCHelp.dot` template has been configured so that the text in source rich-text files looks similar to how it will appear in the final help database. It is important to note that the similarity is merely a convenience to users, since `aleppo` compiles solely on the basis of styled markup and customisation file settings. Hence, for example, doubling the font size of the `Normal` style in a source `.rtf` file does not double the font size in the output database.

## Graphics within topics

Graphics can be inserted into topic body text during `aleppo` conversion. `Aleppo` uses references in `Graphic Link` style to determine which images to load (pictures must be stored in the .`mbm` multiple bitmap file format, generated from Windows bitmaps using the `bmconv` tool).

Consider the text fragment below, which is used to insert a picture of the Boss Puzzle board into the topic. The text specifies that the picture is called `Ordered-Board.mbm`, and is stored in the directory `Pictures\`. The archive directory must be contained within the folder specified in the `graphicsdirectory` field of the project file (`\aleppo\projdir\`).

##### Note

- Aleppo also checks the files for an alternative definition of the graphic style mark, in which the archive is a multi-bitmap file, and the picture to be inserted is the name of one of its contained bitmaps. In this case, the `graphicsdirectory` field of the project file is the directory in which the multi-bitmap archive is stored.

## Changing the topic display order

Topics are ordered by the position of their order-name within the Order File (rather than the sequence in which they appear in the rich-text source file). The order-name for a topic is defined in `Hypertext Anchor` style, and appears directly below the topic title.

In the example above, taken from the source file `AleppoHelp.rtf`, the topic Elements of a Help Project has the order-name `aleppo.project-elements`. The order file `AleppoHelp.order` lists this name second, and hence the topic Elements of a Help Project will appear second in the final database.

        aleppo.quick-start
        aleppo.project-elements
        aleppo.set-up
        aleppo.project_file
        aleppo.rtf_source
        aleppo.order_file
        aleppo.custom_file
        aleppo.running

Order names can be in any language or format, and need not be related to the topic title. Consequently, Order Files are largely immune to localisation issues. Topics which have no order name, or which have an order name which is not used in the order file, are ranked alphabetically in the final database (after the ordered topics).

## Improved topic searching using synonym style-marking

The ease with which a specific topic can be located within an EPOC help database may be improved by adding synonyms, or additional keywords, to the topic. These keywords are defined in `Synonym` style, and appear before topic body text in the rich-text source file.

Topic keywords typically include synonyms, alternative spellings, and even common misspellings. In the file `AleppoHelp.rtf`, the topic Creating a Customisation File has keywords: Localisation, Localization, Localise, Localize, Customise, Customize, Customization, and source. Hence in addition to searching for the words Creating, Customisation and File, the database engine also searches for the US spelling Customize, the alternate topic Localise (and its US spelling), and under the general topic source. The keywords might also have included Making, Generating and Building, to provide some alternative for Creating.

There is a 254 character database limit for the synonym field associated with each topic. Users may specify more than this number of synonym characters, however all text after the 254th character is ignored by `aleppo`.

## Customising the appearance of topic text

The appearance of text within a help database is dependent on the text file declared after the Project File’s `customizationfile` field. If no file is declared, or if a file cannot be found at the specified location, a default set of style definitions are applied. The default style (Default customisation file) is similar to that declared in the customisation file `\epoc32\tools\aleppo\uk.alc`, below, and results in an output which is similar in appearance to text in the `EPOCHelp.dot` template.

        <bodystyle fontstyle=sansserif size=10>
        <titlestyle fontstyle=sansserif size=14>
        <listbullet1style bulletchar=149>
        <listbullet2style bulletchar=45>
        <tipeffects text="Tip:" bold=yes leftindent=36>
        <noteeffects text="Note:" bold=yes leftindent=36>
        <importanteffects text="Important:" bold=yes leftindent=60>

The first word in each line defines the text type to which the style definition is applied. In the example above, the body style is defined as `fontstyle=`sansserif and `size=`10. This means that topic body text (marked as `Normal` style in the source rich-text file) is displayed in 10pt San Serif in the database. Similarly the title style (`Heading 2` style in the source file) is displayed as 14pt San Serif.

Text in `List Bullet` style is displayed in the help database with a preceding bullet symbol. This symbol is taken from position 149 in the symbol table, as defined by the line: `listbullet1style` `bulletchar=`149. Similarly, text in `List Bullet 2` style is preceded by character 45 in the final help database.

The `tipeffects`, `noteeffects` and `importanteffects` keywords apply style definitions to text marked as `Tip`, `Note`, and `Important` styles, respectively, in the rich-text source file. When `aleppo` encounters these style marks it inserts the appropriate text (e.g. Tip) in front of the marked text, as shown below.

Any text can be used for these effects, as long as it is placed between the inverted commas in the style definition `text=“`any-text`”`. The text below results when the customisation file replaces Note with AnyText.

It is also possible to precede text marked with `Tip`, `Note`, and `Important` styles with an icon (graphic). However this is not generally recommended, because it increase the size of the generated help file. Inserting graphics is discussed in greater detail in the reference topic (see Customisation files).

Text following the tip, note or important identifier is indented by an amount defined in the `leftindent=` field. In the example above, Tip, Note and Important text are all indented by 36 twips. For graphics this field is optional. If not defined, text is indented by an amount equal to the width of the graphic.

## Compiling help databases

When all of the project source files have been created, the help database is compiled using the following command.

        aleppo -epoc Project-File

The `-epoc` keyword informs `aleppo` that the output is to be an EPOC help database rather than a proofing HTML version. The command could also specify `-unicode` and `-compress` options to generate unicode and/or compressed help databases. The Project File defines the source documents and graphics used by the project.

An example project file for the stand-alone help file `BossPuzzle.hlp` was given in a previous topic, see Aleppo source files. The source file is stored in the project directory `\aleppo\projdir\` and can be used to compile the database into `\aleppo\projdir\release\`. To view the compilation process, go to `\aleppo\projdir\` and enter the following text on the command line.

        aleppo -epoc Boss.alp

A similar example project file is given below for the Aleppo Help project, `\aleppo\projdir\aleppohelp.alp`. The main difference between this and the Boss Puzzle help file, is that the source, order, and output files are different. The file can be compiled by entering the following text on the command line.

        aleppo -epoc AleppoHelp.alp

A help database combining the topics for both applications may be generated by invoking `aleppo` using the `comb.alp` project file below, which is also stored in `\aleppo\projdir\`. Note that the `sourcefile` keyword is followed by both BossPuzzle and AleppoHelp rich-text source files and that the `orderfile` used is `AleppoHelp.order`. This means that the compiled file will contain all the topics from both files, and will have the same initial topic order as the stand-alone `AleppoHelp.hlp` database. In a normal help database an alternative order file would be used to order the combined topics.

        inputdirectory \aleppo\projdir\
        outputdirectory \aleppo\projdir\releases\
        outputfile BossAleppo.hlp
        sourcefile AleppoHelp BossPuzzle
        orderfile AleppoHelp.order
        graphicsdirectory \aleppo\projdir\
        workingdirectory \aleppo\projdir\temp\
        customizationfile \aleppo\projdir\uk.alc

## Delivering help databases

Help databases are normally delivered to the target system as part of an EPOC `.sis` installation file. Files are typically placed in the same folder as the application with which they are associated. There is no standard location for help databases which are not associated with an application.

During development, authors can alternatively copy files to the EPOC system directly, using EPOC Connect.

##### Notes:

- Help databases are, by default, read-only. Hence users must change the file properties, in the `EPOC File | Properties` menu, to overwrite previous versions of a help database on an EPOC machine.