This is the distribution of Supercite 2.2, released May 1991, It is an
elisp utility to do fancy citing of reply messages for various mail
and news reading subsystems for GNU emacs.  This version fixes bugs,
adds features, and removes some unused things from version 2.1,
originally released in August 1990.  See the file ChangeLog for more
details.

LCD Entry:
supercite|Barry A. Warsaw|bwarsaw@cen.com
|Mail citation package for mail/news readers (3 shar files)
|29-Jun-1991|2.2|

Things removed:

	* Cheapcite. Consider this a failed experiment ;-}. I conducted a
	  poll of the supercite listers and it turns out nobody was really
	  using it anyway (at least no one who responded).  Plus it was
	  just too hard to maintain 2 versions of the same code, and
	  cheapcite didn't really appear to improve the benefit/size
	  costs. If you still want cheapcite, get it from the 2.1
	  distribution.

	* MH-E overloading. This version of supercite is based on emacs
	  18.57 and the mh-e.el mode distributed with emacs 18.57 now
	  supports the necessary hooks. Nothing prohibits you from using
	  supercite 2.2 with emacs versions before 18.57, but if you use
	  MH-E mode with these earlier versions, either save the
	  overloading routines from version 2.1 sc-oloads.el, or grab
	  mh-e.el from 18.57.  I understand its drop-in compatible (but I
	  don't use MH-E so I don't know for sure that this is the case).

Things added:

	* sc.texinfo. Yes, I actually got motivated to write a texinfo
	  manual for this beast. I think it beats the hell out of
	  sc-describe and so I've chopped all that sc-describe stuff out.

	* nicknames. A new variable sc-nickname-alist for matching names
	  to nicknames on a one to many basis.  Nicknames can't currently
	  be automatically used for attribution strings, but will always
	  be presented in attribution completions.

	* GNEWS overloads.

	* new variable sc-header-nuke-list for easier user defining mail
	  headers which get zapped.

	* new variable sc-spacify-name-chars for converting certain funny
	  characters which can be found in names to spaces.

	* new variable sc-all-but-cite-p for setting up all supercite
	  info, but not citing included text. Good for manually citing
	  portions of large messages.

	* new variable sc-auto-fill-query-each-paragraph-p for really fine
	  control of auto filling.

	* new command sc-view-field (C-c f), similar to, but different
	  than, sc-modify-information.

	* new info keys (for use with sc-field): "sc-reply-address" and
	  "sc-from-address".

Things fixed or changed:

	* electric reference mode has been improved slightly so that you
	  shouldn't ever encounter a catastrophic error, where your keymap
	  is fried.  it now works slightly differently and some of the
	  redundant keybindings were removed.

	* changed sc-run-hook to sc-post-hook and added sc-pre-hook. You
	  might want to use these for pre- and post- processing (i.e.
	  changing the header rewrite style based on replying or following
	  up).

	* sc-cite-original no longer binds sc-electric-p to nil so you
	  can be automatically dropped into electric referencing mode in
	  the first yank of the message.

	* renamed all files to begin with sc for consistency (and popular
	  demand).

	* sc-cite-regexp was enhanced to help with inconsistent citation
	  warnings.

	* sc-version takes a numeric argument for inserting into a buffer.

	* massive rewrite of built-in header rewrite functions. they now
	  are more intelligent about what they insert. No more "mumble"
	  strings! Also, changed sc-header-regarding-writes to
	  sc-header-regarding-adds, and put back sc-header-verbose due to
	  popular demand.  Finally, added sc-no-blank-line-or-header. 

	* many bug fixes and optimizations.


-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
This package should contain the following files:

	sc-alist.el 	Association list utilities
	sc-electric.el	Electric insert mode
	sc-oloads.el	Overloading functions
	sc.el       	Supercite version 2.2 main file
	sc.texinfo  	Texinfo manual for supercite version 2.2
	README      	Introduction to supercite version 2.2 (this file)
	ChangeLog   	Differences from version 2.1

Supercite 2.2 has been tested and is known to work with VM 4.37+ and
MH-E 3.7 (distributed with emacs 18.57) out of the box. Supercite will
work with GNUS 3.12+, RMAIL, RNEWS, GNEWS, PCMAIL, and other
packages, once the proper functions have been overloaded (see below).

To learn more about linking to and using supercite, see the associated
texinfo manual.  For those who aren't familiar with GNU's standard
method of distributing documentation manuals, texinfo files can be
used to generate both an on-line and hard copy version of a manual
from a single ascii file.  Texinfo files can be processed by the TeX
typesetting system (not written by GNU, but freely available from many
ftp sites) and converted into PostScript or other printer ready
formats.  Also, the same texinfo file can be processed within emacs to
generate an "info" file, suitable for emacs' on-line info browser.

I believe the emacs distribution comes with an info node called
Texinfo which describes how to generate both hardcopy and on-line
manuals from a given texinfo file (such as sc.texinfo), as well as how
to write such manuals yourself.  To find out more about texinfo files,
while in emacs, type "C-h i" to get you into the info browser, then
type "mTexinfo <RET>" to enter the Texinfo branch. If you have
problems, or for more information, contact the various emacs mailing
lists or news groups.  If you have problems specific to sc.texinfo,
you can naturally contact the supercite mailing list for help.

