back2roots/padua/padua.7z/padua/uucp/Arn103a.lha/doc/Arn.doc

GNU Info File | 1993-09-08 | 122.7 KB | 3,181 lines

This is the manual for Arn V1.03a- the USENET newsreader for the Amiga

Copyright (C) 1992-93 Roland Bless of Blessed Software Products

This program is not in the public domain. It's copyrighted by Roland
Bless. However, this program and its documentation can be freely
distributed, but ONLY if these rules are followed:

   * Commercial usage and making profit with it in any form is strictly
     prohibited, but the program and its documentation may be placed on
     electronic dial-up services for downloading by customers/users of
     such services (like BIX, Compuserve)! DISTRIBUTION, except as
     noted above, IS ONLY ALLOWED AT COST-PRICE/FOR NON-PROFIT! Fred
     Fish naturally has the permission to include it in his great pool
     of Amiga Lib(rary) Disks.

   * All Copyright-notes must be maintained! All rights reserved!
     Copyright remains by Roland Bless.

   * Redistribution of a changed program and/or documentation is not
     allowed!

   * The redistribution of a changed source without permission of the
     author is strictly prohibited!

   * Distribution of this packet/program together with another
     documentation (e.g. translated) is not allowed! This applies esp.
     to German PD-Dealers.

   * The redistribution in a commercial or PD-mailbox program is not
     allowed without my permission (contact [e-mail]).

   * NO WARRANTY! I do not take the responsibility for any loss of data
     or any kind of trouble caused by `Arn'! USE IT AT YOUR OWN RISK!!
     I do not guarantee that all functions work as described/expected!


This is the manual for Arn V1.03a- the USENET newsreader for the Amiga
Copyright (C) 1992-93 Roland Bless of Blessed Software Products


Copyright and copying
**********************

`Arn' is copyrighted software! This program is not in the public
domain. It's copyrighted by Roland Bless.

However, this program and its documentation can be freely distributed,
but ONLY if these rules are followed:

   * Commercial usage and making profit with it in any form is strictly
     prohibited, but the program and its documentation may be placed on
     electronic dial-up services for downloading by customers/users of
     such services (like BIX, Compuserve)! DISTRIBUTION, except as
     noted above, IS ONLY ALLOWED AT COST-PRICE/FOR NON-PROFIT! Fred
     Fish naturally has the permission to include it in his great pool
     of Amiga Lib(rary) Disks.

   * All Copyright-notes must be maintained! All rights reserved!
     Copyright remains by Roland Bless.

   * Redistribution of a changed program and/or documentation is not
     allowed!

   * The redistribution of a changed source without permission of the
     author is strictly prohibited!

   * Distribution of this packet/program together with another
     documentation (e.g. translated) is not allowed! This applies esp.
     to German PD-Dealers.

   * The redistribution in a commercial or PD-mailbox program is not
     allowed without my permission (contact [e-mail]).

   * NO WARRANTY! I do not take the responsibility for any loss of data
     or any kind of trouble caused by `Arn'! USE IT AT YOUR OWN RISK!!
     I do not guarantee that all functions work as described/expected!

If you like the program and want to honour my work, you can support me
and the further developement of the program by sending me a donation.
My address is:

     Roland Bless
     Groetzinger Strasse 44
     FRG --- 76227 Karlsruhe

suggested are $20 US or 30DM, but feel free to spend more. Users in
Germany can remit the money. Please send mail to
`[e-mail]' for bank account information.

I only received 2 donations for non-alpha/beta V1.xx Versions, this is
a little bit disappointing.

At the moment, there is no form of registration, because I don't have
the time for these administrative things. I'll invest this time better
into improving the program. `Arn' is no explicit shareware, because
existing newsreaders for UNIX aren't either.

Credits
=======

I used source code from the following people/institutions.
  1. *Modified* V8-regexp (egrep-style) functions originally from Henry
     Spencer, (C) 1986 by University of Toronto.

  2. slightly modified `termcap.c' and `tgoto.c' from the BSD
     distribution, (C) 1980 The Regents of the University of California.


Introduction
*************

`Arn' is a newsreader for USENET-messages(1) written for the family of
AMIGA computers. `Arn' means 'Amiga reads news'. It works with nearly
all known UUCP installations for the AMIGA and is conform to RFC 1036
(Standard for Interchange of USENET Messages).

What's a newsreader's task?
===========================

The mass of information you can get today over wide area networks is
simply too much to read all the themes you're interested in.

So the first task for a newsreader is to extract the useful information
from the flood of articles. The second task for a newsreader is that
you get informed quick and don't have to deal with administrative
things, like: Did I read this article already? What's new? Where do I
have to send my answer? and so on... `Arn' was designed to offer you
those capabilities. Some features are:
   * table overview over newsgroups and articles

   * selection of groups and articles of interest

   * five different article-overview display-modi
        - subject-threads in alphabetical order (within a thread
          chronologically)

        - subject-threads in chronological order (within a thread
          chronologically)

        - no threads, article sorted by date

        - compacted versions of the first two, which hide follow-ups

   * auto-selection and global/local kill-files

   * fast overview presentation of all articles by use of small
     databases

   * doesn't require much memory and is fast even with really many and
     large groups

   * configurable display of article-headers

   * built-in pager, recognizing extra long lines

   * full usage of screen sizes

   * multi-user support

   * works over the serial line (using termcap), too

   * rudimentary MIME support

The selected newsreading is what `Arn' makes similiar to `nn', a famous
newsreader for UNIX-machines.

History
=======

I started Februar 1990 writing my own newsreader after getting in
contact with UUCP for the AMIGA. The first aim was to get a reliable
working and RFC-conform newsreader that remembered read messages and
that lets one reply or follow-up on articles. This was a very
rudimentary version, but it worked and because it was similar to `rn'
--a UNIX newsreader-- I called it `Arn'. This concept was used until
Version 0.72.

So, `Arn' was written from scratch without using code from other
existing newsreaders. After a while, I noticed that the real information
on the net was only a little part of the big news-volume. Getting out
substancial information in reasonable time induced a need for new
concepts. The UNIX newsreader `nn' by Kim F. Storm seemed to have a
good concept and I tried to implement selected newsreading. I even made
one step beyond `nn' by making groups also selectable. The walking
through all groups was one thing that wasn't good in `nn'. I wanted an
overview of all groups with new and unread articles.

You see, `Arn' is a program that reflects my own idea of a good
newsreader, so your's may be different. The choice of a newsreader is
depends mainly on one's personal taste, therefore you may prefer other
newsreaders.

Actual changes from one version to another can be found in the
`CHANGES'-file which comes with this distribution.

---------- Footnotes ----------

(1)  sometimes also called UUCP-messages


About this manual
==================

This manual was set using the `texinfo'-package from the Free Software
Foundation.

The best what you can do with this manual is to print out the DVI-file
(it has the suffix `.dvi'). A DVI-file is produced by the typeset
program TeX and stands for "device independent file". TeX is a wide
spreaded free distributable program (written by D.E. Knuth) and runs on
a variety of computer-platforms (from Cray to PCs). The good thing
about DVI-files is that you can use them without translation on any
hardware which has a complete TeX or only the special printer-driver
and suitable fonts installed. For best results, use a laserprinter
(maybe your university or friend has one).

Naturally, there exists a very good free distributable TeX for the
AMIGA, called PasTeX. Look for it at ftp-servers or local BBs.

The second method is, to use it with the AmigaGuide (1) program from
Commodore. This is a hypertext-system, i.e. you can jump to
cross-references and subsections by simply clicking on the keyword.
AmigaGuide can be found on Fish-Disk 870.

---------- Footnotes ----------

(1)  AmigaGuide is (C) by Amiga-Commodore Inc.


Overview
*********


The concept: `Arn', `ArnMaster', `ArnDaemon'
=============================================

`Arn' is a very complex newsreader, i.e. it offers a lot of functions.
The main feature is, that you have a list of groups or article subjects
where you can select the items of interest from. To produce a fast
overview about the articles (subject,author,length), `Arn' uses small
databases (only 1-2% of the newsvolume) that are created by the
companion program `ArnMaster'.

`ArnMaster' is the program that updates and maintains the databases
that are used by `Arn'. `Arn' itself cannot create or update the
databases, instead it invokes `ArnMaster' if needed (in some rare
cases). `ArnMaster' should run every time your system got new articles.
Note: `ArnMaster' must have been started and finished before `Arn' is
started, otherwise you have a strong loss in performance (because
`ArnMaster' is called for each group separately).

To do this automatically, I wrote the program `ArnDaemon' which starts
`ArnMaster' if certain programs (have run and finished). See ArnDaemon,
for details.

So you see, `Arn', `ArnMaster' and `ArnDaemon' build a unit together.


Overview of files
==================

You should get `Arn' with the following files:
`Arn'
     the newsreader itself

`ArnMaster'
     the database manager

`ArnDaemon'
     the watch-daemon

`Arn.guide'
     the manual (AmigaGuide(1) -Format). To view with AmigaGuide.

`Arn.dvi'
     the manual, dvi-format (TeX), should be printed.

`.arnrc'
     a sample configuration file for `Arn'

`.arnrc.duucp'
     a sample configuration file for DUUCP

`.arnmasterrc'
     a sample configuration file for `ArnMaster'

`.arnmasterrc.duucp'
     a sample configuration file for DUUCP

`termcap'
     a sample termcap entry

`Arn.info'
     an icon for Arn

`CHANGES'
     release history

`sendm'
     script for archiving mails when sending (must have the script bit
     set!)

`README'
     important notes about the release, please *read*!!!

---------- Footnotes ----------

(1)  AmigaGuide is (C) by Amiga-Commodore Inc.


System Requirements
********************

`Arn' doesn't require special things. Naturally, you need an AMIGA
computer and at least Kickstart V37 (AmigaOS 2.04), but read the
following sections what may improve performance.


Hardware
=========

`Arn' needs no special hardware, so it should run on all Amiga models.


Processor type
---------------

The MC68000 is fast enough, but if you really want a *smart* newsreader
that *flies* through news, you'd better use faster processors like the
MC68020,MC68030,MC68040. `Arn' was always designed with extra care for
run time, so things that need a speed up are mainly the text-output or
your harddisk.


Harddisk
---------

A harddisk is not needed but strongly recommended (for your health...),
respectively a reasonable working is not possible without a harddisk,
and if you have your own site it is really needed for UUCP. The shorter
your average seek time of your harddisk, the faster is `ArnMaster' at
scanning articles, so the average seek time should not be 65ms or
longer.


Memory (RAM)
-------------

Generally speaking: although `Arn' doesn't waste memory, the more
memory the better. With a lot of groups and articles you can really
need a lot of memory, but then you already should have the resources.
`Arn' uses mainly FASTRAM (except for display) and is not a memory
eater, you wont normally use more than 500kBytes.


Software
=========


Operating System
-----------------

`Arn' works only with Kickstarts since AmigaOS2.04 (V37) and newer OS
versions. Because I have AmigaOS2.04 in ROM (Kickstart 37.175), I
developed and tested the program under it. Because this is now the
'standard' OS, and I wanted to make use of the new functions, I dropped
support for Kickstarts 1.2 and 1.3 (*you have been warned!*).


UUCP software
--------------

`Arn' is so configurable that it should work with all exsiting UUCP
packages for the Amiga. The two most known  installations are AmigaUUCP
(aka DUUCP, Dillon's UUCP), CNews and some derivatives from CNews.

It is recommended to use a UUCP-package that supports an `active'-file.
It contains information about available groups, whether they are
moderated or not and lowest, highest article numbers. If your UUCP
doesn't support an `active'-file `ArnMaster' will do this for you, but
you have the disadvantage of scanning the whole news-tree each time
`ArnMaster' runs. This wastes time. DUUCP doesn't support an
`active'-file, yet, but CNews and it's derived versions do.

Furthermore you need certain standard `assign'ements for `Arn'. See
dirs, for details.


Getting started (quick installation)
*************************************

This chapter shows only a few points, that you need for a
*quick*-installation.

   * Put `Arn',`ArnMaster',`ArnDaemon' anywhere into your shell-path. A
     good place for them is the directory where all other UUCP binaries
     are, e.g. `UUCP:c'.

   * If you have AmigaUUCP, you should look into `.arnrc.duucp' and make
     appropriate modifications. Most config-entries are
     self-explanatory, but if you need to know more about an entry,
     look into the Setup chapter. Edit the file `.arnrc' with an
     editor. You need to change the entries
          NEWSDIR
          ACTIVEFILE
          GROUPLIST
          UUCONFIG
          SENDNEWS
          SENDMAIL
          TIMEOFFSET
     These entries must be set for posting, mailing, too.
          SEQFILE
          SIGNATURE

     See .arnrc, for exact meaning of the entries. Place `.arnrc' into
     a directory where you start `Arn' from or simply into `UULIB:'.
     Note that `.arnrc' in the current directory has higher priority
     than the general one in `UULIB:'.

   * Be sure that your UUCP-config-file (where UUCONFIG points to)
     contains the following entries
          UserName
          RealName
          NodeName
          NewsEditor
          MailEditor

   * The config-file `.arnmasterrc' is needed if `.arnrc' is not placed
     in `UULIB:'. Otherwise you can simply add the config-entries for
     `ArnMaster' to `UULIB:.arnrc'.

     This file must have the following entries:
          ACTIVEFILE
          NEWSDIR

     The entry UPDATEACTIVE is needed if your news-system doesn't
     support an `active'-file (like DUUCP).

   * A temporary directory is needed. `Arn' uses `T:', so be sure that
     this assignement is set correctly.

   * Place the file `arnhelp.txt' into `UULIB:'.

After you have done all this, you can start `ArnMaster' from a Shell or
CLI. To produce a logfile from `ArnMaster' simply add the entry
`ARNMASTERLOG' FILENAME. After `Arnmaster' has finished (the first run
will last longer than normally), you can start `Arn'. Use the `Arn -s'
command to start `Arn' until you are sure that your configuration is
right. This option is not required, but helps you at the initial
installation (see options).

New groups that are not in your `GROUPLIST', but in your active file
are added at the top. So all available groups are shown. How to sort
and change the order, See Grouplist. If you want to "unsubscribe"
newsgroups, See unsubscription.

Use `SHIFT-H' anytime for displaying help.

See ArnDaemon, for setting up `ArnDaemon'.


Setup
******

Read this chapter carefully, if you set up `Arn' for the first time. In
general, there are two examples for installation with AmigaUUCP Plus
and AmigaUUCP (DUUCP).


Directories, paths and assignments
===================================

Needed is the directory `T:', as well as a directory where your news
are stored into. As general configuration directory and place where the
help file can be found is `UULIB:' necessary. If you have DUUCP, this
assignement directory exists already.

Your systems "path" should contain the directory where `Arn',
`ArnMaster' and `ArnDaemon' reside (e.g. `UUCP:c'). See AmigaOS
system-documentation for the CLI-command `PATH' how to add something to
your "path".

Add all necessary assignements and paths into your `user-startup'.


