E-Z Braille
User's Manual

By Jeff Wheatley

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

Copyright 1992
ALL RIGHTS RESERVED
                            CONTENTS


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

LICENSE AGREEMENT. . . . . . . . . . . . . . . . . . . . . . .iii

DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . . .iii

ACKNOWLEDGEMENTS . . . . . . . . . . . . . . . . . . . . . . .iii

NOTATION CONVENTIONS . . . . . . . . . . . . . . . . . . . . . iv

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

INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . .  2

CONFIGURING THE TRANSLATOR . . . . . . . . . . . . . . . . . .  3
     Printer Setup . . . . . . . . . . . . . . . . . . . . . .  4
     Braille Setup . . . . . . . . . . . . . . . . . . . . . .  5
     Braille Format Setup. . . . . . . . . . . . . . . . . . .  5
     Other Setup . . . . . . . . . . . . . . . . . . . . . . .  6

USING THE TRANSLATOR . . . . . . . . . . . . . . . . . . . . .  7
     Translating From The Windows. . . . . . . . . . . . . . .  7
     Translating From The Command Prompt . . . . . . . . . . .  8
          Command Line Switches. . . . . . . . . . . . . . . .  9

SUPPORTED WORD PROCESSORS. . . . . . . . . . . . . . . . . . . 10

FORMATTING FOR BRAILLE . . . . . . . . . . . . . . . . . . . . 10
     Braille Output. . . . . . . . . . . . . . . . . . . . . . 13
     More Formatting . . . . . . . . . . . . . . . . . . . . . 13
          Wordperfect Documents. . . . . . . . . . . . . . . . 13
          Text Documents . . . . . . . . . . . . . . . . . . . 14

AUTOMATIC COMPUTER BRAILLE . . . . . . . . . . . . . . . . . . 15

CHANGING GRADES OF BRAILLE . . . . . . . . . . . . . . . . . . 18
                             TABLES

Command Line Switches. . . . . . . . . . . . . . . . . . . . . 10

Block Typing Directives. . . . . . . . . . . . . . . . . . . . 12

Text Document Directive Strings. . . . . . . . . . . . . . . . 14

Single Letter Computer Braille . . . . . . . . . . . . . . . . 16

Computer Braille Symbols . . . . . . . . . . . . . . . . . . . 17

Braille Grade Directives . . . . . . . . . . . . . . . . . . . 19
                           TRADEMARKS

Wordperfect is a registered trademark of Wordperfect Corporation.

Braille Blazer is a trademark of Blazie Engineering.

IBM is a registered trademark of International Business Machines
     Corporation.


                        LICENSE AGREEMENT

You may obtain and use a demonstration version of E-Z Braille at no
charge.  You may make copies of the demonstration version of the
translator for others provided you copy it in its original form. 
Copy your master demonstration diskette or the EZBRAILLE.EXE file,
if you obtained it from a computerized bulletin board service.  The
diskette or file must not have been changed in any way.

The demonstration version of E-Z Braille is changed to a regular
registered version by purchasing a license from your dealer or from
High Expectations.  You will receive an installation diskette. 
This diskette can reinstall the translator or simply convert your
demonstration version to a real version.  Once you create a real
version, you are using registered software.  You may not distribute
copies of the regular installation diskette or your converted
demonstration version.  You may distribute the demonstration
version in its original form only.

If you have purchased a registered version of E-Z Braille, High
Expectations grants you the right to use the software on a single
computer system.  If you want to move the software to another
computer, you must remove it from the first computer.  Please help
us continue to offer quality products at a reasonable cost by
respecting our license.


                           DISCLAIMER

High Expectations warrants the physical materials in this package. 
If the diskette is bad, we will replace it at no charge.  High
Expectations makes no guarantees, express or implied, for this
software, its usability or fitness for a particular purpose.  You
assume all risks.


                        ACKNOWLEDGEMENTS

It is not common to include an igknowledgements section in a
software package.  In this case, it is necessary because of the
great support we have received in the development of this product. 
Any merits you find in this product are due, in large part, to
good, honest feedback from our beta testers.  Special thanks goes
to Tim Cramner, Rick Roderick and Larry Skutchan.  We must also
express appreciation for the generous openness of the National
Federation of the Blind.  We were permitted to draw upon their
translator's more mature exception tables.  The result is that our
translator will make fewer mistakes when using contractions in
words such as "reallocate".  Finally, we owe a great deal of thanks
to you for giving our translator a chance!


                      NOTATION CONVENTIONS

In this document, filenames, 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 response.  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 the DOCUMENT_FILE with an appropriate
name.  If something is unclear, give us a call and we will answer
your questions.
                          INTRODUCTION

The E-Z Braille translation system is designed to maximize your
access of information using braille.  Every effort has been made to
keep the program simple and natural to use.  Our goal is to provide
you with the highest quality braille output with minimum effort on
your part.  Please contact us with your suggestions, criticisms and
flattery.  Nitpicking is the order of the day - keep a PICK.IT file
and let us know about the small things too.  While you are at it,
give us feedback about this manual and help us to make it clear and
easy to read.

