home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / internet / rnfilters / ReadMe < prev    next >
Encoding:
Text File  |  1993-12-29  |  12.0 KB  |  302 lines
  1. The contents of this archive allow ReadNews to be used to read and write ka9q
  2. mail and news.  Note that it requires that !ReadNews, !NewsDir, !Incorp *and*
  3. !Rucp to be seen by the filer, as well as !TCPIP and !MailDir (you no longer
  4. need !BM, but it is sometimes useful to have it around).  It works with all
  5. versions of ka9q at the time of writing, including 1.21 (all three variants),
  6. 1.22 and 1.23 (and should work with 1.24 when it appears).
  7.  
  8. These programs were primarily written to provide `proof of concept' so I
  9. could ask Julian Wright to support ka9q directly.  Julian has agreed to
  10. do this in a future release of ReadNews (which may be some time coming as
  11. the next release is going to have a lot of yummy new features).
  12.  
  13. Version 4, 29-Dec-1993.  Ka9q->rucp version 0.6, rucp->ka9q version 0.8.
  14.  
  15. This file and the BASIC programs ka9q->rucp and rucp->ka9q are © copyright
  16. Paul L. Allen, 1993, all rights reserved.
  17.  
  18.  
  19. Obtaining
  20. ==========
  21.  
  22. !ReadNews, !NewsDir and !Incorp are the component parts of a package known
  23. as ReadNews.  Both the ReadNews package and !Rucp are available for ftp from
  24. ftp.demon.co.uk in /pub/archimedes, or may be obtained from the Newcastle
  25. info-server.  You don't need *all* of !Rucp, just certain bits, but I'm not
  26. sure *which* bits are necessary and which aren't...
  27.  
  28.  
  29. Installation
  30. ============
  31.  
  32. Copy the basic programs to somewhere handy (the same folder as !TCPIP,
  33. !MailDir, and !Rucp is as good as any).
  34.  
  35. In the following discussion, we will use the following names as examples -
  36. adjust them as necessary:
  37.  
  38.     1) Your machine name is `bar'.
  39.  
  40.     2) Your preferred user name (the one which receives most email) is `foo'.
  41.  
  42.     3) The address of your service provider is `demon.co.uk'.
  43.  
  44.     4) Your site name is therefore bar.demon.co.uk and the full mail
  45.        address for your preferred user name is foo@bar.demon.co.uk.
  46.  
  47.     5) Your mail server (the machine you send mail to) is
  48.        post.demon.co.uk (previously gate.demon.co.uk was used for this
  49.        purpose, you should now be using post.demon.co.uk).
  50.  
  51.     6) Your news server is news.demon.co.uk.
  52.  
  53.     7) You want news to be kicked every 1800 seconds (30 mins).
  54.  
  55.     8) The news-prefix is `Dem', so that the list of newsgroups you
  56.        want to receive is in !TCPIP.DemGroup and news appears in file
  57.        !MailDir.DemNews.  Note that the news prefix must be no longer than
  58.        4 characters, but it may be anything you want (provided the result
  59.        is a valid filename).
  60.  
  61.  
  62. In your !TCPIP.Autoexec file, make sure you have the following entries:
  63.  
  64.    hostname bar.demon.co.uk
  65.  
  66.    domain suffix demon.co.uk
  67.  
  68.    nntp addserver news.demon.co.uk 1800 Dem
  69.  
  70.  
  71. In your !Rucp.SystemRC file, make sure you have the following entries:
  72.  
  73.    NewsDir=<Rucp$Dir>.uucp.news
  74.    MailServ=post
  75.  
  76. Actually, it doesn't really matter what you call the MailServ as long as
  77. it's a valid leafname and it is anything *other than* `news'.  You can quite
  78. happily use the default values supplied for all other entries.
  79.  
  80.  
  81. In your !Rucp.!Boot file, make sure you have the following entries:
  82.  
  83.     Set Rucp$Nodename bar
  84.  
  85.     Set Rucp$Domain bar.demon.co.uk
  86.  
  87.     Set Rucp$User foo
  88.  
  89.  
  90. In your !Rucp.Systems file, make sure you have the following entries:
  91.  
  92.     news Any Dir 2400 g "" AT OK ATDP24846 ogin:--ogin: nvmr sword: HiThere
  93.     post Any Dir 2400 g "" AT OK ATDP24846 ogin:--ogin: nvmr sword: HiThere
  94.  
  95. Actually, only the `news' and `post' part are critical - the rest can be
  96. anything acceptable to Rucp (but this is what you get if you modify the
  97. example given in the Systems file).
  98.  
  99.  
  100. In your !Rucp.UserHome folder, set up a folder for user foo containing
  101. the following files (modify the examples which come with !Rucp):
  102.  
  103.     Aliases    a list of commonly-used email addresses - these appear in
  104.                a menu when you click over an address field in ReadNews.
  105.  
  106.     Signature  The signature you want appended to your postings (ReadNews
  107.                ignores the alternate AltSig file - pity).
  108.  
  109.     RC         User configuration file.  Needs at least:
  110.  
  111.                    Mailbox=foo
  112.                    Name=Your Full Name
  113.                    Home=<Rucp$UserHome>.foo
  114.                    FileSent=Sent
  115.                    Signature=Signature
  116.                    Altsignature=AltSig
  117.                    Aliases=<Rucp$UserHome>.foo.Aliases
  118.  
  119.                With optional Organisation and Replyto entries.  Use the rest
  120.                of the defaults as given in the example.  Note that you can
  121.                setup other users (such as postmaster) in the same way but
  122.                sharing your default users alias file and/or signature and/or
  123.                whatever - you can do all sorts of fun things.
  124.  
  125.  
  126. For each user on your system whom you wish to receive mail (at least the
  127. user referred to by Rucp$User and `postmaster', create an entry in
  128. !Rucp.Passwd of the form
  129.  
  130.     <user>:*:::<descriptive name>
  131.  
  132. e.g.:
  133.  
  134.     foo:*:::test user
  135.  
  136. Mail for users not listed in the Passwd file will be sent to `postmaster'
  137. instead.
  138.  
  139.  
  140. This should basically be it (unless I've forgotten something).  I do recall
  141. that at some stage when I was getting all this working I had to create
  142. a folder manually in the !Rucp.uucp... area - can't quite remember what, and
  143. I'm not sure if it was just teething problems.  Please let me know if you
  144. have similar problems, or if there's something I've omitted.
  145.  
  146.  
  147. Usage
  148. =====
  149.  
  150. To transfer incoming news/mail from ka9q to rucp, double-click on ka9q->rucp.
  151. You can run ka9q->rucp whilst connected to Demon, and you can even run it
  152. whilst e-mail and/or news is coming in without losing anything (though you
  153. will get a warning message if ka9q has the relevant files locked - just run
  154. ka9q->rucp again).  After ka9q->rucp has completed, run !Incorp by clicking on
  155. the !Incorp icon on the icon bar - this will take the rucp-format mail and
  156. news and distribute them to the appropriate places in !NewsDir so !ReadNews
  157. can find them.  Note that the file listing newgroups will be deleted if it
  158. is empty.
  159.  
  160. To transfer outgoing news/mail from rucp to ka9q, double-click on rucp->ka9q.
  161. If ka9q is already running you will need to use the command `smtp kick' to
  162. tell it there is new mail waiting to be sent. 
  163.  
  164.  
  165. Notes
  166. =====
  167.  
  168. Ka9q->rucp now handles mail locking correctly.  You can run it whilst mail
  169. or news (or both) are coming in.  If run whilst ka9q is accessing mail/news
  170. files it will give a warning, otherwise it will process whatever mail/news has
  171. arrived and ka9q will continue happily downloading the rest.
  172.  
  173. Ka9q->rucp mail and news processing has been speeded up by a factor of ten
  174. using some assembler routines - it whizzes through at approximately
  175. 100KB/second.  The assembler routines also implement semi-intelligent double-
  176. buffering which results in greatly reduced disc activity.
  177.  
  178. Ka9q->rucp news processing works with news files from all versions of ka9q.
  179. Version 1.21 and below separated news with
  180.  
  181.     #! rnews
  182.  
  183. whilst version 1.22 and above use
  184.  
  185.     #! rnews 1234
  186.  
  187. where `1234' is the number of bytes in the article.  In order to handle both
  188. kinds it simply ignores the byte count and provides its own (it does this fast
  189. enough that there is no point checking for a byte count and doing a simple
  190. file append if present).  The old version of ka9q->rucp did some very odd
  191. things when confronted with version 1.22 news separators and should not be
  192. used with ka9q version 1.22 or above.
  193.  
  194. Ka9q->rucp will not correctly handle news files with certain pathological
  195. errors: #! rnews followed by #! rnews; #! rnews at end of file.  However,
  196. since these should never happen (and with ka9q version 1.22 and above they
  197. should never, never happen), this shouldn't be a problem.  I had meant to
  198. fix this before releasing the filters, but the appearance of ka9q 1.22 meant I
  199. had to get the new versions out fast.
  200.  
  201. Ka9q->rucp has been modified to work with old versions of ka9q (news placed
  202. in !MailDir) and new versions (news placed in !MaildDir.folder) without
  203. any user intervention.
  204.  
  205. Ka9q->rucp does *not* handle `dotted' usernames (introduced in ka9q version
  206. 1.22) - mail for username `fred' is handled, but mail for username fred.blogs
  207. is ignored - use the alias file (also introduced in ka9q version 1.22) to
  208. redirect mail for fred.blogs to fred.  I may eventually find a way around this
  209. restriction, but it would probably mean modifying !Incorp.  Note: BBSs will
  210. probably use the alias file to map fred.blogs to 0.0.3.6 and then use a
  211. dedicated filter to shunt mail for fred.blogs from 0.0.3.6 to BBS user 0036.
  212.  
  213. Rucp->ka9q does not use NNTP to post news (the abilitiy to post news using
  214. NNTP appeared in ka9q version 1.22), and instead uses a mail gateway called
  215. `mail2news' - this name is currently hardwired into the program.  The mail
  216. gateway is more robust than nntp posting in that several DIS machines can
  217. handle mail if post.demon.co.uk is dead, but only news.demon.co.uk handles
  218. NNTP posting.
  219.  
  220. Rucp->ka9q now correctly handles the config file (introduced in ka9q version
  221. 1.23) as well as the autoexec.  It now reads both these files all the way
  222. through (config first) to find the values of the hostname, domain suffix and
  223. news gateway - this means that it uses the last given definition rather than
  224. the previous behaviour of stopping when it has found definitions for all of
  225. them.
  226.  
  227. Rucp->ka9q does not handle BCC: lines.  This is mainly because I took the
  228. easy way out when writing it.
  229.  
  230. Neither program multi-tasks, but you can run them with ka9q active without
  231. losing data (ka9q manages to pick up from any over-runs whilst the filters
  232. are running).  Ka9q->rucp expects user input under certain error-conditions
  233. (which will only appear the next time you run it if it crashes in the middle
  234. of processing news - I've never had this happen), so you might have problems
  235. if you try and run it under FrontEnd.  They will run quite happily in a
  236. taskwindow.
  237.  
  238. I uploaded some add-ons for ReadNews which integrate PGP (public-key
  239. encryption/authentication package) to Demon - look on gate for
  240. /pub/archimedes/RNscripts4pgp.
  241.  
  242.  
  243. ReadNews Bugs
  244. =============
  245.  
  246. ReadNews and Incorp have several minor bugs, and a couple of serious bugs.
  247. Here are the serious bugs and the workarounds:
  248.  
  249. !Incorp dies if it sees a null newsgroup - i.e., a Newsgroups: header which
  250. looks something like:
  251.  
  252.     Newsgroups: comp.sys.acorn,,comp.sys.acorn.tech
  253.                                
  254. The two consecutive commas cause !Incorp to look for a newsgroup with no
  255. name and crash.  The fix is as follows:
  256.  
  257.   1) Use Edit on !Rucp.uucp.news.<whatever> to find the offending line.  Note
  258.      that you may have to look for `,,' or `, ,' or `,  ,' or similar.
  259.  
  260.   2) Move back to the preceeding article and use ReadNews to check that it
  261.      has appeared.  This check is necessary because you might have found
  262.      `,,' at line 2360 of the news file but Incorp crashed on `,  ,' at line
  263.      820.  So you check the preceeding article to make sure you've found
  264.      the right place.
  265.  
  266.   3) Remove all articles prior to the article with the offending line (Incorp
  267.      has already processed them - if you leave them in they will appear twice).
  268.  
  269.   4) Remove the spurious commas in the Newsgroups: header.  Note there may be
  270.      more than one spurious comma.
  271.  
  272.   5) Adjust the byte count in the #! rnews separator accordingly.  For example:
  273.  
  274.          #! rnews 1057
  275.          path demon!sktb.demon.co.uk!pla
  276.          [...]
  277.          Newsgroups: comp.sys.acorn,,comp.sys.acorn.tech
  278.          [...]
  279.  
  280.      would become:
  281.  
  282.          #! rnews 1056
  283.          path demon!sktb.demon.co.uk!pla
  284.          [...]
  285.          Newsgroups: comp.sys.acorn,comp.sys.acorn.tech
  286.          [...]
  287.  
  288.      I.e., one comma has been removed and the byte count adjusted from 1057 to
  289.      1056.  You *must* get the byte count correct or the following articles
  290.      will not be handled properly (they all end up in one gigantic article).
  291.  
  292.      Because ka9q->rucp ignores byte counts and supplies its own, a safer
  293.      alternative to step 5 is to move !Rucp.uucp.<whatever> to
  294.      !MailDir.xxxnews and run ka9q->rucp again.
  295.  
  296.  
  297.  
  298. !ReadNews only handles a limited number of groups.  If you exceed this number
  299. it will start giving `No room' errors in the middle of reading news.  The
  300. fix is to increase the value of WimpSlot given in !ReadNews.!Run (an extra
  301. 32K is all that's needed).
  302.