Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



How to customise the appearance of topic text

The appearance of text within a help file is defined in a customisation file. It is much easier to copy an existing customisation file and modify it than to create a totally new file.

If no customisation file is declared in the project file, or if a file cannot be found at the specified location, a default set of style definitions are applied. The process of customising the appearance of topic text is:

  1. Specify the name of the customisation file in the project file. For example, in the “files” section have:

    <customization>customisation-file-name.xml </customization>

  2. Create or copy a customisation file.

  3. 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 cshcust SYSTEM "/cshlpcmp/dtd/CSHcust.dtd">
    <?xml:stylesheet href="/cshlpcmp/xsl/cshcust.xsl" title="CS-Help customization" type="text/xsl"?>

    If altering an existing project file, there is no need to change this section.

  4. Declare the body of the customisation file in the <cshcust> tags:

    <cshcust>customisation-file-body</cshcust>.

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

  5. Create and specify a paragraph style. For example:

    <parastyle name="note" font="sansserif" size="9" left="20"<b>Note:</b></parastyle>

    The content of the element is styled text to put at the start of a paragraph (e.g. <b>Note:</b>). All of these entities will be specified when defining paragraph styles.

    The style for the text is normal by default, however <I></I> tags can be used to make it italic and <b></b> tags can be used to make it bold.

  6. Specify the symbol used for level one bullets (marked as List Bullet style in the source rich-text file):

    <listbullet1style bulletchar="number-of-symbol"/>.

    The symbol is selected by its number in the symbol table.

  7. Specify the symbol used for level 2 bullets (marked as List Bullet 2 style in the source rich-text file):

    <listbullet2style bulletchar="number-of-symbol"/>

  8. Specify the left indent for lists:

    <lists leftindent="list-indent-left"/>


Note

The <titlestyle>, <bodystyle>, <tipeffects>, <noteeffect> and <importanteffects> styles are deprecated for 6.1 releases but are still compatible. For details on usage of these style see the Customisation file — xml reference section.

[Top]


Example

An example customisation file is located in \CsHelp\project\. A listing of the file is given below.

<?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>
<parastyle name="body" font="sansserif" size="9"/>
<parastyle name="tip" font="sansserif" size="9" image="pictures\tip2" left="20"></parastyle>
<parastyle name="note" font="sansserif" size="9" left="20"<b>Note:</b></parastyle>
<parastyle name="important" font="sansserif" size="9" image="pictures\important2" left="20"></parastyle>

<body style="body"/>

<titlestyle fontstyle="sansserif" size="10"/>
<listbullet1style bulletchar="8226"/>
<listbullet2style bulletchar="8226"/>
<lists leftindent="20"/>
</cshcust>

The file has the standard XML prologue. The paragraph style, or topic text, is set as 9 pt SansSerif in the output file.

Text in List Bullet style is displayed in the help file with a preceding bullet symbol. This symbol is taken from position 8226 in the symbol table. Similarly, text in List Bullet 2 style is preceded by character 45 in the final help database.

Note is specified as being bold by the b tag. When the CS Help compiler encounters these style marks it inserts the appropriate text (e.g. Note) in front of the marked text, as shown below. The tip and important paragraph styles are indicated by an image located in the "pictures" folder of the project directory

The Tip, Note and Important paragraphs are indented by 20 twips. For graphics this field is optional. If not defined, text is indented by an amount equal to the width of the graphic.