1. Introduction

Supercite version 3.1 is a GNU Emacs package written entirely in Emacs Lisp. It interfaces to most of the commonly used Emacs mail user agents (MUAs) and news user agents (NUAs), and provides sophisticated facilities for the citing and attributing of message replies. Supercite has a very specific and limited role in the process of composing replies to both USENET network news and electronic mail.

The preferred way to spell Supercite is with a capital `S', lowercase `upercite'. There are a few alternate spellings out there and I won't be terribly offended if you use them. People often ask though...

Supercite is only useful in conjunction with MUAs and NUAs such as VM, GNUS, RMAIL, etc. (hereafter referred to collectively as MUAs). Supercite is typically called by the MUA after a reply buffer has been setup. Thereafter, Supercite's many commands and formatting styles are available in that reply buffer until the reply is sent. Supercite is re-initialized in each new reply buffer.

Supercite is currently at major revision 3.1, and is known to work in the following environments:

Emacsen:

GNU Emacs 18.57 through 18.59, all current FSF Emacs 19, all current Lucid Emacs 19, and Epoch 4.

MUAs:

VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and beyond, PCMAIL.

NUAs:

RNEWS, GNUS 3.12 and beyond, GNEWS.

1.1 Usage Overview

Typical usage is as follows. You want to reply or followup to a message in your MUA. You will probably hit r (i.e., "reply") or f (i.e., "forward") to begin composing the reply. In response, the MUA will create a reply buffer and initialize the outgoing mail headers appropriately. The body of the reply will usually be empty at this point. You now decide that you would like to include part of the original message in your reply. To do this, you yank the original message into the reply buffer, typically with a key stroke such as C-c C-y. This sequence will invoke an MUA-specific function which fills the body of the reply with the original message and then attributes this text to its author. This is called citing and its effect is to prefix every line from the original message with a special text tag. Most MUAs provide some default style of citing; by using Supercite you gain a wider flexibility in the look and style of citations. Supercite's only job is to cite the original message.

1.2 What Supercite Doesn't Do

Because of this clear division of labor, there are useful features which are the sole responsibility of the MUA, even though it might seem that Supercite should provide them. For example, many people would like to be able to yank (and cite) only a portion of the original message. Since Supercite only modifies the text it finds in the reply buffer as set up by the MUA, it is the MUA's responsibility to do partial yanking. See section 6.1 Reply Buffer Initialization.

Another potentially useful thing would be for Supercite to set up the outgoing mail headers with information it gleans from the reply buffer. But by previously agreed upon convention, any text above the mail-header-separator which separates mail headers from message bodies cannot be modified by Supercite. Supercite, in fact, doesn't know anything about the meaning of these headers, and never ventures outside the designated region. See section 10. Hints to MUA Authors, for more details.

1.3 What Supercite Does

Supercite is invoked for the first time on a reply buffer via your MUA's reply or forward command. This command will actually perform citations by calling a hook variable to which Supercite's top-level function sc-cite-original has been added. When sc-cite-original is executed, the original message must be set up in a very specific way, but this is handled automatically by the MUA. See section 10. Hints to MUA Authors.

The first thing Supercite does, via sc-cite-original, is to parse through the original message's mail headers. It saves this data in an information association list, or info alist. The information in this list is used in a number of places throughout Supercite. See section 3. Information Keys and the Info Alist.

After the mail header info is extracted, the headers are optionally removed (nuked) from the reply. Supercite then writes a reference header into the buffer. This reference header is a string carrying details about the citation it is about to perform.

Next, Supercite visits each line in the reply, transforming the line according to a customizable "script". Lines which were not previously cited in the original message are given a citation, while already cited lines remain untouched, or are coerced to your preferred style. Finally, Supercite installs a keymap into the reply buffer so that you have access to Supercite's post-yank formatting and reciting commands as you subsequently edit your reply. You can tell that Supercite has been installed into the reply buffer because that buffer's modeline will display the minor mode string `SC'.

When the original message is cited by sc-cite-original, it will (optionally) be filled by Supercite. However, if you manually edit the cited text and want to re-fill it, you must use an add-on package such as filladapt or gin-mode. These packages can recognize Supercited text and will fill them appropriately. Emacs' built-in filling routines, e.g. fill-paragraph, do not recognize cited text and will not re-fill them properly because it cannot guess the fill-prefix being used. See section 9. Post-yank Formatting Commands, for details.

As mentioned above, Supercite provides commands to recite or uncite regions of text in the reply buffer, and commands to perform other beautifications on the cited original text, maintaining consistent and informative citations throughout. Supercite tries to be as configurable as possible to allow for a wide range of personalized citation styles, but it is also immediately useful with the default configuration, once it has been properly connected to your MUA. See section 5. Getting Connected, for more details.

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