This file is copyright  Ant Skelton 1995.

Documentation for Ant's MailMode extension to Zap.
==================================================

Requirements
============

MailMode requires version 1.20 or later of Dominic Symes' !Zap editor to run. It may work with
previous versions, or it may not.


Intro
=====

MailMode is an extension to Zap which provides a convenient means of replying to e-mail or usenet
messages. If !Zap is your main means of replying to e-mail messages, then you may well find some
of MailMode's functions useful. MailMode will do the following:

	 Delete SMTP/NNTP headers
	 Insert a one line preamble at the start of the message
	 Indent the text of a previous message
	 Append various signature files to the end of the message
	 Allow a message reply window to be killed without prompting the user for confirmation

Previously, replying to either a SMTP or NNTP message involved a tedious sequence of region selecting,
deleting, reselecting, indenting and file dragging. Having to manually close the window and confirm
you want the file discarded was the final straw, and MailMode was born!

Note however that MailMode does not handle the 'transport' side of e-mail. Well, not yet anyway.
You still need some sort of mail program to send and receive e-mail messages.


Installation
============

1) Copy the directory Ant into the '3rdParty' directory within the !Zap application.
2) Edit Zap's !Run file to include the line:

		RMLoad <Zap$3rdParty>.Ant.ZapMailMod

   within the section labelled "| Load extension modules"

3) Edit Zap's "keys" file. If you want to recognize e-mail/usenet files based on their filenames,
   edit the "Paths:" section. Eg, if your e-mail reader or news reader saves messages with
   the filename 'ReadMail', you might want to add a line like:

		&506    &FFF   \#\*readmail\#\*    +MailMode

   (the first number may not be &506 - it depends how many entries you have in this section
    already. See the comment in the "keys" file.)

   On the other hand, some e-mail programs don't save files with one name - for example, an e-mail
   program might save the message under the name of the person who sent it to you. In addition,
   it's most unlikely that any news reading programs will save articles under the name "ReadMail".

   To compensate for this unsavoury state of affairs, MailMode is able to recognize SMTP/NNTP
   messages from their content. In order for this feature to work, you will have to change a line
   in the "File types:" section of your "keys" file.

   Find the line:     Text       &1FFF   +Text

   and alter it to:   Text       &1FFF   +MailMode

   "But!" I hear you cry, "What about normal text files? I don't want to edit them in Mail Mode!"
   Fear not. Mail mode is on the case. Once you've configured Zap to send all text files to MailMode,
   it will examine new files to see if they're either an e-mail message or a usenet article. If
   MailMode doesn't like the look of them it will automatically switch back to Text mode and leave
   your file unmolested. For the same reason, you cannot edit a new message in MailMode - it will
   switch you straight back to text mode.



MailMode Menu
=============

MailMode has its own menu 'Mode.MailMode'. Parameters can be set for a particular
MailMode window, or global defaults can be set from the icon bar menu 'Options.Mode.MailMode'.


	Strip Headers	This option specifies whether MailMode will attempt to remove
			NNTP and SMTP headers. The default is ON. 
			
	Add Preamble	This option specifies whether MailMode will attempt to add a 'preamble' 
			to the message.  The default is OFF.			

	Indent String	This option specifies whether MailMode will indent ('quote') a
			message which is being replied to. A submenu allows the user to
			alter the string which is used in this process. The string may be
			up to 8 characters long. The default is ' > '.

	Signature	This option specifies whether MailMode should append a signature
			file when replying to a message. A submenu allows the user to
			alter the pathname which Zap uses to locate the signature file.
			The default is '<Zap$3rdParty>.Ant.signature'.
			
	Multi-Sig	This option specifies whether MailMode should use a file containing
			multiple signatures when attempting to append a signature to the end
			of a message. This option is disabled by default, but the default 
			multi-sig file is '<Zap$3rdParty>.Ant.signatures'.			

	Auto-kill	Sadly, this feature has been disabled at the last minute, as it does
			not behave consistently across differing species of Archimedi. It may
			return if Dominic includes some Zap calls I've been pestering
			him for! :)
			
	No protection	This is a stop-gap measure for use while auto-kill is not available.
	

And in more detail ...
======================				

Strip Headers
----- -------

When it sees a new file, MailMode scans the file for the word "Newsgroups:" at the start of a line. If it
finds this, then it assumes the file is a usenet article.

Failing this test, MailMode scans for the phrase "Message-ID:" at the start of a line. This is common to
both e-mail and usenet messages, but a usenet message normally has the "Newsgroups:" field so we can
safely assume that the file is an e-mail message if the "Message-ID:" field is found.

If both these tests fail, MailMode reverts to Zap's normal text mode and editing continues as normal.

Having established that this is a viable file, MailMode scans for the first empty line in the file. Nine
times out of ten, the first such line is the one which separates the message headers from the message body
text. Once found, MailMode will delete all the text from the start of the file up to this point, thus
removing all those nasty headers.


Add Preamble
--- --------

When the preamble option is enabled, MailMode will try to extract the subject and the name of
the sender from the current message (note this only applies to e-mail messages, not news
articles.) If it is successful in this endeavour, MailMode will display a line of the form:

	In message "subject" sender@somewhere wrote:

at the top of the message. The main purpose for extracting these fields is to allow me to
communicate directly with !EMail in version 0.40, and the preamble is a sort of debugging aid,
but I thought some people might like this option - similar things seem to be quite popular
on the net.