How easy and natural is the translator to use?  Well, you will have
to install the translator onto your computer.  And, yes, you do
need to let the translator know how to find your braille printer,
how many lines does the printer braille on a page and other such
stuff.  After that, we believe you will agree that the translator
is quite easy to use.

You want an example?  Okay, lets suppose you need to write a letter
to a friend who is a braille reader.  You don't know much about
braille but somehow you wound up with a computer with the
Wordperfect word processing program and a braille printer.  You use
Wordperfect to write letters to your friends who read print but you
have never brailled a letter to anyone.  Much of the task is
identical to writing the letter for one of your friends who reads
print.  Create the letter in Wordperfect and make a print copy for
proofing.  When you are satisfied with the letter, save it on your
disk.  Lets assume you store the letter under the name FRIEND.LR. 
Exit (quit) Wordperfect and get to the command prompt.  Turn on
your braille printer and type the following command then press
ENTER.

braille friend.lr

Quickly cover your ears because braille printers have a reputation
for loud clattering sounds.  When the clatter stops, uncover your
ears and tear the letter from the braille printer.  Separate the
braille sheets and slide them into a mailing tube or a manila
envelope.  Address, stamp and mail the letter.

What if you are on the other side of the glasses and are an
excellent braille reader.  You have friends too and some of them
are print readers.  Life has smiled on you and you too have a
computer with Wordperfect and a braille printer.  You need to write
a letter to one of your friends who reads print, so you use
Wordperfect to create the letter.  Before printing and mailing the
letter, you save it to the disk under the name FRIEND.LR and exit
Wordperfect to get to the command prompt.  You want to give it a
good "proof read" so you zap out a braille copy by typing the
following command and pressing ENTER.

braille friend.lr

This is the first time you have used this new up-start translator
so you are a bit skeptical about how well it will format and
braille your letter.  After a careful inspection, you decide the
translator did a pretty good job and that the letter is ready to
send.  You use Wordperfect to make a print copy and confidently
stuff it into an envelope to mail.

If you think the translator might be worth your time, read on to
the next section and get the worst part over.  We will do our best
to make the installation and configuration tasks as painless as
possible.  Let us know if you have some ideas for improving any of
this process.  If you are a courageous computer user, you can try
using the QK_START.TXT file on your install diskette.  It indicates
the steps you must take to get things going and how to use the
translator.  It gives a minimum of explanation; you can always
refer to this manual if you get into trouble.


                          INSTALLATION

1)   If you obtained an installation diskette from a dealer or from
     High Expectations, skip to the next step.  Otherwise, if you
     downloaded the translator from a bulletin board service, you
     need to create an install diskette.  Format a diskette and
     label it as your E-Z Braille Install diskette.  The
     translator's files are packed in the EZBRAILLE.EXE file.  To
     unpack them onto your new install diskette, insert the
     diskette into the drive.  Get to the command prompt.  We will
     assume the downloaded EZBRAILLE.EXE file is currently in the
     directory C:\DOWNLOAD and that the diskette is in drive "A". 
     Adjust the following commands to reflect the correct directory
     and drive.  Enter the following command from the command
     prompt.

     c:\download\ezbraille a:

     The translator's files are extracted and placed on your
     diskette.  You can now use the diskette to install the
     translator onto your computer.

2)   Insert your E-Z Braille Installation diskette into a drive. 
     Get to the command prompt.  We will assume your installation
     diskette is in the "A" drive.  Adjust the following commands
     to reflect the correct drive.  Start the installation by
     entering the following command.

     a:\install

3)   The install program asks you where the translator files are to
     be placed.  Press ENTER to use the default of C:\BRAILLE.  To
     use a different directory, enter the full path of the
     directory.  If you are unsure, use the default (just press
     ENTER).

4)   The install program next asks you for a directory in which to
     place the start program.  The start program allows you to
     start the translator whenever you are at a command prompt. 
     The start program must be in a directory that is included in
     the PATH statement in your AUTOEXEC.BAT file.  Enter the full
     path to the directory.  If you are unsure, you can use the
     default of C:\ by pressing ENTER without typing on the line.

5)   The install program creates the directory for the translator,
     if necessary, and copies all translator files into it.  If you
     have already installed the translator into the directory, the
     install program asks if you want to continue anyway.  In this
     case, if you answer YES, the translator is updated.

When finished, the install program indicates a successful
completion of the install and returns to the command prompt.  If
you get a message indicating that the install program could not
find the start command file, you must either update the PATH
statement in your AUTOEXEC.BAT file as indicated by the install
program or you can start the translator manually.  To start the
translator manually, enter the following command.  Remember to
substitute the correct directory if you are not using the default.

c:\braille\braille

We suggest you give us, or a friend, a call for help in changing
your AUTOEXEC.BAT file to avoid needing to use this method.  In the
meantime, use the previous command to start the translator in the
other examples in this manual.


                   CONFIGURING THE TRANSLATOR