What follows below is a quick guide to connecting supercite to your
favorite news/mail reader.  It is excerpted from the texinfo file.

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Getting Connected
*****************
Early in supercite's development, the supercite author, many of the
major reader subsystem authors, and some supercite users got together
and agreed upon a standard interface between all readers and any
supercite-like package (of which supercite is the only known one :-).
*Note Hints to Reader Authors:: for more information on the details of
this interface.  You may want to also *Note Thanks and History:: for
details on how this interface was proposed and adopted.

Suffice to say that at the time of this writing (May 1991), only VM
4.37+ and MH-E 3.7 (as distributed with emacs 18.57) conform to this
interface "out of the box."  If you are connecting supercite to one of
these two packages, you do not need overloading. All other reader
packages must be modified to provide this interface.  The file
`sc-oloads.el' contains "overloading" routines which will allow
you to connect supercite with any of the known major readers currently
in existence (*Note Overloading for Selected Readers::).  This includes:
GNUS 3.12+, GNEWS, RMAIL 18.55+, RNEWS 18.55+ and PCMAIL.  If you are
using a reader package other than one of those mentioned above, contact
the supercite mailing list about getting or writing overloading
functions for that package (*Note The Supercite Mailing List::).

Quick Guide for All Readers
===========================
For any reader package except MH-E, you will need to connect supercite
to the standard hook variable `mail-yank-hooks'.  MH-E users will
need to connect supercite to `mh-yank-hooks'. The supercite
function `sc-cite-original' is intended to be run from a hook. It
not only cites the text, also does much pre- and post-processing on the
reply buffer (*Note Replying and Yanking::) so it should be the first
supercite function to be called on a raw reply buffer. Thus, you will
need one of the following two lines in your `.emacs' file:

     (setq mail-yank-hooks 'sc-cite-original) ; for all but MH-E
     (setq mh-yank-hooks   'sc-cite-original) ; for MH-E only

Also, if supercite is not compiled into your emacs image, you will need
to set up the following autoload, also in your `.emacs' file:

     (autoload 'sc-cite-original "sc" "Supercite 2.2" t)

Supercite will run the user definable hook `sc-load-hook' after
loading. Default value for this variable is `nil'.

Overloading for Selected Readers
================================

Most readers contain hardwired citing styles (often unpopular!) which
cannot be changed. For these readers, you are required to overload the
necessary functions so that they call a hook (i.e., `mail-yank-hooks')
after inserting the original text into the buffer.  This hook can then
be set to call `sc-cite-original' at the appropriate time.

Once again, note that if you are connecting supercite to either MH-E 3.7
or VM 4.37+, you do not need overloading and can skip this section.

Quick Guide to Overloading
--------------------------

Since supercite's overloading routines are usually not loaded into your
emacs session until they are needed, you should add the following small
function to your `.emacs' file.  This will load (via the `require') the
supercite overloading package, and then actually overload the functions
for the particular reader your are using.  Only those original reader
functions already bound will be overloaded, and they will only be
overloaded once per session.

     (defun my-sc-overload-hook ()
       (require 'sc-oloads)     ; be sure this file is on your load-path
       (sc-overload-functions))

Next, you will need to find a hook in the reader which will be called at
an appropriate time to execute `my-sc-overload-hook'. It can be
something of a guessing game to find the right hook, but fortunately
that's already been done for all the readers supercite currently knows
about. You should put one of these two lines in your `.emacs' file:

     (setq news-reply-mode-hook 'my-sc-overload-hook) ; for RNEWS,GNEWS,GNUS
     (setq mail-setup-hook      'my-sc-overload-hook) ; for RMAIL,PCMAIL,GNUS

Note that if you have `sc-oloads.el' compiled into your emacs image, you
do not need `my-sc-overload-hook'. Instead just use one of the following
code fragments:

     (setq news-reply-mode-hook 'sc-overload-functions) ; for RNEWS,GNEWS,GNUS
     (setq mail-setup-hook      'sc-overload-functions) ; for RMAIL,PCMAIL,GNUS

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Enjoy, and please send the author your questions, suggestions,
patches, enhancements and bug reports.  Don't forget, if you're
interested in discussing supercite, join the mailing list by sending
mail to the supercite-request address below.

If you do send bug reports, please indicate the version of supercite
and emacs that you are using and the name and version number of the
reader package you're trying to interface with. This will help you in
getting your problem resolved. There are many very helpful people on
the mailing list, representing probably every supported reader
subsystem.  But no one person uses them all (well, definitely *not*
the supercite author :-), and you want to be able to draw the
attention of the right people.

NAME: Barry A. Warsaw      USMAIL: Century Computing, Inc.
TELE: (301) 593-3330               1014 West Street
INET: bwarsaw@cen.com              Laurel, Md 20707
UUCP: uunet!cen.com!bwarsaw

Want to be on the Supercite mailing list?

Send articles to:
    Internet: supercite@warsaw.nlm.nih.gov
        UUCP: uunet!warsaw.nlm.nih.gov!supercite

Send administrivia (additions/deletions to list, etc) to:
    Internet: supercite-request@warsaw.nlm.nih.gov
        UUCP: uunet!warsaw.nlm.nih.gov!supercite-request

Local Variables:
mode: indented-text
tab-width: 4
left-margin: 8
fill-column: 74
version-control: never
End:
