Current Shareware 1994 January/SHAR194.ISO/email/dove0793.zip/READ.ME

Text File | 1993-07-30 | 21KB | 346 lines

READ.ME File for DoveMail (includes "documentation", such as it is, for
NewsToss and NewsScan):

PLEASE NOTE:  DoveMail and NewsToss now have the ability to process a
batched newsgroup file created by newer versions of the KA9Q program (in
particular a version found on an FTP site in England) that contains carriage
returns in addition to linefeeds.  DoveMail will never CREATE a batched
newsgroup file with carriage returns, however.  Since those who receive news
using the KA9Q program (via an NNTP news server) currently have no easy way
to post news (most NNTP sites seem to disallow posting), NewsScan supports
posting only via a mail to news server.  See the "KillCR" keyword in the
sample DoveMail/NewsToss config files, and the new keywords that start with
"KA9Q" in the NewsScan config file for details.

PLEASE NOTE:  Some previous versions of DoveMail, NewsToss and NewsScan
allowed you to use the "MaxGroups" keyword in the config file.  This line is
no longer needed, nor is it recognized.  Also, DoveMail, NewsToss, and
CUnBatch will now process incoming batched newsgroup files in file datestamp
order, in an attempt to keep messages in some semblance of order.

This archive contains a BETA-TEST version of DoveMail, a newsgroup processor
designed to pass UseNet-type newsgroups between Fidonet-technology nodes in
native RFC-822 / RFC-1036 (batched newsgroup) format.  It also contains
several other programs which you may or may not need in your particular
situation, plus some documentation, sample batch files (PLEASE READ THESE!
They may be more helpful to you than the documentation!), and a copy of the
RFC-1036 specifications for newsgroup messages (please note that RFC-1036 is
the ideal, but there are certain limitations on MS-DOS machines that inhibit
100% compliance.  Still, DoveMail comes close enough that you won't have any
problems with sending improperly formatted messages into the net, or anything
like that).  There's also a copy of a proposed FTSC standard for "Newsgroup
Interchange Within Fidonet", which has been assigned the number FSC-0059
by the Fidonet Technical Standards Committee, and is included in this archive
for your perusal.  And, there's a little file called MAXSTUFF.ZIP which is a
little extra help in using DoveMail for those run the Maximus BBS software.
Here is a rundown of the programs included in this archive, and the
circumstances under which you might use them:

DOVEMAIL.EXE:  You need DoveMail if you are sending newsgroups to and from
other nodes, whether in Fidonet or in the Internet/UseNet.  It passes
newsgroups in the native RFC-822 / RFC-1036 batched newsgroup format.

