[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to sc.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to sc.texi |
|
Date: |
Thu, 06 Sep 2007 05:02:00 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 05:01:59
Index: sc.texi
===================================================================
RCS file: sc.texi
diff -N sc.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ sc.texi 6 Sep 2007 05:01:59 -0000 1.1
@@ -0,0 +1,2533 @@
+\input texinfo @comment -*-texinfo-*-
address@hidden 3.48
address@hidden %**start of header (This is for running Texinfo on a region.)
address@hidden ../info/sc
address@hidden Supercite Version 3.1 User's Manual
address@hidden
address@hidden
address@hidden iftex
+
address@hidden @setchapternewpage odd % For book style double sided
manual.
address@hidden %**end of header (This is for running Texinfo on a region.)
+
address@hidden
+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.
+
address@hidden
+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.
address@hidden quotation
address@hidden copying
+
address@hidden @smallbook
+
address@hidden Emacs
address@hidden
+* SC: (sc). Supercite lets you cite parts of messages you're
+ replying to, in flexible ways.
address@hidden direntry
+
address@hidden
address@hidden 6
address@hidden @titlefont{Supercite User's Manual}
address@hidden 2
address@hidden @titlefont{Supercite Version 3.1}
address@hidden 4
address@hidden Manual Revision: 3.48
address@hidden April 2007
address@hidden 5
address@hidden Barry address@hidden Warsaw
address@hidden @t{bwarsaw@@cen.com}
address@hidden @address@hidden
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
address@hidden Top, Introduction, (dir), (dir)
address@hidden 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.
+
address@hidden
+* 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::
address@hidden menu
address@hidden ifnottex
+
+
address@hidden Introduction, Usage Overview, Top, Top
address@hidden node-name, next, previous, up
address@hidden Introduction
address@hidden
+
address@hidden 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
address@hidden
+
address@hidden
address@hidden
+* Usage Overview::
+* What Supercite Does Not Do::
+* What Supercite Does::
address@hidden menu
address@hidden ifinfo
+
address@hidden MUA
address@hidden NUA
+Supercite is only useful in conjunction with MUAs and NUAs such as VM,
+GNUS, RMAIL, address@hidden (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:
+
address@hidden @asis
address@hidden Emacs versions:
+ GNU Emacs 18.57 through 18.59, all Emacs 19,
+ all current Lucid Emacs, and Epoch address@hidden
+
address@hidden MUAs:
+ VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
+ beyond, address@hidden
+
address@hidden NUAs:
+ RNEWS, GNUS 3.12 and beyond, address@hidden
+
address@hidden 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 address@hidden
+
+
address@hidden Usage Overview, What Supercite Does Not Do, Introduction,
Introduction
address@hidden node-name, next, previous, up
address@hidden r
address@hidden f
address@hidden C-c C-y
address@hidden yank
address@hidden cite, citing
address@hidden attribute, attributing
address@hidden
address@hidden Usage Overview
address@hidden
+
address@hidden 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
address@hidden C-y}. This sequence will invoke an MUA-specific function which
+fills the body of the reply with the original message and then
address@hidden 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.
+
address@hidden What Supercite Does Not Do, What Supercite Does, Usage
Overview, Introduction
address@hidden node-name, next, previous, up
address@hidden What Supercite Doesn't Do
address@hidden
+
address@hidden 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.
address@hidden Buffer address@hidden
+
address@hidden mail-header-separator
address@hidden
+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
address@hidden 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
address@hidden
+
address@hidden What Supercite Does, Citations, What Supercite Does Not Do,
Introduction
address@hidden node-name, next, previous, up
address@hidden sc-cite-original
address@hidden What Supercite Does
address@hidden
+
address@hidden 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
address@hidden 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
address@hidden
+
address@hidden 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
address@hidden association list}, or @dfn{info alist}. The information
+in this list is used in a number of places throughout Supercite.
address@hidden Keys and the Info address@hidden
+
address@hidden nuking mail headers
address@hidden reference header
+After the mail header info is extracted, the headers are optionally
+removed (@dfn{nuked}) from the reply. Supercite then writes a
address@hidden header} into the buffer. This reference header is a
+string carrying details about the citation it is about to perform.
+
address@hidden 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}.
+
address@hidden filladapt
address@hidden gin-mode
address@hidden fill-prefix
address@hidden fill-paragraph
address@hidden
+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, address@hidden @code{fill-paragraph}, do not recognize cited
+text and will not re-fill them properly because it cannot guess the
address@hidden being used.
address@hidden Formatting Commands}, for address@hidden
+
+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 address@hidden
+
address@hidden Citations, Citation Elements, What Supercite Does, Top
address@hidden node-name, next, previous, up
address@hidden nested citations
address@hidden citation
address@hidden
address@hidden Citations
address@hidden
+
address@hidden 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:
+
address@hidden
+>> 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.
address@hidden example
+
address@hidden
address@hidden
+* Citation Elements::
+* Recognizing Citations::
address@hidden menu
address@hidden ifinfo
+
+Note that multiple inclusions of the original messages result in a
+nesting of the @address@hidden>}} 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 @address@hidden>}} characters can sometimes
+make the message very difficult for the eye to scan.
+
address@hidden 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:
+
address@hidden
+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.
address@hidden 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>}.
+
address@hidden sc-nested-citation-p
address@hidden nested-citation-p (sc-)
+Supercite supports both styles of citation, and the variable
address@hidden 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 address@hidden, nested citations
+are used.
+
+
address@hidden Citation Elements, Recognizing Citations, Citations, Citations
address@hidden node-name, next, previous, up
address@hidden citation string
address@hidden
address@hidden Citation Elements
address@hidden
+
address@hidden ifinfo
address@hidden 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:
+
address@hidden citation leader
address@hidden citation-leader (sc-)
address@hidden sc-citation-leader
address@hidden
address@hidden
+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.
+
address@hidden attribution string
address@hidden
+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.
address@hidden an Attribution}, for more address@hidden
+
address@hidden citation delimiter
address@hidden sc-citation-delimiter
address@hidden citation-delimiter (sc-)
address@hidden
+The @dfn{citation delimiter}. This string, contained in the variable
address@hidden 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.
+
address@hidden citation separator
address@hidden citation-separator (sc-)
address@hidden sc-citation-separator
address@hidden
+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.
address@hidden 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
address@hidden@asis{" Jane> "}}.
+This citation string will be inserted in front of
+every line in the original message that is not already address@hidden
+
+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.
+
address@hidden Recognizing Citations, Getting Connected, Citation Elements,
Citations
address@hidden node-name, next, previous, up
address@hidden Recognizing Citations
address@hidden
+
address@hidden 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.
+
address@hidden sc-citation-leader-regexp
address@hidden citation-leader-regexp (sc-)
address@hidden sc-citation-delimiter-regexp
address@hidden citation-delimiter-regexp (sc-)
address@hidden sc-citation-separator-regexp
address@hidden citation-separator-regexp (sc-)
address@hidden sc-citation-root-regexp
address@hidden citation-root-regexp (sc-)
address@hidden sc-citation-nonnested-root-regexp
address@hidden 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
address@hidden"^"}.
+
+Similarly, the variables @code{sc-citation-delimiter-regexp} and
address@hidden respectively describe how citation
+delimiters and separators can look. They follow the same rule as
address@hidden 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
address@hidden 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
address@hidden@refill
+
address@hidden Information Keys and the Info Alist, Reference Headers,
Miscellaneous Commands, Top
address@hidden node-name, next, previous, up
address@hidden information keys
address@hidden Info Alist
address@hidden information extracted from mail fields
address@hidden sc-mail-field
address@hidden mail-field (sc-)
address@hidden
address@hidden Information Keys and the Info Alist
address@hidden
+
address@hidden ifinfo
address@hidden 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
+
address@hidden
+Date:@: 08 April 1991, 17:32:09 EST
+Subject:@: Better get out your asbestos suit
address@hidden example
+
address@hidden sc-mumble
address@hidden mumble (sc-)
address@hidden
+then, the following lisp constructs return:
+
address@hidden
+(sc-mail-field "date")
+==> "08 April 1991, 17:32:09 EST"
+
+(sc-mail-field "subject")
+==> "Better get out your asbestos suit"
address@hidden 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:
+
address@hidden @code
address@hidden sc-attribution info field
address@hidden attribution info field (sc-)
address@hidden "sc-attribution"
+the selected attribution string.
+
address@hidden sc-citation info field
address@hidden citation info field (sc-)
address@hidden "sc-citation"
+the non-nested citation string.
+
address@hidden sc-from-address info field
address@hidden from-address info field (sc-)
address@hidden "sc-from-address"
+email address extracted from the @samp{From:@:} field.
+
address@hidden sc-reply-address info field
address@hidden reply-address info field (sc-)
address@hidden "sc-reply-address"
+email address extracted from the @samp{Reply-To:@:} field.
+
address@hidden sc-sender-address info field
address@hidden sender-address info field (sc-)
address@hidden "sc-sender-address"
+email address extracted from the @samp{Sender:@:} field.
+
address@hidden sc-emailname info field
address@hidden emailname info field (sc-)
address@hidden "sc-emailname"
+email terminus extracted from the @samp{From:@:} field.
+
address@hidden sc-initials info field
address@hidden initials info field (sc-)
address@hidden "sc-initials"
+the author's initials.
+
address@hidden sc-author info field
address@hidden author info field (sc-)
address@hidden "sc-author"
+the author's full name.
+
address@hidden sc-firstname info field
address@hidden firstname info field (sc-)
address@hidden "sc-firstname"
+the author's first name.
+
address@hidden sc-lastname info field
address@hidden lastname info field (sc-)
address@hidden "sc-lastname"
+the author's last name.
+
address@hidden sc-middlename-1 info field
address@hidden middlename-1 info field (sc-)
address@hidden "sc-middlename-1"
+the author's first middle name.
address@hidden 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"},
address@hidden). @xref{Selecting an address@hidden
+
address@hidden Reference Headers, The Built-in Header Rewrite Functions,
Information Keys and the Info Alist, Top
address@hidden node-name, next, previous, up
address@hidden reference headers
address@hidden Reference Headers
address@hidden
+
address@hidden 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.
+
address@hidden
address@hidden
+* The Built-in Header Rewrite Functions::
+* Electric References::
address@hidden menu
address@hidden ifinfo
+
address@hidden header rewrite functions
address@hidden sc-rewrite-header-list
address@hidden 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
address@hidden 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}.
address@hidden References}.
+
address@hidden sc-preferred-header-style
address@hidden preferred-header-style (sc-)
+When Supercite is initially run on a reply buffer (via
address@hidden), it will automatically call one of these
+functions. The one it uses is defined in the variable
address@hidden The value of this variable is an
+integer which is an index into the @code{sc-rewrite-header-list},
+beginning at zero.
+
address@hidden The Built-in Header Rewrite Functions, Electric References,
Reference Headers, Reference Headers
address@hidden node-name, next, previous, up
address@hidden header rewrite functions, built-in
address@hidden
address@hidden The Built-in Header Rewrite Functions
address@hidden
+
address@hidden 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
address@hidden:@:} and @samp{From:@:} mail headers address@hidden
+
address@hidden sc-reference-tag-string
address@hidden 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
address@hidden:@:} 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).
+
address@hidden @code
address@hidden sc-no-header
address@hidden no-header (sc-)
address@hidden sc-no-header
+This function produces no header. It should be used instead of
address@hidden to produce a blank header. This header can possibly contain
+a blank line after the @code{mail-header-separator} line.
+
address@hidden sc-no-blank-line-or-header
address@hidden sc-no-blank-line-or-header
address@hidden 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.
+
address@hidden sc-header-on-said
address@hidden sc-header-on-said
address@hidden header-on-said (sc-)
address@hidden>>>>> On @var{date}, @var{from} said:}
+
address@hidden sc-header-inarticle-writes
address@hidden sc-header-inarticle-writes
address@hidden header-inarticle-writes (sc-)
address@hidden>>>>> In article @var{message-id}, @var{from} writes:}
+
address@hidden sc-header-regarding-adds
address@hidden sc-header-regarding-adds
address@hidden header-regarding-adds (sc-)
address@hidden>>>>> Regarding @var{subject}; @var{from} adds:}
+
address@hidden sc-header-attributed-writes
address@hidden sc-header-attributed-writes
address@hidden header-attributed-writes (sc-)
address@hidden>>>>> "@var{sc-attribution}" == @var{sc-author}
<@var{sc-reply-address}> writes:}
+
address@hidden sc-header-author-writes
address@hidden sc-header-author-writes
address@hidden header-author-writes (sc-)
address@hidden>>>>> @var{sc-author} writes:}
+
address@hidden sc-header-verbose
address@hidden sc-header-verbose
address@hidden header-verbose (sc-)
address@hidden>>>>> On @var{date},address@hidden
address@hidden>>>>> @address@hidden
address@hidden>>>>> from the organization of @address@hidden
address@hidden>>>>> who can be reached at:@: @address@hidden
address@hidden>>>>> (whose comments are cited below with:@:
"@var{sc-cite}")address@hidden
address@hidden>>>>> had this to say in article @address@hidden
address@hidden>>>>> in newsgroups @address@hidden
address@hidden>>>>> concerning the subject of @address@hidden
address@hidden>>>>> see @var{references} for more details}
address@hidden table
+
address@hidden Electric References, Hints to MUA Authors, The Built-in Header
Rewrite Functions, Reference Headers
address@hidden node-name, next, previous, up
address@hidden electric references
address@hidden Electric References
address@hidden
+
address@hidden ifinfo
+By default, when Supercite cites the original message for the first
+time, it just goes ahead and inserts the reference header indexed by
address@hidden 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.
+
address@hidden sc-electric-references-p
address@hidden electric-references-p (sc-)
+If the variable @code{sc-electric-references-p} is address@hidden,
+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
address@hidden
+
+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):
+
address@hidden @asis
address@hidden @code{sc-eref-next} (@kbd{n})
address@hidden sc-eref-next
address@hidden eref-next (sc-)
address@hidden n
address@hidden sc-electric-circular-p
address@hidden electric-circular-p (sc-)
+Displays the next reference header in the electric reference buffer. If
+the variable @code{sc-electric-circular-p} is address@hidden, invoking
address@hidden while viewing the last reference header in the list
+will wrap around to the first address@hidden
+
address@hidden @code{sc-eref-prev} (@kbd{p})
address@hidden sc-eref-prev
address@hidden eref-prev (sc-)
address@hidden p
+Displays the previous reference header in the electric reference buffer.
+If the variable @code{sc-electric-circular-p} is address@hidden,
+invoking @code{sc-eref-prev} will wrap around to the last address@hidden
+
address@hidden @code{sc-eref-goto} (@kbd{g})
address@hidden sc-eref-goto
address@hidden eref-goto (sc-)
address@hidden g
+Goes to a specified reference header. The index (into the
address@hidden) can be specified as a numeric argument to
+the command. Otherwise, Supercite will query you for the index in the
address@hidden
+
address@hidden @code{sc-eref-jump} (@kbd{j})
address@hidden sc-eref-jump
address@hidden eref-jump (sc-)
address@hidden j
+Display the preferred reference header, i.e., the one indexed by the current
+value of @code{sc-preferred-header-style}.
+
address@hidden @code{sc-eref-setn} (@kbd{s})
address@hidden sc-eref-setn
address@hidden eref-setn (sc-)
address@hidden s
+Set the preferred reference header (i.e.,
address@hidden) to the currently displayed address@hidden
+
address@hidden @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c})
address@hidden RET
address@hidden C-j
address@hidden q
address@hidden sc-eref-exit
address@hidden eref-exit (sc-)
+Exit from electric reference mode and insert the current header into the
+reply address@hidden
+
address@hidden @code{sc-eref-abort} (@kbd{q}, @kbd{x})
address@hidden sc-eref-abort
address@hidden eref-abort (sc-)
address@hidden x
+Exit from electric reference mode without inserting the current header.
address@hidden table
+
address@hidden sc-electric-mode-hook
address@hidden electric-mode-hook (sc-)
address@hidden
+Supercite will execute the hook @code{sc-electric-mode-hook} before
+entering electric reference mode.
+
address@hidden Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top
address@hidden node-name, next, previous, up
address@hidden citation interface specification
address@hidden Getting Connected
address@hidden
+
address@hidden 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
address@hidden value, it tells the MUA to run the hook via
address@hidden instead of using the default address@hidden
+
address@hidden
address@hidden
+* Emacs 19 MUAs::
+* Emacs 18 MUAs::
+* MH-E with any Emacsen::
+* VM with any Emacsen::
+* GNEWS with any Emacsen::
+* Overloading for Non-conforming MUAs::
address@hidden menu
address@hidden 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,
address@hidden to MUA Authors}.
+
address@hidden autoload
address@hidden .emacs file
address@hidden sc-cite-original
address@hidden cite-original (sc-)
address@hidden sc-submit-bug-report
address@hidden 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
address@hidden for Supercite. To do the latter, put the following in
+your @file{.emacs} file:
+
address@hidden
+(autoload 'sc-cite-original "supercite" "Supercite 3.1" t)
+(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
address@hidden example
+
address@hidden point
address@hidden mark
+The function @code{sc-cite-original} is the top-level Supercite function
+designed to be run from the citation hook. It expects
address@hidden 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.
address@hidden to MUA address@hidden
+
+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.
+
address@hidden sc-load-hook
address@hidden load-hook (sc-)
address@hidden sc-pre-hook
address@hidden 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 address@hidden
+
address@hidden Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting
Connected
address@hidden node-name, next, previous, up
address@hidden mail-citation-hook
address@hidden .emacs file
address@hidden GNUS, RMAIL, or RNEWS with any Emacs 19
address@hidden
+
address@hidden ifinfo
+These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
+built-in yanking facility, which provides the citing hook variable
address@hidden 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:
+
address@hidden
+(add-hook 'mail-citation-hook 'sc-cite-original)
address@hidden 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:
+
address@hidden
+(setq news-reply-header-hook nil)
address@hidden example
+
address@hidden Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting
Connected
address@hidden node-name, next, previous, up
address@hidden mail-citation-hook
address@hidden .emacs file
address@hidden overloading
address@hidden sendmail.el file
address@hidden GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
address@hidden
+
address@hidden 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
address@hidden for Non-conforming MUAs}. Then follow the directions
+for using these MUAs under Emacs 19.
address@hidden 19 address@hidden
+
address@hidden add-hook substitute
address@hidden setq as a substitute for add-hook
address@hidden setq
address@hidden add-hook
address@hidden sc-unsupp.el file
+Note that those instructions will tell you to use the function
address@hidden 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{:-)address@hidden
+
+To use @code{setq} instead of @code{add-hook}, you would, for example,
+change this:
+
address@hidden
+(add-hook 'mail-citation-hook 'sc-cite-original)
address@hidden example
+
+to:
+
address@hidden
+(setq mail-citation-hook 'sc-cite-original)
address@hidden example
+
+Note the lack of a single quote on the first argument to @code{setq}.
+
address@hidden MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs,
Getting Connected
address@hidden node-name, next, previous, up
address@hidden .emacs file
address@hidden mh-yank-hooks
address@hidden add-hook
address@hidden mail-citation-hook
address@hidden MH-E with any Emacsen
address@hidden
+
address@hidden 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:
+
address@hidden
+(add-hook 'mail-citation-hook 'sc-cite-original)
address@hidden example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
address@hidden 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:
+
address@hidden
+(add-hook 'mh-yank-hooks 'sc-cite-original)
address@hidden example
+
address@hidden 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
address@hidden 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:
+
address@hidden
+(setq mh-yank-from-start-of-msg t)
address@hidden example
+
+Note that versions of MH-E before 3.7 did not provide the
address@hidden variable. Your only option is to upgrade to MH-E
+version 3.7 or later.
+
address@hidden VM with any Emacsen, GNEWS with any Emacsen, MH-E with any
Emacsen, Getting Connected
address@hidden node-name, next, previous, up
address@hidden .emacs file
address@hidden mail-citation-hook
address@hidden mail-yank-hooks
address@hidden VM with any Emacsen
address@hidden
+
address@hidden 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:
+
address@hidden
+(add-hook 'mail-yank-hooks 'sc-cite-original)
address@hidden example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
address@hidden 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:
+
address@hidden
+(add-hook 'mail-citation-hook 'sc-cite-original)
address@hidden example
+
address@hidden GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM
with any Emacsen, Getting Connected
address@hidden node-name, next, previous, address@hidden .emacs file
address@hidden news-reply-mode-hook
address@hidden sc-perform-overloads
address@hidden perform-overloads (sc-)
address@hidden gnews-ready-hook
address@hidden GNEWS with any Emacsen
address@hidden
+
address@hidden ifinfo
+As far as I know, no version of GNEWS supports the citation interface
+required by Supercite. To connect Supercite with GNEWS, please first
address@hidden 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:
+
address@hidden
+(add-hook 'mail-citation-hook 'sc-cite-original)
address@hidden example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
address@hidden function. @xref{Emacs 18 MUAs}, for details on how to
+proceed without @code{add-hook}.
+
address@hidden Overloading for Non-conforming MUAs, Replying and Yanking,
GNEWS with any Emacsen, Getting Connected
address@hidden node-name, next, previous, up
address@hidden overloading
address@hidden sc-oloads.el
address@hidden mail-citation-hook
address@hidden sc-perform-overloads
address@hidden .emacs file
address@hidden Overloading for Non-conforming MUAs
address@hidden
+
address@hidden 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
address@hidden 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.
address@hidden 19 address@hidden
+
address@hidden Hyperbole
address@hidden 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
address@hidden (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
address@hidden 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
address@hidden
+
+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
address@hidden file, to make sure the @file{sc-oloads.el} file gets
+loaded at the right time:
+
address@hidden
+(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
address@hidden 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:
+
address@hidden
+(setq news-reply-mode-hook 'sc-perform-overloads)
+(setq mail-setup-hook 'sc-perform-overloads)
address@hidden example
+
+If you are using RNEWS, put this in your @file{.emacs} file:
+
address@hidden news-reply-mode-hook
address@hidden
+(setq news-reply-mode-hook 'sc-perform-overloads)
address@hidden example
+
+If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
+
address@hidden
+(setq mail-setup-hook 'sc-perform-overloads)
address@hidden example
+
+If you are using GNEWS, put this in your @file{.emacs} file:
+
address@hidden
+(setq news-reply-mode-hook 'sc-perform-overloads)
+(setq gnews-ready-hook 'sc-perform-overloads)
address@hidden 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} address@hidden
+
address@hidden Replying and Yanking, Reply Buffer Initialization, Overloading
for Non-conforming MUAs, Top
address@hidden node-name, next, previous, up
address@hidden Replying and Yanking
address@hidden
+
+This chapter explains what happens when you reply and yank an original
+message from an MUA.
+
address@hidden
+* Reply Buffer Initialization::
+* Filling Cited Text::
address@hidden menu
address@hidden ifinfo
address@hidden Reply Buffer Initialization, Filling Cited Text, Replying and
Yanking, Replying and Yanking
address@hidden node-name, next, previous, up
address@hidden sc-cite-original
address@hidden cite-original (sc-)
address@hidden
address@hidden Reply Buffer Initialization
address@hidden
+
address@hidden ifinfo
+Executing @code{sc-cite-original} performs the following steps as it
+initializes the reply buffer:
+
address@hidden
address@hidden
address@hidden sc-pre-hook
address@hidden pre-hook (sc-)
address@hidden @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)address@hidden
+
address@hidden
address@hidden Supercite's keymap.}
address@hidden sc-mode-map-prefix
address@hidden mode-map-prefix (sc-)
address@hidden C-c C-p
address@hidden 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.
+
address@hidden
address@hidden on Supercite minor mode.}
address@hidden modeline
+The modeline of the reply buffer should indicate that Supercite is
+active in that buffer by displaying the string @samp{SC}.
+
address@hidden
address@hidden the ``Undo Boundary.''}
address@hidden 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.
+
address@hidden
address@hidden the mail headers.}
address@hidden sc-confirm-always-p
address@hidden confirm-always-p (sc-)
address@hidden sc-mail-warn-if-non-rfc822-p
address@hidden 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
address@hidden, 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.
+
address@hidden sc-nuke-mail-headers
address@hidden sc-nuke-mail-header-list
address@hidden nuke-mail-headers (sc-)
address@hidden 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
address@hidden 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
address@hidden'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
address@hidden'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.
+
address@hidden sc-blank-lines-after-headers
address@hidden blank-lines-after-headers (sc-)
+If the variable @code{sc-blank-lines-after-headers} is address@hidden,
+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.
+
address@hidden
address@hidden 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.
+
address@hidden
address@hidden the message body.}
address@hidden sc-cite-region-limit
address@hidden 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 address@hidden 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.
+
address@hidden sc-cite-blank-lines-p
address@hidden 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
address@hidden, 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.
address@hidden the Citation Engine}, for address@hidden
+
address@hidden
address@hidden @code{sc-post-hook}.}
address@hidden sc-post-hook
address@hidden 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 @address@hidden
address@hidden enumerate
+
address@hidden Filling Cited Text, Selecting an Attribution, Reply Buffer
Initialization, Replying and Yanking
address@hidden node-name, next, previous, up
address@hidden filling paragraphs
address@hidden sc-auto-fill-region-p
address@hidden auto-fill-region-p (sc-)
address@hidden filladapt
address@hidden gin-mode
address@hidden sc-setup-filladapt
address@hidden setup-filladapt (sc-)
address@hidden sc-load-hook
address@hidden load-hook (sc-)
address@hidden Filling Cited Text
address@hidden
+
address@hidden ifinfo
+Supercite will automatically fill newly cited text from the original
+message unless the variable @code{sc-auto-fill-region-p} has a
address@hidden 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
address@hidden, you may want to run the function
address@hidden from your @code{sc-load-hook}. This simply
+makes @dfn{filladapt} a little more Supercite savvy than its default
+setup.
+
address@hidden sc-fixup-whitespace-p
address@hidden fixup-whitespace-p (sc-)
+Also, Supercite will collapse leading whitespace between the citation
+string and the text on a line when the variable
address@hidden is address@hidden The default value for
+this variable is @address@hidden
+
address@hidden 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
address@hidden) 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 address@hidden
+
address@hidden 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
address@hidden C-p C-p} (with the default value of @code{sc-mode-map-prefix};
address@hidden Formatting Commands})address@hidden
+
+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
address@hidden When just @code{sc-auto-fill-region-p} is address@hidden, the
+string will display @samp{SC:f}, and when just
address@hidden is address@hidden, the string will display
address@hidden:w}. When both variables are address@hidden, 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.
address@hidden Toggling address@hidden
+
+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.
+
address@hidden Selecting an Attribution, Attribution Preferences, Filling
Cited Text, Top
address@hidden node-name, next, previous, up
address@hidden attribution list
address@hidden sc-preferred-attribution-list
address@hidden preferred-attribution-list (sc-)
address@hidden
address@hidden Selecting an Attribution
address@hidden
+
address@hidden 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
address@hidden 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.
+
address@hidden
address@hidden
+* Attribution Preferences::
+* Anonymous Attributions::
+* Author Names::
address@hidden menu
address@hidden ifinfo
+
address@hidden Attribution Preferences, Anonymous Attributions, Selecting an
Attribution, Selecting an Attribution
address@hidden node-name, next, previous, up
address@hidden Attribution Preferences
address@hidden
+
address@hidden 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 address@hidden, non-empty
+string match is used as the attribution string, and if no keys match, a
+secondary mechanism is used to generate the attribution.
address@hidden Attributions}.
+
+The following preferences are always available in the attribution alist
+(barring error):
+
address@hidden @code
address@hidden "emailname"
+the author's email terminus.
+
address@hidden "initials"
+the author's initials.
+
address@hidden "firstname"
+the author's first name.
+
address@hidden "lastname"
+the author's last name.
+
address@hidden "middlename-1"
+the author's first middle name.
+
address@hidden "sc-lastchoice"
+the last attribution string you have selected. This is useful when you
+recite paragraphs in the address@hidden
+
address@hidden "sc-consult"
address@hidden sc-attrib-selection-list
address@hidden 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.
+
address@hidden "x-attribution"
+the original author's suggestion for attribution string choice. See below
+for address@hidden
address@hidden 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,
address@hidden:}, 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
address@hidden"x-attribution"} always be first, or possible second behind only
address@hidden"sc-lastchoice"}. This latter is the default.
+
address@hidden sc-attrib-selection-list
address@hidden 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:
+
address@hidden
address@hidden
+(@var{infokey} ((@var{regexp} @. @var{attribution})
+ (@var{regexp} @. @var{attribution})
+ (@dots{})))
address@hidden group
address@hidden example
+
address@hidden
address@hidden sc-mail-field
address@hidden 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
address@hidden 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.
+
address@hidden Anonymous Attributions, Author Names, Attribution Preferences,
Selecting an Attribution
address@hidden node-name, next, previous, up
address@hidden sc-default-author-name
address@hidden default-author-name (sc-)
address@hidden sc-default-attribution
address@hidden default-attribution (sc-)
address@hidden
address@hidden Anonymous Attributions
address@hidden
+
address@hidden 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
address@hidden 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.
+
address@hidden sc-use-only-preference-p
address@hidden use-only-preference-p (sc-)
+Also, if the preferred attribution, which you specified in your
address@hidden 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 address@hidden, then
address@hidden 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 address@hidden,
+non-empty string becomes the attribution:@refill
+
address@hidden
address@hidden
+Use the last selected attribution, if there is one.
+
address@hidden
+Use the value of the @code{"x-attribution"} key.
+
address@hidden
+Use the author's first name.
+
address@hidden
+Use the author's last name.
+
address@hidden
+Use the author's initials.
+
address@hidden
+Find the first address@hidden, non-empty attribution string in the
+attribution alist.
+
address@hidden
address@hidden is used.
address@hidden enumerate
+
address@hidden sc-confirm-always-p
address@hidden 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
address@hidden, 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.
+
address@hidden sc-downcase-p
address@hidden 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
address@hidden
+
address@hidden sc-attribs-preselect-hook
address@hidden attribs-preselect-hook (sc-)
address@hidden sc-attribs-postselect-hook
address@hidden 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
address@hidden 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
address@hidden 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 address@hidden
+
address@hidden Author Names, Configuring the Citation Engine, Anonymous
Attributions, Selecting an Attribution
address@hidden node-name, next, previous, up
address@hidden author names
address@hidden Author Names
address@hidden
+
address@hidden 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.
address@hidden Supercite Mailing address@hidden
+
address@hidden sc-titlecue-regexp
address@hidden 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:
+
address@hidden
+From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
address@hidden 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.
+
address@hidden sc-name-filter-alist
address@hidden 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:
+
address@hidden
+(@var{regexp} @. @var{position})
address@hidden example
+
address@hidden
+where @var{regexp} is a regular expression that is matched (using
address@hidden) 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,
address@hidden would have an entry such as:
+
address@hidden
+("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
address@hidden example
+
address@hidden
+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
address@hidden 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.
+
address@hidden Configuring the Citation Engine, Using Regi, Author Names, Top
address@hidden node-name, next, previous, up
address@hidden Regi
address@hidden frames (Regi)
address@hidden entries (Regi)
address@hidden Configuring the Citation Engine
address@hidden
+
address@hidden 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.
+
address@hidden
address@hidden
+* Using Regi::
+* Frames You Can Customize::
address@hidden menu
address@hidden 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
address@hidden|} or @address@hidden 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!
+
address@hidden Using Regi, Frames You Can Customize, Configuring the Citation
Engine, Configuring the Citation Engine
address@hidden node-name, next, previous, up
address@hidden regi-interpret
address@hidden eval
address@hidden looking-at
address@hidden Using Regi
address@hidden
+
address@hidden ifinfo
+Regi works by interpreting frames with the function
address@hidden A frame is a list of arbitrary size where each
+element is a entry of the following form:
+
address@hidden
+(@var{pred} @var{func} address@hidden address@hidden)
address@hidden 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
address@hidden is address@hidden), then the @var{func} for that entry is
address@hidden 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.
+
address@hidden can be a string, a variable, a list or one of the following
+symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If
address@hidden 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
address@hidden This match folds case if the optional
address@hidden is address@hidden 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 address@hidden)address@hidden
+
+The four special symbol values for @var{pred} are recognized:
+
address@hidden @code
address@hidden t
+Always produces a true outcome.
address@hidden begin
+Always executed before the frame is interpreted. This can be used to
+initialize some global variables for example.
address@hidden end
+Always executed after frame interpreting is completed. This can be used
+to perform any necessary post-processing.
address@hidden every
+Executes whenever the frame is reset, usually after the entire frame has
+been matched against the current line.
address@hidden table
+
+Note that @var{negate-p} and @var{case-fold-search} are ignored if
address@hidden 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
+
address@hidden @asis
address@hidden 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.
+
address@hidden the symbol @code{abort}
+This tells Regi to terminate frame processing. However, any @code{end}
+entry is still processed.
+
address@hidden 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 address@hidden
+
address@hidden 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 address@hidden
address@hidden table
+
+During execution of your @var{func}, the following variables will be
+temporarily bound to some useful information:@refill
+
address@hidden @code
address@hidden curline
+The current line in the buffer that Regi is @code{looking-at}, as a string.
address@hidden curframe
+The current frame being interpreted.
address@hidden curentry
+The current frame entry being interpreted.
address@hidden table
+
address@hidden Frames You Can Customize, Post-yank Formatting Commands, Using
Regi, Configuring the Citation Engine
address@hidden node-name, next, previous, up
address@hidden sc-nuke-mail-header
address@hidden Frames You Can Customize
address@hidden
+
address@hidden 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.
+
address@hidden 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
address@hidden 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.
+
address@hidden unciting
address@hidden reciting
address@hidden sc-default-uncite-frame
address@hidden sc-default-recite-frame
+In a similar vein, there are default frames for @dfn{unciting} and
address@hidden, contained in the variables
address@hidden and @code{sc-default-recite-frame}
address@hidden
+
+As mentioned earlier (@pxref{Recognizing Citations}), citations are
+recognized through the values of the regular expressions
address@hidden, 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.
+
address@hidden sc-cite-frame-alist
address@hidden sc-uncite-frame-alist
address@hidden 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},
address@hidden, and @code{sc-recite-frame-alist}
+respectively). These frames can contain alists of the form:
+
address@hidden
+((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame})
@dots{})
+ (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame})
@dots{})
+ (@dots{}))
address@hidden example
+
address@hidden sc-mail-field
address@hidden string-match
+Where @var{infokey} is a key suitable for @code{sc-mail-field},
address@hidden 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 address@hidden
+
+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.
+
address@hidden Post-yank Formatting Commands, Citing Commands, Frames You Can
Customize, Top
address@hidden node-name, next, previous, up
address@hidden sc-mode-map-prefix
address@hidden mode-map-prefix (sc-)
address@hidden C-c C-p
address@hidden Post-yank Formatting Commands
address@hidden
+
address@hidden ifinfo
+Once the original message has been yanked into the reply buffer, and
address@hidden 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
address@hidden 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
address@hidden
+
address@hidden
address@hidden
+* Citing Commands::
+* Insertion Commands::
+* Variable Toggling Shortcuts::
+* Mail Field Commands::
+* Miscellaneous Commands::
address@hidden menu
address@hidden ifinfo
+
address@hidden Citing Commands, Insertion Commands, Post-yank Formatting
Commands, Post-yank Formatting Commands
address@hidden node-name, next, previous, up
address@hidden sc-cite-region-limit
address@hidden Commands to Manually Cite, Recite, and Uncite
address@hidden
+
address@hidden 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
address@hidden to @code{nil}. The following commands
+perform these functions on the region of text between @samp{point} and
address@hidden Each of them sets the @dfn{undo boundary} before modifying
+the region so that the command can be undone in the standard Emacs
address@hidden
+
+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
address@hidden 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:
+
address@hidden @asis
address@hidden sc-cite-region
address@hidden cite-region (sc-)
address@hidden C-c C-p c
address@hidden sc-pre-cite-hook
address@hidden pre-cite-hook (sc-)
address@hidden sc-confirm-always-p
address@hidden confirm-always-p
address@hidden C-u
address@hidden @code{sc-cite-region} (@kbd{C-c C-p c})
address@hidden
+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
address@hidden before interpreting the frame. With an optional
+universal argument (@kbd{C-u}), it temporarily sets
address@hidden to @code{t} so you can confirm the
+attribution string for a single manual citing.
address@hidden the Citation address@hidden
+
address@hidden sc-uncite-region
address@hidden uncite-region (sc-)
address@hidden C-c C-p u
address@hidden @code{sc-uncite-region} (@kbd{C-c C-p u})
address@hidden
+This command removes any citation strings from the beginning of each
+cited line in the region by interpreting the selected frame from
address@hidden, or the default unciting frame
address@hidden It runs the hook
address@hidden before interpreting the frame.
address@hidden the Citation address@hidden
+
address@hidden sc-recite-region
address@hidden recite-region (sc-)
address@hidden C-c C-p r
address@hidden @code{sc-recite-region} (@kbd{C-c C-p r})
address@hidden
+This command recites each line the region by interpreting the selected
+frame from @code{sc-recite-frame-alist}, or the default reciting frame
address@hidden It runs the hook
address@hidden before interpreting the frame.
address@hidden the Citation address@hidden
+
address@hidden sc-confirm-always-p
address@hidden 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}.
address@hidden table
+
address@hidden Insertion Commands, Variable Toggling Shortcuts, Citing
Commands, Post-yank Formatting Commands
address@hidden node-name, next, previous, up
address@hidden Insertion Commands
address@hidden
+
address@hidden ifinfo
+These two functions insert various strings into the reply buffer.
+
address@hidden @asis
address@hidden sc-insert-reference
address@hidden insert-reference (sc-)
address@hidden C-c C-p w
address@hidden @code{sc-insert-reference} (@kbd{C-c C-p w})
address@hidden
address@hidden sc-preferred-header-style
address@hidden 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
address@hidden indicating which reference header to
address@hidden
+
+With just the universal argument (@kbd{C-u}), electric reference mode is
+entered, regardless of the value of @code{sc-electric-references-p}.
+
address@hidden sc-insert-citation
address@hidden insert-citation (sc-)
address@hidden C-c C-p i
address@hidden @code{sc-insert-citation} (@kbd{C-c C-p i})
address@hidden
+Inserts the current citation string at the beginning of the line that
address@hidden is on. If the line is already cited, Supercite will issue
+an error and will not cite the line.
address@hidden table
+
address@hidden Variable Toggling Shortcuts, Mail Field Commands, Insertion
Commands, Post-yank Formatting Commands
address@hidden node-name, next, previous, up
address@hidden toggling variables
address@hidden Variable Toggling Shortcuts
address@hidden
+
address@hidden 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.
+
address@hidden 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
address@hidden C-p address@hidden
+
+The following commands toggle the value of certain Supercite variables
+which take only a binary value:
+
address@hidden @kbd
address@hidden C-c C-p C-t b
+Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
+
address@hidden C-c C-p C-t c
+Toggles the variable @code{sc-confirm-always-p}.
+
address@hidden C-c C-p C-t d
+Toggles the variable @code{sc-downcase-p}.
+
address@hidden C-c C-p C-t e
+Toggles the variable @code{sc-electric-references-p}.
+
address@hidden C-c C-p C-t f
+Toggles the variable @code{sc-auto-fill-region-p}.
+
address@hidden C-c C-p C-t o
+Toggles the variable @code{sc-electric-circular-p}.
+
address@hidden C-c C-p C-t s
+Toggles the variable @code{sc-nested-citation-p}.
+
address@hidden C-c C-p C-t u
+Toggles the variable @code{sc-use-only-preferences-p}.
+
address@hidden C-c C-p C-t w
+Toggles the variable @code{sc-fixup-whitespace-p}.
address@hidden table
+
address@hidden set-variable
+The following commands let you set the value of multi-value variables,
+in the same way that Emacs' @code{set-variable} does:
+
address@hidden @kbd
address@hidden C-c C-p C-t a
+Sets the value of the variable @code{sc-preferred-attribution-list}.
+
address@hidden C-c C-p C-t l
+Sets the value of the variable @code{sc-cite-region-limit}.
+
address@hidden C-c C-p C-t n
+Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
+
address@hidden C-c C-p C-t N
+Sets the value of the variable @code{sc-mail-header-nuke-list}.
+
address@hidden C-c C-p C-t p
+Sets the value of the variable @code{sc-preferred-header-style}.
address@hidden table
+
address@hidden C-c C-p C-p
+One special command is provided to toggle both
address@hidden and @code{sc-fixup-whitespace-p} together.
+This is because you typically want to run Supercite with either variable
+as @code{nil} or address@hidden The command to toggle these variables
+together is bound on @kbd{C-c C-p address@hidden
+
+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.
+
+
address@hidden Mail Field Commands, Miscellaneous Commands, Variable Toggling
Shortcuts, Post-yank Formatting Commands
address@hidden node-name, next, previous, up
address@hidden Mail Field Commands
address@hidden
+
address@hidden ifinfo
+These commands allow you to view, modify, add, and delete various bits
+of information from the info alist.
address@hidden Keys and the Info address@hidden
+
address@hidden @asis
address@hidden C-c C-p f
address@hidden sc-mail-field-query
address@hidden mail-field-query (sc-)
address@hidden C-c C-p f
address@hidden @code{sc-mail-field-query} (@kbd{C-c C-p f})
address@hidden
+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.
+
address@hidden sc-mail-process-headers
address@hidden mail-process-headers (sc-)
address@hidden C-c C-p g
address@hidden @code{sc-mail-process-headers} (@kbd{C-c C-p g})
address@hidden
+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 address@hidden
address@hidden table
+
address@hidden Miscellaneous Commands, Information Keys and the Info Alist,
Mail Field Commands, Post-yank Formatting Commands
address@hidden node-name, next, previous, up
address@hidden Miscellaneous Commands
address@hidden
+
address@hidden ifinfo
address@hidden @asis
address@hidden sc-open-line
address@hidden open-line (sc-)
address@hidden open-line
address@hidden C-c C-p o
address@hidden @code{sc-open-line} (@kbd{C-c C-p o})
address@hidden
+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 address@hidden
+
address@hidden sc-describe
address@hidden describe (sc-)
address@hidden C-c C-p ?
address@hidden C-c C-p h
address@hidden @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
address@hidden
+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.
+
address@hidden sc-version
address@hidden version (sc-)
address@hidden C-c C-p v
address@hidden @code{sc-version} (@kbd{C-c C-p v})
address@hidden
+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.
+
address@hidden sc-submit-bug-report
address@hidden submit-bug-report (sc-)
address@hidden C-c C-p C-b
address@hidden @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
address@hidden
+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.
address@hidden table
+
address@hidden Hints to MUA Authors, Version 3 Changes, Electric References,
Top
address@hidden node-name, next, previous, up
address@hidden Hints to MUA Authors
address@hidden
+
address@hidden 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:
+
address@hidden
+ 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. address@hidden
address@hidden example
+
address@hidden mail-citation-hook
address@hidden mail-yank-hooks
address@hidden sendmail.el
address@hidden mail-yank-original
address@hidden 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}.
address@hidden can be provided for backward compatibility, but
address@hidden should always take precedence. Richard
+Stallman (of the FSF) suggests that the MUAs should @code{defvar}
address@hidden 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
address@hidden
+
+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:
+
address@hidden
address@hidden
+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 address@hidden
+
address@hidden
+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
address@hidden 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
address@hidden
+
address@hidden
+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
address@hidden @code{mail-citation-hook} to @code{nil}, and in your
+yanking function, check its value. If it finds
address@hidden 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
address@hidden@refill
address@hidden 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.''
+
address@hidden Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
address@hidden node-name, next, previous, up
address@hidden Version 3 Changes
address@hidden
+
address@hidden ifinfo
address@hidden 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.
+
address@hidden
address@hidden
address@hidden supercite.el file
address@hidden reporter.el file
address@hidden regi.el file
address@hidden sc.el from version 2
address@hidden 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}.
+
address@hidden
address@hidden is gone in version 3.
+
address@hidden
address@hidden sc-attrib-selection-list
address@hidden attrib-selection-list
address@hidden is gone in version 3. The
address@hidden is a more general construct supporting
+the same basic feature.
+
address@hidden
+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.
+
address@hidden
address@hidden 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.
+
address@hidden
+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.
+
address@hidden
address@hidden sc-cite-region-limit
address@hidden cite-region-limit
+The variable @code{sc-all-but-cite-p} has been replaced by
address@hidden
+
address@hidden
+Keymap hacking in the reply buffer has been greatly simplified, with, I
+believe, little reduction in functionality.
+
address@hidden
+Hacking of the reply buffer's docstring has been completely eliminated.
address@hidden enumerate
+
address@hidden Thanks and History, The Supercite Mailing List, Version 3
Changes, Top
address@hidden node-name, next, previous, up
address@hidden Thanks and History
address@hidden
+
address@hidden 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.
+
address@hidden The Supercite Mailing List, GNU Free Documentation License,
Thanks and History, Top
address@hidden node-name, next, previous, up
address@hidden supercite mailing list address
address@hidden mailing list address
address@hidden The Supercite Mailing List
address@hidden
+
address@hidden 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:
+
address@hidden
+supercite-request@@python.org
address@hidden 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):
+
address@hidden
+supercite@@python.org
address@hidden 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
address@hidden:@:} line:
+
address@hidden
+supercite-help@@python.org
address@hidden example
+
address@hidden GNU Free Documentation License, Concept Index, The Supercite
Mailing List, Top
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Concept Index, Command Index, GNU Free Documentation License,
Top
address@hidden node-name, next, previous, up
address@hidden Concept Index
address@hidden cp
+
address@hidden Command Index, Key Index, Concept Index, Top
address@hidden node-name, next, previous, up
address@hidden Command Index
address@hidden
+
address@hidden ifinfo
+Since all supercite commands are prepended with the string
address@hidden'', each appears under its @address@hidden name and
+its @var{command} name.
address@hidden
address@hidden 2
address@hidden iftex
address@hidden fn
+
address@hidden Key Index, Variable Index, Command Index, Top
address@hidden node-name, next, previous, up
address@hidden Key Index
address@hidden ky
+
address@hidden Variable Index, , Key Index, Top
address@hidden node-name, next, previous, up
address@hidden Variable Index
address@hidden
+
address@hidden ifinfo
+Since all supercite variables are prepended with the string
address@hidden'', each appears under its @address@hidden name and
+its @var{variable} name.
address@hidden
address@hidden 2
address@hidden iftex
address@hidden vr
address@hidden odd
address@hidden
address@hidden
address@hidden
+
address@hidden
+ arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436
address@hidden ignore