Configuration files
====================

`Arn' uses configuration files (besides command-line options) to get
adjusted for certain environments. These files are editable with normal
ASCII-editors. A `.arnrc' in the current directory, from where `Arn' is
started, has higher priority than `UULIB:$USERNAME.arnrc' (>OS2.x only)
and `UULIB:.arnrc'. This is important to remember if you have more than
one `Arn'-user.


Configuration file `.arnrc'
----------------------------

The configuration entries are simple: they consist of a "keyword" and
are often followed by a "value". This value can be omitted if the
presence of the keyword suffices to specify the configuration (like
'boolean' values, where presence means 'true'). In this case I call the
keyword a "boolean"-keyword. The "value" is separated from the
"keyword" by spaces or tabs, the minimum is *one* space or tab.
Keywords are not case-sensitive, i.e. upper or lower case doesn't
matter (e.g. text,Text,TEXT have the same meaning). The value FILENAME
includes always the full path, unless stated otherwise.

Here is an example of a config file
     # Arn Config-File for AmigaUUCP Version 1.16D
     # this is a comment
     NEWSDIR     UUNEWS:
     SAVENEWS    UUCP:usr/rob/News
     ACTIVEFILE  UULIB:news/active
     GROUPLIST   UULIB:.grouplist
     UUCONFIG    UULIB:Config
     SEQFILE     UULIB:seq
     SCREENSW    YES
     QUOTECHAR   "> "
     TIMEOFFSET  0100 GMT
     SIGNATURE   UULIB:signature
     SENDNEWS    rnews <%s ;%s
     SENDMAIL    sendm %s rob
     PATHTYPE    User
     CATCHUPXREFS Yes

Below is an alphabetically order of the config entries. Required
configuration entries are marked with a -!-.

`ACTIVEFILE -!-'
     Format: `ACTIVEFILE FILENAME'
     The value specifies the complete path and filename for your
     `active'-file. This entry is vital for `Arn'. See active-file, for
     detailed description.

`ARTDISPLAYORDER'
     Format: `ARTDISPLAYORDER MODE'
     This keyword determines the order of displayed articles in the
     article-selector level which is used in all groups by default. You
     can change this behaviour temporarily by using the `V)'
     (View-menu, see article-selector commands).

     The MODE is one of
        * `SUBJECT-DATE'
          articles are grouped together by their subjects (to a so
          called  "thread") and are sorted by article-date of the first
          article in the  thread (usually the "parent"-article). Within
          a thread the Date: of the  article determines the order.

          shows only the first article  of a thread, with the number of
          follow-ups (this option is not completely  implemented).

        * `SUBJECT-ALPHABET'
          threads are displayed with the subjects in alphabetical order
          and within a  thread by article-date order.

        * `ARTICLE-DATE'
          displays all articles sorted by their Date: line (no threads).

        * `COMPACT-ALPHABETICAL'
          shows only the first article of a thread, with the number of
          follow-ups  (this option is not completely implemented). Same
          order as in  `SUBJECT-ALPHABET'

        * `COMPACT-DATE'
          shows only the first article of a thread, with the number of
          follow-ups  (this option is not completely implemented). Same
          order as in  `SUBJECT-DATE'

`ASK-FOR-AUTOSELECT-FUPS'
     This keyword doesn't require a value, so it's a "boolean-keyword".
     It's presence causes `Arn' to ask you *every* time you posted a
     follow-up, whether you want to "auto-select" this subject, which
     normally only appears after postings. This is good if you're
     interested in reading answers to your posting.

`AUXEDITOR'
     Format: `AUXEDITOR FILENAME'
     You must use this entry if you started `Arn' in terminal-mode. The
     editor must be useable via stdout/stdout streams. Examples are
     Elvis V1.3, memacs 3.9 (from the `auxsupport' package) or
     naturally `edit'. This editor must work from a ` newshell AUX:'
     correctly.

`CATCHUPXREFS'
     Boolean-keyword for marking crossposted articles as read if you
     "catchup" a group. If this keyword is missing, `Arn' doesn't care
     about cross-postings if you do a catchup.

`COLORS'
     Format: `COLORS WWW XXX YYY ZZZ'
     WWW, XXX, YYY, ZZZ are numbers in hexadecimal (leading 0x), octal
     (leading 0) or decimal. You can specify your own colors for
     `Arn''s screen. The number of values should match with the
     2^(number of bitplanes). The existence of this keyword is
     independent of SCREENDATA. The first number is for pen 1, the
     second for pen 2, etc... Example: `COLORS 0x777 0x000 0xFFF 0xDD0'
     for 2 Bitplanes = 2^2=4 Colors

`CUSTOMFONT'
     Format: `CUSTOMFONT FONTNAME SIZE'
     Specify the font for `Arn''s screen. Note that you have to add a
     `.font' suffix to the font-name. Example: `CUSTOMFONT Courier.font
     13'
     Proportional fonts are not recommended, because they'll make
     `Arn''s overview tables looking weird.

`DBASEDIR'
     Format: `DBASEDIR DIRECTORY'
     The DIRECTORY determines where the databases and X-files are
     stored. By default, they are stored in the `NEWSDIR' directories,
     too. This entry allows you to read news e.g. via local-networks
     (NFS), because normally you'll not have write-access to the
     server-newspartition. Don't forget to add this line in your
     `.arnmasterrc', too, if you specify it here and have a separate
     `.arnmasterrc'. For reading news over the net, you should
     regularly make a copy of the active-file to your machine, because
     `ArnMaster' creates a copy of the `active'-file.

`DOTDIRS'
     boolean-keyword. This entry is obsolete since DUUCP V1.16. Earlier
     AmigaUUCP versions had a 'flat-hierarchy' news-tree. That means
     the articles were stored into directories that were called exactly
     like the newsgroups, namely with dots in their names. The normal
     way of naming directories for newsgroups is by exchanging the dots
     with slashes, so you get a deeper nested news-directory. Example:
     `UUNEWS:comp.sys.amiga.misc' is the 'flat' form,
     `UUNEWS:comp/sys/amiga/misc' is the normal hierarchical form used
     by CNews, AmigaUUCP (since V1.16) and AmigaUUCP Plus. If you
     nevertheless have flat-directories, you must add this keyword.

`EXTERNALPRG'
     Format: `EXTERNALPRG Y|N COMMAND'
     This optional entry specifies an external program to be invoked if
     you type `o' ("other") at the pager. The *first* value must be a
     character "Y" or "N" to enable/disable the SHELLWINDOW during
     execution of the external program. A "N" or "n" will NOT open the
     SHELLWINDOW, all other values will. There is a difference between
     "n" and "N": "N" will switch WorkBenchScreen to front, "n" won't!
     For the specification of SHELLWINDOWs see above. If you enable the
     SHELLWINDOW, but the SHELLWINDOW entry is missing, `Arn' takes its
     internal default. After one or more (white) spaces follows the next
     value: A command containing a %s as placeholder for the
     full-pathname to the article. The %s MUST BE PRESENT! Spaces are
     preserved, the whole command-string is copied until end of line.

     sample-entry: `EXTERNALPRG  Y   rx postit %s'

`FILTER'
     Format: `FILTER COMMAND'
     Program or script to run over your article you wrote, *before*
     posting it. This enables you for example to use a spell checker
     etc... The parameter %s must be part of COMMAND and stands for the
     current temporary articlename. Example: `FILTER  checkarticle %s'

`GROUPLIST -!-'
     Format: `GROUPLIST FILENAME'
     Designates the file where `Arn' stores information about what you
     have already read. Its format is described later in detail (see
     Grouplist). It's similar to the `.newsrc' created by `rn'. This
     file will be created for you, if it doesn't exist. The old
     GROUPLIST-file is always renamed to FILENAME.bak the new one is
     always named FILENAME. For those who want to change their
     GROUPLIST with an editor one day: The entries in GROUPLIST for one
     newsgroup are unlimited. Each list for a newsgroup can be
     continued by starting the next line with one or more white-spaces
     (spaces/tabs). The line will be truncated after 256 characters.
     Because `Arn' normally creates and modifies this list
     automatically, there is no need for you to notice this limit.

`HEADERDISPLAY'
     Format: `HEADERDISPLAY STRING'
     The value is a string of chars that represent header-lines. The
     non letter chars set the display mode like
        * underlined

        * boldfaced

        * inverse

        * slanted of the following line (combination is possible).

     The order in this string induces the order in which the header
     lines will appear when displaying the article!

            _ underlined
            # boldfaced
            / slanted
            + inverse

            A  Approved:
            C  Control:
            D  Date:
            d  Distribution:
            E  Expires:
            e  Supersedes:
            F  From:
            f  Sender:
            G  Newsgroups: (current newsgroup)
            g  Newsgroups: (current newsgroup only if crossposted)
            I  Message-ID:
            K  Keywords:
            L  Lines:
            N  Newsgroups: (complete newsgroups line)
            n  Newsgroups: (complete newsgroups only if crossposted)
            O  Organization:
            P  Path:
            R  Reply-To:
            r  References:
            S  Subject:
            s  Summary:
            W  FollowUp-To:
            X  X-.....:    (the first of arbitrary lines that begin with X-)

     The default string is `n#F#A_S/s/K#DIE0L' which means display
     `Newsgroups:' if crossposted, boldfaced `From:' and `Approved:',
     underlined `Subject:', slanted `Summary:' and `Keywords:',
     boldfaced `Date:', normal `Message-ID:', `Expires:',
     `Organization:' and `Lines:'.

`HEADERFILE'
     Format: `HEADERFILE FILENAME'
     Points to the file that is to append to each article header you
     post. If this keyword or its value (filename) is missing, nothing
     is appended to the header.

`MAILOPTS'
     Format: `MAILOPTS F D'
     This entry allows two values. If there is an "F" or "From" on the
     line, `Arn' automatically generates a `From:'-line at replies. If
     there is (maybe additionally) a "D" or "Date", the same happens
     with `Date:'.
     Examples:
          MAILOPTS F D
          MAILOPTS From
          MAILOPTS Date From

`METAMAIL'
     Format: `METAMAIL COMMAND'
     This entry specifies a template for calling MetaMail if `Arn'
     detects a `Content-Type:' other than `text/plain'. You can specify
     the placeholder `%s' in the COMMAND for the articlename.
     `METAMAIL metamail %s'

`NEWSDIR -!-'
     Format: `NEWSDIR DIRECTORY'
     This entry specifies the "news-directory", i.e. the top level
     directory from where the directory/newsgroup tree starts. The last
     character should not be a "/" (slash), because `Arn' will append
     one for you!
     Examples:
          NEWSDIR  UUNEWS:
          NEWSdir  UUCP:usr/spool/news

`PAGEROPTS'
     Format: `PAGEROPTS ClearScreen Headerstop'
     Possible values are `ClearScreen' or `HeaderStop' (the first letter
     suffices). The value `ClearScreen' lets the pager clear the screen
     before the next page is printed, so you get a top-down-scrolling
     which is faster than normal scrolling. `HeaderStop' lets the pager
     stop right after the header was printed. This is maybe useful for
     slow remote-connections.

`PATHTYPE'
     Format: `PATHTYPE User|No|Domain'
     This optional entry determines how `Arn' generates a `Path:'-line
     for new-articles: `PATHTYPE User' means that `Arn' generates the
     line `Path: user'. `PATHTYPE No' means that `Arn' generates no
     `Path:'-line at all. `PATHTYPE Domain' means that `Arn' generates
     a `Path:'-line with the full-domain systemname (`Path:
     system.domain.topdom!user'), all other values specify a full
     `Path:'-line: `Path: system!user'. For AmigaUUCP Versions >=1.08D
     this entry should be: `PATHTYPE User'

`PUBSCREENNAME'
     Format: `PUBSCREENNAME NAME'
     This entry specifies a name for the public-screen that `Arn' opens
     if this keyword is present. Otherwise `Arn' would open a
     non-public custom screen.

`QUOTECHAR -!-'
     Format: `QUOTECHAR "CCCC"'
     This entry contains your favourite character(s) that will be used
     for quoting, that means is inserted in the leftmost column in each
     line of the included text at replies or follow-ups. This entry is
     LIMITED in length! The whole entry should not contain more than 6
     characters that means 4 characters maximum of QUOTECHAR, because:
     The first char and the last char are stripped off this string just
     to make it possible for including spaces.
          QUOTECHAR "> "
     Quoted text looks like this:
          > this is a test for quotechar. this is a quoted line of text.
          > this is a test for quotechar. this is a quoted line of text.
     or
          quotechar    (## |)
     Quoted text then looks like this:
          ## |this is a test for quotechar. this is a quoted line of text.
          ## |this is a test for quotechar. this is a quoted line of text.

`REPLY-TO'
     Format: `REPLY-TO E-MAIL ADDRESS'
     This optional keyword allows you to specify an alternatively
     e-mail return-address in postings and replies via e-mail.

`SAVENEWS -!-'
     Format: `SAVENEWS DIRECTORY'
     This entry specifies the default directory where `Arn' saves your
     articles, if you use the `s' or `w' commands and no other
     directory is specified. The default name for saved articles is the
     groupname.

