===========================================
Writing Word Substitution Dictionary Tables
===========================================

Introduction
============

This document describes the format of word substitution dictionary tables used by YABT. After reading this document you should be able to create your own word substitution dictionaries and understand some of the limitations of the format.

---------------------------------------
What is a word Substitution dictionary?
---------------------------------------

A word substitution dictionary is a simple list of words which when YABT encounters should simply substitute for a replacement form. YABT does allow users to define which states (which in the case of Braille refer to the grade of Braille) the substitution can be made.

Writing the table
=================

The format of the word substitution dictionary table supported by YABT is currently a multi-column plain text file. Each column is separated by whitespace (eg. tabs or spaces).

The contents of each column are as follows:

1. The state in which the substitution can be made. For the British Braille table (britishtobrl.xml) the state relates to the grade of the Braille. States of interest are:
  * State 1 is for grade 1
  * State 2 is for grade 2
  * State 5 is for computer Braille
  
  State should always be an integer. If multiple states should be specified then multiple rows should be inserted, although if requests are recieved for supporting lists of states in one row recieved this may be altered in the future.
2. The original word. A word is defined as a block of alphabetic characters surrounded by any non-alphabetic characters. This means multi-word contractions such as those for ``of the`` cannot be specified in these tables. You should also be aware that you may have to specify entries in a form suitable for the table being used (eg. when using the British Braille table britishtobrl.xml you should specify the entries in uppercase). Failure to specify the entries in the form desired by the main translation table will not raise any errors but the word substitutions may not be applied as expected or even fail to ever be applied.
3. The replacement text. This can be any text so long as it doesn't contain whitespace characters. Other than no whitespace characters there are no special requirements of this column.




