E-Z Braille
Word Processor Definition 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 AND VALUES SECTION . . . . . . . . . . . . . . . . . . .  2

FORMAT TRANSLATION TABLE . . . . . . . . . . . . . . . . . . .  4
     Match Specification . . . . . . . . . . . . . . . . . . .  5
     Output Specification. . . . . . . . . . . . . . . . . . .  7
                             TABLES

Skip Text Commands . . . . . . . . . . . . . . . . . . . . . .  6

Parameter Specification Command. . . . . . . . . . . . . . . .  6

Parameter Specification Types. . . . . . . . . . . . . . . . .  6

Parameter Manipulation Commands. . . . . . . . . . . . . . . .  7

Directive Names. . . . . . . . . . . . . . . . . . . . . . . .  7
                           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 wptype files provide the translator with all of the information
needed to correctly recognize, read and format a document of a
particular type.  Most users should never need to make changes to
a wptype file.  If the translator does not recognize your word
processor's formatting, please contact High Expectations and we
will correct the problem for all users.  We will get an update to
you as quickly as possible.  If you have a word processor that the
translator does not support, let us know.  To add a new word
processor, we must be able to obtain the file format technical
information for the document files.  If you have access to this
information, or you know how to obtain it, we should be able to
support the word processor.  Otherwise, we will try to find the
information ourselves.  The best reason, we can think of, for
making custom changes to the wptype files is to make your own
directives for block typing, braille translation level etc.  In the
case of text files, you might also want to completely change the
format directive strings as well.  Such changes should be quite
simple and safe to make.  Regardless, we will attempt to explain
fully how the wptype files work.  If you do not want to make custom
changes to your directive strings, you need not read this manual.


The wptype file is composed of two major sections.  The first
section is a set of flags, values and other information that tells
the translator what type of file it is dealing with and how to
recognize it automatically.  The second section is a translation
table of sorts.  It specifies the formatting directives that might
be found in a document file and tells the translator how to use
them for braille formatting.  We will cover the first section first
and will discuss each of the flags and values that must be set.