`SCREENDATA'
     Format: `SCREENDATA WIDTH HEIGHT DEPTH VIEWMODES'
     This entry lets you open `Arn''s screen with individual attributes.
     WIDTH and HEIGHT are the (decimal) dimensions in pixels. DEPTH is
     the (decimal) number of desired bitplanes. VIEWMODES is one of the
     modes that is listed in the prefs-program `screenmode' (e.g.
     `NTSC:High Res Laced' or `EURO:72Hz Productivity'). You can use
     every mode that is accessable via the screenmode-preferences
     program.

     To get the modes that are not known in plain text you can specify
     the mode with the `IDNUM:' specifier. `IDNUM:0x8004' is equivalent
     to Hires-Interlaced for example. However, this option should be
     used with care.

`SCREENSW -!-'
     Format: `SCREENSW Yes|No'
     Favourite editors (named in UUCONFIG) can have their own screens
     and therefore you can force `Arn' to switch or not to switch to
     the WorkBench-Screen (bring it to front). If something like `NO'
     follows (first letter suffices), then `Arn' will not bring the
     WorkBench-Screen to front. If there is a "Yes" or anything other
     than "N", `Arn' will bring the WB-Screen to front. After invoking
     the editor, and after the editor has quit, `Arn' will bring
     *always* the "ArnScreen" to front. If you still don't know what I
     mean, just let it set to "YES".

`SELFSEND'
     Format: `SELFSEND COMMAND'
     This is an obsolete option for early AmigaUUCP versions, which
     spooled articles written on your system for your newsfeed, but
     didn't sort them into your newsgroups. So this entry was used to
     spool the article for your own system. This COMMAND is executed
     additionally to `SENDNEWS'. COMMAND must have the parameter `%s'
     in it.

`SENDMAIL -!-'
     Format: `SENDMAIL COMMAND'
     `command' designates the program which spools mail for your
     mailfeed/sites. It could be ``mail <%s'', with AmigaUUCP it is
     ``sendmail <%s -f user''. The `%s' is placeholder for the filename
     of the message. If your mail doesn't generate a `From:'-line,
     insert the appropriate `MAILOPTS' entry in `.arnrc'. COMMAND could
     also be a script file, like `sendm' which archives all outgoing
     mail into a folder:
          .key mailfile/a,username
          .bra {
          .ket }
          .dot ~

          ; This script is only for archiving outgoing mail
          ; Mail is stored in $maildir/$archive

          set maildir= "T:folders"
          set archive= "mail.sent"
          IF exists "{mailfile}"
           IF NOT exists $maildir
              makedir $maildir
           ENDIF
           echo >>$maildir/$archive From rob (ARCHIVE)
           echo >>$maildir/$archive "Date: " NOLINE
           date >>$maildir/$archive
           type >>$maildir/$archive "{mailfile}"
           IF "{username}" EQ ""
              sendmail <{mailfile}
           ELSE
              sendmail <{mailfile} -f "{username}"
           ENDIF
          ELSE
           echo "{mailfile} not found!"
          ENDIF
          unset maildir
          unset archive

     Please set the script bit (protect +s file), if you're using
     scripts!

`SENDNEWS -!-'
     Format: `SENDNEWS COMMAND'
     This is the command `Arn' invokes, if you want to post an article
     to the net, which means you send it to your newsfeed(s) and/or
     other sites. The COMMAND should contain two placeholders `%s'. The
     first stands for the temporary article-filename, the second for
     the Newsfeed name, which can be ignored by putting it behind a
     semicolon. For AmigaUUCP this line should be
          SENDNEWS rnews <%s ;%s
     For really old versions of AmigaUUCP (before V1.06D) the line
     looks like `SENDNEWS uux %s "%s!rnews"'.

`SEQFILE -!-'
     Format: `SEQFILE FILENAME'
     This is a FILENAME for a file which should contain a single number
     in ASCII-Format. It will be used for the Message-ID of postings or
     follow-ups and is increased by `Arn'. This file exists also under
     Amiga-UUCP as `UULIB:seq'. The number is set to 0 if it was
     negative or 32767. At the moment, no locking is done, so there may
     be conflicts sometimes.

`SHELLWINDOW'
     Format: `SHELLWINDOW WBENCHTOFRONT WINDOWSPECIFICATIONS'
     This entry is for the piping commands `S',`W' and `|'.
     WBENCHTOFRONT is either `Y' or `N': `N' means to bring the
     WorkBench-Screen *not* into front, all other values do. This entry
     is optional, because `Arn' has a default entry for it:
          Y CON:0/0/640/200/Arn-CLI
     But you can take advantage of your favourite console-handler:
          Y MYCON:0/0/640/200/This is a console window raised by Arn
     `MYCON:' is an example for a custom `CON:'-device. Spaces are
     preserved, the whole string is copied until end of line. Normally,
     the `CON:'-Window will appear on the Workbench-Screen! To get rid
     of this `CON:'-Window, enter "endcli" at the CLI-prompt. You can
     naturally describe here a normal file-name, because `Arn' does an
     `filehandle= Open(SHELLWINDOW,MODE_NEWFILE)' and then an
     `Execute(cmd,filehandle,filehandle)'.

`SIGNATURE -!-'
     Format: `SIGNATURE FILENAME'
     The FILENAME of your signature file to append to your
     articles/mails written with `Arn'. NOTE: `Arn' will NOT put any
     characters (e.g. the "--") before your signature-text. But if you
     want this, just insert it into your SIGNATURE-file...

`TIMEOFFSET -!-'
     Format: `TIMEOFFSET OFFSET TIMEZONE'
     This entry contains two values: A timezone-name and the offset to
     your time according to this timezone. Example:
            TIMEOFFSET +0100 GMT
     which means that `Arn' will *subtract one hour* from your local
     time and will use/append timezone GMT in `Date:'-lines. The format
     of the time OFFSET is `[+|-]hhmm', where `hh' is the number of
     hours and `mm' ist the number of minutes (0-60). Example: You're
     9.5 (nine a half) hours before GMT so your offset is 930 (nine
     hours and thirty minutes): `TIMEOFFSET +0930 GMT'. The value can
     be preceded by a minus or a plus sign. If no sign is given a plus
     is assumed (which means to *subtract* that value from your local
     time!). Spaces between the signs and the numbers are not allowed!
     Leading zeros are *not* required and can be omitted.

     To get your local timezone into the `Date:'-line, just use an
     offset of 0 and then put your local-timezone-name after it.
            TIMEoffset 0 MET
     (MET means Middle-European-Time)

     It is recommended to use your offset according to GMT
     (Greenwich-Mean-Time) and use GMT as timezone, because there
     doesn't exist a real standard for timezone-names, yet. The length
     of the TIMEZONE-name is limited to 5 characters! If it is missing
     or too long, `Arn' will display a WARNING and say that it took GMT
     instead!

`UUCONFIG -!-'
     Format: `UUCONFIG FILENAME'
     This specifies the filename for a file where to get information
     about the UUCP environment. It looks like this:
          NodeName      spirits
          UserName      rob
          RealName      Roland Bless
          NewsFeed      pilhuhn
          Organization  Blessed Software Products, private, Karlsruhe (FRG)
          MailEditor    Dme
          NewsEditor    Dme
          DomainName    .ka.sub.org
          DefaultNode   pilhuhn
          Moderators    UULIB:moderators

     Required entries are `NodeName', `UserName', `RealName',
     `MailEditor', `NewsEditor'.

     Note that these entries are taken from local or environment
     variables first if they exist and have higher priority over
     `UUCONFIG'.

     `Moderators' is a special entry that `Arn' uses.
     Format: `MODERATORS FILENAME'
     This FILENAME points to the location were the "moderators"-file
     can be found. The moderators-file contains e-mail addresses of the
     moderators of moderated newsgroups. See moderators, for detailed
     description.

`XLIFETIME'
     Format: `XLIFETIME NUMBER'
     This optional entry specifies the default lifetime in days of your
     "X-file" (see X-files) entries, if you add automatically entries
     to X-files (not with your editor). If this entry is missing the
     XLIFETIME is set to 30 days.

NOTE: If you have more than one `Arn'-user you should not place `.arnrc'
into `UULIB:', but for each user `$USERNAME.arnrc' in `UULIB:' or
`.arnrc' in the user's home-directory (See Multiuser, for details).


Configuration file `.arnmasterrc'
----------------------------------

If you have only one `Arn' user, you can just add the configuration
entries for `ArnMaster' to `UULIB:.arnrc'. This is not possible if you
have more than one user, because you require only *one* configuration
file for `ArnMaster', but for each user a different `.arnrc'! Therefore
the separate configuration file, which has higher priority than
`UULIB:.arnrc'.

`ACTIVEFILE'
     See .arnrc.

`ARNMASTERLOG'
     Format: `ARNMASTERLOG FILENAME'
     If you want that `ArnMaster' logs all actions, you can specify a
     filename for the logfile here.

`COUNTLINES'
     If this keyword is present, `ArnMaster' generates the `Lines:'
     number in databases if missing in article header. The original
     article header remains untouched!

`DBASEDIR'
     See .arnrc.

`DOTDIRS'
     See .arnrc.

`NEWSDIR'
     See .arnrc.

`UPDATEACTIVE'
     Boolean-keyword to use `ArnMaster' for managing the `active'-file.
     You *must* specify this entry if your news system doesn't support
     an `active'-file, e.g. AmigaUUCP V1.16D. Note, that the scanning
     phase is not necessary if you use CNews or AmigaUUCP Plus.


active-file
============

The `active'-file contains information about the newsgroups and
articles that are present on your system (or available). It contains
newsgroup-names and the range of present article-numbers.

If you think your news-system doesn't have one, you can use something
like `UULIB:active'. In the latter case you must create this file by
writing all the names of the available newsgroups on your system into
it. One group on each line. A good help would be a `newsgroups' file,
if existing. In this case you can simply copy it.

Note that you have to add any new newsgroup to the `active'-file
manually, if your news-system doesn't support it!

The `ACTIVEFILE' is read in faster if it's in sorted order. You can do
that by simply using the `SORT'-command from AmigaOS:
     sort UULIB:news/active UULIB:news/active.sorted
     delete UULIB:news/active
     rename UULIB:news/active.sorted UULIB:news/active
or add the groups alphabetically by hand.

The format of the activefile is:
`GROUPNAME   XXXXXX YYYYYY S'

GROUPNAME is for example `comp.sys.amiga.programmer', XXXXXX stands for
the last article number (decimal format), YYYYYY for the first article
number in this group. The number are expected to fit in the
`long'-range, but except 0 you shouldn't change values manually.
`ArnMaster' will correct the entries started with the UPDATEACTIVE
option.

S is a newsgroup status flag and has for `Arn' two significant values
that are represented by lower- or uppercase characters: `y' or `m',
where `y' stands for posting into group okay, `m' for "moderated"
group. Postings in moderated groups are not allowed, unless you're the
moderator himself. `Arn' will display a warning in the case you try to
post into a moderated group. See moderators, for details.

Two example lines from an `active'-file:
     comp.sys.amiga.announce 00046 00039 m
     comp.sys.amiga.applications 01467 01389 y


Multiuser `Arn'
================

If you have AmigaOS >2.X, `Arn' checks for the local variable
`USERNAME', if this doesn't exist it tries the environment (ENV:). If
the variable is set, `Arn' tries to open the config file
`UULIB:$USERNAME.arnrc'.

Other configuration entries that are read from (local/global) variables
are REALNAME, NODENAME, DOMAINNAME, NEWSEDITOR, MAILEDITOR,
ORGANIZATION,MODERATORS. If found they have precedence over the ones
from `UUCONFIG'. This is only possible with AmigaOS 2.0 and later.

To set up `Arn' for more users you have to:
  1. create a "home-directory" for each user, i.e. a directory where
     the user starts the newsreader and other programs from. Example:
     `UUCP:usr/rob'

  2. place a modified `.arnrc' into the home-directory or into `UULIB:'
     named `USERNAME.arnrc' (under OS>2.X with the USERNAME variable
     set if calling `Arn'). Be sure that `GROUPLIST' and `UUCONFIG' are
     changed!

  3. create a separate `UUCONFIG' (See .arnrc, for details) in the
     home-directory, modify the entries `UserName', `RealName' and so
     on.... Let the `UUCONFIG' entry in `.arnrc' point to this file!

  4. Be sure that `UULIB:.arnmasterrc' exists. There should be no
     `.arnrc' in `UULIB:' any longer!

  5. Make sure that each user is in his/her home directory where
     his/her personal `.arnrc' is, when he/she starts `Arn'. Under
     OS2.04 and later you may prefer the concept of local/environment
     variables. Set the `USERNAME' variable and `Arn' will use the
     `$USERNAME.arnrc' in `UULIB:'.

     That's it!


Installation in networks with NFS
==================================

To read news from a netserver there are only a few things to change.

  1. You normally don't have write-access to the news partitions of the
     netserver. The solution is to specify the `DBASEDIR' in `.arnrc'
     (see .arnrc). The toplevel directory of `DBASEDIR' must exist,
     e.g. `mkdir `Work:NewsDbase'' and specify `DBASEDIR
     `Work:NewsDbase'' in `.arnrc'. Don't forget to add this `DBASEDIR'
     in `.arnmasterrc', too.

  2. The `active'-file must be in the format given before (see
     active-file). `ArnMaster' makes a copy of it, so you should
     *regularly copy* the `active'-file from your host or news-server
     to a directory on your machine (normally `UULIB:') and make the
     appropriate `ACTIVEFILE' entry in `.arnmaster' and `.arnrc'.

  3. Make an assign `UUNEWS:' to the remote news-directory (NFS-)device
     or change the `NEWSDIR' entry in the config-files.

  4. Start `ArnMaster' to create the databases (`ArnDaemon' is of no
     use...). NOTE: Currently, directories are created in `DBASEDIR' if
     not existent, but they are *not deleted* if they are empty (this
     is on my TODO list), yet.

  5. That's all. Please report any problems to [e-mail].


Using `Arn' over the serial port(s)
====================================

