
   README file for svlpro program by Brett Barback copyright 1999 by
   Brett Barback nukes@eznet.net Last update: 3/7/99, 016:00:00 EST
   Latest Version 3.4
   
   [Contents]
    1. Latest svlpro news
    2. Introduction to svlpro 
    3. . requirements and supported synths 
    4. features 
    5. . installation 
    6. . the synth.ini file 
    7. . invoking svlpro 
    8. . command mode use 
    9. . review mode 
   10. . future of svlpro 
       
   Introduction to svlpro
[1. Introduction to svlpro]

   What is svlpro?   Svlpro is a full screen screen reader and text to speech
engine for hardware synthesizers on a serial port on your linux operating syste
m.
   Svlpro has immediate speech response for working  in your shell environment
under linux , and has a full screen review feature that works from both command
 and
review mode.
   Svlpro also allows you to control many features of your synthesizer from
the review mode of the program.
   Svlpro transparently intercepts all text input and output from your shell's
terminal and passes it through to your synthesizer while allowing the normal
operation of most programs commonly used under linux, such as lynx, ncftp, irc,
mail,ex and ed editors, and many i have yet to test.
   Svlpro is stil in its infancy but since i use it myself i can assure anyone
who finds it useful and lets me know that i will endeavor to make svlpro work
with as many synthesizers as i can figure out the code for.
   At this point this is the second release of svlpro ; the first versions
were a breakthrough for me as i had been trying to access my linux terminal dir
ectly
for about two years while having to learn linux at the same time.
   With the first release and the help of many on the blinux mailing list i
was able to revise the original code into a smoother more efficient package tha
t
I feel can meet the needs of many blind users of linux with speech devices.

   If you try this program and like it , or find bugs or some lack of support f
or
a synthesizer , let me know and i will work to make it work for you.

   Requirements for svlpro
[2. Requirements and supported synthesizers]

   Currently svlpro works very well with my echo pc synthesizer from street ele
ctronics,
and should work just as well on a number of other synths that i am aware of
so i took the liberty of adding the basic settings for those synths in the synt
h.ini file.
   Currently svlpro will work with any serial device on a com port or a driver
which
has a pipline or device file in the /dev directory on your linux operating syst
em.

   Svlpro knows about the following synthesizers already:
1.  accentsa
2. apollo2
3. braille and speak
4. dectalk express
5. echo pc
6. litetalk
7. speakout
8. transport

   I tried to add the minimal amount of variables for each synth according to
the information I could gather from people who tested the original svlpro and
what documentation i could gather.

   svlpro works very well with the bash shell under linux and a vt100 terminal.
   I fully expect some negative feedback on it's behavior under different shell
s,
and with other terminals, but i simply don't have time to test every one of the
m
and I rely on the people who use the program to let me know what works and what

doesn't.

   Features of svlpro
[2.1. features]

   Svlpro has the following features:
1. immediate speech response from linux shell.
2. full screen review from both command and review mode.
3. synthesizer control from program review mode interface.
4. command line options to select synthesizer configuration and com port.
5. simple configuration file to allow greater user control.
6. compact executable binary for use on linux root install diskettes.
7.   audio signals thru pc speaker to notify of caps  lock, scroll lock and num
 lock states.

And much much more to come.


   Installation of svlpro
[3. installation of svlpro]

   The svlpro binary package requires little installationand should pose few
problems.

   To install on your system do the following:

1. download the package in either tar.gz format or zip format from my web site.

2. Read this README file and the synth.ini file which are contained in the
archive packages.

3. Edit the synth.ini file to reflect what synth you use and what port and
variables you wish to use.
   Detailed instructions on the format of the synth.ini file are contained
in the file itself.

4. svlpro currently requires root privelidges for installation so log in as roo
t and
 Use the makefile to install the svlpro binary to the /bin directory.
  You can edit the Makefile if you desire another location for svlpro.
   the location of the svlpro executable doesnt matter as long as you can acces
s it.

