                                   GMail
                                   =====
Version 1.35 (02 Oct 1998)

Introduction
------------
Whilst I'm developing applications it is sometimes easier to send emails by
writing them 'raw' and saving them into the mail queue. The reason for this
is simple - I've not got enough memory to load all those Toolbox modules that
Messenger needs, have the stack loaded /and/ do other things. GMail gets
around these problems. Although it is no longer able to run in under 32k, it
does provide the largest selection of email options of any Acorn mailer (to
my knowledge).

It relies on !POPstar, !Pop, FreeSMTP, KA9Q, Termite, or ANT's MailBox having
been seen and if it has not then your message will not be sent. The mailboxes
will be used in the order !Pop, KA9Q, !POPstar, Termite, ANT, FreeSMTP if
more than one has been seen, unless you force the use of a particular one
through '-a'.

Note: Although the package is called GMail, and the program refers to itself
as GMail the command to use it is 'mail'. 


Usage
-----
The command line options for GMail are quite simple :
  *mail [-t <email>] [-s <subject>] [-a <agent>] [-c <email>] [-b <email>] [-v]
        [-u] [-f <email>] [-U <user>]

-t <email>   : sets who you are sending the mail to
-s <subject> : sets the subject (use quotes if the subject includes spaces)
-c <email>   : adds an address to the CC list (can be repeated)
-b <email>   : adds an address to the BCC list (will not appear in the email)
               (can be repeated)
-f <email>   : overrides the system variables Mail$Name and Mail$Email
-v           : shows the version number, special features and current mail
               agent
