home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 316.lha / EtaleFileReader / efr.doc < prev    next >
Text File  |  1989-11-30  |  12KB  |  249 lines

  1.  
  2.                         The Etale File Reader
  3.  
  4.                         by William F. Hammond
  5.                             Copyright 1989
  6.  
  7.    [This program is freely distributable.  It may not be included in a
  8. product that is sold, other than in a collection of freely distrib-
  9. utable software for which a modest charge for material and handling is
  10. imposed, without the permission of the author (address at the end of
  11. this file).]
  12.  
  13.    REVISIONS:  This version contains minor revisions and corrections.
  14. Information on the revisions may be found at the end of this file
  15. along with a newly suggested use for "program" mode.
  16.  
  17.    The Etale File Reader is a "more"-like program designed for use
  18. with the mathematically oriented character set that comprises the
  19. Etale font.  The Etale font is an Amiga screen font that is identical
  20. to the ordinary "topaz 8" screen font on standard ASCII characters but
  21. has mathematical symbols, including a complete Greek alphabet,
  22. installed in the "high-ASCII" range.
  23.  
  24.    The Etale font contains four non-printing characters (with hex
  25. codes 87, 86, 88, 8A) for "start superscript", "end superscript",
  26. "start subscript", and "end subscript" that correspond to the
  27. <Ctrl>-<Alt> versions of the keys labeled "g", "f", "h", and "j" in
  28. the "math" keymap that accompanies the Etale font.  My chief reason
  29. for writing the Etale File Reader has been to make it possible to see
  30. superscripts and subscripts on the Amiga screen without having the
  31. machine taken over by a large technically-oriented word processor.
  32.  
  33.    Note that this file reader reads ALL "printing" codes in whatever
  34. font it finds installed when it is called.  Support for super- and
  35. subscripts is, moreover, available when reading ANY file in ANY font
  36. provided that the super- and subscripts are turned on and off in the
  37. file by means of the non-printing codes described above.
  38.  
  39.    It had been possible with the version of the Etale font distributed
  40. in February 1989 to achieve on a suitable printer that which can now
  41. be seen on the screen. The reason that superscripts and subscripts
  42. cannot be seen on the screen without a special program is that the
  43. Amiga's "console device" does not support them. Nor does it support
  44. "merged" symbols.  For example, if a file contains a "/" character,
  45. followed by a "<backspace>" and then a "\", on many printers, and now
  46. in this reader, the result will be something like an uppercase "x". 
  47. The Etale File reader weighs in at 14,708 bytes.  It is perhaps, even
  48. then, slightly obese since it is written in "C".
  49.  
  50.    There are several other ways in which this reader differs from the
  51. standard Commodore-supplied "more" program.  First, for better or for
  52. worse, it does NOT run from WorkBench.  This is because it opens a
  53. screen-size borderless and gadgetless window on the active screen. 
  54. (This makes the viewing area as large as possible consistent with the
  55. size of the screen and the size of the user's font.  Be warned that a
  56. LINE TOO LONG WILL NOT WRAP, but will be CLIPPED.  And yes, "hard"
  57. linefeeds are required.)  Most users will want to have the means to
  58. get behind this window, and it cannot be assumed that the average
  59. WorkBench user is so equipped.  
  60.  
  61.    Care has been taken to make sure that this reader is fully compat-
  62. ible with the concurrent piping available through the PIP: device that
  63. is part of W. Hawes' "ConMan" console handler.  Also, rather than
  64. build a "find" facility into it, I decided to design this program so
  65. that it could be easily inter-faced at the "shell" level with the
  66. "search" command.  For example, with PIP: in the ARP shell:
  67.  
  68.                alias efrf  search file [] \| efr g file
  69.                efrf scruff
  70.  
  71. will put you in the file "file" on the line containing the first
  72. occurence of the pattern "scruff".  To proceed to the next occurence,
  73. enter "n" in the reader window.  To change to regular file reading
  74. mode enter "c" for "continue" in the reader window.
  75.  
  76.    The various internal file reader commands are listed on the "help
  77. card" in this package that has the file name "efr.help".  They are
  78. mostly self-explanatory.
  79.  
  80.    For a quick demonstration of what mathematical text can look like
  81. in the Etale File Reader, install the Etale font using "FastFonts"
  82. from WorkBench 1.3 with the command
  83.  
  84.                ff etale.font
  85.  
  86. after first copying the file "etale.font" to your "fonts:" directory,
  87. creating a subdirectory named "etale" in your "fonts:" directory, and
  88. copying the file "etale_8" to the filename "fonts:etale/8"; and then
  89. enter the command
  90.  
  91.                efr efrdm
  92.  
  93. in your shell (or CLI) window to view the "demo" file.
  94.  
  95.    To scroll through a file in the Etale File Reader without pausing
  96. (except at the end of the file) enter the command
  97.  
  98.                efr t file
  99.  
  100. or the command
  101.  
  102.                efr <file t
  103.  
  104. in your shell window.  Or, simply at any time while reading in a file,
  105. enter "t" at the prompt to scroll toward the end.  While scrolling,
  106. hit any "regular" key to pause and again hit any "regular" key other
  107. than "x" to continue the scroll.  At any time while paused in a scroll
  108. enter "x" to bring up the normal file reader prompt line.
  109.  
  110.    The only command line options are "t", as just explained, or "g",
  111. which invokes "program mode".  To use "program" mode you need a
  112. "program" which is simply an ASCII file in which each line begins with
  113. a number (ignoring leading whitespace characters -- the whitespace
  114. characters are "<space>", "<tab>", "/", "*", "'", and ";").  A line
  115. in a program file that, ignoring whitespace characters, does not begin
  116. with a number will be ignored.  If there are lines beginning with the
  117. numbers 5, 61, 47, and 83, then the command
  118.  
  119.                efr <program g file
  120.  
  121. will open the reader at line 5 in "file".  From that point normal
  122. reader commands can be given.  Then when ready, entering "n" will move
  123. the reader to line 61.  Subsequent invocations of "n" will move the
  124. reader to the lines 47 and 83.
  125.  
  126.    The "efrf" alias described above is not very practical since it is
  127. useful only for searching through one file with the name "file".  The
  128. simplest practical way of interfacing the file reader with the search
  129. command is to use the following shell script with script name "rdf":
  130.  
  131.           .key file/A,pat/A
  132.           .bra {
  133.           .ket }
  134.           echo "Searching {file} for the pattern {pat}"
  135.           search "{file}" "{pat}" | efr g "{file}"
  136.  
  137. (Note that since this script takes arguments, it should NOT be used
  138. with the first version of ARP 1.3 "execute", released in April, 1989,
  139. although it works perfectly well with the corrected version of ARP 1.3
  140. "execute" as well as with the WorkBench 1.3 "execute".)  Then the
  141. command
  142.  
  143.           rdf haystack needle
  144.  
  145. will bring up successively the occurences of the pattern "needle" in
  146. the file "haystack" assuming that the script bit has been set on the
  147. file "rdf".
  148.  
  149.    In addition to the special non-printing ASCII codes reserved for
  150. super- and subscripting there is support for the following escape
  151. sequences for monochromatic text styling:
  152.  
  153.                     <Esc>[0m    Clear all style
  154.                     <Esc>[1m    Boldface
  155.                     <Esc>[3m    Italics
  156.                     <Esc>[4m    Underline
  157.                     <Esc>[7m    Inverse video
  158.  
  159. Other special characters are <backspace> (hex 08) and <tab> (hex 09).
  160. Upon finding a <backspace> the output cursor is moved backward the
  161. width of one character without overwriting.  A printing character that
  162. follows will be merged with the character preceding the backspace.
  163. Upon finding a <tab> the output cursor will be moved forward the width
  164. of three characters without overwriting.  There are no "tab stops" in
  165. the file reader window.  A "null" code (hex 00) in the file being read
  166. will be ignored.
  167.  
  168.    The program does not buffer the file being read.  Thus, it is
  169. possible under backward movements and under forward movements of more
  170. than one screen page for the reading program to be oblivious of
  171. control codes in the file that were "skipped over".  Although there is
  172. no limit on the level of subscripting, there will be glitches when a
  173. line with three or more levels of subscripting appears as the last
  174. line on the screen with its subscripting overwritten by the prompt
  175. line.  This may be cleared by a backward half screen page motion ("u")
  176. followed by a forward screen page motion ("<space>").
  177.  
  178.    Please note that the use of hex code 9B as a substitute for
  179. "<Esc>[" in the world of the console device is not supported in this
  180. file reader.  Any character found in a file that is not a special
  181. character or part of an escape sequence, as described above, will be
  182. sent to the file reader window.
  183.  
  184.    Output to the file reader window is by means of the Move() and
  185. Text() routines found in the ROM-based graphics library.  The file
  186. being read is processed a line at a time.  Before a line is sent to
  187. the reader window it is divided into parts each of which consists of
  188. a sequence of control characters (except for the first part of a line
  189. that does not begin with a control character) followed by a sequence
  190. of regular characters (except for the last part of a line that ends
  191. with a control character).  There is one call to Text() for each
  192. part of a line that has regular characters.  There is no buffering.
  193. Thus, the program does not know the number of lines in the file that
  194. it is reading until the first time that it reaches the end, and any
  195. backward move in the file requires a rewind (which cannot be done if
  196. the file is presented to the program as "standard input").  The user's
  197. response at a prompt is picked up through the reader window's
  198. "Intuition Direct Communication Message Port".
  199.  
  200. Please report any problems or bugs to:
  201.  
  202.   William F. Hammond                           telephone: 518-442-4625
  203.   Department of Mathematics and Statistics
  204.   SUNYA                                        email:
  205.   Albany, NY  12222  (USA)                       wfh58@leah.albany.edu
  206.           
  207.  
  208.                               REVISIONS
  209.  
  210.    This first comment is not a revision, but the answer YES to the
  211. question "Is programming mode good for anything other than the inter-
  212. face with the "search" command?".  If you have an editor with a good
  213. ARexx (a product of William S. Hawes, Maynard, Mass., USA) interface,
  214. you can open the Etale File Reader from the editor on the page that
  215. you are looking at in the editor.  This certainly works with TxEd Plus
  216. (a product of Microsmiths, Inc., Cambridge, Mass., USA). I have not
  217. implemented such a macro with any other editor.  It is just a question
  218. of having the editor (a) write the file being edited, (b) report its
  219. location and the name of the file being edited to ARexx, (c) saving
  220. that location, (d) moving to the top of the screen, (e) writing that
  221. line number in a small temporary file, (f) opening the file reader in
  222. program mode with that small temporary file as the "program", and (g)
  223. returning the editor's cursor back to where it was.  In TxEd Plus all
  224. of this can be wired to a single touch of the "0" key on the numeric
  225. keypad.
  226.  
  227.    The welcome banner flashes only subliminally if the program is
  228. called by its native name "efr" (all lower case) on the command line.
  229. The call may be through any alias so long as the alias string
  230. definition uses the native name.  (It does not matter if the file name
  231. itself is lower case.)  This speeds up loading significantly.  On the
  232. other hand, if the program is not called by its native name, the
  233. welcome banner flashes, as in the earlier versions, for one-half
  234. second.
  235.  
  236.    The message that is sent to the console by the program when (and
  237. if) it discovers the number of lines in the file is now sent to
  238. "standard output" rather than unconditionally to the console. 
  239. Therefore, this message may now be diverted.
  240.  
  241.    If the last character in the file being read is not a linefeed, the
  242. program may or may not, depending on how it reaches the last line,
  243. decide to count the last line in the line count that is reported when
  244. it first reaches the end of the file and subsequently in the "Go To
  245. Line" prompt.  It would make the program two or three hundred bytes
  246. larger to eliminate this, and I am not currently inclined to do so. 
  247. (After all, EMACS on the local mainframe will yell at a user trying to
  248. write a file that does not end with a linefeed.)
  249.