ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / comms_networking / gmail / GMail / !Help < prev next >

Wrap

Text File | 1998-10-02 | 27KB | 585 lines

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 :-)