changeset 84193:0300b27abba2

Move to ../doc/emacs/, misc/

--- a/man/sc.texi	Thu Sep 06 04:39:54 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,2533 +0,0 @@
-\input texinfo  @comment -*-texinfo-*-
-@comment 3.48
-@comment %**start of header (This is for running Texinfo on a region.)
-@setfilename ../info/sc
-@settitle Supercite Version 3.1 User's Manual
-@iftex
-@finalout
-@end iftex
-
-@c @setchapternewpage odd		% For book style double sided manual.
-@comment %**end of header (This is for running Texinfo on a region.)
-
-@copying
-This document describes the Supercite Version 3.1 package for citing and
-attributing the replies for various GNU Emacs mail and news reading
-subsystems.
-
-Copyright @copyright{} 1993, 2001, 2002, 2003, 2004,
-2005, 2006, 2007 Free Software Foundation, Inc.
-
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software.  Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License.  If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
-@end quotation
-@end copying
-
-@c      @smallbook
-
-@dircategory Emacs
-@direntry
-* SC: (sc).		Supercite lets you cite parts of messages you're
-			  replying to, in flexible ways.
-@end direntry
-
-@titlepage
-@sp 6
-@center @titlefont{Supercite User's Manual}
-@sp 2
-@center @titlefont{Supercite Version 3.1}
-@sp 4
-@center Manual Revision: 3.48
-@center April 2007
-@sp 5
-@center Barry A@. Warsaw
-@center @t{bwarsaw@@cen.com}
-@center @t{@dots{}!uunet!cen.com!bwarsaw}
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@ifnottex
-@node Top, Introduction, (dir), (dir)
-@comment  node-name,  next,  previous,  up
-
-This document describes the Supercite Version 3.1 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::
-* Citations::
-* Getting Connected::
-* Replying and Yanking::
-* Selecting an Attribution::
-* Configuring the Citation Engine::
-* Post-yank Formatting Commands::
-* Information Keys and the Info Alist::
-* Reference Headers::
-* Hints to MUA Authors::
-* Version 3 Changes::
-* Thanks and History::
-* The Supercite Mailing List::
-
-* GNU Free Documentation License::
-* Concept Index::
-* Command Index::
-* Key Index::
-* Variable Index::
-@end menu
-@end ifnottex
-
-
-@node  Introduction, Usage Overview, Top, Top
-@comment  node-name,  next,  previous,  up
-@chapter Introduction
-@ifinfo
-
-@end ifinfo
-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
-(@dfn{MUAs}) and news user agents (@dfn{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 @samp{S},
-lowercase @samp{upercite}.  There are a few alternate spellings out there
-and I won't be terribly offended if you use them.  People often ask
-though@dots{}
-
-@ifinfo
-@menu
-* Usage Overview::
-* What Supercite Does Not Do::
-* What Supercite Does::
-@end menu
-@end ifinfo
-
-@cindex MUA
-@cindex NUA
-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:
-
-@table @asis
-@item Emacs versions:
-	GNU Emacs 18.57 through 18.59, all Emacs 19,
-	all current Lucid Emacs, and Epoch 4.@refill
-
-@item MUAs:
-	VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
-	beyond, PCMAIL.@refill
-
-@item NUAs:
-	RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
-
-@end table
-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.  @xref{Getting Connected}, for more details.@refill
-
-
-@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
-@comment  node-name,  next,  previous,  up
-@kindex r
-@kindex f
-@kindex C-c C-y
-@cindex yank
-@cindex cite, citing
-@cindex attribute, attributing
-@comment
-@section Usage Overview
-@ifinfo
-
-@end ifinfo
-Typical usage is as follows. You want to reply or followup to a message
-in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{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 @dfn{yank} the original
-message into the reply buffer, typically with a key stroke such as
-@kbd{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
-@dfn{attributes} this text to its author.  This is called @dfn{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.
-
-@node  What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
-@comment  node-name,  next,  previous,  up
-@section What Supercite Doesn't Do
-@ifinfo
-
-@end ifinfo
-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.
-@xref{Reply Buffer Initialization}.@refill
-
-@vindex mail-header-separator
-@comment
-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
-@code{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. @xref{Hints to MUA Authors}, for more
-details.@refill
-
-@node  What Supercite Does, Citations, What Supercite Does Not Do, Introduction
-@comment  node-name,  next,  previous,  up
-@findex sc-cite-original
-@section What Supercite Does
-@ifinfo
-
-@end ifinfo
-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
-@code{sc-cite-original} has been added.  When @code{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.  @xref{Hints to MUA
-Authors}.@refill
-
-@cindex info alist
-The first thing Supercite does, via @code{sc-cite-original}, is to parse
-through the original message's mail headers.  It saves this data in an
-@dfn{information association list}, or @dfn{info alist}.  The information
-in this list is used in a number of places throughout Supercite.
-@xref{Information Keys and the Info Alist}.@refill
-
-@cindex nuking mail headers
-@cindex reference header
-After the mail header info is extracted, the headers are optionally
-removed (@dfn{nuked}) from the reply.  Supercite then writes a
-@dfn{reference header} into the buffer.  This reference header is a
-string carrying details about the citation it is about to perform.
-
-@cindex modeline
-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 @samp{SC}.
-
-@cindex filladapt
-@cindex gin-mode
-@vindex fill-prefix
-@findex fill-paragraph
-@comment
-When the original message is cited by @code{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 @cite{filladapt} or @cite{gin-mode}.  These packages can recognize
-Supercited text and will fill them appropriately.  Emacs' built-in
-filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
-text and will not re-fill them properly because it cannot guess the
-@code{fill-prefix} being used.
-@xref{Post-yank Formatting Commands}, for details.@refill
-
-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.  @xref{Getting Connected},
-for more details.@refill
-
-@node  Citations, Citation Elements, What Supercite Does, Top
-@comment  node-name,  next,  previous,  up
-@cindex nested citations
-@cindex citation
-@comment
-@chapter Citations
-@ifinfo
-
-@end ifinfo
-A @dfn{citation} is the acknowledgement 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 citations} 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, the person composing the reply),
-but no reference is made as to the identity of the original author.
-This style should look familiar since its use on the net is widespread.
-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
-
-@ifinfo
-@menu
-* Citation Elements::
-* Recognizing Citations::
-@end menu
-@end ifinfo
-
-Note that multiple inclusions of the original messages result in a
-nesting of the @samp{@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 participated in the
-thread, and multiple nesting of @samp{@code{>}} characters can sometimes
-make the message very difficult for the eye to scan.
-
-@cindex non-nested citations
-In @dfn{non-nested citations}, 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 citations are 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-)
-Supercite supports both styles of citation, and the variable
-@code{sc-nested-citation-p} controls which style it will use when citing
-previously uncited text. When this variable is @code{nil} (the default),
-non-nested citations are used.  When non-@code{nil}, nested citations
-are used.
-
-
-@node  Citation Elements, Recognizing Citations, Citations, Citations
-@comment  node-name,  next,  previous,  up
-@cindex citation string
-@comment
-@section Citation Elements
-@ifinfo
-
-@end ifinfo
-@dfn{Citation strings} are composed of one or more elements. 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 four spaces.
-
-@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{Selecting an Attribution}, for more details.@refill
-
-@cindex citation delimiter
-@vindex sc-citation-delimiter
-@vindex citation-delimiter (sc-)
-@item
-The @dfn{citation delimiter}.  This string, contained in the variable
-@code{sc-citation-delimiter} visually separates the citation from the
-text of the line.  This variable has a default value of @code{">"} and
-for best results, the string should consist of only a single character.
-
-@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.
-@end enumerate
-
-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
-@code{@asis{"    Jane> "}}.
-This citation string will be inserted in front of
-every line in the original message that is not already cited.@refill
-
-Nested citations, being simpler than non-nested citations, are composed
-of the same elements, sans the attribution string.  Supercite is smart
-enough to not put additional spaces between citation delimiters for
-multi-level nested citations.
-
-@node  Recognizing Citations, Getting Connected, Citation Elements, Citations
-@comment  node-name,  next,  previous,  up
-@section Recognizing Citations
-@ifinfo
-
-@end ifinfo
-Supercite also recognizes citations in the original article, and can
-transform these already cited lines in a number of ways. This is how
-Supercite suppresses the multiple citing of non-nested citations.
-Recognition of cited lines is controlled by variables analogous to those
-that make up the citation string as mentioned previously.
-
-@vindex sc-citation-leader-regexp
-@vindex citation-leader-regexp (sc-)
-@vindex sc-citation-delimiter-regexp
-@vindex citation-delimiter-regexp (sc-)
-@vindex sc-citation-separator-regexp
-@vindex citation-separator-regexp (sc-)
-@vindex sc-citation-root-regexp
-@vindex citation-root-regexp (sc-)
-@vindex sc-citation-nonnested-root-regexp
-@vindex citation-nonnested-root-regexp (sc-)
-
-The variable @code{sc-citation-leader-regexp} describes how citation
-leaders can look, by default it matches any number of spaces or tabs.
-Note that since the lisp function @code{looking-at} is used to do the
-matching, if you change this variable it need not start with a leading
-@code{"^"}.
-
-Similarly, the variables @code{sc-citation-delimiter-regexp} and
-@code{sc-citation-separator-regexp} respectively describe how citation
-delimiters and separators can look.  They follow the same rule as
-@code{sc-citation-leader-regexp} above.
-
-When Supercite composes a citation string, it provides the attribution
-automatically.  The analogous variable which handles recognition of the
-attribution part of citation strings is @code{sc-citation-root-regexp}.
-This variable describes the attribution root for both nested and
-non-nested citations.  By default it can match zero-to-many alphanumeric
-characters (also ``.'', ``-'', and ``_'').  But in some situations,
-Supercite has to determine whether it is looking at a nested or
-non-nested citation.  Thus the variable
-@code{sc-citation-nonnested-root-regexp} is used to describe only
-non-nested citation roots.  It is important to remember that if you
-change @code{sc-citation-root-regexp} you should always also change
-@code{sc-citation-nonnested-root-regexp}.@refill
-
-@node  Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
-@comment  node-name,  next,  previous,  up
-@cindex information keys
-@cindex Info Alist
-@cindex information extracted from mail fields
-@findex sc-mail-field
-@findex mail-field (sc-)
-@comment
-@chapter Information Keys and the Info Alist
-@ifinfo
-
-@end ifinfo
-@dfn{Mail header information keys} are nuggets of information that
-Supercite extracts from the various mail headers of the original
-message, placed in the reply buffer by the MUA.  Information is kept in
-the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
-various places within Supercite, such as in header rewrite functions and
-attribution selection.  Other bits of data, composed and created by
-Supercite, are also kept as key-value pairs in this alist. In the case
-of mail fields, the key is the name of the field, omitting the trailing
-colon.  Info keys are always case insensitive (as are mail headers), and
-the value for a corresponding key can be retrieved from the alist with
-the @code{sc-mail-field} function.  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
-@vindex mumble (sc-)
-@noindent
-then, the following lisp constructs return:
-
-@example
-(sc-mail-field "date")
-==> "08 April 1991, 17:32:09 EST"
-
-(sc-mail-field "subject")
-==> "Better get out your asbestos suit"
-@end example
-
-Since the argument to @code{sc-mail-field} can be any string, it is
-possible that the mail field will not be present on the info alist
-(possibly because the mail header was not present in the original
-message). In this case, @code{sc-mail-field} will return the value of
-the variable @code{sc-mumble}.
-
-Supercite always places all mail fields found in the yanked original
-article into the info alist.  If possible, Supercite will also places
-the following keys into the info alist:
-
-@table @code
-@cindex sc-attribution info field
-@cindex attribution info field (sc-)
-@item "sc-attribution"
-the selected attribution string.
-
-@cindex sc-citation info field
-@cindex citation info field (sc-)
-@item "sc-citation"
-the non-nested citation string.
-
-@cindex sc-from-address info field
-@cindex from-address info field (sc-)
-@item "sc-from-address"
-email address extracted from the @samp{From:@:} field.
-
-@cindex sc-reply-address info field
-@cindex reply-address info field (sc-)
-@item "sc-reply-address"
-email address extracted from the @samp{Reply-To:@:} field.
-
-@cindex sc-sender-address info field
-@cindex sender-address info field (sc-)
-@item "sc-sender-address"
-email address extracted from the @samp{Sender:@:} field.
-
-@cindex sc-emailname info field
-@cindex emailname info field (sc-)
-@item "sc-emailname"
-email terminus extracted from the @samp{From:@:} field.
-
-@cindex sc-initials info field
-@cindex initials info field (sc-)
-@item "sc-initials"
-the author's initials.
-
-@cindex sc-author info field
-@cindex author info field (sc-)
-@item "sc-author"
-the author's full name.
-
-@cindex sc-firstname info field
-@cindex firstname info field (sc-)
-@item "sc-firstname"
-the author's first name.
-
-@cindex sc-lastname info field
-@cindex lastname info field (sc-)
-@item "sc-lastname"
-the author's last name.
-
-@cindex sc-middlename-1 info field
-@cindex middlename-1 info field (sc-)
-@item "sc-middlename-1"
-the author's first middle name.
-@end table
-
-If the author's name has more than one middle name, they will appear as
-info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
-@dots{}).  @xref{Selecting an Attribution}.@refill
-
-@node  Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
-@comment  node-name,  next,  previous,  up
-@cindex reference headers
-@chapter Reference Headers
-@ifinfo
-
-@end ifinfo
-Supercite will insert an informative @dfn{reference header} at the
-beginning of the cited body of text, which display more detail about the
-original article and provides the mapping between the attribution and
-the original author in non-nested citations.  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 any
-information contained in the info alist can be inserted into a reference
-header.
-
-@ifinfo
-@menu
-* The Built-in Header Rewrite Functions::
-* Electric References::
-@end menu
-@end ifinfo
-
-@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 you can write your own custom header rewrite functions
-(perhaps using the built-in ones as examples). The variable
-@code{sc-rewrite-header-list} contains the list of such header rewrite
-functions.  This list is consulted both when inserting the initial
-reference header, and when displaying @dfn{electric references}.
-@xref{Electric References}.
-
-@vindex sc-preferred-header-style
-@vindex preferred-header-style (sc-)
-When Supercite is initially run on a reply buffer (via
-@code{sc-cite-original}), it will automatically call one of these
-functions. The one it uses is defined in the variable
-@code{sc-preferred-header-style}.  The value of this variable is an
-integer which is an index into the @code{sc-rewrite-header-list},
-beginning at zero.
-
-@node  The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
-@comment  node-name,  next,  previous,  up
-@cindex header rewrite functions, built-in
-@comment
-@section The Built-in Header Rewrite Functions
-@ifinfo
-
-@end ifinfo
-Below are examples of the various built-in header rewrite functions.
-Please note the following:@: first, the text which appears in the
-examples below as @var{infokey} indicates that the corresponding value
-of the info key from the info alist will be inserted there.
-(@pxref{Information Keys and the Info Alist}).  For example, in @code{sc-header-on-said}
-below, @var{date} and @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}.  This variable is used in all
-built-in header rewrite functions, and you can customize its value to
-change the tag string globally.
-
-Finally, the references headers actually written may omit certain parts
-of the header if the info key associated with @var{infokey} is not
-present in the info alist.  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 (but this usually signals a serious
-problem either in your MUA or in Supercite's installation).
-
-@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-)
-@code{>>>>> On @var{date}, @var{from} said:}
-
-@item sc-header-inarticle-writes
-@findex sc-header-inarticle-writes
-@findex header-inarticle-writes (sc-)
-@code{>>>>> In article @var{message-id}, @var{from} writes:}
-
-@item sc-header-regarding-adds
-@findex sc-header-regarding-adds
-@findex header-regarding-adds (sc-)
-@code{>>>>> Regarding @var{subject}; @var{from} adds:}
-
-@item sc-header-attributed-writes
-@findex sc-header-attributed-writes
-@findex header-attributed-writes (sc-)
-@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:}
-
-@item sc-header-author-writes
-@findex sc-header-author-writes
-@findex header-author-writes (sc-)
-@code{>>>>> @var{sc-author} writes:}
-
-@item sc-header-verbose
-@findex sc-header-verbose
-@findex header-verbose (sc-)
-@code{>>>>> On @var{date},}@*
-@code{>>>>> @var{sc-author}}@*
-@code{>>>>> from the organization of @var{organization}}@*
-@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@*
-@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@*
-@code{>>>>> had this to say in article @var{message-id}}@*
-@code{>>>>> in newsgroups @var{newsgroups}}@*
-@code{>>>>> concerning the subject of @var{subject}}@*
-@code{>>>>> see @var{references} for more details}
-@end table
-
-@node  Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
-@comment  node-name,  next,  previous,  up
-@cindex electric references
-@section Electric References
-@ifinfo
-
-@end ifinfo
-By default, when Supercite cites the original message for the first
-time, it 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-)
-If the variable @code{sc-electric-references-p} is non-@code{nil},
-Supercite will bring up an electric reference mode buffer and place you
-into a recursive edit.  The electric reference buffer is read-only, so
-you cannot directly modify the reference text until you exit electric
-references and insert the text into the reply buffer.  But you can cycle
-through all the reference header rewrite functions in your
-@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 and function name will appear in
-the echo area.
-
-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 electric reference 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.@refill
-
-@item @code{sc-eref-prev} (@kbd{p})
-@findex sc-eref-prev
-@findex eref-prev (sc-)
-@kindex p
-Displays the previous reference header in the electric reference 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.@refill
-
-@item @code{sc-eref-goto} (@kbd{g})
-@findex sc-eref-goto
-@findex eref-goto (sc-)
-@kindex g
-Goes to a specified reference header.  The index (into the
-@code{sc-rewrite-header-list}) can be specified as a numeric argument to
-the command.  Otherwise, Supercite will query you for the index in the
-minibuffer.@refill
-
-@item @code{sc-eref-jump} (@kbd{j})
-@findex sc-eref-jump
-@findex eref-jump (sc-)
-@kindex j
-Display the preferred reference header, i.e., the one indexed by the current
-value of @code{sc-preferred-header-style}.
-
-@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.@refill
-
-@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c})
-@kindex RET
-@kindex C-j
-@kindex q
-@findex sc-eref-exit
-@findex eref-exit (sc-)
-Exit from electric reference mode and insert the current header into the
-reply buffer.@refill
-
-@item @code{sc-eref-abort} (@kbd{q}, @kbd{x})
-@findex sc-eref-abort
-@findex eref-abort (sc-)
-@kindex x
-Exit from electric reference mode without inserting the current 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, Emacs 19 MUAs, Recognizing Citations, Top
-@comment  node-name,  next,  previous,  up
-@cindex citation interface specification
-@chapter Getting Connected
-@ifinfo
-
-@end ifinfo
-Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
-original message into the reply buffer.  In reality, the citation of the
-original message is performed via a call through a configurable hook
-variable.  The name of this variable has been agreed to in advance as
-part of the @dfn{citation interface specification}.  By default this
-hook variable has a @code{nil} value, which the MUA recognizes to mean,
-``use your default citation function.''  When you add Supercite's
-citation function to the hook, thereby giving the variable a
-non-@code{nil} value, it tells the MUA to run the hook via
-@code{run-hooks} instead of using the default citation.@refill
-
-@ifinfo
-@menu
-* Emacs 19 MUAs::
-* Emacs 18 MUAs::
-* MH-E with any Emacsen::
-* VM with any Emacsen::
-* GNEWS with any Emacsen::
-* Overloading for Non-conforming MUAs::
-@end menu
-@end ifinfo
-
-Early in Supercite's development, the Supercite author, a few MUA
-authors, and some early Supercite users got together and agreed upon a
-standard interface between MUAs and citation packages (of which
-Supercite is currently the only known add-on @t{:-)}.  With the recent
-release of the Free Software Foundation's GNU Emacs 19, the interface
-has undergone some modification and it is possible that not all MUAs
-support the new interface yet.  Some support only the old interface and
-some do not support the interface at all.  Still, it is possible for all
-known MUAs to use Supercite, and the following sections will outline the
-procedures you need to follow.
-
-To learn exactly how to connect Supercite to the software systems you
-are using, read the appropriate following sections.  For details on the
-interface specifications, or if you are writing or maintaining an MUA,
-@pxref{Hints to MUA Authors}.
-
-@cindex autoload
-@cindex .emacs file
-@findex sc-cite-original
-@findex cite-original (sc-)
-@findex sc-submit-bug-report
-@findex submit-bug-report (sc-)
-The first thing that everyone should do, regardless of the MUA you are
-using is to set up Emacs so it will load Supercite at the appropriate
-time.  You can either dump Supercite into your Emacs binary (ask your
-local Emacs guru how to do this if you don't know), or you can set up an
-@dfn{autoload} for Supercite.  To do the latter, put the following in
-your @file{.emacs} file:
-
-@example
-(autoload 'sc-cite-original     "supercite" "Supercite 3.1" t)
-(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
-@end example
-
-@cindex point
-@cindex mark
-The function @code{sc-cite-original} is the top-level Supercite function
-designed to be run from the citation hook.  It expects
-@samp{point} and @samp{mark} to be set around the region to cite, and it
-expects the original article's mail headers to be present within this
-region.  Note that Supercite @emph{never} touches any text outside this
-region.  Note further that for Emacs 19, the region need not be active
-for @code{sc-cite-original} to do its job.
-@xref{Hints to MUA Authors}.@refill
-
-The other step in the getting connected process is to make sure your
-MUA calls @code{sc-cite-original} at the right time.  As mentioned
-above, some MUAs handle this differently.  Read the sections that follow
-pertaining to the MUAs you are using.
-
-@vindex sc-load-hook
-@vindex load-hook (sc-)
-@vindex sc-pre-hook
-@vindex pre-hook (sc-)
-One final note.  After Supercite is loaded into your Emacs session, it
-runs the hook @code{sc-load-hook}.  You can put any customizations into
-this hook since it is only run once.  This will not work, however, if
-your Emacs maintainer has put Supercite into your dumped Emacs' image.
-In that case, you can use the @code{sc-pre-hook} variable, but this will
-get executed every time @code{sc-cite-original} is called.  @xref{Reply
-Buffer Initialization}.@refill
-
-@node   Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected
-@comment  node-name,  next,  previous,  up
-@vindex mail-citation-hook
-@cindex .emacs file
-@section GNUS, RMAIL, or RNEWS with any Emacs 19
-@ifinfo
-
-@end ifinfo
-These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
-built-in yanking facility, which provides the citing hook variable
-@code{mail-citation-hook}.  By default, this hook's value is @code{nil},
-but by adding the following to your @file{.emacs} file, you can tell
-these MUAs to use Supercite to perform the citing of the original
-message:
-
-@example
-(add-hook 'mail-citation-hook 'sc-cite-original)
-@end example
-
-GNUS users may also want to add the following bit of lisp as well.  This
-prevents GNUS from inserting its default attribution header.  Otherwise,
-both GNUS and Supercite will insert an attribution header:
-
-@example
-(setq news-reply-header-hook nil)
-@end example
-
-@node   Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
-@comment  node-name,  next,  previous,  up
-@vindex mail-citation-hook
-@cindex .emacs file
-@cindex overloading
-@cindex sendmail.el file
-@section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
-@ifinfo
-
-@end ifinfo
-These MUAs use Emacs' built-in yanking and citing routines, contained in
-the @file{sendmail.el} file.  @file{sendmail.el} for Emacs 18, and its
-derivative Epoch 4, do not know anything about the citation interface
-required by Supercite.  To connect Supercite to any of these MUAs under
-Emacs 18 or Epoch 4, you should first
-@pxref{Overloading for Non-conforming MUAs}.  Then follow the directions
-for using these MUAs under Emacs 19.
-@xref{Emacs 19 MUAs}.@refill
-
-@cindex add-hook substitute
-@cindex setq as a substitute for add-hook
-@findex setq
-@findex add-hook
-@cindex sc-unsupp.el file
-Note that those instructions will tell you to use the function
-@code{add-hook}. This function is new with Emacs 19 and you will not
-have it by default if you are running Emacs 18 or Epoch 4.  You can
-either substitute the appropriate call to @code{setq}, or you can use
-the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
-file of unsupported Supercite hacks and ideas.  Or you can upgrade to
-some Emacs 19 variant!  @t{:-)}@refill
-
-To use @code{setq} instead of @code{add-hook}, you would, for example,
-change this:
-
-@example
-(add-hook 'mail-citation-hook 'sc-cite-original)
-@end example
-
-to:
-
-@example
-(setq mail-citation-hook 'sc-cite-original)
-@end example
-
-Note the lack of a single quote on the first argument to @code{setq}.
-
-@node  MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
-@comment  node-name,  next,  previous,  up
-@cindex .emacs file
-@vindex mh-yank-hooks
-@findex add-hook
-@cindex mail-citation-hook
-@section MH-E with any Emacsen
-@ifinfo
-
-@end ifinfo
-MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
-by other MUAs.  At the time of this writing, MH-E 4.0 has not been
-released, but if you have it, put this in your @file{.emacs} file to
-connect Supercite and MH-E 4.x:
-
-@example
-(add-hook 'mail-citation-hook 'sc-cite-original)
-@end example
-
-Note that if you are using Emacs 18 or Epoch 4, you will not have the
-@code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
-proceed without @code{add-hook}.
-
-MH-E version 3.x uses a slightly different interface than other MUAs.
-MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
-like a hook, and doing an @code{add-hook} will not work.
-
-To connect Supercite to MH-E 3.x, you should instead add the following
-to your @code{.emacs} file:
-
-@example
-(add-hook 'mh-yank-hooks 'sc-cite-original)
-@end example
-
-@vindex mh-yank-from-start-of-msg
-You also need to make sure that MH-E includes all the original mail
-headers in the yanked message.  The variable that controls this is
-@code{mh-yank-from-start-of-msg}.  By default, this variable has the
-value @code{t}, which tells MH-E to include all the mail headers when
-yanking the original message.  Before you switched to using Supercite,
-you may have set this variable to other values so as not to include the
-mail headers in the yanked message.  Since Supercite requires these
-headers (and cleans them out for you), you need to make sure the value
-is @code{t}.  This lisp, in your @file{.emacs} file will do the trick:
-
-@example
-(setq mh-yank-from-start-of-msg t)
-@end example
-
-Note that versions of MH-E before 3.7 did not provide the
-@code{mh-yank-hooks} variable.  Your only option is to upgrade to MH-E
-version 3.7 or later.
-
-@node  VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
-@comment  node-name,  next,  previous,  up
-@cindex .emacs file
-@vindex mail-citation-hook
-@vindex mail-yank-hooks
-@section VM with any Emacsen
-@ifinfo
-
-@end ifinfo
-Since release 4.40, VM has supported the citation interface required by
-Supercite.  But since the interface has changed recently the details of
-getting connected differ with the version of VM you are using.
-
-If you are running any release of VM after 4.40, you can add the
-following to your @file{.emacs} to connect Supercite with VM:
-
-@example
-(add-hook 'mail-yank-hooks 'sc-cite-original)
-@end example
-
-Note that if you are using Emacs 18 or Epoch 4, you will not have the
-@code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
-proceed without @code{add-hook}.
-
-Since version 5.34, VM has supported the newer @code{mail-citation-hook}
-interface, but @code{mail-yank-hooks} is still being supported for
-backward compatibility.  If you are running a newer version of VM and
-you want to maintain consistency with other MUAs, use this bit of code
-instead:
-
-@example
-(add-hook 'mail-citation-hook 'sc-cite-original)
-@end example
-
-@node  GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
-@comment  node-name,  next,  previous,  up@cindex .emacs file
-@vindex news-reply-mode-hook
-@findex sc-perform-overloads
-@findex perform-overloads (sc-)
-@vindex gnews-ready-hook
-@section GNEWS with any Emacsen
-@ifinfo
-
-@end ifinfo
-As far as I know, no version of GNEWS supports the citation interface
-required by Supercite.  To connect Supercite with GNEWS, please first
-@pxref{Overloading for Non-conforming MUAs}.
-
-After you have followed the directions in that section.  You should add
-the following lisp code to your @file{.emacs} file:
-
-@example
-(add-hook 'mail-citation-hook 'sc-cite-original)
-@end example
-
-Note that if you are using Emacs 18 or Epoch 4, you will not have the
-@code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
-proceed without @code{add-hook}.
-
-@node  Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
-@comment  node-name,  next,  previous,  up
-@cindex overloading
-@cindex sc-oloads.el
-@vindex mail-citation-hook
-@findex sc-perform-overloads
-@cindex .emacs file
-@section Overloading for Non-conforming MUAs
-@ifinfo
-
-@end ifinfo
-As mentioned elsewhere, some MUAs do not provide the necessary hooks to
-connect with Supercite.  Supercite version 3.1 provides an unsupported
-mechanism, called @dfn{overloading} which redefines certain key
-functions in the MUA, so that it will call the @code{mail-citation-hook}
-variable instead of the MUA's default hard-coded citing routines.  Since
-most newer versions of the known MUAs support the
-@code{mail-citation-hook} variable, it is recommended that you upgrade
-if at all possible.  But if you can't upgrade, at least you're not out
-of luck!  Once you set up overloading properly, you should follow the
-directions for connecting Supercite to the Emacs 19 MUAs.
-@xref{Emacs 19 MUAs}.@refill
-
-@cindex Hyperbole
-@vindex hyperb:version
-Users of Bob Weiner's Hyperbole package take note.  Hyperbole provides
-the necessary overloads (and a whole lot more!) and you can potentially
-clobber it if you were to load Supercite's overloading after
-Hyperbole's.  For this reason, Supercite will @emph{not} perform any
-overloading if it finds the variable @code{hyperb:version} is
-@code{boundp} (i.e. it exists because Hyperbole has been loaded into
-your Emacs session).  If this is the case, Supercite will display a
-warning message in the minibuffer.  You should consult the Hyperbole
-manual for further details.
-
-Overloading involves the re-definition of the citing function with the
-new, @code{mail-citation-hook} savvy version.  The function in
-@file{sc-oloads.el} that does this is @code{sc-perform-overloads}.  This
-function is smart enough to only overload the MUA functions when it is
-absolutely necessary, based on the version numbers it can figure out.
-Also, @code{sc-perform-overloads} will only install the new functions
-once.  It is also smart enough to do nothing if the MUA is not yet
-loaded.@refill
-
-The tricky part is finding the right time and place to perform the
-overloading.  It must be done after the MUA has been loaded into your
-Emacs session, but before the first time you try to yank in a message.
-Fortunately, this has been figured out for you.
-
-If you must overload, you should put the following lisp code in your
-@file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
-loaded at the right time:
-
-@example
-(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
-@end example
-
-Then you must make sure that the function @code{sc-perform-overloads}
-gets run at the right time.  For GNUS, put this in your @file{.emacs}
-file:
-
-@example
-(setq news-reply-mode-hook 'sc-perform-overloads)
-(setq mail-setup-hook 'sc-perform-overloads)
-@end example
-
-If you are using RNEWS, put this in your @file{.emacs} file:
-
-@vindex news-reply-mode-hook
-@example
-(setq news-reply-mode-hook 'sc-perform-overloads)
-@end example
-
-If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
-
-@example
-(setq mail-setup-hook 'sc-perform-overloads)
-@end example
-
-If you are using GNEWS, put this in your @file{.emacs} file:
-
-@example
-(setq news-reply-mode-hook 'sc-perform-overloads)
-(setq gnews-ready-hook 'sc-perform-overloads)
-@end example
-
-Now go back and follow the directions for getting the Emacs 19 MUAs
-connected to Supercite.  Be sure to @pxref{Emacs 18 MUAs} on substitutes
-for Emacs 19's @code{add-hook} function.@refill
-
-@node  Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
-@comment  node-name,  next,  previous,  up
-@chapter Replying and Yanking
-@ifinfo
-
-This chapter explains what happens when you reply and yank an original
-message from an MUA.
-
-@menu
-* Reply Buffer Initialization::
-* 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
-@findex sc-cite-original
-@findex cite-original (sc-)
-@comment
-@section Reply Buffer Initialization
-@ifinfo
-
-@end ifinfo
-Executing @code{sc-cite-original} performs the following steps as it
-initializes the reply buffer:
-
-@enumerate
-@item
-@vindex sc-pre-hook
-@vindex pre-hook (sc-)
-@emph{Runs @code{sc-pre-hook}.}
-This hook variable is run before @code{sc-cite-original} does any other
-work.  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{Inserts Supercite's keymap.}
-@vindex sc-mode-map-prefix
-@vindex mode-map-prefix (sc-)
-@kindex C-c C-p
-@cindex keymap prefix
-Supercite provides a number of commands for performing post-yank
-modifications to the reply buffer.  These commands are installed on
-Supercite's top-level keymap.  Since Supercite has to interface with a
-wide variety of MUAs, it does not install all of its commands directly
-into the reply buffer's keymap.  Instead, it puts its commands on a
-keymap prefix, then installs this prefix onto the buffer's keymap.  What
-this means is that you typically have to type more characters to invoke
-a Supercite command, but Supercite's key bindings can be made much more
-consistent across MUAs.
-
-You can control what key Supercite uses as its keymap prefix by changing
-the variable @code{sc-mode-map-prefix}.  By default, this variable is
-set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the
-best default due to the scarcity of available key bindings in many MUAs.
-
-@item
-@emph{Turns on Supercite minor mode.}
-@cindex modeline
-The modeline of the reply buffer should indicate that Supercite is
-active in that buffer by displaying the string @samp{SC}.
-
-@item
-@emph{Sets the ``Undo Boundary.''}
-@cindex undo boundary
-Supercite sets an undo boundary before it begins to modify the original
-yanked text.  This allows you to easily undo Supercite's changes to
-affect alternative citing styles.
-
-@item
-@emph{Processes the mail headers.}
-@vindex sc-confirm-always-p
-@vindex confirm-always-p (sc-)
-@vindex sc-mail-warn-if-non-rfc822-p
-@vindex mail-warn-if-non-rfc822-p (sc-)
-All previously retrieved info key-value pairs are deleted from the info
-alist, then the mail headers in the body of the yanked message are
-scanned. Info key-value pairs are created for each header found. Also,
-such useful information as the author's name and email address are
-extracted.  If the variable @code{sc-mail-warn-if-non-rfc822-p} is
-non-@code{nil}, then Supercite will warn you if it finds a mail header
-that does not conform to RFC822.  This is rare and indicates a problem
-either with your MUA or the original author's MUA, or some MTA (mail
-transport agent) along the way.
-
-@vindex sc-nuke-mail-headers
-@vindex sc-nuke-mail-header-list
-@vindex nuke-mail-headers (sc-)
-@vindex nuke-mail-header-list (sc-)
-Once the info keys have been extracted from the mail headers, the
-headers are nuked from the reply buffer.  You can control exactly which
-headers are removed or kept, but by default, all headers are removed.
-
-There are two variables which control mail header nuking.  The variable
-@code{sc-nuke-mail-headers} controls the overall behavior of the header
-nuking routines.  By setting this variable to @code{'all}, you
-automatically nuke all mail headers.  Likewise, setting this variable to
-@code{'none} inhibits nuking of any mail headers.  In between these
-extremes, you can tell Supercite to nuke only a specified list of mail
-headers by setting this variable to @code{'specified}, or to keep only a
-specified list of headers by setting it to @code{'keep}.
-
-If @code{sc-nuke-mail-headers} is set to @code{'specified} or
-@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is
-consulted for the list of headers to nuke or keep.  This variable
-contains a list of regular expressions.  If the mail header line matches
-a regular expression in this list, the header will be nuked or kept.
-The line is matched against the regexp using @code{looking-at} rooted at
-the beginning of the line.
-
-@vindex sc-blank-lines-after-headers
-@vindex blank-lines-after-headers (sc-)
-If the variable @code{sc-blank-lines-after-headers} is non-@code{nil},
-it contains the number of blank lines remaining in the buffer after mail
-headers are nuked.  By default, only one blank line is left in the buffer.
-
-@item
-@emph{Selects the attribution and citation strings.}
-Once the mail headers have been processed, Supercite selects a
-attribution string and a citation string which it will use to cite the
-original message.  @xref{Selecting an Attribution}, for details.
-
-@item
-@emph{Cites the message body.}
-@vindex sc-cite-region-limit
-@vindex cite-region-limit (sc-)b
-After the selection of the attribution and citation strings, Supercite
-cites the original message by inserting the citation string prefix in
-front of every uncited line.  You may not want Supercite to
-automatically cite very long messages however.  For example, some email
-could contain a smaller header section followed by a huge uuencoded
-message.  It wouldn't make sense to cite the uuencoded message part when
-responding to the original author's short preface.  For this reason,
-Supercite provides a variable which limits the automatic citation of
-long messages to a certain maximum number of lines.  The variable is
-called @code{sc-cite-region-limit}.  If this variable contains an
-integer, messages with more lines that this will not be cited at all,
-and a warning message will be displayed.  Supercite has performed
-everything necessary, though, for you to manually cite only the small
-portion of the original message that you want to use.
-
-If @code{sc-cite-region-limit} contains a non-@code{nil} value, the
-original message will always be cited, regardless of its size.  If the
-variable contains the value @code{nil}, the region will never be cited
-automatically.  Use this if you always want to be able to edit and cite
-the message manually.
-
-@vindex sc-cite-blank-lines-p
-@vindex cite-blank-lines-p (sc-)
-The variable @code{sc-cite-blank-lines-p} controls whether blank lines
-in the original message should be cited or not.  If this variable is
-non-@code{nil}, blank lines will be cited just like non-blank lines.
-Otherwise, blank lines will be treated as paragraph separators.
-
-Citing of the original message is highly configurable. Supercite's
-default setup does a pretty good job of citing many common forms of
-previously cited messages.  But there are as many citation styles out
-there as people on the net, or just about!  It would be impossible for
-Supercite to anticipate every style in existence, and you probably
-wouldn't encounter them all anyway.  But you can configure Supercite to
-recognize those styles you see often.
-@xref{Configuring the Citation Engine}, for details.@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, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
-@comment  node-name,  next,  previous,  up
-@cindex filling paragraphs
-@vindex sc-auto-fill-region-p
-@vindex auto-fill-region-p (sc-)
-@cindex filladapt
-@cindex gin-mode
-@findex sc-setup-filladapt
-@findex setup-filladapt (sc-)
-@vindex sc-load-hook
-@vindex load-hook (sc-)
-@section Filling Cited Text
-@ifinfo
-
-@end ifinfo
-Supercite will automatically fill newly cited text from the original
-message unless the variable @code{sc-auto-fill-region-p} has a
-@code{nil} value.  Supercite will also re-fill paragraphs when you
-manually cite or re-cite text.
-
-However, during normal editing, Supercite itself cannot be used to fill
-paragraphs.  This is a change from version 2.  There are other add-on
-lisp packages which do filling much better than Supercite ever did.  The
-two best known are @dfn{filladapt} and @dfn{gin-mode}.  Both work well
-with Supercite and both are available at the normal Emacs Lisp archive
-sites.  @dfn{gin-mode} works pretty well out of the box, but if you use
-@dfn{filladapt}, you may want to run the function
-@code{sc-setup-filladapt} from your @code{sc-load-hook}.  This simply
-makes @dfn{filladapt} a little more Supercite savvy than its default
-setup.
-
-@vindex sc-fixup-whitespace-p
-@vindex fixup-whitespace-p (sc-)
-Also, Supercite will collapse leading whitespace between the citation
-string and the text on a line when the variable
-@code{sc-fixup-whitespace-p} is non-@code{nil}.  The default value for
-this variable is @code{nil}.@refill
-
-@vindex fill-prefix
-Its important to understand that Supercite's automatic filling (during
-the initial citation of the reply) is very fragile.  That is because
-figuring out the @code{fill-prefix} for a particular paragraph is a
-really hard thing to do automatically.  This is especially the case when
-the original message contains code or some other text where leading
-whitespace is important to preserve.  For this reason, many Supercite
-users typically run with @code{sc-auto-fill-region-p} (and possibly also
-@code{sc-fixup-whitespace-p}) set to @code{nil}.  They then manually
-fill each cited paragraph in the reply buffer.
-
-I usually run with both these variables containing their default values.
-When Supercite's automatic filling breaks on a particular message, I
-will use Emacs' undo feature to undo back before the citation was
-applied to the original message.  Then I'll toggle the variables and
-manually cite those paragraphs that I don't want to fill or collapse
-whitespace on.  @xref{Variable Toggling Shortcuts}.@refill
-
-@kindex C-c C-p C-p
-If you find that Supercite's automatic filling is just too fragile for
-your tastes, you might consider one of these alternate approaches.
-Also, to make life easier, a shortcut function to toggle the state of
-both of these variables is provided on the key binding
-@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix};
-@pxref{Post-yank Formatting Commands}).@refill
-
-You will noticed that the minor mode string will
-show the state of these variables as qualifier characters. When both
-variables are @code{nil}, the Supercite minor mode string will display
-@samp{SC}.  When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
-string will display @samp{SC:f}, and when just
-@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display
-@samp{SC:w}.  When both variables are non-@code{nil}, the string will
-display @samp{SC:fw}.  Note that the qualifiers chosen are mnemonics for
-the default bindings of the toggling function for each respective
-variable.
-@xref{Variable Toggling Shortcuts}.@refill
-
-Why are these variables not set to @code{nil} by default?  It is because
-many users won't manually fill paragraphs that are Supercited, and there
-have been widespread complaints on the net about mail and news messages
-containing lines greater than about 72 characters.  So the default is to
-fill cited text.
-
-@node  Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
-@comment  node-name,  next,  previous,  up
-@cindex attribution list
-@vindex sc-preferred-attribution-list
-@vindex preferred-attribution-list (sc-)
-@comment
-@chapter Selecting an Attribution
-@ifinfo
-
-@end ifinfo
-As you know, the attribution string is the part of the author's name
-that will be used to composed a non-nested citation string. 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 association list} or @dfn{attribution alist}. This is
-analogous, but different than, the info alist previously mentioned. Each
-element in the attribution alist is a key-value pair containing such
-information as the author's first name, middle names, and last name, the
-author's initials, and the author's email terminus.
-
-@ifinfo
-@menu
-* Attribution Preferences::
-* Anonymous Attributions::
-* Author Names::
-@end menu
-@end ifinfo
-
-@node  Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
-@comment  node-name,  next,  previous,  up
-@section Attribution Preferences
-@ifinfo
-
-@end ifinfo
-When you cite an original message, you can tell Supercite which part of
-the author's name you would prefer it to use as the attribution.  The
-variable @code{sc-preferred-attribution-list} controls this; it contains
-keys which are matched against the attribution alist in the given order.
-The first value of a key that produces a non-@code{nil}, non-empty
-string match is used as the attribution string, and if no keys match, a
-secondary mechanism is used to generate the attribution.
-@xref{Anonymous Attributions}.
-
-The following preferences are always available in the attribution alist
-(barring error):
-
-@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 "middlename-1"
-the author's first middle name.
-
-@item "sc-lastchoice"
-the last attribution string you have selected. This is useful when you
-recite paragraphs in the reply.@refill
-
-@item "sc-consult"
-@vindex sc-attrib-selection-list
-@vindex attrib-selection-list (sc-)
-consults the customizable list @code{sc-attrib-selection-list} which can
-be used to select special attributions based on the value of any info
-key.  See below for details.
-
-@item "x-attribution"
-the original author's suggestion for attribution string choice. See below
-for details.@refill
-@end table
-
-Middle name indexes can be any positive integer greater than zero,
-though it is unlikely that many authors will have more than one middle
-name, if that many.
-
-At this point, let me digress into a discussion of etiquette.  It is my
-belief that while the style of the citations is a reflection of the
-personal tastes of the replier (i.e., you), the attribution selection is
-ultimately the personal choice of the original author.  In a sense it is
-his or her ``net nickname'', and therefore the author should have some
-say in the selection of attribution string.  Imagine how you would feel
-if someone gave you a nickname that you didn't like?
-
-For this reason, Supercite recognizes a special mail header,
-@samp{X-Attribution:}, which if present, tells Supercite the attribution
-string preferred by the original author.  It is the value of this header
-that is associated with the @code{"x-attribution"} key in the
-attribution alist.  Currently, you can override the preference of this
-key by changing @code{sc-preferred-attribution-list}, but that isn't
-polite, and in the future Supercite may hard-code this.  For now, it is
-suggested that if you change the order of the keys in this list, that
-@code{"x-attribution"} always be first, or possible second behind only
-@code{"sc-lastchoice"}.  This latter is the default.
-
-@vindex sc-attrib-selection-list
-@vindex attrib-selection-list (sc-)
-The value @code{"sc-consult"} in @code{sc-preferred-attribution-list}
-has a special meaning during attribution selection.  When Supercite
-encounters this preference, it begins processing a customizable list of
-attributions, contained in the variable @code{sc-attrib-selection-list}.
-Each element in this list contains lists of the following form:
-
-@example
-@group
-(@var{infokey} ((@var{regexp} @. @var{attribution})
-         (@var{regexp} @. @var{attribution})
-         (@dots{})))
-@end group
-@end example
-
-@noindent
-@findex sc-mail-field
-@findex mail-field (sc-)
-where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
-is a regular expression to match against the @var{infokey}'s value. If
-@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
-used as the attribution string.  Actually, @var{attribution} can be a
-string or a list; if it is a list, it is @code{eval}uated and the return
-value (which must be a string), is used as the attribution.
-
-This can be very useful for when you are replying to net acquaintances
-who do not use the @samp{X-Attribution:@:} mail header.  You may know
-what nickname they would prefer to use, and you can set up this list to
-match against a specific mail field, e.g., @samp{From:@:}, allowing you
-to cite your friend's message with the appropriate attribution.
-
-@node  Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
-@comment  node-name,  next,  previous,  up
-@vindex sc-default-author-name
-@vindex default-author-name (sc-)
-@vindex sc-default-attribution
-@vindex default-attribution (sc-)
-@comment
-@section Anonymous Attributions
-@ifinfo
-
-@end ifinfo
-When the author's name cannot be found in the @samp{From:@:} mail
-header, a fallback author name and attribution string must be supplied.
-The fallback author name is contained in the variable
-@code{sc-default-author-name} and the fallback attribution string is
-contained in the variable @code{sc-default-attribution}.  Default values
-for these variables are @code{"Anonymous"} and @code{"Anon"},
-respectively. 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 the preferred attribution, which you specified in your
-@code{sc-preferred-attribution-list} variable cannot be found, 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 the variable's value 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, and the first step to return a non-@code{nil},
-non-empty string becomes the attribution:@refill
-
-@enumerate
-@item
-Use the last selected attribution, if there is one.
-
-@item
-Use the value of the @code{"x-attribution"} key.
-
-@item
-Use the author's first name.
-
-@item
-Use the author's last name.
-
-@item
-Use the author's initials.
-
-@item
-Find the first non-@code{nil}, non-empty attribution string in the
-attribution alist.
-
-@item
-@code{sc-default-attribution} is used.
-@end enumerate
-
-@vindex sc-confirm-always-p
-@vindex confirm-always-p (sc-)
-Once the attribution string has been automatically selected, a number of
-things can happen. If the variable @code{sc-confirm-always-p} is
-non-@code{nil}, you are queried for confirmation of the chosen
-attribution string. The possible values for completion are those strings
-in the attribution alist, however you are not limited to these choices.
-You can type any arbitrary string at the confirmation prompt. The string
-you enter becomes the value associated with the @code{"sc-lastchoice"}
-key in the attribution alist.
-
-@vindex sc-downcase-p
-@vindex downcase-p (sc-)
-Once an attribution string has been selected, Supercite will force the
-string to lower case if the variable @code{sc-downcase-p} is
-non-@code{nil}.
-
-@vindex sc-attribs-preselect-hook
-@vindex attribs-preselect-hook (sc-)
-@vindex sc-attribs-postselect-hook
-@vindex attribs-postselect-hook (sc-)
-
-Two hook variables provide even greater control of the attribution
-selection process.  The hook @code{sc-attribs-preselect-hook} is run
-before any attribution is selected.  Likewise, the hook
-@code{sc-attribs-postselect-hook} is run after the attribution is
-selected (and the corresponding citation string is built), but before
-these values are committed for use by Supercite.  During the
-post-selection hook, the local variables @code{attribution} and
-@code{citation} are bound to the appropriate strings.  By changing these
-variables in your hook functions, you change the attribution and
-citation strings used by Supercite.  One possible use of this would be
-to override any automatically derived attribution string when it is only
-one character long; e.g. you prefer to use @code{"initials"} but the
-author only has one name.@refill
-
-@node  Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
-@comment  node-name,  next,  previous,  up
-@cindex author names
-@section Author Names
-@ifinfo
-
-@end ifinfo
-Supercite employs a number of heuristics to decipher the author's name
-based on value of the @samp{From:@:} mail field of the original message.
-Supercite can recognize almost all of the common @samp{From:@:} field
-formats in use.  If you encounter a @samp{From:@:} field that Supercite
-cannot parse, please report this bug.
-@xref{The Supercite Mailing List}.@refill
-
-@vindex sc-titlecue-regexp
-@vindex titlecue-regexp (sc-)
-There are a number of Supercite variables that control how author names
-are extracted from the @samp{From:@:} header.  Some headers may contain a
-descriptive title as in:
-
-@example
-From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
-@end example
-
-Supercite knows which part of the @samp{From:@:} header is email address
-and which part is author name, but in this case the string @code{"Decent
-Hacker"} is not part of the author's name.  You can tell Supercite to
-ignore the title, while still recognizing hyphenated names through the
-use of a regular expression in the variable @code{sc-titlecue-regexp}.
-This variable has the default value of @code{"\\\\s +-+\\\\s +"}.  Any
-text after this regexp is encountered is ignored as noise.
-
-@vindex sc-name-filter-alist
-@vindex name-filter-alist (sc-)
-Some @samp{From:@:} headers may contain extra titles in the name fields
-not separated by a title cue, but which are nonetheless not part of the
-author's name proper.  Examples include the titles ``Dr.'', ``Mr.'',
-``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third).
-Also, some companies prepend or append the name of the division,
-organization, or project on the author's name.  All of these titles are
-noise which should be ignored.  The variable @code{sc-name-filter-alist}
-is used for this purpose. As implied by its name, this variable is an
-association list, where each element is a cons cell of the form:
-
-@example
-(@var{regexp} @. @var{position})
-@end example
-
-@noindent
-where @var{regexp} is a regular expression that is matched (using
-@code{string-match}) against each element of the @samp{From:@:} field's
-author name.  @var{position} is a position indicator, starting at zero.
-Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
-@code{sc-name-filter-alist} would have an entry such as:
-
-@example
-("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
-@end example
-
-@noindent
-which only removes them if they appear as the first word in the name.
-The position indicator is an integer, or one of the two special symbols
-@code{last} or @code{any}.  @code{last} always matches against the last
-word in the name field, while @code{any} matches against every word in
-the name field.
-
-@node  Configuring the Citation Engine, Using Regi, Author Names, Top
-@comment  node-name,  next,  previous,  up
-@cindex Regi
-@cindex frames (Regi)
-@cindex entries (Regi)
-@chapter Configuring the Citation Engine
-@ifinfo
-
-@end ifinfo
-At the heart of Supercite is a regular expression interpreting engine
-called @dfn{Regi}.  Regi operates by interpreting a data structure
-called a Regi-frame (or just @dfn{frame}), which is a list of
-Regi-entries (or just @dfn{entry}).  Each entry contains a predicate,
-typically a regular expression, which is matched against a line of text
-in the current buffer.  If the predicate matches true, an associated
-expression is @code{eval}uated.  In this way, an entire region of text
-can be transformed in an @emph{awk}-like manner.  Regi is used
-throughout Supercite, from mail header information extraction, to header
-nuking, to citing text.
-
-@ifinfo
-@menu
-* Using Regi::
-* Frames You Can Customize::
-@end menu
-@end ifinfo
-
-While the details of Regi are discussed below (@pxref{Using Regi}), only
-those who wish to customize certain aspects of Supercite need concern
-themselves with it.  It is important to understand though, that any
-conceivable citation style that can be described by a regular expression
-can be recognized by Supercite.  This leads to some interesting
-applications.  For example, if you regularly receive email from a
-co-worker that uses an uncommon citation style (say one that employs a
-@samp{|} or @samp{@}} character at the front of the line), it is
-possible for Supercite to recognize this and @emph{coerce} the citation
-to your preferred style, for consistency.  In theory, it is possible for
-Supercite to recognize such things as uuencoded messages or C code and
-cite or fill those differently than normal text.  None of this is
-currently part of Supercite, but contributions are welcome!
-
-@node  Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
-@comment  node-name,  next,  previous,  up
-@findex regi-interpret
-@findex eval
-@findex looking-at
-@section Using Regi
-@ifinfo
-
-@end ifinfo
-Regi works by interpreting frames with the function
-@code{regi-interpret}.  A frame is a list of arbitrary size where each
-element is a entry of the following form:
-
-@example
-(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]])
-@end example
-
-Regi starts with the first entry in a frame, evaluating the @var{pred}
-of that entry against the beginning of the line that @samp{point} is on.
-If the @var{pred} evaluates to true (or false if the optional
-@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is
-@code{eval}uated.  How processing continues is determined by the return
-value for @var{func}, and is described below.  If @var{pred} was false
-the next entry in the frame is checked until all entries have been
-matched against the current line.  If no entry matches, @samp{point} is
-moved forward one line and the frame is reset to the first entry.
-
-@var{pred} can be a string, a variable, a list or one of the following
-symbols: @code{t}, @code{begin}, @code{end}, or @code{every}.  If
-@var{pred} is a string, or a variable or list that @code{eval}uates to a
-string, it is interpreted as a regular expression.  This regexp is
-matched against the current line, from the beginning, using
-@code{looking-at}.  This match folds case if the optional
-@var{case-fold-search} is non-@code{nil}.  If @var{pred} is not a
-string, or does not @code{eval}uate to a string, it is interpreted as a
-binary value (@code{nil} or non-@code{nil}).@refill
-
-The four special symbol values for @var{pred} are recognized:
-
-@table @code
-@item t
-Always produces a true outcome.
-@item begin
-Always executed before the frame is interpreted. This can be used to
-initialize some global variables for example.
-@item end
-Always executed after frame interpreting is completed. This can be used
-to perform any necessary post-processing.
-@item every
-Executes whenever the frame is reset, usually after the entire frame has
-been matched against the current line.
-@end table
-
-Note that @var{negate-p} and @var{case-fold-search} are ignored if
-@var{pred} is one of these special symbols.  Only the first occurrence of
-each symbol in a frame is used; any duplicates are ignored.  Also
-note that for performance reasons, the entries associated with these
-symbols are removed from the frame during the main interpreting loop.
-
-Your @var{func} can return certain values which control continued Regi
-processing.  By default, if your @var{func} returns @code{nil} (as it
-should be careful to do explicitly), Regi will reset the frame to the
-first entry, and advance @samp{point} to the beginning of the next line.
-If a list is returned from your function, it can contain any combination
-of the following elements:@refill
-
-@table @asis
-@item the symbol @code{continue}
-This tells Regi to continue processing entries after a match, instead of
-resetting the frame and moving @samp{point}. In this way, lines of text
-can have multiple matches, but you have to be careful to avoid entering
-infinite loops.
-
-@item the symbol @code{abort}
-This tells Regi to terminate frame processing. However, any @code{end}
-entry is still processed.
-
-@item the list @code{(frame . @var{newframe})}
-This tells Regi to substitute @var{newframe} as the frame it is
-interpreting.  In other words, your @var{func} can modify the Regi frame
-on the fly.  @var{newframe} can be a variable containing a frame, or it
-can be the frame in-lined.@refill
-
-@item the list @code{(step . @var{step})}
-Tells Regi to move @var{step} number of lines forward as it continues
-processing. By default, Regi moves forward one line.  @var{step} can be
-zero or negative of course, but watch out for infinite loops.@refill
-@end table
-
-During execution of your @var{func}, the following variables will be
-temporarily bound to some useful information:@refill
-
-@table @code
-@item curline
-The current line in the buffer that Regi is @code{looking-at}, as a string.
-@item curframe
-The current frame being interpreted.
-@item curentry
-The current frame entry being interpreted.
-@end table
-
-@node  Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
-@comment  node-name,  next,  previous,  up
-@vindex sc-nuke-mail-header
-@section Frames You Can Customize
-@ifinfo
-
-@end ifinfo
-As mentioned earlier, Supercite uses various frames to perform
-certain jobs such as mail header information extraction and mail header
-nuking.  However, these frames are not available for you to customize,
-except through abstract interfaces such as @code{sc-nuke-mail-header},
-et al.
-
-@vindex sc-default-cite-frame
-However, the citation frames Supercite uses provide a lot of customizing
-power and are thus available to you to change to suit your needs.  The
-workhorse of citation is the frame contained in the variable
-@code{sc-default-cite-frame}.  This frame recognizes many situations,
-such as blank lines, which it interprets as paragraph separators.  It
-also recognizes previously cited nested and non-nested citations in the
-original message.  By default it will coerce non-nested citations into
-your preferred citation style, and it will add a level of citation to
-nested citations.  It will also simply cite uncited lines in your
-preferred style.
-
-@cindex unciting
-@cindex reciting
-@vindex sc-default-uncite-frame
-@vindex sc-default-recite-frame
-In a similar vein, there are default frames for @dfn{unciting} and
-@dfn{reciting}, contained in the variables
-@code{sc-default-uncite-frame} and @code{sc-default-recite-frame}
-respectively.@refill
-
-As mentioned earlier (@pxref{Recognizing Citations}), citations are
-recognized through the values of the regular expressions
-@code{sc-citation-root-regexp}, et al.  To recognize odd styles, you
-could modify these variables, or you could modify the default citing
-frame.  Alternatively, you could set up association lists of frames for
-recognizing specific alternative forms.
-
-@vindex sc-cite-frame-alist
-@vindex sc-uncite-frame-alist
-@vindex sc-recite-frame-alist
-For each of the actions -- citing, unciting, and reciting -- an alist is
-consulted to find the frame to use (@code{sc-cite-frame-alist},
-@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
-respectively).  These frames can contain alists of the form:
-
-@example
-((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
- (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
- (@dots{}))
-@end example
-
-@vindex sc-mail-field
-@findex string-match
-Where @var{infokey} is a key suitable for @code{sc-mail-field},
-@var{regexp} is a regular expression which is @code{string-match}'d
-against the value of the @code{sc-mail-field} key, and @var{frame} is
-the frame to use if a match occurred.  @var{frame} can be a variable
-containing a frame or a frame in-lined.@refill
-
-When Supercite is about to cite, uncite, or recite a region, it consults
-the appropriate alist and attempts to find a frame to use.  If one
-is not found from the alist, then the appropriate default frame is used.
-
-@node  Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
-@comment  node-name,  next,  previous,  up
-@vindex sc-mode-map-prefix
-@vindex mode-map-prefix (sc-)
-@kindex C-c C-p
-@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 do its thing, a number of
-useful Supercite commands will be available to you. Since there is wide
-variety in the keymaps that MUAs set up in their reply buffers, it is
-next to impossible for Supercite to properly sprinkle its commands into
-the existing keymap.  For this reason Supercite places its commands on a
-separate keymap, putting this keymap onto a prefix key in the reply
-buffer. You can customize the prefix key Supercite uses by changing the
-variable @code{sc-mode-map-prefix}.  By default, the
-@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
-but unfortunately the best general solution so far.  In the rest of this
-chapter, we'll assume you've installed Supercite's keymap on the default
-prefix.@refill
-
-@ifinfo
-@menu
-* Citing Commands::
-* Insertion Commands::
-* Variable Toggling Shortcuts::
-* Mail Field Commands::
-* Miscellaneous Commands::
-@end menu
-@end ifinfo
-
-@node   Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
-@comment  node-name,  next,  previous,  up
-@vindex sc-cite-region-limit
-@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 unciting of
-regions of text in the reply buffer. Often you may want to recite a
-paragraph to use a nickname, or manually cite a message when setting
-@code{sc-cite-region-limit} to @code{nil}.  The following commands
-perform these functions on the region of text between @samp{point} and
-@samp{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
-
-A quick note about Emacs 19.  Unlike in Emacs 18, the region delimited
-by @samp{point} and @samp{mark} can have two states.  It can be
-@dfn{active} or @dfn{inactive}.  Although Emacs 19 and Lucid Emacs 19
-use different terminology and functions, both employ the same convention
-such that when the region is inactive, commands that modify the region
-should generate an error.  The user needs to explicitly activate the
-region before successfully executing the command.  All Supercite
-commands conform to this convention.
-
-Here is the list of Supercite citing commands:
-
-@table @asis
-@findex sc-cite-region
-@findex cite-region (sc-)
-@kindex C-c C-p c
-@vindex sc-pre-cite-hook
-@vindex pre-cite-hook (sc-)
-@vindex sc-confirm-always-p
-@vindex confirm-always-p
-@kindex C-u
-@item @code{sc-cite-region} (@kbd{C-c C-p c})
-@comment
-This command cites each line in the region of text by interpreting the
-selected frame from @code{sc-cite-frame-alist}, or the default citing
-frame @code{sc-default-cite-frame}.  It runs the hook
-@code{sc-pre-cite-hook} before interpreting the frame.  With an optional
-universal argument (@kbd{C-u}), it temporarily sets
-@code{sc-confirm-always-p} to @code{t} so you can confirm the
-attribution string for a single manual citing.
-@xref{Configuring the Citation Engine}.@refill
-
-@findex sc-uncite-region
-@findex uncite-region (sc-)
-@kindex C-c C-p u
-@item @code{sc-uncite-region} (@kbd{C-c C-p u})
-@comment
-This command removes any citation strings from the beginning of each
-cited line in the region by interpreting the selected frame from
-@code{sc-uncite-frame-alist}, or the default unciting frame
-@code{sc-default-uncite-frame}.  It runs the hook
-@code{sc-pre-uncite-hook} before interpreting the frame.
-@xref{Configuring the Citation Engine}.@refill
-
-@findex sc-recite-region
-@findex recite-region (sc-)
-@kindex C-c C-p r
-@item @code{sc-recite-region} (@kbd{C-c C-p r})
-@comment
-This command recites each line the region by interpreting the selected
-frame from @code{sc-recite-frame-alist}, or the default reciting frame
-@code{sc-default-recite-frame}. It runs the hook
-@code{sc-pre-recite-hook} before interpreting the frame.
-@xref{Configuring the Citation Engine}.@refill
-
-@vindex sc-confirm-always-p
-@vindex confirm-always-p (sc-)
-Supercite will always ask you to confirm the attribution when reciting a
-region, regardless of the value of @code{sc-confirm-always-p}.
-@end table
-
-@node  Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
-@comment  node-name,  next,  previous,  up
-@section Insertion Commands
-@ifinfo
-
-@end ifinfo
-These two functions insert various strings into the reply buffer.
-
-@table @asis
-@findex sc-insert-reference
-@findex insert-reference (sc-)
-@kindex C-c C-p w
-@item @code{sc-insert-reference} (@kbd{C-c C-p w})
-@comment
-@vindex sc-preferred-header-style
-@vindex preferred-header-style (sc-)
-Inserts a reference header into the reply buffer at @samp{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.@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-p i
-@item @code{sc-insert-citation} (@kbd{C-c C-p i})
-@comment
-Inserts the current citation string at the beginning of the line that
-@samp{point} is on.  If the line is already cited, Supercite will issue
-an error and will not cite the line.
-@end table
-
-@node  Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
-@comment  node-name,  next,  previous,  up
-@cindex toggling variables
-@section Variable Toggling Shortcuts
-@ifinfo
-
-@end ifinfo
-Supercite defines a number of commands that make it easier for you to
-toggle and set various Supercite variables as you are editing the reply
-buffer.  For example, you may want to turn off filling or whitespace
-cleanup, but only temporarily.  These toggling shortcut commands make
-this easy to do.
-
-@kindex C-c C-p C-t
-Like Supercite commands in general, the toggling commands are placed on
-a keymap prefix within the greater Supercite keymap.  For the default
-value of @code{sc-mode-map-prefix}, this will be
-@kbd{C-c C-p C-t}.@refill
-
-The following commands toggle the value of certain Supercite variables
-which take only a binary value:
-
-@table @kbd
-@item C-c C-p C-t b
-Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
-
-@item C-c C-p C-t c
-Toggles the variable @code{sc-confirm-always-p}.
-
-@item C-c C-p C-t d
-Toggles the variable @code{sc-downcase-p}.
-
-@item C-c C-p C-t e
-Toggles the variable @code{sc-electric-references-p}.
-
-@item C-c C-p C-t f
-Toggles the variable @code{sc-auto-fill-region-p}.
-
-@item C-c C-p C-t o
-Toggles the variable @code{sc-electric-circular-p}.
-
-@item C-c C-p C-t s
-Toggles the variable @code{sc-nested-citation-p}.
-
-@item C-c C-p C-t u
-Toggles the variable @code{sc-use-only-preferences-p}.
-
-@item C-c C-p C-t w
-Toggles the variable @code{sc-fixup-whitespace-p}.
-@end table
-
-@findex set-variable
-The following commands let you set the value of multi-value variables,
-in the same way that Emacs' @code{set-variable} does:
-
-@table @kbd
-@item C-c C-p C-t a
-Sets the value of the variable @code{sc-preferred-attribution-list}.
-
-@item C-c C-p C-t l
-Sets the value of the variable @code{sc-cite-region-limit}.
-
-@item C-c C-p C-t n
-Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
-
-@item C-c C-p C-t N
-Sets the value of the variable @code{sc-mail-header-nuke-list}.
-
-@item C-c C-p C-t p
-Sets the value of the variable @code{sc-preferred-header-style}.
-@end table
-
-@kindex C-c C-p C-p
-One special command is provided to toggle both
-@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together.
-This is because you typically want to run Supercite with either variable
-as @code{nil} or non-@code{nil}.  The command to toggle these variables
-together is bound on @kbd{C-c C-p C-p}.@refill
-
-Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?})
-brings up a Help message on the toggling keymap.
-
-
-@node  Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
-@comment  node-name,  next,  previous,  up
-@section Mail Field Commands
-@ifinfo
-
-@end ifinfo
-These commands allow you to view, modify, add, and delete various bits
-of information from the info alist.
-@xref{Information Keys and the Info Alist}.@refill
-
-@table @asis
-@kindex C-c C-p f
-@findex sc-mail-field-query
-@findex mail-field-query (sc-)
-@kindex C-c C-p f
-@item @code{sc-mail-field-query} (@kbd{C-c C-p f})
-@comment
-Allows you to interactively view, modify, add, and delete info alist
-key-value pairs.  With no argument, you are prompted (with completion)
-for a info key.  The value associated with that key is displayed in the
-minibuffer.  With an argument, this command will first ask if you want
-to view, modify, add, or delete an info key. Viewing is identical to
-running the command with no arguments.
-
-If you want to modify the value of a key, Supercite will first prompt
-you (with completion) for the key of the value you want to change.  It
-will then put you in the minibuffer with the key's current value so you
-can edit the value as you wish.  When you hit @key{RET}, the key's value
-is changed.  For those of you running Emacs 19, minibuffer history is
-kept for the values.
-
-If you choose to delete a key-value pair, Supercite will prompt you (with
-completion) for the key to delete.
-
-If you choose to add a new key-value pair, Supercite firsts prompts you
-for the key to add.  Note that completion is turned on for this prompt,
-but you can type any key name here, even one that does not yet exist.
-After entering the key, Supercite prompts you for the key's value.  It
-is not an error to enter a key that already exists, but the new value
-will override any old value.  It will not replace it though; if you
-subsequently delete the key-value pair, the old value will reappear.
-
-@findex sc-mail-process-headers
-@findex mail-process-headers (sc-)
-@kindex C-c C-p g
-@item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
-@comment
-This command lets you re-initialize Supercite's info alist from any set
-of mail headers in the region between @samp{point} and @samp{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
-@end table
-
-@node  Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
-@comment  node-name,  next,  previous,  up
-@section Miscellaneous Commands
-@ifinfo
-
-@end ifinfo
-@table @asis
-@findex sc-open-line
-@findex open-line (sc-)
-@findex open-line
-@kindex C-c C-p o
-@item @code{sc-open-line} (@kbd{C-c C-p o})
-@comment
-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
-
-@findex sc-describe
-@findex describe (sc-)
-@kindex C-c C-p ?
-@kindex C-c C-p h
-@item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
-@comment
-This function has been obsoleted by the @TeX{}info manual you are now
-reading. It is still provided for compatibility, but it will eventually
-go away.
-
-@findex sc-version
-@findex version (sc-)
-@kindex C-c C-p v
-@item @code{sc-version} (@kbd{C-c C-p v})
-@comment
-Echos the version of Supercite you are using.  With the optional
-universal argument (@kbd{C-u}), this command inserts the version
-information into the current buffer.
-
-@findex sc-submit-bug-report
-@findex submit-bug-report (sc-)
-@kindex C-c C-p C-b
-@item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
-@comment
-If you encounter a bug, or wish to suggest an enhancement, use this
-command to set up an outgoing mail buffer, with the proper address to
-the Supercite maintainer automatically inserted in the @samp{To:@:}
-field.  This command also inserts information that the Supercite
-maintainer can use to recreate your exact setup, making it easier to
-verify your bug.
-@end table
-
-@node  Hints to MUA Authors, Version 3 Changes, Electric References, Top
-@comment  node-name,  next,  previous,  up
-@chapter Hints to MUA Authors
-@ifinfo
-
-@end ifinfo
-In June of 1989, some discussion was held between the various MUA
-authors, the Supercite author, and other Supercite users. These
-discussions centered around the need for a standard interface between
-MUAs and Supercite (or any future 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. [@dots{}]
-@end example
-
-@vindex mail-citation-hook
-@vindex mail-yank-hooks
-@cindex sendmail.el
-@findex mail-yank-original
-@findex defvar
-This specification was adopted, but with the recent release of
-Emacs 19, it has undergone a slight modification.  Instead of the
-variable @code{mail-yank-hooks}, the new preferred hook variable that
-the MUA should provide is @code{mail-citation-hook}.
-@code{mail-yank-hooks} can be provided for backward compatibility, but
-@code{mail-citation-hook} should always take precedence.  Richard
-Stallman (of the FSF) suggests that the MUAs should @code{defvar}
-@code{mail-citation-hook} to @code{nil} and perform some default citing
-when that is the case.  Take a look at Emacs 19's @file{sendmail.el}
-file, specifically the @code{mail-yank-original} defun for
-details.@refill
-
-If you are writing a new MUA package, or maintaining an existing MUA
-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 MUA should follow these
-steps:
-
-@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 @samp{point} to the beginning of the line containing the first mail
-header in the body of the reply. Set @samp{mark} at 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 venture outside the region for any reason,
-and anything within the region is fair game, so don't put anything that
-@strong{must} remain unchanged inside the region.  Further note that for
-Emacs 19, the region need not be set active.  Supercite will work
-properly when the region is inactive, as should any other like-minded
-package.@refill
-
-@item
-Run the hook @code{mail-citation-hook}. 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 MUA should
-@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
-yanking function, check its value.  If it finds
-@code{mail-citation-hook} to be @code{nil}, it should perform some
-default citing behavior.  User who want to connect to Supercite then
-need only add @code{sc-cite-original} to this list of hooks using
-@code{add-hook}.@refill
-@end enumerate
-
-If you do all this, your users will not need to overload your routines
-to use Supercite, and your MUA will join the ranks of those that conform
-to this interface ``out of the box.''
-
-@node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
-@comment  node-name,  next,  previous,  up
-@chapter Version 3 Changes
-@ifinfo
-
-@end ifinfo
-@cindex sc-unsupp.el file
-With version 3, Supercite has undergone an almost complete rewrite, and
-has hopefully benefited in a number of ways, including vast
-improvements in the speed of performance, a big reduction in size of the
-code and in the use of Emacs resources, and a much cleaner and flexible
-internal architecture.  The central construct of the info alist, and its
-role in Supercite has been expanded, and the other central concept, the
-general package Regi, was developed to provide a theoretically unlimited
-flexibility.
-
-But most of this work is internal and not of very great importance to the
-casual user. There have been some changes at the user-visible level,
-but for the most part, the Supercite configuration variables from
-version 2 should still be relevant to version 3.  Below, I briefly
-outline those user-visible things that have changed since version 2. For
-details, look to other sections of this manual.
-
-@enumerate
-@item
-@cindex supercite.el file
-@cindex reporter.el file
-@cindex regi.el file
-@cindex sc.el from version 2
-@cindex sc-elec.el from version 2
-Supercite proper now comes in a single file, @file{supercite.el}, which
-contains everything except the unsupported noodlings, overloading (which
-should be more or less obsolete with the release of Emacs 19), and the
-general lisp packages @file{reporter.el} and @file{regi.el}.  Finally,
-the @TeX{}info manual comes in its own file as well.  In particular, the
-file @file{sc.el} from the version 2 distribution is obsolete, as is the
-file @file{sc-elec.el}.
-
-@item
-@code{sc-spacify-name-chars} is gone in version 3.
-
-@item
-@vindex sc-attrib-selection-list
-@vindex attrib-selection-list
-@code{sc-nickname-alist} is gone in version 3.  The
-@code{sc-attrib-selection-list} is a more general construct supporting
-the same basic feature.
-
-@item
-The version 2 variable @code{sc-preferred-attribution} has been changed
-to @code{sc-preferred-attribution-list}, and has been expanded upon to
-allow you to specify an ordered list of preferred attributions.
-
-@item
-@code{sc-mail-fields-list} has been removed, and header nuking in
-general has been greatly improved, giving you wider flexibility in
-specifying which headers to keep and remove while presenting a
-simplified interface to commonly chosen defaults.
-
-@item
-Post-yank paragraph filling has been completely removed from Supercite,
-other packages just do it better than Supercite ever would.  Supercite
-will still fill newly cited paragraphs.
-
-@item
-@vindex sc-cite-region-limit
-@vindex cite-region-limit
-The variable @code{sc-all-but-cite-p} has been replaced by
-@code{sc-cite-region-limit}.
-
-@item
-Keymap hacking in the reply buffer has been greatly simplified, with, I
-believe, little reduction in functionality.
-
-@item
-Hacking of the reply buffer's docstring has been completely eliminated.
-@end enumerate
-
-@node  Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
-@comment  node-name,  next,  previous,  up
-@chapter Thanks and History
-@ifinfo
-
-@end ifinfo
-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 Supercite version 2 evolved to the point where much
-of the attribution selection mechanism was automatic, and features have
-been continuously added through the comments and suggestions of the
-Supercite mailing list participants.  Supercite version 3 represents a
-nearly complete rewrite with many of the algorithms and coding styles
-being vastly improved.  Hopefully Supercite version 3 is faster,
-smaller, and much more flexible than its predecessors.
-
-In the version 2 manual I thanked some specific people for their help in
-developing Supercite 2.  You folks know who you are and your continued
-support is greatly appreciated.  I wish to thank everyone on the
-Supercite mailing list, especially the brave alpha testers, who helped
-considerably in testing out the concepts and implementation of Supercite
-version 3.  Special thanks go out to the MUA and Emacs authors Kyle
-Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming
-to a quick agreement on the new @code{mail-citation-hook} interface, and
-for adding the magic lisp to their code to support this.
-
-All who have helped and contributed have been greatly appreciated.
-
-@node  The Supercite Mailing List, GNU Free Documentation License, Thanks and History, Top
-@comment  node-name,  next,  previous,  up
-@cindex supercite mailing list address
-@cindex mailing list address
-@chapter The Supercite Mailing List
-@ifinfo
-
-@end ifinfo
-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
-supercite-request@@python.org
-@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
-supercite@@python.org
-@end example
-
-If you are sending bug reports, they should go to the following address,
-but @emph{please}! use the command @code{sc-submit-bug-report} since it
-will be much easier for me to duplicate your problem if you do so.  It
-will set up a mail buffer automatically with this address on the
-@samp{To:@:} line:
-
-@example
-supercite-help@@python.org
-@end example
-
-@node GNU Free Documentation License, Concept Index, The Supercite Mailing List, Top
-@appendix GNU Free Documentation License
-@include doclicense.texi
-
-@node  Concept Index, Command Index, GNU Free Documentation License, 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
-@ifinfo
-
-@end ifinfo
-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
-@ifinfo
-
-@end ifinfo
-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
-@setchapternewpage odd
-@summarycontents
-@contents
-@bye
-
-@ignore
-   arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436
-@end ignore