home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 337.lha / lire_v2.1 / lire.doc < prev    next >
Encoding:
Text File  |  1990-02-07  |  12.1 KB  |  223 lines
  1. 4]                  ------------------------------------
  2. 3]                           LIRE (revised)
  3. 3]                        © by Charles VASSALLO
  4. 4]                  ------------------------------------
  5.  
  6.   (All rights reserved.)
  7.  
  8.    This is the second version of my minimal text reader, that reads text
  9. files and nothing more. It is a few bytes shorter (2044 instead of 2084) but
  10. one block less (5 instead of 6). Some bugs have been fixed; maybe new ones
  11. have appeared -- let me know. It lost a few peculiarities (no copper list
  12. now) but it gained a few additional features.
  13.  
  14. (i) the cursor indicates the location in the text and allows you to directly
  15. jump anywhere you want to go, instead of flipping pages.
  16.  
  17. (ii) more color features. The text is displayed in a 4-color window opened
  18. in a custom screen. The background is in color 1 and the text is normally
  19. printed in color 2, except for the lines beginning with codes 3] or 4], which
  20. are printed in color 3 or 4 respectively. Can be useful for highlighting
  21. titles, as shown above; this is commonly used throughout JUMPDISK.
  22.   (By the way, I think that it would be more consistent with the internal
  23. operating system numeration to number colors from 0 to 3, but it is now
  24. customary to go from 1 to 4)
  25.   The default palette (the colors you are presently seeing) is imposed by
  26. the program. This is a deliberate choice, my personal taste. If you don't
  27. share it , you can change the palette either by means of a little surgery
  28. on the binary file, or using the more fanciful color possibilities of the
  29. routine. More on this later on.
  30.  
  31.    There is no depth gadget. However, a custom screen is used for the
  32. display, so you can push it in the back or in the front of the other screens
  33. by pressing <left-AMIGA+ N> or <left-AMIGA + M>. The drawback of the custom
  34. screen is that it eats up 32 Kbytes of precious chip ram ; I also considered
  35. a less greedy version with a display in the Workbench screen, but I had to
  36. set up special hotkeys for screen switching (because AMIGA+N/M keys do not
  37. work with the various windows in the Workbench screen). All in all, I feel
  38. that the present version is simpler to use.
  39.  
  40.    In principle, lines are not truncated at 80 characters. Words that would
  41. be cut by the 80-th character limit are gently shifted to the next line.
  42. There are 2 intentional exceptions (not to mention those unintentional) :
  43. - lines with a first word larger than 80 characters, i.e. 80 characters or
  44.   more without any space. What language do you speak? Or maybe you are 
  45.   reading a binary file? Such lines are definitely truncated.
  46. - lines where the 1st character is ']', for reasons that will be explained
  47.   later on.
  48. Files can be prepared with any text editor. You can even use a text processor
  49. provided that you save the file as a plain ASCII file, otherwise all the
  50. control characters would be rendered as various uncontrolled hieroglyphs.
  51. For the same reason, try to avoid TAB codes. (Most of text editors designed
  52. for programmers can insert TAB codes. You can remove them with a special
  53. utility like 'Repstring' -- see JumpDisk, Sept.88 -- or by loading the file
  54. with ED and saving it).
  55.  
  56.    LIRE is re-executable and reentrant, i.e. it can be made resident. If
  57. anybody meets a guru after that, please tell me. Though the practical
  58. interest of making such a tiny text-reader resident is questionable, it was an
  59. interesting exercice to do so. Also, it allowed me to shorten the routine,
  60. mainly because a lot of local variables are now dynamically allocated by the
  61. system instead of being part of the program itself. Here are some details
  62. about that :
  63.  
  64. ]]12                                   ]13                                          ]21
  65. ]]12     Traditional program           ]13           Reentrant program              ]21
  66. ]]12                                   ]13                                          ]21
  67. ]]12 Variables are directly reserved   ]13  The direct reservation of memory for    ]21
  68. ]]12 within the program itself, like   ]13  local variables is replaced with a      ]21
  69. ]]12       var1:  dc.l 0               ]13  calculation of offsets, like            ]21
  70. ]]12       var2:  dc.w 0               ]13              var1=0                      ]21
  71. ]]12       var3:  dc.w 0               ]13              var2=var1+4                 ]21
  72. ]]12       .............               ]13              var3=var2+2                 ]21
  73. ]]12 and so on. The corresponding      ]13              ...........                 ]21
  74. ]]12 memory is a physical part of      ]13             total=last.var+4             ]21
  75. ]]12 the object file (that in your     ]13   These numbers are calculated by the    ]21
  76. ]]12 diskette). In the program,        ]13   assembler and do not correspond to any ]21
  77. ]]12 variables are called with a       ]13   physical memory. A block of 'total'    ]21
  78. ]]12 direct addressing, like           ]13   bytes is dynamically allocated and     ]21
  79. ]]12      move.l var1,d0               ]13   its address is put into some address   ]21
  80. ]]12      add.w  var2,d0               ]13   register, let's say a4. The variables  ]21
  81. ]]12      ..............               ]13   are called with indirect addressing :  ]21
  82. ]]12 Since a program can be loaded     ]13            move.l var1(a4),d0            ]21
  83. ]]12 anywhere in the memory, DOS needs ]13            add.w  var2(a4),d0            ]21
  84. ]]12 special information to relocate   ]13            .................             ]21
  85. ]]12 the variables. This information   ]13   The code is "position-independent".    ]21
  86. ]]12 is provided by the assembler and  ]13                                          ]21
  87. ]]12 it can somewhat increase the      ]13   NO RELOCATION INFORMATION REQUIRED!    ]21
  88. ]]12 length of the object file.        ]13                                          ]21
  89. ]]12                                   ]13                                          ]21
  90.  
  91. I thus obtained a routine with about 1800 bytes (the initial LIRE was
  92. 2084 bytes). However, since a 1800-byte file occupies the same place in a
  93. diskette as a 2048-byte files, i.e. 5 blocks, why not add some extra
  94. functions until the 5 blocks are filled ? I decided to add new color
  95. features, such as those just above. Similar features were already displayed
  96. in "Read2.0", by Thomas Beale (see JumpDisk, March 1989).
  97.    Skeptical ? Color is vanity ? (But do you realize that you are using an
  98. Amiga ??) Well, you can find a reduced LIRE0 in this drawer. Only 1836 bytes
  99. long, without any more fanciful peculiarity than the ability to read the
  100. lines beginning with "c]". As for you, color-fancying readers, follow me!
  101.  
  102.    Color instructions must be set in the text file itself. Obviously, they
  103. don't improve its readeability when displayed with another reader, but
  104. after all, such files should not be normally displayed in that way. You are
  105. given two new possibilities :
  106.   -  you can change both pen and background colors anywhere in a line,
  107.   -  you can change the whole palette.
  108.  
  109. ]]14                                  ]21
  110. ]]14 TO CHANGE PEN/BG COLORS LOCALLY, ]21 you must first inform the program that
  111. ]]14                                  ]21 there is a special coding in the line,
  112. by inserting "]" at its very beginning. Then, insert "]pb" (where p or b are
  113. 1,2,3,4) to set the pen color to "p" and the background color to "b", at the
  114. exact location where you wish the new colors to be set. For instance,
  115. the lines
  116.  
  117.  "] Now, default colors (pen=2 bg=1);]32 now, pen=3 bg=2;]14 now, pen=1 bg=4"
  118.  "] Default again; ]13now, pen=1 bg=3                    ]21"
  119.  
  120.  (actually without the double quotes) will be rendered as
  121.  
  122. ] Now, default colors (pen=2 bg=1);]32 now, pen=3 bg=2;]14 now, pen=1 bg=4
  123. ] Default again; ]13now, pen=1 bg=3                    ]21
  124.  
  125. Notice that the default colors are restored at the final linefeed, just after
  126. the last character of the line; the next line begins with them. If you want a
  127. whole paragraph printed with special colors, you must insert a sequence ]]pb
  128. ahead of each line (a "]" to announce a special line, and "]pb" to switch
  129. colors immediately). Similarly, in the second line above, notice the extra ]21
  130. after the spaces to be rendered in the new background color; without it, ED
  131. would have put its linefeed just after the last character ("1") and the
  132. colored line would have stopped here.
  133.  
  134. C]AA9004A22549
  135. ]]14                                 ]21
  136. ]]14 HOW TO CHANGE THE WHOLE PALETTE ]21  Inside the operating system, colors are
  137. ]]14                                 ]21  defined with their amounts of red, green
  138. and blue, coded as hex numbers from 0 to F (F=maximum value, 0=null value).
  139. The brightest white is thus FFF; a medium grey is 999; a dark green is 050;
  140. a clear reddish yellow (not the brightest) is B90, and so on.
  141.    To change the palette, you just have to insert a special line, beginning
  142. with a code C], followed by the four triplets RGB, for the four colors of
  143. the workbench display (see below)
  144.    Putting this line ahead of the whole file allows you to bypass the
  145. default colors of the routine.
  146.  
  147. As an example ,let's assume that we want the following colors
  148.            1 (background),      dark bluish gray   : 445
  149.            2 (normal printing), bright pale yellow : BB9
  150.            3 (highlight 1) ,    medium cyan        : 0AA
  151.            4 (highlight 2) ,    unsaturated red    : F77
  152. The special command line will be
  153.  
  154. "C]445BB90AAF77"  (of course, no double quote; the C must be the 1st letter;
  155.                    also, no space. Use capital letters only)
  156. C]445BB90AAF77
  157. The palette is changed as soon as this line is read, i.e. just now if you
  158. are scrolling (or flipping pages) forward in this text. It will remain active
  159. as long as no other palette command line is read. Actually, I placed another
  160. command (restoring my favorite default palette) just above the title of
  161. this paragraph. Now, scroll backwards to observe this restoration and come
  162. back here, line by line.
  163.    Of course, if there is a single palette change in the middle of the text,
  164. it can be bypassed if the user goes directly from the beginning to the end
  165. of the text without passing by each page. Nothing is perfect! Remember this
  166. problem when preparing your text file.
  167.  
  168. ]]14                                            ]21
  169. ]]14 THE HARD WAY TO CHANGE THE DEFAULT PALETTE ]21  If you don't like either my
  170. ]]14                                            ]21  default palette or my way of
  171. changing it (for instance, because you adopted the shorter LIRE0), you can
  172. still change it. If you TYPE (with OPT H) the routine file, the end reads
  173.  
  174.     07D0: 20746578 74293C3C 3C3C2020 20203E3E     text)<<<<    >>
  175.     07E0: 3E3E4558 49540AA9 00040A22 05490000    >>EXIT.....".I..
  176.     07F0: 000003F2                               ....
  177.  
  178. Just after the binary for EXIT, you can read 0AA9 0004 0A22 0549. Apart from
  179. the leading zeros, this directly gives the triplets RGB of the four colors.
  180. With your favourite disk editor, replace them according to your own choice
  181. (don't change the leading zeros).
  182.  
  183.  
  184.  
  185. C]AA9004A22549
  186. ]]14                          ]21
  187. ]]14  HOW TO USE THE ROUTINE  ]21  The routine call be called from Workbench or from
  188. ]]14                          ]21  CLI. From CLI, merely type
  189.  
  190.                   lire filename <and press RETURN>
  191.  
  192. To use it with Workbench icons, attach a Project type icon to the text file
  193. you wish to read. Click this icon (once) and select "Info" from the pulldown
  194. Workbench menu at top left of the Workbench screen. In the ToolTypes box,
  195. type
  196.                   :lire
  197.  
  198. and click the Save box at bottom left of the screen. You must copy "lire" to
  199. the same diskette as the text file.
  200.  
  201.  
  202. ]]14                  ]21
  203. ]]14  IN A NUTSHELL   ]21
  204. ]]14                  ]21    When EDiting the file :
  205.  
  206.   p]  prints the line in color p (p=1,2,3,4). Background remains in color 1
  207.  
  208.   ]   announces that special codes ]pb follow in the line, to set pen color
  209.       to p and background color to b
  210.  
  211.   C]RGBXYZUVWKLM (all symbols after ] must be hex numbers. Use capital
  212.       letters only. No space). Sets a new palette
  213.             color 1 = red R , green G, blue B
  214.             color 2 = red X , green Y, blue Z
  215.       ... and so on.
  216.  
  217. ]]12 The codes p], ], C] must be at the extreme left of the line.              ]21
  218.  
  219. 2]  Also, don't forget, when viewing the text :
  220. 2]         leftAMIGA+N pushes the display to the back of other screens
  221. 2]         leftAMIGA+M recalls it in the front
  222.  
  223.