************************************************************************* * WreadFiles Program Documentation * * * * Version 4.2 M.L. Barlow April 1992 * ************************************************************************* INTRODUCTION. What it Does: WreadFiles is a vocal text file reader program for use on the Commodore Amiga. The text is both printed to the screen and spoken. The basic features are summarized as follows: o Text is read in sentences rather than lines. o Dynamic Speech Correction on over 3000 word or word fragments. o Reading Rate: 700 bytes/minute (A1000, CPU 68000). o Reading Rate: 980 bytes/minute (A3000, CPU 68030). o Corrected Pronunciation of many place and personal names. o Corrected Pronunciation of some foreign names and expressions. o Corrected Pronunciation of many abbreviations containing vowels. o Expansion of many capitalized abbreviations. o Standard pronunciation of many multi-digit numbers. o ANSI color codes stripped from text displayed or spoken. o Ignores repeated characters. o Different voices for user interface and reading. < Alternate voice for text delineated by brackets. -> These brackets are often used to identify quoted text. <- << Three basic types are supported. Single or double brackets >> > may be forward or reverse, left side only or left and right. < o Single file or indexed multi-file read modes. o Run from Workbench or CLI. o Used with A1000 (OS 1.3) and A3000 (OS 2.04) ---------------------------------------------------------------------- COPYRIGHT The Author RESERVES the option to copyright this program. By the provisions of the Hague Copyright Convention, to which the U.S. has recently become a signatory, I am reserving the option to copyright this program. Any reproduction of WreadFiles, in whole or in part, without my permission is a potential copyright violation. Permission is granted for telecommunication services to distribute this program if distributed unmodified and intact with this documentation and if no special charges beyond the normal service rates are made. This program may also be included on public domain software disks if distributed on a non-profit basis under the same conditions as above. I am not requesting payment from any person receiving this program under the conditions above. If you were charged for this program, version 4.2, beyond the limits set forth above then you may have been defrauded. Anyone distributing modified or incomplete versions of this program or documentation may be fully liable for any consequence of such action. I have not yet formally copyrighted WreadFiles as it is my judgement that this program is not of "commercial" quality in its current state and that there is not a commercially viable market for a program of this type. ..... Of course I may be wrong. ---------------------------------------------------------------------- PREREQUISITES WreadFiles uses the USA versions of Amiga translator.library and narrator.device to generate speech. I do not know if these files differ for Amigas sold in other countries. However, WreadFiles is "tuned" to the performance of the files I have. WreadFiles will not run if you have removed the translator.library or the narrator.device from your Workbench disk. Fonts: WreadFiles will attempt to load either the clean 8 font, the pearl 8 font, or the topaz 8 font in that order. If the first font found is one you have replaced with a larger or smaller font, then WreadFiles may not function properly. Versions of the clean.font or pearl.font which have the control characters defined are recommended (in the event the file you try to read has control characters in it). ---------------------------------------------------------------------- INSTALLATION There are no special configuration or setup files required for this program. It may be installed on a floppy or hard disk. For the OS 1.3 or earlier operating systems, I find it most convenient to install WreadFiles on the root directory of the hard disk so that its icon is directly available. With OS 2.0x the "leave out" option in the Workbench Icons menu will accomplish the same function if the program and its icon are in a subdirectory. There should be no reason to change your Startup-Sequence for this program. You may wish to add a shorthand alias, for CLI use, to your Shell-Startup such as: alias Wread run >NIL: sys:system/WreadFiles [] if Wreadfiles were in your sys:system directory. This is not required and I do not recommend that you do this if you have any doubts about this process. You may rename your copy of the program if you wish. ---------------------------------------------------------------------- OPERATING MODES WreadFiles has two basic operating modes: single file mode and index file mode. In single file mode WreadFiles is given the name of a single file to read. This is the default mode of the program and no special action is required to invoke it. In index file mode WreadFiles is given the name of a text file which contains a list of files to read. The index may contain as many as 300 files which will be read automatically in the sequence listed. You invoke the index file mode by typing an @ character before entering the file name in the program's requestor or on the CLI line. If a file name starts with an @ character, place a single quote (') ahead of the name to enable reading it as a single file. Index file ICONS are identified by a MODE=filelist tool type entry. ---------------------------------------------------------------------- RUNNING THE PROGRAM There are four basic methods of starting WreadFiles. Mode 2 below is the best method for general use with Workbench, especially with OS 2.0x. In each case WreadFiles will start using the command color palette and using the control voice (Andy). As soon as the file to read is loaded, the screen will switch to the text color palette and the voice will switch to the reading voice (Tex). There may be a slight cough or pop at the very beginning as WreadFiles clears its throat (initializes the narrator). A. Method 1: Directly From its Workbench Icon. Running WreadFiles from its Workbench icon is the most direct way to start WreadFiles. However, you must know the full CLI name of the file you wish to read as there is no internal file selector. The program will say "hello there" and ask for a file name. Enter the file name in the text gadget presented. If the file is an index file (you must know this) then place an @ character ahead of the file name. If the program cannot access the file name entered then the program will apologize and exit with a red screen abort. Also, if you push enter without entering a file name, WreadFiles will assume that you wish to abort. The following are sample entries: |-----------------------| | ram:wread.doc | single file name: ram:wread.doc |=======================| | @ram:File_list | index file name: ram:File_list |=======================| | '@oddname | single file name: @oddname |=======================| | @@oddlist | index file name: @oddlist |-----------------------| B. Method 2: Using Extended (shift) Icon Select Extended Select is the easiest method of selecting the file to be read from Workbench. For best operation, the WreadFiles icon and the icon for the target file to be read should both be visible. The icon for the target file may be an OS 2.x pseudo-icon displayed with the "view all files" window option set. The procedure is as follows: First: Single click on the WreadFiles icon. A face should appear on the icon. Second: Push and hold either shift key down and then: double click on the icon for the target file to be read. The program will say "hello there" and acknowledge the selection of the file before reading it. *********************************************************************** * * * NOTE: This file, Wread.doc, has been created with a standard * * sys:utilities/more project icon. You may use the method above to * * have WreadFiles read this file for you. Read the Caveats and * * Warnings first! * * * *********************************************************************** C. Method 3: WreadFiles Project Icon Select. If the file has a true WreadFiles Project icon, then it is only necessary to double click that icon to start WreadFiles. This method requires that WreadFiles be located on a fixed directory path in your system so that the default tool entry is always valid. The following is an example of such an entry: ======================== Default Tool: |sys:system/WreadFiles | ======================== D. Method 4: From the CLI. Finally, you may start WreadFiles from the CLI just like any other CLI function. If you just type: 1> directory_name/WreadFiles then WreadFiles will start up the same as in method (1) above. You may also provide the name of the target file to be read on the CLI command line in lieu of entering it in the program. An example of this might be the line: 1> ram:WreadFiles ram:Wread.doc An example of calling an index file, df0:Wread.list, is: 1> dh0:WreadFiles @df0:Wread.list WreadFiles can be used by a CLI batch file with commands like those above. ---------------------------------------------------------------------- USING THE PROGRAM: MENU OPTIONS When a menu option is selected, the screen will change to command colors and the control voice will announce the selection. WreadFiles cannot respond to commands while it is reading a sentence. Thus the program's response to a menu selection will be delayed until after it has finished reading the current sentence. WreadFiles does limit the length of any sentence to one screen of text to prevent intolerable delays. Command delay is not a problem with normal text. A. Project Menu 1. Start Over [Pick File]: Right-Amiga P Selecting this option in single file mode will restart reading from the beginning. In index file mode this is the Pick File option. Pick File presents a menu of the files on the index for selecting the next file to read. 2. Skip this File: Right-Amiga S Selecting this option in single file mode is the same as selecting Exit/Quit. In index file mode this option aborts reading the current file and goes on to the next file or exits the program if the last file was being read. 3. Exit/Quit: Right-Amiga Q Ends the program. The program will acknowledge that you have opted to exit and say good-bye. B. Options Menu 1. Speech Correction: Right-Amiga C Toggles Correction on and off. When speech correction is off, the default translator is restored. Only sentence processing is done by the program when speech correction is off. The control voice will announce whether speech correction is being enabled or disabled. 2. Pick Reading Rate: Right-Amiga R Allows you to pick the reading rate. For fast processors the default reading rate is 210 words per minute. For slower Amigas, such as the A1000, the default rate is set at 250 words per minute to compensate for the longer processing time required. C. Icon Menu The Icon Menu is only available if the target file to be read has been selected by name (startup methods 1 or 4 above). Notes: 1. Do not have two disks with the SAME volume name in your system when you use these options. 2. These icon create/modify options are the only functions of this program which will write to your disk. If you have any concern about the compatibility of WreadFiles with your system, I recommend that you avoid creating or modifying icons while multitasking or using disks containing valuable non-replaceable data. The only problem I have had with the current versions of these functions has been icons ending up on the wrong disk when disks with duplicate volume names (Capts:) were in the system. 1. Make New Icon Creates a new project icon with WreadFiles as the default tool. If the file is an index file then the MODE=filelist tool type will be added. Otherwise a default MODE=singlefile tool type will be used. 2. Modify Old Icon Attempts to modify the default tool and tool types entry of the existing icon of the file or index file selected at startup without changing its image. If no existing icon is found for that file, then a new icon will be made. D. [Copyright] "Menu" This is not a menu but a notice: |===========================| | The Author RESERVES the | | option to copyright | | this program. | | | | M.L. Barlow | | Silverdale, WA, USA | |===========================| ---------------------------------------------------------------------- USING THE PROGRAM: KEYBOARD OPTIONS A. Menu Hot Keys. The following are menu hot keys; see above for a description of the menu functions. 1. Right-Amiga P ... Start Over [Pick File] 2. Right-Amiga S ... Skip this File 3. Right-Amiga Q ... Exit/Quit 4. Right-Amiga C ... Speech Correction(on/off) 5. Right-Amiga R ... Pick Reading Rate B. Keyboard Pause Striking any active key, other than those specified above, will pause the program. The screen color will change to command colors and the control voice will announce that the program is paused. WreadFiles will remain paused until another key is struck. The normal menu is removed while the program is paused. ---------------------------------------------------------------------- MULTITASKING WreadFiles does multitask, even with itself. As this is being written there are 12 copies of the program running on my A3000. A mad jumble of spoken text is being produced as each copy takes its turn speaking a sentence. This is being done to test the stability of the program. Since the speech correction routine is continuously allocating and de-allocating small chunks of memory, any problem with this routine could result in these programs stepping on each other. While the program appears to be passing this test, it is not exhaustive. The user is cautioned that no matter how much testing I do, there is no guarantee that multitasking WreadFiles will be safe on his or her system. The CPU is under intensive use while this program is talking. This is a serious limitation to effectively multitasking this program on 68000 based systems. WARNING! I have noticed that some programs, such as AmigaBasic, may fail [GURU] if they start using the audio hardware while another program is using the narrator. ---------------------------------------------------------------------- FILE COMPATIBILITY WreadFiles works best with single column ASCII text files having a maximum length of 80 characters. These files are printed to the screen in their original format. The program recognizes ^J (CONTROL J which is ASCII code 10), ^M, or sequential ^M^J or ^J^M as end of line (EOL)indicators. WreadFiles will strip out many standard ANSI escape sequences, such as those used for color formatting (^[[33;41m). The program ignores these codes, since color is used by the program to show where active reading is taking place. (Lines containing sentences which have been read are black and the unread lines are blue.) If the text lines in the file are longer than 80 characters then the program will reformat the lines to fit on the screen. This also applies to files which only have end of line indicators at the ends of paragraphs. Files containing tables of numbers or mathematical formulas are not recommended for use with WreadFiles. The program works best with narrative text. If you attempt to read a specially formatted, word processor file (or any binary file) the result will usually be gibberish. Some word processors which use near ASCII format (Scribble!) may be partially readable. ---------------------------------------------------------------------- SHORT COLUMN FILES Since unusually short text lines (like the line above) are one of the criteria that WreadFiles uses to identify sentence ends, files with narrow column text will not be properly processed. The reading of files known to be of 60 or 40 column type can be improved by adding nominal column width identifiers {60} or {40} respectively after the file name. The curly brackets are required. At least one space must precede the first bracket. See the section on index files for an example. WreadFiles project icons may also contain a column code with a tool type of the form: MODE=singlefile,40 This type of entry is not relevant for index file icons because that information is contained in the file. ---------------------------------------------------------------------- INDEX FILES Index files are ASCII text files where each line contains a file description in the first 41 characters of the line and a file name which begins at the 42nd character. The file description is what the user will see if he uses the Pick File option. The file name is what WreadFiles uses to access the file. If any file cannot be accessed by the name provided then the program will "good-bye" with a red screen abort. For best results, use the volume name rather than device name to identify the root directory of each file. The entry can also contain the narrow column format indicators. An example of a typical entry line is as follows: SuperWord from GnSoft by Ron Jennings UG_Disk:Reviews/SuperWord {60} In this example the file name is followed by a column width code. The entries should be sequential with no blank lines. The last text line should end with a carriage return. Lines will be ignored which reference the same file name as that of the preceding line. ---------------------------------------------------------------------- HOW IT WORKS: The text is spoken one sentence at a time to achieve a natural speech rhythm. WreadFiles uses standard punctuation marks and other criteria to determine where the sentence breaks are. Each sentence is scanned for over 3000 word or word fragments which are mispronounced by the Amiga translator or are associated with mispronounced words. These words (or word fragments) are replaced dynamically on the fly with text which will be more correctly pronounced. The target text may be replaced unconditionally whenever found, or only if qualified by the adjacent text. In a few cases where two common words are spelled the same, (homographs) WreadFiles will attempt to determine the correct pronunciation by examining the adjacent words. Most of the text replacements are not case sensitive. Case sensitive changes are primarily for standard capitalized abbreviations. These abbreviations may be spoken as letters (AFL => ay.f.l) or expanded to their original form (BTW => buy the way,). The program processes many standard abbreviations and BBS abbreviations. This reduces the amount of time it is necessary to look at the screen to see what was said. Common state two letter designations (WA) are expanded unless they are easily confused with common words (HI). Many common abbreviations such as those for months of the year and days of the week are also expanded on a non case sensitive basis. Occasionally these expansions are inappropriate; such as when the AZ text editor is rendered as the "Arizona" text editor. Multi-digit numbers are also replaced by text to sound more natural. WreadFiles is usually able to convert The dollar sign preceding a number to the appropriate text following the number. A limited attempt is also made to determine if the dollar sign is a hexadecimal number indicator. WreadFiles attempts to identify and remove cosmetic text patterns from what is spoken so that the listener does not have to hear such things as the word "asterisk" repeated 76 times. The program cannot protect the listener from general ASCII art, but it will remove some combinations of slashes, spaces and backslashes which are abnormal for spoken text. Most speech correction changes are made by modifying the text given to the translator. There are also changes made to the translator output. For some words there was no way to force the translator to produce the correct phonetic translation. For these cases, the abnormal consonant cluster zv was selected to serve as a marker for changes to be made to the translator output (e.g. breezvth, ayzvsheya, pzvissihfihk, etc.) Some translator output vowel codes are also changed in cases where they did not sound right when combined with specific consonants. ---------------------------------------------------------------------- POTENTIAL APPLICATIONS The following are potential applications of this program: A. Reading ASCII Text Files. WreadFiles may be used to read standard ASCII text files. In this application using WreadFiles is similar to typing a file to SPEAK: except that WreadFiles also displays the text being read and provides extensive preprocessing of the text to remove most of the words mispronounced by the translator.library (on a frequency of use basis). B. Talking Story Disk WreadFiles could be used for a non-commercial talking story disk. The index file mode would be best for that type of application. The 212 kbyte size of this file, mostly due to the embedded speech correction data, will limit the text on a nominal 880 kbyte disk to about 550 kbytes. This amount of material would take about 9 hours and 20 minutes to read on an A3000 (or other 68030 based Amiga) or a little over 13 hours on a non-accelerated A1000, A500, or A2000. C. Aid For Visually Impaired While WreadFiles has not been specifically written for this application, I have made the menu selection boxes large so that someone with minor visual impairment might make them out. Perhaps WreadFiles combined with another utility would be beneficial for people with more severe visual impediments. WreadFiles does allow other programs to obtain access to the translator, narrator, and audio.device between each sentence break. ---------------------------------------------------------------------- DEFICIENCIES My primary emphasis on WreadFiles has been the speech correction. There remain several areas where this program should be improved. Correcting all these deficiencies could cause the code size to grow another 50 - 100 kbytes. A. No User Scrolling. No user scrolling capability is provided. Adding this feature would not be simple because the input text buffer is modified as it is read. This minimizes buffer preprocessing delays. It is possible to scroll through the list of the files to be read in index mode, however this is not a substitute for being able to quickly scroll forward and backward through the file being read. B. No File Selector. I have not attempted to program a file selector which is standard on most Amiga programs. I may add the standard OS 2.x file requester in the future. C. Sentence Speaking Cannot Be Interrupted. This is normally not a problem. However, if you load a file which contains a long segment of text lacking the criteria which identify sentence breaks, then the program may not respond to your commands or attempts to stop the program for several minutes. D. No ARexx Port It is conceivable that an ARexx port could be useful for interactive multitasking. I have not yet considered what should be done in this regard. ---------------------------------------------------------------------- CAVEATS AND WARNINGS This is a program I wrote initially for my own use. No warranty is made on the accuracy of this documentation or the fitness of this software for any purpose. The speech correction routines in WreadFiles are tightly "tuned" to the existing USA, OS 1.3 and 2.04 versions of the translator.library and narrator.device. There is no guarantee that future improvements in the operating system software will not degrade or disrupt the operation of this program. No commitment is made to release any future versions of this program. I have only used WreadFiles on two computer systems: 1. Amiga A1000 with 512 kilobytes of chip and 2 megabytes of fast ram using Kickstart 1.2 with Workbench 1.3. The program did run after invoking NoFastMem, just after reboot, but I cannot guarantee operation with a 512K Amiga. 2. Amiga A3000/25 system with 10 megabytes total ram using OS 2.04 The only background programs I have had running are ConMan on the A1000 and GRABBIT on the A3000. This software has not been tested in other systems as commercial software is normally tested during the beta test stage. The user must assume FULL responsibility for backing up important files etc. should this program malfunction in his or her system or expose a weakness in other software while multitasking. You may find the steady drone of the Amiga voice produced by WreadFiles sleep inducing. :} I hope you find WreadFiles useful and that none of the dire possibilities mentioned above ever occurs. M.L. Barlow 12 Apr 1992 ---------------------------------------------------------------------- VERSION HISTORY Version 1: True Basic code. The program was inspired by an article by Earl McGhee in the March 1987 issue of Jump Disk. Version 2: True Basic main program, speech correction coded in C. Developed optimized high speed assembly language routines for the critical text search and replace functions. Version 3: Whole program coded in C. Added icon create/modify feature. Version 4: Speech correction sequence reorganized, added "Gang Buster" routines for words with common beginnings. Added number conversion. Version 4.1 Added modifications to optimize program for OS 2.04 on A3000. Version 4.2 Added feature to split words to be spoken which have embedded capital letters (TrueVision => True Vision). Reduced maximum spoken sentence length from 100 to 23 lines. Added compatibility with ^M, ^M^J and ^J^M EOLs. Discovered and fixed an obscure bug with the sentence processor - thanks to Dick Raymond who posted a message to GEnie with 54 empty lines in it. First public release. ---------------------------------------------------------------------- Wread.doc 28627 ----rwed 12-Apr-92 15:XX:XX Wread.doc.info 389 ----rw-d 19-Mar-92 20:27:25 WreadFiles 212304 ----rwed 12-Apr-92 11:57:42 WreadFiles.info 1318 ----rw-d 09-Apr-92 17:07:41 ----------------------------------------------------------------------