The APM News System

      by Richard M. Marshall and Frank D. Cringle


   News  is  a  means of distributing information to as many people as possible,
and still only sending it to those that want it.  The concepts used in this News
System  are  borrowed  heavily  from  USENET,  a  collection of cooperating UN*X
systems.  USENET is intercontinental in its scale; APM News is more  restricted,
being local to the APMs and the Filestores.

!<Concepts
   Here we establish the terminology to be used in the rest of this document.


   The APM News System  divides  its  news  up  into Topics.  Each topic is then
divided into Articles which users Post.   There are topics created for each area
of discussion.   For example there is a topic GENERAL in which items of  general
interest, for example seminar notices, should be posted.  There is a topic  NEWS
in which discussion about the news system and its programs takes place.  If  you
would like a new topic to be created post an article justifying its existence to
the topic TOPICS.


   The  first article in each topic is a short description of the purpose of the
topic.  This is provided for new users to allow them to decide if they  wish  to
Subscribe  to the topic or not.  Only news in topics to which you are subscribed
is presented in future runs of ReadNews.  Articles which have been in the system
for  a long time are Expired by the News Administrator at regular intervals, but
article number 1 of each topic always remains.

!Page
   Articles  and  other  lengthy  information  are  shown  to the user through a
system similar to UN*X More.  This displays a  page  at  a  time  in  an  easily
readable  manner.    This  document will use the pseudo verb To More to indicate
that this is being used.
!>
!<Precursors
Two operations worth performing before using the news system,  and  some  useful
tips.

!<Terminal Type Setting
   Since the news system uses advanced screen driving it needs to know what kind
of terminal you are on.  The default is Visual 200.

If you are not using a Visual 200 make the one of the following symbol 
assignments:

   for Wyse 75                Terminal=WY75
   for Digital VT220          Terminal=VT220
   for Visual 55              Terminal=Visual55

to restore to Visual 200      Terminal=Visual200
!>
!<Editor Setting
   The  News  system  makes frequent use of an Editor.  This can be either IE or
VECCE.  IE is the default, but the symbol definition:

      Editor=VECCE

   or

      Editor=ECCE

results in VECCE being used instead.
!>
!<Seen File
   To  record what articles you have already read the News System creates a file
NEWS.SEEN  in  your  login  directory.  This is an organism readable file in the
same format as the corresponding UN*X file.  You should never have to edit  this
file, but it can be deleted if you want to start afresh.

   In the description of the programs this is referred to as the "Seen File".
!>
!<Lock-outs
   When posting to a topic you will occasionally get the message:

The topic <whatever> is being used at the moment, retrying....

printed out.  This means that someone else is using the topic file and the  news
system  cannot write to it.  There are ten retries spaced at 6 seconds each.  If
this fails the article you were going to post  is  filed  for  you  and  can  be
submitted with PostNews at a later date.
!>
!>
!<Commands
   The news system is composed of three commands for the appropriate operations.
These  operations  are  checking  to  see  if  there  is any fresh news, reading
incoming news and replying to it, and originating  new  items.    The  following
commands implement these functions:

!<CheckNews
   This program should be placed in your LOGIN.COM file.   It tells you  if  any
articles  have  been  posted  which  you  have  not yet seen.  Your SEEN file is
compared with the current contents of the groups you are subscribed to.

   Users with more than one directory can check the  SEEN  file  in  their  home
directory by giving their "real" user name as a parameter.

!>
!<ReadNews
   This  is  the  main  program  of  the news suite.  It provides facilities for
reading  both  new  and  old  articles,  replying  to  or  posting articles, and
examination of each topic.  As this program uses advanced screen driving  please
read  the  section  in  precursors  on  terminal  types before attempting to use
ReadNews.
  
!<First Time Users
   The  first  time  you  use ReadNews it prints out a shortened version of this
help information, just enough to let you progress through the first  attempt  at
reading  the  stuff.      This  message is only printed out if you do not have a
NEWS.SEEN file, so if you delete it you will get it back.  It is  worth  reading
the document if you have not read every item in this help information.

   It is probably worth explaining a bit about the user interface of ReadNews as
it  is  designed for a personal machine rather than a mainframe at the other end
of a long haul network.   The first thing to  note  is  that  all  commands  are
single  letters and take immediate effect - you do not need to press return.  If
you get confused, or there is a pause in the program the worst thing you can  do
is  try  typing  rubbish  ahead  as  this will only confuse you more and more as
things flash past!  It is also worth noting that case is NOT significant  within
ReadNews - for example 'n' is the same as 'N'.

   The basic command set is the four arrow keys and the  space  bar.    This  is
all  that is normally needed to use ReadNews.  The idea is that the news is laid
out like a newspaper.   Each topic is a column of articles, the  newer  articles
are  at  the  bottom  of  the column so that DOWN advances and UP retreats.  The
horizontal keys move between topics, with the newer topics to the right.   Space
will always give the default command - this obviously varies from place to place
but  it  usually  means  Yes.   If you are viewing a long article and the prompt
"--More--" appears at anytime SPACE will move you to the next  page  (Moring  as
described in Concepts above).    There will be a percentage shown after the More
prompt; this shows how much of the article you have already read.

   At any time the command 'Q' is valid.  In response to "--More--"  this  stops