You can start `Arn' in a mode, that it uses standard in- and output.
For flexibility of control- and display-codes a "termcap"-entry is used.
`Arn' looks for the environment variable `TERMCAP_PATH' (in `ENV:'). It
should contain a path of files (not directories!), where termcap entries
can be found. Filenames are separated by spaces or commata. By default
this path is set to: `s:termcap UUCP:etc/termcap'.

Don't forget to set the `AUXEDITOR' entry in `.arnrc'.

To start `Arn' in this mode, you must use the commandline option
`-TTERMINAL'. With an amiga-ansi terminal you should enter:
     Arn -Tamiga
This command must be typed in the remote-shell, that is, if you opened
with `newshell AUX:' a shell, you must start `Arn' *from this new
shell*.


Termcap entries
----------------

Here is a short overview over termcap features. To learn the syntax of
a termcap entry, you should just look into the sample that comes with
`Arn'. First there is a field with the name of the terminal emulation,
for more than one name you can separate them through `|'. This field
ends with a colon. There are number-fields, boolean fields, and string
fields. An incomplete example of a termcap entry is:
     A0|ansi|Minimum ANSI:\
        :co#80:li#24:am:bs:bw:\
        :ae=\017:al=\E[L:as=\016:bl=\007:
`co' and `li' entries designate the number of columns and the number of
lines that the terminal can display. Both are number-fields. `am' is a
boolean-field. `bl=\007' is a string-field with an octal number
encoding the control character. `\E' is used for escape. Lines can be
continued by a `\' as last char in line. A `:tc=NAME:' as last field
points to the termcap entry named NAME.

Required entries:
   * cursorkeys (d=down, u=up, l=left, r=right)
          :kd=STRING:ku=STRING:kl=STRING:kr=STRING:

   * cursor motion codes (`nd' means non destructive space)
          :do=STRING:up=STRING:le=STRING:nd=STRING:

   * delete/erase character `:dc=STRING:' or `:ec=STRING:'

   * insert character `:ic=STRING:'

   * position cursor to row and column `:cm=STRING:'
     (`cm' screen relative cursor motion)

   * clear screen `:cl=STRING:'

   * clear to end-of-line `:ce=STRING:'

   * backspace key `:kb=STRING:'

If one of the entries is missing, `Arn' refuses to work on that
terminal. The following video attributes are optional.
     boldfaced on/off `:md=STRING:me=STRING:'

   * underlined on/off `:us=STRING:ue=STRING:'

   * slanted on/off `:as=STRING:ae=STRING:'
     (means alternate character set on/off)

   * inverse on/off `:mr=STRING:me=STRING:'
     or if `mr' is not available the standout mode is used instead:
     `:so=STRING:se=STRING:'

If some video codes are missing, they are set to the inverse codes.
Note that inverse video is used for displaying selection, so it's
important that these entries are set. If inverse codes are not
available, no attributes are used.

Furthermore there is also:
`:kD=STRING:' denoting the <delete char>-key.

Note that the parsing of cursor keys is currently a hack, so that the
cursor keys should *not* differ in the first character and only the
first character of the key_backspace and key_deletechar are used. This
will be changed to a more reasonable behaviour!

If using `Arn' in a CON:-shell on the Amiga, you must use the CSI
'\x9b' (for termcap: \233) for reading the cursor-keys. The CON:-device
understands normally CSI as well as `ESC[' for introducing
control-modes, but reading them can only return CSI.


Starting `Arn'
***************

Normally `Arn' is started from a Shell or CLI. You can use the supplied
icon with `Iconx' to start `Arn' from WorkBench. `ArnMaster' should
have run before you start `Arn'.


Commandline options
====================

Usage: `Arn [-?ipgsXRPN] [-TTERMINAL] [-DDIRECTORY]'

Options can be set together after one `-' sign or each option single:
`Arn -R -g' is the same as `Arn -Rg'.

`?'
`i'
     print the version number and usage info.

`p'
     starts `Arn' directly in "post-article-mode". After the article is
     posted (or not), `Arn' quits.

`s'
     `Arn' waits for pressing a key after it has started, so you can
     see better what configuration is used. This is helpful if
     installing `Arn' for the first time.

`X'
     start `Arn' in "X-file-expire-mode". `Arn' will not open it's
     screen, but look for all X-files and delete old entries (that are
     those whose expirationdate is reached) in them. You should let run
     `Arn' regularly with this option by `dcron'.

`R'
     reset all entries in your `GROUPLIST' (all groups loose their read
     marks)

`g'
     `Arn' prompts for a groupname to enter after starting and jumps
     directly into this group (if existing).

`PN'
     set `Arn''s task priority to N, where N is an integer between -127
     and 128. `Arn -P-2X' starts `Arn' in X-file-expire-mode with
     priority -2.

`-DDIRECTORY'
     `Arn' uses this directory as it were a newsgroup. All articles
     must have single numbers as filename like in normal newsgroups. No
     information about read/unread articles is saved after exiting.
     DIRECTORY should specify a complete path and should have *no*
     trailing "/".

`-TTERMINAL'
     starts `Arn' with terminal emulation TERMINAL in the current shell,
     using standard in- and output streams.

You can close the shell-window from where you started `Arn' (if you
didn't started it with `-T' option), because "stderr" is not used and
in-/output from executed programs is directed to to `NIL:'. Example:
     run <nil: >nil: Arn >nil: <nil:
You can close the window after `Arn' was launched.


Reading news
*************

Note that an `active'-file is vital for `Arn', See active-file.


Grouplist
==========

The `grouplist'-file is the file which determines what newsgroups you
read and their sequence. It also contains information about read
articles.

`Arn' will read the `active'-file and check for groups which are
missing in the `grouplist' (or if it even doesn't exist). Groups that
are completely new to your `grouplist' are inserted at the top and a
'+' is displayed at the group to inform you that this group is new to
your `active'-file respectively `grouplist'. These groups are
automatically added (or to be more precise "subscribed") to your
`grouplist', unless you "unsubscribe" them explicitely. The sequence of
presenting/reading newsgroups is determined by the sequence of the
`GROUPLIST' entries (to change this order you can use the `View-Menu',
see group-selector command table). New groups are always inserted at
the top, so the newest group can be found in the first position. But,
if no `grouplist' exists the groups are in alphabetical order.
To get the same order as in the `active'-file, use the sort option from
the `View-Menu'.

In `GROUPLIST' is also stored the last article number from the
`active'-file, if you leave `Arn' with `Q'. This last article number is
compared to the numbers in `active'-file next time you start `Arn'. If
the last article number in `active'-file is higher, there are new
articles and `Arn' will display this group with an 'N' as new-flag. You
can forbid `Arn' to update this last article number by exiting it with
`X', instead of `Q'. That keeps "new" articles marked as "new".

If `GROUPLIST' is updated, the old `GROUPLIST' can be found in the same
directory under the same name with the extension `.bak'. If you
accidentally pressed `Q', you can restore the old marks, by deleting
and renaming both files.


Format of Grouplist-files
--------------------------

The format of the Grouplist-file is very simple. It's an ASCII-text file
so you can edit it with a normal editor. Please use an editor which is
able to edit lines of 256 or more characters, otherwise you have to
break some lines manually.

The format syntax is:
GROUPNAME STATUS-SEPARATOR`<WS>'`;'NUMBER`;'`<WS>'RANGE

Where GROUPNAME is the normal name of the newsgroup, STATUS-SEPARATOR
is either `:' or `!'. The `:' denotes subscribed groups, the `!'
denotes unsubscribed groups. After some whitespaces (tabs or space),
which are expressed by `<WS>' here, there can follow a number
surrounded by semicolons. This number is the highest article number of
the group *last* time you left `Arn' with `Q'. This number is used by
`Arn' to determine which articles are considered as "new" (namely all
those, whose article-number is greater than this number).
RANGE denotes numbers separated by commas with *no* spaces between. A
range `37-45' stands for all numbers between 37 and 45 (includes 37 and
45). The range for each group can be continued on the next line, by
placing whitespaces in the first column (line-continuation).

Here is an example of a `GROUPLIST'.
     de.comp.lang.c: ;96; 37-45,56
     de.comp.lang.c++: ;109; 30-39
     de.comp.lang.lisp: ;5;
     de.comp.lang.misc: ;28;
     de.comp.lang.pascal: ;43; 11-14
     de.comp.lang.perl: ;1;
     de.comm.uucp: ;384; 348-351,382
     de.comm.gateways! ;1644;
     de.comm.ham! ;139;
     de.test: 1-2,300-400,
      212,231-267,1134,2333

`de.test' shows an example of line continuation, `de.comm.gateways' and
`de.comm.ham' are examples of unsubscribed groups.

Comments in the file are not allowed.


Unsubscription of newsgroups
-----------------------------

To "unsubscribe" a newsgroup means to exclude it from the group
overview. So you should unsubscribe all those groups you're not
interested in.

Use the `U'-command in the group-selector level to get into the
Unsubscription-Menu. If you want to unsubscribe some newsgroups you
should select them before calling this menu. See group-selector command
table, for details.

Once a group is unsubscribed you can "resubscribe" it with the same menu
you unsubscibed it.


The group-selector level
=========================

If `Arn' has come up properly, it will display a list of newsgroups
which have unread or new articles. This looks like this:
      Arn by R.Bless -   63/158  Newsgroups - page   1 of 3  New/Unread/Total
     >a   uka.ki                                            +  0/     1/     1
      b N alt.sys.amiga.uucp                                   5/     6/   115
      c N de.comp.sys.amiga.uucp                               1/     2/    31
      d N de.comp.sys.amiga.misc                               8/     9/   308
      e N alt.sys.amiga.uucp.patches                           1/    10/    11
      f   de.admin.news.announce                             M 0/     1/     3
      g N de.admin.news.groups                                 8/    14/   107
      h N de.admin.archiv                                      1/    65/    69
      i   de.admin.lists                                       0/     7/     7
      j   de.admin.mail                                        0/    71/    86
      k N de.admin.misc                                        1/    70/    77
      l N de.comp.lang.c                                       3/    11/    11
      m N de.comm.uucp                                         2/     2/    21
      n N de.comm.internet                                     2/    34/    34
      o N de.comm.misc                                         5/    71/    72
      p   de.comp.databases                                    0/     2/     2
      q   de.comp.gnu                                          0/     3/     8
      r   de.comp.graphik                                      0/     1/     1
      s   de.comp.os.minix                                     0/     8/     8
      t N de.comp.os.unix                                      5/    32/    35
      u   de.comp.os.xenix                                     0/     3/     4
      v N de.comp.security                                     1/     3/     6
      w   de.comp.sources.d                                    0/     9/    21
      x N de.comp.tex                                          5/    91/    91
      y   de.etc.lists                                         0/     1/     1
      z N de.etc.misc                                          1/    11/    25
     .a N de.admin.news.misc                                   5/     5/    92
     .b N de.admin.news.software                               1/     1/     1
     .c N de.comp.lang.c                                       1/    11/    12
     .d N de.comp.lang.c++                                     4/    15/    15
     .e   de.comp.lang.misc                                    0/     2/     2

The first line is the header-line:
      Arn by R.Bless -   63/158  Newsgroups - page   1 of 3  New/Unread/Total
it shows how many groups are included in the current listing (here 63)
and how many newsgroups are subscribed in your `GROUPLIST' (here a
total of 158). Furthermore the number of the currently displayed page
is shown as well as the total number of pages. `New/Unread/Total' is
only the legend for the columns under it.

The `N' in the second column shows that there are 'new' articles since
you last exited `Arn' with `Q' which deletes all 'new' marks. The
second column makes it easier for one to see which `N' belongs to which
groups.

The `+' informs you about new groups in your `active'-file, and `M' is
shown when the group is "moderated" (see moderators). There is also a
flag `U' which is shown if you selected to view all unsubscribed
newsgroups, too.

There are two ways reading news:

For speedy news reading you can use the up/down cursor keys to move to
the desired group and press ENTER to get into the "article selector".
There you can select articles to read in the same way you did with the
groups. See article selector, for details.

For sophisticated news reading you can select all the groups that are
of your interest: To select a group, just press the letter that is
listed before the groupname and the line of the selected article will
appear in inverse text. To select a range of groups press the letter of
the first group then `-' and `Arn' prompts in the last line `Select
range:', the next letter entered marks the end of your selection.

You get to the next page with further newsgroups to select by pressing
SPACE or cursor right. If you're on the last page and press SPACE
you'll automatically enter the first selected group. You can press `Z'
to read the selected groups immediately independent on which page you
are. If you finished reading one newsgroup you're automatically
transferred into the next select group until you read all selected
groups or exited with `Q' or `X'.


Group-selector commands
------------------------

Here is an overview of all possible commands of the group-selector
level. The cursor keys are denoted as `C_...'.

`C_UP'
`C_DOWN'
     Moves the `>' prompt up and down pointing to the current article.

`C_RIGHT'
`>'
     Displays the next page of newsgroups if there are any more.

`C_LEFT'
`<'
     Displays the previous page of newsgroups.

`^'
     Go to the first page

`$'
     Go to the last page.

`A'
     Show all subscribed newsgroups (toggles).

`a...z'
`.a....z'
`.A....Z'
     One letter in lower case selects this newsgroup. If you  press the
     `-' next, `Arn' waits for another lower case letter  to specify a
     range.  These letters can be preceeded by an extension character,
     the dot `.'.  This is possible (and then necessary) if your screen
     (and font) lets you  show more than 26 lines for selection. This
     gives you a current maximum  of 78 selection lines.

`+'
     Selects all groups that are marked as NEW.

`@'
     Inverts any existing selection of the current page.  You can
     select a whole page by pressing `@' when no  selection exists.

`#'
     Selects all groups on all pages (not only the current page).

`%'
     Unselects all groups on all pages.

`ENTER'
     Enter the group where your prompt points to.  If the group doesn't
     contain unread or new articles, all  existing articles are listed.

`G NAME'
     go to the named newsgroup. Resubscribe unsubscribed newsgroups
     this way, too. (case is not important!)

`/PAT'
`?PAT'
     search forward (`/') or backwards (`?') for the groupname
     containing PAT. PAT is a substring. Searching is not case
     sensitive! Searching starts at prompt position and can be
     continued, by simply typing `/ RET'. If the group is found (if it
     is unsubscribed, `Arn' adds all unsubscribed groups to your
     display) puts the cursor into front of the group.

`E'
     post a new article to the net. See posting.

`V'
     This invokes the view-menu. You can alter the number and order of
     groups  that are displayed in this level. You will see something
     like:
     `Show U)nsubscribed, R)ead, M)ove (behind cursor), S)ort, Q)uit:'
    `U'
          Show unsubscribed groups, too. This should display all groups
          that are in    your `grouplist'.

    `R'
          Show read groups (those with no unread articles), too.
          Similar but not always    identical to the `A'-command.

    `M'
          Move *selected* groups to the position *behind* the cursor
          (the first selected group will appear then in the line below
          the actual    cursor line). Naturally, this affects only the
          order in your `grouplist'.

    `S'
          Use alphabetical order for the *whole* `grouplist'.

    `Q'
          Do nothing, return to newsgroup-selector.

`U'
     This invokes the subscription-menu.
     You can "unsubscribe" or "resubscribe" newsgroups. To "unsubscribe"
      a newsgroup means that you're not interested in this group and
     you don't want  to see it in your group-menu. However, you can
     resubscribe these groups  anytime. The subscription-menu looks
     like:  `U)nsubscribe, R)esubscribe, Q)uit:'
    `U'
          A next submenu is displayed, saying:
          `S)elected Groups, G)roup at cursor (default):'          If
          you have selected some newsgroups before, and press `S'
             now, all these groups get unsubscribed.

    `R'
          The same submenu as with `U' ist displayed. You must have used
                   the "view-menu" before to show unsubscribed
          newsgroups.

    `Q'
          Do nothing, return to newsgroup-selector.