After you install the translator, you need to tell it how to print
on your braille printer.  You may also want to change some other
settings.  Here is what's what.  Start the translator by entering
the following command from the command prompt.  Use the alternate
command discussed in the previous section in place of this one if
necessary.

braille

The copyright screen appears and then the "Braille Generation"
window.  We will discuss this window in the "Using the Translator"
section.  For now, our goal is to tell the program where the
braille printer is connected to the computer and other printer
specific tid-bits.  Notice that the bottom of the "Braille
Generation" window contains a couple of lines that indicate what
keys you can use.  ALT-P is the key for "Printer Setup".  Press
ALT-P and the "Printer Setup" window replaces the "Braille
Generation" window.  Check each of the items on this screen.  If
they are set correctly for your braille printer, leave them alone. 
Refer to the documentation for your braille printer if you do not
know what settings it requires.  Use the ARROW or TAB keys to move
to an item and type a new value.  If you are unsure about an item,
press the F1 or Help key.  A help window will appear below the
"Printer Setup" window.  It will provide an explanation of the item
your cursor is on.  Use the PAGE UP and PAGE DOWN keys to scroll
through the help screens.  Press ESCAPE when you are finished
reading help.  We will also discuss the "Printer Setup" items in
the following paragraphs.  Note that all setup windows are
discussed here.  You must check the "Printer Setup" to produce
braille.  The other settup windows are intended to tailor the
translator to your needs.  You can examine and experiment with
these setup windows as you gain more experience.  For now, just try
the "Printer Setup".


Printer Setup

This setup window contains items that must be set according to your
specific braille printer.  These items must be set according to the
braille printer you are using.

The "Printer Port" item is the name of the printer port that your
braille printer is connected to.  There are two basic types of
ports on your PC.  The serial port and the parallel port.  MsDOS
gives each port on your computer a name.  Programs such as the
translator use the port name when printing.  The name of the serial
port is COM1.  If you have more than one serial port, the second
one is named COM2 etc.  MsDOS refers to your parallel port as LPT1. 
Again, if you have more than one parallel port, the second is named
LPT2 and so forth.  Most ink printers use the parallel port or
LPT1.  To provide flexibility, most of the braille printers
currently on the market provide both a parallel and a serial port. 
If your ink printer is connected to the parallel port, you can
connect your braille printer to the serial port.  The reverse is
also true.  If you do not use an ink printer, we recommend you
connect your braille printer to the parallel port.  The serial
ports require you set communication parameters but the parallel
port needs only to have a cable connecting it to the printer. 
Regardless, the translator must know where your braille printer is
connected.  Enter the port name here if the default value is not
correct.

Most braille printers use a twenty five line by forty character
braille page.  Some can squeeze twenty six or even twenty seven
lines on the same page.  Set the "Lines Per Page" and "Characters
Per Line" items according to your printer.  There are two standard
page sizes used by most braille printers.  The 11.5 by 11 inch
paper can hold twenty five to twenty seven lines by forty to forty
two characters.  The smaller 8.5 by 11 inch paper can hold from
twenty five to twenty seven lines by thirty three to thirty four
characters.  If you are unsure, use the low end of the range for
the size of paper your printer uses.

Most braille printers expect all text sent to it to be in lower
case.  For some, it is a requirement and for others it does not
matter.  A few braille printers require that the text be in upper
case.  The "Upper Case Output" item is used to tell the translator
whether to output all lower case text or all upper case.  If you
are unsure what your printer requires, try using the default
setting.  If the resulting braille looks incorrect, change this
item and try again.  If set to Y, all output text is forced to
upper case.  If set to N, all output is forced to lower case.


Braille Setup

These items tailor the braille translation process to your needs
and tastes.  It is not necessary to change this setup to produce
braille.

The braille code is actually a set of braille codes.  The most
commonly used code is Grade II Braille.  Grade I Braille is also
used for new readers.  Set the "Braille Grade" item to "2" for
grade II and "1" for grade I braille.

Computer braille is a grade of braille used when it is necessary
for the braille reader to know the exact syntax of the text being
read.  It is commonly used for program listings and other computer
related information.  The translator can scan the input text for
text that should be translated into computer braille.  When found,
the translator can automatically output that segment of text as
computer braille and the rest of the input text is output as normal
braille.  The "Automatic Computer Braille" item tells the
translator whether or not to automatically translate this text into
computer braille.

Most braille readers in the United States prefer to have capital
letters indicated by a special capitalization symbol.  The English
do not use the capitalization symbol.  The "English Braille" item
tells the translator whether to generate capitalization symbols. 
When set to Y, no capitalization symbols are generated.


Braille Format Setup

This setup window contains items that control the format of your
braille documents.  Before each document is brailled, these items
are set as the active braille format.  The print document may
change the format as it is being brailled.  It is not necessary to
change these items but you may set them to tailor the braille
format to your tastes and needs.


The "Number Pages" item causes the page number to be placed at the
top right corner of each braille page.  Set this item to N if you
do not want the page numbers.

