sc: Hints to MUA Authors
10 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 underwent a slight modification
with the release of Emacs 19. Instead of the variable
‘mail-yank-hooks’, the hook variable that the MUA should provide is
‘mail-citation-hook’. Richard Stallman suggests that the MUAs should
‘defvar’ ‘mail-citation-hook’ to ‘nil’ and perform some default citing
when that is the case.
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 (except for any necessary decoding, e.g., of
quoted-printable text), 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.
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 MUA will join the ranks of those that conform
to this interface “out of the box.”