                       The APL Newsreader

                         by Jim Weigang

                         November 1994


The APL Newsreader allows you to browse and read messages or newsgroup
postings stored on your IBM PC-compatible (80386 or higher) computer.
It displays a directory of the messages, including the date, author, and
subject, and lets you easily step from message to message.  Searching
commands allow you to scan either the directory or the message text for
phrases.  The directory can be sorted by date, author, or by subject
(allowing you to follow a series of messages on a particular topic).
APL messages can be transliterated from {keyword} form to APL symbols at
the touch of a key.  Messages can be appended to a DOS file for further
processing.

   The newsreader is packaged with the archive of the USENET
comp.lang.apl newsgroup from 1989 to October, 1994.  The intent in
distributing this archive is to broaden the awareness in the APL
community of this communication resource, to give new users a chance to
see what has been discussed over the years, and to point out that
postings to the group are not as transitory as they appear on the net
(where they typically disappear within a week).  Coupled with the
archive, comp.lang.apl is, in effect, an electronic APL journal to which
virtually anyone can subscribe and contribute.  The archive is
maintained by Lee J. Dickey at the University of Waterloo and can be
downloaded by anyone using the Unix "ftp" program to connect to the
computer known as "watserv1.waterloo.edu".  

   The author would like to thank Lee Dickey for maintaining the
comp.lang.apl archive, and to thank Manugistics, Inc. (a.k.a. STSC) for
generously providing the APL*PLUS II/386 run-time interpreter that is
used by the newsreader.


System Requirements

To run this software, you need DOS 3.3 or higher, an 80386 (or '486 or
Pentium) CPU, at least 2 megabytes of free extended or expanded memory
(RAM), an EGA or VGA display, and about 1 megabyte of disk space.  To
unpack the full comp.lang.apl archive, you will need an additional 14
megabytes of disk space.


Startup

To start the newsreader, enter the following command from DOS:

   aplnews

(If you get an error, type "cd \aplnews" and then "aplnews".)  To leave
the newsreader, type "exit" from command mode.


Command Mode

When the newsreader starts, you are placed in a DOS-like command
interpreter.  The prompt in this mode is similar to the usual DOS prompt
(it displays the current drive and directory) but with an extra ">" at
the end to remind you that you're not really in DOS.  In this mode, you
can use the "dir" command to display the names of files, or use the "cd"
command to change the current directory.  These commands work pretty
much the same way as in DOS.  To start the newsreader, use the command
"news" followed by the name of the news file.  For example, the command:

        news abc.txt

