5. Getting Connected

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 10. 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 10. 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 6.1 Reply Buffer Initialization.

5.1 GNUS, RMAIL, or RNEWS with any Emacs 19

These MUAs, distributed with both FSF and Lucid GNU Emacs 19, use Emacs' 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)

Note that the mail-citation-hook interface described above was not supported in FSF Emacs 19 until version 19.16 and in Lucid Emacs 19 until version 19.8. If you are running an earlier version of one of these Emacsen, you will need to either upgrade to the latest version, or use the unsupported overloading feature provided with Supercite. See section 5.6 Overloading for Non-conforming MUAs.

5.2 GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4

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 5.6 Overloading for Non-conforming MUAs. Then follow the directions for using these MUAs under Emacs 19. See section 5.1 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 a single quote on the first argument to setq.

5.3 MH-E with any Emacsen

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

5.4 VM with any Emacsen

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 5.2 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)

5.5 GNEWS with any Emacsen

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 5.6 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 5.2 GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4, for details on how to proceed without add-hook.

5.6 Overloading for Non-conforming MUAs

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 5.1 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 5.2 GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 on substitutes for Emacs 19's add-hook function.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.