`C'
     Catchup group that's in the cursor line. Note that crosspostings
     are not marked as read, unless you specify the `CATCHUPXREFS'
     keyword  in `.arnrc'.

`O'
     This invokes the options-menu where you can turn on/off some
     general behaviour of  `Arn'. This looks like
     `H)eaderstop on,L)ocal Kill off,G)lobal Kill off,C)learScreen
     on,Q)uit:'
     e.g. if you press `H', "headerstop" is turned on.
    `H'
          Turns "header-stop-mode" on/off (default ON). See pager
          commands.

    `L'
          Turns local X-files on/off (default ON). See X-files, for
          information on X-files.

    `G'
          Turns global X-files on/off (default ON).

    `C'
          Turns "clear-screen-mode" on/off (default is OFF).   If this
          mode is enabled the screen is cleared before showing the
          next page. Useful if you use more than one bitplane and you
          think   scrolling is to slow.

`CTRL-T'
     Shows or hides the ScreenTitle. This key-combination toggles.

`R'
     Re-read the `active'-file. Useful, if new articles arrived and you
     want to read them without leaving `Arn' first.

`L'
     List all newsgroups from grouplist and show their status:
           newsgroupname                        : U M D xxxxxx-yyyyyy
     The flags U M D stand for:
        * U - This group is currently unsubscribed.

        * M - This group is moderated.

        * D - This group will be removed from `GROUPLIST'. Their
     negations are not shown. xxxxxx-yyyyyy is the first and last
     article number in this group.

`H'
     activates a short help-list. The help file must be available. It
     is *very important* to remember this command.... To stop
     displaying the help-file, just press `q'.

`Q'
     Quit `Arn'  `Arn' will update it's `GROUPLIST' and wait for you to
     press any  key. All articles that were marked as new are (the next
     time you  use `Arn') considered as old.

`X'
     Same as `Q', but the new-marks are retained (not updated).

`CTRL-C'
     Quits `Arn' without updating the `GROUPLIST' (Emergency-exit).


The article-selector level
===========================

A typical article selection screen will look like this.
     comp.sys.amiga.programmer - page   1 of   7 - 128 of 168      lines     artnr
      a Dave Plonka      1.3/2.0 difference w/# of IDCMP messages     39  R    131
      b Peter Cherna     >                                            20 N     155
      c [e-mail].u 2.04 ROMS on the 3000 -- Is there any wa     11  R    107
      d Joakim Rosqvist  68040 speed                                  16 N     151
      e Lee_Robert_Willi a new 1.3 Intuition interface builder        38  R     56
      f C A Wichura      Re: Absence of new uucp binaries???           -  R     68
      g Ralph Babel      Re: Allocmem() causes expunge(). When ca     45        43
      h Bruno Costa      Re: Amiga 2.04 fd files                      20        90
      i Chris Hanson     AmigaDOS StartNotify() and deletion. Bug     44        17
      j Peter Cherna     >                                            68        44
      k Chris Hanson     >                                             -        63
      l Ronn F. Black    AmigaVision Bug Discovered...                33        22
      m Markus Wild      Re: Are even HARD links broken under 2.0     45         5
     >n Mike Meyer       >                                            22         7
      o Michael B. Smith >                                             -        64
      p Chris Hooper     >                                             -        86
      q Mike Meyer       >                                            55       112
      r Chris Hooper     >                                            34 N     166
      s Jeff Dickson     Re: Assembler addressing mode                19  R     95
      t Wolf Faust       Re: Bug in 2.04 parallel device driver?      31  R     84
      u Mike Schwartz    C Comment question                           13  R    100
      v Matija Milostnik >                                            22  R    104
      w Jeff Dickson     >                                            16  R    117
      x Jeff Dickson     >                                            17  R    122
      y Brett Bourbin    >                                             -  R    126
      z Craig Fisher     >                                            26  R    134
      ---------------------------------------------------------------------------
The first line shows the groupname that is displayed, the number
of the page that is actually shown, the number of pages available and
the number of displayed articles on that pages, as well as the number
of total articles available in this group. In the example above there
are 40 articles not displayed (read earlier) which you can display with
`A' (show all).

The name of the author is displayed (`ArnMaster' tries to find the
realname and cuts it to 16 chars maximum, if this fails `(nobody)' is
displayed instead) and after it the subject. FollowUps to an article
are marked with `>' instead with the subject. If there is a parent
article (if it contains no `Re:'), the subject is always printed.

Articles are sorted according to their posting `Date:' within a subject
thread. They only come out of order if the poster uses timezones that
`Arn' doesn't know (`Arn' recognizes 102 different timezones), or are
not unique. If the sequence of articles is not the chronological,
you'll see something like this:
       Re: foobar
       >
       >
       foobar
       >
       >
where foobar is the parent article. Subject-threads can be sorted
by date (of first article in thread) or alphabetically. Another sort
order is by article-date, which does not make threads. The sort order
can be changed by the `V'-command (view), see below.

Then the number of lines contained in that article follows. If there is
a `-' instead, it means that `ArnMaster' could not find the
`Lines:'-line in the article. You can avoid this by using `ArnMaster''s
`COUNTLINES' option, See .arnmasterrc.

The flag-field is shown next, `N' means new, `R' read, `D' deleted. The
last field shows the article number of that article in this group.

As in the group-selection-level you can read articles in two ways.

Move the cursor to the desired article and press ENTER resp. RET, the
pager will show the article.

Or select individually with `a'...`z',`.a'...`.z',
`.A'...`.Z',`+',`@',`#' articles. Interesting is the `*' feature: It
selects the whole unread thread of articles that have the same subject
as the last one you have selected.

SPACE takes you through all pages and starts the pager for reading the
whole bunch of selected news when at the last page. Alternately, you can
use `Z' or TAB to immediately read your selected articles. TAB does
automatically a catchup (i.e. mark ALL articles in this group as read)
if you've read all the articles and takes you to the next selected
group or if there is none to the group-selection-level.

If you return to the group-selection-level the group is still marked
with the `N' flag, if it contained new articles, but the number of new
(and unread) articles is set to 0. This is a feature and not a bug,
because you still will be able to distinguish groups containing new
articles from 'old' groups.

If entering the group again after reading all 'new' and read articles
are marked as new and read.


Article-selector commands
--------------------------

`ENTER'
     displays article which is on your cursorline.

`SPACE'
     show next page of articles. If on last page, read selected
     articles. If there are none selected you get to the next select
     group or back to the group-selection.

`a...z'
`.a....z'
`.A....Z'
     selects a single article for later reading.  To select a range
     type START LETTER`-'END LETTER (to select  articles c-e type
     `c-e'). All articles which have a dot in the first  column must be
     selected by a two-key sequence, consisting of the `.'  and the
     letter in the second column.

`*'
     select all unread articles with same subject as the previous
     selected.

`+'
     select all new articles

`@'
     invert the selection (selects whole page if no article selected).

`#'
     select all articles.

`%'
     unselect all articles.

`A'
     show all articles (not only unread and new). This function toggles.

`V'
     View menu:
     `1)Subject alphabetical, 2)Subj. date, 3)Article date,
     4)Compacted, Q)uit'

     This determines the article order for this and all further groups.

     The first option shows articles grouped together by their
     subjects, with the  subjects in alphabetical order and within a
     thread by article-date order.  The second option displays the
     threads sorted by article-date of the first  article in the thread
     (usually the "parent"-article). The third option  displays all
     articles sorted by their Date: line (no threads, but `*'  still
     selects the thread). The fourth option shows only the first article
      of a thread, with the number of follow-ups (this option is not
     completely  implemented).

`Z'
     read all selected articles immediately.

`TAB'
     read all selected articles at once and then catchup that group.
     You can escape from this action with the `X'-command in the pager
     (returning to selection and leaving all unread articles selected.

`C_UP'
     cursor up.

`C_DOWN'
     cursor down.

`C_RIGHT'
`>'
     same as space.

`C_LEFT'
`<'
     one page back.

`^'
     go to first page.

`$'
     go to last page.

`J'
     junk. Mark the article in the cursor line as read.

`U'
     mark unread. Remove the read-mark of the article in the cursor
     line.

`C'
     catch up. Mark all articles in this group as read! Goto next group.

`CTRL-T'
     show/hide ScreenTitle.

`E'
     post an article to this group.

`O'
     options-menu. See group-selector command table.

`K'
     X-file menu.  This submenu looks like this:  `E)dit, K)ill,
     A)utoselect, D)elete, Q)uit:'  `K',`A',`D' are applied to the
     article where your cursor  points to. See X-file-menu, for details.

`/'
`?'
     this activates the searching in articles on all pages.  If you
     want to search in all articles you must use the `A'-command before
      (and the `r' in the MODIFIER).  `/' searches forward from the
     current cursor position.  `?' searches backwards.  Format:
     `/'PATTERN`~'MODIFIER
     PATTERN denotes a "sub-string" or "regular-expression"  (see
     Regular expressions). If you type `/RET' the search  is continued
     with the same PATTERN and attributes as before.  MODIFIER:
    `c'
          case dependent.

    `a'
          search in whole article.

    `h'
          search in header (default).

    `r'
          search in read articles, too.

    `R'
          PATTERN is a regular-expression.

`M'
     Miscellaneous-Menu.  This allows you to mark/unmark selected
     articles or to unsubscribe  this group (see unsubscription).
           J)unk, U)nread, unS)ubscribe, Q)uit:

`B'
     Version info.

`N'
`P'
     go to next or previous selected newsgroup.

`Q'
     Quit reading this group. Go to next selected group.

`X'
     Go back to newsgroup-selector.

`CTRL-C'
     Leave `Arn' immediately (`GROUPLIST' is not saved!). If you press
SPACE on last page or `Z' or TAB and there are selected articles,
you'll enter the pager, the lowest level in `Arn'.


The pager level
================

`Arn' has a builtin pager which gives you the advantage of starting
actions, like replying directly and it has certain special display
features like hiding/emphasizing certain header-lines or recognizing
super long lines.

It supports some features of the MIME-standard (Multipurpose Internet
Mail Extensions, see RFC-1341 [Borenstein & Freed]), with builtin
"quoted-printable"-decoding and "base64"-decoding. Note, that MIME
hasn't been defined for News as I'm writing this, but it won't hurt to
offer such support.
`Arn' can only process messages with `Content-Type: text/plain'
directly, for all other types METAMAIL is called (see .arnrc).


Display features
-----------------

`Arn' will display an article beginning with the line:
      Article XXX (of XXX) in XXXXXXX.
              ^^^     ^^^     ^^^ actual newsgroup
              |||     Last article-number in this group.
       Current article-number

Then follows the header (that are the first lines until a newline is
detected). The header is displayed as you specified in `.arnrc' or by
default in this way: display `Newsgroups:' if crossposted, boldfaced
`From:' and `Approved:', underlined `Subject:', slanted `Summary:' and
`Keywords:', boldfaced `Date:', normal `Message-ID:', `Expires:',
`Organization:' and `Lines:'.