begins reading the file "abc.txt" in the current directory.  You can
specify a different drive and directory in the usual way (e.g., "news
d:\mynews\news39.txt").

   The comp.lang.apl archive is supplied on the following files:

        cla91   - archive for 1989 through 1991
        cla92   - archive for 1992
        cla93   - archive for 1993
        cla94   - archive for 1994, through October

These files have no filename extension, so to read one you would issue a
command such as "news cla94".  Each of these files has a corresponding
"directory file", which has the same name but with the extension ".dir"
(e.g, cla94.dir).  If the directory file does not exist, it will be
generated automatically by the newsreader.  Because this is a somewhat
time-consuming process, ready-made directory files are supplied for the
archive.

   
Newsreader Basics

When you issue a "news" command, the newsreader displays the directory
for the news file.  Each line of the directory gives the message number,
date of posting, number of lines in the message, author and subject of
the message.  For example:

 [917]   1 Jul 94  (40)  Jim Weigang        Distributing c.l.a archive
                
 Msg #   Date      # of  Author             Subject
                   Lines

A cursor bar highlights one entry in the directory.  Use the cursor
arrow keys to move the bar up or down.  Use the PgUp or PgDn keys to
page up or down through the directory.  To view the highlighted message,
press the Enter key or the Space bar.  Press Escape to return to the
directory screen.

   When you are viewing a message, the status line at the bottom of the
screen shows the directory entry for the message.  You can scroll
through the message using the cursor arrow or PgUp/PgDn keys.  Holding
down the Ctrl key while pressing the cursor arrow keys moves faster
through the text.  You can scroll horizontally with the left and right
arrow keys.  The Space bar advances you to the next screen of the
message, or, if you are at the end of a message, to the next message.  A
del symbol is displayed at the bottom of each message to mark the end of
the message.

   From within the newsreader, press the F1 key for a summary of the
available commands.  To exit from the newsreader, press Escape from
the directory screen.  This returns you to command mode, where you
can type "exit" to return to DOS.


Movement While Viewing a Message

When you are viewing a message, pressing the space bar moves one screen
down within the message, or to the next message if the end-of-message
marker (a del symbol) is visible.  Thus, to read everything in an
archive, you can just keep hitting the space bar.  Press the Enter key
to move to the next message regardless of where you are in the message.
Backspace is the opposite of space: it move to the previous screen, or,
if you are at the top of a message, it goes to the previous message.
Ctrl-Backspace is the opposite of Enter; it goes to the previous message
regardless of where you are.

   Home moves to the left margin of the message; End moves to the right
margin.  Ctrl-Home moves to the top line, Ctrl-End to the bottom of the
message.  Moving to the top line will reveal some usually uninteresting
header lines that the newsreader places above the starting screen.

   
Mouse

Limited mouse support is provided, allowing the mouse buttons to be used
as a convenient "remote control".  The left (primary) mouse button is
equivalent to Space--it advances to the next screen.  The right button
is equivalent to Backspace, moving back a screen.  Double-clicking the
left or right buttons is equivalent to Enter or Ctrl-Backspace, moving
to the next or previous message.


Wrapping Long Lines

If a message contains lines that are more than 80 columns wide, you can
either scroll sideways using the left or right cursor arrow keys, or you
can press Ctrl-W to the wrap long lines to a width of 80 columns.


Tagging

A message can be "tagged" by pressing Ctrl-T.  An asterisk (*) appears
to the left of the directory entry to indicate that the message is
tagged.  Press Ctrl-T again to untag the message.  Any number of
messages may be tagged.  The searching commands use tagging to indicate
which messages contain the target phrase.

   You can step from one tagged message to another using Ctrl-N (next)
or Ctrl-P (previous).  This works in either the directory screen or the
message screen.  Untagged messages are skipped over.

   To untag all messages, press Ctrl-U.  A prompt asks for confirmation
before the tagging is cleared.


Sorting

You can sort the directory by pressing Ctrl-O (order).  A prompt asks if
you want to sort by Date, Author, Subject, Thread, or Nothing.  Press
either D, A, S, T, or N.  Sorting by subject arranges all messages on a
given topic together, allowing you to follow the discussion without
intervening messages on other topics.  Sorting by "thread" is an
especially useful mix between subject and date sort: the messages are
arranged by subject, by date within each subject, and with the oldest
subjects first (not in alphabetical order).  Sorting by nothing displays
the messages in the order they're found in the file, which may be
something of a jumble.  To sort by more than one key, first sort by the
secondary key and then sort again by the primary key.


Searching

To search the directory for a phrase, press Ctrl-L (locate).  You will
be prompted to enter the target phrase.  The search is not sensitive to
case, and it is a phrase search, not a word search.  (E.g., when searching
for "the", a match will be found within the word "them".)  Directory
entries containing the phrase will be tagged, and the cursor will be
moved down to the first entry containing the phrase.

Note:  The tagging is "or-ed" into the current selection.  That is,
additional directory entries are tagged without clearing the previous
tags.  Use Ctrl-U (untag) before Ctrl-L if you want to select only
messages matching the current phrase.

   To search the full message file for a phrase, press Ctrl-S (search).
Again, you will be prompted to enter the search phrase.  A progress
report is displayed as the message file is searched, because this type
of search takes much longer than a directory search.  You can interrupt
a message file search by pressing any key during the search.  Any
occurrences that were found before interruption will be tagged as if the
search finished normally.

   You can search for more than one phrase at a time by giving an
expression as the search phrase.  An expression consists of quoted
strings connected by "and" or "or" symbols.  For example, the following
expression:

         'nested' ^ 'array'

finds messages that contain both the phrase "nested" and "array".  The
expression may be arbitrarily complex and may include parentheses.  It
is evaluated by replacing each quoted string with an expression that
asks, "Does this phrase occur in the message?", and then evaluating the
whole thing as an APL expression.  Ergo, the order of execution is
right-to-left, precedence-free.  (And you can use operations like not
equal, greater and less as you would in any APL Boolean expression.)

Note:  The "or" symbol is entered by pressing Alt-9.  "Nor" is
Alt-Shift-9, "nand" is Alt-Shift-0, and not equal is Alt-8.

Note:  Any search phrase that begins with a left parenthesis or a single
quote is assumed to be an expression.  To search for a simple phrase
that begins with left parenthesis or quote, you must enclose the phrase
in quotes, as in '(By' or '''Press'.


Exporting Messages

To write the text of a message to a DOS file, press Ctrl-V while you are
viewing the message.  You will be prompted to enter the name of the
file.  The message will be appended to the end of the file, followed
by an ASCII Record Separator character (decimal 30) on a line by itself.

Note:  After you use Ctrl-V once, the file name prompt displayed for the
second and later uses will include a default response that is the name
you entered for the previous Ctrl-V command.  To append messages
repeatedly to the same file, you need press only Ctrl-V and Enter after
the first Ctrl-V.  To append to a different file, however, you must
remember to erase the default response before entering the new file
name.


Editing Objects

To edit an APL variable or a DOS file from within the newsreader, press
Ctrl-I.  You will be prompted to enter the name of the variable or file.
To exit from the editor, use one of the following keystrokes:

   Ctrl-E    - save changes and exit
   Ctrl-Q    - discard changes and exit
   Ctrl-X    - suspend editing temporarily without saving changes

To return to an edit session that you suspend with Ctrl-X, press
Ctrl-Shift-N or the F8 function key.  Beware that changes will be lost
if you leave APL with suspended edit sessions.


APL Keywords

When you are viewing a message, you can press Ctrl-A (APL) to translate
the {keywords} in the message to APL symbols.  (These keywords are the
ones produced by the programs in the APLASCII workspace, which is
available via ftp in the watserv1.waterloo.edu archive.)  Unrecognized
keywords are left in place, without any warning being displayed.  The
message is changed only while you are viewing it, not permanently.
(However, if you write the message to a file using Ctrl-V, the APL
symbols will be written.)  To go back to {keywords}, press Escape,
Enter.


Customizing Colors

A file named APLNEWS.INI is used to determine the colors used by the
newsreader.  Edit this file using a standard text editor to adjust the
colors.  Comments within the file explain the format.  This file also
contains the SortOrder parameter, which is used as the default sort
order when building the directory for a new file.

                              - End -