The "Page Number" item sets the starting page number.

The "Widows/Orphan Protection" item prevents the first line of a
paragraph from being widowed at the bottom of a page and the last
line from being orphaned at the top of a page.  Set this item to N
to turn this protection off.

The margin items specify the amount of blank or white space to
leave on the boarders of each braille page.  The "Left" margin
specifies the width of the left margin.  If set to 0, the braille
text is printed from the left edge of the paper.  If set to 1, the
text is shifted to the right by one space to leave a left boarder. 
The other margins work in the same way.  If the right margin is set
to 0, the text is printed upto the right edge.  If set to 1, a one
space boarder is maintained on the right edge of the page.  The top
and bottom margins are given in lines rather than characters but
are otherwise identical.

The "Line Spacing" item sets the number of lines used for each
actual brailled line.  If set to 1, each brailled line will occupy
one line on the page; no blank lines between braille lines.  If set
to 2, a blank  line is placed between braille lines.

The "Supress Hard Pages" item is used to conserve braille paper. 
When set to Y, hard page breaks in the print document are replaced
by a blank line in the braille document.  When set to N, page
breaks in the print document will cause corresponding page breaks
in the braille.


Other Setup

These items are for more advanced users.  The items here should be
changed only if you know what you are doing.  Otherwise, leave them
alone.

The "Input Document Type" item is used to tell the translator what
type of document to expect.  Set this item to AUTOSELECT.  The
translator will then examine each document and determine what word
processor created it.  It can then create a braille copy of the
document.

The "Translation Table" item should only be changed by advanced
users!  This item tells the translator the name of the translation
table to use to convert the print text to braille.  Most users
should leave this item alone!

The "Trace Translation Table" item is a debugging tool for advanced
users who have made changes to the translation table.  It causes
the translator to display each translation rule before it is
tested.  Leave this item set to N.


                      USING THE TRANSLATOR

What do you need to know to use the translator?  We presented an
example in the "Introduction" section of a nonbraille user printing
a braille letter for a friend.  The example is illustrative of how
you will use the translator.  You should create your document
without worrying about braille.  When it looks write in print or on
screen, you can store the document on disk, get to the command
prompt and tell the translator to make a braille copy.  There are
a couple of ways to tell the translator to make a braille copy of
a document.  The example from the "Introduction" used a command
that was entered from the command prompt.  The translator's windows
provide an alternative.  The following topics discuss both methods
in more detail.


Translating From The Windows

Translating from the windows is quite simple.  To start the
translator from the command prompt, enter the following command.

braille

The copyright screen appears and then the "Braille Generation"
window.  The "Braille Generation" window contains two items.  The
"Document to be Brailled" item is the name of the print document
that you want to make a braille copy of.  The "File for Braille
Output" item is normally left blank and the braille document is
sent to the braille printer for a hard copy.  If a filename is
typed here, a soft braille copy of the document is stored into the
named file and nothing is sent to the braille printer.  To make a
braille copy of the letter discussed in the "Introduction" section,
you enter FRIEND.LR in the "Document to be Brailled" item.  Press
ENTER and the cursor moves to the "File for Braille Output" item. 
Press ENTER again and the braille printer should start to clatter
as it produces the braille copy.  When finished printing, the
"Braille Generation" window is shown permitting you to braille more
documents.  Press ESCAPE when you are finished.  You are returned
to the command prompt.

While in the "Braille Generation" window, notice the lines at the
bottom of the window.  These lines indicate what keys are
available.  The F1 key displays help information for the item under
the cursor.  ESCAPE is used to exit the translator and return to
the command prompt.  ALT-S saves any changes you make to your
setup.  Control-ENTER is used to start making a braille copy - this
is a short-cut way to say that all items are set so start
brailling.  The other keys are used when you want to make changes
to your setup or configuration.  Press ALT-P to go to the "Printer
Setup".  ALT-F brings up the "Braille Format Setup" window, ALT-B
is for the "Braille Setup" window and ALT-O is for the "Other
Setup" window.  Each of these windows works like the "Braille
Generation" window.  Use the ARROW and TAB keys to move among the
items.  To change an item, move to the item and type the new value
over the old one.  Press F1 to get help on the item under the
cursor.  The list of available keys is always shown at the bottom
of the window.  Be sure you use ALT-S to save any setup changes you
make.


Translating From The Command Prompt

Telling the translator to make a braille copy of a document from
the command prompt saves time and keystrokes.  The translator must
first be installed and setup to use your printer.  To make a
braille copy from the command prompt, use the same command that you
use to go to the windows.  The difference is that you add the name
of the document to be brailled.  You may also add the name of a
file that the formatted braille output will be stored into.  Here
is the general form of the command you will use.

braille document_file output_file

Replace DOCUMENT_FILE with the name of your document.  If you want
a hard braille copy of the document, leave OUTPUT_FILE off of the
command.  If you type the OUTPUT_FILE with the command, the
translator will not use the braille printer but will store the
output braille into the OUTPUT_FILE.  You can later copy this file
directly to your braille printer to make a hard braille copy.  Look
at the following examples.