The full header can be displayed by pressing `v' (verbose header), but
it's displayed without attributes.

The body-text follows after the header and each line is carefully
registered in its length so that `Arn' stops after your screen is
filled up (this is not the whole truth: `Arn' will always display the
next N-1 lines, if your screen has a maximum of N lines, to let you
always see/remember the last line from the previous page). Even TABs
are counted, so no text will scroll off the screen until you pressed a
key (control characters are not checked, so control codes may confuse
the pager. In this case blame the poster and not me!). If the next line
is very long, `Arn' can stop before the bottom line has been reached.
If `Arn' detects a `^L' (ASCII-12=FormFeed) it just will behave as it
has reached the N-1 lines: it will stop and prompt:
     --- MORE (XX %) <XXX> (XX unread) ---
               ^^     ^^^   ^^
               |        |   number of unread articles in this group
               |        --- Article-number
               --- percent of displayed text
`Arn' will continue displaying this article if you type SPACE or
TAB. If stopped at an `^L' (FormFeed=ASCII 12), it will display `^L'
instead of the real code. (If `Arn' detects a `^L' *within* a line then
the output of this line is slowed down! If this ^L is not in the first
column, any of your commands are ignored, until to the end of this
line.)

After the number of unread articles there can be some letters in
brackets `{}'. This shows the article status (`R' for read,`D' for
marked as deleted, `N' for new).

If you're reading selected articles, the count will not show unread, but
`[XX togo]' which means there are `XX' articles remaining if you're
reading forward (SPACE,`n').

If you have read all the text, you're at the end of this article or the
article contains only one page, `Arn' prompts:
     End of article <XXX> in XXXXXX (XXX). What now?[npq]:
                     ^^^     ^       ^^^number of unread articles in this
           Article-number    |          group.
                             Newsgroup-name

The number of unread articles *includes* the actual displayed article,
although you're just reading it. It will be marked as read (and all
cross-postings, too, if your UUCP- software generates an `Xref:'-line)
if you now press SPACE. So if the last article in a newsgroup is
reached, you will see that there's still one article unread (that's the
one you're reading).

The line limit is 1024 Bytes (then the line is not longer considered as
one line!)

Sometimes, offending messages (e.g. bad jokes) are encoded with the
"rot(13)"-encryption. This is a very simple encryption, but it prevents
the reader from directly reading the article. Normally those texts give
a hint that the contents of the posting/message may be offensive and
that the rest is "rot"ed. Use `x' for decoding such messages, see below.

Now you can enter some pager-commands (`h' or `H' for help exists here,
too!):


Pager-level commands
---------------------


Basic pager commands
.....................

`T'
`CTRL-R'
     restarts the current article (disables rot(13)-mode).

`v'
     restarts the current article with a verbose header.

`BS'
`CTRL-H'
     Display previous page. Displays the previous page(s) scrolled off
     (turns rot-mode off).

`CTRL-L'
     Redisplay the last page. Helpful after pressing `h',H for help.

`O'
     Options-menu. See group-selector command table, for details.

`x'
     display next page in "rot(13)"-mode.

`D NUM'
     enter a new rot-number (default is 13). If the text is encrypted
     with rot 18, you must use rot 8 to decrypt it.

`SPACE'
     displays next page, if at the end of an article *only*  this key
     marks your article as *read* (plus all  articles in the
     appropriate groups if it is a crossposting and  your news-system
     supports the `Xref:'-line) and searches for the  next selected
     article. If there is none you'll get to the next  selected group,
     if any.

`RET'
`ENTER'
     Displays only the next line. If pressed at the end of an article
     this article will be marked as read.

`g PAT'
     searches in this article for given substring (*no `REGEXP'*)
     starting at the top. This search is *not case dependent*!  If the
     pattern is found, the line containing this pattern is  displayed
     in the first line of the screen, otherwise `Arn'  displays `NOT
     FOUND!'.

`G'
     continue the search for a pattern ('see g').

`TAB'
     will also display the next page of text, but does nothing if at
     the end of the article.


Moving to articles in pager
............................

`n'
`N'
     read next selected article (leaves the current article unread!).
     NOTE: Only `j' marks this article as read or SPACE if  pressed at
          End of article <XXX> in XXXXXX (XXX). What now?[npq]:

`p'
`P'
     read previous selected article.

`NUMBER'
     goto article with this number. A number consists of digits from
     the set of  0...9.  `Arn' will enter the "command-mode" if you
     enter a number.  Just press RET/ENTER after you typed in the
     desired number. `Arn' now jumps directly to this article  (if
     available, otherwise it does nothing). After you quit reading this
     article,  `Arn' continues reading the selected articles, if you
     were reading selected  articles before jumping.

`/PAT~MOD'
     searches for PAT in articles.  PAT must be a substring or a valid
     "REGEXP"  (See Regular expressions.). MOD is a modifier:
    `c'
          case dependent search

    `a'
          search for pat in the whole article/text

    `h'
          search in header

    `r'
          search in read articles, too

    `R'
          `pat' is a regular expression.

     If no modifiers are given, the default is:  case independent
     search, search in unread articles only, substring (no  regular
     expression).

     `/ RET' (no pattern or modifiers specified) means to *search again*
      with the last pattern and settings.  To abort the search, just
     press *any* key (it's your task to  keep your fingers away... from
     the keyboard).  Currently, trailing spaces are not discarded!

`?PAT~MOD'
     to search in the other direction (? alone searches for the  same
     pattern backwards). See explanations for `/PAT~MOD'  above.


Posting, replying, forwarding, cancel
......................................

`f'
`F'
     invokes your editor and produces a "follow-up" (i.e. a public
     reply into  this or possibly another newsgroup).  This function
     should only be used if your answer is informative  enough for the
     whole readership, otherwise you should prefer the  REPLY-function.
      `F' will include the original article-text, but with the
     `QUOTECHAR'  inserted at the beginning of each line! Quote only
     the important passages for  easier remembering the subject, not
     the whole article!  Try to summarize if possible.  See follow-up,
     for details.

`E'
     enter a new message (post new article to the net).  `Arn' will
     render you to post a new article to this newsgroup.  (if not
     moderated! See posting, for details).

`c'
     Cancel this article, if it is yours. A control-posting is created
     if the `From:'-line contains `UserName@NodeNameDomainName'!  The
     editor is invoked, same procedure as with follow-up. The cancel
     function will send a control-article which is distributed just as
     normal  news-articles, but because it is a control-article, it
     will cause the  news-sites to cancel (delete) the article where
     you pressed this key.  This function is useful, if you posted an
     article to the net and  it already has left your system, but you
     nevertheless want to withdraw it  (maybe you posted nonsense,
     flames...).

`r'
`R'
     Reply. Invokes editor and produces a reply (`R' for quoting text),
      which is sent as e-mail (private-mail). See reply, for details.

`M'
     Invokes miscellaneous-menu which offers you forwarding articles or
      special-quoted followups (see special follow-ups).  Type `F' for
     sending this article via e-mail to an addressee  which you are
     asked for (See Forwarding, for details).


Other commands
...............

Archiving articles:
`s NAME'
`w NAME'
`os NAME'
`ow NAME'
     appends article(s) to a file.

     `Arn' appends it to the file NAME in the directory  `SAVENEWS'
     (See .arnrc.), if given, else to  `SAVENEWS:GROUPNAME' if no name
     is specified! You can save it/them to other directories/devices by
     specifying the *full path-name* containing a colon `:'. This even
     works for `prt:', so you can easily print articles with `s prt:'!
     These commands can be preceded by a range! Examples: (assuming
     `SAVENEWS' is `UUCP:usr/rob/News' and the current  newsgroup is
     `comp.sys.amiga.misc')

        * `s' appends article with header to
          `UUCP:usr/rob/News/comp.sys.amiga.misc'

        *  `os' appends all *selected* articles *in thread order* to
          `UUCP:usr/rob/News/comp.sys.amiga.misc'

        *  ``w' help' appends article without header to
          `UUCP:usr/rob/News/help'

        *  `1000,1010-1040 `s''  appends complete articles
          1000,1010-1040 to
          `UUCP:usr/rob/News/comp.sys.amiga.misc'

        * ``s' UUCP:tmp/help' appends complete article to
          `UUCP:tmp/help'

     If the NAME begins with a `|', the rest of NAME and all following
     text will be considered as shell-commands. Save the article to
     standard-input of the following command (PIPING): `s |sort to
     RAM:test' will pass the article to standard-input of `sort', which
     then will put the result into `RAM:test'. `s | sort to RAM:test'
     is allowed also. NOTE: `s |' and `w |' commands will sent all
     further output to `NIL:'! So redirect your output if necessary or
     use the commands `S'/`W'/`|'! `S' and `W' will open a
     `SHELLWINDOW' (See .arnrc.) which will act as input/output stream.
     To get rid of this window and to reenter `Arn', just type `endcli'
     to the CLI-command prompt. `S' is equivalent with ``S |'' and
     ``|'', ``W'' with ``W |''.

     This is *not* a *real* piping mechanism, because it doesn't use the
     `PIPE:' device and it normally had to "run" the commands following
     `s |'. This function creates a temporary-file in `T:' and then
     redirects the input-stream of the following program to this
     temp-file. The temp-file is then deleted. ``s |'COMMAND OPTIONS
     FURTHER_COMMANDS' is executed as `command <PIPE_tmpfile options
     further_commands'. With some shells you're able to do multiple
     pipes: `S search STDIN fred | sort | type to RAM:test NUMBER'

`|'
     is shorthand for ``S |''.

Marking articles (read or unread):
`u'
     don't mark this article as read.  Note: this will *not* unmark all
     crosspostings, too.

`j'
     junk this article (mark it as read) and do `n'.  (If your
     UUCP-software supports `Xref:'-Lines (CNews and   AmigaUUCP Plus
     do), all crosspostings are marked as read, too).

`J'
     mark this article as read, but stay at this article.

`C'
     catch up. `Arn' will ask you for a confirmation. Mark all
     articles as read! Goto next group.

`k'
     catch up current subject. This command works only when you're
     reading  selected articles. All articles with the same subject are
     marked as read  and become unselected! Nothing is written into
     X-files, so this can be  considered as a temporarily thread-kill
     (or better thread-skip).

X-file commands:
`K'
     invokes the X-file menu. See article-selector commands.

`d'
     this adds the subject of the current article to your local X-file.
      The subject is cut at a length of 30 characters and the
     validity-period  is set to the default XLIFETIME.

Miscellaneous commands:
`M'
     invoke the Miscellaneous-menu:
            F)orward, S)pecial quoted follow-up, Q)uit:
      See Forwarding, See special follow-ups, for explanation of these
     actions.  `Q' quits the menu (no action taken).

`o'
     other program. This key invokes the external program `EXTERNALPRG'
      if specified in `.arnrc'

`CTRL-T'
     show screen-title. This key toggles (show/hide).  The window is
     resized and the `CTRL-L' command is issued.

`I'
     show current newsgroup status.

`h'
`H'
     HELP. Display the help-text.


Range commands
...............

Range commands are executed only for some listed articles. You can
additionally specify filter flags to restrict the field of activity.
You first specify the range and then the command that is applied to it.
Note that you can select articles and then use range command to save
them for example (`1-$:s s T:test') Format: RANGE CMD
A range consists of one or more subranges:
     RANGE:== subrange{","subrange}
     subrange:== number{":"flags} | number"-"number{":"flags}
     flags:== [minflag]
     minflag:== "u" | "U" | "r" | "R" | "d" | "D" | "n" | "N"
     number:== [digit] | "^" | "." | "$"
     digit:==  "0" | "1" | "2" | "3" | "4" |
               "5" | "6" | "7" | "8" | "9"

     [x] denotes one or more occurrences of x.
     {x} denotes zero or more occurrences of x.
     |  means "or"

     special numbers: ^ first article, $ last article,
                      . current article.
     valid flags: U,u,R - unread; r - read;
                  s - selected; S - not selected;
                  n - new; N - not new.

     CMD is one of =,r/j,u/U,w,W,s,S,|

     / means alternatively and | is here the "Pipe" sign (not
     "or") and part of the commmand.

     j,r - mark it read; u,U - mark it unread;
     w,s - w,W,s,S,| -> see above (save,write)


Leave the pager
................

`q'
     Quit reading this article (let it marked read or unread).  Go to
     next selected article if any.

`Q'
     Quit reading this article and goto the article selection or  next
     selected group.

`X'
     Quit reading article and return to article selection page, don't
     show next  selected article. If you are reading with the
     TAB-command, which  catchups a group after reading all selected
     articles, this command aborts  the catchup function and returns to
     the article-selector level.

`CTRL-C'
     Quit `Arn' immedeately don't update `GROUPLIST'.


Writing news
*************

Naturally, you can't only read articles, but you also can reply to
postings, or create postings yourself. I want to distinguish "posting",
"follow-up", "reply".
posting
     This is a public message sent to all nodes in the net.

follow-up
     This is a reply to a posting, which is sent as a public message
     back into  the newsgroup.

reply
     This is a reply, which is not public, but sent via e-mail to the
     author  of the message on which you replied.


Posting
========

To "post" means that you write a new article with a new subject. Use
the `E'-command (enter new message) in all levels for invoking a post.
`Arn' will ask you for the desired newsgroup(s), the subject and
distribution. Then it will invoke your favourite editor (see
`UUCONFIG') and display the correct header. Now you can enter your text
after a blank line behind the header. If you quit your editor, `Arn'
will  prompt some choices which are described in detail in the
follow-up section.


Follow-up
==========

To follow-up on an article you must be in the pager-level, reading the
article you want to follow-up on. There exist the commands
   *  `f' for a follow-up without quotation

   *  `F' for a follow-up including the quoted article

   *  `M' for invoking the Miscellaneous-menu which gives the
     possibility  of a special quoted follow-up. This means you can
     quote the header  and temporarily change the quotation sign. This
     is recommended if the article  has already some nested quotations.

`Arn' generates a temporary file in your `T:' directory.


article-header
---------------

The header contains all the required lines (RFC 1036). All entries
taken from the original-article get here with respect to the
"line-continuation" (a header line can be continued by starting the
next line with spaces or tabs, if it seems to be too long for an 80
column display).

The `Newsgroups:' line contains the same newsgroups as the
`FollowUp-To:'-line of the original-article (if exists), otherwise the
`Newsgroups:'-line from the original article is copied. If the
`FollowUp-To:'-line contains more than one newsgroupname (one comma to
separate), the following WARNING is displayed.
     WARNING: Ambiguous FollowUp-To:-Line! Please (e)dit!
You should enter your editor once more and redirect the discussion into
only one newsgroup, but if you like, you can also suggest two or more
newsgroups (it's just a WARNING-message...).

If the `FollowUp-To:'-line contains something like `poster' or only
newsgroups that are not in your active-file you get a warning message,
too. `poster' is a nonsens newsgroup, which should express that the
author wants a reply instead. If you post to groups that are not in your
`active'-file, they are stored in the pseudo-newsgroup `junk', which
means that they are lost (never distributed).

The `Subject:'/`Title:'-line is generated by inserting a `Re: ' before
the original `Subject:'-line, but only if this line didn't begin with
`Re:' or `Re^'! The `Reply-To:'-address is either directly taken from
your `.arnrc' (`REPLYTO') or `UserName@NodeNameDomainName' as default.
The `FollowUp-To:'-line is identical with the `Newsgroups:' line. It
should only contain one newsgroup-name, to direct the follow-ups into
one group. The `References:' is either created or copied from the
original article. The `Message-ID:' of the original article is appended
(`Arn' does an automatic wrap around of long references lines).
*IMPORTANT:* If nevertheless your EDITOR wraps lines around, make sure
that the new lines *start* with SPACE or TAB-characters
(line-continuation!)!

The `Distribution:' is copied unchanged. The `Organization:' is
appended if available from `UUCONFIG'. The `Lines:'-line is inserted,
if you really send the article off. The `HEADERFILE' is appended to the
header.


article-body
-------------

*After at least one blank line* you can write your text or the
included/quoted text follows after a line like this:
     In article <[e-mail]> Freddy Foobar writes:
(If the realname is missing, the address is taken). `Arn' doesn't
support multiple parentheses like in: `(Freddy Foobar (the world's
best))' The RFC 1036 says that this should be avoided!!

Again: REMEMBER TO LEAVE AT LEAST ONE BLANK LINE BETWEEN THE HEADER AND
THE MESSAGE-BODY/TEXT!

Your `SIGNATURE' (from `.arnrc') will be added behind the header.

After you've finished your editor, `Arn' will prompt:
     p)ost, e)dit, f)ilter, a)bort:

