Author:Symbian Ltd.
Date:November 1998
Version:1.0
Aleppo Help File
Aleppo: quick start
aleppo.quick-start
This file describes the process of EPOC32 help authoring using aleppo. It assumes aleppo is already installed on your computer, and that you have a default \aleppo working directory.
To start authoring, read “Elements of a Help Project” and then follow the instructions in the topics up to “Running Aleppo”.

•	The source documents for this help file are included in the ADK example documentation. They demonstrate each of the elements of an EPOC 32 help project.
This Text is in Comment Style, and will not compile to the target EPOC platform

Elements of a Help Project
aleppo.project-elements
source files documents 
Every help project is comprised of a project directory containing four source files and three sub-directories, as described below.
Project Directory : To hold the entire project. It should be located within the \aleppo directory (created during installation). 
Project File : Defines the location of all resources used by the project (eg graphics files, source files, working directories).
RTF Source File : Contains the style-marked topic headings and text.
Order File : Defines the order in which selected topics appear in the compiled database.
Customisation File : Defines the appearance of style-marked text in the converted help database. The file also controls certain language dependent style features.
Pictures Sub-Directory : An archive of pictures used in the help file. 
Releases Sub-Directory : An archive of old help files.
Temp Sub-Directory : Contains aleppo working files.

Could insert a picture of an example file structure here!

Setting up a Help Project
aleppo.set-up
create creating
Help projects contain the elements described in the previous topic (“Elements of a help project”).
To set up a project  
1.	Create a work folder in \aleppo for your project, e.g. \aleppo\ProjectName.
2.	Create the folders: \temp, \pictures and \releases within the work folder. 
3.	Create the plain-text files: ProjectName.alp, ProjectName.order, and ProjectName.alc in the work folder. Amend the files as described in the topics “Creating a Project File”, “Creating an Order File”, “Creating a Customisation File” respectively.
4.	Create a rich-text file ProjectName.rtf based on the MSWord template EPOCHelp.dot (installed with aleppo). This is the starting point for the new help source file.

•	Most projects will have similar project and customisation file structure. It is often easier to copy and edit a project, than to generate the files from scratch. The source file names and contents can then be changed for the new project.

Creating a Project File
aleppo.project_file
source
The Project File (see topic “Project files”) defines the locations of all resources in the project. 
To create a project file: 
1.	Create a text file (NotePad).
2.	Type in the keyword inputdirectory, followed by the name of the project work directory.
3.	Type in the keyword outputdirectory, followed by the name of directory in which the help database is to be created. The standard output folder is the "Documents" folder of the EPOC32 emulator, allowing immediate testing of compiled help files.
4.	Type in the keyword outputfile, followed by the name of the new help database.
5.	Type in the keyword sourcefile, followed by the name of the rich-text source file/s.
•	Do not use the file extension (.rtf).
•	The source file/s must be located in the directory inputdirectory.
6.	Type in the keyword orderfile, followed by the name of the project order file.
•	The order file must be located in the directory inputdirectory.
7.	Type in the keyword graphicsdirectory, followed by the name of a directory containing picture archives.
•	If the graphics archive is the directory \ProjectName\pictures then the graphics directory is \ProjectName.
8.	Type in the keyword workingdirectory, followed by the name of a directory aleppo can use for storing working files.
9.	Type in the keyword customizeationfile, followed by the path and name of the customisation file.
•	A standard customisation file uk.alc can be found in \epoc32\tools\aleppo.
10.	Save the file in the project work directory (e.g. \aleppo\ProjectName). Any file name can be used, however the extension must be .alc.
•	The easiest way of creating a project file is to copy an existing file and modify the resource locations.
•	A sample file can be viewed in the topic “Example Project File”
•	Directories are specified with a trailing \.
•	The target format of the conversion is not defined in the project file (EPOC32 help database or HTML). This is supplied to aleppo as a command line argument. 
•	Any number of source RTF files can be compiled into a single help database. Simply add the names of all the source files to the sourcefile line. Filenames must be separated with spaces as shown below:
sourcefile 
EPOCHlp1 EPOCHlp2 EPOCHlp3