In case you're interested, MailMode scans for the SMTP headers 'Subject:' and 'From:'.
In constructing a valid address from the 'From:' field, MailMode first looks for anything
within angled brackets <like-this>. Failing this, it will use the text up to the first
white-space character as an address. Thus it ought to be able to handle addresses such as:

	From: joe_bloggs@public.org (Joe Bloggs)
	From: Joe Bloggs <joe_bloggs@public.comm>

If an address is unusually long, MailMode may give up before it sees the terminating '>', in
which case it will get the address of the sender wrong. This is unlikely, though. However,
if you do notice MailMode failing to get an address right, please send the offending header
to me at the address below.


Indent String
------ ------

When replying to a message or article, it is common practice to indent the text of the
message, to distinguish the original text from text which you have added in the reply.
MailMode will indent all the lines of a message with the string you provide it if this
option is enabled. The default string is ' > '. This is also the string which the MSGQUOTE
command will use.


Signature
---------

A signature is a standard text segment appended to the end of an e-mail message or usenet article,
and is widely regarded as a good means of wasting bandwidth and irritating other people. MailMode
will attempt to open the signature file, and will append any text it finds there to the end of the
current article.

If you have multi-sig enabled, then this option is by-passed.


MultiSig
--------

Multisig is an exciting new development in the field of bandwidth-wasting technology, and is essential
for users who want to maintain more than one feeble .sig gag.

Multisig operates in much the same way as the normal signature option, but the relevant file may contain
more than one signature. MailMode will faithfully cycle through all the available signatures in the given
file each time you append one to a message. Variety, as they say, is the spice of life.

Files which contain multiple signatures are in a freaky not-entirely-obvious format. This is because
MailMode has to write data to this file (in order to keep track of the last signature it used), so the
file format is a compromise between readability for MailMode and readability for the user.

Read the file 'MultiHelp' for information on how to set up your multiple signature file.

Note that MultiSig takes preference over the normal signature option, so if you've got them
both switched on, multi-sig will handle any requests for signatures and the normal (one off)
signature routine will never be called.

Also note that MultiSig applies to MailMode's SIGNATURE command.


Auto-kill
---------

Auto-kill currently does nothing, as it has proved to be unstable on some RISC OS platforms.
This option may return, circumstances permitting. The basic idea was that !Zap would automatically
close a MailMode window as soon as the current file was dragged to a suitable application.


No Protection
-------------

This is a temporary measure until I can get the auto-kill-on-drag option working, so don't get
too attached to it :).

When this option is enabled, a MailMode window is unprotected against being killed, ie Zap
will _not_ prompt you with the usual warning 'File has been modified since last save' - it
will just kill the window and all the text in it, so use with caution.

This option is useful, as it saves you one mouse click when closing a window on an e-mail message,
which are usually quite transient affairs and don't need to be saved. However, if you're not quite
as lazy as me, you may prefer to disable this option and have the added security of Zap's paranoia.

Note that this only applies to messages which are being edited in MailMode (ie replies). If you
are originating a message then you will most likely be editing it in text mode, in which case Zap
will still prompt you for confirmation if you try to kill a window which contains unsaved data.


MailMode Commands
=================

Version 0.31 of MailMode provides three commands, SIGNATURE, MSGQUOTE, and STRIPHEADERS.
These commands can be executed from Zap's minibuffer, or may be bound to keys in Zap's
Keys file.


	SIGNATURE	This command appends a signature file to the end of the current file.
			The pathname used to locate this file is that set in the MailMode
			menu.

			This command is useful in text mode when messages are being generated
			as opposed to being replied to.

	MSGQUOTE	This command indents all lines in the current window with the string
			specified in the MailMode menu.

	STRIPHEADERS	This command will delete NNTP/SMTP headers from the current file if
			they exist.

Suggested key bindings are:

MailMode Keys:
cInsert		&1ED	MSGQUOTE
cHOME		&13E	SIGNATURE
sc<-|		&15C	STRIPHEADERS

i.e. ctrl-insert indents the current message, ctrl-home appends a signature file, and
shift-ctrl-backspace strips off the headers.
The above four lines can be dropped straight into Zap's Keys file, although you should
check that the keys aren't previously bound to another command.

Note that these commands apply to _all_ modes, they are not just operational in MailMode.


Another subtle change which has been made is that MailMode will now allow you to change
mode from text mode to mailmode, so if you accidentally drag a message into a text editing
window, you can still apply MailMode's features.











Why doesn't MailMode work?
--------------------------

If you are experiencing problems, you should note the following limitations to MailMode's behaviour.

1) Files which contain the phrases "Newsgroups:" or "Message-ID:" at the start of a line but which are
   not e-mail or usenet messages will be savagely mauled by MailMode. To avoid this, don't have these
   phrases at the beginning of a line. It's that simple. :)

2) Valid message files which don't have a blank line between the headers and the body text will not
   have their headers removed. This is because MailMode doesn't know where the headers stop and the
   message begins. In addition, MailMode will not attempt to indent any of the message with '>'s.

3) If you want to save multiple copies of a message you've edited, then you're out of luck! After the first
   save event MailMode will kill the window. If you want a copy, you'll have to either save the message
   to disk and then mail the saved version, or save the message to your mail program and mail a copy
   to yourself.










Ant.
14 Febraury 1995.
23 February 1995.
09 March 1995.
<ant@omi.co.uk>
<ant@cb1.com>

