home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / readsum.zip / MANUAL.DOC < prev    next >
Text File  |  1994-12-18  |  8KB  |  204 lines
  1.                         READ SUMmaries
  2.  
  3. Rexx scripts to read summaries and produce selection files created and used
  4. by the uqwk off-line reader program.
  5.  
  6. Use, Modify, and abuse these scripts at your own risk, I'm not responsible.
  7.  
  8. Usage:
  9.  
  10. Sortsum: <Summary File> - pre-process summary files created by uqwk.
  11. Readsum: <No Arguments> - Read and select desired articles. (the interface)
  12. makesel: <No Arguments> - Create a selection file suitable for uqwk.
  13.  
  14.  
  15. Configuration may be done by editing the actual .CMD files, use your
  16. editors Search function to look for lines that contain @CFG in them.
  17. If you are using OS/2, all the file name variables appear at the top of
  18. the file. You may change these as needed.
  19.  
  20. @CFG's after the beginning are mainly designed for those who are porting
  21. to another operating system, (They contain the words OS dependent)
  22.  
  23. ****
  24. Sortsum:   sortsum  <summary.ext>
  25.  
  26.  This script sorts a summary file and formats it so that readsum
  27.  may use it.
  28.  
  29.  Files generated:
  30.        Tempfil   Default "Tempfil.tmp"  (deleted)
  31.        Sortfil   Default "SortFil.tmp"  (Used by readsum)
  32.        GroupFil  Default "Groups.Tmp"   (Used by readsum)
  33.  
  34.  Readsum.CMD and Makesel.CMD need to be aware of the filenames
  35.  created by readsum.CMD.
  36.  
  37.  Sortsum.CMD requires an external sort program. This can be adjusted
  38.  by changing the variable SortPgm = "<your sort program>" Since OS/2's
  39.  Sort program can only work on files < 63k, you may want to obtain another
  40.  sorting program.
  41.  
  42.  SortSum can take a while to run, (after all, this is interpreted Rexx)
  43.  It is non-interactive, so you can use the Detach command with it.
  44.  
  45.  Due to the way readsum works, it is not recommended that you use Summary 
  46.  files larger than 9 newsgroups. The larger the files, the more sluggish
  47.  readsum is.
  48.  
  49. ----
  50. Modifications: (Not required reading)
  51.  
  52. This information is useless unless you intend to modify the scripts,
  53. or create programs to work along with this one. File formats are listed
  54. in the beginning of the file Sortsum.cmd
  55.  
  56. SortSum formats a summary file for the sort program, and feeds it to
  57. the sort program as tempfil. The sort program sorts tempfil and generates
  58. Sortfil. Tempfil is then deleted.
  59.  
  60. Sortsum then generates Groupfil. GroupFil keeps track of the articles that are
  61. tagged, Newsgroup names, and the seek position of where the articles for
  62. a given newsgroup begin. 
  63.  
  64. An explanation may be needed here, Since the articles are proceeded by a
  65. number that represents their newsgroup, And the sort program sorts from left 
  66. to right, in newsgroup order, it is possible to use tempfil's seek
  67. position. (this way sortsum avoids reading the sortfil)
  68.  
  69. Sortsum was written with the goal of using the OS/2's Detach command.
  70. it may safely be run in the background, (depending on your sort program)
  71.  
  72. You may wish to assign Groupfil and Sortfil as command line arguments, for
  73. reasons mentioned under readsum.
  74. ****
  75. Readsum: Readsum <no arguments>
  76.  
  77.                  This is the main interface program.
  78.  
  79. Help is available by pressing F1.
  80.  
  81. I tried to make this program look like Gopher and TIN.
  82.  
  83. Move the tag-pointer up and down the screen, and press enter to select a 
  84. newsgroup. Then move the tag-pointer up and down the list of articles
  85. and tag the article(s) you are interested in retrieving. After you are done
  86. tagging articles, press <ENTER> to save tagged articles, or Escape to
  87. abandon changes.
  88.  
  89. You may search articles by pressing "/", tag an item by pressing "*", select
  90. all articles by pressing "Ins", delete all articles by pressing "Del"
  91. Pressing Home, End, Pgup/Pgdn will navigate the screen in the usual way.
  92.  
  93. Entering a number from the newsgroup selection level will display the articles
  94. for that newsgroup, You may then tag desired articles.
  95.  
  96. When you are done tagging articles, and are at the newsgroup selection
  97. level, press escape or Csr-Left. You will be prompted if you wish to save
  98. tagged articles. Press N,Escape, or Crsr-Left if you do not. (The default is 
  99. to save tag information)
  100.  
  101. You may go back at a later time and continue tagging articles if you wish,
  102. the articles that were previously tagged are saved, depending on if you
  103. pressed "n" on "Save tagged articles?" prompt. This way you don't have to tag
  104. all the interesting articles in 1 session.
  105.  
  106. The selection file is not created when you are done, you need to run
  107. "makesel.cmd" to build this.
  108.  
  109. Configuration:
  110.  
  111.        Tempfil   Default "Tempfil.tmp"  (deleted)
  112.        Sortfil   Default "SortFil.tmp"  (Generated by Sortsum)
  113.        GroupFil  Default "Groups.Tmp"   (Generated by Sortsum)
  114.  
  115. Use your editors "Search" function to look for lines containing @CFG.
  116.  
  117. The above filenames must be consistent with Sortsum and Makesel.
  118.  
  119. ----
  120. Modifications: (Not required reading)
  121.  
  122. This information is useless unless you intend to modify the scripts,
  123. or create programs to work along with this one. File formats are listed
  124. in the beginning of the file Sortsum.cmd
  125.  
  126. Readsum relies on ansii codes for it's keyboard input, and Screen
  127. output. The keyboard may be customized in this way. The colors may be
  128. changed in the procedure CsrAttrib()
  129.  
  130. Other files, such as those 00index.txt generated by some Ftp locations
  131. could feasibly be modified to work with this program, and provide a way
  132. of tagging files that are of interest to the operator. (If your ambitious)
  133.  
  134. Readsum reads in the GroupFil file, and uses it to seek up and down
  135. sortfil. This is how it avoids reading in the whole sortfil at once.
  136.  
  137. You may wish to assign Groupfil and Sortfil via command line arguments, data
  138. queues, environment variables, etc.. This way, several lists can exist at the 
  139. same time, sortsum could run as you are tagging articles from a differen't
  140. summary file, maksel could be processing a third summary file, etc..
  141.  
  142. The Tagged field of Groupfil is modified so that articles are
  143. saved for the next run, or for the makesel program. (See File Formats, in
  144. sortsum.cmd for information on how to use this.)
  145. ****
  146.  
  147. MakeSel:  Makesel <no arguments>
  148.  
  149. Before you can use uqwk to select the desired articles, this program
  150. must be run. The reason it is a separate program, and not run after
  151. readsum is that it takes a while to process the selected articles.
  152.  
  153. Makesel is non-interactive, so it may be detached, it also may take
  154. a while to run, depending on how large the files are.
  155.  
  156. Example: Detach Makesel
  157.  
  158. Configuration:
  159.  
  160. Configuration:
  161.  
  162.        Sortfil   Default "SortFil.tmp"  (Generated by Sortsum)
  163.        GroupFil  Default "Groups.Tmp"   (Modified by Readsum)
  164.        OutFil    Default "Selected.sel" (Generated here, Upload to uqwk)
  165.  
  166. Use your editors "Search" function to look for lines containing @CFG.
  167. Adjust the variables as needed.
  168.  
  169. The above filenames must be consistent with Sortsum and Makesel.
  170.  
  171. ----
  172. Modifications: (Not required reading)
  173.  
  174. This information is useless unless you intend to modify the scripts,
  175. or create programs to work along with this one. File formats are listed
  176. in the beginning of the file Sortsum.cmd
  177.  
  178. Makesel relies on Groupfil and Sortfil to generate a selection file.
  179. The tagged field of groupfil is used to determine which articles are tagged
  180. for offline reading.
  181.  
  182. First it reads a line from Groupfil,
  183. then it reads in all articles from sortfil, saving only those that
  184. have been tagged in memory.
  185.  
  186. After it has processed Groupfil and Sortfil, it writes Outfil using a format 
  187. that uqwk will accept.
  188.  
  189. MakeSel was written with the goal of using the OS/2's Detach command.
  190. it may safely be run in the background, (depending on your sort program)
  191.  
  192. You may wish to assign Groupfil, Sortfil and Outfil as command line arguments, 
  193. for reasons mentioned under readsum.
  194. ****
  195.  
  196. It is my hope that you will enjoy these scripts as much as I've enjoyed
  197. learning about Rexx. If you have any questions, ideas, or just want
  198. someone to yell at.. :) I can be reached at: jhoglund@cscns.com
  199.                                              70244,3234@compuserve.com
  200.  
  201. I'd appreciate knowing if this project was useful to anyone.
  202. Jamie
  203.  
  204.