home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 16 / CD_ASCQ_16_0994.iso / maj / swag / reader.doc < prev    next >
Text File  |  1994-08-26  |  18KB  |  384 lines
  1.  
  2.  
  3.                               READER.EXE v2.9
  4.                            (SWAG packet READER)
  5.                                 (c) GDSOFT
  6.                                 August 1994
  7.  
  8. INTRODUCTION
  9. ------------
  10.  
  11. SWAG (SourceWare Archival Group) is a collection of source code and program
  12. examples for the PASCAL programming language. The material has been donated
  13. by  various  PASCAL  programmers  from  around  the  world,  who  desire to
  14. contribute to the advancement of  one of the greatest programming languages
  15. there is.  MANY THANKS to all  who have contributed. As  such, NO CHARGE OF
  16. ANY KIND IS PERMITTED FOR THIS WORK.
  17.  
  18. The material has been collected from various network conferences worldwide,
  19. and organized  according to subject.  New material is  added quarterly, and
  20. new SWAG  packets are available  from various BBS  sources on a  FIRST call
  21. basis. See BBS.TXT for current support sites and how your BBS can join.
  22.  
  23. GETTING STARTED
  24. ----------------
  25.  
  26. The program READER.EXE is a executable program that will allow you to read,
  27. extract or print the contents of  SWAG packets. These packets are organized
  28. according to subject, with each one containing a number of PASCAL "snipets"
  29. on that subject. In the rest of this document, I'll refer to the program as
  30. "READER".
  31.  
  32. The SWAG packets should be placed ALL together in a directory on your disk.
  33. It is recommended that you create a single directory named '\SWAG'. You can
  34. use the DOS command :
  35.  
  36.                             mkdir c:\swag
  37.  
  38. Unpack  the distribution  archives and  place  all  of the  files with  the
  39. extension of "*.SWG" in this directory along with READER.EXE.
  40.  
  41. USING THE READER
  42. ----------------
  43.  
  44. Using the  reader is really very  simple. Just execute it,  and you will be
  45. presented with a  directory of all of the .SWG  files in the directory that
  46. READER is located in. If you have .SWG files elsewhere on your disk, or for
  47. that matter, any disk on your system,  you can move around the disk to find
  48. them  by  selecting  the  ".."  file  which  will  take  you  to the PARENT
  49. directory. Use the HOME, END and the arrow keys to maneuver around.
  50.  
  51. ALSO,
  52.  
  53. The directory window  is search key sensitive. This means  that if you have
  54. .SWG files  or directories listed in  the directory box, you  can just type
  55. the name of the file you want.  For example, pressing 'A' will place you at
  56. the first  entry starting with  'A'. Press 'N',  and you will  jump the the
  57. entry with 'AN...'  if you have one. If  NOT, you will jump the  first file
  58. starting with the letter 'N'.
  59.  
  60. At the bottom  of the screen you will notice  a menu indicating some cursor
  61. and function keys :
  62.  
  63.                         F2 - GREP
  64.                         F5 - Toggle STATS
  65.  
  66.                         <ENTER> - GO
  67.                         ESC - QUIT
  68.  
  69. F2 calls  the GREP (search)  function. This is  a VERY POWERFUL  and useful
  70. function, but  in order to  use this function,  you MUST have  at least ONE
  71. .SWG file  in the directory  box, and it  MUST be highlighted  !! Place the
  72. cursor any one of the .SWG files,  and press F2. You will be presented with
  73. a prompt window :
  74.  
  75.                         SWAG Message Base Reader 2.8
  76. ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  77. ▓▓┌ D:\SWAG\FILES\ ▓▓┌──────────── SOURCEWARE ARCHIVAL GROUP ───────────┐▓▓
  78. ▓▓│ [A:\]          │▓▓│                                                  │▓▓
  79. ▓▓│ [B:\]          ▓▓▓│ Your SWAG Support Team :                         │▓▓
  80. ▓▓│ [C:\]          │▓▓│                                                  │▓▓
  81. ▓▓│ [E:\]          │▓▓│ Gayle Davis  Goshen, Indiana  46526              │▓▓
  82. ▓▓│ ..\            │▓▓│ Kerry Sokalsky  North York, Ontario  M2P 1L2     │▓▓
  83. ▓▓│ ANSI.SWG       │▓▓│                                                  │▓▓
  84. ▓▓│ ARCHIVES.SWG   │▓▓│ About SWAG :                                     │▓▓
  85. ▓▓│ CHARS.SWG      │▓▓│                                                  │▓▓
  86. ▓▓│ CMDLINE.SWG    │▓▓│ SWAG is a collection of source code and program  │▓▓
  87. ▓▓│ COLOR.SWG      │▓▓│ examples for the PASCAL program language.   The  │▓▓
  88. ▓▓│ COM┌────────────────────── GREP SWAG Files ───────────────────────┐L │▓▓
  89. ▓▓│ COP│  Search For: CURSOR&CRT|ANSI&FILE                            │n │▓▓
  90. ▓▓│ CRC└──────────────────────────────────────────────────────────────┘t │▓▓
  91. ▓▓│ CRT.SWG        │▓▓│ programming platforms available today.           │▓▓
  92. ▓▓│ CURSOR.SWG     │▓▓│                                                  │▓▓
  93. ▓▓│ DATATYPE.SWG   │▓▓│ MUCH THANKS AND GRATITUDE TO ALL CONTRIBUTORS !! │▓▓
  94. ▓▓│ DATETIME.SWG   │▓▓│ NO Charge of ANY kind is permitted for this work │▓▓
  95. ▓▓└────────────────▓▓│                                                  │▓▓
  96. ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓└──────────────────────────────────────────────────┘▓▓
  97. ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  98.  
  99. Enter a string  to search for. You may search  for a multiple occurrence of
  100. substrings using  BOOLEAN operators AND (&)  OR (|). For example,  a search
  101. for  THIS&THAT|THEM&THOSE would  return  all  snipets containing  both ORed
  102. phrases THIS&THAT OR THEM&THOSE.
  103.  
  104. In BOOLEAN Algebra, the AND operator  takes precedence over the OR operator
  105. (except  when  using  parentheses).  This  is  NOT  the  case with the GREP
  106. function. You  can use the PARENTHESES  () to dictate which  portion of the
  107. search string is  to be processed first. If  multiple levels of parentheses
  108. are used,  the order is RIGHT  to LEFT, starting with  the innermost set of
  109. parentheses, wherever they occur.
  110.  
  111. As an example, in the phrase ((this|that)&(them&those)), (them&those) would
  112. be processed  before (this|that)) innermost  to outermost. In  other words,
  113. all snipets  will be returned  containing THIS or  THAT AND they  also will
  114. contain (THEM and THOSE).
  115.  
  116. Within a set  of parentheses, order will be left  to right. Construction of
  117. the search string itself requires combining the desired substrings together
  118. with  the desired  BOOLEAN operators.  Without the  parentheses, the search
  119. string will be processed logically. THIS|THAT&THEM&THOSE will return all of
  120. the snipets  that contain THIS  plus the  ones  that contain THAT  & THEM &
  121. THOSE. You can  see that this is totally different  than what you'll get by
  122. using the parentheses.
  123.  
  124. Additionally, you can also include a  date in the format MM/DD/YY, and ONLY
  125. records AFTER this  date will be included. If you  enter JUST the date, ALL
  126. SWAG  snipets  AFTER  this  date  will  be  included. For example, entering
  127. CURSOR|ANSI&CRT|05/08/93  would search  the  SWAG  packets for  matches for
  128. CURSOR OR (ANSI  AND CRT) occurring AFTER 05/08/93.  Entering JUST 05/08/93
  129. at the prompt would bring back ALL snipets AFTER 05/08/93 REGARDLESS of the
  130. subject.
  131.  
  132. Enter  an empty  string as  the search  string, and  READER will return all
  133. snipets since the LAST SWAG release.
  134.  
  135. READER will  search ALL of  the SWAG packets  in the CURRENT  directory for
  136. matches  based on  your criteria.  A processing  box will  appear, and  all
  137. occurrences of your  search string(s) or date matches will  be written to a
  138. NEW SWAG file.  Initially, this file is named GREPSWAG.SWG,  and will be in
  139. the current  directory. Upon completion of  this GREP process, you  will be
  140. asked for the  file name. Enter any name AND  directory you choose, and the
  141. file will be  RENAMED and moved to that directory.  This process allows you
  142. to  create  SWAG  files  containing  ANY  combination  of material that you
  143. please.
  144.  
  145. You can ALSO search JUST the HEADER  of the SWAG snipet. Just enter a tilde
  146. (~) character  as the FIRST character  on the search line.  For instance to
  147. find all snipets by GAYLE DAVIS, you would enter ~GAYLE DAVIS on the search
  148. line. ONLY  the header of snipets  is searched for matches.  This a way you
  149. can look at all snipets by a certain contributor. You can also use multiple
  150. search criteria  here. For instance,  ~GAYLE DAVIS|GUY MCLOUGHLIN|JOE  BLOW
  151. would bring back  everything for each of these  persons. This search method
  152. is VERY fast as on the headers have  to be read. By the way, the same rules
  153. about AND/OR searching apply when search just the headers.
  154.  
  155. F5 toggles the STATS function. In order  for this to work, you MUST have at
  156. least ONE  .SWG file in  the directory box,  and it MUST  be highlighted !!
  157. Place  the cursor  any one  of the  .SWG files,  and press  F5. You will be
  158. presented with an  EXPANDED directory list showing the  description of each
  159. .SWG file and the number of snipets in each.
  160.  
  161. VIEWING, EXTRACTING, PRINTING SWAG SNIPETS
  162. ------------------------------------------
  163.  
  164. Once you have  some .SWG files in the directory  box, press <ENTER> and the
  165. package will be read and you be able to manage the SWAG snipets.
  166.  
  167. You will be  presented with a list of  all of the snipets contained  in the
  168. package with descriptions for each.
  169.  
  170. At the bottom of the screen, will be the following menu.
  171.  
  172. │                                                                          │
  173. │  F1-Help ▀     F3-Options ▀    ┘- Read  ▀    F4-Write ▀     ESC-Quit ▀  │
  174. │  ▄▄▄▄▄▄▄▄▄     ▄▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄     ▄▄▄▄▄▄▄▄▄▄  │
  175.  
  176.  
  177.                 F1   - provides some "quick" ALT keys.
  178.  
  179.                 ┌──────────── READER : HELP ───────────┐
  180.                 │ Alt F       Find Text                │
  181.                 │ Alt S       Sort Index               │
  182.                 │ Alt T       Tag ALL                  │
  183.                 │ Alt U       UnTag ALL                │
  184.                 │ Ctl S       SHELL to DOS             │
  185.                 │ Spacebar    Tag Current              │
  186.                 │ <ENTER>     Read Item                │
  187.                 │                                      │
  188.                 │ F1          Help                     │
  189.                 │ F3          Program Options          │
  190.                 │ F4          Write Tagged Items       │
  191.                 │ ESC         Quit Program             │
  192.                 └──────────────────────────────────────┘
  193.  
  194.                 F3   - brings up the OPTIONS menu.
  195.  
  196.                 ┌──────────────────────┐
  197.                 │  About               │
  198.                 │  Sort - (ALT S)      │
  199.                 │  Spacebar Tag - ON   │
  200.                 │  Colors              │
  201.                 │  Dos Shell           │
  202.                 │  Screen Lines - 25   │
  203.                 └──────────────────────┘
  204.  
  205.                 <CR> - read the snipet
  206.                 F4   - Write TAGGED items
  207.                 ESC  - Quit
  208.  
  209.  
  210. 43/50 LINE VIDEO
  211. ----------------
  212.  
  213. You will have the capability of using 43/50 line screens if you have EGA or
  214. better.  The  option  can  be  found  in  the  OPTIONS  menu  (F3).  It  is
  215. automatically  disabled if  the user  doesn't have  the capability.  Select
  216. SCREENLINES, and if you have an EGA/VGA, you'll get 43/50 line mode.
  217.  
  218. COLORS
  219. ------
  220.  
  221. To be quite  honest, the whole business of allowing  users to change colors
  222. is quite a  problem. It adds a lot  of code to the program,  and more often
  223. than not, it is used only once  by the user. Therefore, the color selection
  224. if VERY limited.
  225.  
  226. There are four  color group choices available. LIGHTGRAY,  BLUE, CYAN, RED,
  227. GREEN and MAGENTA. Select one that you find pleasing. This will be disabled
  228. on monochrome monitors.
  229.  
  230. DOS SHELL
  231. ---------
  232.  
  233. You can shell  out to DOS from within  the READER. This ability is  here on
  234. the OPTIONS  menu. You can  ALSO do  this  at ANYTIME by  using CTRL[S] key
  235. sequence.
  236.  
  237. SORTING
  238. -------
  239.  
  240. ALT S on the main selection window  brings up the SORT box. The snipets can
  241. be sorted by :
  242.  
  243.                         ┌────────────────────────────┐
  244.                         │                            │
  245.                         │  Select Sort Field :       │
  246.                         │                            │
  247.                         │         C - CONFERENCE     │
  248.                         │         N - NUMBER         │
  249.                         │         T - TO             │
  250.                         │         F - FROM           │
  251.                         │         S - SUBJECT        │
  252.                         │                            │
  253.                         └────────────────────────────┘
  254.  
  255.  
  256. TAGGING ITEMS
  257. -------------
  258.  
  259. Snipets can be tagged by using the SPACEBAR. SPACEBAR tag can be turned OFF
  260. in the OPTIONS menu.  ALL items can be tagged with ALT  T and untagged with
  261. ALT U. Tagged items can be written to a file with F4.
  262.  
  263.  
  264. READING SNIPETS
  265. ---------------
  266.  
  267. Pressing <ENTER> on any of the snipets  allows it to be reviewed. You'll be
  268. presented with the  "snipet" screen and you can use  the menu at the bottom
  269. of the screen :
  270.  
  271. ┌────────────────────────────────────────────────────────────────────────┐
  272. │ ▀ Next(+) ▀ preV(-) ▀ Mark ▀ Find ▀ Extract ▀ Kill ▀ Print ▀ ESC-Quit  │
  273. │ ▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄  ▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄  ▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  │
  274. └────────────────────────────────────────────────────────────────────────┘
  275.  
  276. To accommodate  many of the  QWK reader  users  out there, you  can use the
  277. PLUS(+) and  MINUS(-) keys to  display the NEXT  or PREVIOUS snipet  OR the
  278. SPACEBAR key  will display the  NEXT snipet. You  can Mark, Find,  Extract,
  279. Kill or  Print snipets. If  you have a  mouse, you can  select any of these
  280. functions by using the LEFT button on any item.
  281.  
  282.  
  283. EXTRACTING SNIPETS
  284. ------------------
  285.  
  286. Snipets can be  extract to an ASCII file by  selecting and pressing the 'E'
  287. key. Enter  the filename, and  the data  with  be written out.  If the file
  288. selected is already on  your disk, you will be asked if  you want to APPEND
  289. or OVERWRITE.
  290.  
  291. KILLING SNIPETS
  292. ---------------
  293.  
  294. Starting with version  2.9, you are able to delete  (KILL) snipets that you
  295. do not  want for some  reason. BE CAREFUL  HERE !!! Once  deleted, they are
  296. gone forever. Upon exit from the file, the entire .SWG file will be rebuilt
  297. to    eliminate    the    killed    snipet.
  298.  
  299. WRITING TAGGED SNIPETS
  300. ----------------------
  301.  
  302. Once you  have tagged a  group of snipets,  you can write  them to an ASCII
  303. file using F4. Enter  the filename, and if it exists, you  will be asked if
  304. you want  to APPEND or OVERWRITE.  All of the tagged  items will be written
  305. sequentially.
  306.  
  307. FINDING TEXT IN SNIPETS
  308. -----------------------
  309.  
  310. You  can  use  the  (F)ind  command  to  find  text located within the SWAG
  311. snipets. This works JUST LIKE the BORLAND  PASCAL IDE. You can ALSO use the
  312. ^Q^F  key sequence  to activate  this function.  Just as  with the  IDE, ^L
  313. displays the NEXT find.
  314.  
  315. SWAG SNIPETS MARKED WITH CHECKMARK
  316. ----------------------------------
  317.  
  318. If you  see snipets with a  CHECKMARK (#251) beside them,  this indicates a
  319. NEW item  added since the LAST  update. The READER.EXE keeps  track of this
  320. and  marks  these  automatically.  The  checkmark  is  only  there for your
  321. reference.
  322.  
  323. THE READER INI FILE
  324. -------------------
  325.  
  326. The READER  program keeps several  of its program  defaults in an  INI file
  327. (simple ASCII) in the same directory  as READER.EXE. Contained in this file
  328. are several items that you can change  to affect the way the program works.
  329. The lines in this file have the format LABEL=VALUE.
  330.  
  331. The file looks like this :
  332.  
  333.          COLOR=LIGHTGRAY       (LIGHTGRAY,BLUE,CYAN,RED,GREEN,MAGENTA)
  334.          43/50=NO              (YES or NO)
  335.          SORT=n                (nUMBER,fROM,tO,sUBJECT,cONFERENCE)
  336.          TEXTEXT=PAS           (default extension for extracted files)
  337.          EXTRACTDIR=D:\TEMP\   (default directory for extraction)
  338.          PRINTER=LPT1          (printer port [LPT1,LPT2,LPT3,LPT4])
  339.          SWAGDIR=\SWAG\FILES\  (Wherever you keep them)
  340.          SWAGADDS=YES          (Display those BBS adds at the top (YES/NO)
  341.  
  342. You can change this file using any  word processor. I think that you'll get
  343. the idea.
  344.  
  345.  
  346. COMMAND LINE USAGE
  347. ------------------
  348.  
  349. Starting with  this version of the  READER, individual SWAG packets  can be
  350. read  from  the  DOS  command  line.  Simple  type READER swagfilename. For
  351. example, you can look at all of the snipets in ANSI.SWG by typing :
  352.  
  353.                            READER ANSI.SWG <ENTER>
  354.  
  355. You don't really need to enter the  extension, as the READER will append it
  356. for you.  If the .SWG  files are not  in the current  directory READER will
  357. look for them somewhere on your current PATH.
  358.  
  359. XX3402 ENCODED FILES
  360. --------------------
  361.  
  362. Many  of the  SWAG snipets  contain code  that has  been encoded  using Guy
  363. Mcloughlin's XX3402  encoder. This has  been done due  to the necessity  to
  364. include OBJ  code in the snipet,  and this allows us  a way to do  it. What
  365. this fine  program does is to  create an ASCII encoded  file containing the
  366. BINARY data.  You need to  "CUT" these items  from the snipet,  giving it a
  367. unique name, and  decode it using XX3402. It's really  an easy thing to do.
  368. Once you cut your file out, just execute from the DOS command line :
  369.  
  370.                         XX3402 d yourfilename
  371.  
  372. Magically, the file  needed to compile the snipet will  appear !! It's just
  373. that easy. See the file included  with the SWAG distribution XX3402.ZIP for
  374. complete instructions, and  the COMPLETE SOURCE CODE to  this fine program.
  375. Thanks GUY for letting us use XX3402 for SWAG.
  376.  
  377. We  hope that  you find  the READER   easy to  use, and  the SWAG  material
  378. valuable in development of your PASCAL programs.
  379.  
  380. ENJOY !!!!! and GOOD PROGRAMMING !!!
  381.  
  382. Gayle Davis, Kerry Sokalsky and Jeff Fanjoy
  383. SWAG Support Team
  384.