home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 1 / Mecomp-CD.iso / amiga / tools / wb / swread_040 / swread.doc < prev    next >
Text File  |  1997-06-16  |  42KB  |  961 lines
  1.  
  2.   * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  3.   *                                                                       *
  4.   *                        SWread Program Documentation                   *
  5.   *                                                                       *
  6.   *  Version 5.1                                 M.L. Barlow  June 1997  *
  7.   * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  8.  
  9.   INTRODUCTION. 
  10.  
  11.   What it Does:
  12.  
  13.     SWread is a simplified version of the WreadFiles vocal text reader
  14.   program for use on the Amiga.  The large internal USA English translation
  15.   enhancement library (about 250 Kbytes) has been removed.  The huge
  16.   !USA.accent provided with Translator43 restores most of the functionality
  17.   removed from WreadFiles51.  The basic features are summarized as follows:
  18.  
  19.   o    The text is both printed to the screen and spoken.
  20.  
  21.   o    Text is read in sentences rather than lines. 
  22.  
  23.   o    ANSI color codes stripped from text displayed or spoken. 
  24.  
  25.   o    Single file or indexed multi-file read modes. 
  26.  
  27.   o    Run from Workbench or CLI. 
  28.  
  29.   o    ASL file requester for input file selection for OS 2.04+.
  30.  
  31.   o    Alternate high-contrast color setup: white text on black background
  32.        in addition to the normal black text on lavender green.
  33.  
  34.   o    Standard Hard and Soft (default) voice options.
  35.  
  36.   o    Program icon tooltypes enable user pre-selection of reading
  37.        rate, color and full screen ASL file requester.
  38.  
  39.   o    Program and file icon tooltypes enable selection of accent
  40.        (language), Quote Processing, and default voice.
  41.  
  42.   o    Text Width Declaration:  Menu option allows user declaration of
  43.        the text width parameter for optimum sentence recognition.
  44.  
  45.   o    Vocal Annotation Options:  File and program tooltypes enable
  46.        partial or complete suppression of vocal annotation.
  47.  
  48.   o    Exit Option: a -r option suppresses the normal Workbench-to-front
  49.        action on program exit. 
  50.  
  51.   o    Silent Fast-Forward Function:  This enables skipping tiresome or
  52.       tedious text..
  53.  
  54.   o    File Position Indicator: A decade graduated reading position
  55.        indicator (and selector) is provided at the top of the screen.
  56.  
  57.   o    File Position Seek Function: The File Position Indicator may be used
  58.        to select (and re-select) the reading point.
  59.  
  60.   o    Different voices and languages for user interface and reading. 
  61.  
  62.  ***********      Optional Special Processing Mode Features   ***********
  63.  
  64.   o    Tonal representation of "Narrative Quoted text."* 
  65.  
  66.   o    Tonal representation of Internet/BBS reference quote levels.*
  67.  
  68.   o    Splits words with Embedded capitals (DogHouse->dog house)
  69.  
  70.   o    Repeated character suppression. 
  71.  
  72.   o    Minor case-sensitive English text fixes.
  73.  
  74.   ----------------------------------------------------------------------
  75.  
  76.                                 COPYRIGHT
  77.  
  78.   ----------------------------------------------------------------------
  79.  
  80.     The Author RESERVES the option to copyright this program.  By the
  81.   provisions of the Hague Copyright Convention, to which the U.S. has
  82.   become a signatory, I am reserving the option to copyright this
  83.   program.  Any reproduction of SWread, in whole or in part, without my
  84.   permission is a potential copyright violation. 
  85.  
  86.     Permission is granted for telecommunication services to distribute this
  87.   program if distributed unmodified and intact with this documentation and if
  88.   no special charges beyond the normal service rates are made.  This program
  89.   may also be included on public domain software disks if distributed on a
  90.   non-profit basis under the same conditions as above. 
  91.  
  92.     I am not requesting payment from any person receiving this program
  93.   under the conditions above.  If you were charged for any version of this
  94.   program beyond the limits set forth above then you may have been
  95.   defrauded.
  96.  
  97.     Anyone distributing modified or incomplete versions of this program or
  98.   documentation may be fully liable for any consequence of such action. 
  99.  
  100.   ----------------------------------------------------------------------
  101.  
  102.                               PREREQUISITES
  103.  
  104.   ----------------------------------------------------------------------
  105.  
  106.     SWread uses the USA versions of Amiga translator.library, or the
  107.   multilingual translator replacement libraries (Translator42 or
  108.   Translator43) and narrator.device provided with Commodore Amiga operating
  109.   systems 2.04 and earlier to generate speech.  Commodore and Escom did not
  110.   include these files with the newer operating systems.  SWread will not
  111.   run if you have a later version of the operating system lacking these
  112.   files or if you have removed the translator.library or the
  113.   narrator.device from your Workbench disk.
  114.  
  115.     Fonts: SWread will attempt to load either the clean 8 font, the
  116.   pearl 8 font, or the topaz 8 font in that order.  If the first font found
  117.   is one you have replaced with a larger or smaller font, then SWread
  118.   may not function properly.  Versions of the clean.font or pearl.font
  119.   which have the control characters defined are recommended (in the event
  120.   the file you try to read has control characters in it). 
  121.  
  122.   ----------------------------------------------------------------------
  123.  
  124.                                INSTALLATION
  125.  
  126.   ----------------------------------------------------------------------
  127.  
  128.      There are no extra configuration or setup files required for this
  129.   program.  All user configurable options are implemented as tooltypes of the
  130.   SWread.info icon. It may be installed on a floppy or hard disk.  For
  131.   the OS 1.3 or earlier operating systems, I find it most convenient to
  132.   install SWread on the root directory of the hard disk so that its icon
  133.   is directly available.  With OS 2.0x the "leave out" option in the
  134.   Workbench Icons menu will accomplish the same function if the program and
  135.   its icon are in a subdirectory.  There should be no reason to change your
  136.   Startup-Sequence for this program.  You may wish to add a shorthand alias,
  137.   for CLI use, to your Shell-Startup such as:
  138.  
  139. alias Wread run >NIL: sys:system/SWread []
  140.  
  141.   if SWread were in your sys:system directory.  This is not required
  142.   and I do not recommend that you do this if you have any doubts about this
  143.   process. 
  144.  
  145.     You may rename your copy of the program if you wish. 
  146.  
  147. ----------------------------------------------------------------------
  148.  
  149.                              OPERATING MODES
  150.  
  151.   ----------------------------------------------------------------------
  152.  
  153.     SWread has two basic operating modes: single file mode and index file
  154.   mode.  In single file mode SWread is given the name of a single file to
  155.   read.  This is the default mode of the program and no special action is
  156.   required to invoke it.
  157.  
  158.     In index file mode SWread is given the name of a text file which
  159.   contains a list of files to read.  The index may contain as many as 300
  160.   files which will be read automatically in the sequence listed.  You invoke
  161.   the index file mode by typing an @ character before entering the file
  162.   name in the program's requester or on the CLI line.  If a file name starts
  163.   with an @ character, place a single quote (') ahead of the name to enable
  164.   reading it as a single file.
  165.  
  166.    Index file ICONS are identified by a MODE=filelist tool type entry. 
  167.  
  168.   ----------------------------------------------------------------------
  169.  
  170.                            STARTING THE PROGRAM
  171.  
  172.  ----------------------------------------------------------------------
  173.  
  174.     There are four basic methods of starting SWread.  Mode 2 below is
  175.   the best method for general use with Workbench, especially with OS 2.0x. 
  176.  
  177.     In each case SWread will start using the command color palette and
  178.   using the control voice (Andy).  As soon as the file to read is loaded,
  179.   the screen will switch to the text color palette and the voice will
  180.   switch to the reading voice (Tex).  There may be a slight cough or pop
  181.   at the very beginning as SWread clears its throat (initializes the
  182.   narrator). 
  183.  
  184.   A. Method 1: Directly From its Workbench Icon. 
  185.  
  186.     Running SWread from its Workbench icon is the most direct way to  
  187.   start SWread.  For versions 4.2 and below, you must know the full CLI
  188.   name of the file you wish to read as there is no internal file selector. 
  189.   The program will say "hello there" and ask for a file name.
  190.  
  191.     A standard ASL file requester will appear if you are using OS 2.04 or
  192.   greater.  That requester will provide a filtered list of the files
  193.   available (#?.info, #?.o, #?.lzh and #?.lha files are not listed) This will
  194.   allow you to search for the file you wish to hear.
  195.  
  196.     Enter the file name in the text gadget presented.  If the file is an
  197.   index file (you must know this) then place an @ character ahead of the file
  198.   name.  If the program cannot access the file name entered then the program
  199.   will apologize and exit with a red screen abort.  Also, if you push enter
  200.   without entering or selecting a filename, SWread will assume that you
  201.   wish to abort(quit).  This is also what happens if you select the "Abort"
  202.   gadget on the ASL requester.
  203.  
  204.   The following are sample non-ASL entries:
  205.  
  206.     |-----------------------|
  207.     | ram:SWread.doc        |      single file name: ram:SWread.doc
  208.     |=======================|
  209.     | @ram:File_list        |      index file name:  ram:File_list
  210.     |=======================|
  211.     | '@oddname             |      single file name: @oddname
  212.     |=======================|
  213.     | @@oddlist             |      index file name:  @oddlist
  214.     |-----------------------|
  215.  
  216.   To select an index file with the ASL requester, you must insert an '@'
  217.   symbol ahead of the selected file name in the bottom text box.
  218.  
  219.   B. Method 2: Using Extended (shift) Icon Select
  220.  
  221.     Extended Select is the easiest method of selecting the file to be read
  222.   from Workbench.  For best operation, the SWread icon and the icon for
  223.   the target file to be read should both be visible.  The icon for the target
  224.   file may be an OS 2.x pseudo-icon displayed with the "view all files"
  225.   window option set.  The procedure is as follows:
  226.  
  227.   First: Single click on the SWread icon.  A face should appear on the
  228.          icon. 
  229.  
  230.   Second: Push and hold either shift key down and then: double click on the
  231.           icon for the target file to be read. 
  232.  
  233.   The program will say "hello there" and acknowledge the selection of the
  234.   file before reading it. 
  235.  
  236.     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  237.     *                                                                     *
  238.     *  NOTE:  This file, SWread.doc, has been created with a standard     *
  239.     *  sys:utilities/more project icon.  You may use the method above to  *
  240.     *  have SWread read this file for you.  Read the Caveats and          *
  241.     *  Warnings first!                                                    *
  242.     *                                                                     *
  243.     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  244.  
  245.   C. Method 3: SWread Project Icon Select. 
  246.  
  247.     If the file has a true SWread Project icon, then it is only necessary
  248.   to double click that icon to start SWread.  This method requires that
  249.   SWread be located on a fixed directory path in your system so that the
  250.   default tool entry is always valid.  The following is an example of such
  251.   an entry:
  252.                   ========================
  253.    Default Tool:  |sys:system/SWread      |
  254.                   ========================
  255.  
  256.    D. Method 4: From the CLI. 
  257.  
  258.      Finally, you may start SWread from the CLI just like any other CLI
  259.   function.  If you just type:
  260.  
  261. 1> directory_name/SWread
  262.  
  263.   then SWread will start up the same as in method (1) above.  You may
  264.   also provide the name of the target file to be read on the CLI command line
  265.   in lieu of entering it in the program.  An example of this might be the
  266.   line:
  267.  
  268. 1> ram:SWread ram:Wread.doc
  269.  
  270.   An example of calling an index file, df0:Wread.list, is:
  271.  
  272. 1> dh0:SWread @df0:Wread.list
  273.  
  274.     SWread can be used by a CLI batch file with commands like
  275.   those above. 
  276.  
  277.     CLI OPTIONS
  278.  
  279.     SWread version 5.1 will accept a cluster of options preceded by a
  280.   single dash following the program name. Currently supported options are as
  281.   follows:
  282.  
  283.   -q  no greetings and minimal vocal annotation;
  284.   -a  no greetings or normal vocal annotations;
  285.   -r  no automatic Workbench screen to front on exit.
  286.  
  287.     An example of usage in an ARexx script line called by another program
  288.   would be:
  289.  
  290.   ADDRESS COMMAND 'Work:Wread/SWread -qr ram:tempfile.txt'
  291.  
  292.     In this case the use of the -r option would prevent the disruption of
  293.   the pre-existing screen arrangement.
  294.  
  295.   ----------------------------------------------------------------------
  296.  
  297.                      USING THE PROGRAM: MENU OPTIONS
  298.  
  299.   ----------------------------------------------------------------------
  300.  
  301.     When a menu option is selected, the screen will change to command
  302.   colors and the control voice will announce the selection. 
  303.  
  304.     SWread cannot respond to commands while it is reading a sentence. 
  305.   Thus the program's response to a menu selection will be delayed until
  306.   after it has finished reading the current sentence.  SWread does
  307.   limit the length of any sentence to one screen of text to prevent
  308.   intolerable delays.  Command delay is not a problem with normal text. 
  309.  
  310.   A. Project Menu
  311.  
  312.      1. Start Over [Pick File]: Right-Amiga P
  313.  
  314.         Selecting this option in single file mode will restart reading from
  315.      the beginning.  In index file mode this is the Pick File option. 
  316.      Pick File presents a menu of the files on the index for selecting the
  317.      next file to read. 
  318.  
  319.      2. Silent Fast-Forward: Right-Amiga F
  320.  
  321.         When this option is selected, the program toggles in or out of the
  322.      silent fast forward mode.  The program in this mode prints text to
  323.      the screen without pausing to speak.  You may also toggle this mode
  324.      on and off by Alt-Left-mouse clicking (clicking the left mouse button
  325.      with the ALT key held down) on the File Position Indicator.  Normal
  326.      vocal reading will resume after selecting pause or if the mouse is
  327.      clicked on the lower part of the screen.  The silent reading speed
  328.      is reduced if the mouse pointer is brought down from the top of the
  329.      screen.  If the end of the file is encountered in this mode, normal
  330.      vocal reading is restarted at the beginning of the file.
  331.  
  332.  
  333.      3. Skip this File: Right-Amiga S
  334.  
  335.         Selecting this option in single file mode is the same as selecting
  336.      Exit/Quit.  In index file mode this option aborts reading the
  337.      current file and goes on to the next file or exits the program if the
  338.      last file was being read. 
  339.  
  340.      4. Exit/Quit: Right-Amiga Q
  341.  
  342.         Ends the program.  The program will acknowledge that you have opted
  343.       to exit and say good-bye. 
  344.  
  345.   B. Options Menu
  346.  
  347.      1. Special Processing:  Right-Amiga C
  348.  
  349.         Toggles special processing on and off.  When special processing
  350.      is enabled, the following features are normally enabled:
  351.  
  352.         (a.)  Tone-shift indication of "quoted text."
  353.  
  354.         (b.)  Tone-shift indication of the BBS quote level
  355.  
  356.         (c.)  Repetitive text patterns are detected and ignored.
  357.  
  358.         (d.)  Words with embedded capitals (TestEngine) are split apart.
  359.  
  360.         (e.)  Recognition of some in-line symbolic letters (\/\/,/\/\).
  361.  
  362.         (f.)  International accented letters converted to simple Roman.
  363.  
  364.         (g.)  A few English, case sensitive [of Job -> of joab] word
  365.               fixes.
  366.  
  367.      2. Pick Reading Rate: Right-Amiga R
  368.  
  369.         Allows you to pick the reading rate.  For fast processors the
  370.      default reading rate is 210 words per minute.  For slower Amigas, such
  371.      as the A1000, the default rate is set at 250 words per minute to
  372.      compensate for the longer processing time required. 
  373.  
  374.  
  375.      3, Declare Text Width;  Submenu  40: Right-Amiga 4
  376.  
  377.                              Submenu  60: Right-Amiga 6
  378.  
  379.                              Submenu  80: Right-Amiga 8
  380.  
  381.         Permits user declaration of a text width parameter for the current
  382.      file.  This parameter is used in the determination of unusually short
  383.      text lines.  A short line is one of the criteria used to detect
  384.      sentence ends.  The user may select 40, 60, or 80 characters depending
  385.      on which best describes the current file.
  386.  
  387.        This parameter will be saved as set with any file icon created as
  388.      described below.
  389.  
  390.  
  391.      4. Next Display Palette: Right-Amiga D
  392.  
  393.         Switch from normal palette (black text on lavender background) to
  394.      the high contrast palette (white text on black) or vice versa.  The
  395.      high contrast palette has been added at the request of a user for
  396.      better visibility. 
  397.  
  398.  
  399.      5. Change Voice.
  400.  
  401.         SWread5.1 (and WreadFiles5.1 [unreleased]) feature 2 optional
  402.   voices when used with Narrator37.7.  The "Hard" voice is the standard
  403.   flat response settings used with earlier versions of WreadFiles.  The
  404.   new "Soft" voice features maximum low frequency boost and high frequency
  405.   cut to minimize "telephone" voice sound effect.  This menu option
  406.   toggles between the two voices.
  407.  
  408.  
  409.   C. Icon Menu
  410.  
  411.        The Icon Menu is only available if the target file to be read has been
  412.      selected by name (start-up methods 1 or 4 above). 
  413.  
  414.      Notes:
  415.  
  416.      1.  Do not have two disks with the SAME volume name in your system
  417.      when you use these options. 
  418.  
  419.      2. These icon create/modify options are the only functions of this
  420.      program which will write to your disk.  If you have any concern about
  421.      the compatibility of SWread with your system, I recommend that you
  422.      avoid creating or modifying icons while multitasking or using disks
  423.      containing valuable non-replaceable data.  The only problem I have had
  424.      with the current versions of these functions has been icons ending up
  425.      on the wrong disk when disks with duplicate volume names were in the
  426.      system. 
  427.  
  428.      1. Make New Icon
  429.  
  430.         Creates a new project icon with SWread as the default tool.  If
  431.      the file is an index file then the MODE=filelist tool type will be
  432.      added.  Otherwise a default MODE=singlefile tool type will be used. 
  433.  
  434.      2. Modify Old Icon
  435.  
  436.         Attempts to modify the default tool and tool types entry of the
  437.      existing icon of the file or index file selected at start-up without
  438.      changing its image.  If no existing icon is found for that file, then a
  439.      new icon will be made. 
  440.  
  441.   D. [Copyright]  "Menu"
  442.  
  443.        This is not a menu but a notice:
  444.  
  445.                        |===========================|
  446.                        |  The Author RESERVES the  |
  447.                        |  option to copyright      |
  448.                        |  this program.            |
  449.                        |                           |
  450.                        |       M.L. Barlow         |
  451.                        |    Silverdale, WA, USA    |
  452.                        |===========================|
  453.  
  454.  
  455.  
  456.   ----------------------------------------------------------------------
  457.  
  458.            USING THE PROGRAM: FILE POSITION INDICATOR FUNCTIONS
  459.  
  460.   ----------------------------------------------------------------------
  461.  
  462. TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTTT|TTT
  463. _________|_________|_________|_________|_________|_________|_________|_______ 
  464.                                        '
  465.  
  466.                         The File Position Indicator 
  467.  
  468.     The File Position Indicator is a decade graduated indicator bar at the
  469.   top of the screen.  This bar functions as an indicator and pseudo gadget
  470.   for fast file navigation.  The indicator shows the current reading
  471.   position as a percentage of the total file being read.  The indicator is
  472.   graduated in 1 percent increments with a resolution of about 1/6th of a
  473.   percent and is updated for each line of text processed.
  474.  
  475.                         File Reading Position Select
  476.  
  477.       The File Position Seek is invoked by Shift-Left-mouse clicking
  478.     (clicking the LEFT mouse button with a SHIFT key held down) at the
  479.     desired target reading position on the File Position Indicator gadget.
  480.     The program sets the file pointer just ahead of your target point and
  481.     pre-reads the file up to the target point.  During the pre-reading
  482.     interval, only the file position indicator is updated.  This allows
  483.     reading to resume at the target point on a complete sentence.
  484.  
  485.  
  486.   ----------------------------------------------------------------------
  487.  
  488.                    USING THE PROGRAM: KEYBOARD OPTIONS
  489.  
  490.   ----------------------------------------------------------------------
  491.  
  492.   A. Menu Hot Keys. 
  493.  
  494.     The following are menu hot keys; see above for a description of the
  495.   menu functions. 
  496.  
  497.      1. Right-Amiga P ... Start Over [Pick File from index]
  498.  
  499.      2. Right-Amiga F ... Toggle Silent Fast Forward mode in/out.
  500.  
  501.      3. Right-Amiga S ... Skip this File.
  502.  
  503.      4. Right-Amiga Q ... Exit/Quit.
  504.  
  505.      5. Right-Amiga C ... Special Processing (on/off).
  506.  
  507.      6. Right-Amiga R ... Pick Reading Rate.
  508.  
  509.     7a. Right-Amiga 4 ... Declare 40 column file.
  510.  
  511.     7b. Right-Amiga 6 ... Declare 60 column file.
  512.  
  513.     7c. Right-Amiga 8 ... Declare 80 column file (default).
  514.  
  515.      8. Right-Amiga D ... Next Display Palette (toggle).
  516.  
  517.      9. Right-Amiga V ... Change Voice.
  518.  
  519.   B. Keyboard Pause
  520.  
  521.      Striking any active key, other than those specified above, will pause
  522.   the program.  The screen color will change to command colors and the
  523.   control voice will announce that the program is paused.  SWread will
  524.   remain paused until another key is struck.  The normal menu is removed
  525.   while the program is paused. 
  526.  
  527.   ----------------------------------------------------------------------
  528.  
  529.               USING THE PROGRAM: WORKBENCH TOOL-TYPE OPTIONS
  530.  
  531.   ----------------------------------------------------------------------
  532.  
  533.     You may customize some features of this program by manually adding or
  534.   changing the tooltypes entries of the SWread program icon.  This is
  535.   accomplished by selecting the icon (single click) and using the Workbench
  536.   [Project] Info menu item on OS 1.3 or the [Icons] information menu item on
  537.   OS 2.x/3.x.  There are nine user selectable parameters available.  If the
  538.   program is started from the CLI, it will also search for its icon (e.g.
  539.   SWread.info) file and use the options found.  File-icon tool-type options
  540.   normally supercede the equivalent program-icon options.
  541.  
  542.   TOOL-TYPE OPTIONS SUMMARY
  543.  
  544.   A.  Mode (MODE=)  Select single or multifile wread mode:  (file only)
  545.  
  546.     1.  (MODE=filelist) multifile mode.
  547.     2.  (MODE=singlefile,40) single file, text width 40.
  548.     3.  (MODE=singlefile,60) single file, text width 60.
  549.     4.  (MODE=singlefile) single file, text width 80 (default).
  550.  
  551.   B.  Andyoff (ANDYOFF=) Vocal annotation suppression:
  552.  
  553.     1.  (ANDYOFF=all)  Maximum vocal annotation suppression (file only).
  554.     2.  (ANDYOFF=)     Partial vocal annotation suppression.
  555.     3   (ANDYOFF=none) Normal vocal annotation (default).
  556.  
  557.   C.  Voice (VOICE=) Select voice type:
  558.  
  559.     1.  (VOICE=soft) select soft voice (default).
  560.     2.  (VOICE=hard) select hard voice.
  561.  
  562.   D. Accent (ACCENT=) Select Accent:
  563.  
  564.     1.  (ACCENT=accent_name) Select accent_name.accent.
  565.     2.  (ACCENT=@accent_name) Select accent_name.accent with special
  566.                               processing.
  567.  
  568.     3.  (ACCENT=@!USA) Select !USA.accent with special processing
  569.                               (default).
  570.  
  571.     Note.  Selected accents must be in the Locale:accents drawer.
  572.  
  573.  
  574.   E.  Text Quotes (TEXTQUOTES=) Select "text quote" processing mode: 
  575.  
  576.     1.  (TEXTQUOTES=say) Always pass quotes to Translator.
  577.     2.  (TEXTQUOTES=fix) Tone shift with special processing (default).
  578.     3.  (TEXTQUOTES=tone) Tone shift with normal and special processing.
  579.     4.  (TEXTQUOTES=cut) Remove double quotes from spoken text stream.
  580.  
  581.   F.  Reference Quotes (REFQUOTES=) Select maximum BBS style reference
  582.                                     quote level tonal indication:
  583.  
  584.     1.  (REFQUOTES=n)  Set maximum reference tone level to n where
  585.                        0<=n<=8.
  586.     2.  (REFQUOTES=8)  Set 8 reference tone levels (default).
  587.  
  588.   G.  Speak Rate (SPEAK_RATE=) Set normal speaking rate:
  589.  
  590.     1.  (SPEAK_RATE=nnn) Set speaking rate to nnn where 99<nnn<301.
  591.     2.  (SPEAK_RATE=210) Set speaking rate to 210 (default).
  592.  
  593.   H.  Preset (PRESET=) Select fixed display palette:
  594.  
  595.     1.  (PRESET=normal) Select the normal display palette (default).
  596.     2.  (PRESET=hcontrast) Select the high contrast display palette.
  597.  
  598.   I.  ASL Size (ASL_SIZE=) Select optional full-screen ASL requester:
  599.  
  600.     1.  (ASL_SIZE=full) Select full-screen, low-res ASL requester
  601.                         (aid to visually impaired users).
  602.     2.  (ASL_SIZE=normal) Normal ASL requester (default).
  603.  
  604.  
  605. -------------------------------------------------------------------------
  606.  
  607.                          VOCAL ANNOTATION OPTIONS
  608.  
  609. -------------------------------------------------------------------------
  610.  
  611.      Two general options enable partial or complete suppression of vocal
  612.   annotation.  Partial suppression is accomplished by proceeding the file
  613.   name with a -q option for CLI invocation or adding an ANDYOFF tooltype to
  614.   the file or program icon. This will cause the greeting and most of the
  615.   exit messages to be skipped. Some of the normal menu responses will be
  616.   less verbose with this option. The -a option in CLI invocation or
  617.   ANDYOFF=all file tooltype (but not for the program) icon
  618.   will suppress all vocal messages except for the final "GOODBYE" and error
  619.   reports.  The ANDYOFF=none file tooltype will restore normal vocal
  620.   messages for that file.
  621.  
  622.  
  623.   ----------------------------------------------------------------------
  624.  
  625.                        PROGRAM NOTES: MULTITASKING
  626.  
  627.   ----------------------------------------------------------------------
  628.  
  629.     SWread does multitask, even with itself.  The user is cautioned that
  630.   there is no guarantee that multitasking SWread will be safe on his or her
  631.   system.  The program has been tested with Mungwall and Enforcer.
  632.   Translator42 has been found to have a potential buffer overflow software
  633.   failure problem.  Upgrading to Translator43 is recommended.
  634.  
  635.     The CPU is under intensive use while this program is talking. This is a
  636.   serious limitation to effectively multitasking this program on 68000 based
  637.   systems.
  638.  
  639. -------------------------------------------------------------------------
  640.  
  641.                              GENERAL WARNING
  642.  
  643. -------------------------------------------------------------------------
  644.  
  645.     I have noticed that some programs, such as AmigaBasic, may fail [GURU]
  646.   if they start using the audio hardware while another program is using the
  647.   narrator or audio system.  In each case where I have observed this with
  648.   WreadFiles running [No such problem has yet occurred with SWread], the
  649.   program in question will also fail if also multitasked with the Commodore
  650.   Speak: device. I suspect these programs may not been written to deal with
  651.   multi-process contention for the audio channel resources.
  652.  
  653.   ----------------------------------------------------------------------
  654.  
  655.                       NARRATIVE QUOTED TEXT HANDLING
  656.  
  657.   ----------------------------------------------------------------------
  658.  
  659.     Narrative quoted text handling is normally a Special Processing
  660.   function.  This feature is only invoked if the default accent file name
  661.   is prefixed with an '@' character, such as @!USA in the tooltype list.
  662.   It may also be invoked with its own tooltype.
  663.  
  664.     The previous versions of WreadFiles let the Translator Library put the
  665.   words `quote' and `unquote' around each segment of quoted text.  With
  666.   WreadFiles version 5.0, standard "quoted segments" of text are indicated
  667.   by a 15 Hz tone increase.  `Single' quotes are ignored as before.
  668.  
  669.     "Pending quotes like this will remain in effect for a maximum of 24
  670.   sentences.  Pending quotes will end with the next quote encountered while
  671.   they are in effect or at the next blank or cosmetic line encountered"
  672.   unless a quotation mark is at the very beginning of the next sentence.
  673.   Pending quotes are not allowed to continue across changes of the BBS
  674.   quote level.
  675.  
  676.     A noticeable delay will occur around short "quoted" phrases within a
  677.   sentence because each tonal segment must be sent to the narrator
  678.   separately.
  679.  
  680.   ----------------------------------------------------------------------
  681.  
  682.                 INTERNET/BBS TEXT REFERENCE QUOTE HANDLING
  683.  
  684.   ----------------------------------------------------------------------
  685.  
  686.      Internet/BBS quoted text handling is normally a Special Processing
  687.   function.  This feature is only invoked if the default accent file name
  688.   is prefixed with an '@' character, such as @!USA in the tooltype list.
  689.   It may also be invoked with its own tooltype.
  690.  
  691.     SWread provides support for tonal representation of 8 levels of
  692.   Internet/BBS style quoted text. The tone of the voice is increased 10 Hz
  693.   per recognized quote indicator.  Valid quote indicators now include the
  694.   leading colon, bar and right square bracket.  Initialled quotes [MB>] are
  695.   not recognized because they may occur in normal text.  The number of
  696.   tones provided may be changed by the (REFQUOTES=) tool-type on the
  697.   program or reading object file icon. Setting (REFQUOTES=0) will suppress
  698.   this feature.
  699.  
  700.    Reference level 0 with a "narrative quote" test example.
  701.    > Reference level 1 with a "narrative quote" test example.
  702.    >> Reference level 2 with a "narrative quote" test example.
  703.    :>| Reference level 3 with a "narrative quote" test example.
  704.    >> >> Reference level 4 with a "narrative quote" test example.
  705.    >| > >> Reference level 5 with a "narrative quote" test example.
  706.    ::>> >> Reference  level 6 with a "narrative quote" test example.
  707.    ::>>| >> Reference level 7 with a "narrative quote" test example.
  708.    ]:>>|]  >> Reference level 8 with a "narrative quote" test example.
  709.  
  710.  
  711.  
  712.   ----------------------------------------------------------------------
  713.  
  714.                     PROGRAM NOTES: FILE COMPATIBILITY
  715.  
  716.   ----------------------------------------------------------------------
  717.  
  718.     SWread works best with single column ASCII text files having a
  719.   maximum length of 80 characters.  These files are printed to the screen in
  720.   their original format.  The program recognizes ^J (CONTROL J which is ASCII
  721.   code 10), ^M, or sequential ^M^J or ^J^M as end of line (EOL)indicators. 
  722.   SWread will strip out many standard ANSI escape sequences, such as
  723.   those used for color formatting (^[[33;41m).  The program ignores these
  724.   codes, since color is used by the program to show where active reading is
  725.   taking place. (Lines containing sentences which have been read are black
  726.   and the unread lines are blue.)
  727.  
  728.     If the text lines in the file are longer than 80 characters then the
  729.   program will reformat the lines to fit on the screen.  This also applies
  730.   to files which only have end of line indicators at the ends of paragraphs. 
  731.  
  732.     Files containing tables of numbers or mathematical formulas are not
  733.   recommended for use with SWread.  The program works best with
  734.   narrative text. 
  735.  
  736.     If you attempt to read a specially formatted, word processor file
  737.   (or any binary file) the result will usually be gibberish.  Some word
  738.   processors which use near ASCII format (Scribble!) may be partially
  739.   readable. 
  740.  
  741.     If the file contains special angle bracket indicators such as f<o:>gel
  742.   for fögel or t<e^>te-<a`>-t<e^>te for tête-à-tête, then it is best to use
  743.   a text editor to search and replace all such bracket structures with
  744.   their equivalents. Reading un-converted HTML or SGML files is not
  745.   recommended. HTMLess may be used to convert many HTML files to plain
  746.   ASCII.
  747.  
  748.   ----------------------------------------------------------------------
  749.  
  750.                           SHORT TEXT LINE FILES
  751.  
  752.   ----------------------------------------------------------------------
  753.  
  754.     Since unusually short text lines (like the line above) are one of the
  755.   criteria that SWread uses to identify sentence ends.  Thus files with
  756.   narrow text will not be properly processed.  The reading of files known
  757.   to be 60 or 40 characters wide, maximum, can be improved by adding one of
  758.   the two standard text width identifiers, {60} or {40} respectively, after
  759.   the file name.  The curly brackets are required.  At least one space must
  760.   precede the first bracket.  See the section on index files for an
  761.   example. 
  762.  
  763.       SWread project icons may also contain a text width code with a tool
  764.  type of the form:
  765.  
  766.                         [MODE=singlefile,40]
  767.  
  768.     With SWread version 5.1, the text width in effect will be saved
  769.   with any icon created.  This parameter may be declared in the options
  770.   menu.
  771.  
  772.     This type of entry is not relevant for index file icons because that
  773.   information is contained in the file. 
  774.  
  775.   ----------------------------------------------------------------------
  776.  
  777.                     INDEX FILES: Multi-File Read Mode
  778.  
  779.   ----------------------------------------------------------------------
  780.  
  781.     Index files are ASCII text files where each line contains a file
  782.   description in the first 41 characters of the line and a file name which
  783.   begins at the 42nd character.  The file description is what the user will
  784.   see if he uses the Pick File option.  The file name is what SWread uses
  785.   to access the file.  If any file cannot be accessed by the name provided
  786.   then the program will "good-bye" with a red screen abort.  For best
  787.   results, use the volume name rather than device name to identify the root
  788.   directory of each file.  The entry can also contain the narrow text width
  789.   indicators.  An example of a typical entry line is as follows:
  790.  
  791. File description               File name at column 42       Text width code
  792. |                                        |                         |
  793. SuperWord from GnSoft by Ron Jennings    UG_Disk:Reviews/SuperWord {60}
  794.  
  795.     In this example, the file name is followed by an optional text width
  796.   code.  The entries should be sequential with no blank lines.  The last text
  797.   line should end with a carriage return.  Lines will be ignored which
  798.   reference the same file name as that of the preceding line.  The
  799.   tool-types of indexed files are not accessed by SWread.
  800.  
  801.   ----------------------------------------------------------------------
  802.  
  803.                        PROGRAM NOTES: HOW IT WORKS:
  804.  
  805.   ----------------------------------------------------------------------
  806.  
  807.      SWread reads a text file in 36 K-Byte segments.  This enables the
  808.   program to handle files of any size without exceeding normal memory
  809.   limitations.  The text in the buffer is processed as it is read to avoid
  810.   processing delays.  The first stage of this processing is the conversion
  811.   of the file end of line (EOL) characters to the standard C programming
  812.   language end of text-string indicators.  If the file lacks EOLs, there
  813.   may be a noticeable delay at this point while the program searches to the
  814.   end of the buffer.
  815.  
  816.      SWread next uses standard punctuation marks and other criteria to
  817.   determine the location of sentence breaks. This allows the text to be
  818.   spoken one sentence at a time to achieve a natural speech rhythm.
  819.   Sentences may be fractions of lines or any number of whole and partial
  820.   lines up to one full screen.  The text lines are printed to the screen as
  821.   is except that long lines are wrapped and joined with the next line and
  822.   some ANSI control codes are stripped out.
  823.  
  824.      This program uses its own private screen to provide a simple fixed
  825.   environment for the 'bare-bones' high-speed direct text rendering
  826.   routines and reduce Workbench clutter.  Each sentence is written once,
  827.   before it is read or processed for speaking in the New-Text color and
  828.   precisely over-written again, after it has been read in the Normal-Text
  829.   color.
  830.  
  831.      The program keeps track of the number of bytes read as each sentence
  832.   is resolved to update the file position indicator and implement file
  833.   position seek.
  834.  
  835.      When special processing is invoked, SWread will use high-speed
  836.   conditional, search and replace routines to modify the spoken form of
  837.   each sentence.  Each modification is performed in sequence to the whole
  838.   sentence to be spoken.  The program will attempt to identify and remove
  839.   cosmetic text patterns from the spoken text so that the listener does not
  840.   have to hear such things as the word "asterisk" repeated 76 times.  This
  841.   program mode cannot protect the listener from general ASCII art, but it
  842.   will remove some combinations of slashes, spaces and backslashes which
  843.   are abnormal for spoken text.
  844.  
  845.     When the reading is finished, the Workbench screen is popped forward.
  846.   This may be suppressed by the -r CLI invocation option.
  847.  
  848.   ----------------------------------------------------------------------
  849.  
  850.                   PROGRAM NOTES: POTENTIAL APPLICATIONS
  851.  
  852.   ----------------------------------------------------------------------
  853.  
  854.   The following are potential applications of this program:
  855.  
  856.   A. Reading ASCII Text Files. 
  857.  
  858.      SWread may be used to read standard ASCII text files.  In this
  859.   application using SWread is similar to typing a file to SPEAK: except
  860.   that SWread also displays the text being read and allows random access
  861.   to any part of the document by shift-clicking on the file reading
  862.   position indicator.
  863.  
  864.   B. ETEXT Book Reader.
  865.  
  866.      Many classic books have now become available on the Internet.  The
  867.   !USA.accent has been developed with many of these texts.  Most of these
  868.   texts are quite readable as is, however I find it helpful in many cases
  869.   to remove the special annotation and sentence breaking pagination that is
  870.   frequently used or retained to attempt to make the file a faithful
  871.   representation of the appearance of the original text.
  872.  
  873.   C. Aid For Visually Impaired
  874.  
  875.     While SWread has not been specifically written for this application,
  876.   I have made the menu selection boxes large so that someone with minor
  877.   visual impairment might make them out.  Perhaps SWread combined with
  878.   another utility would be beneficial for people with more severe visual
  879.   impediments.  SWread does allow other programs to obtain access to the
  880.   translator, narrator, and audio.device between each sentence break. 
  881.  
  882.  
  883.   ----------------------------------------------------------------------
  884.  
  885.                        PROGRAM NOTES: DEFICIENCIES
  886.  
  887. -------------------------------------------------------------------------
  888.  
  889.     My primary emphasis on WreadFiles has been the speech correction. 
  890.   There remain several areas where this program should be improved.
  891.  
  892.   A. No Locale Support.
  893.  
  894.     As of this version, there is no Locale support for annotation.  All
  895. annotation is in English and the American.accent is used for spoken
  896. annotation.  Foreign users may wish to disable the vocal annotation
  897. with the (ANDYOFF=) too.
  898.  
  899.   B. Sentence Speaking Cannot Be Interrupted. 
  900.  
  901.     This is normally not a problem.  However, if you load a file which
  902.   contains a long segment of text lacking the criteria which identify
  903.   sentence breaks, then the program may not respond to your commands or
  904.   attempts to stop the program for several minutes. 
  905.  
  906.   D. No ARexx Port
  907.  
  908.     It is conceivable that an ARexx port could be useful for interactive
  909.   multitasking.  I have not yet considered what should be done in this
  910.   regard. 
  911.  
  912.     The -r CLI option allows SWread to be invoked with an ADDRESS
  913.   COMMAND call to read a file prepared by another application.  I have
  914.   developed an ARexx script for AWeb that calls WreadFiles to read the
  915.   current WWW page text.
  916.  
  917.  
  918.   ----------------------------------------------------------------------
  919.  
  920.                            CAVEATS AND WARNINGS
  921.  
  922. -------------------------------------------------------------------------
  923.  
  924.     This is a program I wrote initially for my own use.  No warranty is
  925.   made on the accuracy of this documentation or the fitness of this
  926.   software for any purpose.  There is no guarantee that future improvements
  927.   in the operating system software will not degrade or disrupt the
  928.   operation of this program. It is quite likely that any replacement system
  929.   would be incompatible with this program. No commitment is made to release
  930.   future versions of this program.
  931.  
  932.     I have only used SWread on two computer systems:
  933.  
  934.      1. Amiga A1000 with 512 kilobytes of chip and 2 megabytes of fast ram
  935.         using Kickstart 1.2 with Workbench 1.3.  I cannot guarantee
  936.         operation with a 512K Amiga.
  937.  
  938.  
  939.   2. A4000/040 system with 16 megabytes total ram, OS 3.0. 
  940.  
  941.     The only background programs I have had running are ConMan on the A1000
  942.   and on the A4000; Enforcer-quiet and GRABBIT.
  943.  
  944.  
  945.     This software has not been tested in other systems or with all
  946.   possible settings and combinations as commercial software is normally
  947.   tested during the beta test stage.  The user must assume FULL
  948.   responsibility for backing up important files etc. should this program
  949.   malfunction in his or her system or expose a weakness in other software
  950.   while multitasking.
  951.  
  952.     You may find the steady drone of the Amiga voice produced by SWread
  953.   sleep inducing. :}
  954.  
  955.     I hope you find SWread useful and that none of the dire possibilities
  956.    mentioned above ever occurs. 
  957.  
  958.                                                  M.L. Barlow   16 June 1997
  959.  
  960.  
  961.