Example Project File

inputdirectory   
\aleppo\ProjectName\
outputdirectory
\epoc32\wins\c\Documents\
outputfile       
Project.hlp
sourcefile       
ProjectName
orderfile          
ProjectName.order
graphicsdirectory
\aleppo\ProjectName\
workingdirectory
\aleppo\ProjectName\temp\
customizeationfile
\epoc32\tools\aleppo\uk.alc

Project File
The project file is a plain-text file with a .alc extension. It is used by aleppo to determine the location of all resources used by the project. 
The format of an aleppo document is given below:
inputdirectory           
input-directory-name
outputdirectory         
output-directory name
outputfile                  
output-file-name
sourcefile                
source-file-name-list
orderfile                  
order-file
graphicsdirectory      
graphics-directory
workingdirectory      
working-directory
customizeationfile     
customisation-file

•	
where
•	input-directory-name specifies the directory containing all source RTF files. Typically this is the project directory \aleppo\Project
•	output-directory-name specifies the target directory for the new help database. The standard output folder is: \epoc32\wins\c\Documents    (the "Documents" folder of the EPOC32 emulator.
•	output-file-name specifies the filename of the generated help database. It is created within output-directory-name.
•	source-file-name-list specifies the filename/s (without .rtf extensions) of all RTF source files in the project. An arbitrary number of source files may be specified (any order), however the application name for each source file must be unique. All input source files must be located in the directory input-directory-name.
•	order-file specifies which order-file aleppo should use to define the topic order in the generated help database (see topic “Order File”).
•	graphics-directory specifies the directory containing the help database’s picture archives. An individual graphic is referenced by graphics-directory and then archive name (in the rtf).
•	working-directory specifies the name and location of aleppo’s working directory. This directory should be reserved exclusively for the use of aleppo. Work files are not deleted after an aleppo run.
•	customization-file specifies the name and location of the project customisation file.
•	An example of a typical project file is provided in the topic “Creating a Project File”.
•	If any file or directory name is specified as a relative path, such as ..\graphics\, or \help\agenda\, then it is resolved against the drive and directory which was current when the aleppo command was issued.
•	All directories must be specified with a trailing \.
•	The target format of the conversion is not defined in the project file (EPOC32 help database or HTML). This is supplied to aleppo as a command line argument. 

Creating an RTF Source File
aleppo.rtf_source
The rich-text source file contains the actual text to be displayed in the help database. The MSWord template “EPOCHelp.dot” provides the starting point for new help RTF files.
To create an RTF source file: 
1.	Open a new MSWord document using the template “EPOChelp.dot” (installed with aleppo). 
•	The new document opens with entry fields for author, date, version, application name, topic title, topic name (for sorting), topic synonyms and topic text.
2.	Enter file information (author, date and version) next to the appropriate template fields.
•	The file information is in “Comment” style and hence is not displayed in the final help database.
3.	Replace the Application Name text (“Heading 1” style) with the database title. 
•	The title associates each topic with an application (Necessary when the help database contains help for several applications).
•	All topics must have an application name. An application name such as General is used to describe functions not associated with any application.
4.	Replace the Topic title field (“Heading 2” style) with a topic for the application. 
•	The title must be a single paragraph.
•	The topic must be unique to the help database.
•	The title need not be the first topic to be displayed (topic order is defined in the Order File).
5.	Replace the Topic name for sorting field (“Hypertext Anchor” style) with a sorting name. The position of this name in the order file defines display order in the converted database.
•	This field is optional (may be deleted). If no topic name is defined then the topic is displayed alphabetically (after ordered topics).
6.	Replace the Synonyms for the topic field (“Synonyms” style) with alternative keywords for the topic.
•	The search engine will use the title and synonyms to locate topics. Synonyms might be alternative spellings, or even mis-spellings (eg “Sinonyms”).
•	The synonym field is optional (may be deleted).
7.	Replace the Topic text field (“Normal” style) with the topic text. Diferent formatting can be applied to the text (see topics “Styles”, “Style Marking” and “RTF Source Files” for more information).
8.	Further topics can be added by running the “New Topic” macro Ctrl+T. Alternatively, a new topic can be created by changing the title text to “Heading 2” style.
•	Copy/Paste on an existing topic is also effective.
9.	Save the topic as a rich text (.rtf) file in the project directory. The filename should not contain any spaces.

•	Authors should amend the Project, Order and Customisation files to reflect the new source file name, topic order, and topic style appearance.
•	Create any graphics files to be used in the help file and place them in the appropriate graphics files folder.
•	Create an RTF file for each “application” in the project directory. Any number of source RTF files can be compiled into a single help database. Simply add the names of all the source files to the sourcefile line of the Project File.

Creating an Order File
aleppo.order_file
invoking initializing invoke initialize source
The Order File (see topic “Order files”) defines the display order of topics within the help database. 
To create an order file: 
1.	Create a text file (NotePad).
2.	Type in the order name for the topic that is to be displayed first. This order name is immediately below the topic title in the rich-text source file (“Hypertext Anchor“ style).
3.	On subsequent lines type in the order names matching the order in which the topics are to be displayed.
4.	Save the file in the project work directory (\aleppo\ProjectName). Any file name may be used, however the extension must be .order.
•	The new Order File name must be entered in the orderfile field of the Project File.
•	A sample file can be viewed in the topic “Order File”.

Creating a Customisation File
aleppo.custom_file
Localisation Localization Localise Localize Customise Customize Customization source
The Customisation File (see topic “Customisation Files”) defines the appearance of style-marked text in the converted help database.
To create a customisation file:
1.	Create a text file (NotePad).
2.	Type in the text given in the topic “Example Customisation File”.
3.	Save the file in the project work directory (\aleppo\ProjectName). Any file name may be used, however the extension must be .alc
•	The new Customisation File name must be entered in the customizeation field of the Project File.
•	In practice the Customisation File rarely needs to be altered. Hence most Project Files can be mapped to the standard file UK.alc in the \EPOC32\tools\aleppo directory.

Running Aleppo
aleppo.running
start starting
aleppo’s operation is controlled from a project file, which is passed as the second argument when the program is invoked. The first argument is either -epoc32 or -html (depending on whether the output is to be an EPOC32 Help Database or an HTML proof copy).
To create an EPOC32 Help Database:
1.	Open an the MS-DOS window.
2.	Type aleppo -epoc32 project-file at the command prompt.
3.	View the output on the WINS Emulator or a Series 5.
To create an HTML proofing copy:
1.	Open an the MS-DOS window.
2.	Type aleppo -html project-file at the command prompt.
3.	View the output on an html browser.

•	The Project, Order, Customization and source RTF files must all be set up prior to invoking aleppo.
•	The HTML proofing option allows style debugging of files (it is difficult to get access to the inner workings of the EPOC32 database format.

RTF Source File
Topic information is stored as style-marked text (see topic) within an RTF source file. aleppo uses a small set of style markings (in conjunction with the customisation and order files) to resolve the help file into its title, order, synonym, and text formatting components. 
As a result ONLY THE STYLES SUPPORTED BY ALEPPO WILL TRANSLATE TO THE HELP DATABASE.
These styles are encapsulated in the EPOCHelp

Example RTF Source File
TOPIC UNDER CONSTRUCTION
It is not possible to include a sample text file because the EPOC32 help database cannot show the “style” information. Users

Author: (“Comment” style)
Date: 
Version: 
-----------------------------------------------
Topic title (“Heading 2” style)
Topic name for sorting (“Hypertext Anchor” style)
Synonyms for the topic (“Synonym” style)
Text for topic (“Normal” style)
+ (“Tip” style)
- (“Note” style)

Order Files
source hypertext anchor
Order Files define the order in which topics are displayed in the final help database. The topics are ranked by order name (the field below the topic title defined in “Hypertext Anchor” style).
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.
Example file : App.order
application.topic_1
application.topic_2
...
application.topic_n
•	In the final database, topics without an order name are ranked alphabetically (after the ordered files).

Customisation File
Localisation Localization Localise Localize Customise Customize Customization
Construction const
TOPIC UNDER CONSTRUCTION

Example Customisation File
Customise Customize Customization
<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>

Test topic
Synonyms for the test topic
•	This is a test help file, not an example!  Use this file when testing Aleppo installation.  Do not necessarily follow its style.  In particular, this help file makes inappropriate use of embedded graphics, which use a lot of space.  This is not recommended for real applications.
Normal. Text for the test topic. Menu commands look like this. And here's a picture archive=pictures name=exit-button of the exit button.
Normal text again. This normal text has had some manual formatting applied to it. This text is in bold. This text is in italics. This text is in superscript. This text is in subscript. This text is bold italic. This text is bold superscript. This text is bold subscript. This text is bold italic and superscript and this text is bold italic and subscript.
Definition Term. Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
Definition definition. Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
6	Important. Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
•	Note. Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
•	Tip. Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
1.	List number. Any old blurb to fill up the page, and to see what it will look like.
•	List bullet 2. Any old blurb to fill up the page, and to see what it will look like.
•	List bullet 2.
2.	List number. Any old blurb to fill up the page, and to see what it will look like.
List continue. Any old blurb to fill up the page, and to see what it will look like.
List continue.
This is a Comment!!! Any old blurb to fill up the page, and to see what it will look like.
Normal text again.
•	List bullet. Any old blurb to fill up the page, and to see what it will look like.
1.	List number 2. Any old blurb to fill up the page, and to see what it will look like.
2.	List number 2.
List continue 2. Any old blurb to fill up the page, and to see what it will look like.
•	List bullet.
3.	List manual 2. Any old blurb to fill up the page, and to see what it will look like.
9.	List manual 2.
Normal text again.
3.	List manual. Any old blurb to fill up the page, and to see what it will look like.
9.	List manual.

Synonym Style
Construction const
TOPIC UNDER CONSTRUCTION

Checklist
Construction const
TOPIC UNDER CONSTRUCTION

Error Messages
Troubleshooting errors
Construction const
TOPIC UNDER CONSTRUCTION

EPOC Help Template
.dot rtf source document
Construction const
TOPIC UNDER CONSTRUCTION

•	The page width in the Epochelp.dot template is designed to approximate the width of the default help display on a Psion Series 5 machine to give you an idea of how text will wrap. 

Formatting Columns
.dot rtf source document
TOPIC UNDER CONSTRUCTION

Numbering
.dot rtf source document
TOPIC UNDER CONSTRUCTION

Bullets
.dot rtf source document
TOPIC UNDER CONSTRUCTION

Compressed Format
.dot rtf source document
TOPIC UNDER CONSTRUCTION

Style Marking
rtf source
TOPIC UNDER CONSTRUCTION

EPOC32 Help Database Structure
TOPIC UNDER CONSTRUCTION

Text for topic

Styles
style marking rtf source
TOPIC UNDER CONSTRUCTION

Application Name
under construction
TOPIC UNDER CONSTRUCTION

Stored in an invisible column in the database, with an exclamation mark following. Allows all topics referring to a given application to be found by searching on the name, followed by an exclamation mark.
All topics must have an application name. An application name such as General is used to describe functions not associated with any application.

Topic Title for Searching
TOPIC UNDER CONSTRUCTION

Graphics
pictures
TOPIC UNDER CONSTRUCTION