The use of white space and comments in the wptype source file is
identical to that for the translation table file.  You may place
white space (space, return and tab characters) almost anywhere in
the file.  Both block and line end comments are provided.  The
block comments are for longer comments that require more than one
line.  They start with the start comment symbol "/*" and end with
the comment end symbol "*/".  Between the start and end comment
symbols, you may place any text except "/*".  The line end comment
is started with the "//" symbol and is ended with a press of the
RETURN key.  Wise use of white space and comments makes for easier
reading and better understanding of what is happening.  Quoted
strings are also the same as for the translation table file.  You
may use either the single quote (') or the double (") but you must
end the string with the same symbol that started it.  A quoted
string must not be split across lines.  You can include a quote
character within a quoted string by using the other quote.  For the
double quote, use '"he said"' and use "John's" for the single
quote.  The escape symbol back slash "\" can be used to include
special symbols.  "\n" contains the newline symbol.  "\t" contains
the tab symbol and "\\" contains the back slash symbol.  If you
place a comment within a quoted string, the comment becomes part of
the string.  Numeric values may be interred in decimal (base 10),
binary (base 2), octal (base 8) or hexadecimal (base 16).  Decimal
is assumed unless otherwise indicated.  To use binary, postpend a
"b" to the number.  For octal, postpend a "o".  Use a "h" for
hexadecimal.  If the number is in hexadecimal, the first digit must
be in the range (0-9) or the wptype compiler will assume it is a
name and not a number.  If you have a number that starts with a-f,
prepend a 0 as 0ffh.


                    FLAGS AND VALUES SECTION

These entries must appear in the order indicated and may not be
omitted.  Use one of the existing wptype files as an example.  We
will not necessarily cover the items in the order required.

The WPTYPE item is a flag that tells the translator the general
category of document file to be processed.  Its form is:

wptype = type

Type can be set to TEXT (standard ASCII text file that may contain
formatting directives) or WP (a file produced by a word processor). 
The WP files are assumed to be document files that contain soft
returns at the end of paragraph lines.  The TEXT file is assumed to
be a standard ASCII text file that contains hard returns at the end
of every line.  Note that the text file may be a WSWG (what you see
is what you get) file; it may have spaces to make the left margin
and formfeed characters for page breaks.  Actually, the same is
true for the WP type as well; it may also have tabs or spaces for
the left margin and hard returns at the end of every line.

The WPTYPE_ID specifications are used by the translator to
automatically recognize the document file.  It has the form:

wptype_id
{
  hasno (hasno_list);
  scan_code_string1;
  scan_code_string2;
  ...
}

The hasno_list may consist of any combination of CR_LF (newlines),
CONTROLCHAR (ASCII codes less than 32) and GRAPHCHAR (ASCII codes
above 127).  The translator scans the first line or two of the file
and if a control character is found when HASNO(CONTROLCHAR) is
specified, the file is ruled out for that file type.  CR_LF and
GRAPHCHAR work similarly.  scan_code_string# is a set of strings
that the translator also looks for.  There are two types of these
strings.  The scan strings are scanned for in the first several
bytes of the input file.  The code strings are looked for at a
specific location in the file.  The syntax for the strings is:

scan(scansize:string);
code(position:string);

Scansize refers to the number of bytes of the file to examine and
position is a specific location in the input file at which the
string should be found.  String can be a quoted string or may be
specified numerically.

The translator first tests the code strings.  If all of the code
strings are matched in the input file, the file is processed by
this wptype file.  If a code string is specified and it did not
match, this wptype file is ruled out as a possibility.  Otherwise,
the scan strings and the hasno flags are used.  If a hasno
specification is broken, the wptype file is ruled out.  Finally,
the file with the longest matched scan string is the winner.  If no
scan strings are matched or if all wptype files are ruled out, the
translator gives up with an error message.

The SOFTZONE is a value that indicates the effective length of a
line in the document file.  This value is used to assist in block
typing.  Its form is:

softzone = 65

TABSIZE indicates the number of spaces generated by a press of the
TAB key in the word processor used to generate the document file. 
Most word processors use a default value of five while many editors
use eight.  The form is:

tabsize = 5

The DIRECTIVECHARS keyword is used to define a set of characters
used to start directive strings.  For example, the translator
supports directives that start with the tilde character for block
type specification and braille translation changes.  Thus the
string would contain the tilde character.  Invisible directives
such as those used by Wordperfect have no directive indicating
character and thus need not be of concern here.  If your word
processor uses directive strings however, add the directive
indicating character to the DIRECTIVECHARS string.  The form is:

directivechars('~')

LINEDIRECTIVE is a flag associated with the DIRECTIVECHARS string. 
It indicates if directives must start at the beginning of the line. 
Its form is:

linedirective = no  // yes or no

No means that directives do not have to start at the beginning of
the line.

STANDARDMARGINS is a set of values used to indicate the standard
margins and page size used by the word processor that produced the
document file.  The values include the top, bottom, left and right
margins and the number of lines per page and columns per line.  The
form is:

standardmargins = top#, bottom#, left#, right#, lpp#, cpl#

Example: standardmargins 6, 6, 10, 10, 66, 85

The HEADER flag indicates the type of file header to expect in the
document file.  Its form is:

header type

Type can be either NONE, FIXED(OFFSET) or VARIABLE(OFFSET).  NONE
indicates the file has no header.  FIXED indicates that the file
has a header with fixed length.  Offset is the length (in bytes) of
the header which is the offset position of the start of the text. 
VARIABLE indicates that the size of the header is variable.  Offset
indicates the offset position of a value that contains the position
of the start of the text.  The value is assumed to be a four byte
double word value in the standard form (low order bytes first).

ZEROCODE indicates a character code that is not needed by the
format translation table.  The code is used to replace zero
character codes.  Do not concern yourself with this value other
than to set it to a non-printing character that is not used in the
format translation table.  The form is:

zerocode = 255


                    FORMAT TRANSLATION TABLE

This section of the WPTYPE file contains the format translation
table.  The table consists of a series of rules that are used to
recognize format directives in the document file and to convert
them to format directives suitable for braille.  The table consists
of a series of rules.  Each rule handles one format directive.  The
wptype compiler sorts the rules into numeric order before storing
them into the object file.  When the translator finds an invisible
character or a character listed in the DIRECTIVECHARS string from
the input text, it passes control to the format translation table
to find the rule to handle the character.  If a rule is matched,
the braille directive is output.  Otherwise, if the character is an
invisible character, it is discarded.  The rules are of the form:

match_specification = output;

The match_specification consists of a match string followed by scan
and parameter specifications.  It may also contain parameter
manipulation specifications.  If a rule is matched, all of the
input text processed by the match string, skip components and
parameter specifications is discarded and is replaced with the
output specification of the rule.


Match Specification

The match string may be specified as a quoted string, numeric value
or any combination there of.  Each component is separated by comas. 
Here are some examples.

'~c.'
'~',99,'.'
126,99,46
7eh, 63h,2eh

All of these examples are equivalent.  The matching string is used
to determine if the input text is to be processed by this rule.  If
the match string equates to the input text, then the rest of the
rule is used and no other rules are examined.

A special form of the match string permits the rule to match with
a range of strings.  The form is:

low_string:high_string

Low_string must be the same length as high_string and its numeric
value must be less than high_string.  If the input text matches
low_string, high_string or has a numeric value between the two, the
rule is matched and takes control.  Note, do not use a zero value
character in a range string!  The zero values are replaced with
another value.  The results can be messy.  The ranged match string
permits stripping of a set of formatting directives that fall in a
numeric range.

The remainder of the match_specification consists of three general
types of components: skip text, parameter specification and
parameter modification.  These start processing the input text
where the match string left off.

The skip text components include the following:


                       Skip Text Commands

Name           Purpose

skip(#)        skips the next # bytes of input text
scan(char)     skip input text until char is found
jump(parm#)    skip parm[#] bytes of input text

These are used to discard input text.  The SKIP command skips the
specified number of bytes and the remaining match_specification
processes the input text from the new position.  The SCAN command
also discards input text by scanning for the specified character. 
The input text following the character is used by the remaining
match_specification.  The JUMP command discards the number of bytes
indicated by a previously defined parameter.  This is used
primarily for variable length directives when the directive
contains a length specification.

The parameter specification component indicates where each
directive parameter is located and what form it is stored in.  The
form is shown in the following table.


                 Parameter Specification Command

parm(parm#,type)

Parm# is a number you assign to identify this parameter in the
rule.  Type indicates the format that the parameter is stored in. 
Type can be any of the values in the following table.


                  Parameter Specification Types

Name           Description

byte           single byte
word           standard 16 bit value (low-byte first)
rword          16 bit value with bytes reversed (high-byte first)
word14         standard word with high-bits clear on bytes
rword14        byte reversed word with high-bits clear on bytes
text           number in text "12"
string[#]      string of length #
dstring(char)  char delimited string

The parameter manipulation components can modify a specific
parameter by adding, subtracting, multiplying or dividing its value
with a constant value.  They are listed in the following table.


                 Parameter Manipulation Commands

Name                          Purpose

addparm(parm#, const)         add const to parm[parm#]
subparm(parm#,const)          subtract const from parm[parm#]
multparm(parm#,const)         multiply parm[parm#] by const
divparm(parm#,const)          divide parm[parm#] by const


Output Specification

The output specification of a rule consists of a string followed by
parameter specifications.  The string specification is the same as
for the match_specification.  In addition, there are keywords that
will generate the translators formatting directives.  The parameter
specifications follow the string.  The parameter specifications are
also the same as for the match_specification except that certain
types are not allowed.  You may use the BYTE, WORD and STRING types
but not TEXT, DSTRING, RWORD, WORD14 or RWORD14.  Note that the
parameter type, in this case, refers to the way the parameter will
be output and not the way it was in the input text.  The following
table lists the directive keywords available to be used in the
string specification.


                         Directive Names

Name                          Purpose

block_off                     end protected block
block_on                      start protect block
bottommarginb,byte            set bottom margin relative to bottom
bottommargint,byte            set bottom margin relative to top
centerblk                     start centering lines
centerln                      center this line
centerpage                    vertically center this page
cleartabs                     clear all tabstops
conditionalpage,byte          end page if < byte lines left
definemarktext,byte,byte      contents or list placed here - first
                              parm = 1 for contents and 21h for
                              list - second byte should be set to
                              5
endcenter                     stop centering lines
heading                       set block type to heading
italics                       start italicizing text
italics_off                   stop italicizing text
justify,byte                  set line justify to 0=left, 2=center
leftmargin,byte               set left margin
linespacing,byte              set line spacing
list                          set block type to list
marktext_off,byte,byte        end marktext - byte1 is set to
                              1=contents, 21h=list - byte2 set to
                              5
marktext_on,byte,byte         start marktext - byte1 is set to
                              1=contents, 21h=list - byte2 is 5
newline                       hard return
newpage                       hard new page
pagenum,word                  set page number
pagenumtype,byte              set page numbering to 0=arabic,
                              1=roman
paragraph                     set block type to paragraph
rightmarginl,byte             set right margin relative to left
rightmarginr,byte             set right margin relative to right
setbm_by_form,byte,byte       set bottom margin to byte1-byte2
settaba,byte                  set tab relative to absolute left
settabr,byte                  set tab relative to left margin
standardtabs,byte,byte        set tabs at byte2 intervals from
                              byte1
stickyspace                   don't break line here
tab                           tab to next tabstop
table                         set block type to table
tabreset,byte[20]             set tabstops from 20 byte bit string
                              - bit set = tabstop at the offset of
                              the bit - note the bits are in
                              reverse order in each byte
tempindent                    temp set left margin to next tab
                              stop - margin restored at next hard
                              return
topmargin,byte                set top margin
widows_off                    turn widows/orphan protection off
widows_on                     turn widows/orphan protection on
