GNU Info

(sc)Hints to MUA Authors

---

Next: Version 3 Changes Prev: Electric References Up: Top

---

Enter node , (file) or (file)node

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."