showing  you  the  article and moves to the command prompt.   In response to any
other command prompt (not "Press any key to Continue") 'Q' will leave  ReadNews.
Anything that you have read will be marked as read, but later items remain.  The
command Control-Y aborts ReadNews at any time, not marking any articles as read.
Notice that Control-T is disabled - this is intentional.

   This should be enough knowledge to actually  use  the  program  in  a  simple
fashion,  but  quite  a  number  of  other  commands  are  available.  These are
described in the next few sections.  The last simple command to describe here is
'?' - it always outlines the available commands.
!>
!<New Topics
   When  you  first  come  to  use the news facility all the topics are new, and
every now and then new ones will be added.   When  you  first  encounter  a  new
topic  you  will  be  shown  the  introductory  message and asked if you want to
subscribe.  You can type the following commands to this:

   SPACE,  Y       - Yes, I want to subscribe.  If there are any articles in the
                     topic you will start to read them (see next section).    If
                     there are none you will move to the next topic.

   N               - No, I don't want to subscribe.  This means  that  you  will
                     not see any  articles  posted  to  this  topic  unless  you
                     specifically  ask  to  see them.  This process is described
                     later.

   Q               - Quit the ReadNews program.

   Left            - Move back to previous topic.
   Right           - Move to next topic.

                        Neither  of  these  commands change the topic status, so
                        the next time the topic is encountered you will be asked
                        if you wish to subscribe.
!>
!<Reading Articles
   When an article is first displayed a header is shown.  This  header  contains
the name of the sender, where it was sent from and when, how long it is and what
its  subject  is.   From this you can decide if you want to read it or not.  The
prompt  "Action:"  should now have appeared at the top right of the screen.

   Pressing  SPACE at this point Mores the article to the terminal, once More is
done then pressing space moves on to the next unread article.    When  the  last
unread article in the topic has been read you are moved to the next topic.

   Pressing N moves on directly without reading the article, but it is marked as
being read - this is useful when an article is of no interest to you.

   Numerous  other commands are available to move around and operate on articles
and topics.  These are outlined in the next two sections.
!>
!<Other Article Operations

   The following classes of commands operate on articles within a topic.

!<Movement

Up       - Last Article.  This command moves to the previous article, whether or
           not it had been read.   This command will move back  onto  message  1
           but no further.
 
Down     - Next Article.  This command moves to the next article, whether or not
           it  had been read.  This command moves onto the next topic at the end
           of a topic.

#        - Move to a particular article, giving its number followed by RETURN.
           Simply typing the number has the same effect.

<        - This command moves to Article number 1 in the current topic.

>        - This moves to the last article in the current topic.
!>
!<Answering

   You can request to Reply to an article with the R command.  In this case  the
edit to enter the message starts with a RE subject and the number of the article
being  replied to.  It is also possible to simply post an original item with the
P command.

   Neither of these commands takes effect immediately.  All answers are composed
at  the  end  of  the  topic.   There is a good reason for this; it stops people
sending in replies that may already be there as you are  "forced"  to  read  the
rest of the articles following the one you are answering.

   In  the  case  of  Reply  the  editor  of your choice is called with both the
subject loaded and a buffer called ORIGINAL, in the case of IE, or the secondary
input in VECCE containing the original message.  To allow you to  clearly  quote
the  message  each  line  starts  with "> ", or ">> " for multiple levels.

   The user name, date, and location are prepended to the message  automatically
and  cannot  be changed.   If a file NEWS.SIG exists in your directory then this
is added after the article.  This is very useful and  could  contain  a  message
like:

      Cheers,
             Alex

and saves typing it every time you post an article.  A small separator (----) is
placed between the article and the signature, so you do  not  need  one  in  the
signature file.
!>
!<Others

C          -  Cancel an article submitted by yourself.  This makes a hole in the
              directory of articles where the message used to be.  Articles  can
              not  be  recovered.  The command prompts Really? to which you must
              type Y to take action.  After cancelling you must explicitly  move
              to the next article.

S          - Save an article in a file.   This prompts for a file name and  then
             either  creates  the  file with the article in it, or appends it to
             an existing file.

I, E       - Ignore an Article, leave it for reading later.  E is  provided  for
             UN*X compatibility.

D          - Directory of Articles.  This  command  Mores  a  list  of  all  the
             articles  (number, sender, subject) to the terminal.  It provides a
             summary of what is in the topic.  
!>
!>
!<Topic Operations

The following commands operate on Topics, rather than articles within a topic.

!<Movement

   These commands move from one topic to another.

Left  - Last Topic.   This moves back to any unread messages in previous topics.
        If there are no messages left you are informed of this and moved  on  to
        the next unread message.

Right - Next Topic.  This command skips over the rest of the topic, leaving  any
        articles  unread.        This command enables you to reply to an article
        immediately  when  used  with  R.    This  practice,  however,  is   not
        recommended.      Normally  the  Left command is used after a use of the
        Right command.

!>
!<Others