braille friend.lr

This may look familiar.  This command makes a hard copy of the
document named FRIEND.LR (assuming your braille printer is turned
on and ready to print).

braille friend.lr output.brl

This command also makes a braille copy of the document FRIEND.LR. 
This time, the braille is not a hard copy; it is not printed on the
braille printer.  Instead, the braille is stored into the file
named OUTPUT.BRL.  OUTPUT.BRL is a soft braille copy.  You can use
the MsDOS file COPY command to copy OUTPUT.BRL to the name of your
printer port.  The result will be a hard braille copy.  See your
MsDOS manual for information on using the COPY command.

Your command can also tell the translator to use a different
printer port and other such things.  See the following section for
all of the details.  If you are content with what you know about
using the translator from the command prompt, you can skip the next
section.  You can read it later if the need arises.


     Command Line Switches

Command line switches permit you to override your configuration
options from the command prompt.  As a new user, you may wish to
skip this section for now.  You can read it after you are more
comfortable with the translator and are ready to try something new. 
For those who are ready for something a bit more technical, read
on.

What is a command line switch?  The command line is another name
for the command prompt.  A switch is like a light switch; it turns
an item on and off.  The command line switches are used to override
item settings in your configuration.  For example, if you set
your"Braille Grade" configuration item to "2" for grade II braille,
you can use a command line switch that tells the translator to use
grade I braille for this document.  The switches are added to your
command when you translate a document from the command prompt. 
Each switch is preceded with a dash "-" or slash "/" character. 
The single letter switch name follows the dash.  Some of the
switches require a parameter or value.  The value is typed after
the switch name.  Here are some examples.

braille friend.lr -g1

This command translates the document FRIEND.LR using grade I
braille.  The "G" switch overrides the "Braille Grade"
configuration item.  The "1" following the switch is a parameter
telling the translator to use grade I braille.  Note that there is
a space on each side of the switch but there are no spaces between
the dash, the switch name and the parameter.

braille friend.lr -pcom1

This command also makes a braille copy of the FRIEND.LR document. 
The grade of braille used depends on the "Braille Grade"
configuration item.  The "P" switch overrides the "Printer Port"
configuration item.  The braille printer is assumed to use the
serial port COM1.

The full list of command line switches is shown in the following
table.


                      Command Line Switches

Switch         Description

/a             autocomputer braille y = on, n = off
/c             sets printer columns per page to its parameter
/d             debug mode is used for translation table debugging
/e             english braille takes a parameter of (n = no) or (y
               = yes)
/g             braille grade takes a parameter of 1 = Grade I or 2
               = Grade II braille
/l             sets printer lines per page to its parameter value
/p             printer port takes port name as a parameter
/t             translator takes translation table name as a
               parameter
/u             uppercase output text y = yes, n = no
/w             word processor type takes type-name as a parameter


                    SUPPORTED WORD PROCESSORS

E-Z Braille can read documents created by Wordperfect versions 4.2,
5.0 and 5.1.  It can also read documents created by a text editor
or a document that is created by another word processor but that is
stored or saved as a text file.  We plan to support many other word
processors in the near future.  You can help by telling us what
word processors you might like to use.

If you have a word processor that is not currently supported, you
can still make braille copies of your word processor documents. 
Most word processors store documents in a specialized format that
is specific to that word processor.  Most of these can also store
the document into a generic format that any other word processor or
program can use.  This generic format is generally referred to as
a ASCII text file or as a text file.  Refer to your word
processor's manual for instructions on storing a document as a text
file or text document.  Be forewarned that some of your print
formatting will not be stored in the text document.  Centering,
underlining, page numbering and so forth will disappear.  The
section "Text Documents" explains how to add this printer
formatting to text documents.


                     FORMATTING FOR BRAILLE

Lets start with the punch line - format your document so it looks
nice in print and it should look nice in braille when you make the
braille copy.  This is true regardless of what word processor or
text editor created the document.  Okay, now for the body of the
joke.

Braille is significantly bulkier than print; a braille page has
about half as many lines and columns as the same sized print page. 
The result is that braille and print formatting are not very
similar.  Print material uses white space and special print styles,
underlining and the like to permit rapid visual scanning.  For
braille, the white space is wasteful as it adds to the bulk of the
braille document.  Braille has only one print style, thus it uses
special symbols and formatting to highlight text for the tactual
(finger tips) reader.

Gee, if the differences between print and braille are so great, how
can good print formatting relate to good braille formatting?  Well,
it works like this.  The translator knows how to format a braille
paragraph, a braille hanging paragraph, braille list and so forth. 
The important thing is to know which to use on what text.  The
translator examines the punctuation and the formatting
(particularly the left margin) of each chunk or block of text in
the document.  It uses this information to "type" the text block -
this one is a paragraph because the first line is indented, the
rest are not and it ends with a period.  Once the block of text is
"typed", it can be reformatted to look nice in braille.  And that
brings us to the answer to the question.  If the print document is
nicely formatted, the translator can more accurately recognize each
block of text and produce nicer braille.  The following discussion
will clarify what the translator looks for and how it formats the
various  blocks.

