Supercite User's Manual
First Edition, Supercite Version 2.2
May 1991
Barry A. Warsaw bwarsaw@cen.com ...!uunet!cen.com!bwarsaw Copyright (C) 1991 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 is a GNU Emacs package written entirely in elisp which interfaces to common mail and news reading subsystems, and provides sophisticated citing and attributing of the original messages. Supercite has a very specific and limited role in the process of composing replies to both Netnews and Electronic Mail.
Supercite is only useful in conjunction with mail/news reading subsystems such as VM, GNUS, RMAIL, etc. (hereafter referred to collectively as readers). Supercite is typically called through a hook, defined by the reader, when the initial reply buffer is set up. Thereafter, supercite's many commands and formatting styles are available in that reply buffer until the reply is sent, at which time supercite is re-initialized and ready for the next reply.
The current version of supercite is 2.2 and this version is known to work with GNU Emacs 18.57 based readers such as RMAIL, RNEWS, and MH-E, as well as all versions of GNUS up to this writing (3.12 and 3.13), GNEWS, all versions of VM up to this writing (VM version 4 from 4.37 to 4.41 and VM version 5) and PCMAIL. Only VM and MH-E (version 3.7 which was released with emacs 18.57) will work with supercite "out of the box." All other readers must overload interfacing routines, supplied with the supercite package, to provide the necessary glue between the reader and supercite. See section Getting Connected for more details.
Standard operating procedure is usually as follows. You want to reply or followup to an article or message in the reader you are using. Typically, you will enter r or f to begin composing the reply. The reader you are using will create a buffer and initialize the mail headers appropriately. At this point you will probably be faced with an empty reply buffer. Now you decide that you would like to include part of the original message in your reply so you "yank" the original message into the reply buffer, typically with a key stroke such as C-c C-y. This should invoke a reader specific function which fills the buffer with the raw original message and then runs a hook to massage the reply buffer. When you've connected supercite to this hook, it will run at this time, extracting useful information from the various yanked mail headers, creating an attribution string, citing the original message, and inserting a reference header.
Because of this clear division of labor between supercite and the reader, some useful operations, which at first thought should be under the domain of supercite, are really the responsibility of the reader package. For example, many people have indicated that they would like to be able to yank (and cite) only a portion of the original message. Since supercite only modifies the raw text it finds in the buffer as set up by the reader, it is the reader's responsibility to do partial yanking. However, supercite can be told to not modify the text when called via the hook, in which case the raw reply will remain unchanged, but supercite will be initialized for manual citing. See section Reply Buffer Initialization.
@vindex{mail-header-separator}
Another potentially useful thing would be for supercite to set up the
outgoing mail headers with information it gleans from the reply buffer
composition. But by previously agreed upon convention, any text above
the mail-header-separator (typically
`--text follows this line--')
which separates mail headers from message bodies is not
modifiable by supercite. Supercite has no understanding of the semantics
of these headers. See section Hints to Reader Authors for more
details.
Though supercite is usually loaded and run initially through a hook function, it will "leach" onto the major-mode of the reply buffer by extending the keymap of the buffer, and modifying its major-mode documentation string. In this way, after the initial yank of included text, all of supercite's post-yank formatting commands will be available in the reply buffer, without any advanced knowledge by the reader of supercite's existence or use by you.
Supercite provides routines to do automatic filling of cited text, commands to recite or uncite regions of text in the reply buffer, and commands to perform other beautifications on the reply, 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 reader. See section Getting Connected for more details.