U     - Unsubcribe to this topic.  This moves onto the next topic, and marks the
        current one as being of no interest to you so that  subsequent  articles
        posted to this topic will not be seen unless specifically asked for.

T      - Topics Operations.    This command shows all the topics available, with
         those that you are subscribed to highlighted.   The  cursor  keys  move
         around within this menu and the following subcommands may be used:

            SPACE      - Change subscription.  If you were previously subscribed
                         to a topic you will be unsubscribed, and moved onto the
                         next  topic  in  the  list.    If  you  move  onto   an
                         unsubscribed   one   and   hit   SPACE   you   will  be
                         resubscribed.

            I          - This displays the introductory message  for  the  topic
                         with the cursor on it.

            D          - This lists all the articles (number, from, subject) via
                         More.    This  command is not shown on the mini-menu at
                         the top of the screen.

            RETURN     - This selects the topic under the cursor  as  the  topic
                         for  reading  and  enters  it  at article one.  Reading
                         articles no longer effects the Seen  File,  and    read
                         ones become immediately visible.

            X          - This returns to perusing articles in the topic that the
                         command was issued in.
!>
!>
!<Other commands

?     - Print out a one page summary of this information

Q     - Quit ReadNews, recording which articles have been read in the Seen File.

^Y    - Abort, do not write back the Seen File.
!>
!<Command Line Options

   The following options are available at the command line:


      <topic>        - This means read only the specified topic.  The default is
                       the special topic ALL which matches  every  topic.    For
                       UN*X  freakies  it  is  possible to say "-n <topic>" with
                       the same effect as without the "-n"!

      -Ignore        - This means ignore the Seen File, and make all  previously
                       read  articles  visible  again.    For UN*X compatibility
                       there is also the qualifier "-x" which  is  the  same  as
                       "-Ignore".

      -Reverse       - This means start at  the  end  of  the  topics  and  work
                       backwards through the articles.

      -User=<user>   - This  specifies  the  real  user whose Seen File is to be
                       used.  This is very useful for people who are  frequently
                       logged in under different identities.
!>
!>
!<PostNews
   This  program  is  used  for  posting articles on a new subtopic, rather than
posting replies or followups to existing articles.

!<Command Line Options
   PostNews supports the following command line options:

Topic:

   This is the name of the news topic to which the  article  is  to  be  posted.
This  is a compulsory parameter, and the program will prompt for it if it is not
specified on the command line.


File:

   This is the name of the file containing the article to be posted.  If no file
name  is  given (the normal case) then the Editor is called to allow the article
to  be  created.  The editor will startup with the word "Subject: " at the start
of the file.

   The first line of the input file is taken as the subject line.  If  the  file
contains  Formfeed  /  Newline  sequences,  these  are  interpreted  as  message
separators, and if a message starts with a VMS Mail style header (From:, To: and
Subj: lines), the subject line is extracted from this header.

   The user name, date, and location are prepended to the message  automatically
and  cannot  be changed.   If a file NEWS.SIG exists in your directory then this
is added after the article.  This is very useful and  could  contain  a  message
like:

      Cheers,
             Alex

and saves typing it every time you post an article.  A small separator (----) is
placed between the article and the signature, so you do  not  need  one  in  the
signature file.
!>
!>
!>
!<Hardcopy
   To  allow  the  generation  of  hard  copy  of news items the program NToL is
provided.  This stands for News To Layout and can produce either a Version 1  or
Version 1.5 layout file.

   To use the program the command is:
   
         News:NToL <topic>/<output>

   <topic>  should  be the name of an existing topic. The match all topic ALL is
            not allowed in this program.
   <output> is the name of the file to put the Layout into.  If  this  parameter
            is ommitted the output goes to <topic>.LAY.

   The following qualifiers are available:

      -LASER    specifies that Layout 1.5 is to be generated

      -CONTENTS specifies that a contents page is to be generated

      -CONFIRM  means that the user is shown the number, from and subject of
                every article in the topic and is asked whether to include
                it or not.

      -PAGE     results in a fresh page being taken for each article

      -First    The number of the first article to be printed, defaults to 1

      -Last     The number of the last article to be printed, defaults to the
                last message in the topic

   The output file is eminently suited to editing.
!>
!<Administration
   This  information  is  for  News  Administrators  only, and cannot be used by
ordinary mortals as it is all internally protected.

!<Create
   This program is for creating new topics.  The NEWS password  must  be  quoted
before it is used.

   The  parameters  are  the  same  as  PostNews, i.e. the name of the topic and
optionally  a file (defaulting to calling the editor).  The first message should
explain the purpose of the topic.  This message (up to the first empty line)  is
presented  to  users the first time they see the topic, with the "subscribe Y/N"
question.    Blank  lines  in  the  message  should  contain at least one space,
otherwise  they  will  terminate the display - the message is in fact  a  pseudo
header.
!>
!<Expire

   This command is yet to be needed/written!

!>
!<Crunch
   This program allows cancelled or expired messages to be finally removed  from
topic files.  The NEWS password must be quoted before it is used.

   The parameter is either a topic name or "ALL", with obvious meaning.
!>
!>