home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / ytsg4.zip / ytsg.doc < prev    next >
Text File  |  1998-01-21  |  11KB  |  287 lines
  1.  
  2. Preramble:
  3.  
  4.   Much of this program has changed from the original version:
  5.  
  6.      - Now handles version .9x Yarn news files.
  7.      - Actual regular expressions have been added.
  8.      - Search capabilities have been greatly enhanced.
  9.      - HTML output has been added.
  10.      - Wildcards in the filenames should make it much easier to use.
  11.      - Output is now sorted by the date field in the header.
  12.      - Some parts have been sped up a lot (although I found a big
  13.        slowdown during testing when many input files must be sorted).
  14.      - Dos version has been dropped.
  15.  
  16.   I am hoping that the HTML/cgi-bin capabilities will be useful.  PLEASE
  17.   let me know if you would like me to pursue this!
  18.  
  19.                                                   - Rick Curry
  20.                                                     Wed  98-01-21
  21.  
  22.  
  23.                            YTSG version 4.01
  24.  
  25. ytsg - Convert Yarn files to SOUP offline reader format using grep
  26.          syntax to select messages.
  27.  
  28. Copyright (C) 1998, Richard Curry Consulting: trindflo@fishnet.net All
  29. Rights Reserved
  30.  
  31. Parts of this software were copied from source code made available as
  32. part of IBM's Developer's Connection.  IBM copyright information has been
  33. retained in the source.
  34.  
  35. This program is distributed in the hope that it will be useful, but
  36. WITHOUT ANY WARRANTY; without even the implied warranty of
  37. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  38.  
  39. SUMMARY:
  40.  
  41.    This file contains the code to translate/copy Yarn news files into
  42.    soup offline reader format.  This was initially is intended to allow
  43.    cleanup of a corrupted Yarn newsbase.
  44.  
  45.  
  46. Usage:
  47.     ytsg [-{BFHNPSW}[{\:!}]str] [-D{SE}date] [-{GL}n] [-{QUX}] [-Oh] File[s]
  48.  
  49. Flags:
  50.     -{BFHNPSW}:str -
  51.      Specify one or multiples of these switches to search the Body,
  52.      From, Header, Newsgroups, Path, Subject or Whole message for the
  53.      string 'str' and disqualify a message which fails to match any one
  54.      of the strings specified.
  55.  
  56.      If none of these strings is specified, then all messages will
  57.      selected.
  58.  
  59.      'str' may start with \, :, and/or ! (order is important).
  60.      \ causes case insensitive matching.
  61.      : causes str to be interpreted as a unix style regular expression.
  62.      If not using a unix regular expression, ! can be used to negate the
  63.      search (the search will match the absence of 'str').
  64.  
  65.      Multiple search criteria are allowed, but only one per field (one
  66.      subject search, one body search, etc.)
  67.  
  68.      An example of a search of the subject using regular expressions:
  69.           -s\:[[(][0-9]+/[0-9]+[)]]
  70.  
  71.     -D{SE}: Dates (start/end) to include.  You may specify one or both
  72.      to restrict the search.  The format is rigid: YYYYMMDD e.g.
  73.      -DS:19970225.  All 4 digits of the year must be specified.  There
  74.      is one alternate form (suggested by Tim Middleton) of a number of
  75.      days previous to today: e.g. -DS-5 would restrict the search to
  76.      exclude all messages with an internal date stamp more than 5 days
  77.      earlier than today.
  78.  
  79.     -Gn Messages containing more than 'n' bytes are disqualified.
  80.  
  81.     -L Logging threshold.  Errors and informational messages are logged
  82.      to the file 'ytsg.log'.  A smaller number logs less information.
  83.      Any number can be specified, but a value greater than 600 does not
  84.      create any more logging (and produces a lot of text).  When the log
  85.      level is 500 or more the index file is not deleted at the end of
  86.      the run and it remains in your %TMP% directory.  The default is 300
  87.      and equates to warning level messages.  400=Informational,
  88.      500=Debug, and 600=Noise.
  89.  
  90.     -Oh Output links in html to message location for later retrieval.
  91.      This will generate output which can be used from a WEB browser to
  92.      read messages.  This feature allows you to create a custom Yarn
  93.      newsbase and share it over the WEB.
  94.  
  95.     -Q Silence as much of the work messages as possible.  Normally a dot
  96.      (.) prints for each message which matches.  This options will
  97.      remove this output and some other "warm fuzzy" messages designed to
  98.      let the user know that work is actually being done.
  99.  
  100.     -U Scan "unused" (deleted) messages as well.  Only applies to
  101.      version .9x Yarn news files.  Ytsg can not detect if a message has
  102.      been deleted in earlier versions of Yarn.
  103.  
  104.     -X Show the hex offset of each selected message.  Generally this is
  105.      useful for diagnostics.
  106.  
  107.  
  108. Notes:
  109.  
  110.      Switches are not case sensitive ( i.e. -DS: = -dS: ).
  111.  
  112.      The default search is case sensitive: it is faster.
  113.  
  114.      The date algorithm is fairly simple and when it gets confused it
  115.      allows the date.
  116.  
  117.      Usually a space can separate the switch letter and it's associated
  118.      value.
  119.  
  120.      A value is required for all switches which accept a value: if you
  121.      specify the switch, plug in the value.
  122.  
  123.      A search of the 'Path' field will match either Path: or Return-Path:.
  124.  
  125.      STDIN not allowed as an input source.  This is to allow for ytsg to
  126.      operate as a cgi-bin.
  127.  
  128.      File[s] can be a mixture of .8x or .9x Yarn files.
  129.  
  130.      Wildcards may used in specifying File[s].
  131.  
  132.  
  133. The ytsg command searches the specified input file(s) for news or mail
  134. messages which match your specified pattern(s).
  135.  
  136. The ytsg command outputs message(s) which match your criteria to either
  137. soup formatted files, or as HTML summary information.  The patterns that
  138. you specify must exist within the first 64K bytes of the article.
  139.  
  140. If you are outputting the information as soup, the string 'Newsgroups:'
  141. is searched for.  This line is searched for strings which already exist
  142. in your newsrc file (these are newsgroups that you are already reading).
  143. If no Newsgroups string is found, the message is formatted into email
  144. format. If no string in your newsrc file matches the Newsgroups string,
  145. then the message is identified as belonging to the first group named in
  146. the Newsgroups line.  This search will recognize and ignore the
  147. 'X-Newsgroups' line added by Yarn version .85.
  148.  
  149. In order to create newsgroups properly, ytsg needs to know where your
  150. newsrc file is located.  It uses the 'HOME' variable to find this file.
  151. If this variable is not set and you are requesting soup output, ytsg
  152. will complain and terminate.
  153.  
  154. In order to avoid corruption of existing soup files, if the file 'AREAS'
  155. exists in the current directory ytsg will complain and terminate.
  156.  
  157.  
  158.  
  159. SETUP:
  160.  
  161. With thanks to several Yarn users who have BETA tested and suggested
  162. improvements for this software.
  163.  
  164. You need to have your HOME environment variable set.  The program uses
  165. this to locate your newsrc file.
  166.  
  167. You need to have a newsrc file.  It can be an empty file, but you should
  168. probably use the one you had.  I use the the newsrc file to group the
  169. messages into groups that you probably want to see.  If I don't know
  170. which what groups you use, I just go with the first thing on the
  171. Newsgroups line of the message.  So you will end up seeing strange
  172. newsgroups which you never subscribed to appear in Yarn because of
  173. cross-posting.  I don't use any of the numeric information in the newsrc
  174. file, but I do pay attention to the ':' and '!' marks.
  175.  
  176. Certain errors will crash ytsg after the AREAS file has already been
  177. created.  As a safety mechanism, ytsg will always terminate if an AREAS
  178. file already exists in the directory.  If the AREAS file resulted from a
  179. a crashed or terminated run, just delete the AREAS file.
  180.  
  181. Ytsg is now using a B+ index which it places in the directory specified
  182. in your %TMP% environment variable (I think this is the current
  183. directory if you do not set TMP).  This file can get quite large (on the
  184. order of 7% the size of the input files which are being analyzed).  If
  185. Ytsg crashes for any reason, you should make sure that files like *.CTN
  186. in your TMP directory are deleted (Actually ytsg is not the only program
  187. which might leave garbage in this directory!)  Ytsg intentionally leaves
  188. this file if you set the log level to 500 or greater with the '-l'
  189. switch.
  190.  
  191.  
  192. USES:
  193.  
  194. As stated earlier, this program was initially intended to allow cleanup
  195. of a corrupted Yarn newsbase.  All of the files in the %YARN%\news
  196. directories are converted back into SOUP files and the whole lot is
  197. imported into a fresh copy of Yarn.  The 'Grep' or search capability was
  198. later added and allows limited filtering of a newsbase: this has been
  199. used to manipulate pseudo-newsgroups created with the "newgroup" command
  200. for email filtering.
  201.  
  202. INBOX and folder files can also be processed by ytsg with a warning:
  203. they will go back to whatever groups they originated from.  This means a
  204. message in a folder which originally was part of a newsgroup will be
  205. imported into that newsgroup.  A message without a Newsgroups: line will
  206. be imported into email -- this includes email messages 'filtered' by
  207. Yarn into pseudo-newsgroups even if the message contains a X-Newsgroups:
  208. line.
  209.  
  210.  
  211. EXAMPLES:
  212.  
  213.      Full rebuild:
  214.  
  215. This software is fully tested and nothing can go wrong.  So first we
  216. make a copy...
  217.  
  218. SET YARN=H:\OLDYARN
  219. SET HOME=H:\OLDYARN\RRC
  220.  
  221. Change to a drive/directory which is convenient to hold the output of
  222. ytsg.  The output will be about the same size as the files you are
  223. reading.  David Meade tells me that during testing of ytsg, he
  224. experienced a noticeable improvement in speed by running ytsg on a
  225. different physical drive than the one he was reading from.
  226.  
  227. Rem The following represents where the old style, .8x Yarn news files live.
  228. ytsg %YARN%\news\*
  229.  
  230. Rem The following represents where the new style, .9x Yarn news file lives.
  231. ytsg %YARN%\news.dat
  232.  
  233.  
  234. SET YARN=H:\newYARN
  235. SET HOME=H:\newYARN\RRC
  236.  
  237. clearall
  238.  
  239. makegps
  240.  
  241. import -u (pathname of the directory where you ran ytsg)
  242.  
  243.  
  244. - Finis -
  245.  
  246.  
  247.      Refilter INBOX:
  248.  
  249. SET YARN=H:\YARN
  250. SET HOME=H:\YARN\RRC
  251.  
  252. cd %HOME%\mail
  253. copy INBOX INBOX.sav
  254. ytsg INBOX
  255. cd %YARN%
  256. import -u %HOME%\mail
  257.  
  258. - Finis -
  259.  
  260.  
  261.  
  262. -Begin clearall.cmd (I think this works for version .9x) ----------------------
  263. cd %YARN%
  264. del history.*
  265. del supersed.*
  266. del active
  267. del overview
  268. del news
  269. del news.dat
  270.  
  271. cd %HOME%\yarn
  272. del readart.*
  273. del newsrc
  274. del scores\saved
  275. -End -- Cut -------------------------------------------------------------------
  276.  
  277. -Begin makegps.cmd (only a small excerpt.  mine has over 200 lines.) ----------
  278. newgroup junk 14
  279. newgroup list.yarn 9999 9999 yarn-list@lists.colorado.edu
  280. newgroup rain.local.general 9999
  281. newgroup rain.local.rain-l 9999
  282. newgroup rain.local.help 9999
  283. newgroup tri.politics 9999
  284. newgroup tri.politics.sb 9999
  285. -End -- Cut -------------------------------------------------------------------
  286.  
  287.