home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / snews-20.zip / SNEWS.DOC < prev    next >
Text File  |  1992-08-02  |  19KB  |  459 lines
  1. NOTE: This documentation is somewhat out of date. Read README.OS2 for
  2. changes in the OS/2 (SNEWS /2) releases.
  3.  
  4. -----------
  5.                             Simple NEWS 1.0
  6.                             ===============
  7.  
  8.  
  9. INTRODUCTION
  10. ============
  11.  
  12.     'Simple NEWS' is an news add-on for UUPC.  It is intended for use as a
  13.     leaf node and offers:
  14.  
  15.       - Threaded news reading.  This allows you to be much more
  16.         selective about what you read, enabling you to cover many more
  17.         newsgroups.
  18.  
  19.       - The when a cross-posted article is read the news-reader marks all
  20.         the other instances of the article as read too.
  21.  
  22.       - Separate rc files are kept for each user, which record the individual
  23.         articles that you have seen.  This is in contrast to some readers
  24.         which simply record the highest article number read.  The user is
  25.         defined, as for mail users, in the file pointed to by the UUPCUSRRC
  26.         environment variable.
  27.  
  28.       - Usual range of response facilities: follow-up news, reply by mail,
  29.         forward by mail, save article/thread to disk.
  30.  
  31.       - Articles are now stored in one file per newsgroup, rather than
  32.         one file per article.  This results in an enormous saving (up to 3:1)
  33.         in disk space on disks with with a default cluster size of 4kb per
  34.         cluster.
  35.  
  36.       - Processing of batched/compressed news.  Unbatched and uncompressed
  37.         are not processed.  Control messages are not processed.
  38.  
  39.       - Posting - Posts are unbatched and uncompressed.  You can only post
  40.         to your 'mailserv'.  You cannot feed another site.  Posting can only
  41.         be done from within the news reader SNEWS.  If you are looking for
  42.         something to feed other sites why not try Waffle?
  43.  
  44.       - 'Received date' oriented expire to maintain the news database.
  45.  
  46.     I looked at porting Tass and wnews, but in the end decided they were
  47.     far more effort than it was worth, as these news systems were more
  48.     complicated than was necessary for a single user (at a time) dos
  49.     implementation.  Especially when the PC is likely to be a leaf node.
  50.  
  51.     Generally the algorithms used are simple, but the speed is adequate
  52.     for a feed for several users, expiring after 5-10 days.  The main
  53.     bottleneck occurs during the 'expire' operation, which must rewrite
  54.     the entire news database.
  55.  
  56.     'Simple NEWS' was built rather quickly (and it shows in places :-) to
  57.     suit my own needs.  I'm distributing it in the hope you might find it
  58.     useful.
  59.  
  60.     [Posting is a bit of a kludge.  The D... and X... files are created,
  61.     then queued using the UUCP program.  If you look in the source code
  62.     you will see this is all a bit dodgy.  I should sort this out some
  63.     time.  I've tested it by posting to a Waffle system which isn't all
  64.     that fussy, and by posting to a CNEWS/Unix SYSV system, which is
  65.     rather particular].
  66.  
  67.  
  68.   Requirements
  69.   ------------
  70.  
  71.     - A minimum of PC-XT, 640k RAM, plenty free.  The uncompress
  72.       is the hungry bit.  If you use a lot of TSR's, you could get
  73.       around this by having your feed use 12 bit compression.
  74.  
  75.     - Several megabytes of disk depending on size of the feed.
  76.       In NZ the 100 groups in my active file runs at about 45MB/month. So
  77.       you need to turn it over reasonably quickly.
  78.  
  79.     - You must have installed UUPC and the optional program, UUCP in
  80.       particular.  I'm using 11k.  You do not need any UUPC sources to
  81.       build Simple NEWS.
  82.  
  83.     The sources compile under Borland's TC++ and BC++, but I imagine you
  84.     should be able to compile it under earlier versions of TC and port it
  85.     to other MS-DOS ANSI C compilers with out much trouble.
  86.  
  87.  
  88.   Support
  89.   -------
  90.  
  91.     I don't want to be *deluged* with complaints, bug reports, or suggestions
  92.     for improvements.  I can think of enough of these for myself, :-).  And
  93.     no whining about the dodgy processing of the headers.  This will be
  94.     fixed sometime.
  95.  
  96.     If you have a problem, please try hard to solve it before you contact
  97.     me.  If you find a bug let me know.  Unless a bug absolutely cripples
  98.     you, you'll have to wait for the next release.  This policy arises
  99.     largely out of the fact that email costs me $$$.
  100.  
  101.  
  102.  
  103.   Caveats & Copyright
  104.   -------------------
  105.  
  106.     This software is copyright (1991) by John McCombs, Christchurch,
  107.     New Zealand.
  108.  
  109.     This package is free software, but NOT public domain; you can
  110.     redistribute it and/or modify it under the terms of the GNU
  111.     General Public License, version 1, as published by the Free Software
  112.     Foundation.
  113.  
  114.     This program is distributed in the hope that it will be useful,
  115.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  116.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  117.     GNU General Public License for more details.
  118.  
  119.     See the file COPYING, which contains a copy of the GNU General
  120.     Public License.
  121.  
  122.     The compress included here was not written by me, and is to the best
  123.     of my knowledge in the public domain.  Any unix compatible compress may
  124.     be used.
  125.  
  126.  
  127.   Acknowledgments
  128.   ---------------
  129.  
  130.     I'd like to thank Steve Kohlenberger, of PreSoft Architects, for
  131.     making suggestions and doing some testing for me.
  132.  
  133.  
  134. FILES AND DIRECTORIES
  135. =====================
  136.  
  137.     NEWS BASE DIRECTORY - This is the top level directory for Simple NEWS.
  138.       the active file and the users rc files are kept here.  This directory
  139.       is defined by the environment variable UUPCNEWS
  140.  
  141.     *.NRC - These files have a list of the articles which a user has
  142.       seen.  The name of the file is derived from the 'mailbox' variable,
  143.       for example my news rc file would be 'john.nrc'.  The nrc files are
  144.       kept in the news base directory.
  145.  
  146.       The nrc files are created and maintained automatically by the news
  147.       reader and should not be edited by hand.  If one becomes corrupted,
  148.       just delete it.
  149.  
  150.     HISTORY - The history file contains a list of the message-id's of all
  151.       the cross-posted articles in the database.  It is used by the
  152.       news-reader to find all the instances of a cross-posted article,
  153.       The file fields are message-id, received date in seconds (Unix date),
  154.       newsgroup name & article number for each instance of the article.
  155.       The history entries are added by 'unbatch' and deleted by 'expire'.
  156.  
  157.     ACTIVE - The active file contains a list of the newsgroups we expect to
  158.       get.  The format is defined under installation, below.  All articles
  159.       to newsgroups not defined in the active file are posted to junk.
  160.       You MUST use 'addgroup' and 'rmgroup' to maintain the active file.
  161.       DON'T use and editor on it.
  162.  
  163.       The active file is in the news base directory.
  164.  
  165.     NG - This file is a list of newsgroup names, one per line, that you
  166.       can post to.  You can post only to groups listed in this file.  The
  167.       newsgroups file is in the news base directory.  If you want to
  168.       prevent anyone posting, simply remove the ng file.
  169.  
  170.     POST.LOG - This file, which is in the news base directory, is a log
  171.       of all postings.  You can read this file with 'mail' using the
  172.       -f option.
  173.  
  174.     ARTICLES - these are placed in files in a directory called 'newsbase'
  175.       which is a sub-directory of the news base directory.  There is one text
  176.       file and one index file for each newsgroup.  The name of the text file
  177.       is found in the second field of the corresponding entry in the active
  178.       file.  For example if the news base directory is d:\uucp\news
  179.       then articles in comp.sys.ibm.pc might be in a file called:
  180.  
  181.         d:\uucp\news\newsbase\87297243
  182.  
  183.       and the index file will be
  184.  
  185.         d:\uucp\news\newsbase\87297243.IDX
  186.  
  187.       Don't change these files by hand - use expire to do the deletion,
  188.       to keep the active file in sync.  Use 'addgroup' to create them
  189.       and 'rmgroup' to remove them.
  190.  
  191.     INDEX FILES - Each newsgroup has an index file which has information
  192.       about the articles in that newsgroup.  The format is
  193.  
  194.           00000000 00000001 687297893  Re: senior (humph!)
  195.           00001927 00000002 687297893  need rx02 controller.
  196.           00002801 00000003 687297893  Re: senior (humph!)
  197.           00003707 00000004 687297893  Another dumb luser story
  198.  
  199.       The first field is the offset of the article in the text file. The
  200.       second field is the article number.  The third field is the date/time
  201.       that the article was added to the database, and the fourth field
  202.       is the article subject.  This latter field is used by the newsreader
  203.       to build the threads.
  204.  
  205.     INCOMING NEWS BATCHES - These are placed by UUPC in the directory
  206.       defined by the 'NewsDir' UUPC.RC variable.  Unbatch processes the
  207.       batches from this directory, and deletes them when done.
  208.  
  209.     EXE Files - These can be placed in any directory that is included
  210.       in the PATH statement.  They are unbatch.exe, snews.exe, expire.exe
  211.       addgroup.exe rmgroup.exe and compress.exe.
  212.  
  213.  
  214. INSTALLATION
  215. ============
  216.  
  217. Installation is easy.
  218.  
  219.     0.  First get UUPC going and delivering news batches into the
  220.         'incoming' directory.  The name of this directory is set in the
  221.         UUPC.RC file using the 'NewsDir' variable.  The incoming directory
  222.         *must* be reserved solely for this purpose, and it must have
  223.         no files in it, other than the news batches that 'uuxqt' will
  224.         create there.
  225.  
  226.     1.  Put "set UUPCNEWS=c:\uucp\news" in your autoexec.bat.  This is
  227.         the 'root' directory for your news system.  The 'active', 'ng' etc
  228.         files are placed here and the news database is a subdirectory
  229.         of this directory.  UUPCNEWS must be *different* from the 'NewsDir'
  230.         specified in the UUPC.RC file.
  231.  
  232.         The 'NewsDir' directory is where batches of news are deposited by
  233.         'uuxqt'.  It is also the place where 'unbatch' looks for work.
  234.         If your news base directory is "c:\uucp\news" then you might
  235.         use "c:\uucp\news\incoming" as the 'NewsDir', eg:
  236.  
  237.              set UUPCNEWS=c:\uucp\news          <-- in autoexec.bat
  238.  
  239.              NewsDir=c:\uucp\news\incoming      <-- in UUPC.RC
  240.  
  241.  
  242.     2.  Create the 'active' file in this directory, using 'addgroup'.
  243.         For example:
  244.  
  245.             addgroup alt.sources comp.sys.ibm.pc.misc comp.sys.ibm.pc
  246.  
  247.         Each entry has the form of "alt.sources 87297268 00000000 00000000 y".
  248.         The first number is the filename of the file where the articles are
  249.         stored.  The next two numbers are the the lowest article number
  250.         (minus 1) and the highest article number, respectively.
  251.         The three numbers MUST be EXACTLY 8 digits long with EXACTLY one space
  252.         between them.  The last field is ignored.
  253.  
  254.         An example 'active.bat' file is included.
  255.  
  256.         ADDGROUP should be run from a batch file, so that you can easily
  257.         re-initialise the news system should the need ever arise.
  258.  
  259.     3.  Create a the 'ng' newsgroups file in the same directory as the active
  260.         file.  This file should contain the names of the newsgroups that
  261.         you wish to be able to post in.  As a minimum you probably want
  262.         the groups in your active files, less the names of the moderated
  263.         groups.  The file 'ng' looks like this:
  264.  
  265.             alt.angst
  266.             alt.aquaria
  267.             alt.artcom
  268.             alt.astrology
  269.             alt.atheism
  270.  
  271.         An example 'ng' file is included.
  272.  
  273.     4.  Edit the makefile and run it, and/or put the exe files in the DOS PATH.
  274.  
  275.     6.  Call your host and get some news.  Copy some of these batches into
  276.         another directory, so that you can use them again for testing
  277.         purposes.
  278.  
  279.         Run 'unbatch'.  This is where most problems occur.  Check:
  280.  
  281.            - That your disk is not full.
  282.  
  283.            - That the 'TempDir' directory specified in the UUPC.RC
  284.              file exists.  Check that there is also room on this drive.
  285.  
  286.            - Before the unbatch there should be some files with names
  287.              like '290f8f99.001'.  These are the news batches.
  288.  
  289.            - Dump the first part of one of these batches.  The file
  290.              should start with '#! cunbatch'.  If it doesn't, check that
  291.              your host is sending compressed batched news to you.
  292.  
  293.            - Run 'unbatch -n'.  The -n switch tells unbatch to feed the
  294.              first batch to compress and then stop.  If you look in TempDir
  295.              you should see two files, '$unbatch' and '$unbatch.z'.  The
  296.              first file is the uncompressed version of the latter.
  297.  
  298.              If the uncompress fails, check that you are using the
  299.              compress.exe supplied with Simple NEWS.  If you have another
  300.              compress.exe make sure the the SNEWS one is first on the DOS
  301.              PATH.
  302.  
  303.              Compress is run with the command line 'compress -d $unbatch.z',
  304.              and it must *not* convert unix type linefeeds to DOS style
  305.              cr/lf.
  306.  
  307.              Look in '$unbatch' with an editor.  You should see news
  308.              articles separated by the string '#rnews <number>'.
  309.  
  310.     5.  Modify UUIO.BAT putting "unbatch" after the last line of the
  311.         file.
  312.  
  313.     Once you have done this you should have your batches processed
  314.     automatically after transfer.  Use SNEWS to read your news, and
  315.     run expire once in a while to deleted the old stuff.  You could
  316.     stick the expire in your autoexec file.
  317.  
  318.  
  319.     Help!
  320.     -----
  321.  
  322.     In general you should not edit/delete the active file or the news
  323.     database files by hand.  Use only addgroup/rmgroup/unbatch/expire
  324.     for these tasks.
  325.  
  326.     The history and *.nrc files should not be edited by hand, but
  327.     deleting them is not fatal.  If they get corrupted, just delete
  328.     them.
  329.  
  330.     The active file, article text files and index files are all checked
  331.     to ensure that they stay in sync.  If someting gets corrupted you
  332.     can probably fix the problem by using rmgroup to delete the affected
  333.     group, then using addgroup to put it back.  The most likely cause of
  334.     this problem is 'unbatch' or 'expire' crashing.
  335.  
  336.     If things get really messed up your only option may be to re-init the
  337.     news system.
  338.  
  339.     You cannot post articles without a valid 'ng' file.  You can only
  340.     post to newsgroups listed in the 'ng' file.
  341.  
  342.  
  343. SNEWS - NEWS READER
  344. ===================
  345.  
  346.     SNEWS is a threaded news reader, somewhat reminiscent of TASS.  The
  347.     display has three levels, choose a newsgroup, choose a thread, and
  348.     read an article.  At each level the Home/End/PgUp/PgDn/UpArr/DnArr
  349.     can be used to move around.  ENTER selects whatever you are
  350.     pointing at, and TAB moves you to the next unread group/article.
  351.     To read the all of a thread (read and unread) keep hitting ENTER.
  352.     ESCAPE takes you back a level.
  353.  
  354.     'h' invokes a help screen,  'c' marks all articles in a group as read.
  355.     'p' posts an article, from any level.
  356.  
  357.     When reading an article 'r' and 'f' allow a mail reply and a news
  358.     followup of the current article, respectively.  You are given the
  359.     option of quoting the article.  'x' toggles a rot13 conversion of the
  360.     article.  PgUp from the start of the article will display all the
  361.     headers.
  362.  
  363.     The above commands are case sensitive.
  364.  
  365.     SNEWS maintains a list in the user's .nrc file of which articles have
  366.     been seen.
  367.  
  368.     In the group and thread levels the number of unread articles, if any,
  369.     is displayed, followed by the total number of articles, in brackets,
  370.     for each group/thread.
  371.  
  372.     The threads are constructed in the order that the articles were unbatched
  373.     which is usually pretty close to the chronological order.
  374.  
  375.     When you read a cross-posted article, all the other instances of that
  376.     article, in the other newsgroups, are also marked as read.  This saves
  377.     you having to sort out which articles you have previously seen.  If
  378.     you use 'c' to mark all the articles in a group as read, the instances
  379.     of cross-posted articles in other groups are *not* marked.
  380.  
  381.     Free memory is shown in [] at the top of each page.  You'll probably
  382.     have a hard time using it all up.
  383.  
  384.  
  385.     Posting
  386.     -------
  387.  
  388.     You can only post to newsgroups listed in the 'ng' file in the news base
  389.     directory.  If a newsgroup name is in the 'active' file, but not in the
  390.     'ng' you will not be able to post to that group.  This is a suitable way
  391.     to prevent posts to a moderated group.
  392.  
  393.     A copy of each post is saved in a file called 'post.log' in the news base
  394.     directory.  This file may be perused using mail, with a command like
  395.  
  396.         mail -f \uucp\news\post.log
  397.  
  398.  
  399. UNBATCH
  400. =======
  401.  
  402.     Just run it.  It looks for work in the UUPC.RC NewsDir directory,
  403.     and tosses the articles into the files defined in the active file.
  404.     News batches are removed as they are successfully processed.
  405.  
  406.     The only option is "-n".  This option causes the program to halt after
  407.     uncompressing the first batch, without unbatching it.  The uncompressed
  408.     file remains in the temp directory.  This switch is helpful in tracing
  409.     unpacking problems.
  410.  
  411.     Requires COMPRESS.EXE to be on the PATH.  Unbatch requires around
  412.     500k of free memory for the uncompress of 16 bit news batches.
  413.  
  414.  
  415. EXPIRE
  416. ======
  417.  
  418.     Expire takes one argument, the number of days.
  419.  
  420.         expire 5
  421.  
  422.     will delete articles 5 days or older from the news database.
  423.  
  424.     Expire will give you summary of the number of articles and size
  425.     of the remaining news database, and of the articles deleted.
  426.  
  427.  
  428.  
  429. ADDGROUP
  430. ========
  431.  
  432.     The 'addgroup' utility is used to create or add groups to the active
  433.     file.  For example:
  434.  
  435.         addgroup alt.sources  comp.sys.ibm.pc.misc  comp.sys.ibm.pc
  436.  
  437.     will add these groups, creating an new active file if none exists.
  438.     The newsgroup files in the 'newsbase' directory are also created.
  439.  
  440.  
  441. RMGROUP
  442. =======
  443.  
  444.     To remove a newsgroup, simply run rmgroup, followed by the newsgroup
  445.     names.  For example
  446.  
  447.         rmgroup alt.sources comp.sys.ibm.pc.misc comp.sys.ibm.pc
  448.  
  449.     This will remove the files and delete the entry from the active file.
  450.     The 'ng' newsgroups file is unaffected.
  451.  
  452.  
  453.  
  454. --
  455. Good luck
  456.  
  457. John McCombs
  458. john@ahuriri.gen.nz
  459.