Hints to MUA Authors

In June of 1989, some discussion was held between the various MUA authors, the Supercite author, and other Supercite users. These discussions centered around the need for a standard interface between MUAs and Supercite (or any future Supercite-like packages). This interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in a mail message to the Supercite mailing list:

	Martin> Each news/mail-reader should provide a form of
	Martin> mail-yank-original that

	Martin> 1: inserts the original message incl. header into the
	Martin>    reply buffer; no indentation/prefixing is done, the header
	Martin>    tends to be a "full blown" version rather than to be
	Martin>    stripped down.

	Martin> 2: `point' is at the start of the header, `mark' at the
	Martin>    end of the message body.

	Martin> 3: (run-hooks 'mail-yank-hooks)

	Martin> [Supercite] should be run as such a hook and merely
	Martin> rewrite the message.  This way it isn't anymore
	Martin> [Supercite]'s job to gather the original from obscure
	Martin> sources. [...]

This specification was adopted, but with the recent release of Emacs 19, it has undergone a slight modification. Instead of the variable mail-yank-hooks, the new preferred hook variable that the MUA should provide is mail-citation-hook. mail-yank-hooks can be provided for backward compatibility, but mail-citation-hook should always take precedence. Richard Stallman (of the FSF) suggests that the MUAs should defvar mail-citation-hook to nil and perform some default citing when that is the case. Take a look at Emacs 19's `sendmail.el' file, specifically the mail-yank-original defun for details.

If you are writing a new MUA package, or maintaining an existing MUA package, you should make it conform to this interface so that your users will be able to link Supercite easily and seamlessly. To do this, when setting up a reply or forward buffer, your MUA should follow these steps:

1. Insert the original message, including the mail headers into the reply buffer. At this point you should not modify the raw text in any way, and you should place all the original headers into the body of the reply. This means that many of the mail headers will be duplicated, one copy above the mail-header-separator line and one copy below, however there will probably be more headers below this line.
2. Set `point' to the beginning of the line containing the first mail header in the body of the reply. Set `mark' at the end of the message text. It is very important that the region be set around the text Supercite is to modify and that the mail headers are within this region. Supercite will not venture outside the region for any reason, and anything within the region is fair game, so don't put anything that must remain unchanged inside the region. Further note that for Emacs 19, the region need not be set active. Supercite will work properly when the region is inactive, as should any other like-minded package.
3. Run the hook mail-citation-hook. You will probably want to provide some kind of default citation functions in cases where the user does not have Supercite installed. By default, your MUA should defvar mail-citation-hook to nil, and in your yanking function, check its value. If it finds mail-citation-hook to be nil, it should perform some default citing behavior. User who want to connect to Supercite then need only add sc-cite-original to this list of hooks using add-hook.

If you do all this, your users will not need to overload your routines to use Supercite, and your MUA will join the ranks of those that conform to this interface "out of the box."