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