E-Z Braille
Translation Tables
Technical Reference Manual

By Jeff Wheatley

High Expectations
1012 Reilus Court
Lexington, KY  40517
(606) 273-6640

Copyright 1992
ALL RIGHTS RESERVED
                            CONTENTS


TRADEMARKS . . . . . . . . . . . . . . . . . . . . . . . . . .iii

NOTATION CONVENTIONS . . . . . . . . . . . . . . . . . . . . .iii

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . .  1

FLAGS. . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

TOKENS . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

PATTERNS . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

TABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     Match Specification . . . . . . . . . . . . . . . . . . .  6
     Action Specification. . . . . . . . . . . . . . . . . . .  8

SELECT TABLES. . . . . . . . . . . . . . . . . . . . . . . . . 11

COMPILING AND DEBUGGING THE TRANSLATION TABLE. . . . . . . . . 11
                             TABLES

Translation Table Keywords . . . . . . . . . . . . . . . . . .  2

Text Output Commands . . . . . . . . . . . . . . . . . . . . .  9

Flag Update Commands . . . . . . . . . . . . . . . . . . . . .  9

Translate Table Commands . . . . . . . . . . . . . . . . . . . 10

Continuation Commands. . . . . . . . . . . . . . . . . . . . . 10

Translation Table Trace Commands . . . . . . . . . . . . . . . 10
                           TRADEMARKS

Wordperfect is a registered trademark of Wordperfect Corporation.

Braille Blazer is a trademark of Blazie Engineering.

IBM is a registered trade mark of International Business Machines
     Corporation.


                      NOTATION CONVENTIONS

In this document, file names, commands and other special key words
are shown in upper case when used in a paragraph.  When used in a
table or example, they are shown in all lower case.

In our explanations and examples, we often indicate that you must
enter a command or a responce.  By this, we mean that you must type
the specified text and then press the ENTER key.  If we say enter
the following command, the command will be shown on a line by
itself.  You should type the indicated text and then press the
ENTER key.

In our examples, we may use names like DOCUMENT_FILE.  In such
cases, you should replace DOCUMENT_FILE with an approaprate name. 
If something is unclear, give us a call and we will answer your
questions.                          INTRODUCTION

The translation tables contain a large number of rules that the
translator uses to convert or translate the regular text of your
document into braille.  Most users should never need to modify the
translation tables.  If you find a translation error, you should
contact High Expectations so we can correct the error for everyone. 
We will send you an update with the correction as quickly as
possible.  If you need to customize the translator, then read on. 
Otherwise, you need not read this manual.  If you are still here,
lets get started.

Start by making a backup copy of the source table file TRANS.TBL. 
If you get into trouble, you can always restore the translation
table and start again.  The TRANS.TBL file is also the best source
of examples available - you may wish to examine it as you read the
following material.

The translation process starts at the beginning of the input
document file and scans the text for things to translate.  You can
think of the translator as a pipe or box that the input text flows
into.  The text is scanned and changed and the braille text comes
out the other end.  While in the pipe, the text is compared with a
set of translation rules until one of the rules matches or fits the
text.  The matched rule then takes control and processes the text. 
The result flows out the output end of the pipe.

The translation table consists of four basic components.  The flags
may be turned on and off; they are used to control the translation
by providing status information to the rules.  The flags definition
block contains a list of all of the flags used by the translation
table.  A token is like a wild card; it represents a specified set
of characters.  All tokens are defined in the token definition
block.  Patterns are similar to tokens but they represent a series
of characters.  They are defined in the pattern definition block. 
The tables are the most important unit in the translation table. 
They use the flags, tokens and patterns to do all of the
translating.

The organization of the translation table requires that the flags
definition block come first followed by the token definition then
the pattern definition block.  The tables follow.  The tables may
be in any order.  The END key word must follow the last table.

