Supercite User's Manual
Supercite Version 3.1
Manual Revision: 3.47 August 1993
Barry A. Warsaw bwarsaw@cen.com ...!uunet!cen.com!bwarsaw Copyright (C) 1993 Barry A. Warsaw
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
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:
For systems with version numbers, all known subsequent versions also work with Supercite. For those systems without version numbers, Supercite probably works with any recently released version. Note that only some of these systems will work with Supercite "out of the box." All others must overload interfacing routines to supply the necessary glue. See section Getting Connected for more details.
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.
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 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 Hints to MUA Authors for more
details.
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 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 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 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 Getting Connected for more details.