The translator recognizes three types of paragraphs in the
document.  A block style paragraph has a blank line before and
after and none of the lines is indented (there is no indent or
outdent.)  An indented paragraph has the first line indented.  A
hanging paragraph has the first line outdented and the remaining
lines are indented.  In other words, the block paragraph has an
even left edge with a blank line before and after each paragraph. 
The indented paragraph has the first line shifted to the right
while the hanging paragraph has the first line shifted to the left. 
Several indented paragraphs or several hanging paragraphs may
follow one another with no separating blank line.  The left margin
and blank lines are important for determining the start of each
paragraph or list item.  Punctuation and its placement are the key
factors in determining that the text is paragraphical.  The
paragraph must have some normal sentence terminating punctuation:
period, question mark or exclamation.  The end of the block must
end with a period, question mark, exclamation or colon character. 
Quotes and parenthesis are ignored here.  If no such punctuation is
found, the text is assumed to be a list, table or heading.  A
paragraph formatted as a list, table or heading is not nicely
formatted braille.

Tables, lists and headings must first fail the paragraph test. 
Then, if the text contains tabs, it is assumed to be a table.  If
the text is centered or there is only one line, it is assumed to be
a heading.  Otherwise, the text is assumed to be a list.  Two types
of lists are supported.  The standard list has each item starting
at the same indention level.  If a line is indented, it is assumed
to be a continuation of the previous line.  The code block is a
list too but an indented line is not assumed to be a continuation
of the previous line.  Rather, it is assumed to be a list item on
a new indention level.  The translator uses line length to
distinguish between standard and code lists.  As with the standard
list block, table items may have entries that occupy more than one
line if the extra lines are indented.  Heading table and list
blocks are assumed to be separated from other text and from one
another by blank lines.

The translator is most likely to become confused when list or table
entries or headings are ended with sentence terminating
punctuation.  If your list items end with a period, the translator
may assume the list is a block paragraph.  The resulting braille
will not be correctly formatted in this case.

What do you do if the translator is confused by a particular block
of text and formats it as a paragraph when it is a list?  We hope
this will not happen often!  But, if it does, you can correct the
problem by preceding the block of text with a block type directive. 
A block type directive is a sequence of characters that tells the
translator what type of block follows.  The directive should be
placed at the beginning of the block and there should be a blank
line preceding the block.  The directives consist of a directive
start character (the "~" or tilde), the directive name and then the
end directive character "." or the period).  A list of the block
typing directives follows.  Note that the start and end character
are not shown.  Also, note that these directives may be used
regardless of what word processor or text editor was used to create
the document.


                     Block Typing Directives

Directive           Block Type

p                   paragraph
hp                  hanging paragraph
l                   standard list
code                code list
t                   table
h                   heading


Braille Output

How does the translator format text for the braille copy?  Hanging
paragraphs are formatted as hanging paragraphs in braille; the
first line is outdented and the subsequent lines are indented two
spaces to the right.  If there is a blank line separating two
hanging paragraphs, it is removed.  The block and indented
paragraphs are formatted as indented braille paragraphs.  The first
line is indented two spaces to the right.  If there is a blank line
separating two paragraphs, it is removed.  Headings are formatted
as they are in the print document.  If the line is centered, it is
centered in braille.  If it is at the left margin, the same is true
for the braille heading.  If indented, it is similarly indented in
braille.  If the text block is a standard list, each entry of the
list is outdented.  If an entry requires more than one braille
line, the extra lines are indented two spaces to the right.  Code
lists have each item indented according to their indention level in
the print document.  If the entry is indented to the second
indention level in the print document, it is indented to the second
level in braille.  Each indention level is shifted two spaces
further to the right.  If an entry requires more than one braille
line, the subsequent lines are indented two indention levels or by
four spaces.  Table blocks are formatted much the same as standard
lists.  Each entry in the table is outdented with extra lines being
indented two spaces.  The fields of the table are separated by a
cimicolon and two spaces.  If there are multiple blank lines above
or below a table, list or heading, they are compressed to a single
blank line.  A blank line is retained above and below for clarity.


More Formatting

E-Z Braille supports most of the standard formatting provided by
Wordperfect and other quality word processors.  If you are using a
supported word processor, the translator will recognize and use
your centering, underlining, page numbering, table of contents
generation and so forth.  At the risk of sounding redundant, we
will say once again: "Format it nicely in print and it will be
nicely formatted in braille."  If the translator does not
specifically support a certain type of formatting, it will ignore
it and continue working with the rest of the document.  The
following sections will discuss special issues for each type of
word processor or text editor.  Read the sections that pertain to
you and skip the rest.


     Wordperfect Documents

