Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/479a.lha/barn_v2.01/barn.doc

Text File | 1991-02-10 | 15KB | 410 lines

              BARN - Bah's Amiga ReadNews

             Version 2.0 - January 6, 1991

            Written by Jeff Van Epps (aka Lord Bah)


1 OVERVIEW

1.1 Purpose

    BARN is a Usenet news-reader designed to replace "Anews", which comes
with AmigaUUCP 1.03D.  It is intended to behave quite a bit like "rn" from
the UNIX world.

1.2 Features

    Follows subject threads while reading articles.  This means that after
you read one article, you are next presented with the next article in the
newsgroup with the same subject.

    Kill files allow you to weed out messages regarding subject which you
aren't interested in, or from people whose messages waste your time.

    Article pager behaves like "more", with forward and backward paging and
display of percentage of article read.

    Email reply function and post followup article function use editor
specified by the user in a configuration file.    Both functions have an
"include article" option.

    Configuration files allow multiple users to read news on the same
machine, from the same directory, at the same time.


2 REQUIREMENTS

2.1 Hardware

    There are no specific hardware requirements.

2.2 Software

    So far, BARN has only been used on AmigaUUCP 1.03D systems.  But it
should understand any future versions with no problems.

    It does require the "rmail" program to send email.


3 INSTALLATION

3.1 Executable

    Place the "barn" executable wherever you want, most conveniently
somewhere in your path.

3.2 Configuration File

    Edit the supplied "barn.config" file for your site.  Blank lines are
ignored, and any line beginning with a "#" in column 1 is a comment.  Each
line is of the form "variable=value", with no spaces allowed around the
equal sign.

    user=username

    This is the equivalent of UserName in UULIB:Config.  It is the user
name by which the mail system addresses mail to you.  It is used in the
From: line of outgoing mail and news postings.

    node=machinename

    This is the equivalent of NodeName in UULIB:Config.  It is the name by
which the outside world knows your machine.  It is used in the From: line
of outgoing mail and news postings.

    name=Joe User

    This is the equivalent of RealName in UULIB:Config.  It is your full
name.  It is used in the From: line of outgoing mail and news postings.

    domain=.server.company.com

    This is the equivalent of DomainName in UULIB:Config.  It is used in
constructing the From: line of outgoing mail and news postings.  The full
constructed line is:  From: $node!$user@$domain ($name).  I don't consider
this general enough, but I haven't had to come up with anything better yet.

    editor=stevie

    The editor which will be invoked to compose email and followups.

    newsrc=.newsrc

    The name of the file which keeps track of which articles you have read
in each newsgroup.

    kill=KILL

    The name of the kill files.  There will be one global kill file in the
root of the news directory structure whose kill rules will apply to all
articles in all newsgroups.  There is also a local kill file within each
newsgroup which applies to only that newsgroup.  This filename must start
with the letters "KILL".

    signature=UULIB:.signature

    The contents of the signature file will be appended to the outgoing
email and news articles which you compose before you are placed in the
editor.  The contents will NOT be appended after you exit the editor, so
you may delete the signature if you want.

    lines=23
    columns=80

    These define the dimensions of the window in which you will run the
program.  I'm new to Amiga programming and haven't yet bothered to figure
out how to obtain the current window size or adjust to dynamic resizing
during execution.

    noscroll=true

    Setting this variable to any value (even false!) will cause the pager
to start each new page at the top of the window rather than scrolling.

3.3 Multiple Users

    If you will have multiple users certain rules should be followed
regarding configuration files.

    There will be one configuration file for each user.  I recommend naming
the files <username>.config or barn.<usename>.

    Within each config file, the variables "user", "name", "newsrc",
"kill", and "signature" will change.  I recommend setting "newsrc" to
<username>.newsrc and "kill" to KILL.<username>.  The others are up to you.

    The variables "lines", "columns", "noscroll", and "editor" may be
different in each config file depending on individual user preference.

    When the config file to be used is not named "barn.config", you must
specify it on the command line, i.e.

    barn <username>.config

3.4 Initial .newsrc file

    Create a text file called ".newsrc" in the base directory where news is
stored (usually UUNEWS:).  Each line must have the name of a newsgroup
(e.g. comp.sys.amiga), a space and a "0".  This file will be used by BARN
to keep track of which articles have already been read in each newsgroup.

    If you have been using a different newsreader, you may indicate to BARN
