home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / pas / swag / reader.doc < prev    next >
Text File  |  1994-12-02  |  19KB  |  414 lines
  1.  
  2.  
  3.                               READER.EXE v3.1
  4.                            (SWAG packet READER)
  5.                                 (c) GDSOFT
  6.                                November 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 3.0
  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 packet HEADERS in the CURRENT directory
  136. for 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. Pressing ESCAPE WILL NOT
  142. save a file at all. This process allows you to create SWAG files containing
  143. ANY combination of material that you please.
  144.  
  145. You can  ALSO search the ENTIRE  SWAG snipet buffer for  data. Just enter a
  146. tilde (~) character as the FIRST character on the search line. For instance
  147. to  find all  snipets containing  CRT, you  would enter  ~CRT 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. Beginning with  version 3.0, we added  KEYS to the SWAG  header. This makes
  156. the searching function work MUCH faster,  and you can use EDIT HEADER (CTRL
  157. [H]) function to edit these keys.
  158.  
  159. OTHER FUNCTION KEYS IN THE MAIN SCREEN
  160. --------------------------------------
  161.  
  162. ALT[R] lets you rename any of the .SWG files that you have.
  163.  
  164. [DEL] allow you to DELETE any of the .SWG files. BE CAREFUL HERE !!
  165.  
  166. [F5] toggles the  STATS function. In order for this  to work, you MUST have
  167. at least ONE .SWG file in the  directory box, and it MUST be highlighted !!
  168. Place  the cursor  any one  of the  .SWG files,  and press  F5. You will be
  169. presented with an  EXPANDED directory list showing the  description of each
  170. .SWG file and the number of snipets in each.
  171.  
  172. VIEWING, EXTRACTING, PRINTING SWAG SNIPETS
  173. ------------------------------------------
  174.  
  175. Once you have  some .SWG files in the directory  box, press <ENTER> and the
  176. package will be read and you be able to manage the SWAG snipets.
  177.  
  178. You will be  presented with a list of  all of the snipets contained  in the
  179. package with descriptions for each.
  180.  
  181. At the bottom of the screen, will be the following menu.
  182.  
  183. │                                                                          │
  184. │  F1-Help ▀     F3-Options ▀    ┘- Read  ▀    F4-Write ▀     ESC-Quit ▀  │
  185. │  ▄▄▄▄▄▄▄▄▄     ▄▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄     ▄▄▄▄▄▄▄▄▄▄  │
  186.  
  187.  
  188.                 F1   - provides some "quick" ALT keys.
  189.  
  190.                 ┌──────────── READER : HELP ───────────┐
  191.                 │ Alt F       Find Text                │
  192.                 │ Alt S       Sort Index               │
  193.                 │ Alt T       Tag ALL                  │
  194.                 │ Alt U       UnTag ALL                │
  195.                 │ Ctl S       SHELL to DOS             │
  196.                 │ Spacebar    Tag Current              │
  197.                 │ <ENTER>     Read Item                │
  198.                 │                                      │
  199.                 │ F1          Help                     │
  200.                 │ F3          Program Options          │
  201.                 │ F4          Write Tagged Items       │
  202.                 │ ESC         Quit Program             │
  203.                 └──────────────────────────────────────┘
  204.  
  205.                 F3   - brings up the OPTIONS menu.
  206.  
  207.                 ┌──────────────────────┐
  208.                 │  About               │
  209.                 │  Sort - (ALT S)      │
  210.                 │  Spacebar Tag - ON   │
  211.                 │  Colors              │
  212.                 │  Dos Shell           │
  213.                 │  Screen Lines - 25   │
  214.                 └──────────────────────┘
  215.  
  216.                 <CR> - read the snipet
  217.                 F4   - Write TAGGED items
  218.                 ESC  - Quit
  219.  
  220.  
  221. 43/50 LINE VIDEO
  222. ----------------
  223.  
  224. You will have the capability of using 43/50 line screens if you have EGA or
  225. better.  The  option  can  be  found  in  the  OPTIONS  menu  (F3).  It  is
  226. automatically  disabled if  the user  doesn't have  the capability.  Select
  227. SCREENLINES, and if you have an EGA/VGA, you'll get 43/50 line mode.
  228.  
  229. COLORS
  230. ------
  231.  
  232. To be quite  honest, the whole business of allowing  users to change colors
  233. is quite a  problem. It adds a lot  of code to the program,  and more often
  234. than not, it is used only once  by the user. Therefore, the color selection
  235. if VERY limited.
  236.  
  237. There are four  color group choices available. LIGHTGRAY,  BLUE, CYAN, RED,
  238. GREEN and MAGENTA. Select one that you find pleasing. This will be disabled
  239. on monochrome monitors.
  240.  
  241. DOS SHELL
  242. ---------
  243.  
  244. You can shell  out to DOS from within  the READER. This ability is  here on
  245. the OPTIONS  menu. You can  ALSO do  this  at ANYTIME by  using CTRL[S] key
  246. sequence.
  247.  
  248. SORTING
  249. -------
  250.  
  251. ALT S on the main selection window  brings up the SORT box. The snipets can
  252. be sorted by :
  253.  
  254.                         ┌────────────────────────────┐
  255.                         │                            │
  256.                         │  Select Sort Field :       │
  257.                         │                            │
  258.                         │         N - NUMBER         │
  259.                         │         F - FROM           │
  260.                         │         S - SUBJECT        │
  261.                         │         D - DATE           │
  262.                         │                            │
  263.                         └────────────────────────────┘
  264.  
  265.  
  266. TAGGING ITEMS
  267. -------------
  268.  
  269. Snipets can be tagged by using the SPACEBAR. SPACEBAR tag can be turned OFF
  270. in the OPTIONS menu.  ALL items can be tagged with ALT  T and untagged with
  271. ALT U. Tagged items can be written to a file with F4.
  272.  
  273.  
  274. READING SNIPETS
  275. ---------------
  276.  
  277. Pressing <ENTER> on any of the snipets  allows it to be reviewed. You'll be
  278. presented with the  "snipet" screen and you can use  the menu at the bottom
  279. of the screen :
  280.  
  281. ┌────────────────────────────────────────────────────────────────────────┐
  282. │ ▀ Next(+) ▀ preV(-) ▀ Mark ▀ Find ▀ Extract ▀ Kill ▀ Print ▀ ESC-Quit  │
  283. │ ▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄  ▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄  ▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  │
  284. └────────────────────────────────────────────────────────────────────────┘
  285.  
  286. To accommodate  many of the  QWK reader  users  out there, you  can use the
  287. PLUS(+) and  MINUS(-) keys to  display the NEXT  or PREVIOUS snipet  OR the
  288. SPACEBAR key  will display the  NEXT snipet. You  can Mark, Find,  Extract,
  289. Kill or  Print snipets. If  you have a  mouse, you can  select any of these
  290. functions by using the LEFT button on any item.
  291.  
  292.  
  293. EXTRACTING SNIPETS
  294. ------------------
  295.  
  296. Snipets can be  extract to an ASCII file by  selecting and pressing the 'E'
  297. key. Enter  the filename, and  the data  with  be written out.  If the file
  298. selected is already on  your disk, you will be asked if  you want to APPEND
  299. or OVERWRITE.
  300.  
  301. KILLING SNIPETS
  302. ---------------
  303.  
  304. Starting with version  2.9, you are able to delete  (KILL) snipets that you
  305. do not  want for some  reason. BE CAREFUL  HERE !!! Once  deleted, they are
  306. gone forever. Upon exit from the file, the entire .SWG file will be rebuilt
  307. to    eliminate    the    killed    snipet.
  308.  
  309.  
  310. EXTRA MENU - CTRL KEYS
  311. ----------------------
  312.  
  313. Pressing the CTRL key brings up the EXTRA menu :
  314.  
  315. ┌────────────────────────────────────────────────────────────────────────┐
  316. │ ▀ Next(+) ▀ preV(-) ▀ Move ▀ Copy ▀ Extract ▀ Header       ▀ ESC-Quit  │
  317. │ ▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄  ▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄         ▄▄▄▄▄▄▄▄  │
  318. └────────────────────────────────────────────────────────────────────────┘
  319.  
  320. .. The HEADER function lets you edit the CONTRIBUTOR, SUBJECT and the KEYS.
  321.  
  322. .. The MOVE  function lets  you  move  snipets to  another .SWG  file. The
  323. original snipet will deleted from the current file.
  324.  
  325. ..  The COPY function lets  you  copy  snipets to  another .SWG  file. The
  326. original snipet will remain unchanged.
  327.  
  328.  
  329. WRITING TAGGED SNIPETS
  330. ----------------------
  331.  
  332. Once you  have tagged a  group of snipets,  you can write  them to an ASCII
  333. file using F4. Enter  the filename, and if it exists, you  will be asked if
  334. you want  to APPEND or OVERWRITE.  All of the tagged  items will be written
  335. sequentially.
  336.  
  337. FINDING TEXT IN SNIPETS
  338. -----------------------
  339.  
  340. You  can  use  the  (F)ind  command  to  find  text located within the SWAG
  341. snipets. This works JUST LIKE the BORLAND  PASCAL IDE. You can ALSO use the
  342. ^Q^F  key sequence  to activate  this function.  Just as  with the  IDE, ^L
  343. displays the NEXT find.
  344.  
  345. SWAG SNIPETS MARKED WITH CHECKMARK
  346. ----------------------------------
  347.  
  348. If you  see snipets with a  CHECKMARK (#251) beside them,  this indicates a
  349. NEW item  added since the LAST  update. The READER.EXE keeps  track of this
  350. and  marks  these  automatically.  The  checkmark  is  only  there for your
  351. reference.
  352.  
  353. THE READER INI FILE
  354. -------------------
  355.  
  356. The READER  program keeps several  of its program  defaults in an  INI file
  357. (simple ASCII) in the same directory  as READER.EXE. Contained in this file
  358. are several items that you can change  to affect the way the program works.
  359. The lines in this file have the format LABEL=VALUE.
  360.  
  361. The file looks like this :
  362.  
  363.          COLOR=LIGHTGRAY       (LIGHTGRAY,BLUE,CYAN,RED,GREEN,MAGENTA)
  364.          43/50=NO              (YES or NO)
  365.          SORT=n                (nUMBER,fROM,tO,sUBJECT,cONFERENCE)
  366.          TEXTEXT=PAS           (default extension for extracted files)
  367.          EXTRACTDIR=D:\TEMP\   (default directory for extraction)
  368.          PRINTER=LPT1          (printer port [LPT1,LPT2,LPT3,LPT4])
  369.          SWAGDIR=\SWAG\FILES\  (Wherever you keep them)
  370.          SWAGADDS=YES          (Display those BBS adds at the top (YES/NO)
  371.  
  372. You can change this file using any  word processor. I think that you'll get
  373. the idea.
  374.  
  375.  
  376. COMMAND LINE USAGE
  377. ------------------
  378.  
  379. Starting with  this version of the  READER, individual SWAG packets  can be
  380. read  from  the  DOS  command  line.  Simple  type READER swagfilename. For
  381. example, you can look at all of the snipets in ANSI.SWG by typing :
  382.  
  383.                            READER ANSI.SWG <ENTER>
  384.  
  385. You don't really need to enter the  extension, as the READER will append it
  386. for you.  If the .SWG  files are not  in the current  directory READER will
  387. look for them somewhere on your current PATH.
  388.  
  389. XX3402 ENCODED FILES
  390. --------------------
  391.  
  392. Many  of the  SWAG snipets  contain code  that has  been encoded  using Guy
  393. Mcloughlin's XX3402  encoder. This has  been done due  to the necessity  to
  394. include OBJ  code in the snipet,  and this allows us  a way to do  it. What
  395. this fine  program does is to  create an ASCII encoded  file containing the
  396. BINARY data.  You need to  "CUT" these items  from the snipet,  giving it a
  397. unique name, and  decode it using XX3402. It's really  an easy thing to do.
  398. Once you cut your file out, just execute from the DOS command line :
  399.  
  400.                         XX3402 d yourfilename
  401.  
  402. Magically, the file  needed to compile the snipet will  appear !! It's just
  403. that easy. See the file included  with the SWAG distribution XX3402.ZIP for
  404. complete instructions, and  the COMPLETE SOURCE CODE to  this fine program.
  405. Thanks GUY for letting us use XX3402 for SWAG.
  406.  
  407. We  hope that  you find  the READER   easy to  use, and  the SWAG  material
  408. valuable in development of your PASCAL programs.
  409.  
  410. ENJOY !!!!! and GOOD PROGRAMMING !!!
  411.  
  412. Gayle Davis, Kerry Sokalsky and Jeff Fanjoy
  413. SWAG Support Team
  414.