E-Z Braille supports most of Wordperfect's standard formatting
including: centering of lines and pages, underlining, tabbing, hard
returns and end of page, orphan/widow protection, conditional end
of page, table of contents and listing generation, margin changes,
page numbering, hanging paragraphs and more.  Note that underlined
text is italicized in braille.  Also, if you generate a table of
contents or a list in Word Perfect, you must delete the generated
text before storing the document and creating a braille copy.  The
translator can find the start of the generated text but cannot
determine if the following text is real or generated text.


     Text Documents

Text documents are documents created using a text editor.  They can
also be produced by a word processor.  If you are using a word
processor that is not currently supported by the translator, you
can probably tell your word processor to make a text copy of your
document.  You can then make a braille copy from the text document.

To do formatting such as centering and underlining in a text
document, you must go to a bit more trouble than is the case for a
word processor.  In a word processor, if you want to center a line,
you press a center key and the line appears centered on the screen. 
A text editor is not so sophisticated!  It will not format for you. 
You must use format directive strings to get the job done.  These
directive strings do not make the line in your editor appear as
centered but they will tell the translator to center the line in
braille.  Note that these directives should be used as if you were
formatting the document for print.  The translator will convert
them for braille.  If you enter values for braille, they may be
converted to inappropriate values by the translator.  The format
directive strings consist of the directive start character (the "~"
or tilde) followed by the directive name and, in some cases, a
parameter.  The directive string is ended with the end directive
character (the "." or period.)  The following table lists the
available format directive strings for text documents.


                 Text Document Directive Strings

Directive                Purpose

c                        center this line
centerpage               vertically center this page
cp#                      conditional end of page
ul                       start underlining
eul                      end underlining
page                     hard end of page
numberpages              start numbering pages
pagenum#                 set page number
pagenumtype#             (0 = arabic, 1 = roman)
widows#                  widow/orphan protection (0 = off, 1 = on)
block_on                 start protect block
block_off                end protect block
ls#                      set line spacing
bm#                      bottom margin set
tm#                      top margin set
lm#                      left margin set
rm#                      right margin set
mtc#                     mark table of contents (# is level number)
emtc#                    end mark table of contents (# is level
                         number)
gentoc                   generate table of contents here
mtl#                     mark list (# is section number)
emtl#                    end mark list (# is section number)
genlist                  generate list here

Here are a few examples of using format directive strings in a text
document.

~c. Center this line

This directive string centers the text "Center this line" on the
line.

~cp5. Conditionally Forced Heading

This directive string prevents the next five lines from being split
across pages.  If there are fewer than five lines remaining on the
current page, the text starting with the current line is pushed to
the top of the next page.

~numberpages. Do Page Numbering

This starts printing page numbers on the top right corner of each
braille page.


                   AUTOMATIC COMPUTER BRAILLE

Most of the text we read is basic literature and standard Grade II
braille provides a clear, efficient code for reading the text in
braille.  Sometimes, however, we must read text that contains
unusual symbols and computer filenames and (bless us all) computer
program listings.  In these situations, Grade II braille often is
ambiguous and even misleading.  We have added a few features to our
translator that should help make the text you are reading clear. 
The best part is that the translator does the work automatically;
you need not tell it where the problems are, it detects them and
takes actions to make the text easier to read.  The translator uses
a special symbol code (dots 4,5,6) to indicate symbols such as the
slash, asterisk and number sign when they are otherwise unclear. 
These symbols are called single letter computer braille.  This name
is not completely accurate - the symbols are not computer braille
but they are very similar.  The single letter computer braille
symbols are shown in the following table.  Each symbol consists of
two cells.  The first cell is always the dots 4,5,6 indicator
symbol.  The dots for the second cell are shown in the table along
with the meaning of the symbol.


                 Single Letter Computer Braille

Dots           Symbol

3,4            slash or division
1,6            asterisk or times symbol
3,4,5,6        number sign
1,2,3,4,5,6    equal symbol
4,5,6          underline symbol

For more serious situations, the translator drops automatically
into computer braille.  When regular text is encountered again, the
translator resumes with Grade II braille.  The computer braille
looks very strange to a first-time reader of computer braille.  The
familiar contractions and capitalizations are replaced with
uncontracted letters and strange symbols replace the familiar
punctuation symbols.  Once you are comfortable with computer
braille, you realize its power.  It allows the reader to know
exactly what the text contains.  There are no ambiguities in
computer braille.

How does computer braille work?  Grade II and even grade I braille
can be ambiguous because the meaning of many symbols depends on the
context in which it is used.  The symbol made of dots 2,5,6
represents the letters "dis" when at the beginning of a word, "dd"
when in the middle of a word and the period "." when at the end of
a word.  That works fine for most literature but what if you are
looking at a computer filename or other computer type name that
contains a period in the middle of the word.  Is the semble the
"dd" or a period?  You might even have a period at the beginning of
the word.  Is it "dis" or a period?  There are many similar
situations.  Another problem comes to play when unusual symbols
such as the tilde are used.  Grade II makes extensive use of almost
every possible combination of symbols for contractions and regular
punctuation.  There are simply no dot combinations left for symbols
such as tilde.  Computer braille avoids all of these problems by
sacrificing contractions.  Then, it assigns a dot sequence to most
of the symbols.  A few symbols require a shift indicator because,
even in computer braille, there are simply not enough possible dot
combinations to go around.  The following discussion and table will
specify the computer braille code.