White space and comments may be placed almost anywhere in the
translation table.  White space refers to space characters, return
characters and tabs.  Careful use of white space will make for
clearer and faster reading of the translation table.  Comments are
notes and explanations used to clarify the associated code. 
Comments are essential for understanding any type of code and the
translation table code is no exception.  Comments may be placed
wherever there is white space.  Two types of comments are provided. 
The block comments may be used for long explanations that require
more than one line.  The comment is started with the start comment
symbol "/*" and is ended with the end comment symbol "*/".  The
text of the comment comes between.  The line end comments are
intended for clarifying a line of code or as single line comments. 
The line end comment is started with the "//" symbol.  It is ended
by pressing the RETURN key.  Both types of comments may contain any
characters you like with the exception of the symbol that ends the
comment.  Also, you should not place the start comment symbol "/*"
inside a block comment.  This is called a nested comment and is not
allowed.

The translation table uses quoted strings in various places. 
Quoted strings may use either the single quote (') or the double
(") but you must end the string with the same quote that started
the string.  So, 'abc' or "abc" will work while "abc' will generate
an error.  A quoted string may contain one or more characters and
may not be continued across lines.  If you place a comment within
quotes, the comment is treated as part of the string which is
probably not what you want.  You may place almost any character
inside the quotes.  To include a quote symbol in a quoted string,
use the other type of quote to inclose the string.  "it's" holds
the string (it's).  '"he said"' contains the string ("he said"). 
There is an escape character "\" that permits entry of the newline
(return) character and the "\" character itself.  "\n" contains the
single newline symbol.  "\t" contains the tab character (CTRL-I or
code 09h).  "\\" contains the character "\".

The flags, tokens, patterns and tables must each be given a name. 
A name must consist of a letter followed by additional letters,
digits or an underscore symbol.  The length of a name is restricted
to about forty characters.  Upper and lower case letters are not
distinguished.  In general, you can use any name you wish.  There
are a few restrictions however.  The tokens and patterns should not
have any common names.  The name is used to determine if a token or
pattern is intended.  You may have a flag, token or pattern and a
table that all have the same name if you like.  The context that
the name is used in determines if it refers to a flag, token or
table.  You should avoid using keywords as flag, token, pattern or
table names.  See the list of keywords below.


                   Translation Table Keywords

Keyword   Purpose

flags     test flags
tokens    start token definition block
patterns  start pattern definition block
table     start table definition
select    specify select table
end  end of translation table
...  range indicator
any  match 0-60 chars
mark set end of replaceable string
rescan    compare matched input text again
set  set flags
clear     clear flags
directive compare/output format directive
byte output byte
lastch    match last output character
text match input text
then precedes action_specification
append    output specified string
prepend   prepend string to current output string
copy output replaceable string
copych    output next non-replaceable character
flush     flush output string to printer
skipch    discard next non-replaceable char
translate translate using specified table
maintable set controlling table to specified table
traceon   turn debug tracing on
traceoff  turn debug tracing off
loop continue with first rule of table
repeat    repeat this rule
continue  continue with next rule
condcontinue   continue with next rule if no output
return    return to calling table or translator
savelastch     do not change lastch for this rule
if   precedes match_specification
do   acts as match_specification that always matches
use  precedes table name in select table entry


                              FLAGS

The flags definition block is the first code in the table.  This
block is a list of all of the flags used by the translator.  If you
add a flag to the list, add it to the bottom of the list!  The
first few flags must be in a certain order so the translator can
set translation level, english braille, etc.  The flags definition
block begins with the FLAGS keyword followed by an open brace "{". 
The list of flag names follows with a coma "," between names.  The
closing brace "}" ends the flag definition block.  When translation
starts, all flags are cleared and then the translator sets some of
the flags according to the translation and english braille settings
indicated by the user.  A translation rule can use the flags when
matching with the input text.  When a rule matches with the text,
it can clear or set flags as necessary.


                             TOKENS

The token definition block follows the flag definition block.  It
begins with the TOKENS keyword.  As with the flags, the open brace
and close brace symbols inclose a list of token definitions.  Each
definition is of the form:

tokenname = definition;

The definition is a set of characters and tokens.  When a token is
used in a translation rule, it acts like a wild card in that it
matches with the input text character if that character appears in
the definition set of the token.  The token ALPHA might be defined
as the set of all alphabetic letters.  If the input text character
is an uppercase or lowercase letter, the ALPHA token will match
with it.  The definition set may be defined with a quoted string,
a character range, another token, a format directive or any
combination of them.  Components must be separated by comas.  The
range of character specification allows you to specify a set of
characters without needing to list each.  You must have some
knowledge of the ASCII character set and its order to use this. 
The following example specifies all uppercase and all lowercase
letters to be the definition for the token ALPHA.

alpha = 'a'...'z', 'A'...'Z'; // matches any letter

The ENDSENTENCE token uses a quoted string to enumerate its
definition set.  It matches with any end of sentence punctuation.

endsentence = '.?!';

The directive(directive_name) component matches if directive_name
is in the input text.  Finally, you can use other tokens as part of
the definition.  Consider the following token definitions.  The
token UPPER is defined to be any uppercase letter and LOWER to be
any lowercase letter.  ALPHA is defined to be UPPER or LOWER.

upper = 'A'...'Z';
lower = 'a'...'z';
alpha = upper, lower;


                            PATTERNS

The pattern definition block is next.  It starts with the PATTERNS
keyword and also has a list of definitions inclosed by open and
close brace symbols.  The pattern definitions are of the form:

patternname = definition;

The definition may consist of quoted strings, tokens and a few
special keywords.  The pattern matches a string (a sequence of
characters) from the input text.  To understand the difference
between a token and a pattern,  consider that our input text is
"the".  The ALPHA token will match the "t", the "h" or the "e"
(depending on its placement) but it matches with exactly one of
them.  The pattern THEPATTERN matches with "the" or all three
characters.

thepattern = 'the';

If we wanted to match a sequence consisting of any letter followed
by the string of letters "ation", we could use the following
pattern.

pattern = alpha, 'ation';

Note that the pattern uses the token ALPHA to indicate that the
first character of the input text can be any letter.  The rest of
the letters must be "ation".  We will continue discussion of
patterns later under the topic "Tables" subtopic "Match
Specification" in the discussion of the text specification.  Note
that the pattern definition and the text specification are
identical.


                             TABLES

After the pattern definition block, the tables may be placed in any
order.  Each table starts with the TABLE keyword followed by the
table name.  An open brace starts the table definition and a
closing brace ends the definition.  The definition is a set of
rules.  Each rule is of the form:

if match_specification then action_specification;

When a table is executed, the rules are tested in order.  If the
rule match_specification matches the input text, then the
action_specification is acted on.  Thus, the match_specification
says what we are looking for and the action_specification says what
to do if we find what we are looking for.  If the
match_specification does not match, the next rule is tested.  Once
a match is found, the process starts over with the next input text. 
There is an alternate rule that has the form:

do action_specification;

This rule always matches if it is reached - it may not be reached
if an earlier rule matches.  The action_specification works the
same as for the IF-THEN form with the exception that processing
continues with the next rule in the table rather than returning to
the calling table or translator.


Match Specification

The match specification is preceded by the IF keyword.  Its form
is:

[flag_specification] [&] [lastch_specification] [&]
[text_specification]

Note that each part is optional; you may have all or any
combination of the three.  You must have at least one of them
however.  They must be separated by the ampersand "&" character.

The flag specification tests a set of flags to determine if they
are set (on) or clear (off).  The not indicator exclamation "!"
character is used to specify that the flag is clear.  Consider the
example:

flags(flag1, !flag2)

This flag specification will match if FLAG1 is on or set and FLAG2
is off or clear.  Otherwise, the rule will fail.  

The last character specification allows the rule to examine the
last character that was processed by the translator.  It only goes
back one character.  The following example matches if the last
character was the letter "l".

lastch = 'l'

The next example matches if the last character was any letter.

lastch = alpha

The not indicator negates the match.  In other words, what would
normally match fails and what would fail is matched.

lastch=!'a'

This fails if the last character was an "a" character.  It matches
if the last character was not an 'a' character.

The text specification matches with the current input text string. 
Its form is the same as that used for pattern definitions.  The
keyword TEXT appears followed by the equal symbol and then the
definition.

text = alpha,'ation'

This matches if the first character of the input text is a letter
and the next characters are "ation".  As with the pattern
definitions, the text specification may contain quoted strings,
tokens, patterns and other special keywords.  The not symbol may be
used to negate the match of a specific character.

text='abc',!'d'

This portion of the rule matches if the first three text characters
are "abc" and the fourth text character is not "d".

When a rule is intended to replace input text with another string,
it is important to know exactly what text is considered to be
matched.  The rule may need to examine seven characters of the text
but will replace only the first five.  The last two characters
should be left for another rule to examine.  We refer to this
replaceable part of the input text as the replaceable string.  The
replaceable string may be zero or more characters long and always
starts with the first character of the input text.  There are two
ways to indicate the end of the replaceable text.  The MARK keyword
acts as a delimiter.  All matched text before the MARK keyword
becomes the replaceable string and the text that follows is not
replaceable.  If the MARK keyword is not used, the end of the
replaceable string is determined to be the end of the matched
string (all characters from the input text that are matched by the
match specification) or at the first token or pattern that appears
in the match specification.  Here are some examples.

text='ation'

The entire matched string is the replaceable string.

text=mark,'ation'

Nothing is replaceable; the replaceable string has a length of
zero.

text='be',alpha

The "be" is in the replaceable string and the letter that matches
with ALPHA is not.

text='be',mark,'st'

The "be" is in the replaceable string and "st" is not.

To this point, we have discussed text specification components that
each match exactly one character of the input text.  Each character
of a quoted string matches one character in the text and each token
matches one character in the text.  Patterns can match a string of
characters from the input text.  The pattern is a bit like a macro
when used in the text specification.  If you expand the pattern,
you once again have a one-to-one correspondence between compare
components and input text characters.

...
thepattern = 'the';
...
text = ' ', thepattern, ' '

Matches if the first character is a SPACE, the next characters are
"the" and the last character is a SPACE.  The replaceable string
consists of the first SPACE only.

The ANY keyword allows the rule to match multiple text characters. 
It is used to mask a series of similar characters.

text = any '.'

This matches zero, one or up to about sixty "." characters in a
row.  The ANY keyword can be used in conjunction with tokens and
patterns and the not symbol may be used to negate the component
being examined.

text= any alpha

This matches zero or many letters.

text=! any alpha

This matches zero or many characters until a letter is encountered.

Finally, the RESCAN keyword may be used in the match specification
to start examining the input text from the start again.  This is
not often used but if a rule needs to scan the input text more than
once, the RESCAN can be used.  The effect is to say that the input
text must match text specification part A and must also match part
B etc.

The directive keyword may be used in the match specification or a
token definition to match with a translator format directive.  The
form of the keyword is:

directive(directivename)

Directivename must be one of the directive names listed in the
Directive Names Table.


Action Specification

The action specification follows the THEN or DO keywords of a table
rule.  Its purpose is to control what is done when the
match_specification of the rule matches the input text.  It can
exchange the input text with other text, output the matched text,
set or clear flags and all sorts of other stuff.  Unless otherwise
indicated, the replaceable string is always discarded!  The
specification may contain several components separated by comas. 
There are four general categories of actions that the action
components do: text output, flag updates, translation and
continuation.  The text output components are listed in the
following table.


                      Text Output Commands

Name                Purpose

append'string'      append or output string
prepend'string'     prepend string to current translation string
directive(dirname)  output format directive
byte(byte_code)     output byte_code
copy                copy replaceable string to output
copych              copy next non-replaceable character to output
skipch              discard next non-replaceable character
flush               flush output string to printer

The flag update components set and clear specified flags.  They are
listed in the following table.


                      Flag Update Commands

Name                     Purpose

set(flag1,flag2,...)     sets flag1, flag2, ...
clear(flag1,flag2,...)   clears flag1, flag2, ...

The translation components cause another table to be translated and
set the main or controlling table.  MAINTABLE(tablename) sets the
table that will control translation until the next MAINTABLE is
acted on.  The TRANSLATE(table_specification) component causes the
indicated table to be translated.  Table_specification can be a
table name or a table definition.  To use a table definition, use
the following syntax:

translate({ table_definition })

Table_definition is the same as for any other table.  The result is
a nested table.  Here are the translation components listed in
table form.


                    Translate Table Commands

Name                          Purpose

maintable(tablename)          set controlling table
translate(table_definition)   translate table

The continuation components of the action specification determine
what happens when this rule is completed.  There should be at most
one continuation component in the action specification.  If no
continuation components appear in the action specification, the
default continuation is to return or end the translation of the
table and return to the calling table or the translator.  Here are
the available continuation components.


                      Continuation Commands

Name           Purpose

return         return to calling table or translator
continue       continue with next rule of this table
condcontinue   continue with next rule of this table if no text
               output
repeat         repeat this rule
loop           continue with first rule of this table


The debug commands are used to help you understand how your changes
to the translation tables work.  When trace is turned on, each
translation rule is displayed before it is executed.  When a new
table is entered, the table name, current position in the input
text and ASCII code of the current input text character are
displayed.  When text is output or flushed to the printer, the
string is displayed.  The result is that you can watch the
translator as it translates.  Trace can be turned on with the "D"
command line switch or with the TRACEON command in the action
specification of a translator rule.  The commands are listed in the
following table.


                Translation Table Trace Commands

Name           Purpose

traceon        start tracing with next rule
traceoff       stop tracing after this rule


                          SELECT TABLES

If you scan through the TRANS.TBL file, you will see lots of tables
that are all of the same general form.  You will perhaps notice one
table that looks different.  This is a select table.  The purpose
of a select table is to select a table to translate the input text
according to the input text.  Our braille translation table uses a
table ALPHA to take an alphebetic character as the next input text
character and to select the correct translation table to handle
that letter.  It uses TBL_A if the letter is an "a".  TBL_B is used
if the input text character is a "b".  We have had a need for only
one such table but you could certainly have more.  The structure is
similar to a regular table.  You start with the TABLE keyword
followed by a table name.  The SELECT keyword comes next followed
by the opening brace.  A list of select rules is ended with a
closing brace.  The form of each rule is:

if 'x' use tablename;

tablename can be any table.  Be careful to give the select table a
character that is listed in one of the select rules.  If no rule is
found, the table returns to the calling table.


          COMPILING AND DEBUGGING THE TRANSLATION TABLE

Your package contains the program CPLTBL which converts your
translation table source code to object code that the translator
can use.  From the command line, change to the directory which
contains the translator files.  Enter the following command:

cpltbl trans

The compiler reads the source from TRANS.TBL and places the object
in TRANS.OBJ.  If no errors are detected, the compiler displays
information about the number of flags, tokens, patterns and tables
and ends.  If an error is detected, the compiler displays an error
message with line number and ends.  The line number is the line in
the source file where the error was detected.  You will find the
error on that line or perhaps the line or two above.

Just because the compiler thinks the translation table is correct
does not mean everything is done!  The compiler finds syntax errors
but it does not find errors in logic.  Another way to put it is
that the translator does exactly what the table dictates regardless
of the wisdom of the actions.  The upshot is that you may not get
the results you wanted.  The worst error conditions available are
the looping error and the too many nested tables error.  The first
error occurs if you use the LOOP or REPEAT continuation components
in an action specification and that rule always matches.  The
translator will repeat the rule several times but will eventually
generate a looping error and terminate with a message.  The nested
tables error condition occurs if one table calls another with the
translate component of the action specification.  If the first
table calls a second which calls a third and so on, to the point
that there are too many calls, the translator generates a nested
tables error and terminates with a message.  It takes a lot of work
to generate either of these errors.  Most likely, the error will be
that the braille output is not what you wanted or intended.  There
are lots of ways that this error can occur.

The debug mode was designed to track down all logic errors.  It
allows you to watch the translation process.  As each rule is
examined, the rule is displayed.  You press a key to go to the next
rule.  As text is output, it is also displayed.  You can turn trace
mode on with the /d command line switch.  You can also use the
TRACEON and TRACEOFF components in the action specification.