5. copy the synth.ini and any other .ini files for whatever synthesizers you pl
an
to use to your home directory or a default directory which can be specified wit
h
the svlrc environment variable.
*** NOTE: You can change the location of the synth.ini file to something differ
ent
if you set an environment variable called "svlrc"  to point to your default
svlpro directory.
for example:
if you put your svlpro init files in a directory called /root/.svlpro/ then
your environment variable would be set like this:

for bash /sh shells:
export svlrc="/root/.svlpro"

for csh shells:
setenv svlrc "/root/.svlpro"


6. Svlpro requires the /dev/vcs0 and /dev/vcsa0 virtual console devices  to
so you must create them and set their permissions properly.

  To create the vcs files in the /dev/directory type

make vcs


   ; synth.ini file
[4. the synth.ini file ]

   The synth.ini is styled after the windows type .ini files and is pretty
freestyle as far as placement of the variables and sections.

   The [synth] section  defines which synth you use by default and which
port and configuration file to be used .

the synth variable:
format: synth string
command line switch: -s string
   where string is the name of the synthesizer or configuration you wish to use

by default.
  this variable will be announced when svlpro successfully initializes the synt
h.

the port variable:
format: port string
  where string is either a file name in /dev such as /dev/ttyS0 or a hexidecima
l number
representing a port adress. (see the port variable later in this text.).
  if this variable is missing a default port variable found in the individual
configuration file will be used if it exists. or the command line parameter -p
port is used.
see the port variable in the individual synth  ini file section below.

the file variable:
format: file string
   where string is a valid file name of an initialization file containing setti
ngs
for a particular synthesizer , it's port address and desired initilization,
or other data needed to make the synthesizer work properly.
  note that svlpro looks for these files as well as the synth.ini  in either th
e
user's home directory or a directory specified by the svlrc environment variabl
e.


   The [user] section of the synth.ini file defines what shell you wish to use
while running svlpro and whether it's a login shell or not.
   The first variable in this section must be a full path pointing to the
location of your desired shell program; (/bin/bash by default).
   The second parameter is the name of the shell such as bash  or csh.
   Any additional  parameters are arguments to be passed to the shell upon
startup, such as -login to make bash a login shell , or -l to make tcsh a login
shell, (consult the man pages on the shell you intend to use).

   The [svlpro] section contains settings for some of svlpro's internal variabl
es
which you wish to have set at program startup.
  current valid entries are as follows:

echo string
caps string
nums string
speed string

   string may be either on, off, or a numeric or string value, depending on the
 context of
the variable.

  all variables in this section may also be set during run-time with the /set
command from review mode.

  the echo variable
format: echo on/off
  determines whether svlpro should speak characters as they are typed at the ke
yboard.

the caps variable:
format: caps on/off
  determines whether svlpro should announce when it encounters a capitalized le
tter.
  When svlpro encounters a capital letter it will say the word cap preceding th
e letter.
  *** future versions will allow the variation of pitch or volume when a capita
l
is encountered.

The nums variable:
format: nums  on/off
  determines whether svlpro should speak numeric data it encounters as single d
igit
by digit or as phrases such as thousand, million, etc....

the speed variable:
format speed decimal value
  the decimal value is multiplied by 1/12 th of a second to assist if you exper
ience
problems when running svlpro on a slow or extremely fast machine.  higher value
s
increase time between reads and writes, lower values decrease the time between
reads and writes.

   The [dict] section allows a user to define character to word or phrase
mappings for those who have synthesizers without onboard dictionary buffers; i.
e. echo;
   If your synth has it's own dictionary you wish to use, simply  rename the se
ction to something like [nodict]
   This tells svlpro to ignore the dictionary section
   ***note: don't simply comment out the line with the [dict] on it like #[dict
]
as this will allow svlpro to interpret the remaining arguments in the dictionar
y
section and add them to the previously accessed section.
   You could however , delete the entire dictionary section if you have no plan
s
to use it, but re-creating it would have to be done manually until i can
implement a run time dictionary definition function (which is  planned soon)

*** NOTE ***
  As of version 3.2 individual synthesizer configurations are now contained in