DOVEPACK.EXE:  You need DovePack if you are sending newsgroups to other nodes
and your current mail packer does not recognize the *.UUT/*.PKU naming
convention for batched newsgroup packets.  If you have limited memory, or use
an archiver that requires large amounts of memory, you may also need to use
the SHROOM program described below.

NOFLO100.LZH is an archive of a program that I did NOT write, but that you
MAY find useful if you are using DovePack and your system needs file attach
MESSAGES (rather than ".flo" files) to be created before it can deliver
outgoing mail.  DovePack can do this by itself to a limited extent, but if it
doesn't meet your needs, this program might.  See the documentation for
DovePack for more details.

COMPRESS.EXE:  This is another program that I did NOT write, but that you may
need.  You need this program if you are receiving COMPRESSed batched
newsgroup files (probably directly from a system in UseNet or some other
branch of the Internet).  When decompressing files, I suggest calling this
version of COMPRESS by using  COMPRESS -dfv <filemask>, where <filemask> is a
filename (possibly including wildcard characters) of the files you want to
decompress.  Note:  When calling COMPRESS from a batch file, I suggest the
use of a batch file line similar to this:
     FOR %%A IN (<filemask>) DO compress -dfv %%A
but replace <filemask> as indicated above.  This forces COMPRESS to deal with
each file one at a time.  If you don't do this, and one or more compressed
files are bad, COMPRESS will stop when it encounters the first bad file and
will leave it and any other remaining (possibly good) files compressed.  If
you do use the FOR...IN...DO construct, then COMPRESS should find and
decompress ALL of the good files [NOTE: If you shell to COMPRESS from the
CUNBATCH program described below, you don't need to do the batch file
trick... CUNBATCH will automatically force COMPRESS to deal with the files
one at a time].  This version of COMPRESS is able to decompress files created
with 12 bit or 16 bit compression, but I'm not sure that it will decompress
files created with 14 bit compression, should you ever receive such files.
You can get a help screen for this program by typing COMPRESS -?, and there
is also a separate documentataion file (COMPRESS.DOC).

CUNBATCH.EXE:  You need this program if you are receiving COMPRESSed batched
newsgroup files (probably directly from a system in UseNet or some other
branch of the Internet), and the files have the "c" header ("#! cunbatch"),
and the MS-DOS version of COMPRESS that you are using to decompress the files
is not "smart" enough to skip this header (none that I know of is).
CUNBATCH.EXE can also be used to ADD the "c" header to files that YOU have
created using COMPRESS, should you find it necessary to do so.  And you can
optionally shell to COMPRESS from within CUNBATCH, in order to force COMPRESS
to deal with batched newsgroup files one at a time (note, however, that this
requires additional memory, so if you are multitasking in a tight memory
situation you may need to run CUNBATCH first and then run COMPRESS
separately, or try using the SHROOM program described below to invoke
COMPRESS).  Type COMPRESS without any arguments to get a help screen.
N.B.:  The -c switch allows you to shell to an external program (normally
COMPRESS) only *AFTER* the "c" header is removed (or added), and it is only
usable where the the name of the file to be acted upon is the last item in
the called program's invocation line.  It is intended specifically for
calling the COMPRESS program while unpacking compressed newsgroup files, and
may not be too useful in other situations.  Also, you MUST include the FULL
DRIVE and PATH specifications (if not in the "current" directory) and
EXTENSION (e.g.  ".EXE") of the compression program called using the -c
switch.

(Please note that you probably do NOT need either COMPRESS.EXE or
CUNBATCH.EXE unless you are receiving newsgroups from a "real" UseNet site...
most DoveMail users will NOT need to use either program!)

SHROOM2D.ZIP (may be a later version in the archive you receive, if I forget
to update this file) is an archive of a shareware program that I did NOT
write, but that you MAY find useful if DOVEPACK or CUNBATCH runs out of
memory when shelling out to the file compressor.  SHROOM ("Shell Room
Utility", a shareware program written and copyrighted by Davis Augustine) is
supposed to cause the application program (DOVEPACK or CUNBATCH in this case)
to be swapped to a disk file before the shelled program (the compression
program) is executed.  You may also find it useful with other programs on
your system that shell to file compressors or other programs.  Please read
the documention carefully to decide which command line arguments you need to
use, since they may vary depending on the DOS shell you use.  At a minimum
you will probably need to use the -t * switch, and I would also be sure to
use the -p switch so that the program doesn't hang waiting for keyboard input
if your hard drive is full (unless, of course, you consider a full hard drive
to be such a serious error that you WANT everything to come to a screeching
halt!).  A typical SHROOM invocation line might look like this:
     SHROOM -p -t * DOVEPACK [... command line arguments for DovePack ...]
If you like to know exactly what the programs on your system are doing, you
may also want to add the -v (verbose mode) switch.  If you don't have to use
either DOVEPACK or CUNBATCH, then you may not need this program at all,
although it could come in handy for use with other memory-hungry applications
(such as your Fidonet mail packer, if it doesn't already have the ability to
swap itself to a disk file while calling the compression program).  PLEASE
NOTE: SHROOM is a copyrighted software work which is distributed as
shareware, so if you use it, be sure to read the shareware license in the
documentation file.  If you are one of the few required to register your copy
of DoveMail, that registration does *NOT* relieve you of the responsibility
of separately registering your copy of SHROOM, if you use SHROOM on your
system.  SHROOM is provided only as a convenience for those who might
otherwise have difficulty locating it, and is not an official part of the
DoveMail package, and may be removed without notice from future releases of
the DoveMail archive.

NEWSSCAN.EXE:  A program to scan messages TO an UNcompressed batched
newsgroup packet FROM Fidonet *.msg files (or, optionally, to scan messages
out to a mail queue for use by the KA9Q program).  If you are a "leaf node",
you could possibly use this program alone (without necessarily running
DoveMail) to scan outgoing newsgroup messages.  Please see the documentation
file NEWSSCAN.DOC, the sample NEWSSCAN.CFG file, and the SAMPLE.SIG file
included in this archive.

NEWSTOSS.EXE:  A program to toss messages FROM an UNcompressed batched
newsgroup packet TO Fidonet *.msg files.  If you are a "leaf node", you could
possibly use this program alone (without necessarily running DoveMail) to
toss incoming newsgroup files.  No separate documentation is included for
this program, but if you read the sample NEWSTOSS.CFG file you should be able
to figure it out.  Please be aware that NewsToss will toss a received
newsgroup message no matter how long it is... this has NOT caused any problem
with Maximus (the BBS) or Ned (a message reader/editor), but possibly might
if you are using other (poorly-written!) software.  NewsToss accepts one
optional command line argument, the name of the configuration file (if not
specified, NewsToss.Cfg is used).

The latter two programs (NewsScan and NewsToss) support the Fidonet *.msg
format only.  They will NOT deal with a "flat file" message format.  However,
you may be able to use some of the programs included in other packages (such
as FredGate or UFgate) to convert the newsgroup packet to and from Fidonet
format.  Also, these two programs do NOT have documentation files (yet), but
you should be able to figure out how to use them from reading the
liberally-commented sample config files.  Finally, if a message is received
that was posted to multiple newsgroups, NewsToss will toss a copy of that
message to every area that you carry.  If a user replies to that message in
ANY area, NewsScan will post the REPLY to all areas to which the original was
posted (the "Newsgroups:" line from the original is copied verbatim into the
reply).  Therefore, YOU SHOULD INSTRUCT USERS TO REPLY TO A MESSAGE ONLY
*ONCE*, even if they see it posted in multiple areas on your BBS.  Posting
the SAME reply to the SAME message in multiple areas on your board WILL cause
duplicate messages to be sent out.

The advantage of using DoveMail to send messages between nodes is that none
of the UseNet message header information is lost in transmission between
nodes, and if a message is posted to multiple newsgroups, it is only
transmitted once (whereas, if it is converted to echomail format, it may be
transmitted multiple times).  Also, long messages are not truncated or
changed in transmission between nodes, and finally, there is no chance that a
message will be improperly discarded as a duplicate (this is a particular
problem in Newsgroups converted to echomail, because many echomail processors
use a checksum of parts of Fidonet message headers to determine if messages
are duplicates, and since all newsgroup messages are assumed to be addressed
to "All" and since some gateway software uses the date and time that the
message was converted to echomail rather than the original date and time from
the message, there tends to be a much higher incidence of converted newsgroup
messages falsely discarded as duplicates by echomail processors).

Please bear in mind that this program is NOT fully tested in all situations,
and if you attempt to use it and find that it does not work properly, I would
very much appreciate a detailed description of the problem.  If it bombs
while processing an incoming newsgroup file, I would definitely appreciate
receiving a copy of the newsgroup file in question, your DoveMail.Cfg file,
and anything else you feel may be helpful in diagnosing the problem.

The NewsToss and NewsScan programs will exit with an errorlevel if a fatal
error occurs during execution, but I have not documented these yet, and they
may change.  With NewsScan, any errorlevel greater than zero generally
indicates there was a problem in reading or writing a file (possibly a full
disk?).  With NewsToss, any errorlevel greater than one indicates some type
of fatal error, but an errorlevel of one simply indicates that no batched
newsgroup files were found.  If you have logging enabled, you'll have a
better idea of what happened if a problem occurred.

Once again, this is BETA-TEST software.  If you use it, YOU are a
Beta-tester!  So please don't complain if something doesn't work right as I
never represented the program as being completely bug-free!  You may give
this program to others, but if you do please give them the original
distribution archive containing all files, and please make it clear to them
that they, too, will be Beta-testers!

PLEASE NOTE...

Despite the inclusion of NewsToss and NewsScan in this archive, conversion to
Fidonet format is not really the function of DoveMail.  Any programs that I
write to convert messages between RFC-822 / RFC-1036 and FTS-0001 formats
will always be separate programs, not part of DoveMail.

The way that I envision DoveMail being used in this situation is as follows.
Let's assume you receive newsgroup feeds, and pass them onto others.
Obviously, DoveMail will do that.  It may well be that some of those
newsgroups are ones that you don't personally care about, but that you
receive for the sole purpose of passing on to others (this would be similar
to a "passthru" echomail conference).

So, in order to get a feed for your own system, what you need to do is to get
DoveMail to "export" (pass on) a feed for your own use.  You would do this by
setting up a feed to a "dummy" node, and by using a fully pathed filename
rather than a fidonet address in the "Newsnodes" section of the DoveMail.Cfg
file.  The file you specify would have your messages written to it, still in
RFC-822 / RFC-1036 format (it would be a regular newsgroup packet, in other
words).  If you have passthru areas, then this packet would consist of the
messages found in any incoming packets you process, MINUS any messages
destined solely for newsgroups that you don't carry (the "passthrus").  Now,
the only difference between this packet that you "export" for your own use
and the ones that you make for other systems is that the packet you make for
your use is not sent to another system!  Instead, it stays on your board and
it's up to you to decide what to do with it.  At this point DoveMail washes
its hands of the matter!

What is supposed to happen at this point is one of two things.  The most
ideal (but least likely given the present state of existing software) thing
that should happen is that your BBS program, message editor, or whatever
would use this packet directly.  You'd just keep appending new messages to
it, and occasionally run a utility that would prune out old and cancelled
messages (something like RENUM in Fidonet).  You'd have one file for all your
newsgroup messages.  If you (or a user on your BBS) entered a message in a
newsgroup, it would be written to a separate RFC-822 / RFC-1036 (batched
newsgroup) format file, which would be processed by DoveMail just like any
other incoming message, and only AFTER DoveMail processed the message would
it be added to your file of "readable" messages.  In other words, the
messages would NEVER be converted to FTS-0001 format.

But since existing Fidonet-technology BBS's don't work that way, the messages
will probably have to be converted to Fidonet format.  But here we run into a
problem:  What, exactly, is Fidonet format?  *.msg type files?  A *.PKT file?
A Hudson-style message base?  You may wish to have the newsgroup messages
converted to any of these formats.

My preference is to convert to the *.msg format directly, and skip going
through an echomail processor which can't handle long messages, and which
might decide that a message is a duplicate of a previously-seen message and
discard it even though the message really ISN'T a dupe.  But that won't work
very well for those who don't use the *.msg format.  So as you can see, there
are a number of things that COULD be done to further process the RFC-822 /
RFC-1036 batched newsgroup packet, and since every sysop may wish to do
somthing different, any software that I would write for the purpose will not
please everyone!

So, I release DoveMail with the caveat that if you need to have messages
converted to a Fidonet-Technology FTS-0001 format, and if for some reason the
NEWSTOSS and NEWSSCAN programs in this archive don't meet your needs, then
you'll still need to use UFGate or FredGate or some similar program to do the
conversion.

I do fear that some sysops may be a bit confused by the above explanation, so
let me try and clarify it by stating the differences between DoveMail and
ConfMail.

When ConfMail imports an echomail packet, it tosses each message to a *.msg
format file in the appropriate message directories on your system.  If you
are feeding echoes to other nodes, you then run ConfMail Export to look in
your message areas, find the messages that have not yet been sent, and pack
them for other nodes.  This system works well for echomail because you can't
post a single message to multiple echomail areas (without creating a separate
copy of the message in each area).

However, a single newsgroup message CAN be posted to multiple newsgroups, so
we can't use exactly the same system we use for echomail.  So, DoveMail does
not toss messages to a *.msg format at all.  Instead, when it imports a
batched newsgroup packet, it directly packs those messages to the batched
newsgroup packets destined for other nodes.  In other words, if the only
piece of software you run is DoveMail, you'll be able to provide newsgroup
feeds to other nodes, but the messages won't appear on your system!

The way around this dilemma is to have dovemail make a packet for your node.
To do this, you set up a "dummy" node that is really YOU.  For example, under
the "Begin_Newsnodes" section of the config file, you might put something
like:

mynode     +C:\bbs\innews.grp

Then, under "Begin_Newsgroups", you'd use "mynode" under any newsgroup you
want to carry on your system, like this:

Begin_Newsgroups
some.news.group
   mynode
.....

This would put any newsgroups you want to receive into C:\bbs\innews.grp.  If
you then need to toss the newsgroups to *.msg files, you could use NewsToss,
and you'd put the following line it its config file (NewsToss.Cfg):

Infiles C:\bbs\innews.grp

This would toss the packet that DoveMail created for YOUR system.  All the
messages tossed by NewsToss will have the SENT flag set, so they will not be
exported back off your system.

Now, when a local user enters a message in a Newsgroup area, you export it by
running NewsScan.  If you want DoveMail to process it, just make sure that
the file created by NewsScan is placed in a file area and has a filespec that
DoveMail expects to find (as specified in the InFiles statement in
DoveMail.Cfg, and the OutFile statement in NewsScan.Cfg).  When NewsScan
exports a message, it sets the "Sent" bit in the message header so that the
message will not be sent twice.  It also makes use of the "High Water Mark"
in 1.msg, similar to ConfMail and other echomail processors, to speed up
processing.

If this still isn't clear, please feel free to send me netmail.  I understand
that this all operates a little differently than what you may be used to, but
hopefully it's not too different from the way other Fidonet programs operate.
I would welcome any suggestions that anyone may have that would make this
documentation clearer.

Your comments and suggestions are appreciated.  Flames are NOT!

Jack Decker
Fidonet address: (no longer valid)
Internet: [e-mail]

Please note that other mail addresses given in former editions of this
document are no longer valid.