If you type `p', `Arn' will check the header for redundant lines and
removes them, the `FollowUp-To:'-line is removed if it's identical with
the Newsgroups-line. Then the article is sent to your
`SENDNEWS'-program that is typically to your spool-directory
respectively newsfeed. After that, `Arn' executes the
`SELFSEND'-program if the entry in the `.arnrc' exists/is valid. If you
have generated a new posting (not a follow-up) or specified the
`ASK-FOR-AUTOSELECT-FUPS' keyword in `.arnrc', then you'll be asked:
`Do you want to autoselect this subject? (y/N):' Only if you press `y'
or `Y' the subject is marked for autoselection. It'll be selected as
long as your `XLIFETIME' lasts.

     NOTE: The contents of your posting are not checked/changed after
     editing, so  YOU ARE RESPONSIBLE FOR ANY NONSENSE IN THE
     MESSAGE-HEADER! (and the trouble you'll get)

With `e' you'll enter your editor once more.

With `f' you can invoke a filter program that changes your article. See
`FILTER' in `.arnrc' (See .arnrc.).

With a you don't send this article to the net! The article remains
still in your `T:' directory as `T:CancelledArt.'USERNAME!

If you didn't change the article at all, `Arn' will abort automatically.


Special follow-ups
-------------------

This feature can be reached by using the Miscellaneous-menu (command
`M', then press `S') in the pager level.

This invokes the special quotation follow-up function. It is recommend
to use this function whenever the article you want to follow-up on has
already some levels of nested quotations or if you want to include the
article-header into your follow-up.

You're asked `Quote header? y)es or N)o:', default is no. The header is
always quoted with the `QUOTECHAR' from `.arnrc' Next question is
`Quotechars: S)pecify, I)nitials, else normal:' If you choose specify,
you can enter a string of 20 chars max. that is used as quotechar
(preceding each line of quoted text). If you use initials, `Arn' uses
the first two letters from the authors first- and lastname if available
and displays what it suggests as quotechar. If it's okay just press
return, otherwise you can edit the string. Normally `Arn' uses the
`QUOTECHAR' from `.arnrc'.


Reply
======

Attention: No `From:'-line is generated. This is normally the job of
your sendmail-program (AmigaUUCP: `sendmail -f user').... If this is
nevertheless not possible, use the `MAILOPTS' in `.arnrc' or try it
with a script file (see `SENDMAIL' entry in `.arnrc') and write me
which program has this problems. The principle is the same as with
FollowUps, but this article then is sent as e-mail via `SENDMAIL'.

The `To:'-address is created from the following lines: `Reply-To:' if
available, otherwise `Return-Path:' if available, otherwise `From:'.

Two empty `Cc:' and `Bcc:' lines are created. The `Subject:'-line
follows the same rules as in followup-articles. A line `In-Reply-To:'
is generated containing the articles Message-ID and the newsgroup it is
from.

If quoting (`R'), `Arn' creates a first line of text like this:
     In sub.culture.foobars, article <[e-mail]>, you wrote:
If not quoting this line looks like this:
     This is a reply to your article <[e-mail]>, in sub.culture.foobars.

Your signature is included after the header. If you don't want a
signature, delete it within your editor.

After finished writing the article, `Arn' will prompt:
     s)end, e)dit, a)bort:

The message "Sending mail..." is *no proof* that your mail really will
be spooled/sent off! You must be sure that your entry in `.arnrc' is
correct and that this mail is really sent (try it once!).

If you didn't change the article at all, `Arn' will abort
automatically. If you aborted or an error occured the mail remains
still in your `T:' directory as `T:CancelledArt.'USERNAME!


Forwarding
===========

To `forward' an article means to send this article to other people by
e-mail. This is useful if you think this article/information might be
useful for some people which are not reading (regularly) this newsgroup.

Invoke forwarding through the Miscellaneous-menu in the pager-level.

This command is similiar to `R', but you can specify the mail-addresses.
`Arn' prompts:
     Forwarding this article...
     To:
     Cc:
     Bcc:
At the `To:' you can write down the e-mail addresses of the intended
receivers. At `Cc:' (carbon copy) all receivers which should get also a
copy, and at `Bcc:' (blind carbon copy) all people who should get a
copy, too, but all receivers listed under `To:' and `Cc:' shouldn't
know about these copies (that's the difference to `Cc:'). You can leave
these lines blank by typing RET. `Arn' displays:
     generating mail...
The generated mail looks like this:
     To: [e-mail]
     Cc:
     Bcc:
     Subject: FORWARDED article from amiga.test
     Reply-To: [e-mail]
     Organization: Blessed Software Products, private, Karlsruhe (FRG)

     This is an article from amiga.test,
     forwarded by Roland Bless <[e-mail]>.

     ------------- beginning of forwarded article -------------
     <header quoted with '|'>

     <body (not quoted)>
     ---------------- end of forwarded article ----------------

`Arn' doesn't show this mail, unless you type `e' at the
     s)end, e)dit, a)bort:
If you edit the article you must save it, otherwise `Arn' will abort
automatically the mail.


Moderated newsgroups
=====================

Moderated groups are special groups where you have no normal write
rights. They are marked in the group-level with an `M' flag. All
articles must be approved by a moderator of this newsgroup, which then
posts the article for you. Non approved articles are thrown away by the
news-transport system!

The intention of moderated newsgroups is to get informative newsgroups
with essential postings and without discussions about postings. This
normally restricts the traffic.

Often are groups that contain announcements, lists, sources or binaries
moderated. To contribute posting to these groups, you have to mail your
posting to the moderator.

This is supported by `Arn' with a moderators-file. This file contains
the e-mail addresses of the appropriate moderators from the moderated
newsgroups. Enable the use of a moderators file by adding the entry in
`UUCONFIG':
`Moderators UULIB:Moderators'.

The format is as follows:
NEWSGROUP EMAIL-ADDRESS

where NEWSGROUP is a newsgroup name, which can have dashes instead of
dots as a separator between subgroups. You can specify a default entry
which must have the placeholder `%s', which is replaced with the 'dash'
newsgroup name. This could be the e-mail address of a host which has a
complete moderators list and routes your mail to the right moderator.
This default entry looks like this:
`all    [e-mail]' which is e.g. expanded to
`[e-mail]'.


X-files
********

To automagically suppress messages you're not interested in, you can
use the X-file (aka "kill-file").

Unread messages that are matched by the entries in your X-file are
simply   skipped and marked as read ("junked") if you're reading
articles. For   `Subject:' and `From:' X-file entries the articles are
matched   already if you   enter a newsgroup, so junked articles will
not appear in the article list.   All other header-fields are examined
if the article is going to be   displayed.

You normally have two levels of X-files: global X-files and local ones.
  Global X-files are examined in EACH newsgroup, unless you turn this
feature off in the options-menu.   Local X-files are only active in
your current newsgroup you're reading   (you can also turn them off)
and therefore can be different for   every newsgroup.


X-file menu
============

The easiest way to create/use X-files is to use the `K'-command in
the pager-/article-selection level.

You'll see this line then:
       E)dit, K)ill, A)utoselect, D)elete, Q)uit:
  "Edit" lets you edit the kill files (local or global),
"Kill","Autoselect","Delete" lead to a further submenu:
       S)ubject, A)uthor, R)egexp, E)xpression, Q)uit:
  in pager-mode `T)hread' is a possible choice, too.

To get rid of all articles that have the same subject press `S', e.g.
or `A' to skip all messages written by this author.   `T' puts the
first Message-ID of the References-line into the X-file and   therefore
skips all articles refering to this Msg-ID (to abort type 'Q').   Note
that `T)hread' will not "prekill" articles, i.e. they are displayed in
 the article selection menu and junked if you want to read them!!
`S)' and `A)' junks/autoselects articles before you enter the article
selection pages. To get rid of a thread it's normally the best way to
type `S)' here.   `A)'utoselection lets you automatically pre-select
articles. Note that   auto-selecting/killing an author is much slower
than   auto-selecting/killing a subject, so if you only have a 68000
you should   not have too much `From:' entries in X-files!!

`R)' lets you specify a regular expression (which are slow),
`E)xpression'   lets you specify a substring to search for. In both
cases `Arn' prompts   for a Header-Field for which the expression
should be valid. Note that   only `Subject:' and `From:' are
pre-killing articles, so they are not   displayed on article-selection
pages.   Avoid regular expressions! They are processed very slow (I may
change anytime   over to other regexp).

After that a second prompt asks for the X-file-scope, that is global or
  local.   Then a last menu asks:
       Validity period: A)lways, S)pecify, else default, Q)uit (no change):

`A'
     The specified entry will never expire (deleted by `Arn -X').

`S'
     If you type `S' here, the next prompt asks for the date:
              Enter entry-expiration-date (mmddyyyy):
       The "mmddyyyy" says that you have to enter the first two
     digits as month, the next two as day and the last four digits
     the full year. There are no spaces or separators allowed.

`RET'
     If you simply type RET the default expiration period (XLIFETIME) is
       taken. See .arnrc.

`Q'
     Your last chance to prevent adding this entry.

`Arn' will add/create the entry in the X-file automatically for you.

X-file format
=============

You naturally can add manually entries which is normally easy. An X-file
  entry looks like this:
       Header-field:/pattern~command expirationdate
  If the header field is missing `Subject:' is default.   Pattern is a
sub-string that, if it matches with the header-line which begins   with
Header-field, will cause a command to be executed.   If there is the
letter 'r' after the ~ in the command characters, the   pattern is
interpreted as regular expression and not as sub-string.   The regular
expression is an V8-regexp, which is explained in detail in   the
chapter "Regular Expressions" (see Regular expressions).   'c' will
make matching (both regular expression and substring) case-dependent.
The '^' modifier restricts sub-string matching to the beginning. This is
  useful if you want to kill a certain thread, but not all diverging
topics, too.   Example: `gaga~^' kills `Subject: Re: gaga', but not
`Subject: Re: foobar (was Re: gaga)'. This '^' modifier is used by
the `S)' command in the X-file menu (see X-file-menu).

Command is   'j'(junk) or   's'(autoselect)   Again junk is default if
this field is omitted.

For AUTOSELECTION, i.e. articles that match are selected if you enter
this group, you must specify the 's' command.

The lifetime of each entry can be limited to the expirationdate. This
is optional, if there is none expirationdate specified, the lifetime
of this entry is unlimited (unless you delete it by hand!).   Note that
the entry is only IGNORED if the expirationdate is reached.   To
physically delete the redundant lines, you must start "Arn" with
command-line option "-X". This inconvenience is because of better
performance during reading articles. I recommend to run regularly
"Arn -X" via "dcron".

`Arn' sets the lifetime automatically to `XLIFETIME' days,   if you're
adding entries with "S","A","T" or "K".

The expirationdate has the format:   `ddmmyyyy', with `dd'-day,
`mm'-month, `yyyy'-year

