How to configure a project file

The project file defines the location of all resources used by the project and the target help file name. The project file has an extension .cshlp, for use with the CS Help compiler GUI, or .xml for use with the command line driven tool. The easiest way to create a project file is to alter an existing file to suit the new project structure and files. To create a project file:

1. Create an XML prologue. This gives the XML version conformance, the location of the DTD for source document validation and the location of the XSL file to allow the proofing XML to be viewed in a browser. The code fragment below shows a typical prologue.

   <?xml version="1.0"?>
   <!DOCTYPE cshproj SYSTEM "/epoc32/tools/cshlpcmp/dtd/cshproj.dtd">
   <?xml:stylesheet href="/epoc32/tools/cshlpcmp/xsl/CSHproj.xsl" title="CS-Help project file" type="text/xsl"?>

   If altering an existing project file this need not be changed.

2. Declare the body of the project file in the <cshproj> tags:

   <cshproj>
   rest-of-project file
   </cshproj>

   The rest of the project file is defined within these tags.

3. Specify the UID of the Help file:

   <helpfileUID>
   UID-of-Help-file
   </helpfileUID>

4. Specify the directories used by the project, as shown below.

   <directories>
   <input>directory containing project, source rtf and customisation files\</input>
   <output>output directory\</output>
   <graphics>directory for holding graphics files\</graphics>
   <working>directory for temporary working files\</working>
   </directories>

   If altering an existing project file, simply change the input, output, graphics and working directories to suit your project structure. Note directory names must be specified with a trailing backslash “\”—as shown above before the closing tags.

5. Specify the names of the customisation and source rtf files used by the project, and the name of the output file—as shown below. xml source files may also be specified. The CS Help compiler finds/creates these at the locations specified in the <directories> section.

   <files>
   <source>
   <file>source-rtf-file-name.rtf</file>
   <xmlfile>source-xml-file-name.xml</xmlfile>
   </source>
   <destination>CS-Help-output-file-name.hlp </destination>
   <customization>customisation-file-name.xml </customization>
   </files>

   If altering an existing project file, simply change the name of the source and output files. The customisation file can also be changed, however most projects will use the same file.

6. Save the file

A listing of the project file for the Shapes example is given below — Shapes.cshlp. This contains the UID of the help file followed by the directories used by the project in <directories> tags. The rtf source file, output file shapes.hlp and customisation file are specified in the <files> tags.

<?xml version="1.0"?>
<!DOCTYPE cshproj SYSTEM "/epoc32/tools/cshlpcmp/dtd/cshproj.dtd">
<?xml:stylesheet href="/epoc32/tools/cshlpcmp/xsl/CSHproj.xsl" title="CS-Help project" type="text/xsl"?>

<cshproj>
<helpfileUID>0X10008AB6</helpfileUID>
<directories>
 <input></input>
 <output>..\..\..\epoc32\winscw\c\resource\help\</output> 
 <graphics></graphics>
 <working>temp\</working>
</directories>
<files>
 <source>
 <file>shapes.rtf</file>
 </source>
 <destination>shapes.hlp</destination>
 <customization>custom.xml</customization
</files>
</cshproj>

A project file combining the topics for both the Shapes application and the CS Help demonstration file may be created by specifying both rtf files between the <source> tags. The appropriate section, given below, is taken from the project file \CsHelp\project\CombinedProj.cshlp.

<source>
 <file>CsHelp.rtf</file>
 <file>Shapes.rtf</file>
</source>

Project file—.cshlp.