which articles you have already read in each newsgroup.  Each line in the
newsrc file contains the newsgroup name, one space, and a sequence of
markers separated by commas.  Each marker is either one number or an
inclusive range of two numbers separated by a dash.  As an example:

    comp.sys.amiga 1-500,512,520-534

    indicates that in newsgroup comp.sys.amiga, articles numbered 1 thru
500, 512, and 520 thru 534 have been read.  Articles numbered 501 thru 511,
513 thru 519, and 535 or higher have not been read.


4 OPERATION

4.1 Newsgroup Selection Level

    BARN will scan the newsgroups listed in the newsrc file in the order in
which they are listed.    Upon encountering each newsgroup, it will descend
into that directory.  For each file in the directory whose name does not
begin with "KILL", it will interpret the filename as an article number and
determine whether or not that article has already been read, based on the
markers for that newsgroup in the newsrc file.    If the article has not been
read, then the headers of the article are read and compared against the
global and local kill files.  If the article is not killed, it is added to
the list of articles to be read.

    When finished scanning the directory, BARN presents the newsgroup name
and the number of unread articles to the user and asks if the user wishes
to read the newsgroup now.  If there are no unread articles, BARN proceeds
to the next newsgroup in the newsrc file without user intervention.

    User commands at the newsgroup selection level:

    a        About BARN.  Prints credits and version.
    c        Catch up.  Mark all articles in the newsgroup as read.
    n        No, don't read this newsgroup now.  Markers are not updated.
    q        Quit BARN.    Writes the newsrc file and exits.
    y        Yes, read this newsgroup now.  Goes to article selection level.
 <space>    Same as Yes.
 h,H,or ?   Prints help for this level.

4.2 Article Selection Level

    The interesting headers of the lowest numbered article are presented to
the user along with the article selection level prompt.

    User commands at the article selection level:

    a        About BARN.  Prints credits and version.
    c        Catch up.  Mark all articles in the newsgroup as read.
    f        Post followup news article.  Uses user's $editor from config.
    F        Followup, including contents of current article in new article.
    j        Junk this article (mark it as read).
    k        Kill articles matching the current subject pattern.
    K        Kill, placing this kill pattern in the local kill file.
    m        Mark this article as unread.
    n        No, don't read this article.  Mark it as read.
    q        Quit this newsgroup.
    r        Reply to article originator via email.  Uses $editor from config.
    R        Reply, including contents of current article.
    w        Write this article.  Prompts for filename.
    y        Yes, read this article now.
 <space>    Yes, read this article now.
 <minus>    Go to previously displayed article, marking it as unread.
 <equal>    Scan subject threads.
    /        Find next article with subject which BARN will prompt for.
    #        Go to article with number BARN will prompt for (if unread).
 h,H,or ?   Print help for this level.

    Unless directed otherwise, BARN will present the next article matching
the current subject thread.  If there is no such article, it will present
the lowest numbered article still unread.

    There are some commands which are less than completely clear, so I'll
go over them.

4.2.1 Followups

    The Subject header is copied from the current article, and other
headers are generated from sources such as the config file, the system date
and time, etc.    These headers are placed into a temporary file named
T:arnreply.  The user's signature is appended to the file, and the user's
editor specified in the config file is started, given the temporary
filename as an argument on the command line.  If the user specified an
including followup (capital F command), then the text of the current
article is placed in the temporary file between the headers and the
signature, with each line prefixed by "> ".

    When the editor returns, the last modification time of the temporary
file is checked.  If it was not modified by the user while in the editor,
the followup operation is aborted.  If it was modified, then the contents
of the temporary file are sent as an email message to "inews@bisco".  This
is a cheap way to post news for me, but I realize that no one else will be
able to use it.  For now, you will have to obtain the source for BARN and
modify this address to one which you can reach which will let you post
news.  Eventually, either I will fix this or someone else will fix this and
I will include the fix in a subsequent release of BARN.

4.2.2 Replies

    Replies are almost identical to followups.    The only difference is that
a To: field is inserted into the temporary file addressing the mail to the
originator of the article before invoking the editor, and the To: field is
extracted again after exiting the editor (allowing the user to change the
destination of the message in the editor, in case the From: field from the
original article was bad).  The "rmail" program is then fed the contents of
the temporary file and given the address as an argument.

    This should probably use the Reply-To: field if one exists, but I