The / and ~ are separators and can be obtained itself by doubling:   //
is the slash itself or ~~ accordingly tilde.   Please note that you
have to override special regexp-meta-signs by   \ (backslash) (but
`Arn' makes it at S,A,T automatically).

BTW: Concerning 'S': `Arn' cuts the subject to 30 characters.

X-files consider only HEADERS for matching patterns at the moment.
You can specify the header field like From:, Keywords:, Summary:, etc.
 as mentioned above.

Local X-files are named ".X<UserName>" and located in the newsgroup
sub-dir. The global-X-file is named ".glX<UserName>" and is located in
 the same directory as your GROUPLIST-file is.

Note: If you're searching for a subject ('/') and this subject is in
     your X-file, "Arn" will execute the X-command (maybe junk)
and skip to the next article not in your X-file. This behaviour
may change in future.


Regular expressions
********************

Regular expressions are somewhat complex and not always easy to
understand, but you normally won't need all the features, so don't
worry!   (Syntax in a BNF-like form)

Valid regular expressions:
Terminal symbols are enclosed in ' ', they mean the textual symbol
itself.   Nonterminal symbols are enclosed in < >.   {x} denotes zero
or more occurrences of x.   [x] denotes one or more occurrences of x.
|  means "or"
       <regexp>:== <branch>{'|'<branch>}
       <branch>:== {<piece>}
       <piece>:== <atom>
       <piece>:== <atom>'*'   (matches sequence of 0 or more matches of the atom)
       <piece>:== <atom>'+'   (matches sequence of 1 or more matches of the atom)
       <piece>:== <atom>'?'   (matches a match of the atom or the null-string)
       <atom> :== '('<regexp>')' | <range> | '.' | '^' | '$' | '\'<char> | <char>

       '.' matches ANY character
       '^' matches the NULL-string at the beginning
       '$' matches the NULL-string at the end
       '\' matches the character that immediately follows.

       <range>:== '['<sequence>']'  matches any single character from
                                    the <sequence>
       <sequence>:== [<char>] | <char>'-'<char> | '^'[char]
       '-' means the full list of ASCII characters between the two characters.
       '^' means "not", so it matches all characters not from the rest of the
       sequence.
       To include ']' or '-' in the sequence make it the fist character in the
       sequence.

       <char> :== any valid character (esp. 'A'-'Z','a'-'z','0'-'9')

To override the meta-characters *,-,. etc. use the backslash before
(\* means the asterisk itself). Somehow, this seems not always to work
as   one expects. Didn't have the time to figure it out, yet.

Puuhh! Sorry for that. Now some concrete examples:
       regexp                           match                       no match
       ----------------------------------------------------------------------
       abc                              aabbaaaabc                  abababacb
       Multiple words are allowed       Multiple words are allowed  Multiple
       abc|abd                          abababd                     xyzab
       ([Aa](miga)?)(-*)500             Amiga-500                   500
       ([Aa](miga)?)(-*)500             Aa-500                      A
       ([Aa](miga)?)(-*)500             A-500                       miga
       ab*bc                            abbbbc                      ac
       ab*bc                            abc                         axbbc
       ab+bc                            abbc                        abc
       ab+bc                            abbbbbc                     abq
       ab?bc                            abbc                        abbbc
       ab?bc                            abc                         ac
       ^abc$                            abc                         abcc
       ^abc                             abcc                        aabc
       abc$                             aabc                        abca
       a.c                              abc                         abb
       a.c                              axc                         ac
       a.*c                             axyzc                       axyzd
       ^a(bc+|b[eh])g|.h$               abh                         abcf
       (bc+d$|ef*g.|h?i(j|k))           effgz                       zzz


ArnMaster
**********


Purpose
========

`ArnMaster' creates (small) databases for `Arn'. These databases are
read by `Arn' and inform it about subject, author, lines, followups,
etc.    To get fast and comfortable news-reading these databases are
required.    Because of their clever design they are quite small (ca.
2% of your news-volume)    and can be used on systems with low disk
space, too.    Without `ArnDaemon', you must start `ArnMaster' only
once if you've got    in new articles. It'll run over all groups
containing new articles and    update all databases for the groups.
After `ArnMaster' has    finished, you can start `Arn' and read your
news without any delay.    `Arn' invokes `ArnMaster' only if the
database seems to be    older than the entry in the `active'-file. This
can happen if you    posted a single article and `ArnMaster' did not
run over this group    yet or was not started after posting.

Please note, that the processing speed depends strongly on your
hard-disk    seeking speed (and fragmentation of the news-partition,
which is    unavoidable). `ArnMaster' itself doesn't need much CPU-time
in general    so don't blame me for bad coding....    I use red-black
(i.e. near-balanced) binary trees for managing big groups.

The time that `ArnMaster' needs for scanning will increase if your
news-system doesn't support an ACTIVEFILE.

Don't be alarmed by the long time an initial run can last. This is quite
   normal if you have a lot of articles and all databases have to be
build    from scratch. The speed depends mainly on the fragmentation of
your    News-Harddisk and how many articles in each group are scanned.
  On the same disk I got speed results from 150 articles/min    upto
844 articles/min (excerpt from logfile):

        arnmasterV0.20 (03 Sep 93 22:30:46) Total articles scanned: 4478 in 109/192 groups
        arnmasterV0.20 (03 Sep 93 22:30:47) CREATED 'Lines:' : 117
        arnmasterV0.20 (03 Sep 93 22:30:47) ENDED: Elapsed time 05:18s (844/min)

In every day usage, `ArnMaster' needs only to scan all new articles
and takes advantage of the already existing databases. So typical run
 times are in the minute range. Low scan rates can be a result of only a
   few new articles in each group, so the overhead of getting from
group to    group and opening/reading/writing the database in might be
too big in    respect to the number of new/scanned articles.


`.arnmasterrc'
===============

`ArnMaster' requires a configuration file, it can be the separate
file `.arnmasterrc' in `UULIB:' or if you have only one global
`.arnrc' (i.e. no other `Arn'-user) in your `UULIB:',    you can add
necessary entries for `ArnMaster' there.    However, `.arnmasterrc' has
the higher priority!

The separate configuration file is required if you have several
`Arn' users.

Note that the former keyword `NEWSDIRTYPE'    is no longer valid in
`.arnrc'!

Currently these entries are possible (required entries have a -!-):
`ACTIVEFILE -!-'
     where is your `active'-file and what's its name? See active-file,
          for details about the `ACTIVEFILE'.

`ARNMASTERLOG'
     where should `ArnMaster' have its logfile?

`DOTDIRS'
     (obsolete). See .arnrc, for details.

`NEWSDIR'
     Specify the name of your newsgroups directory.    If this entry is
     missing `UUNEWS:' is default.

`DBASEDIR'
     Destination directory for `.newsdb'-files. This entry    is
     optional, because normally the `.newsdb' files are    kept in the
     `NEWSDIR'. But if you have no permission to    write in `NEWSDIR'
     (e.g. a server), you should specify    this entry to a directory
     on your machine. The top    level directory you give as value must
     exist!

`COUNTLINES'
     If this keyword is present, `ArnMaster' generates the    `Lines:'
     number in databases if missing in article    header. The original
     article header remains untouched!    See also `-L' option.

`UPDATEACTIVE'
     This keyword is like the `-A' option and creates/updates    the
     active-file for you. YOU MUST SPECIFY this keyword    if you have
     AmigaUUCP (Dillon) or any other UUCP-news-    software that
     doesn't support an `active'-file. See also    `-A' option.

     Example:
             ACTIVEFILE    UULIB:news/active
             ARNMASTERLOG  T:logfile
             DOTDIRS       Yes
             COUNTLINES


Usage
======

`ArnMaster' should be placed the directory where your other UUCP
commands   feel comfortable (e.g. `UUCP:c' or `UUCP:bin').   User of
Dillon's AmigaUUCP *MUST* specify the `-A' option   (unless you already
have an `active'-file) or the `UPDATEACTIVE'   keyword in
`.arnmasterrc'.

`ArnMaster' can only be started from a Shell/CLI:
       Arnmaster [-?idALCP(n)X] [-g|G groupname]
   Options:
`-?'
`-i'
     Info about usage and version.

`-d'
     Debug. Some more information is printed during scanning on
     standard-output (stdout).

`-P(n)'
     Set Task Priority to (n). Example: -P-2 sets the priority to   -2.

`-X'
     Deletes ALL databases.   YOU shoud manually delete the copy of the
     `active'-file   `ACTIVE.bak', too!

`-g NAME'
     Scan only group name.

`-G DIRECTORY'
     Scan only special directory and create `.newsdb'.     Normally
     `Arn' uses this option if it is directed to a     directory.

`-A'
     Scan all newsgroups and update your `ACTIVEFILE'.     IMPORTANT:
     This switch *must* be present if you use Dillon's     AmigaUUCP!!

`-L'
     Generates `Lines:' number in databases if missing in article
     header. The original article header remains untouched!     Because
     counting the lines will require some time this     option is NOT
     default. You can alternatively use the     `COUNTLINES' keyword in
     the config-file.

`-C'
     Check for inconsistent databases.     This option forces
     `ArnMaster' to read all the databases     and to rescan articles
     if they are not in the database,     but in the active-range.
     Expired articles are deleted from the database     avoiding
     displaying subjects for non-existent articles.     This option was
     introduced due to a bug in `Arnmaster'     which sometimes caused
     missing datasets in the databases.     THIS OPTION WILL MAKE YOUR
     DATABASES AS ACTUAL AS POSSIBLE.


Action
=======

`ArnMaster' reads your `active'-file and compares it with the    copy
`ACTIVE.bak'.    If there are differences the group is scanned.    [If
you specified the `-A' option or the keyword `UPDATEACTIVE'    is in
the `ArnMaster' config file, `ArnMaster' will scan all groups    that
it found in `ACTIVEFILE'.    If you don't have an `ACTIVEFILE' yet, you
simply should list    ALL newsgroups you get in the `ACTIVEFILE', one
groupname per line. You    maybe can copy the `newsgroups' file from
AmigaUUCP to `ACTIVEFILE', if    there are *no* entries after the
newsgroupname in a line. Don't forget    (although not required) to set
the 'm' flag for moderated groups, once    `ArnMaster' 'created' the
`ACTIVEFILE'].

First, the old database is read if it exists, discarding all expired
entries, then all new articles are scanned and the information is
written back into a new database.    The databases are created in the
group directories by default (or in the    `DBASEDIR' directory
hierarchy) with the name `.newsdb'.

`ArnMaster' assumes that 0 is not a valid    article-number. If all
groups are scanned, the current active file is    copied under the same
name with the extension `.bak'.

        Note:    Databases may contain false information if you delete
     articles    manually (esp. articles with highest numbers). New
     articles may    get old subjects from deleted articles.    You can
     try the `-C' option first, but if this fails    delete all
     databases with `arnmaster -X',    then invoke `ArnMaster' once
     again and all databases should    be corrected.
   To have consistent databases it is recommended to start
`ArnMaster' after each expire-run, too (best with -C)!!


FixActive
----------

For CNews/wCNews/AmigaUUCP Plus users there is a special feature:
You can use `ArnMaster' as `fixactive' (which is faster and    treats
empty groups correct) by simply linking or copying `ArnMaster'    to
`fixactive'. `ArnMaster' only updates the active-file then.


Logfile
========

The main logfile entries look like this:
     arnmasterV0.14 -(09 Dec 92 19:18:37)- group.name:      12/102:102
   The number before the slash are the articles that Arnmaster should
have    scanned (in this example 12). This number is calculated from the
   difference between `ACTIVEFILE' and `ACTIVEFILE.bak'. If there is a 0
   it means that `ArnMaster' looked for expired entries.

The next number shows how many articles `ArnMaster' actually has got in
   its database. The number after the colon shows how many articles it
  should be refering to the `ACTIVEFILE'. If these numbers are not the
same    then there are some expired/deleted articles.


Errors
=======

If you got CORRUPT DATABASES you can *try* to fix it by deleting the
corrupt `.newsdb' and rerun `ArnMaster' on this group (see `-g'
option).    The article number `ArnMaster' reports with corrupt
databases is not    always correct, but you could look for this article
and see if this    article is causing problems because of a strange
header format.

You should report database errors to [e-mail], but only
  if you send an lharced and uuencoded `.newsdb' with the concerning
article    header. You can find out the article number and group in
your `ARNMASTERLOG'.


ArnDaemon
**********

`ArnDaemon' is a program that automatically calls `ArnMaster'   (see
ArnMaster) to update all databases if `rnews' or `expire'   ran and
therefore it's likely that the databases need a refresh.   It's called
daemon, because it should reside in the background and watch   for
those programs. To get `ArnDaemon' started, you should add the
following line in your `startup-sequence' or `user-startup':
`run arndaemon <nil: >nil: -L t:logfile'

The -L option says that the following argument is the name of a logfile
in   which `ArnMaster' writes. If this option is missing, no logfile
will be   used.   The usage is:
       arndaemon [-L logfile][-X program][-A programlist][-P(n)T(n)]

Description of switches:
`-L'
     specify logfile, is explained with `ArnMaster'.

`-A'
     describes the program-list, which specifies the programs on which
     `ArnDaemon'  calls the program to execute (normally `ArnMaster').
     The list is a list of TaskNames separated by commas (spaces are
     *not*  allowed). The default program-list is: `rnews,expire'
     NOTE: ** for AmigaUUCP (Dillon) you should specify
     `rnews,trimnews' **

`-X'
     the program to invoke if one program of the program-list was
     detected.  Default is `ArnMaster'.

`-P'
     set `ArnDaemons' priority to value n. The value must follow
     directly, e.g.  `-P-2' sets the priority to -2.

`-T'
     period in seconds in which `ArnMaster' waits/sleeps after it has
     scanned   the process-list. (Default is 8 seconds).


Theory of working
==================

`ArnDaemon' looks for the programs from the program-list in the
CLI-Process-list and if it finds a program running it'll wait 2 seconds
  and then look again if the program is still running. If so then it'll
  wait another 2 seconds and so on... But if the program is not active
for   a period of 1 minute, `ArnMaster' (or the through `-X' specified
program)   is invoked. `ArnDaemon' waits until the execution has
finished   and then watches every 8 seconds again for the programs.
Note that 8 seconds is normally not enough to detect a single (own)
posting.

To quit `ArnDaemon' just send `CTRL-C' (or `^D',`^E',`^F'),   so
'break'ing the daemon-process from CLI will quit `ArnDaemon'.


Bugs
*****

fmode() is disabled within pager due to a bug in the SAS/C-library, so
you may get strange effects if you have article with CRLF as
EOL-indicator. This causes more serious problems when using `Arn' in
termcap-mode. Sorry, I hope this is fixed soon by SAS.

Another bug may show-up and cause strange behaviour: It's the CMD_CLEAR
command from the console device, which writes 0-bytes into memory
(sometimes in Arn's headerbuffer, so the header seems to be broken).
This bug exists in OS2.04 and is patched by the `setpatch'-program
>=V37.28.

Please send *detailed* bug reports to: `[e-mail]'. These
*must* include the full version string (including date) of `Arn',
respectively `ArnMaster' or `ArnDaemon' and information about your
system (showconfig command output is good for this).

The termcap entries for input (keys) are not used correctly.


Todo-list
**********

Besides this manual needs some revision, there are a lot of functions
I'd like to see in `Arn', but I didn't had the time to implement them,
yet:

   * compacted threads - only the first article of a thread is shown, a
     count for follow-ups on this subject is given, too. Selecting this
     article means to select the whole thread.

   * locking mechanisms - use of lock-files or owndevunit.library for
     avoiding conflicts with news-software.

   * ArnDaemon should use file-notification if possible.

   * Correct reading of cursor keys from termcap

   * NNTP-support.

   * groupname completion.

   * save existing selections at exit.

   * restricted function levels for AUX:-modes

   * mouse/intuition-support.