|
|
|
|
|
|
|
|
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\.
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).
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\.
Section Contents
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.
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.
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).
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.
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:
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.
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 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\).
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).
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.
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.
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
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.
|
|
|
|
|
|
|
|