Letters look the same as for grade I or II braille.  If a single
letter is capitalized, the shift indicator (dots 4,5,6) precedes
the letter.  If two or more capital letters appear together, the
caps lock indicator precedes the letters.  The caps release
indicator is used, if needed, to indicate the following letters as
lowercase.  Numeric digits look the same but they are "dropped"
down in the cell and are not preceded by the number sign.  You will
not recognize any of the punctuation symbols; refer to the
following table.  The following table specifies the computer
braille symbols.  The dots' column specifies the dots for the
symbol.  Several symbols occupy two cells.  In this case, the first
cell is the shift indicator (dots 4,5,6).  We will mark these
symbols with an underline "_" symbol followed by the dot numbers
for the second cell.  Note that the shift indicator is generally
used to indicate symbols that you normally must press the shift to
obtain on the computer.  In these cases, the second cell will look
like the unshifted symbol preceded by the shift indicator.  The
vertical bar, for example,  is the shift of the back slash so the
symbols in computer braille are identical but the vertical bar is
preceded by the shift indicator.


                    Computer Braille Symbols

Dots           Symbol

_3,4,6         start computer braille
_1,5,6         end computer braille
_3,4,5         caps lock - following letters are upper case
_1,2,6         caps release - the following letters are lower case
_1,2,3,4,6     line continuation - line is continued on next line
3              apostrophe (single quote)
5              quote or double quote
6              coma
4,6            period or decimal point
1,4,5,6        question mark
2,3,4,6        exclamation
1,5,6          colon
5,6            cimicolon
3,4            slash or division symbol
1,6            asterisk or times indicator
3,6            dash or subtraction indicator
3,4,6          plus or addition indicator
1,2,3,5,6      left parenthesis
2,3,4,5,6      right parenthesis
4              at sign
3,4,5,6        number sign
1,2,4,6        dollar
1,4,6          percent
4,5            carrot or up arrow
1,2,3,4,6      ampersand or and symbol
_4,5,6         underline
1,2,3,4,5,6    equal symbol
2,4,6          left bracket
_2,4,6         left brace
1,2,4,5,6      right bracket
_1,2,4,5,6     right brace
1,2,5,6        back or reverse slash
_1,2,5,6       vertical bar
3,4,5          greater than
1,2,6          less than
_4,5           tilde
_4             grove accent

The shift indicator is also used to precede sequences of symbols
that are all in the lower part of the cell.  If, for example, there
are numbers separated by spaces, the shift indicator is placed in
front of the sequence to make it clear that the symbols are numeric
digits and not letters.  Spaces and tabs are also shown clearly. 
Countable spaces are used to indicate the exact number of spaces. 
If there are five or more spaces in a row, the countable spaces are
used.  The sequence is preceded and ended by a regular space.  The
remaining spaces are displayed as the shift indicator followed by
full cell symbols.  For example, five spaces are shown as the
sequence: space, shift indicator, full cell, full cell, space.  Six
spaces would require a third full cell be added to the sequence. 
Tabs are not specifically supported in computer braille but E-Z
Braille has implemented a simple system that will serve until a
better standard is established.  In our experience, the number of
tabs is not important - the need is for a field separator for
tables that are translated into computer braille.  We use the
symbol: space shift indicator, full cell, space.  Note this looks
like the countable spaces symbol.  However, for countable spaces,
you will always have at least two full cells in the sequence. 
Here, we have only one full cell.

If you don't want the computer braille, you can disable the
automatic generation of computer braille by turning it off in your
configuration or with the "a" command line switch.  See the
sections "Configuring the Translator" and "Command Line Switches"
for details.


                   CHANGING GRADES OF BRAILLE

You can make a copy of a document using grade I or grade II braille
for its entirety, but sometimes you need a mix of the grades of
braille in a single document.  You can place directive strings in
your text to change from one to another type of translation.  If
the auto computer braille setting is on, you can also use a grade
I or grade II braille directive string at the beginning of a
specific block to prevent the translator from using computer
braille in the block.  The directive strings start with a tilde (~)
character.  They end with a dot (.) character.  The directives
include the following.


                    Braille Grade Directives

Directive      Translates To

gr0            no translation
gr1            grade I braille
gr2            grade II braille
cb             computer braille
ecb            end computer braille - resume previous grade
tcb            temp computer braille - until space
eb1            english braille - no case indicators
eb0            english braille off

You may change the grade of braille being used at any point in your
document.  If you find yourself using the grade I or grade II
directive to prevent a block from being autotranslated as a
computer braille block more than once in a while, please contact us
so we can improve the detection of computer braille blocks.