-a <agent>   : sets the mail agent, overriding the default (you probably won't
               need this, but it's there just in case). Valid agents are :
               ant, freesmtp, termite, ka9q, pop, direct, popstar.
-m <attach>  : attaches a file in MIME format (binary files will use base64
               unless disabled with -u)
               <attach> may be in quotes, and may be of the form :
               "<filename>" to attach a file and use the default 'guesses'
               "<filename> <name>" to attach a file, and use the name given,
                 rather than a unixified version of the name.
               "<filename> <name> <content-type>" to attach a file, and use a
                 name and specify the content type rather using the 'guess'
               "<filename> . <content-type>" to attach a file, and specify the
                 content type rather than the 'guess'
               "URL:<url>" to attach a 'message/external-body' url (if enabled)
               Any of these names may be suffixed by " :<description>" to
               give a textual description of the data included.
-u           : disable base64 inclusion and use uucode instead
-U <user>    : Use user <user>, overriding Mail$User

Alternatively, the simple syntax 'mail <email>' is available. If To: or
Subject: fields are not given in the command line they will be prompted for.

Once you have entered the details prompted for you can write the email. When
this has been done enter '.' on a line by itself to finish and place the mail
in the queue. Note: GMail will not format the text for you - if you want the
text to wrap you'll just have to press return. The end of the line of hypens
indicates where the message will begin to have quoted-printable encoding
added. If you do not wish to have quoted printable characters in your mail,
do not exceed the last -.


Setting up
----------
For GMail to work you need to set up a few variables :

  Mail$Email        : Should be set to your email address
  Mail$Name         : Should be set to your real name
  Mail$Organisation : Sets the 'X-Organization' field for the mail
  Mail$SigFile      : Should be set to a file containing your signature
                      If unset then the home directory will be searched for
                      a file named /sig
  Mail$Addresses    : Should be set to an address book file.
                      If unset then the home directory will be searched for
                      a file named /addrbook
  Mail$Headers      : Should be set to a headers file - this will be included
                      in the main headers of the message.
  Mail$ReplyTo      : Should be set to the return address for replies.
  Mail$Gateway      : Should be set to a mail gateway if one is required by
                      the sender.
  Mail$Sender       : Should be set to the sender name to use by default
                      instead of 'guessing'.
  Mail$FCC          : Should be the file used to store copies of outgoing
                      mail. (File Carbon Copy)
  
The only one that needs to be set up for GMail to work is Mail$Email (unless
you use -f).

If Mail$Addresses or Mail$SigFile are unset then your home directory will be
searched for the files /addrbook and /sig respectively.

Non-'root' user settings are stored in Mail$<user>$<suffix>, eg
Mail$Gerph$Sender. Any unset user variables will default to the user
settings. Any set to null strings will be assumed to be unwanted (eg
Mail$<user>$ReplyTo will not be used, even if Mail$ReplyTo is configured -
this is called 'override' in the configuration).

For more specific information on the use of these variables, see the front
end help file !GMailFE.!Help. It is recommended you use the FrontEnd to
configure GMail rather than doing it by hand !


Installation
------------
RiscPC owners (and those with RiscPC-style boot sequences) :
  The GMail directory should be placed inside Choices:Boot.PreDesk so that it
  is run on startup.

Other beings :
  The GMail.!Run file should be run on startup (or at some convenient point).

After installation you may want to run the !Run file in it's new location so
that the computer knows about it.


Example files
-------------
Along with this program should be three example files - /addrbook, /headers
and /sig, as well as a !Setup file which will configure these. The !Run file
should be run to initialise the system.

/addrbook is a simple address book with my address and ANT's support address.
/headers is a simple example of the user defined headers.
/sig is a dummy signature file that you'll probably want to change. Remember
signatures should start with the characters '-- ', but if you wanted to
include a closing comment before the seperator this is perfectly ok.


Address book
------------
The GMail address book (specified with Mail$Addresses) is in a very simple
format :

<nick><spaces><expansion>

<nick> must therefore not contain any spaces, but the expansion may include
further nicks which will be expanded.

If you prefix the address book filename with a '*', it will NOT be read as
a GMail address book. It will parse the file as if it were a raw Pine address
book file. Distribution lists are not supported in this format, but it may
still be useful if you switch between platforms regularly.


Use under TelnetD
-----------------
If you are using TelnetD and Mail$Email is unset then your login will be
read, along with Inet$HostName to form an email address which should be
valid. If Mail$Name is unset then this will also be read. Home directory in
this context becomes your home directory as defined in the passwd file.


Use with the ANT suite
----------------------
When used wih the ANT suite the address book and signature are assumed to be
that in the last known !MarcelDir. Also, the 'headers' file is also taken
from within the MarcelDir and added to the mail. The your name and email
address will be taken from the /marcelrc file in the !MarcelDir, as will the
ReplyTo address if set.

GMail has been tested under the ANT suite by ANT.


Use with KA9Q
-------------
KA9Q requires a smtp gateway to be given in it's 'work' file, and since GMail
cannot use localhost to deliver mail it has to resort to reading from the
AutoExec file to find a line starting 'smtp gateway'. If this line is not
found then an error will be raised and you cannot send mail.

KA9Q uses a sequence file to describe what name to give the next file in the
queue; if this file does not exists then an error will be raised.

GMail has not been actively tested under KA9Q, but according to tests should
run correctly.


Use with FreeSTMP
-----------------
FreeSMTP uses a sequence file to describe what name to give the next file in
the queue; if this file does not exists then an error will be raised.

GMail has been extensively tested under FreeSMTP.


Use with Termite
----------------
GMail has not been tested under Termite, but according to tests it should run
correctly.


Use with !POP
-------------
GMail has been quite well tested with POP, and appears to work correctly.


Use with !POPStar
-----------------
GMail has been quite well tested with !POPStar, and appears to work correctly.


Use with Acorn's !Mail
----------------------
GMail has not been actively tested with !Mail. To use it with this, you need
to set a variable AcornPostOut$Dir to point to the !PostOut directory.
Probably it is best to do this in the !PostOut.!Boot file, eg :
  Set AcornPostOut$Dir <Obey$Dir>

However, you must be running !Connect before mail inserted in to !PostOut
will be recognised. This kind of negates the usefulness of GMail. Alas, Mine
is not to reason why...


Use with BBS's
--------------
It is possible that this version of GMail may contain support for BBS upload
files. Use Mail -v to check this. To use these, the switch -a <bbs> must be
used. Only Arcade, Digibank (now defunct?) and Arctic are currently supported.
Fidonet addresses must be specified in the form :

  * Username <local@fidonet>
    For mail local to the BBS you upload to, with Username substituted.
    For example:
      Gareth S. Long <local@fidonet>
    Notice that <local@fidonet> is a literal.

  * Username <area.number@fidonet>
    For mail in an echo or local area given by 'number'.
    For example:
      Helen Rayner <area.100@fidonet>
    Notice that area is a literal.

  * Username <net:area/node.point@fidonet>
    For netmail, with net, area, node and point filled in correctly. Point may
    be omitted and will then be assumed to be 0.
    For example:
      Justin Fletcher <2:254/27.1@fidonet>

  * Username <internet address>
    For mail via the BBS to email gateway.
    For example:
      Derek W. Dick <fish@the.company.co.uk>

The mail will be placed in the file Mail$BBSUpload.

If you feel you would like a fido packet creator as well, please mail me to
let me know...


MailTo URL's
------------
If GMail is the first mail program to be seen (you run setup before you have
seen, for example, Marcel) then it will capture all mailto style URL's. In
practice this means that clicking on a email address in Fresco (or anywhere
else supporting the ANT URL protocol) will load GMail in a taskwindow. If you
don't want this then you should comment the last line out of the !Run file.


MIME attachments
----------------
MIME attachments have been extensively tested and appear to work correctly in
all circumstances. Files which appear from their start to be binary will be
attached using base64 (or uucode if base64 is disabled), those which are
mostly text, but contain high-ascii or control characters will be encoded
using quoted-printable. Other files will be included as text.

No external utility is required to attach files (ie, there is no need for
mpack to be in the path). GMail is pretty much RFC 2045 compliant, and almost
completely RFC 2047 compliant (this makes it the first on the Acorn
platform!). If you find any mistakes I'll be very happy to modify the code.

The MimeMap module (Acorn variant) is used to find the correct type for
files. 'application/riscos' is used for types which MimeMap is unaware of,
and all filenames are converted to unix format. UUCoded files are still
embedded inside a MIME header so that you may extract the relevant
information from the header if you wish.

Any message not requiring MIME encoding (eg a simple email in 7bit ASCII)
will not use MIME at all. This should cut down the size of the headers sent.


Special features
----------------
There are a number of 'special' compile time features which may (or may not)
be present in this copy of GMail. Since these require slightly more memory
than a 'standard' build of the program I've not always included them but they
are available currently on request. The special features which might be
available currently are :
 * Direct SMTP connection as a mail agent (rather than using FreeSMTP, ANT,
   Termite, POP or KA9Q). This /requires/ an internet stack to be installed.
   Note: Termite is not a 'standard' stack and is not supported; consult
         Doggysoft for details.
 * UUEncoding as well as Base64 encode. This is useful when you have friends
   (as I do) who don't seem to believe that MIME is a useful thing and are
   still stuck in the dark ages of UUCode.
 * 'Message/external-body URL' as well as standard files. This was defined
   in RFC2017 and allows you to attach files that are globally accessable
   rather than including the contents of the file itself. I don't know any
   mail reader that can currently support this. 
 * External edits from the command line. This is useful on those common
   occasions when you've written something which didn't sound quite how it
   did in your head and don't want to have to edit the mail whilst it's
   in the queue. An external edit equipped editor (Zap/StrongEd) must be
   present for this to work.
 * Multiple users. This should allow you to use lots of different users with
   just one configuration file.
 * Directory archiving. This allows you to specify a directory as an
   attachment and it will be automatically archived in zip format and
   attached. This is achieved using the simple 'store' algorithm and
   therefore is not amazingly efficient. This is experimental.
 * BBS upload file support. See the section above. This is experimental.

Current 'standard' versions include UUEncode, multi-user and
Message/external-body URL features. If you specify -v on the command line you
will see what features are enabled on your version.

    
Updates
-------
This program may (or may not) be updated periodically. See the Freenet site
for details <http://freenet.barnet.ac.uk/>.


Disclaimer
----------
The author accepts no responsibility for any problems which this application
may cause or loss of data resulting in its use. This application is Public
Domain Freeware. This means that it may be distributed, so long as no charge
other than copying costs are charged for it. The copyright remains with
myself (Justin Fletcher).


Authorship
----------
All code within GMail is by Justin Fletcher, except :
  * getopt, (c) AT&T
  * crc32, (c) Mark Addler - see zlib for original copy.


Contact
-------
Any comments, queries, donations or bug reports can be sent to Justin
Fletcher at :

E-Mail : Networking@thevillage.ndirect.co.uk
URL    : http://www.thevillage.ndirect.co.uk/
IRC    : On #Acorn as Gerph
Tel    : (01842) 812276

Snail Mail :
    Justin Fletcher
    Galadriel
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


History
-------
Version 1.00 : 19 Feb 1997
               First version written, and added Users module interface :-)
