home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Mega Top 1
/
os2_top1.zip
/
os2_top1
/
APPS
/
DATACOM
/
READERS
/
YRN2_068
/
YARN.DOC
< prev
next >
Wrap
Text File
|
1994-06-23
|
31KB
|
911 lines
Yarn User Manual - version 0.68
Yarn - offline news storage and reading system
Copyright (c) 1994 Chin Huang
Permission to copy and distribute this material for any purpose and
without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies. THE AUTHOR MAKES NO
REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
PURPOSE. IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES. THE AUTHOR WILL ASSUME NO LIABILITY FOR DAMAGES EITHER FROM
THE DIRECT USE OF THIS PRODUCT OR AS A CONSEQUENCE OF THE USE OF THIS
PRODUCT.
INTRODUCTION
Yarn is a suite of programs for your personal computer, used to store and
read USENET news downloaded from a USENET host.
FEATURES
- An import program inserts USENET articles into a "news base" from
Simple Offline USENET Packet (SOUP) format. A mail filter moves
incoming mail to specific folders or deletes incoming mail based on a
set of user defined rules.
- For each newsgroup, you specify the number of days to keep articles,
after which, an expire program deletes them. However, articles
containing an Expires: header are deleted on the date specified in the
header.
- The news base stores only one copy of a cross-posted article. The news
base implementation stores multiple articles per file.
- The Yarn news reader presents articles in threads arranged by Message-
ID and References. The reader program generates SOUP reply packets.
- Multiple users are supported by storing separate configuration files
for each user.
SYSTEM REQUIREMENTS
- MS-DOS 3.0 or higher
- 80386 compatible CPU or better to run the 32-bit DOS extender version
of the reader program. A real mode version of the reader is also
included for non-386 systems.
- a lot of hard disk storage, depending on how much news you want to
keep. For example, the author subscribes to 120 newsgroups including
some binaries and sources groups, keeping most articles for 7 days.
The amount of disk space used is 40 megabytes.
1
Yarn User Manual - version 0.68
INSTALLATION
INSTALL YARN DIRECTORY
Unpack the files from the Yarn package into a directory. Run the command
install [drive:]directory
where [drive:]directory specifies where to install the Yarn data
directory. This directory is created if it doesn't already exist. Choose
a disk drive with a lot of free space because the news base will be stored
here. In this document, this directory will be called the $YARN
directory.
SET UP USER DIRECTORY
To set up a user directory where Yarn will store your user information,
run the command
adduser
A form appears in which you fill in the required user information.
+ Add User ------------------------------------------------------------+
| |
| Home directory: C:\JIM |
| |
| User ID: jsmith |
| |
| Host system: netcom.com |
| |
| User's full name: Jim Smith |
| |
| Editor program: edit |
| |
| Reply packet file: C:\UPLOAD\IOXR.ZIP |
| |
+----------------------------------------------------------------------+
Home directory
Specify the directory where Yarn will store your user information.
This directory is created if it doesn't already exist. In this
document, this directory will be called the $HOME directory.
User ID
Set this to your login name on the host from which you download and
upload USENET news.
Host system
Set this to the full domain name of your host.
User's full name
Set this to your full name. This is the name that appears in
parentheses on the From: header in messages you send.
2
Yarn User Manual - version 0.68
Editor program
Set the name of the editor program to run when you send messages.
The program must be in your PATH.
Reply packet file
Specify the full path of the SOUP reply packet file where your
outgoing messages are stored. If the reply packet file does not
exist, it is created when you post an article or send a mail message
from the reader program. When you exit the reader program, the reply
packet is ready to upload to your host.
The program writes the user information to a configuration file named
$HOME\yarn\config. This document refers to other configuration settings
also stored in this file. If you want to change those settings, you have
to edit the configuration file with a text editor.
SET TIME ZONE
Set the environment variable TZ to your time zone. The format of the TZ
string is
zzz[+/-]h[h][ddd]
zzz is a three character field representing the name of the time zone.
[+/-]h[h] is an optionally signed number representing the local time
zone's difference from Greenwich Mean Time (GMT) in hours. Positive
numbers adjust westward from GMT. Negative numbers adjust eastward from
GMT.
ddd is an optional three character field that represents the name of the
local time zone's daylight saving time.
If no TZ environment variable is set, a default TZ=EST5EDT is assumed.
UPDATE SYSTEM FILES
Put these SET commands in your AUTOEXEC.BAT file to ensure the environment
settings persist after the next time you reboot your system. (If you are
installing Yarn for OS/2, put the SET commands in your CONFIG.SYS file
instead.) Use the settings determined above for the values appearing to
the right of the equal signs.
SET YARN=$YARN
SET HOME=$HOME
SET TZ=EST5EDT
USING THE MAIL FILTER
The mail filter looks at incoming mail messages and process the messages
based on a set of rules you define. You can set up a rule that
automatically moves messages you receive from a mailing list to a specific
folder. Or, you can automatically delete messages from a specific user so
that you don't even see messages from that user.
3
Yarn User Manual - version 0.68
Run the filter program to set up the filter rules. A list of filter rules
appears. To add a filter rule, press the [Ins] key. The mail rule form
appears.
+ Mail Rule ----------------------------------------------------------+
| |
| Rule name: Yarn Mailing List |
| |
| Search in: ( ) From Search for: yarn-list |
| (*) To Match case: No |
| ( ) Subject |
| |
| Action: (*) Move to folder/newsgroup: yarn |
| ( ) Delete |
| |
+---------------------------------------------------------------------+
Rule name
Enter a name for the rule. Filter rules are processed in sorted
order by rule name. Each rule is checked in turn until a match is
found. If no rules match, the message is moved to the INBOX folder.
Search in
Select the mail header to search. If you select "To", then the To:
and Cc: headers are searched.
Search for
Enter the string to search for in the selected header.
Match case
Set the field to Yes if you want the search to be case sensitive.
Action
Select "Move to folder/newsgroup" if you want to move the message to
a specific folder or newsgroup. If the specified name is a newsgroup
in the active list, the message is moved to the newsgroup, otherwise
the message is moved to the named folder. Select "Delete" if you
want to automatically delete the message.
SET UP OTHER USERS
To set up another user, run the adduser command, and specify a different
home directory. To run Yarn as that user, set the HOME environment
variable to the user's home directory.
ENVIRONMENT
These enviroment variables modify the behaviour of Yarn if they are set.
EDITOR Specifies the external editor program, overriding the editor
specified in the configuration file.
YARNRC Specifies an alternate configuration file to read instead of the
default $HOME\yarn\config.
4
Yarn User Manual - version 0.68
CREATE LIST OF ACTIVE NEWSGROUPS
You must inform Yarn of every newsgroup you will be importing by running
the command
newgroup <name> <keepDays> [<maxDays>]
where <name> is the newsgroup name and <keepDays> is the number of days
that articles in the newsgroup will be kept before the expire program
deletes them. If you later want to change the number of keep days, run
this command again, specifying the new keep days value.
The optional parameter <maxDays> is the absolute maximum number of days an
article will be kept. Some articles may have an Expires: header which
contains a date far in the future. Normally the article will be kept
until that date, but if you set this parameter to a value greater than
zero, the article will be kept only for the specified number of days.
Instead of naming a newsgroup on the command line, you can specify a text
file containing a list of newsgroup names. Every newsgroup listed in the
file is assigned the keep days value.
newgroup @<file> <keepDays> [<maxDays>]
REMOVE NEWSGROUP FROM ACTIVE LIST
To remove a newsgroup from the active newsgroup list, run the command
rmgroup <name>
where <name> is the newsgroup name.
HOW TO ADD PGP SUPPORT
Yarn contains hooks to external cryptographic programs. The standard Yarn
distribution is set up to run Pretty Good Privacy (PGP). Ensure that the
PGP executable is in the execution PATH. Uncomment the "secret-sign",
"encrypt", "decrypt" and "decrypt-view" lines in the Yarn configuration
file. You also have to install the LIST.COM program into a directory in
the PATH. The PGPD.BAT batch file specified by "decrypt-view" runs the
LIST.COM program to view the plaintext. Yarn is now configured to use the
PGP privacy and authentication functions.
OPERATION
IMPORT NEWS AND MAIL
To import messages from SOUP format, run
import <file>
where <file> is the path of the SOUP file. The import program takes these
options.
5
Yarn User Manual - version 0.68
-n Do not delete the packet file.
-q Operate in quiet mode. Do not list imported article numbers.
-r Import rnews batches instead of SOUP files.
If the import program finds a newsgroup in the packet that is not in the
active newsgroup list, it adds the newsgroup to the active list. The keep
days and maximum keep days for the added newsgroup are specified by the
"keep" and "max-keep" settings respectively in the configuration file.
For example, if the configuration file contains the settings
keep=7
max-keep=30
then articles are normally kept in the newsgroup for 7 days and absolutely
not more than 30 days.
EXPIRE NEWS
Periodically run the expire program to delete old articles from the news
base. To expire old articles from all newsgroups, run the command
expire
To expire old articles from specific newsgroups, list the newsgroups on
the command line. For example:
expire comp.answers news.answers
To delete all read articles in all newsgroups, run
expire -r
To delete read articles from specific newsgroups, run expire with the -r
option and list the newsgroups on the command line. For example:
expire -r comp.answers news.answers
The program may expire newsgroups in addition to the newsgroups you
specified if an expired article was crossposted to multiple newsgroups.
You can specify a text file containing a list of newsgroups to expire.
Run expire with the argument
@<file>
on the command line, where <file> is the file path.
The expire program accepts these options:
-d<n> Assume it is <n> days in the future. Use this option to expire
articles before they normally would have been expired.
6
Yarn User Manual - version 0.68
-n Do not actually delete any articles. Used for testing.
-r Delete read articles.
READ NEWS
Run the yarn program to read news and mail. The yarnx program is a
version of the reader with a 32-bit DOS extender and it can list much more
articles in a newsgroup. It requires an 80386 compatible CPU or better.
It also needs to find the file DOS4GW.EXE in a directory in your PATH.
The reader program operates in several modes -- the newsgroup selection
level, the article selection level, and the article reading level.
In the newsgroup selection level, yarn displays a window listing the
newsgroups you are subscribed to along with the number of unread articles
in each newsgroup. You can subscribe, unsubscribe or rearrange the order
of newsgroups in this list. Press the [Ins] key to subscribe to a
newsgroup. This brings up a list of unsubscribed newsgroups. To make a
selection, use the arrow keys to move the highlight to the newsgroup, and
then press the [Enter] key. The selected newsgroup is inserted into the
subscribed newsgroup list. Press the [Del] key to unsubscribe from the
highlighted newsgroup. To move a newsgroup in the list, press the [Del]
key to remove it, position the highlight to the desired location, then
press the [Ins] key and reinsert the newsgroup.
By selecting a newsgroup, you go to the article selection level, where
yarn presents a list of the subjects of each article. You can select an
article to read from this list, taking you to the article reading level.
NEWSGROUP SELECTION LEVEL
These commands are available in the newsgroup selection level.
Down Arrow, Ctrl-N
Move to the next newsgroup.
Up Arrow, Ctrl-P
Move to the previous newsgroup.
Tab, N
Move to the next newsgroup that contains unread articles.
Shift-Tab, P
Move to the previous newsgroup that contains unread articles.
Home Move to first newsgroup.
End Move to last newsgroup.
/ Search forward for newsgroup name containing matching text.
? Search backward for newsgroup name containing matching text.
7
Yarn User Manual - version 0.68
; Continue forward search.
: Continue backward search.
Space, Right Arrow
Go to the article selection level, listing only unread articles.
Enter
Go to the article selection level, listing all articles.
Ins, +
Subscribe to a newsgroup and insert the newsgroup at the current
position.
Del, -
Unsubscribe from the highlighted newsgroup.
A Post an article to the highlighted newsgroup.
C Mark all articles in the highlighted newsgroup as read.
O Save unread articles in the highlighted newsgroup to a folder.
S Save unread articles in the highlighted newsgroup to a file. The
program prompts for a file name. If you don't give a full path name,
the file is stored in the directory $HOME/News.
W Same as 'S', except omit the article headers.
! Run command shell. Type "exit" to return to Yarn.
F2, Ctrl-L
List address book.
Esc Exit program
ARTICLE SELECTION LEVEL
These commands are available in the article selection level.
Down Arrow, Ctrl-N
Move to the next article.
Up Arrow, Ctrl-P
Move to the previous article.
Tab, N
Move to the first article of the next thread.
Shift-Tab, P
Move backwards to the previous article beginning a thread.
Home Move to first article.
8
Yarn User Manual - version 0.68
End Move to last article.
/ Search forward for article containing matching text.
? Search backward for article containing matching text.
; Continue forward search.
: Continue backward search.
Space, Right Arrow
Read the article.
Del, -
Mark the article as read and go to the next unread article.
Ins, +
Mark the article as unread.
O Save the current article through to the last article in the thread to
a folder.
S Save the current article through to the last article in the thread to
a file. The program prompts for a file name. If you don't give a
full path name, the file is stored in the directory $HOME/News.
W Same as 'S', except omit the article headers.
K Mark the current article through to the last article in the thread as
read.
U Mark the current article through to the last article in the thread as
unread.
C Mark all articles in the newsgroup as read.
A Post an article to the newsgroup.
! Run command shell. Type "exit" to return to Yarn.
F2, Ctrl-L
List address book.
F3, Ctrl-A
Add the author of the current message to the address book.
Esc, Left Arrow
Return to the newsgroup selection level.
ARTICLE READING LEVEL
These commands are available in the article reading level.
Down Arrow, Enter
Scroll one line down.
9
Yarn User Manual - version 0.68
Up Arrow
Scroll one line up.
PgDn, Space
Show next page.
PgUp, b
Show previous page.
Home Go to top of article.
g Search article for matching text.
G Continue search in article.
/ Search forward for article containing matching text.
? Search backward for article containing matching text.
; Continue forward search.
: Continue backward search.
n, Right Arrow
Mark the article as read and show the next unread article.
N Show next article.
p Show previous unread article.
P Show previous article.
a, A Post an article to the newsgroup.
f Post a followup article.
F Post a followup article, quoting the original article.
r Mail a reply to the author of the article.
R Mail a reply, quoting the original article.
m Mail the article to someone.
o Save the article to a folder.
s Save the article to a file. The program prompts for a file name. If
you don't give a full path name, the file is stored in the directory
$HOME/News.
w Same as s except omit article headers.
x ROT13 decrypt the article.
10
Yarn User Manual - version 0.68
X Decrypt the article by running the external cryptography program
specified in the Yarn configuration.
k, Del
Mark the article as read.
K Mark this article and the rest of the articles in the thread as read.
u, Ins
Mark the article as unread.
U Mark this article and the rest of the articles in the thread as
unread.
C Mark all the articles in the newsgroup as read.
v Toggle verbose headers.
c Cancel the article. You must be the author to be able to cancel the
article.
z Supersede the article. You must be the author to be able to
supersede the article.
=, Left Arrow
Return to the article selection level.
! Run command shell. Type "exit" to return to Yarn.
F2, Ctrl-L
List address book.
F3, Ctrl-A
Add the author of the current message to the address book.
Esc Return to the newsgroup selection level.
READ MAIL
To read mail, press [Shift-M] at the newsgroup selection level. This
brings up a list of mail messages you received.
If you have no mail, you are given the opportunity to send mail. A form
pops up, asking you to enter the destination mail address and subject for
the message you want to send. If you press the [F2] key while the cursor
is in the mail address field, the address book pops up. You can select an
entry from the address book by moving the highlight with the arrow keys
and pressing the [Enter] key.
Press [Shift-F] at the newsgroup selection level to bring up a list of
folders. You can select a folder to read from this list.
If you start yarn with the -m option, you go directly to reading your
received mail and skip reading news. If you start yarn with the -f
option, you go directly to the folder list and skip reading news.
11
Yarn User Manual - version 0.68
EDIT REPLIES
The Yarn reader allows you to edit the messages in the reply packet. At
the newsgroup selection level, press [Shift-R] to display a list of
folders in the reply packet. The reply packet may contain up to two
folders, ``mail'' which holds outgoing mail messages, and ``news'' which
holds outgoing USENET articles.
By selecting a folder, you go to the message selection level, where the
program lists the messages in the folder. Press the [Del] key to delete
the currently highlighted message. Press [Shift-E] to edit the message.
To view a message, select it from the message selection level. While a
message is displayed, pressing the 'd' key deletes the message. Press the
'e' key to edit the message.
If you start yarn with the -r option, you go directly to the replies list
and skip reading news.
USING THE ADDRESS BOOK
The address book is used to conveniently retrieve mail addresses. An
address book entry consists of an alias and an address. An alias is a
word representing a address or a list of addresses. If an alias appears
in a To:, Cc:, or Bcc: header, it is replaced with the corresponding
address(es) when the message is sent.
To list the address book, press [F2] at the newsgroup selection level. To
add an address book entry, press the [Ins] key. A form appears in which
you enter the alias and address. To specify a list of addresses, enter
the addresses in the Address: field, separating them with a comma.
While you are reading a message, you can capture the mail address of the
message author and add it to the address book by pressing the [F3] key.
YARN OPTION SUMMARY
The yarn program accepts these options:
-b Output to the display using BIOS calls instead of direct screen
writes.
-f List folders. Do not read news.
-m List mail. Do not read news.
-r List replies. Do not read news.
-s Disable the '!' run shell command.
QUESTIONS AND ANSWERS
``How do I create SOUP files on my UNIX host?''
12
Yarn User Manual - version 0.68
The uqwk program creates and processes SOUP files on your UNIX host.
It is available by anonymous FTP from ftp.gte.com in the /pub/uqwk
directory.
To create a SOUP download packet, named "down.zip" in this example,
run these commands on your UNIX host:
uqwk +n +x +L
zip down.zip AREAS *.MSG
Download the down.zip file to your PC. Run this command on your PC
to insert the messages into the Yarn news base:
import down.zip
When you send mail or post articles, the Yarn reader creates a SOUP
reply packet, named "up.zip" in this example. Upload the up.zip file
to your UNIX host. Run these commands on your UNIX host to send the
messages in the reply packet:
unzip -U up.zip
uqwk -m -n +L -RREPLIES
``Sometimes when I select a newsgroup by pressing the space bar from the
newsgroup selection level, yarn lists less articles than the number of
unread articles shown.''
This occurs if the newsgroup you selected contains cross-posted
articles that you already read in another newsgroup. The program
marks these articles as read and updates the count of unread articles
when you select the newsgroup.
``After running expire, I reduced the keep days for a newsgroup and ran
expire again, but it didn't delete any more articles.''
Each article is assigned an expiry date after which it is deleted.
The expire program deletes articles having an expiry date older than
the current date. The article storage scheme requires that an
article's expiry date be set when the article is imported into the
news base. Once imported, the article's expiry date cannot be
changed. When you change the keep days for a newsgroup, you only
change how long you keep subsequently imported articles. You don't
affect the expiry dates of articles already in the news base.
``What is the junk newsgroup?''
When the import program finds an article that doesn't belong to any
of the groups in the active newsgroup list, it tosses the article
into the junk newsgroup. This usually shouldn't happen with properly
configured software.
``I configured Yarn for OS/2 to run the DOS version of PKZIP and PKUNZIP.
Now the import program reports unpack failed.''
13
Yarn User Manual - version 0.68
To use PKZIP and PKUNZIP, put these settings in your configuration
file, adjusting the drive and path appropriately.
compress=c:\os2\cmd.exe /c c:\path\pkzip -m %f %d\*.*
uncompress=c:\os2\cmd.exe /c c:\path\pkunzip -o %f %d
``How do I configure Yarn to use InfoZip's zip and unzip programs?''
Put these settings in the configuration file.
compress=zip -kjm %f %d/*
uncompress=unzip -o %f
FILES
$HOME\mail Folder directory
$HOME\news Default save directory
$HOME\replies Reply work directory
$HOME\yarn User configuration directory
$HOME\yarn\addrbook Address book file
$HOME\yarn\config User configuration file
$HOME\yarn\filter Mail filter configuration file
$HOME\yarn\newsrc Newsgroup subscription file
$HOME\yarn\readart.* Read cross-posted article lookup table
$YARN\active Active newsgroup file
$YARN\history.* Article history lookup table
$YARN\overview Article overview directory
$YARN\news Article file directory
ACKNOWLEDGEMENTS
This product uses the SPAWNO routines by Ralf Brown to minimize memory use
while shelling to DOS and running other programs.
14
