Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]


Customisation file — .xml

[Top]


Overview

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


Customisation file syntax

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:


XML prologue

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"?>

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

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

[Top]


Customisation file syntax — line by line

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


Body and title styles

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:

 

List styles

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/>

Tip, note and important effects

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.

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.

[Top]


Default customisation 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>

[Top]


Viewing in XML

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.