Version 1.01 :03 Apr 1997
               Mail$Organisation added, problem with stricmp fixed (used to
               resolve david@<blah> into the david in the address book)
               Termite support added.
Version 1.02 : 23 Apr 1997
               ANT support added. Mailed to Nick Smith for evaluation.
Version 1.03 : 17 Jun 1997
               Modifications for use with ANT and unixtime function added to
               get around the broken SharedCLibrary code.
Version 1.04 : 01 Jul 1997
               Fixed unixtime function to take account of timezone, and
               modified to use getopt - yes, we now have cli parameters !
               cc, bcc and subject parameters added. Generally tidied up
               nasty code. Wrote another parser for the address book (for
               Marcel's strange format).
Version 1.05 : 01 Jul 1997
               Added support for MarcelRC so that ANT users need never set
               Mail$Name or Mail$Email.
Version 1.06 : 02 Jul 1997
               Message-Id added, additional help added to command line
               options.
               Added URLOpen_MailTo command to the Setup file so that we
               can launch mail from link type things - could be nice in
               ArcWeb, etc...
               Send to ANT for further evaluation.
Version 1.07 : 07 Jul 1997
               Added -f, and fixed some more of the nastiness inside the
               writer. GMail's getting big now - 16k :-(. Changed sig file
               format (makes code easier anyhow !), added comment about
               writing mail at top of mail. Added support for KA9Q -
               untested. Updated help.
Version 1.08 : 08 Jul 1997
               Added some very basic MIME mailing capability. Doesn't work
               amazingly yet, but it suffices. Mail's massive now - 21k; I'm
               gonna have to stop adding features soon or it'll not run in
               32k.
               Sent to ANT for yet more evaluation testy type stuff...
Version 1.09 : 09 Jul 1997 Final release.
               Fixed filename conversion and added display of attachments in
               header.
Version 1.10 : 10 Jul 1997
               Fixed broken -f code where no Mail$Email was defined.
Version 1.11 : 11 Jul 1997
               Arrrggghhhh... NEVER say you've got a final release before
               you've checked everything umpteen thousand times ! Minor bug
               which meant that nothing would ever be attached at the end of
               the message fixed.
Version 1.12 : 14 Jul 1997
               Fixed bugs in Termite work file storer. Added !POP support.
               Re-organised internals of sendit() - now should be able to add
               almost any reasonable form of mail with only a few extra
               instructions. Now at 24k :-(
Version 1.13 : 4 Aug 1997
               SFILE added (allows use of 'direct' transport by special
               build). POP support fixed. Mail$Gateway and Mail$Sender support
               added.
Version 1.14 : 13 Aug 1997
               Added uucode support.
Version 1.15 : 02 Sep 1997
               Added quoted-printable support /everywhere/. I believe that
               this makes 'gmail' the only acorn mailer to currently support
               quoted-printable headers. Only other addition is that the main
               message body is now checked for quoted printable and charset
               attributes are added to any 'text/*' types. Mail$Organisation 
               is now read correctly when headers file exists.
Version 1.16 : 03 Sep 1997
               'To:' may now have multiple entries, improved input routines
               to be faster (and saved around 220 bytes!). More sensible
               checks on the address being sent to mean that it is no longer
               possible to send mail to local users by omitting the local
               domain name; to do this, you'll have to add an address book
               entry to automatically expand these.
Version 1.17 : 03 Sep 1997
               Implemented MimeMap SWIs to allow more control over mappings
               than the simple internal handling. MIME handling is now
               'correct' for the main message body. Whilst this means that a
               few more headers are included, it should now be completely
               MIME compliant.
Version 1.18 :07 Sep 1997
               Added support for message/external-body URL's (only).
               Specifying URL:<url> will include an external body to jump
               to that url. It's not sensible to include mailto: url's
               here...
Version 1.19 : 07 Sep 1997
               External Edit support added. Rudimentary at present, but
               a major rewrite of the main program and other sections may
               be required before this situation improves.
Version 1.20 : 25 Nov 1997
               All sorts of little changes and bug fixes added. Important
               change is that address book lookups will now search recursively
               so you can just keep an alias for a group of nicknames now.
               Removed bug in POP work file creation (was leaving RCPT's in
               there because it wasn't using ka9q).
               Possible corruption of address book looked up name fixed (I
               hope).
               Rudimentary Sendmail like piping supported; see mail -v for
               more details.
               Fixed 'NULL organisation' and 'NULL subject' bugs.
Version 1.21 : 26 Dec 1997
               Fixed numerous bugs in the internal MimeMap system which could
               confuse the attachments a bit.
Version 1.22 : 26 Dec 1997 - 13 Jan 1998
               Added FCC and fixed more bugs in the mime code; the majority
               of these were internal and are associated with the FCC
               facility.
               Fixed bugs with SigFile and Addresses when used with ANT stuff.
               Fixed MimeMap veneer to use Acorn code rather than ANT's broken
               one. So there should now be no need to use my patch from the
               freenet site.
               Wrote a configuration application.
               Fixed masses of bugs in mimer and added 'nice' system for
               setting the attachment name and content types for file
               attachments.
               Fixed minor bug which meant that FCC'd MIME's were invalid
               because they had incorrect boundaries.
               Fixed bugs which left you unable to specify a mailer agent
               if none was detected (thus making it impossible to use
               'direct').
               Added 'direct' to the list of things to compile in. This is
               obviously very experimental and you'll just have to try it and
               see if it works :-)
Version 1.23 : 31 Jan 1998 (fix release!)
               Fix for very minor uucode bug that left 'begin' lines off the
               start of lines ! (oops, forgot to label the version on this
               one)

Version 1.24 : 26 Feb 1998 (another fix release)
               Fixed bug in mail -x < <file> so that it doesn't duplicate
               lines any more (!).
               Content descriptions added (and will be qp'd)
               Doesn't use MIME if the message body is 'simple'. This cuts
               down on the amount of 'cack' that is sent for simple emails
               as most will be.
               A few other minor bugs fixed.

Version 1.25 : 03 Mar 1998
               Added support for POPstar.
               I dunno... People keep writing mailers, and I have to keep
               implementing their transports. Fun.

Version 1.26 : 10 Mar 1998
               Agent check lines were insensitive. Thus mail -a POPstar
               didn't work. Fixed now.

Version 1.27 : 18 Mar 1998
               Added 'multiuser' functions. Setting Mail$User or using -U
               <user> should let you change users more easily. Variables
               specific to the user are Mail$<User>$<var>. Defined, but
               null variables are returned as if unset (eg
               *Set Mail$gerph$replyto "" would mean that user gerph had
               no reply to address). If the variable is Unset the 'root'
               version is used.
               Fixed bug in Content-Encoding-Type which could be rubbish
               /iff/ null messages were sent.

Version 1.28 : 24 Mar 1998
               Added Pine address book parsing. Prefixing the filename of
               the address book with a '*' will parse the file as a pine
               address book, rather than a GMail address book.
               Fixed minor bug in the filetype routines which was not
               returning the correct filetypes for image files. There
               should no longer be messages with the type &4000 ;-)

Version 1.29 : 25 Mar 1998
               Added support for JFZippy, a very, very, very simple archiver,
               as a compile time option. Since it takes space I don't think
               most people will want it, but it might be useful.
               Unfortunately it doesn't produce the correct CRC's so it'll
               give you warnings when you try to extract the files if you
               use infozip or pkunzip :-(
               A few changes to the !Help file to correct mistakes.

Version 1.30 : 26 Mar 1998-05 Apr 1998
               Fixed CRC problems (!). I'm using Marc Adler's CRC32 code,
               so it ought to work correctly now.
               Fixed FCC date format so that CheckMail (and Pine) can
               understand it.

Version 1.31 : 25 Apr 1998
               Fixed bug in uucode stuff so we should now be able to
               include it without it coming out as base64!
               Fixed spelling mistakes and display of default mailer if
               -v or -h specified.
               Fixed MIME QP-encoding so that it doesn't randomly truncate
               lines now, and you can actually see how far you have to go
               by the ---'s on the top line.

Version 1.32 : 18 May 1998
               Modularised the Mailer system. Added BBS support, after
               seeing David Dade's article about the descent in BBS usage.
               Personally I can't do much, but I can try.

Version 1.33 : 31 May 1998
               Fixed date production to be RFC1123 compliant.
               Reformatted the main headers in the output so they look
               a little clearer.

Version 1.34 : 01 Jun 1998
               Feedback from David Dade - the Arcade upload was wrong. This
               should now be fixed. A few minor bugs fixed. Local addresses
               are now ignored.
               Things look a lot nicer now.
               You do realise that this !Help file is now almost as large
               as some of the early versions of GMail ?
               This version of GMail is a whopping 55k. That's a little
               extreme for this kind of program in my opinion. But the
               only alternative is to cut some of the things out, or to
               use QuickMail.

Version 1.35 : 02 Oct 1998
               Now works with my MimeMap module. Main problems were that
               when I wrote the MimeMapping stuff ANT had not released
               'correct' documentation for the MimeMap module. Now that I
               /know/ what the buffer size should be, I can use it :-)
