\input texinfo  @comment -*-Texinfo-*-
@setfilename ../info/sc.info
@settitle Supercite User's Manual
@iftex
@finalout
@end iftex
@c @setchapternewpage odd		% For book style double sided manual.
@c      @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % For printing in double spaces
@end tex
@ifinfo
This document describes the Supercite package for citing and attributing
the replies for various GNU Emacs mail and news reading subsystems.

Copyright @copyright{} 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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo
@c
@titlepage
@sp 6
@center @titlefont{Supercite User's Manual}
@sp 4
@center First Edition, Supercite Version 2.3
@sp 1
@center May 1991
@sp 5
@center Barry A. Warsaw
@center @t{bwarsaw@@cen.com}
@center @t{...!uunet!cen.com!bwarsaw}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 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.

@end titlepage
@page
@ifinfo
@node Top, Introduction, , (dir)    
@comment  node-name,  next,  previous,  up

This document describes the Supercite package for citing and attributing
the replies for various GNU Emacs mail and news reading subsystems. The
manual is divided into the following chapters.

@menu
* Introduction::                    Overview of Supercite.
* Citation Styles::                 Different style for citing the reply.
* References and Information::      Informative headers describing citations.
* Getting Connected::               Connecting supercite to reader subsystems.
* Replying and Yanking::            What happens when you yank-reply a message.
* Post-yank Formatting Commands::   Things you can do after the initial yank.
* Keymaps::                         How to customize supercite key bindings.
* Hints to Reader Authors::         Hints to authors of reader packages.
* Thanks and History::              Recognizing those who have contributed.
* The Supercite Mailing List::      How to get on and post articles.

Indices:

* Command Index::   Menus of commands and their references.
* Concept Index::   Menus of concepts and their references.
* Key Index::       Menus of command keys and their references.
* Variable Index::  Menus of variables and their references.
@end menu
@end ifinfo

@node Introduction, Citation Styles, Top, Top    
@comment  node-name,  next,  previous,  up
@unnumbered Introduction
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.

@cindex readers, mail/news
Supercite is only useful in conjunction with mail/news reading
subsystems such as VM, GNUS, RMAIL, etc. (hereafter referred to
collectively as @dfn{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.3 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.  @xref{Getting Connected} for more details.

As of this writing (30-Dec-1992) version 2.3 is now compatible with
Lucid Emacs 19.3. This is the only substantive difference between
version 2.3 and version 2.2.

@kindex r
@kindex f
@kindex C-c C-y

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 @kbd{r} or @kbd{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 @kbd{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.
@xref{Reply Buffer Initialization}.@refill

@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 @code{mail-header-separator} (typically
@samp{--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.  @xref{Hints to Reader Authors} for more
details.@refill

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.
@xref{Getting Connected} for more details.
@node Citation Styles, References and Information, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Citation Styles
@cindex nested citations
@cindex citation
@cindex nested citations
A @dfn{citation} is the acknowledgment of the original author of a mail
message, in the body of the reply. There are two basic citation styles
which supercite supports. The first, called @dfn{nested citation} style
is an anonymous form of citation; in other words, an indication is made
that the cited line was written by someone @emph{other} that the current
message author (i.e., other than you, composing this reply), but no
reference is made as to the identity of the original author. Here's an
example of what a message buffer would look like using nested citations
after multiple replies:

@example
>> John originally wrote this
>> and this as well
> Jane said that John didn't know
> what he was talking about
And that's what I think too.
@end example

Note that multiple inclusions of the original messages result in a
nesting of the ``@code{>}'' characters.  This can sometimes be quite
confusing when many levels of citations are included since it may be
difficult or impossible to figure out who actually wrote the first
included message. Also, the multiple nesting of ``@code{>}'' characters
can sometimes make the message very difficult for the eye to scan.

@cindex non-nested citations
In @dfn{non-nested citation} style, each cited line begins with an
informative string attributing that line to the original author. Only
the first level of attribution will be shown; subsequent citations don't
nest the citation strings. The above dialog might look like this when
non-nested citation style is used:

@example
John> John originally wrote this
John> and this as well
Jane> Jane said that John didn't know
Jane> what he was talking about
And that's what I think too.
@end example

Notice here that my inclusion of Jane's inclusion of John's original
message did not result in a line cited with @samp{Jane>John>}.

@vindex sc-nested-citation-p
@vindex nested-citation-p (sc-)
The supercite variable @code{sc-nested-citation-p} controls the style of
citations. When @code{nil} (the default), non-nested citations are used.
When non-@code{nil}, nested citations are used.
@ifinfo

@menu
* Citation Elements::           Composing citation strings.
* Attributions::                Automatic attribution string selection.
* Author Names and Nicknames::  How supercite deciphers author's names.
@end menu
@end ifinfo
@node Citation Elements, Attributions, Citation Styles, Citation Styles
@comment  node-name,  next,  previous,  up
@section Citation Elements
@cindex citation string
@cindex citation delimiter
@vindex sc-citation-delimiter
@vindex citation-delimiter (sc-)
@dfn{Citation strings} are composed of one or more elements. Nested
citations, being less complex (and less informative) than non-nested
citations, are composed of only a single element, the
@dfn{citation delimiter}.  This string is user defined in the variable
@code{sc-citation-delimiter} and has a default value of @code{">"}.
Nested citations will contain a single space between the last level
(oldest) citation and the original text. It is usually a good idea to
make @code{sc-citation-delimiter} a single character.

Non-nested citations are composed of four elements, three of which are
directly user definable.  The elements are concatenated together, in
this order:

@cindex citation leader
@vindex citation-leader (sc-)
@vindex sc-citation-leader
@enumerate
@item
the @dfn{citation leader}.  The citation leader is contained in the
variable @code{sc-citation-leader}, and has the default value of a
string containing a single tab character.

@cindex attribution string
@item
the @dfn{attribution string}.  This element is supplied automatically by
supercite, based on your preferences and the original message's mail
headers, though you may be asked to confirm supercite's choice.
@xref{Attributions} for more details.

@item
the citation delimiter as described above.

@cindex citation separator
@vindex citation-separator (sc-)
@vindex sc-citation-separator
@item
the @dfn{citation separator}.  The citation separator is contained in
the variable @code{sc-citation-separator}, and has the default value of
a string containing a single space character.
@end enumerate

@vindex sc-cite-regexp
@vindex cite-regexp (sc-)
For example, suppose, you were using the default values for the above
variables, and supercite provided the attribution string @samp{Jane}.
In this case, the composed, non-nested citation string used might be
something like @samp{\tJane> } (the @samp{\t} represents a tab
character). This citation string will be inserted in front of every line
in the original message that is not already cited. Supercite uses the
regular expression in the variable @code{sc-cite-regexp} to determine
whether a line is already cited or not.  The default value for this
variable is:

@example
"\\s *[-a-zA-Z0-9_.]*>+\\s *"
@end example

@noindent
Nemacs users may want to set @code{sc-cite-regexp} to:

@example
"\\s *\\([a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\)*\\s *>+"
@end example
@node Attributions, Author Names and Nicknames, Citation Elements, Citation Styles
@comment  node-name,  next,  previous,  up
@section Attributions
@cindex attribution list
@vindex sc-preferred-attribution
@vindex preferred-attribution (sc-)
The attribution string is the part of the author's name that will be
used in a composed non-nested citation string to acknowledge the
originator of a section of text. Supercite scans the various mail
headers present in the original article and uses a number of heuristics
to extract strings which it puts into the @dfn{attribution list}. This
list contains such information as the author's first, middle, and last
names, the author's initials, and the author's email terminus. It is
consulted during automatic composition of the citation string, and will
be the list presented to you if attribution confirmation is selected
(also @pxref{Replying and Yanking}). The variable
@code{sc-preferred-attribution} allows you to determine which part of
the author's name should be used when supercite composes automatic
citation strings.  The value of this variable must be one of the
following quoted symbols:

@table @code
@item emailname
the author's email terminus.

@item initials
the author's initials.

@item firstname
the author's first name.

@item lastname
the author's last name.

@item middlename1
the author's first middle name.
@end table

Middle name indexes can be any positive integer greater than zero,
though it is unlikely that many authors will supply more than one middle
name, if that many.  Default value for @code{sc-preferred-attribution}
is @code{'firstname}.

@vindex sc-default-author-name
@vindex sc-default-attribution
@vindex default-author-name (sc-)
@vindex default-attribution (sc-)
When, for whatever reason, the author's name cannot be found in the
@samp{From:} mail header, a default author name and attribution string
must be supplied. The default author name is set in the variable
@code{sc-default-author-name} (default value is @code{"Anonymous"}), and
the default attribution string is contained in the variable
@code{sc-default-attribution}, (default value is @code{"Anon"}).  Note
that in most circumstances, getting the default author name or
attribution is a sign that something is set up incorrectly.

@vindex sc-use-only-preference-p
@vindex use-only-preference-p (sc-)
Also, if your preferred attribution cannot be found, or is either
@code{nil} or the empty string, a secondary method can be employed to
find a valid attribution string. The variable
@code{sc-use-only-preference-p} controls what happens in this case. If
@code{sc-use-only-preference-p} is non-@code{nil}, then
@code{sc-default-author-name} and @code{sc-default-attribution} are
used, otherwise, the following steps are taken to find a valid
attribution string. The first step to return a non-@code{nil}, non-empty
string becomes the attribution:@refill

@vindex sc-confirm-always-p
@vindex confirm-always-p (sc-)
@enumerate
@item 
Use the author's first name.

@item 
Find the first non-@code{nil}, non-empty attribution string in the
attribution list.

@item 
If the variable @code{sc-confirm-always-p} is non-@code{nil}, then
you are queried for an attribution string with a completing read. The
possible values for completion are those strings in the attribution
list, however, you can override all presented strings by simply typing
in your attribution at the prompt.

@item 
@code{sc-default-attribution} is used.
@end enumerate

@vindex sc-downcase-p
@vindex downcase-p (sc-)
Finally, once a legal attribution string is found, you can force the
string to lower case characters by setting the variable
@code{sc-downcase-p} to non-@code{nil}.
@node Author Names and Nicknames, , Attributions, Citation Styles
@comment  node-name,  next,  previous,  up
@section Author Names and Nicknames
@cindex author names
Supercite employs a number of heuristics to decipher the author's name
base on the @samp{From:} field.  Supercite can recognize @samp{From:}
fields with the following forms:

@enumerate
@item 
@code{From: John Xavier Doe <doe@@speedy.computer.com>}
@item 
@code{From: "John Xavier Doe" <doe@@speedy.computer.com>}
@item 
@code{From: doe@@speedy.computer.com (John Xavier Doe)}
@item 
@code{From: computer!speedy!doe (John Xavier Doe)}
@item 
@code{From: doe%speedy@@computer.com (John Xavier Doe)}
@item 
@code{From: computer!speedy!doe (John Xavier-Doe)}
@item 
@code{From: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)}
@item 
@code{From: doe@@speedy.computer.com}
@item 
@code{From: computer!speedy!doe}
@end enumerate

@vindex sc-titlecue-regexp
@vindex titlecue-regexp (sc-)
Note that some author fields (as in example 7 above) will contain a
descriptive title. The user can choose to ignore the title, while still
recognizing hyphenated names (as in the second to last example above),
through the use of a regular expression in the variable
@code{sc-titlecue-regexp}. This variable has the default value of
@code{"\\\\s +-+\\\\s +"}.

@vindex sc-spacify-name-chars
@vindex spacify-name-chars (sc-)
Some author names may contain non-alphanumeric characters, especially if
the author's name is extracted from their email terminus. You can
specify that those characters in the author's name be converted to spaces
with the variable @code{sc-spacify-name-chars}. This is a list of
characters suitable for @code{memq}. Default value for this variable is
@code{'(?_ ?* ?+ ?=)}.

For @samp{From:} lines matching one of these styles, supercite will be
able to pick out the author's full name (i.e., @code{"John Xavier Doe"})
and the author's email terminus or email name (i.e., @code{"doe"}). In
examples 8 and 9 above, the author's name will be the email terminus
(i.e., @code{"doe"}). The name extracted by supercite is then split into
its individual components and kept in the attribution list either for
supercite's automatic use, or for presentation to you in a completing
confirmation.  When asked to confirm the selected attribution, supercite
will present you with this list, but you can add new attributions to the
list by just typing it in at the prompt. The selected attribution
(whether completed or added) is remembered as the selected attribution
for future operations or completions.

@vindex sc-nicknames-alist
@vindex nicknames-alist (sc-)
Many names also have common nicknames which supercite cannot
automatically decipher. Therefore, supercite consults a variable
@code{sc-nicknames-alist} which contains a list of common name to
nickname associations. While supercite cannot automatically use a
nickname as the attribution string, matching nicknames will be presented
to you when attribution confirmation is requested (@xref{Post-yank
Formatting Commands}). Any part of the author's name can match an entry
in this list, and one name can match more than one nickname. The list
contains associations of the form:@refill

@example
(NAME NICKNAME)
@end example

@noindent
Default value for this variable is:

@example
@group
'(("Michael" "Mike")
  ("Daniel" "Dan")
  ("David" "Dave")
  ("Jonathan" "John")
  ("William" "Bill")
  ("Elizabeth" "Beth")
  ("Elizabeth" "Betsy")
  ("Kathleen" "Kathy")
  ("Smith" "Smitty"))
@end group
@end example
@node References and Information, Getting Connected, Citation Styles, Top    
@comment  node-name,  next,  previous,  up
@chapter References and Information
@cindex reference headers
Supercite will insert an informative @dfn{reference header} at the
beginning of the cited body of text, which provides more detail about
the original article.  Whereas the citation string usually only contains
a portion of the original author's name, the reference header can
contain such information as the author's full name, email address, the
original article's subject, etc.  In fact, just about any information
contained in the mail headers of the original article can be inserted
into a reference header.

@cindex header rewrite functions
@vindex sc-rewrite-header-list
@vindex rewrite-header-list (sc-)
There are a number of built-in @dfn{header rewrite functions} supplied
by supercite, but supercite is extensible in that you can write your own
custom header rewrite functions (perhaps using the built-in ones as
examples) and tell supercite to use your function. In fact, supercite
consults a list of header rewrite functions in the variable
@code{sc-rewrite-header-list}. You can put any rewrite function, custom
or built-in, into this list.  This list has the default value:

@example
'((sc-no-header)
  (sc-header-on-said)
  (sc-header-inarticle-writes)
  (sc-header-regarding-adds)
  (sc-header-attributed-writes)
  (sc-header-verbose)
  (sc-no-blank-line-or-header)).
@end example

@vindex sc-preferred-header-style
@vindex preferred-header-style (sc-)
When supercite is called via its hook function @code{sc-cite-original},
it will automatically call one of these functions to insert a reference
header. The one it uses is user definable in the variable
@code{sc-preferred-header-style}.  The value of this variable is an
integer which is an index into the @code{sc-header-rewrite-list}, with
the first function indexed at zero. The default value for this variable
is 1 (i.e., default values use the function @code{sc-header-on-said} when
automatically rewriting the header).
@ifinfo

@menu
* The Built-in Header Rewrite Functions::   Inserting informative headers.
* Mail Fields and Information Keys::        How information is obtains.
* Electric References::                     View headers before insertion.
@end menu
@end ifinfo
@node The Built-in Header Rewrite Functions, Mail Fields and Information Keys, , References and Information
@comment  node-name,  next,  previous,  up
@section The Built-in Header Rewrite Functions
@cindex header rewrite functions, built-in
@ifinfo

@end ifinfo
Below are examples of the styles of the various built-in header rewrite
functions. Please note the following: first, the text which appears in
the examples below as @samp{@var{fieldkey}} indicates that the value of
a particular @dfn{information key} corresponding to
@samp{@var{fieldkey}} will be inserted there. (@xref{Mail Fields and
Information Keys}).  For example, in @code{sc-header-on-said} below,
@samp{@var{date}} and @samp{@var{from}} correspond to the values of the
@samp{Date:} and @samp{From:} mail headers respectively.@refill

@vindex sc-reference-tag-string
@vindex reference-tag-string (sc-)
Also, the string ``@code{>>>>>}'' below is really the value of the
variable @code{sc-reference-tag-string}, which is user definable.
Finally, the references headers actually written may omit certain parts
of the header if the information key associated with @var{fieldkey} is
not present.  In fact, for all built-in headers, if the @samp{From:}
field is not present in the mail headers, the entire reference header
will be omitted.

@table @code
@findex sc-no-header
@findex no-header (sc-)
@item sc-no-header
This function produces no header. It should be used instead of
@code{nil} to produce a blank header.  This header can possibly contain
a blank line after the @code{mail-header-separator} line.

@item sc-no-blank-line-or-header
@findex sc-no-blank-line-or-header
@findex no-blank-line-or-header (sc-)
This function is similar to @code{sc-no-header} except that any blank
line after the @code{mail-header-separator} line will be removed.

@item sc-header-on-said
@findex sc-header-on-said
@findex header-on-said (sc-)
@example
>>>>> On @var{date}, @var{from} said:
@end example

@item sc-header-inarticle-writes
@findex sc-header-inarticle-writes
@findex header-inarticle-writes (sc-)
@example
>>>>> In article @var{message-id}, @var{from} writes:
@end example

@item sc-header-regarding-adds
@findex sc-header-regarding-adds
@findex header-regarding-adds (sc-)
@example
>>>>> Regarding @var{subject}; @var{from} adds:
@end example

@item sc-header-attributed-writes
@findex sc-header-attributed-writes
@findex header-attributed-writes (sc-)
@example
>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:
@end example

@item sc-header-verbose
@findex sc-header-verbose
@findex header-verbose (sc-)
@example
@group
>>>>> On @var{date},
>>>>> @var{sc-author}
>>>>> from the organization of @var{organization}
>>>>> who can be reached at: @var{sc-reply-address}
>>>>> (whose comments are cited below with: "@var{sc-cite}")
>>>>> had this to say in article @var{message-id}
>>>>> in newsgroups @var{newsgroups}
>>>>> concerning the subject of @var{subject}
>>>>> see @var{references} for more details
@end group
@end example
@end table
@node Mail Fields and Information Keys, Electric References, The Built-in Header Rewrite Functions, References and Information
@comment  node-name,  next,  previous,  up
@section Mail Fields and Information Keys
@ifinfo

@end ifinfo
@cindex information keys
@cindex key-value pairs
@cindex information extracted from mail fields
@findex sc-field
@findex field (sc-)
@dfn{Information keys} are nuggets of information that supercite
extracts from various mail fields placed in the reply buffer by the
reader.  Information is kept in a list as @dfn{key-value} pairs and can
be retrieved for use in reference headers with the function
@code{sc-field}.  In addition, other bits of data, composed and created
by supercite, are also kept as key-value pairs. In the case of mail
fields, the key is always the name of the field, cast to lower case
characters, without the trailing colon.  Thus, if the following fields
were present in the original article:@refill

@example
Date: 08 April 1991, 17:32:09 EST
Subject: Better get out your asbestos suit
@end example

@vindex sc-mumble-string
@vindex mumble-string (sc-)
@cindex mumble string
@noindent
then, @code{(sc-field "date")} would return the string
@code{"08 April 1991, 17:32:09 EST"}, and
@code{(sc-field "subject")} would return the
string @code{"Better get out your asbestos suit"}.  Since the argument
to @code{sc-field} can be any string, it is possible that the mail field
will not be present, or that the string was incorrectly typed. In this
case, @code{sc-field} will return a @dfn{mumble string} as defined in
the variable @code{sc-mumble-string}.  The default value for this
variable is the empty string (i.e., @code{""}).@refill

@vindex sc-mail-fields-list
@vindex mail-fields-list (sc-)
The variable @code{sc-mail-fields-list} contains a list of mail fields
(as information keys), which supercite will extract for use with
@code{sc-fields}.  Only the values of these mail fields will be
extracted.  Default value for this variable is:

@example
'("date"  "message-id"  "subject" "newsgroups" "references"
  "from"  "return-path" "path"    "reply-to"   "organization"
  "reply" )
@end example

Note that mail headers can also be removed from the body of the reply
once their information has been extracted.
@xref{Reply Buffer Initialization} for more details.

The @samp{From:} field will always be put into the information list
exactly once. In addition to these information keys, supercite also
always places the following keys into the information list:

@table @code
@cindex information fields
@vindex sc-attribution field
@vindex attribution(sc-) field
@item sc-attribution
the selected attribution string.

@item sc-nested-citation
@vindex sc-nested-citation field
@vindex nested-citation(sc-) field
the nested citation string.

@item sc-citation
@vindex sc-citation field
@vindex citation(sc-) field
the non-nested citation string.

@item sc-from-address
@vindex sc-from-address field
@vindex from-address(sc-) field
email address extracted from the @samp{From:} field.

@item sc-reply-address
@vindex sc-reply-address field
@vindex reply-address(sc-) field
email address extracted from the @samp{Reply-To:} field.

@item sc-emailname
@vindex sc-emailname field
@vindex emailname(sc-) field
email terminus extracted from the @samp{From:} field.

@item sc-initials
@vindex sc-initials field
@vindex initials(sc-) field
the author's initials.

@item sc-author
@vindex sc-author field
@vindex author(sc-) field
the author's full name.

@item sc-firstname
@vindex sc-firstname field
@vindex firstname(sc-) field
the author's first name.

@item sc-lastname
@vindex sc-lastname field
@vindex lastname(sc-) field
the author's last name.

@item sc-middlename-1
@vindex sc-middlename fields
@vindex middlename(sc-) fields
the author's first middle name.
@end table

As above, if the author's name has more than one middle name, they will
appear as information keys with the appropriate index.
@node Electric References, , Mail Fields and Information Keys, References and Information
@comment  node-name,  next,  previous,  up
@section Electric References
@cindex electric references
By default, supercite just goes ahead and inserts the reference header
indexed by @code{sc-preferred-header-style}.  However, you may want to
select different reference headers based on the type of reply or
forwarding you are doing. You may also want to preview the reference
header before deciding whether to insert it into the reply buffer or
not. Supercite provides an optional @dfn{electric reference} mode which
you can drop into to give you this functionality.

@vindex sc-electric-references-p
@vindex electric-references-p (sc-)
Electric reference mode is a quasi-major-mode which you enter whenever
supercite inserts a reference header and the variable
@code{sc-electric-references-p} is non-@code{nil}. Actually you are
placed into a recursive edit inside the electric reference buffer, which
is a read-only buffer.@refill

When in electric reference mode, you can scan back and forth through the
list of reference headers in @code{sc-rewrite-header-list}.  You can
also set a new preferred header style, jump to any header, or jump to
the preferred header. The header will be shown in the electric reference
buffer and the header index will appear in the echo area. You cannot,
however, actually edit the headers while in electric reference mode; you
will have to do that once the header has been inserted into the reply
buffer.

The following commands are available while in electric reference mode
(shown here with their default key bindings):

@table @asis
@item @code{sc-eref-next} (@kbd{n})
@findex sc-eref-next
@findex eref-next (sc-)
@kindex n
@vindex sc-electric-circular-p
@vindex electric-circular-p (sc-)
Displays the next reference header in the other buffer. If the variable
@code{sc-electric-circular-p} is non-@code{nil}, invoking
@code{sc-eref-next} while viewing the last reference header in the list,
will wrap around to the first header.

@item @code{sc-eref-prev} (@kbd{p})
@findex sc-eref-prev
@findex eref-prev (sc-)
@kindex p
Displays the previous reference header in the other buffer. If the
variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
@code{sc-eref-prev} will wrap around to the last header.

@item @code{sc-eref-goto} (@kbd{g})
@findex sc-eref-goto
@findex eref-goto (sc-)
@kindex g
Display the reference header indexed by @var{refnum} where @var{refnum}
is a valid index into @code{sc-rewrite-header-list}. @var{refnum} can be
supplied as a numeric argument to this command, or you will be queried
for it in the minibuffer.

@item @code{sc-eref-jump} (@kbd{j})
@findex sc-eref-jump
@findex eref-jump (sc-)
@kindex j
Display the preferred reference header -- the one indexed by the current
value of @code{sc-preferred-header-style}.

@item @code{sc-eref-exit} (@kbd{q}, @key{LFD}, and @key{RET})
@kindex RET
@kindex LFD
@kindex q
@findex sc-eref-exit
@findex eref-exit (sc-)
Exit from electric reference mode and insert the current header into the
reply buffer.  Also note that exiting the recursive edit (with command
@code{(exit-recursive-edit)}, typically bound to @kbd{ESC C-c}),
executes sc-eref-exit.

@item @code{sc-eref-abort} (@kbd{x})
@findex sc-eref-abort
@findex eref-abort (sc-)
@kindex x
Exit from electric reference mode without inserting the current header.

@item @code{sc-eref-setn} (@kbd{s})
@findex sc-eref-setn
@findex eref-setn (sc-)
@kindex s
Set the preferred reference header (i.e.,
@code{sc-preferred-header-style}) to the currently displayed header.
@end table

@vindex sc-electric-mode-hook
@vindex electric-mode-hook (sc-)
@noindent
Supercite will execute the hook @code{sc-electric-mode-hook} before
entering electric reference mode.
@node Getting Connected, Replying and Yanking, References and Information, Top
@comment  node-name,  next,  previous,  up
@chapter 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 :-).
@xref{Hints to Reader Authors} for more information on the details of
this interface.  You may want to also @pxref{Thanks and History} for
details on how this interface was proposed and adopted.

@cindex overloading
@cindex sc-oloads.el
Suffice to say that at the time of this writing (May 1991), only VM (all
versions after 4.37) and MH-E (version 3.7, which is 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 @file{sc-oloads.el} contains @dfn{overloading}
routines which will allow you to connect supercite with any of the known
major readers currently in existence (@pxref{Overloading for Selected
Readers}).  This includes: GNUS (versions 3.12 and 3.13), GNEWS, RMAIL
and RNEWS (as distributed with emacs versions after and including
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 (@pxref{The Supercite
Mailing List}).
@ifinfo

@menu
* Quick Guide for All Readers::         What all users must do.
* Overloading for Selected Readers::    What only some users must do.
@end menu
@end ifinfo
@node Quick Guide for All Readers, Overloading for Selected Readers, Getting Connected, Getting Connected
@comment  node-name,  next,  previous,  up
@section Quick Guide for All Readers
@vindex mail-yank-hooks
@vindex mh-yank-hooks
@findex sc-cite-original
@findex cite-original (sc-)
For any reader package except MH-E, you will need to connect supercite
to the standard hook variable @code{mail-yank-hooks}.  MH-E users will
need to connect supercite to @code{mh-yank-hooks}. The supercite
function @code{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 (@pxref{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 @file{.emacs} file:

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

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

@example
(autoload 'sc-cite-original "sc" "Supercite 2.3" t)
@end example

@vindex sc-load-hook
@vindex load-hook (sc-)
Supercite will run the user definable hook @code{sc-load-hook} after
loading. Default value for this variable is @code{nil}.
@node Overloading for Selected Readers, , Quick Guide for All Readers, Getting Connected
@comment  node-name,  next,  previous,  up
@section Overloading for Selected Readers
@cindex overloading
@ifinfo

@end ifinfo
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.,
@code{mail-yank-hooks}) after inserting the original text into the
buffer.  This hook can then be set to call @code{sc-cite-original} at
the appropriate time.@refill

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

@menu
* Quick Guide to Overloading::  What you need to put in your .emacs file.
* Overloading Details::         For extending the overloading mechanism.
@end menu
@end ifinfo
@node Quick Guide to Overloading, Overloading Details, Overloading for Selected Readers, Overloading for Selected Readers
@comment  node-name,  next,  previous,  up
@subsection Quick Guide to Overloading
@ifinfo

@end ifinfo
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 @file{.emacs} file.  This will load (via the
@code{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.@refill

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

Next, you will need to find a hook in the reader which will be called at
an appropriate time to execute @code{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 @code{.emacs}
file:@refill

@vindex news-reply-mode-hook
@vindex mail-setup-hook
@example
(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
@end example

Also for GNEWS users, you need to put the following line in your
@code{.emacs} file:

@vindex gnews-ready-hook
@example
(setq gnews-ready-hook 'my-sc-overload-hook) ; for GNEWS
@end example

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

@example
(setq news-reply-mode-hook 'sc-overload-functions) ; for RNEWS,GNEWS,GNUS
(setq mail-setup-hook      'sc-overload-functions) ; for RMAIL,PCMAIL,GNUS
(setq gnews-ready-hook     'sc-overload-functions) ; for GNEWS (need both)
@end example
@node Overloading Details, , Quick Guide to Overloading, Overloading for Selected Readers
@comment  node-name,  next,  previous,  up
@subsection Overloading Details
@ifinfo

@end ifinfo
All the overload functions can be found in the file @file{sc-oloads.el}.
In this file are a number of functions which mimic the default behavior
of the yanking functions of the major readers. They are typically
defined with the same name as their original counterparts, except that
``@code{sc-}'' is prepended to the name.  At the appropriate time, the
supercite version will be overloaded onto the original, by way of
@code{fset}-ing the function cell of the original symbol to the function
in the supercite version.  In this way, overloading is completely under
the control of the individual users, eliminating the need for a system
administrator's intervention. Overloading is a general solution to the
wider problem of extending the functionality of distribution emacs elisp
code, without requiring the editing or patching of the distribution
files, something that is often not possible for individual users.@refill

@vindex sc-overload-functions
@findex sc-overload-functions
@vindex overload-functions (sc-)
@findex overload-functions (sc-)
The function @code{sc-overload-functions} performs the actual
@code{fset} modification, though it does it in a slightly intelligent
manner. It will first check to see if the function symbol is bound, and
if not, will skip attempting to overload that symbol. Also, it will
check to see if overloading has already been performed on the symbol,
and will not try to re-overload the function. It does this by setting
the @dfn{property} @code{sc-overloaded} on the symbol after overloading
it.@refill

The variable @code{sc-overload-functions} contains an association list
of original functions to hook-ified version functions.  Entries take the
form:

@example
(ORIGINAL OVERLOAD)
@end example

@noindent
and include all the known yank/reply functions for the major reader
subsystems:

@itemize @bullet
@item 
@code{mail-yank-original}
@item 
@code{news-reply-yank-original}
@item 
@code{reply-yank}
@item 
@code{group-reply-yank}
@item 
@code{group-follow-yank}
@end itemize

If you encounter a reader package that requires overloading, but that
supercite does not currently know about, you will need to write the
reply-yanking function which cites the text, to call a hook to do the
citing. You should call that hook @code{mail-yank-hooks} for consistency
and set the default value to the default behavior of the reader. Then
add the name of the original function and the overloading function to
the @code{sc-overload-functions} association list. @xref{Hints to Reader
Authors} for more details.@refill

@node Replying and Yanking, Post-yank Formatting Commands, Getting Connected, Top
@comment  node-name,  next,  previous,  up
@chapter Replying and Yanking
@findex sc-cite-original
@findex cite-original (sc-)
@ifinfo

@end ifinfo
When you perform a yank in the reply buffer set up by your reader, it
should execute the function @code{sc-cite-original} via one of the hooks
mentioned above (@pxref{Getting Connected}).  Since this function is
called by a hook, it is not passed any arguments and so expects the raw
reply buffer to be very specifically formatted
(@pxref{Hints to Reader Authors}).
For the most part, @code{sc-cite-original} will do some
default things, based on your preferences, with very little direct
interaction with you. After the initial yank of the original message,
you can use various supercite commands to reformat and beautify your
reply (@pxref{Post-yank Formatting Commands}).@refill
@ifinfo

@menu
* Reply Buffer Initialization::     What sc-cite-original does.
* Filling Cited Text::              Automatically filling cited text.
@end menu
@end ifinfo
@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
@comment  node-name,  next,  previous,  up
@section Reply Buffer Initialization
Executing @code{sc-cite-original} performs the following initializations
of the reply buffer:
@ifinfo

@end ifinfo
@enumerate
@item 
@vindex sc-pre-hook
@vindex pre-hook (sc-)
@emph{Runs @code{sc-pre-hook}.}
You can set this variable to execute any function. It will be called
before supercite does anything.  You could conceivably use this hook to
set certain supercite variables based on the reply buffer's mode or name
(i.e., to do something different based on whether you are replying or
following up to an article).@refill

@item 
@emph{Gets information from the mail headers.}
@vindex sc-confirm-always-p
@vindex confirm-always-p (sc-)
All previously retrieved information keys are deleted, then the mail
headers in the body of the text are scanned. Information key-value pairs
are created for each header found. For example, such things as the
author's name and email address are extracted, and the attribution and
citation strings are also derived at this point. If the variable
@code{sc-confirm-always-p} is set, supercite will confirm the selected
attribution string with you at this time before it uses it in the
citation string.@refill

@item 
@vindex sc-nuke-mail-headers-p
@vindex nuke-mail-headers-p (sc-)
@vindex sc-header-nuke-list
@vindex header-nuke-list (sc-)
@emph{``Nukes'' the mail headers.} If the variable
@code{sc-nuke-mail-headers-p} is non-@code{nil}, the mail headers
@strong{in the body of the message}, will be deleted. As mentioned
before, supercite does nothing to the mail headers above the
@code{mail-header-separator} line. You can control which mail
headers are kept and which are deleted by modifying the variable
@code{sc-header-nuke-list}.  This variable contains a list of mail
headers to remove, where each entry in the list is a self contained
regular expression unit.  These units will be @code{concat}'ed together
into one big regular expression of the form:@refill

@example
@code{"^@var{header}:\\|^@var{header}:\\|}@dots{}@code{^@var{header}:"}
@end example

The entries in @code{sc-header-nuke-list} correspond to the individual
@var{header}'s in the above example, and the entries are case
insensitive. If @code{sc-header-nuke-list} is @code{nil}, no headers
will be removed (however, it is better to use
@code{sc-nuke-mail-headers-p} for this). The default value of
@code{sc-header-nuke-list} is:

@example
'("via" "origin" "status" "received" "remailed" "cc" "sender" "replied"
  "organization" "keywords" "distribution" "xref" "references" "expires"
  "approved" "summary" "precedence" "subject" "newsgroup[s]?"
  "\\(followup\\|apparently\\|errors\\|\\(\\(in-\\)?reply\\)?-\\)?to"
  "x-[a-z0-9-]+" "[a-z-]*message-id" "\\(summary-\\)?line[s]"
  "\\(\\(return\\|reply\\)-\\)?path" "\\(posted-\\)?date"
  "\\(mail-\\)?from")
@end example

@item 
@emph{Cites the message body.}
@vindex sc-all-but-cite-p
@vindex all-but-cite-p (sc-)
If the variable @code{sc-all-but-cite-p} is non-@code{nil}, the message
will not be cited. This way, you can have supercite initialize itself
and do everything but cite the text. This would be useful if you were
citing a very long article (which may take a bit of time), or for some
unique citing formats (i.e., mixed text and code, with different filling
and citing requirements).@refill

@item 
@emph{``Leaches'' onto the current buffer}.
Because supercite is intended to run with a number of different readers,
many of which will have been designed without knowledge of supercite,
and because the supercite package adds functionality to these
subsystems, it must be somewhat subversive in the way it adds its
functions to the keymaps of the current buffers, and its documentation
to the documentation strings of the major-mode of the reply buffer.
@xref{Keymaps} for more information on how supercite sets the keymap of
the reply buffer and how you can change the default key bindings.@refill

@kindex C-h m
@findex describe-mode
Once supercite has attached itself to the reply buffer, getting
major-mode help, by typing @kbd{C-h m} (@code{describe-mode}) will print
out not only the original mode documentation string, but also
supercite's documentation string. This documentation will describe the
available supercite commands and their key bindings.@refill

@item 
@emph{Runs @code{sc-post-hook}.}
@vindex sc-post-hook
@vindex post-hook (sc-)
This variable is very similar to @code{sc-pre-hook}, except that it runs
after @code{sc-cite-original} is finished. This hook is provided mostly
for completeness and backward compatibility. Perhaps it could be used to
reset certain variables set in @code{sc-pre-hook}.@refill
@end enumerate

@node Filling Cited Text, , Reply Buffer Initialization, Replying and Yanking
@comment  node-name,  next,  previous,  up
@section Filling Cited Text
@ifinfo

@end ifinfo
@cindex filling paragraphs
@vindex sc-auto-fill-region-p
@vindex auto-fill-region-p (sc-)
@vindex sc-fill-paragraph-hook
@vindex fill-paragraph-hook (sc-)
@findex sc-fill-paragraph
@findex fill-paragraph (sc-)
Supercite provides some paragraph filling functions and will
automatically fill paragraphs as they are cited, when the variable
@code{sc-auto-fill-region-p} is non-@code{nil} (the default value).
There are other packages freely available which work quite well when
filling paragraphs of the non-nested citation style (and probably better
than supercite's built-in functions!) so supercite calls the filling
function via the hook @code{sc-fill-paragraph-hook}. The default is for
supercite to call the function @code{sc-fill-paragraph}.@refill

@vindex sc-auto-fill-query-each-paragraph-p
@vindex auto-fill-query-each-paragraph-p (sc-)
You can also have supercite query you before filling each paragraph in
the cited region. This would be useful for citing an article with mixed
code and text, where you would want to fill the text regions but not the
code regions.  Set the variable
@code{sc-auto-fill-query-each-paragraph-p} to non-@code{nil} (default
value is @code{nil}) for this feature. Note that
@code{sc-auto-fill-region-p} must be non-@code{nil} for query filling
to work.@refill

Note further that turning off auto-filling does not preclude you from
manually filling each paragraph (@pxref{Post-yank Formatting Commands}).

@vindex sc-fixup-whitespace-p
@vindex fixup-whitespace-p (sc-)
Finally, supercite will collapse leading whitespace between the citation
string and the text line when the variable @code{sc-fixup-whitespace-p}
is non-@code{nil}.  The default value for this variable is
@code{nil}.@refill

@node Post-yank Formatting Commands, Keymaps, Replying and Yanking, Top    
@comment  node-name,  next,  previous,  up
@chapter Post-yank Formatting Commands
@ifinfo

@end ifinfo
Once the original message has been yanked into the reply buffer, and
@code{sc-cite-original} has had a chance to operate on the buffer, a
number of useful supercite commands will be available to you. These
commands are described in this section. Note that the key bindings given
with the command names are those for the default keymap in
@code{sc-default-keymap}.  @xref{Keymaps} for more information on
changing the key bindings.@refill
@ifinfo

@menu
* Commands to Manually Cite Recite and Uncite::
* String Insertion Commands::
* Information Commands::
* Miscellaneous Commands::
@end menu
@end ifinfo

@node Commands to Manually Cite Recite and Uncite, String Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
@comment  node-name,  next,  previous,  up
@section Commands to Manually Cite, Recite, and Uncite
@ifinfo

@end ifinfo
Probably the three most common post-yank formatting operations that you
will perform will be the manual citing, reciting, and un-citing of
regions of text in the reply buffer. Often you may want to recite a
paragraph to use a nickname, or manually cite a paragraph when using
@code{sc-all-but-cite-p}.  The following commands perform these
functions on the region of text between @emph{point} and @emph{mark}.
Each of them sets the @dfn{undo boundary} before modifying the region so
that the command can be undone in the standard emacs way.@refill

@table @asis
@findex sc-cite
@findex cite (sc-)
@kindex C-c C-t
@item @code{sc-cite} (@kbd{C-c C-t})
@ifinfo

@end ifinfo
This command cites each line in the region of text, but only if the line
is not already cited as described by @code{sc-cite-regexp}. It also
inserts a reference header at the top of the region. If you supply the
optional numeric argument, it will be passed to
@code{sc-insert-reference} (@pxref{String Insertion Commands}).  You
will always be asked to confirm the attribution string before the region
is cited, regardless of the value of @code{sc-confirm-always-p}.@refill

@findex sc-uncite
@findex uncite (sc-)
@kindex C-c C-u
@item @code{sc-uncite} (@kbd{C-c C-u})
@ifinfo

@end ifinfo
This command removes any citation strings from the beginning of each
cited line in the region.@refill

@findex sc-recite
@findex recite (sc-)
@kindex C-c C-a
@item @code{sc-recite} (@kbd{C-c C-a})
@ifinfo

@end ifinfo
This command simply un-cites, then cites the lines in the region, asking
for confirmation of the new attribution string.@refill
@end table
@node String Insertion Commands, Information Commands, Commands to Manually Cite Recite and Uncite, Post-yank Formatting Commands
@comment  node-name,  next,  previous,  up
@section String Insertion Commands
These two functions insert strings into the reply buffer.

@table @asis
@findex sc-insert-reference
@findex insert-reference (sc-)
@kindex C-c C-r
@item @code{sc-insert-reference} (@kbd{C-c C-r})
@ifinfo

@end ifinfo
Inserts a reference header into the reply buffer at point.  With no
arguments, the header indexed by @code{sc-preferred-header-style} is
inserted. An optional numeric argument is the index into
@code{sc-rewrite-header-list} indicating which reference header to
write. Of course, if @code{sc-electric-references-p} is set, you are
dropped into electric reference mode instead.@refill

With just the universal argument (@kbd{C-u}), electric reference mode is
entered, regardless of the value of @code{sc-electric-references-p}.
@findex sc-insert-citation
@findex insert-citation (sc-)
@kindex C-c C-i
@item @code{sc-insert-citation} (@kbd{C-c C-i})
@ifinfo

@end ifinfo
Inserts the current citation string at the beginning of the line that
point is on.
@end table
@node Information Commands, Miscellaneous Commands, String Insertion Commands, Post-yank Formatting Commands
@comment  node-name,  next,  previous,  up
@section Information Commands
These commands allow you to modify and view various bits of information.

@kindex C-u
@table @asis
@findex sc-modify-information
@findex modify-information (sc-)
@kindex C-c C-m
@item @code{sc-modify-information} (@kbd{C-c C-m})
@ifinfo

@end ifinfo
Allows you to interactively modify information key value pairs
(@xref{Mail Fields and Information Keys}). With the universal argument
(@kbd{C-u}), it deletes a key (and its associated value) instead. This
command will ask for completion on the information key to modify. You
can add a new key-value pair by supplying a new key string at the prompt
instead of completing.@refill

@findex sc-view-field
@findex view-field (sc-)
@kindex C-c f
@item @code{sc-view-field} (@kbd{C-c f})
@ifinfo

@end ifinfo
Allows you to simply view information key values. This is essentially an
interactive version of @code{sc-field}. It will prompt you for the
information key to view. With the universal argument (@kbd{C-u}),
this command will also insert the key value into the current buffer at
point.@refill

@findex sc-glom-headers
@findex glom-headers (sc-)
@kindex C-c g
@item @code{sc-glom-headers} (@kbd{C-c g})
@ifinfo

@end ifinfo
Lets you re-initialize supercite's information key-value pairs from a
set of mail headers in the region between point and mark. This function
is especially useful for replying to digest messages where supercite
will initially set up its information for the digest originator, but you
want to cite each component article with the real message author.  Note
that unless an error during processing occurs, any old information is
lost.@refill

@findex sc-version
@findex version (sc-)
@kindex C-c C-v
@item @code{sc-version} (@kbd{C-c C-v})
@ifinfo

@end ifinfo
Shows the version of supercite you are using.  With the optional universal
argument, this command inserts the version information into the current
buffer (good for identifying bug
reports! -- @pxref{The Supercite Mailing List}).@refill
@end table
@node Miscellaneous Commands, , Information Commands, Post-yank Formatting Commands
@comment  node-name,  next,  previous,  up
@section Miscellaneous Commands
@table @asis
@findex sc-open-line
@findex open-line (sc-)
@kindex C-c C-o
@item @code{sc-open-line} (@kbd{C-c C-o})
@ifinfo

@end ifinfo
Similar to emacs' standard @code{open-line} commands, but inserts the
citation string in front of the new line.  As with @code{open-line},
an optional numeric argument inserts that many new lines.@refill

@vindex sc-fill-arg
@vindex fill-arg (sc-)
@findex sc-fill-paragraph-manually
@findex fill-paragraph-manually (sc-)
@kindex C-c C-q
@kindex C-c q
@item @code{sc-fill-paragraph-manually} (@kbd{C-c q} and @kbd{C-c C-q})
@ifinfo

@end ifinfo
Manually fills the current paragraph. Actually this is an interactive
version running the hook @code{sc-fill-paragraph-hook}, however it does
bind the global variable @code{sc-fill-arg} to the value of the optional
argument. What this implies of course, is that you can use any paragraph
filling package you want to actually do the filling of the cited
paragraph. If that package takes an argument, you can write a simple
wrapper function to pass @code{sc-fill-arg} as that argument.@refill

@findex sc-describe
@findex describe (sc-)
@kindex C-c ?
@item @code{sc-describe} (@kbd{C-c ?})
@ifinfo

@end ifinfo
This function has been obsoleted by the texinfo manual you are now
reading. It is still provided for compatibility, but it will eventually
go away.

@end table

@node Keymaps, Hints to Reader Authors, Post-yank Formatting Commands, Top  
@comment  node-name,  next,  previous,  up
@chapter Keymaps
@ifinfo

@end ifinfo
@cindex per-interface keymap
@vindex current-local-map
Since every reader can conceivably use a different buffer and/or
major-mode to reply in, supercite can't know ahead of time what the
state of the buffer is. So supercite needs to leach onto whatever buffer
the reply is being made in, modifying the keymap and the documentation
string for that buffer. A mechanism was developed to provide a
@dfn{per-interface} keymap, which installs itself into the reply
buffer's @code{current-local-map} based on the major-mode of the
buffer.@refill

@vindex sc-local-keymaps
@vindex local-keymaps (sc-)
The variable @code{sc-local-keymaps} contains an association list of the
form:

@example
((MAJOR-MODE [FUNCTION | MAJOR-MODE])+)
@end example

When it is time to modify the keymap of the current buffer, supercite
looks up that buffer's major-mode in this association list. If it
matches an entry, supercite looks at the value associated with the key.
If the value is a list, it is assumed that this list is a function which
will set the current local keymap as intended. If however, the value is
another major-mode symbol name, then this returned major mode is looked
up in @code{sc-local-keymaps}, and the resulting keymap-setting function
is evaluated. Only one level of indirection is allowed, but this does
let you save space when defining key bindings. If you have many modes
which have the same bindings, you only need define the keymap setting
function once, and then let all other modes refer to this mode's keymap.

Here is the default value for @code{sc-local-keymaps}:

@example
'((mail-mode
   (lambda ()
     (local-set-key "\C-c\C-r" 'sc-insert-reference)
     (local-set-key "\C-c\C-t" 'sc-cite)
     (local-set-key "\C-c\C-a" 'sc-recite)
     (local-set-key "\C-c\C-u" 'sc-uncite)
     (local-set-key "\C-c\C-i" 'sc-insert-citation)
     (local-set-key "\C-c\C-o" 'sc-open-line)
     (local-set-key "\C-c\C-q" 'sc-fill-paragraph-manually)
     (local-set-key "\C-cq"    'sc-fill-paragraph-manually)
     (local-set-key "\C-c\C-m" 'sc-modify-information)
     (local-set-key "\C-cf"    'sc-view-field)
     (local-set-key "\C-cg"    'sc-glom-headers)
     (local-set-key "\C-c\C-v" 'sc-version)
     (local-set-key "\C-c?"    'sc-describe)
   ))
 (mh-letter-mode
   (lambda ()
     (local-set-key "\C-c\C-r" 'sc-insert-reference)
     (local-set-key "\C-c\C-t" 'sc-cite)
     (local-set-key "\C-c\C-a" 'sc-recite)
     (local-set-key "\C-c\C-u" 'sc-uncite)
     (local-set-key "\C-ci"    'sc-insert-citation)
     (local-set-key "\C-c\C-o" 'sc-open-line)
     (local-set-key "\C-cq"    'sc-fill-paragraph-manually)
     (local-set-key "\C-c\C-m" 'sc-modify-information)
     (local-set-key "\C-cf"    'sc-view-field)
     (local-set-key "\C-cg"    'sc-glom-headers)
     (local-set-key "\C-c\C-v" 'sc-version)
     (local-set-key "\C-c?"    'sc-describe)
   ))
 (news-reply-mode mail-mode)
 (vm-mail-mode mail-mode)
 (e-reply-mode mail-mode)
 (n-reply-mode mail-mode)
 )
@end example

@vindex sc-default-keymap
@vindex default-keymap (sc-)
If the major-mode of the buffer is not found in the association list,
then the function in @code{sc-default-keymap} is evaluated. The default
value for @code{sc-default-keymap} is:

@example
'(lambda ()
   (local-set-key "\C-c\C-r" 'sc-insert-reference)
   (local-set-key "\C-c\C-t" 'sc-cite)
   (local-set-key "\C-c\C-a" 'sc-recite)
   (local-set-key "\C-c\C-u" 'sc-uncite)
   (local-set-key "\C-c\C-i" 'sc-insert-citation)
   (local-set-key "\C-c\C-o" 'sc-open-line)
   (local-set-key "\C-c\C-q" 'sc-fill-paragraph-manually)
   (local-set-key "\C-cq"    'sc-fill-paragraph-manually)
   (local-set-key "\C-c\C-m" 'sc-modify-information)
   (local-set-key "\C-cf"    'sc-view-field)
   (local-set-key "\C-cg"    'sc-glom-headers)
   (local-set-key "\C-c\C-v" 'sc-version)
   (local-set-key "\C-c?"    'sc-describe)
   )
@end example

@vindex sc-electric-mode-map
@vindex electric-mode-map (sc-)
The keymap for electric reference mode can also be user defined, but
since there is no need for a per-interface map, there is only a single
variable, @code{sc-electric-mode-map} which contains the keymap. If you
set this variable, you can override the default key bindings for
electric reference mode. @xref{Electric References} for a description
of the default key bindings for this mode.
@node Hints to Reader Authors, Thanks and History, Keymaps, Top    
@comment  node-name,  next,  previous,  up
@chapter Hints to Reader Authors
In June of 1989, some discussion was held between the various reader
authors, the supercite author, and other supercite users. These
discussions centered around the need for a standard interface between
these readers and supercite (or any future readers, or supercite-like
packages).  This interface was formally proposed by Martin Neitzel on
Fri, 23 Jun 89, in a mail message to the supercite mailing list:

@example
	Martin> Each news/mail-reader should provide a form of
	Martin> mail-yank-original that

	Martin> 1: inserts the original message incl. header into the
	Martin>    reply buffer; no indentation/prefixing is done, the header
	Martin>    tends to be a "full blown" version rather than to be
	Martin>    stripped down.

	Martin> 2: `point' is at the start of the header, `mark' at the
	Martin>    end of the message body.

	Martin> 3: (run-hooks 'mail-yank-hooks)

	Martin> [Supercite] should be run as such a hook and merely
	Martin> rewrite the message.  This way it isn't anymore
	Martin> [supercite]'s job to gather the original from obscure
	Martin> sources. [...]
@end example

This proposal was adopted, and thus supercite 2.3 conforms to this
interface, as does VM (versions 4.37 and beyond, including versions
5.xx), as well as MH-E 3.7 which is distributed with emacs 18.57.

If you are writing a new reader package, or updating an existing reader
package, you should make it conform to this interface so that your users
will be able to link supercite easily and seamlessly. To do this, when
setting up a reply or forward buffer, your reader should follow these
steps (outlined above and discussed in greater detail below):

@enumerate
@item 
Insert the original message, including the mail headers into the reply
buffer. At this point you should not modify the raw text in any way, and
you should place all the original headers into the body of the reply.
This means that many of the mail headers will be duplicated, one copy
above the @code{mail-header-separator} line and one copy below,
however there will probably be more headers below this line.@refill

@item 
Set ``point'' to the beginning of the line containing the first mail
header in the body of the reply. Set ``mark'' to the end of the message
text.  It is very important that the region be set around the text
supercite is to modify and that the mail headers are within this region.
Supercite will not look at or modify anything outside the region, and
anything within the region is fair game, so don't put anything that
@strong{must} remain unchanged inside the region.@refill

@item 
Run the hook @code{mail-yank-hooks}. You will probably want to provide
some kind of default citation functions in cases where the user does not
have supercite installed. By default, your reader should set
@code{mail-yank-hooks} to execute this default citation function. Users
who want to use supercite can then set @code{mail-yank-hooks} to
@code{sc-cite-original}.@refill
@end enumerate

If you do all this you will not need to provide overloading routines and
your reader will join the ranks of those subsystems who conform to this
interface ``out of the box.''
@node Thanks and History, The Supercite Mailing List, Hints to Reader Authors, Top
@comment  node-name,  next,  previous,  up
@chapter Thanks and History
The supercite package was derived from its predecessor superyank 1.11
which was inspired by various bits of code and ideas from Martin Neitzel
and Ashwin Ram. They were the folks who came up with the idea of
non-nested citations and implemented some rough code to provide this
style. Superyank and now supercite 2.3, have evolved to the point where
much of the attribution selection mechanism is automatic, and features
have been continuously added through the comments and suggestions of the
supercite mailing list participants.

Many of these folks have contributed their help in debugging, making
suggestions for enhancements, and supplying support code or bug fixes
for the previous versions of supercite. I would like to thank (in
alphabetical order):

@itemize @bullet
@item 
Mark D. Baushke
@item 
Chris Davis
@item 
Dan Jacobson
@item 
Kyle Jones
@item 
David Lawrence
@item 
Piet van Oostrum
@item 
Khalid Sattar
@item 
Kayvan Sylvan
@item 
Masanobu Umeda
@item 
Joe Wells
@end itemize

I apologize if I've left anybody out. All who have helped have been
greatly appreciated.

Also, thanks to David Eckelkamp, John Stoffel, and Walter Rowe for proof
reading the initial drafts of this manual.
@node The Supercite Mailing List, Concept Index, Thanks and History, Top
@comment  node-name,  next,  previous,  up
@chapter The Supercite Mailing List
@cindex supercite mailing list address
@cindex mailing list address
The author runs a simple mail expanding mailing list for discussion of
issues related to supercite. This includes enhancement requests, bug
reports, general help questions, etc.  To subscribe or unsubscribe to
the mailing list, send a request to the administrative address:

@example
Internet: supercite-request@@anthem.nlm.nih.gov
    UUCP: uunet!anthem.nlm.nih.gov!supercite-request
@end example

Please be sure to include the most reliable and shortest (preferably
internet) address back to you.  To post articles to the list, send your
message to this address (you do not need to be a member to post, but be
sure to indicate this in your article or replies may not be CC'd to
you):

@example
Internet: supercite@@anthem.nlm.nih.gov
    UUCP: uunet!anthem.nlm.nih.gov!supercite
@end example

If you are sending 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.  Without this
information, it will be difficult to get useful advice.

@node Concept Index, Command Index, The Supercite Mailing List, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index
@printindex cp

@node Command Index, Key Index, Concept Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Command Index
Since all supercite commands are prepended with the string
``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
its @var{command} name.
@iftex
@sp 2
@end iftex
@printindex fn
@node Key Index, Variable Index, Command Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Key Index
@printindex ky
@node Variable Index, , Key Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Variable Index
Since all supercite variables are prepended with the string
``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
its @var{variable} name.
@iftex
@sp 2
@end iftex
@printindex vr
@summarycontents
@contents
@bye