# Customisation file — `.alc`

## Contents

- Overview
- Customisation file syntax
- Customisation file syntax — line by line

- Body and title styles
- List styles
- Tip, note and important effects

- Default customisation file
- Conversion to HTML

## Overview

The customisation file controls the appearance of the generated database. The following sections define the customisation file structure, and list the default customisation settings.

## Customisation file syntax

  `[ <bodystyle` [ `fontstyle=`font-style] [ `size=`font-size ] `> ]`
  `[ <titlestyle` [ `fontstyle=`font-style] [ `size=`font-size]`> ]`
  `[ <listbullet1style` `bulletchar=`bullet-symbol `> ]`
  `[ <listbullet2style` `bulletchar=`bullet-symbol `> ]`
  `[ <tipeffects
  ` [`text=”`text`”` `leftindent=`indent [`bold=yes` | `no`] ]
  | [`archive=`archive-name `name=`picture-name [`leftindent=` indent] ]`> ]`
  `[ <noteeffects
  ` [`text=”`text`”` `leftindent=`index [ `bold=yes` | `no` ] ]
  | [`archive=`archive-name `name=`picture-name [`leftindent=`indent] ]`> ]`
  `[ <importanteffects
  ` [`text=”`text`”` `leftindent=`indent [ `bold=yes` | `no` ] ]`
  `| [`archive=`archive-name `name=`picture-name [`leftindent=` indent] ]`> ]`

For information about how to interpret the syntax, see BNF grammars.

##### Arguments

font-style | The font style, must be either `serif` or `sansserif`.
font-size | The font size, in points.
bullet-symbol | The character value of the symbol to be used as the bullet.
text | Any text appropriate for the type of tip, note or important effect
indent | The amount of indent from the left hand edge of the topic window.
archive-name | The name of the graphic archive in which the effects graphic is stored.
picture-name | The name of the graphic to precede text style marked with one of the effects styles

##### Notes

- All lines of the file, and indeed the file itself, are optional. The default customisation file settings are defined in a following section.
- Graphics may be inserted in place of tip, important and note effects using the syntax above. However this will considerably increase the size of the final help database.

## Customisation file syntax — line by line

Section Contents

- Body and title styles
- List styles
- Tip, note and important effects

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

### Body and title styles

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. `fontstyle=` allows you to specify either `serif` or `sansserif`. `size=` allows you to specify a size, in points.

The default is

        <bodystyle fontstyle=sansserif size=10>

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.

The default is

        <titlestyle fontstyle=sansserif size=14>

### List styles

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

  `<listbullet1style` [ `bulletchar=`bullet-symbol ] `>`

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

        <listbullet1style bulletchar=149>

which is a blob, in the standard paragraph font.

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. The default is

        <listbullet2style bulletchar=149>

which is a blob, in the standard paragraph font.

### Tip, note and important effects

The `<tipeffects>` tag specifies the effects for a paragraph in `Tip` style.

  `<tipeffects text="`text`"` `leftindent=`index [`bold=yes` | `no`] `>`

Use `text=` to specify text, such as `Tip:`, to be used to indicate a tip. Use `bold=` to indicate whether this text should appear in bold, and use `leftindent=` to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the tip text.

The default is

        <tipeffects text="Tip:" bold=yes leftindent=36>

giving the text Tip: in bold, with a half-inch indent.

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

  `<noteeffects text="`text`"` `leftindent=`index [ `bold=yes` | `no` ] `>`

Use `text=` to specify text, such as `Note:`, to be used to indicate a note. Use `bold=` to indicate whether this text should appear in bold, and use `leftindent=` to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the note text.

The default is

        <noteeffects text="Note:" bold=yes leftindent=36>

giving the text Note: in bold, with a half-inch indent.

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

  `<importanteffects text="`text`"` `leftindent=`index [ `bold=yes` | `no` ]`>`

Use `text=` to specify text, such as `Important:`, to be used to indicate an important note. Use `bold=` to indicate whether this text should appear in bold, and use `leftindent=` to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the important note text.

The default is

        <importanteffects text="Important:" bold=yes leftindent=60>

giving the text Important: in bold, with a 5/6-inch indent.

In EPOC release 5 and greater; paragraphs marked with effect styles may alternatively be preceded by a graphic (rather than text). The help database stores a graphic for every paragraph marked with an effects style. Hence the benefits of using a graphic must be weighed against the resulting increase in help database size, prior to using this feature.

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.

##### Note:

- Graphics defined in the customisation file for Tip, Important and Note effects are not shown in HTML output format.

## Default customisation file

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

        <bodystyle fontstyle=sansserif size=10>
        <titlestyle fontstyle=sansserif size=14>
        <listbullet1style bulletchar=149>
        <listbullet2style bulletchar=149>
        <tipeffects text="Tip:" bold=no leftindent=36>
        <noteeffects text="Note" bold=yes leftindent=36>
        <importanteffects text="Important" bold=yes leftindent=60>

## Conversion to HTML

This format is available for proof-reading only. No customisation is possible.