
    NNTP - Network News Transport Protocol

    This version (1.7b) of Fnos implements a batching NNTP client
    routine. News articles retrieved are stored locally into a single
    file: BATCH.TXT. Provisions for sending new news articles have not
    been implemented, as yet. (MB - Jan '98)

    The 'nntp addserver <servername> <interval>' command must be
    executed prior to an 'nntp kick' command. If the NNTP.DAT file is
    used, then no other commands are required for the nntp client to
    work.

   
    The nntp commands are:
     
     nntp directory [<spool-directory> [<control-directory>]]
     
           Allows specification of the spool directory (where the news
           batches will be written) and the control directory (where
           the history, data, kill and get files are kept).  The
           control directory is discussed below.
           
           Default spool directory: /spool/mail
           Default control directory: /spool/news
           
     nntp groups [<group-list>]
          
           Allows specification of group list (see discussion below).
           Not used by the standard DIS.EXE installation.
           
           Default value: none
          
     nntp addserver <server-name> <poll-interval> [<time-window>]
     [<group-list>]
          
           Allows specification of news servers.  The poll-interval is
           the interval in seconds between polls of the news server
           (e.g., 1800 means poll the news server every 30 minutes).
           The time-window specifies a time window for polling.  The
           format is hour:min-hour:min (e.g., 18:00-20:00 means only
           poll between 6pm and 8pm local time).  The group-list is
           discussed below.
           
           Default value: none
           
     nntp dropserver <server-name>
          
           Removes a news server from the polling list.
          
     nntp kick [server-name]
     
           Forces a poll of the news server specified.  Has no effect
           if a poll is already being attempted.
           
     nntp listservers
          
           Lists the current news servers, the times until the next
           poll and the polling intervals.
          
     nntp batch [on|off [<buffers>]]
          
           When on, allows requests to be sent to the news server
           before the replies from previous requests have been
           received.  This makes things go faster.  The number of
           buffers determines the number of requests that may be
           outstanding.  Each buffer occupies around 1/2K of memory
           space.
           
           Default value: off, 2 buffers
           
     nntp newgroups [on|off]
          
           When on, the news server is asked for a list of new groups
           created since the last successful poll.  The list is
           appended to the file NEWGROUP in the control directory.  No
           attempt is made to remove duplicate entries.
           
           Default value: off
           
     nntp trace [<trace-level>]
          
           Allows specification of trace information to be sent to the
           screen.  The levels are defined as follows:
           
                      1 - minimal session progress only
                      2 - transient errors reported
                      3 - detailed progress
                      4 - actual received articles displayed
           
           All error messages are sent to the FNOS log file whatever
           the tracing level.
           
           Default value: 1
           
     nntp safety [on|off]
          
           When on, output files are closed after each article is
           received.  This gives maximum protection if a machine crash
           occurs but adds extra disk overhead.
           
           Default value: on
          
     nntp verbose [on|off]
          
           (Being replaced by nntp trace option)

          
   Control Directory
   -----------------
          
     The following files may be created or read from the control
     directory:
          
           NNTP.DAT
               
                 Used to record the time of the last successful poll of
                 each server.  Optionally used to specify the newsgroup
                 list for each server.  The format is specified below.
                 Old server entries are not automatically removed from
                 this file.
                 
           HISTORY
                 
                 Used to hold the message ids of articles received.
                 This information is only required by the NNTP client
                 to prevent duplicate articles from being received.
                 Old message ids are automatically removed from this
                 file using the SNEWS expire program.
                 
           NEWGROUP
               
                 Used to hold the names of new groups created on the
                 servers.  No attempt is made to prevent duplicate
                 names from being added.  Old group names are not
                 automatically removed from this file.
               
           KILL
          
                 Used to hold patterns with which received header lines
                 are compared.  If certain patterns match then the
                 corresponding article bodies will not be fetched.  The
                 format is specified below.  If this file exists then
                 all new articles will be fetched in two stages: header
                 first then body.  See the description of this file
                 later in this chapter.
                 
           GET
                 
                 Used to hold message ids of articles that should be
                 unconditionally fetched (i.e., not subject to the KILL
                 file pattern matching).  The message ids of articles
                 that are unavailable will not be removed from this
                 file.  The file may therefore require periodic
                 flushing. See the description of this file later in
                 this chapter.
                 
           *.TMP, *.LCK
           
                 Temporary files created during an nntp session. These
                 files should be automatically deleted.  The *.LCK
                 files should be manually deleted if there are no
                 active programs using files in the control directory.
                 
                 
    Format of the NNTP.DAT file
    ---------------------------
          
     There should be one line for each server.  This line will be
     automatically written after a successful nntp session and need not
     be created manually.  The line has the format:
     
          <server-name> <date> <time>
     
     The first character of the server name must be in column one.
     <date> has the form YYMMDD and <time> has the form HHMMSS.  The
     year is assumed to be in the closest century and the time is GMT.
     For example:
     
          news.demon.co.uk 920909 073954
     
     The newsgroups to be received from each server may optionally be
     specified on the lines following the line for the server.  Each
     line containing a newsgroup specification must begin with a
     whitespace character (e.g., space or tab).  One or more newsgroup
     entries may be put on a line, separated by whitespace or commas.
     Multiple entries on one line will never be split across multiple
     requests.  Blank lines in the middle of the newsgroup list force
     the list to be split into multiple requests.  Blank lines before
     and after the newsgroup list are ignored.
     
     Newsgroup entries may be complete names or may contain asterisks
     ("*") to allow pattern matches.  In addition, an exclamation mark
     ("!") as the first character will negate a match allowing
     newsgroups matching certain patterns to be ignored.  For example,
     "demon.*,!demon.test" will specify all groups in the demon
     hierarchy except demon.test.
     
     General guidance:
     
     1    List all newsgroups one per line (except as noted below).
     This will minimise the number of requests made.
     
     2    Always list "omit" entries (entries beginning with an
     exclamation mark) on the same line as the entries to which they
     apply.
     
     3    Don't separate the newsgroup list with blank lines. However
     blank lines are OK before and after the list.
     
     Example:
     
     ----------------------------------------
     news.demon.co.uk 920909 073954
     
          demon.* !demon.test
          comp.binaries.eniac
          comp.sys.eniac
          comp.unix.eniac
          alt.humor
          rec.pets rec.pets.gerbils
     
     ----------------------------------------
     
     Warning: be careful to leave the server line unchanged.  If the
     server line is not recognised then all news available may be
     requested.
     
     
   6.9.4 Format of the KILL file
   -----------------------------
   
     The kill file is a mechanism designed to enable you to download
     the headers of a news message first and then retrieve the bodies
     of selected articles later.
     
     News-collecting (in the killed groups) becomes a two-stage
     process.

     The kill file should contain one pattern per line.  Each header
     line received is compared with every pattern until a match occurs.
     A match must be exact, with the first character of the pattern
     matching the first character of the header line and the last
     character of the pattern matching the last character of the header
     line.  Case is insignificant and whitespace is always represented
     by a single space character. The pattern may contain special
     characters as follows:
     
     !    If the first character of a pattern is "!" then the rest of
           the line forms a "keep" pattern ("!" means don't kill).  If
           any header line matches a keep pattern then the article body
           will be fetched.
     
           If the first character of a pattern is not "!" then the
           whole line forms a "kill" pattern.  If any header line
           matches a kill pattern and no header line matches a keep
           pattern then the article body will not be fetched.
           
           The "!" character has no significance in any other position
           and will be matched literally.
               
     ?    Matches any single character.
     
     *    Matches zero or more characters.
     
     [ ]  Matches any single character that appears within the square
           brackets.  For example, [0123456789] will match any single
           decimal digit.  The characters can be specified as a range:
           [0-9] has the same meaning as the previous example.
     
     [^ ] Matches any single character that does not appear within the
           square brackets.  For example, [^abc] will match any single
           character except "a", "b" and "c".
     
     \    Matches the following character literally.  For example, \*
           will match a single asterisk and \\ will match a single
           backslash.
     
           The kill file patterns are all loaded into memory at the
           start of the news session - the kill file should therefore
           be kept as small as possible.  Off-line article selection
           can be performed by creating a kill file containing the
           single pattern "*".  This will cause only headers to be
           fetched.  The message ids of the required articles can then
           be put in the get file for retrieval during the next news
           session.
          
     Example:
     
     ----------------------------------------
     Lines: *[0-9][0-9][0-9]*
     Newsgroups: *rec.pets*
     !Newsgroups: *rec.pets.gerbils*
     ----------------------------------------
     
     The first line should kill any messages with more than 99 lines.
     Unfortunately some long messages do not contain a "Lines:" line so
     this is not foolproof.
     
     The second line should kill any postings or cross-postings to the
     rec.pets hierarchy.
     
     The third line will keep any postings to the rec.pets.gerbils
     hierarchy regardless of any matches with the other kill patterns.
     
     Note that the header lines of killed articles are retained. The
     full posting can be fetched later by putting the message id into
     the get file.
     
     
   Format of the GET file
   ----------------------
          
     The GET file is used to uncoditionally retrieve files from the
     news server.  In it you simply put the message-ids of the articles
     wanted.  You get the message-ids by looking at the headers of the
     articles retrieved (you will have retrieved just the header and no
     body).  Look for the header line that says Message-id: and take
     the data following it and put it in the GET file e.g.:
     
     <757001059snz@smof.demon.co.uk>
     
     Note that these message-ids stay there and so you should
     occasionally delete the contents of your GET file.
     
     NOS.EXE keeps a history of articles it has received and so putting
     a message id in your GET file is not enough.  You need to remove
     the entry out of the ~/SPOOL/NEWS/HISTORY file.
     
   News Error Messages
   -------------------
   
     Whilst receiving news you may occasionally see an "error" message.
     These are documented in RFC 977.  The most common ones are:
     
     230  You exited from NOS.EXE before news had finished downloading.
     Perhaps you typed exit at the fnos> prompt without checking the
     sockets or the line dropped.  This will make your next download of
     news longer.
     
     400  The news machine is busy - please try later.  This can happen
     if there is a great load on the news server and it decides that it
     cannot process your request for news with enough efficiency.  This
     is only temporary and you should leave only a short while before
     retrying, say 30 minutes.  You may of course try sooner or later
     as you wish - simply type nntp kick (or n k) at the fnos> prompt.
   
   Handy tips
   ----------
     
     If you don't always want to receive news:
     -----------------------------------------
     
     You may not always want to receive news every time you connect or
     you may wish to only receive news during certain periods of the
     day e.g. cheap rate.
     
     You can define some handy function keys in autoexec.net:
     
     fkey 60 "nntp addserver news.demon.co.uk 600 00:00-23:59\n"
     fkey 61 "nntp dropserver news.demon.co.uk\n"
     
     and alter you nntp addserver line thus:
     
     nntp addserver news.demon.co.uk 600 18:00-07:59
     
     That means that at any time F3 will stop news, and F2 will start
     it (e.g. at weekends).  Normally you should press F2 right at the
     beginning of your connection, before news normally starts.  If
     given later it may be necessary to follow it with an nntp kick (n
     k).
     
     If you want to select only certain articles in Newsgroups:
     ----------------------------------------------------------
     
     This can be done by using Kill files.  See the section earlier in
     this chapter on the formatting and use of kill files.
     
    *** End of NNTP help file ***
