Customisation file — .xml

The appearance of help topics can be controlled through the use of an optional customisation file. Specifically the customisation file controls:

• Typeface and size of text used for topic titles and bodies.

• The character used as a bullet for level 1 and level 2 lists.

• Indentation, boldness, and any preceding text or icon for note, tip and important paragraphs.

CS Help XML documents are preceded by an XML prologue followed by the content of the document. The main body of the customisation file is indicated by a cshcust tag. The cshcust tag contains bodystyle, titlestyle, listbullet1style, listbullet2style, noteeffects, tipeffects, importanteffects tags. A customisation file is given by:

<cshcust>
<bodystyle ...>
<titlestyle ...>
<listbullet1style ...>
<listbullet2style ...>
<noteeffects ...></noteeffects>
<tipeffects ...></tipeffects>
<importanteffects ...></importanteffects>
</cshcust>

Note:

• All customisation choices, and indeed the file itself, are optional. The default customisation file settings are defined in a following section.

A customisation file starts with a XML prologue. The prologue enables the customisation file to be viewed in an XML enabled browser.

The prologue is defined as follows;

<?xml version="1.0"?>

• indicates the version of the XML standard that the source document agrees with.

<?xml:stylesheet href="/cshlpcmp/xsl/cshcust.xsl" title="CS Help customization" type="text/xsl"?>

• defines the URL of the style sheet used to transform the source XML file into viewable HTML.

<!DOCTYPE cshcust SYSTEM "/cshlpcmp/dtd/cshcust.dtd">

• defines the document type and gives the URL of the DTD used to validate the source XML.

This section details the syntax of each line of the main body of the customisation file.

The titlestyle and bodystyle tags allow the typeface and size of the font used for the topic title and body text to be customised. Both tags have two attributes fontstyle and size. The Fontstyle attribute can be either serif or sansserif . The actual font is determined by the help application. The size attribute gives the font size in points. Both attributes are optional.

Use the <bodystyle> tag to specify body style attributes:

<bodystyle
 [ fontstyle= "serif" | "sansserif" ]
 [ size="font-size" ] />

This specifies the style of all text in body of a help topic, unless overridden by special effects as described below.

For example:

<bodystyle fontstyle=serif size=12/>

Use the <titlestyle> tag to specify all attributes of the topic title style.

<titlestyle
 [ fontstyle= "serif | sansserif"  ]
 [ size=font-size ]/>

This specifies the style of title lines only. The fontstyle= and size= attributes have the same meaning as on the <bodystyle> tag.

For example:

<titlestyle fontstyle=serif size=14/>

Notes:

• The tags must be terminated with />

• All attribute values must be enclosed in ""

The listbullet1style and listbullet2style allows the bullet point character to be specified. Both tags have a single attribute bulletchar which contains the value of the character to use.

Use the <listbullet1style> tag to specify attributes of first-level bulleted lists:

<listbullet1style  bulletchar="bullet-symbol" />

This specifies the bullet character to be used on all first-level bulleted lists. The default is:

<listbullet1style bulletchar=149/>

which is a blob, in the standard paragraph font. This symbol is taken from position 149 in the symbol table.

Use the <listbullet2style> tag to specify attributes of second-level bulleted lists:

<listbullet2style  bulletchar= "bullet-symbol"  />

This specifies the bullet character and font to be used on all first-level bulleted lists. For example:

<listbullet2style bulletchar=149/>

Effects can be applied to note, tip and important paragraphs through the use of noteeffects, tipeffects and importanteffects tags. Each of these tags can take five attributes.

• leftindent, this contains the number of twips that the paragraph text should be indented by from the left hand margin. If this is set to 0 or missing then the paragraph text is flush to the left margin.

• archive, contains the directory (relative to the picture directory stated in the project file) that a picture used to precede the paragraph may be found.

• name, contains the filename (without an extension) that can be found in the given archive.

The content of the tag is the text used to proceed the paragraph. This content can take bold, italic, super and sub-script formatting.

The <tipeffects> tag and its contents specifies the effects for a paragraph in Tip style.

<tipeffects [ leftindent="index "]>[<b>]["text"][</b>]<tipeffects/>

The following example gives the text Tip: in bold, with a half-inch indent:

<tipeffects leftindent="36"><b>Tip:</b></tipeffects>

The <noteeffects> tag specifies the effects for a paragraph in Note style.

<noteeffects [leftindent="index"]>[<b>]["text"][</b>]<noteeffects/>

The following example gives the text Note: in bold, with a 5/6-inch indent:

<noteeffects leftindent=60/><I>Note:</I></noteeffects>

The <importanteffects> tag specifies the effects for a paragraph in Important style.

<importanteffects[leftindent="index"]>[<b>]["text"][</b>]<importanteffects/>

The following example gives the text Important: in italic, with a half-inch indent:

<importanteffectsleftindent=36/><I>Important:</I></importanteffects>

If the note/tip/important paragraph is preceded by a graphic the meaning of the left indent is altered. If the leftindent tag’s value is zero then the paragraph text is placed flush with the left margin. However if the left indent attribute is not given then the text is lined up under the right hand edge of the graphic.

The effect definitions are as shown below, where the graphic definition is the same as used for inserting a graphic in the source rich-text file.

<tipeffects archive="archive-name" name="picture-name" [leftindent="index"]>

<noteeffects archive="archive-name" name="picture-name" [leftindent="index"]>

<importanteffects archive="archive-name" name="picture-name" [leftindent="index"]>

The leftindent= field defines the indentation of the paragraph text from the left margin. The field is optional, and defaults to a width equal to that of the graphic. leftindent=0 implies that the text is flush with the left margin.

For example:

<noteeffects archive="fetsrc" name="exit" leftindent="36"/>

<importanteffects archive="fetsrc" name="full-but" leftindent="60"><b><I>Important</I></b></importanteffects>

Notes:

Using graphics to precede the paragraph can significantly increase the size of the generated help file.

The following file contains all CS Help’s defaults. It is suitable for running CS Help to generate help text in UK or US English locales.

<?xml version="1.0"?>
<!DOCTYPE cshcust SYSTEM "/cshlpcmp/dtd/CSHcust.dtd">
<?xml:stylesheet href="/cshlpcmp/xsl/cshcust.xsl" title="CS Help customization" type="text/xsl"?>
<cshcust>
<bodystyle fontstyle="sansserif" size="10"/>
<titlestyle fontstyle="sansserif" size="14"/>
<listbullet1style bulletchar="149"/>
<listbullet2style bulletchar="149"/>
<tipeffects leftindent="36"><b>Tip:</b></tipeffects>
<noteeffects leftindent="36"><b>Note:</b></noteeffects >

<importanteffects leftindent="60"><b>Important:</b></importanteffects>

</cshcust>

Customisation options are not applied to proofing XML.

The CS Help compiler provides XSL style sheets that will allow a representation of the help file to be viewed in a XML enabled browser (such as Internet Explorer 5.0). This format is available for proof-reading only. No customisation is possible. XSL style sheets are located at epoc32\tools\cshlpcmp.