haven't gotten around to it yet.

4.2.3 Kill Files

    Each line of a kill file contains a header name and a regular
expression, such as:

1    Subject: MS-DOS
2    Sender: fool@school
3    Subject: ^Re:
4    Subject: word.*process

(1) kills any article whose subject line contains the string "MS-DOS".  (2)
kills any article whose sender header line contains the string
"fool@school".  (3) kills any article whose subject line begins with "Re:".
(4) kills any article whose subject line contains the string "word",
followed by any number of characters, followed by the string "process".

    Any "interesting" header may be used in a kill file.  Currently,
"interesting" is defined as one of: "Subject", "From", "To", "Date",
"Sender".  A future version of BARN will allow these to be specified in a
file referenced from the config file.

    For a full description of regular expressions, see the regexp man page.

    Any kill file can be edited with a normal editor, but don't leave any
blank lines.  Do not edit the global kill file while BARN is running, and
do not edit a local kill file while BARN is in that newsgroup, or your
changes to the file will be lost when BARN writes out its idea of what the
kill file is.

    When you use the 'K' command to add a subject to the local kill file,
BARN will escape with a backslash any characters in the subject which would
have special meaning to regexp and add a pattern on the front of the
subject which matches any number of "Re:"-type prependages.

4.2.4 Mark as Unread

    The 'm' command is not well-implemented at this time.  It should keep
the article out of the user's sight until all other articles in the
newsgroup have been dealt with.  Instead the user will see the article
again right after the next subject thread is exhausted.

    It will be improved.

4.2.5 Write Article

    This prompts for a filename and then writes the current article to that
filename in the directory from which BARN was executed using the AmigaDOS
"copy" command.

4.2.6 Previous Article

    Returns to the previously displayed article and unmarks ONLY that
article, even if the user has just executed a 'k' - kill command on that
subject.

4.2.7 Scan Subjects

    For each unique subject still unread, displays the first article number
using that subject, the number of reply articles under the same subject,
and the subject text.

4.2.8 Find Subject

    The '/' command sets the current subject thread to whatever the user
enters.  The system behaves just as if an article with that subject had
been read.  This includes using the user-entered subject as a kill pattern.

4.3 Pager Level

    BARN's built-in pager displays the article one page at a time, using
the 'lines' and 'columns' variables from the config file.  Most of the
commands valid at the article selection level are also valid within the
pager.

    User commands at the pager level:

    a        About BARN.  Prints credits and version.
    b        Go backward one page.
 <space>    Go forward one page.
 <return>   Go forward one line.
   <bs>     Go backward one page.
 h,H,or ?   Print help for the pager level.

    and  [fFjkKmnqrRw]    from the article selection level.


5 LIMITATIONS

5.1 Followup

    As noted in section 4.2.1, you will probably not be able to post news
from your system unless you can modify the source code.  There is no method
for posting "base" articles, only followups.

5.2 From Name

    The "From:" line constructed may not be in a form suitable for your
site.

5.3 Article Expiration

    I consider article expiration to be a separate function.  I've supplied
a short shell script that I use to do this; modify to suit.


6 FUTURE ENHANCEMENTS

    Junking a range of article numbers.

    Verbose command to display all article headers.

    Customizable list of "interesting" headers, not just "From", "Date", and
"Subject".

    Use Message-ID to avoid multiple display of cross-posted articles.  I
currently do this with an external program.

    More interesting commands to handle articles which have already been read.


7 SOURCE CODE MODIFICATION

    I use SAS C 5.10.  There are probably some library functions that I use
which Manx does not provide.  I also use Miles Bader's "cc" front-end to
"lc" to sort out all of the compiler options.  You will also need to find
Henry Spencer's "regexp" library to recompile.

    If you do make modifications, please send them to me rather than
releasing them yourself so that I can try to keep track of different
versions.  Thank you for your cooperation.


8 CREDITS

    Uses sendpacket.c and raw.c from the AmigaUUCP distribution, which is
apparently now in the hands of an entity called Dynamyx.  The mentioned source
files were written by CBM and Chuck McManis, respectively.  I'll put my source
in the public domain eventually, but I want to make sure there are no bugs
first.

    Uses the regexp library written by Henry Spencer and copyrighted by
the University of Toronto in 1986.

    All else written by Jeff Van Epps.

    Compiled with SAS C 5.10.