their own individual .ini files (usually with the name of the synth; such as "e
cho.ini")

*** Individual synthesizer .ini file ***

The individual synthesizer .ini files allow a user to start svlpro  using
different synthesizers and different configurations simply by naming the config
uration
at the command line or in the synth.ini file.

   The most important and most complex section is the section pertaining to
the selected synthesizer.
   In this section we define the special characters, strings and values of
settings that are used to control the synthesizer from the svlpro interface.

  This section contains variables such as driver, port,  baud, handshake , etc
, etc.

  The driver variable:
format:  driver [string]
command line switch: -d [string]
   string may be either serial or internal, or may be omitted, in which case se
rial is used by default.


  The port variable
format: port
command line switch: -p

  The string may be either the name of a file in the /dev directory such as
/dev/ttyS0 for com1 , or /dev/dtpc0 for the dectalk pc module by nico@cam.org.
   You may also use a hexidecimal representation of the port address, such as 0
x3f8
for com1 or 0x2f8 for com2 .   In this manner , it may be possible to access an
 internal
synthesizer board if you also specify internal for the driver varaible and give
a correct board start address for the port variable.

The command line switch will override any port specified in the ini files.
        This switch should be used if running svlpro from a linux install root
diskette,
since svlpro's synth.ini file is configured to use a default port which may
or may not be the one your synth is attached to.

*** baud and handshake variables implemented with version 3.4 ***

the baud and handhshake variables apply to devices when the driver variable is
set to serial.

the baud variable:
format: baud speed,parity,databits,stopbits
    settings to configure the serial port are usually device specific ,   a con
figuration of
 9600 bps, no parity and 8 data bits and 1 stop bit   is common and will be sel
ected
by default if this variable is missing.

the handshake variable:
format handshake string
  string is either cts , for rtscts flow control,
or xon for xon/xoff flow control.
   cts is selected by default if this variable is missing.

   Next, we have the strings and character variables and their values which
are used to control such things as rate, pitch, volume, intonation, gender and
the like , which are specific to the particular synthesizer being used  so
consult your synthesizer documentation if you plan to add any variables here.

  At present there are three fields which must be filled in as follows:

label value string/chars


   The label field contains a string which is used to identify the variable to
svlpro and can be any word or phrase that describes the variable to the user.
   The word should not start with a hash mark (used for comments) , or a '['
character  (used for sections),  although these characters may appear elsewhere
in the string.

   The value field should contain a decimal value to which the variable will be
set upon startup.
   Some variables require no value at all but this field must at least contain
a zero (0), in which case it is only passed when required.
   For synths that use hexidecimal and octal values, these  values should be
converted to decimal in the synth.ini file until i implement an internal
conversion within svlpro.

   The third field is the most important and most complex, although  I took
great care to make it both simple and universal to work between svlpro and
the various synths used with it.

  The control string field contains the format of the command to the synthesize
r
in dos conventions with unix style variable substitutions.
   This makes for easy editting and entry of control characters  and strings
in a highly readable fashion.

      Control characters are represented by the letter of the key preceded by
an upcarrot sign (^),  and case is not important.
   When svlpro encounters an '^' sign in this field it converts the next
character it encounters to a control character before sending it to the synth.

   When svlpro encounters a percent sign (%), in the command field it converts
the value in the value field according to the next character encountered
in the command field and then sends it to the synthesizer.
   Valid '%' values are '%d' for a decimal value, '%s' for a string value,
and future improvements will accommadate other data types and special variables
.

   The command field can contain white space and thus should be enclosed in
quotation marks ("), which will be ignored
unless preceded by a backslash (\);

   All other characters in the command field are passed literally to the synth.

   the '^', '%', '"' and  '\' characters can be entered literally in the
command field by preceding them with a backslash (\).

   ***note: most synths command fields are case sensitive with respect to
the strings and characters used to control the synth's functions. Also , the
order of the  value/parameter is important and in some cases, the conversion
of the value passed is important as well.

   Consult your synthesizer documentation to verify that your command strings
are correct.

   The [init] section contains a list of variables that should be sent to the
synthesizer  upon program startup.
   Use the symbolic or "label" name for the variable here and svlpro will get
the string and value for that variable from the synthesizer definition section.
  Thus, the variable must be pre-defined or it will not be processed.
For example:
   If you defined an init string in the section for your accent as below,

[accent]
port /dev/ttys0
silent 0 ^x
init 0 ^[y^[w^[e^m

then your [init] section would look simply like this,

[init]
init

   future improvements to the program will add a key macro definition section ,

window definition section for monitoring specific parts of your run time
screen, and multiple speech environment sections that allow reloading and savin
g
of different speech setups for recall during run time.

   Svlpro expects to find the synth.ini file in your home directory upon startu
p
unless you set the svlrc environment variable  to point to a different location
or file name.
see the section on installation for more details on the svlrc environment
variable.

   Invoking svlpro
[5. invoking svlpro]

   Once svlpro is properly installed, starting it is as easy as typing

svlpro

or

svlpro -s synthname

   If the program is operating properly and initializes the synthesizer should
speak and announce:

 synthname ready

   This serves to indicate that svlpro has selected the proper synthesizer
configuration from the synth.ini file and has opened the device and initialized

it according too the [init] section of synth.ini.

   If you fail to hear the synth speak then check your synth.ini file to ensure

you selected the proper port and that your initilization strings are correct.
   Also check that the permissions on the device allow you access and that your
synth is properly attached and turned on.

   if all is correct then try typing the alt-O key combination to see if
your terminal emits a beep.  If the terminal beeps then svlpro has failed and
you are left at your speechless linux shell prompt.

   Try restarting svlpro redirecting it's output to a file or another
terminal where you have speech or braille access to see
what error code gets reported.

   Error codes start at 1 and increase according to svlpro's progress during
the attempt at startup.
  Codes are as follows:

code 1... error processing synth.ini file
code 2 ... error opening device port
code 3 ... error forking child process
code 4 error executing user shell

   If you don't hear a beep when you try the alt-o key sequence  , then you
should hear a message announcing "review mode".
svlpro may be operating but recieving no text to speak.   This could indicate
a problem with communication between the terminal and svlpro.
   Try pressing the arrow keys on the numeric keypad to navigate around the
screen and see if any of the onscreen text gets spoken.
   Blank lines will be announced as blank, characters will be spoken or spaces
announced, the home key will move you to the top left corner of the screen,
and the end key will move you to the beginning of the last line.
  The page up and page down keys read from the top of the screen to the cursor
and from the cursor to the end of the screen respectively.

   If svlpro speaks any text from the screen buffer then it is definitely a
problem with communication with your terminal.

   Test this as follows:
1. press the alt-o key combination again and you should hear the synth
announce "command mode to indicate that input will go to the terminal.
2. clear your screen by typing "clear"
3. do a directory listing of /etc, this should fill your screen with the listin
g
and give you plenty to examine from review mode.
4. press the alt-o combination to enter review  mode, svlpro should announce
this.
5. use the keypad to move around reading by line and letter and homing to the
top of the screen and to the bottom line  until your sure you are reading the
listing from the /etc directory.
   If your screen doesnt appear to have changed, and you don't see the listing
from /etc then either the terminal is not recieving your input, or your
/dev/vcs0 and vcsa0 files may not exist or be restricted.
   If the vcs files exist and permissions are set correctly then it may be
that svlpro is malfunctioning in its reading of the terminal.
   Please report this bug to me immediately and I will try to solve the problem
.

   If you get no speech output at all then  try entering review mode and increa
s
the volume with the following command:

/volume value

   Svlpro should announce "volume value" as the
volume increases or decreases.

   If you still have no speech output and your terminal doesnt beep when you
hit the alt-o key combination, then your terminal may not be operating properly
.
   If the terminal beeps then something has blocked the terminal from
communicating with svlpro and  you should contact me with the type of synth,
the port it's attached to  and an explanation of the problem.

   If svlpro should fail and dump core then that is an indication that the
compilation may be incompatible for your system and you should contact me with
your specs to see if i can compile a binary package that will work on your syst
em.
   It may also mean that your missing a variable in your synth.ini file so
check to ensure that the format is correct and if necessary remove all
unnecessary variables that may be overrunning the storage buffers when svlpro
starts.
   If this happens, and you reduce the number of loading variables and it allow
s
svlpro to succeed then I would need to adjust the buffers in the binary to
allocate enuff memory for increased use.

   If any other errors occur please let me know and I will try to respond quick
ly
and get the program going for you.

   If svlpro starts and speaks for you then you can move onto the next section
and begin using your linux/svlpro terminal     .
   If you successfully run svlpro and modify the synth.ini file adding more
control variables for a particular synth then I would appreciate a copy so
I can update the init files distributed with the package.

   Command mode
[6. command mode]

   The following keys are in effect when svlpro starts and while performing
normal linux shell activity:

alt-O ... toggles review/command modes
        While in command mode all text is sent to the terminal for processing
except where noted otherwise.   While in review mode
terminal input is blocked and  synthesizer controls may be set , the screen may
be reviewed until the ennter key is pressed or the alt-o sequence is pressed
again.

alt-/ ... toggles auto review mode
   When auto review is activated the normal screen review keys on the numeric
keypad are enabled and the screen can be reviewed  without having to enter
review mode with the alt-o sequence.
   Auto review mode remains in effect as long as the keys pressed are screen
review keys on the numeric keypad.

   When auto review mode is active, the following keys apply:

keypad key ...... function
home ... moves review cursor to top left corner of the screen, speaks top line.
.
end... moves the review cursor to the bottom left corner of the screen, speaks
bottom line.
up arrow... moves review cursor up one line, speaks that line.
down arrow ... moves review cursor down one line speaks that line.
left arrow... moves review cursor left one character, speaks that character.
right arrow ... moves review cursor right one character, speaks that character.
center key ... speaks current character.
page-up key... speaks from top of screen to review mode cursor.
page-down key ... speaks from review mode cursor to bottom of screen.
holding down the control key with the left or right arrow key will read bword
  by word rather than letter by letter.

   Pressing and holding the ctrl key while the synth is speaking serves to
silence speech immediately.

   Note the pressing the caps lock,num lock and scroll lock keys will now emit
distinct tones to indicate whether a keyboard led is turned on or off.
   two tones in sucession will indicate the flag being turned on, and a single
lower tone will indicate the flag being turned off.

   Review mode
[7. review mode]

   All review  key sequences that operate in command   or auto review mode
operate in review mode.

enter key ... exits review mode

spacebar ... announces review cursor coordinates.

Additionally, the following commands serve to alter svlpro's or your synth's
behavior.

***  note: some commands are not fully implemented, but may be planned for futu
re improvements.

/rate [value] ... sets synthesizer rate to [value].
/volume [value] ... sets synthesizer volume to [value].
/pitch [value] ... sets synthesizer pitch to [value]..

***note: most synthesizer variables can be set as in the above three examples.
  whereas the command corresponds to the label of the sequence in the individua
l
.ini file.  preceded by a slash.

/help [command] .... gives help for svlpro , or hgives help for [command].

/load [filename/configuration] ... loads a pre-existing configuration file or
synthesizer configuration, (not implemented).

/save [filename] ... saves the current configuration to [filename] for future r
etrieval.
( not implemented).

/bind [key] [args] ... sets key bindings for svlpro (not implemented).

/alias [aliasname] [args] ... displays, defines, or alters user defined alias c
ommands. (not implemented).

/set [variable] [value] ... sets, or displays svlpro specific variables, (parti
ally implemented).


   Future of svlpro
[8. future features]

   All improvements, changes and additions to the svlpro program will be
announced on the blinux mailing list
blinux-list@redhat.com

and on the svlpro home page at
home.eznet.net/~nukes/svlpro/svl.html

   As of this release I set the version number at 3.4.

   All inquiries about svlpro should be directed to me at
nukes@eznet.net
with subject line containing the word svlpro.

   As of this writing i have many ideas to incorporate into the program but I
welcome suggestions and bug reports and am grateful to all who help me to
advance this project.

end of README file for svlpro by Brett Barback
