Hitting C-c C-y in your MUA's reply buffer yanks and cites the
original message into the reply buffer. In reality, the citation of the
original message is performed via a call through a configurable hook
variable. The name of this variable has been agreed to in advance as
part of the citation interface specification. By default this
hook variable has a nil value, which the MUA recognizes to mean,
"use your default citation function". When you add Supercite's
citation function to the hook, thereby giving the variable a
non-nil value, it tells the MUA to run the hook via
run-hooks instead of using the default citation.
Early in Supercite's development, the Supercite author, a few MUA authors, and some early Supercite users got together and agreed upon a standard interface between MUAs and citation packages (of which Supercite is currently the only known add-on :-). With the recent release of the Free Software Foundation's GNU Emacs 19, the interface has undergone some modification and it is possible that not all MUAs support the new interface yet. Some support only the old interface and some do not support the interface at all. Still, it is possible for all known MUAs to use Supercite, and the following sections will outline the procedures you need to follow.
To learn exactly how to connect Supercite to the software systems you are using, read the appropriate following sections. For details on the interface specifications, or if you are writing or maintaining an MUA, see section Hints to MUA Authors.
The first thing that everyone should do, regardless of the MUA you are using is to set up Emacs so it will load Supercite at the appropriate time. You can either dump Supercite into your Emacs binary (ask your local Emacs guru how to do this if you don't know), or you can set up an autoload for Supercite. To do the latter, put the following in your `.emacs' file:
(autoload 'sc-cite-original "supercite" "Supercite 3.1" t) (autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
The function sc-cite-original is the top-level Supercite function
designed to be run from the citation hook. It expects
`point' and `mark' to be set around the region to cite, and it
expects the original article's mail headers to be present within this
region. Note that Supercite never touches any text outside this
region. Note further that for Emacs 19, the region need not be active
for sc-cite-original to do its job.
See section Hints to MUA Authors.
The other step in the getting connected process is to make sure your
MUA calls sc-cite-original at the right time. As mentioned
above, some MUAs handle this differently. Read the sections that follow
pertaining to the MUAs you are using.
One final note. After Supercite is loaded into your Emacs session, it
runs the hook sc-load-hook. You can put any customizations into
this hook since it is only run once. This will not work, however, if
your Emacs maintainer has put Supercite into your dumped Emacs' image.
In that case, you can use the sc-pre-hook variable, but this will
get executed every time sc-cite-original is called. See section Reply Buffer Initialization.
These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
built-in yanking facility, which provides the citing hook variable
mail-citation-hook. By default, this hook's value is nil,
but by adding the following to your `.emacs' file, you can tell
these MUAs to use Supercite to perform the citing of the original
message:
(add-hook 'mail-citation-hook 'sc-cite-original)
GNUS users may also want to add the following bit of lisp as well. This prevents GNUS from inserting its default attribution header. Otherwise, both GNUS and Supercite will insert an attribution header:
(setq news-reply-header-hook nil)
These MUAs use Emacs' built-in yanking and citing routines, contained in the `sendmail.el' file. `sendmail.el' for Emacs 18, and its derivative Epoch 4, do not know anything about the citation interface required by Supercite. To connect Supercite to any of these MUAs under Emacs 18 or Epoch 4, you should first see section Overloading for Non-conforming MUAs. Then follow the directions for using these MUAs under Emacs 19. See section GNUS, RMAIL, or RNEWS with any Emacs 19.
Note that those instructions will tell you to use the function
add-hook. This function is new with Emacs 19 and you will not
have it by default if you are running Emacs 18 or Epoch 4. You can
either substitute the appropriate call to setq, or you can use
the add-hook function that is provided in the `sc-unsupp.el'
file of unsupported Supercite hacks and ideas. Or you can upgrade to
some Emacs 19 variant! :-)
To use setq instead of add-hook, you would, for example,
change this:
(add-hook 'mail-citation-hook 'sc-cite-original)
to:
(setq mail-citation-hook 'sc-cite-original)
Note the lack of of a single quote on the first argument to setq.
MH-E 4.x conforms to the mail-citation-hook interface supported
by other MUAs. At the time of this writing, MH-E 4.0 has not been
released, but if you have it, put this in your `.emacs' file to
connect Supercite and MH-E 4.x:
(add-hook 'mail-citation-hook 'sc-cite-original)
Note that if you are using Emacs 18 or Epoch 4, you will not have the
add-hook function. See section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 for details on how to
proceed without add-hook.
MH-E version 3.x uses a slightly different interface than other MUAs.
MH-E provides a hook variable mh-yank-hooks, but it doesn't act
like a hook, and doing an add-hook will not work.
To connect Supercite to MH-E 3.x, you should instead add the following
to your .emacs file:
(add-hook 'mh-yank-hooks 'sc-cite-original)
You also need to make sure that MH-E includes all the original mail
headers in the yanked message. The variable that controls this is
mh-yank-from-start-of-msg. By default, this variable has the
value t, which tells MH-E to include all the mail headers when
yanking the original message. Before you switched to using Supercite,
you may have set this variable to other values so as not to include the
mail headers in the yanked message. Since Supercite requires these
headers (and cleans them out for you), you need to make sure the value
is t. This lisp, in your `.emacs' file will do the trick:
(setq mh-yank-from-start-of-msg t)
Note that versions of MH-E before 3.7 did not provide the
mh-yank-hooks variable. Your only option is to upgrade to MH-E
version 3.7 or later.
Since release 4.40, VM has supported the citation interface required by Supercite. But since the interface has changed recently the details of getting connected differ with the version of VM you are using.
If you are running any release of VM after 4.40, you can add the following to your `.emacs' to connect Supercite with VM:
(add-hook 'mail-yank-hooks 'sc-cite-original)
Note that if you are using Emacs 18 or Epoch 4, you will not have the
add-hook function. See section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 for details on how to
proceed without add-hook.
Since version 5.34, VM has supported the newer mail-citation-hook
interface, but mail-yank-hooks is still being supported for
backward compatibility. If you are running a newer version of VM and
you want to maintain consistency with other MUAs, use this bit of code
instead:
(add-hook 'mail-citation-hook 'sc-cite-original)
As far as I know, no version of GNEWS supports the citation interface required by Supercite. To connect Supercite with GNEWS, please first see section Overloading for Non-conforming MUAs.
After you have followed the directions in that section. You should add the following lisp code to your `.emacs' file:
(add-hook 'mail-citation-hook 'sc-cite-original)
Note that if you are using Emacs 18 or Epoch 4, you will not have the
add-hook function. See section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 for details on how to
proceed without add-hook.
As mentioned elsewhere, some MUAs do not provide the necessary hooks to
connect with Supercite. Supercite version 3.1 provides an unsupported
mechanism, called overloading which redefines certain key
functions in the MUA, so that it will call the mail-citation-hook
variable instead of the MUA's default hard-coded citing routines. Since
most newer versions of the known MUAs support the
mail-citation-hook variable, it is recommended that you upgrade
if at all possible. But if you can't upgrade, at least you're not out
of luck! Once you set up overloading properly, you should follow the
directions for connecting Supercite to the Emacs 19 MUAs.
See section GNUS, RMAIL, or RNEWS with any Emacs 19.
Users of Bob Weiner's Hyperbole package take note. Hyperbole provides
the necessary overloads (and a whole lot more!) and you can potentially
clobber it if you were to load Supercite's overloading after
Hyperbole's. For this reason, Supercite will not perform any
overloading if it finds the variable hyperb:version is
boundp (i.e. it exists because Hyperbole has been loaded into
your Emacs session). If this is the case, Supercite will display a
warning message in the minibuffer. You should consult the Hyperbole
manual for further details.
Overloading involves the re-definition of the citing function with the
new, mail-citation-hook savvy version. The function in
`sc-oloads.el' that does this is sc-perform-overloads. This
function is smart enough to only overload the MUA functions when it is
absolutely necessary, based on the version numbers it can figure out.
Also, sc-perform-overloads will only install the new functions
once. It is also smart enough to do nothing if the MUA is not yet
loaded.
The tricky part is finding the right time and place to perform the overloading. It must be done after the MUA has been loaded into your Emacs session, but before the first time you try to yank in a message. Fortunately, this has been figured out for you.
If you must overload, you should put the following lisp code in your `.emacs' file, to make sure the `sc-oloads.el' file gets loaded at the right time:
(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
Then you must make sure that the function sc-perform-overloads
gets run at the right time. For GNUS, put this in your `.emacs'
file:
(setq news-reply-mode-hook 'sc-perform-overloads) (setq mail-setup-hook 'sc-perform-overloads)
If you are using RNEWS, put this in your `.emacs' file:
(setq news-reply-mode-hook 'sc-perform-overloads)
If you are using RMAIL or PCMAIL, put this in your `.emacs' file:
(setq mail-setup-hook 'sc-perform-overloads)
If you are using GNEWS, put this in your `.emacs' file:
(setq news-reply-mode-hook 'sc-perform-overloads) (setq gnews-ready-hook 'sc-perform-overloads)
Now go back and follow the directions for getting the Emacs 19 MUAs
connected to Supercite. Be sure to see section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 on substitutes
for Emacs 19's add-hook function.