aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGlenn Morris2008-02-27 04:42:33 +0000
committerGlenn Morris2008-02-27 04:42:33 +0000
commit52151df0ac7a4b0c900df93f4711cc72bbf6d737 (patch)
treed6ee0f37e3174722a8acc05218b62f07f3176ab2
parent34b5f6df51ef655c4719ce2f0bf57440b21a7c66 (diff)
downloademacs-52151df0ac7a4b0c900df93f4711cc72bbf6d737.tar.gz
emacs-52151df0ac7a4b0c900df93f4711cc72bbf6d737.zip
Remove a lot of old and obsolete info.
(titlepage): Simplify. (Emacs 19 MUAs, Emacs 18 MUAs, MH-E with any Emacsen) (VM with any Emacsen, GNEWS with any Emacsen) (Overloading for Non-conforming MUAs, Version 3 Changes) (The Supercite Mailing List): Delete nodes. (Introduction): Remove info about old packages. (Getting Connected): Simplify. Remove info about old packages. (Citing Commands): Delete Emacs 19 info. (Hints to MUA Authors): Simplify. (Thanks and History): Merge in some info from the deleted node "Version 3 Changes".
-rw-r--r--doc/misc/ChangeLog15
-rw-r--r--doc/misc/sc.texi716
2 files changed, 82 insertions, 649 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index b611cb324c9..e9f3ada1c02 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,18 @@
12008-02-27 Glenn Morris <rgm@gnu.org>
2
3 * sc.texi: Remove a lot of old and obsolete info.
4 (titlepage): Simplify.
5 (Emacs 19 MUAs, Emacs 18 MUAs, MH-E with any Emacsen)
6 (VM with any Emacsen, GNEWS with any Emacsen)
7 (Overloading for Non-conforming MUAs, Version 3 Changes)
8 (The Supercite Mailing List): Delete nodes.
9 (Introduction): Remove info about old packages.
10 (Getting Connected): Simplify. Remove info about old packages.
11 (Citing Commands): Delete Emacs 19 info.
12 (Hints to MUA Authors): Simplify.
13 (Thanks and History): Merge in some info from the deleted node
14 "Version 3 Changes".
15
12008-02-05 Juanma Barranquero <lekktu@gmail.com> 162008-02-05 Juanma Barranquero <lekktu@gmail.com>
2 17
3 * org.texi (Setting tags, In-buffer settings): 18 * org.texi (Setting tags, In-buffer settings):
diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi
index f98b63b628e..e23e9e4ea58 100644
--- a/doc/misc/sc.texi
+++ b/doc/misc/sc.texi
@@ -2,7 +2,7 @@
2@comment 3.48 2@comment 3.48
3@comment %**start of header (This is for running Texinfo on a region.) 3@comment %**start of header (This is for running Texinfo on a region.)
4@setfilename ../../info/sc 4@setfilename ../../info/sc
5@settitle Supercite Version 3.1 User's Manual 5@settitle Supercite User's Manual
6@iftex 6@iftex
7@finalout 7@finalout
8@end iftex 8@end iftex
@@ -11,9 +11,8 @@
11@comment %**end of header (This is for running Texinfo on a region.) 11@comment %**end of header (This is for running Texinfo on a region.)
12 12
13@copying 13@copying
14This document describes the Supercite Version 3.1 package for citing and 14This document describes Supercite, an Emacs package for citing and
15attributing the replies for various GNU Emacs mail and news reading 15attributing replies to mail and news messages.
16subsystems.
17 16
18Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 17Copyright @copyright{} 1993, 2001, 2002, 2003, 2004,
192005, 2006, 2007, 2008 Free Software Foundation, Inc. 182005, 2006, 2007, 2008 Free Software Foundation, Inc.
@@ -47,17 +46,10 @@ license to the document, as described in section 6 of the license.
47@end direntry 46@end direntry
48 47
49@titlepage 48@titlepage
50@sp 6 49@title Supercite User's Manual
51@center @titlefont{Supercite User's Manual} 50@subtitle cite and attribute mail and
52@sp 2 51@subtitle news, in flexible ways
53@center @titlefont{Supercite Version 3.1} 52
54@sp 4
55@center Manual Revision: 3.48
56@center April 2007
57@sp 5
58@center Barry A@. Warsaw
59@center @t{bwarsaw@@cen.com}
60@center @t{@dots{}!uunet!cen.com!bwarsaw}
61@page 53@page
62@vskip 0pt plus 1filll 54@vskip 0pt plus 1filll
63@insertcopying 55@insertcopying
@@ -67,9 +59,9 @@ license to the document, as described in section 6 of the license.
67@node Top, Introduction, (dir), (dir) 59@node Top, Introduction, (dir), (dir)
68@comment node-name, next, previous, up 60@comment node-name, next, previous, up
69 61
70This document describes the Supercite Version 3.1 package for citing and 62This document describes Supercite, an Emacs package for citing and
71attributing the replies for various GNU Emacs mail and news reading 63attributing replies to mail and news messages. The manual is divided
72subsystems. The manual is divided into the following chapters. 64into the following chapters.
73 65
74@menu 66@menu
75* Introduction:: 67* Introduction::
@@ -82,9 +74,7 @@ subsystems. The manual is divided into the following chapters.
82* Information Keys and the Info Alist:: 74* Information Keys and the Info Alist::
83* Reference Headers:: 75* Reference Headers::
84* Hints to MUA Authors:: 76* Hints to MUA Authors::
85* Version 3 Changes::
86* Thanks and History:: 77* Thanks and History::
87* The Supercite Mailing List::
88 78
89* GNU Free Documentation License:: 79* GNU Free Documentation License::
90* Concept Index:: 80* Concept Index::
@@ -96,22 +86,17 @@ subsystems. The manual is divided into the following chapters.
96 86
97 87
98@node Introduction, Usage Overview, Top, Top 88@node Introduction, Usage Overview, Top, Top
99@comment node-name, next, previous, up
100@chapter Introduction 89@chapter Introduction
101@ifinfo
102 90
103@end ifinfo 91Supercite is a GNU Emacs package written entirely in Emacs Lisp. It
104Supercite version 3.1 is a GNU Emacs package written entirely in Emacs 92interfaces to most of the commonly used Emacs mail user agents
105Lisp. It interfaces to most of the commonly used Emacs mail user agents
106(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides 93(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
107sophisticated facilities for the citing and attributing of message 94sophisticated facilities for the citing and attributing of message
108replies. Supercite has a very specific and limited role in the process 95replies. Supercite has a very specific and limited role in the process
109of composing replies to both USENET network news and electronic mail. 96of composing replies to both USENET network news and electronic mail.
110 97
111The preferred way to spell Supercite is with a capital @samp{S}, 98The preferred way to spell Supercite is with a capital @samp{S},
112lowercase @samp{upercite}. There are a few alternate spellings out there 99lowercase @samp{upercite}.
113and I won't be terribly offended if you use them. People often ask
114though@dots{}
115 100
116@ifinfo 101@ifinfo
117@menu 102@menu
@@ -124,49 +109,21 @@ though@dots{}
124@cindex MUA 109@cindex MUA
125@cindex NUA 110@cindex NUA
126Supercite is only useful in conjunction with MUAs and NUAs such as VM, 111Supercite is only useful in conjunction with MUAs and NUAs such as VM,
127GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs). 112Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a
128Supercite is typically called by the MUA after a reply buffer has been 113reply buffer has been setup. Thereafter, Supercite's many commands and
129setup. Thereafter, Supercite's many commands and formatting styles are 114formatting styles are available in that reply buffer until the reply is
130available in that reply buffer until the reply is sent. Supercite is 115sent. Supercite is re-initialized in each new reply buffer.
131re-initialized in each new reply buffer.
132
133Supercite is currently at major revision 3.1, and is known to work in the
134following environments:
135
136@table @asis
137@item Emacs versions:
138 GNU Emacs 18.57 through 18.59, all Emacs 19,
139 all current Lucid Emacs, and Epoch 4.@refill
140
141@item MUAs:
142 VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
143 beyond, PCMAIL.@refill
144
145@item NUAs:
146 RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
147
148@end table
149For systems with version numbers, all known subsequent versions also
150work with Supercite. For those systems without version numbers,
151Supercite probably works with any recently released version. Note that
152only some of these systems will work with Supercite ``out of the box.''
153All others must overload interfacing routines to supply the necessary
154glue. @xref{Getting Connected}, for more details.@refill
155 116
156 117
157@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction 118@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
158@comment node-name, next, previous, up
159@kindex r 119@kindex r
160@kindex f 120@kindex f
161@kindex C-c C-y 121@kindex C-c C-y
162@cindex yank 122@cindex yank
163@cindex cite, citing 123@cindex cite, citing
164@cindex attribute, attributing 124@cindex attribute, attributing
165@comment
166@section Usage Overview 125@section Usage Overview
167@ifinfo
168 126
169@end ifinfo
170Typical usage is as follows. You want to reply or followup to a message 127Typical usage is as follows. You want to reply or followup to a message
171in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} 128in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
172(i.e., ``forward'') to begin composing the reply. In response, the MUA 129(i.e., ``forward'') to begin composing the reply. In response, the MUA
@@ -184,11 +141,8 @@ using Supercite you gain a wider flexibility in the look and style of
184citations. Supercite's only job is to cite the original message. 141citations. Supercite's only job is to cite the original message.
185 142
186@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction 143@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
187@comment node-name, next, previous, up
188@section What Supercite Doesn't Do 144@section What Supercite Doesn't Do
189@ifinfo
190 145
191@end ifinfo
192Because of this clear division of labor, there are useful features which 146Because of this clear division of labor, there are useful features which
193are the sole responsibility of the MUA, even though it might seem that 147are the sole responsibility of the MUA, even though it might seem that
194Supercite should provide them. For example, many people would like to 148Supercite should provide them. For example, many people would like to
@@ -198,7 +152,6 @@ set up by the MUA, it is the MUA's responsibility to do partial yanking.
198@xref{Reply Buffer Initialization}.@refill 152@xref{Reply Buffer Initialization}.@refill
199 153
200@vindex mail-header-separator 154@vindex mail-header-separator
201@comment
202Another potentially useful thing would be for Supercite to set up the 155Another potentially useful thing would be for Supercite to set up the
203outgoing mail headers with information it gleans from the reply buffer. 156outgoing mail headers with information it gleans from the reply buffer.
204But by previously agreed upon convention, any text above the 157But by previously agreed upon convention, any text above the
@@ -209,12 +162,9 @@ outside the designated region. @xref{Hints to MUA Authors}, for more
209details.@refill 162details.@refill
210 163
211@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction 164@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction
212@comment node-name, next, previous, up
213@findex sc-cite-original 165@findex sc-cite-original
214@section What Supercite Does 166@section What Supercite Does
215@ifinfo
216 167
217@end ifinfo
218Supercite is invoked for the first time on a reply buffer via your MUA's 168Supercite is invoked for the first time on a reply buffer via your MUA's
219reply or forward command. This command will actually perform citations 169reply or forward command. This command will actually perform citations
220by calling a hook variable to which Supercite's top-level function 170by calling a hook variable to which Supercite's top-level function
@@ -252,7 +202,6 @@ display the minor mode string @samp{SC}.
252@cindex gin-mode 202@cindex gin-mode
253@vindex fill-prefix 203@vindex fill-prefix
254@findex fill-paragraph 204@findex fill-paragraph
255@comment
256When the original message is cited by @code{sc-cite-original}, it will 205When the original message is cited by @code{sc-cite-original}, it will
257(optionally) be filled by Supercite. However, if you manually edit the 206(optionally) be filled by Supercite. However, if you manually edit the
258cited text and want to re-fill it, you must use an add-on package such 207cited text and want to re-fill it, you must use an add-on package such
@@ -273,14 +222,10 @@ it has been properly connected to your MUA. @xref{Getting Connected},
273for more details.@refill 222for more details.@refill
274 223
275@node Citations, Citation Elements, What Supercite Does, Top 224@node Citations, Citation Elements, What Supercite Does, Top
276@comment node-name, next, previous, up
277@cindex nested citations 225@cindex nested citations
278@cindex citation 226@cindex citation
279@comment
280@chapter Citations 227@chapter Citations
281@ifinfo
282 228
283@end ifinfo
284A @dfn{citation} is the acknowledgement of the original author of a mail 229A @dfn{citation} is the acknowledgement of the original author of a mail
285message in the body of the reply. There are two basic citation styles 230message in the body of the reply. There are two basic citation styles
286which Supercite supports. The first, called @dfn{nested citations} is 231which Supercite supports. The first, called @dfn{nested citations} is
@@ -342,13 +287,9 @@ are used.
342 287
343 288
344@node Citation Elements, Recognizing Citations, Citations, Citations 289@node Citation Elements, Recognizing Citations, Citations, Citations
345@comment node-name, next, previous, up
346@cindex citation string 290@cindex citation string
347@comment
348@section Citation Elements 291@section Citation Elements
349@ifinfo
350 292
351@end ifinfo
352@dfn{Citation strings} are composed of one or more elements. Non-nested 293@dfn{Citation strings} are composed of one or more elements. Non-nested
353citations are composed of four elements, three of which are directly 294citations are composed of four elements, three of which are directly
354user definable. The elements are concatenated together, in this order: 295user definable. The elements are concatenated together, in this order:
@@ -401,11 +342,8 @@ enough to not put additional spaces between citation delimiters for
401multi-level nested citations. 342multi-level nested citations.
402 343
403@node Recognizing Citations, Getting Connected, Citation Elements, Citations 344@node Recognizing Citations, Getting Connected, Citation Elements, Citations
404@comment node-name, next, previous, up
405@section Recognizing Citations 345@section Recognizing Citations
406@ifinfo
407 346
408@end ifinfo
409Supercite also recognizes citations in the original article, and can 347Supercite also recognizes citations in the original article, and can
410transform these already cited lines in a number of ways. This is how 348transform these already cited lines in a number of ways. This is how
411Supercite suppresses the multiple citing of non-nested citations. 349Supercite suppresses the multiple citing of non-nested citations.
@@ -448,17 +386,13 @@ change @code{sc-citation-root-regexp} you should always also change
448@code{sc-citation-nonnested-root-regexp}.@refill 386@code{sc-citation-nonnested-root-regexp}.@refill
449 387
450@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top 388@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
451@comment node-name, next, previous, up
452@cindex information keys 389@cindex information keys
453@cindex Info Alist 390@cindex Info Alist
454@cindex information extracted from mail fields 391@cindex information extracted from mail fields
455@findex sc-mail-field 392@findex sc-mail-field
456@findex mail-field (sc-) 393@findex mail-field (sc-)
457@comment
458@chapter Information Keys and the Info Alist 394@chapter Information Keys and the Info Alist
459@ifinfo
460 395
461@end ifinfo
462@dfn{Mail header information keys} are nuggets of information that 396@dfn{Mail header information keys} are nuggets of information that
463Supercite extracts from the various mail headers of the original 397Supercite extracts from the various mail headers of the original
464message, placed in the reply buffer by the MUA. Information is kept in 398message, placed in the reply buffer by the MUA. Information is kept in
@@ -562,12 +496,9 @@ info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
562@dots{}). @xref{Selecting an Attribution}.@refill 496@dots{}). @xref{Selecting an Attribution}.@refill
563 497
564@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top 498@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
565@comment node-name, next, previous, up
566@cindex reference headers 499@cindex reference headers
567@chapter Reference Headers 500@chapter Reference Headers
568@ifinfo
569 501
570@end ifinfo
571Supercite will insert an informative @dfn{reference header} at the 502Supercite will insert an informative @dfn{reference header} at the
572beginning of the cited body of text, which display more detail about the 503beginning of the cited body of text, which display more detail about the
573original article and provides the mapping between the attribution and 504original article and provides the mapping between the attribution and
@@ -606,13 +537,9 @@ integer which is an index into the @code{sc-rewrite-header-list},
606beginning at zero. 537beginning at zero.
607 538
608@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers 539@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
609@comment node-name, next, previous, up
610@cindex header rewrite functions, built-in 540@cindex header rewrite functions, built-in
611@comment
612@section The Built-in Header Rewrite Functions 541@section The Built-in Header Rewrite Functions
613@ifinfo
614 542
615@end ifinfo
616Below are examples of the various built-in header rewrite functions. 543Below are examples of the various built-in header rewrite functions.
617Please note the following:@: first, the text which appears in the 544Please note the following:@: first, the text which appears in the
618examples below as @var{infokey} indicates that the corresponding value 545examples below as @var{infokey} indicates that the corresponding value
@@ -689,12 +616,9 @@ line after the @code{mail-header-separator} line will be removed.
689@end table 616@end table
690 617
691@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers 618@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
692@comment node-name, next, previous, up
693@cindex electric references 619@cindex electric references
694@section Electric References 620@section Electric References
695@ifinfo
696 621
697@end ifinfo
698By default, when Supercite cites the original message for the first 622By default, when Supercite cites the original message for the first
699time, it just goes ahead and inserts the reference header indexed by 623time, it just goes ahead and inserts the reference header indexed by
700@code{sc-preferred-header-style}. However, you may want to select 624@code{sc-preferred-header-style}. However, you may want to select
@@ -787,13 +711,22 @@ Exit from electric reference mode without inserting the current header.
787Supercite will execute the hook @code{sc-electric-mode-hook} before 711Supercite will execute the hook @code{sc-electric-mode-hook} before
788entering electric reference mode. 712entering electric reference mode.
789 713
790@node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top 714@node Getting Connected, Replying and Yanking, Recognizing Citations, Top
791@comment node-name, next, previous, up
792@cindex citation interface specification 715@cindex citation interface specification
793@chapter Getting Connected 716@chapter Getting Connected
794@ifinfo
795 717
796@end ifinfo 718
719@vindex mail-citation-hook
720@cindex .emacs file
721In most cases, all that is necessary to begin using Supercite is to add
722the following to @file{~.emacs}:
723
724@example
725(add-hook 'mail-citation-hook 'sc-cite-original)
726@end example
727
728@noindent For more details of the process, read on@dots{}
729
797Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the 730Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
798original message into the reply buffer. In reality, the citation of the 731original message into the reply buffer. In reality, the citation of the
799original message is performed via a call through a configurable hook 732original message is performed via a call through a configurable hook
@@ -805,27 +738,12 @@ citation function to the hook, thereby giving the variable a
805non-@code{nil} value, it tells the MUA to run the hook via 738non-@code{nil} value, it tells the MUA to run the hook via
806@code{run-hooks} instead of using the default citation.@refill 739@code{run-hooks} instead of using the default citation.@refill
807 740
808@ifinfo
809@menu
810* Emacs 19 MUAs::
811* Emacs 18 MUAs::
812* MH-E with any Emacsen::
813* VM with any Emacsen::
814* GNEWS with any Emacsen::
815* Overloading for Non-conforming MUAs::
816@end menu
817@end ifinfo
818
819Early in Supercite's development, the Supercite author, a few MUA 741Early in Supercite's development, the Supercite author, a few MUA
820authors, and some early Supercite users got together and agreed upon a 742authors, and some early Supercite users got together and agreed upon a
821standard interface between MUAs and citation packages (of which 743standard interface between MUAs and citation packages (of which
822Supercite is currently the only known add-on @t{:-)}. With the recent 744Supercite is currently the only known add-on @t{:-)}. Supercite can
823release of the Free Software Foundation's GNU Emacs 19, the interface 745probably be used with most Emacs MUAs, with a greater or lesser degree
824has undergone some modification and it is possible that not all MUAs 746of effort.
825support the new interface yet. Some support only the old interface and
826some do not support the interface at all. Still, it is possible for all
827known MUAs to use Supercite, and the following sections will outline the
828procedures you need to follow.
829 747
830To learn exactly how to connect Supercite to the software systems you 748To learn exactly how to connect Supercite to the software systems you
831are using, read the appropriate following sections. For details on the 749are using, read the appropriate following sections. For details on the
@@ -840,14 +758,13 @@ interface specifications, or if you are writing or maintaining an MUA,
840@findex submit-bug-report (sc-) 758@findex submit-bug-report (sc-)
841The first thing that everyone should do, regardless of the MUA you are 759The first thing that everyone should do, regardless of the MUA you are
842using is to set up Emacs so it will load Supercite at the appropriate 760using is to set up Emacs so it will load Supercite at the appropriate
843time. You can either dump Supercite into your Emacs binary (ask your 761time. This happens automatically if Supercite is distributed with your
844local Emacs guru how to do this if you don't know), or you can set up an 762Emacs version. If not, you can set up an @dfn{autoload} for Supercite.
845@dfn{autoload} for Supercite. To do the latter, put the following in 763
846your @file{.emacs} file: 764To do the latter, put the following in your @file{.emacs} file:
847 765
848@example 766@example
849(autoload 'sc-cite-original "supercite" "Supercite 3.1" t) 767(autoload 'sc-cite-original "supercite" nil t)
850(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
851@end example 768@end example
852 769
853@cindex point 770@cindex point
@@ -857,7 +774,7 @@ designed to be run from the citation hook. It expects
857@samp{point} and @samp{mark} to be set around the region to cite, and it 774@samp{point} and @samp{mark} to be set around the region to cite, and it
858expects the original article's mail headers to be present within this 775expects the original article's mail headers to be present within this
859region. Note that Supercite @emph{never} touches any text outside this 776region. Note that Supercite @emph{never} touches any text outside this
860region. Note further that for Emacs 19, the region need not be active 777region. Note further that the region need not be active
861for @code{sc-cite-original} to do its job. 778for @code{sc-cite-original} to do its job.
862@xref{Hints to MUA Authors}.@refill 779@xref{Hints to MUA Authors}.@refill
863 780
@@ -878,284 +795,7 @@ In that case, you can use the @code{sc-pre-hook} variable, but this will
878get executed every time @code{sc-cite-original} is called. @xref{Reply 795get executed every time @code{sc-cite-original} is called. @xref{Reply
879Buffer Initialization}.@refill 796Buffer Initialization}.@refill
880 797
881@node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected 798@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top
882@comment node-name, next, previous, up
883@vindex mail-citation-hook
884@cindex .emacs file
885@section GNUS, RMAIL, or RNEWS with any Emacs 19
886@ifinfo
887
888@end ifinfo
889These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
890built-in yanking facility, which provides the citing hook variable
891@code{mail-citation-hook}. By default, this hook's value is @code{nil},
892but by adding the following to your @file{.emacs} file, you can tell
893these MUAs to use Supercite to perform the citing of the original
894message:
895
896@example
897(add-hook 'mail-citation-hook 'sc-cite-original)
898@end example
899
900GNUS users may also want to add the following bit of lisp as well. This
901prevents GNUS from inserting its default attribution header. Otherwise,
902both GNUS and Supercite will insert an attribution header:
903
904@example
905(setq news-reply-header-hook nil)
906@end example
907
908@node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
909@comment node-name, next, previous, up
910@vindex mail-citation-hook
911@cindex .emacs file
912@cindex overloading
913@cindex sendmail.el file
914@section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
915@ifinfo
916
917@end ifinfo
918These MUAs use Emacs' built-in yanking and citing routines, contained in
919the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its
920derivative Epoch 4, do not know anything about the citation interface
921required by Supercite. To connect Supercite to any of these MUAs under
922Emacs 18 or Epoch 4, you should first
923@pxref{Overloading for Non-conforming MUAs}. Then follow the directions
924for using these MUAs under Emacs 19.
925@xref{Emacs 19 MUAs}.@refill
926
927@cindex add-hook substitute
928@cindex setq as a substitute for add-hook
929@findex setq
930@findex add-hook
931@cindex sc-unsupp.el file
932Note that those instructions will tell you to use the function
933@code{add-hook}. This function is new with Emacs 19 and you will not
934have it by default if you are running Emacs 18 or Epoch 4. You can
935either substitute the appropriate call to @code{setq}, or you can use
936the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
937file of unsupported Supercite hacks and ideas. Or you can upgrade to
938some Emacs 19 variant! @t{:-)}@refill
939
940To use @code{setq} instead of @code{add-hook}, you would, for example,
941change this:
942
943@example
944(add-hook 'mail-citation-hook 'sc-cite-original)
945@end example
946
947to:
948
949@example
950(setq mail-citation-hook 'sc-cite-original)
951@end example
952
953Note the lack of a single quote on the first argument to @code{setq}.
954
955@node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
956@comment node-name, next, previous, up
957@cindex .emacs file
958@vindex mh-yank-hooks
959@findex add-hook
960@cindex mail-citation-hook
961@section MH-E with any Emacsen
962@ifinfo
963
964@end ifinfo
965MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
966by other MUAs. At the time of this writing, MH-E 4.0 has not been
967released, but if you have it, put this in your @file{.emacs} file to
968connect Supercite and MH-E 4.x:
969
970@example
971(add-hook 'mail-citation-hook 'sc-cite-original)
972@end example
973
974Note that if you are using Emacs 18 or Epoch 4, you will not have the
975@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
976proceed without @code{add-hook}.
977
978MH-E version 3.x uses a slightly different interface than other MUAs.
979MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
980like a hook, and doing an @code{add-hook} will not work.
981
982To connect Supercite to MH-E 3.x, you should instead add the following
983to your @code{.emacs} file:
984
985@example
986(add-hook 'mh-yank-hooks 'sc-cite-original)
987@end example
988
989@vindex mh-yank-from-start-of-msg
990You also need to make sure that MH-E includes all the original mail
991headers in the yanked message. The variable that controls this is
992@code{mh-yank-from-start-of-msg}. By default, this variable has the
993value @code{t}, which tells MH-E to include all the mail headers when
994yanking the original message. Before you switched to using Supercite,
995you may have set this variable to other values so as not to include the
996mail headers in the yanked message. Since Supercite requires these
997headers (and cleans them out for you), you need to make sure the value
998is @code{t}. This lisp, in your @file{.emacs} file will do the trick:
999
1000@example
1001(setq mh-yank-from-start-of-msg t)
1002@end example
1003
1004Note that versions of MH-E before 3.7 did not provide the
1005@code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E
1006version 3.7 or later.
1007
1008@node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
1009@comment node-name, next, previous, up
1010@cindex .emacs file
1011@vindex mail-citation-hook
1012@vindex mail-yank-hooks
1013@section VM with any Emacsen
1014@ifinfo
1015
1016@end ifinfo
1017Since release 4.40, VM has supported the citation interface required by
1018Supercite. But since the interface has changed recently the details of
1019getting connected differ with the version of VM you are using.
1020
1021If you are running any release of VM after 4.40, you can add the
1022following to your @file{.emacs} to connect Supercite with VM:
1023
1024@example
1025(add-hook 'mail-yank-hooks 'sc-cite-original)
1026@end example
1027
1028Note that if you are using Emacs 18 or Epoch 4, you will not have the
1029@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
1030proceed without @code{add-hook}.
1031
1032Since version 5.34, VM has supported the newer @code{mail-citation-hook}
1033interface, but @code{mail-yank-hooks} is still being supported for
1034backward compatibility. If you are running a newer version of VM and
1035you want to maintain consistency with other MUAs, use this bit of code
1036instead:
1037
1038@example
1039(add-hook 'mail-citation-hook 'sc-cite-original)
1040@end example
1041
1042@node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
1043@comment node-name, next, previous, up@cindex .emacs file
1044@vindex news-reply-mode-hook
1045@findex sc-perform-overloads
1046@findex perform-overloads (sc-)
1047@vindex gnews-ready-hook
1048@section GNEWS with any Emacsen
1049@ifinfo
1050
1051@end ifinfo
1052As far as I know, no version of GNEWS supports the citation interface
1053required by Supercite. To connect Supercite with GNEWS, please first
1054@pxref{Overloading for Non-conforming MUAs}.
1055
1056After you have followed the directions in that section. You should add
1057the following lisp code to your @file{.emacs} file:
1058
1059@example
1060(add-hook 'mail-citation-hook 'sc-cite-original)
1061@end example
1062
1063Note that if you are using Emacs 18 or Epoch 4, you will not have the
1064@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
1065proceed without @code{add-hook}.
1066
1067@node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
1068@comment node-name, next, previous, up
1069@cindex overloading
1070@cindex sc-oloads.el
1071@vindex mail-citation-hook
1072@findex sc-perform-overloads
1073@cindex .emacs file
1074@section Overloading for Non-conforming MUAs
1075@ifinfo
1076
1077@end ifinfo
1078As mentioned elsewhere, some MUAs do not provide the necessary hooks to
1079connect with Supercite. Supercite version 3.1 provides an unsupported
1080mechanism, called @dfn{overloading} which redefines certain key
1081functions in the MUA, so that it will call the @code{mail-citation-hook}
1082variable instead of the MUA's default hard-coded citing routines. Since
1083most newer versions of the known MUAs support the
1084@code{mail-citation-hook} variable, it is recommended that you upgrade
1085if at all possible. But if you can't upgrade, at least you're not out
1086of luck! Once you set up overloading properly, you should follow the
1087directions for connecting Supercite to the Emacs 19 MUAs.
1088@xref{Emacs 19 MUAs}.@refill
1089
1090@cindex Hyperbole
1091@vindex hyperb:version
1092Users of Bob Weiner's Hyperbole package take note. Hyperbole provides
1093the necessary overloads (and a whole lot more!) and you can potentially
1094clobber it if you were to load Supercite's overloading after
1095Hyperbole's. For this reason, Supercite will @emph{not} perform any
1096overloading if it finds the variable @code{hyperb:version} is
1097@code{boundp} (i.e. it exists because Hyperbole has been loaded into
1098your Emacs session). If this is the case, Supercite will display a
1099warning message in the minibuffer. You should consult the Hyperbole
1100manual for further details.
1101
1102Overloading involves the re-definition of the citing function with the
1103new, @code{mail-citation-hook} savvy version. The function in
1104@file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This
1105function is smart enough to only overload the MUA functions when it is
1106absolutely necessary, based on the version numbers it can figure out.
1107Also, @code{sc-perform-overloads} will only install the new functions
1108once. It is also smart enough to do nothing if the MUA is not yet
1109loaded.@refill
1110
1111The tricky part is finding the right time and place to perform the
1112overloading. It must be done after the MUA has been loaded into your
1113Emacs session, but before the first time you try to yank in a message.
1114Fortunately, this has been figured out for you.
1115
1116If you must overload, you should put the following lisp code in your
1117@file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
1118loaded at the right time:
1119
1120@example
1121(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
1122@end example
1123
1124Then you must make sure that the function @code{sc-perform-overloads}
1125gets run at the right time. For GNUS, put this in your @file{.emacs}
1126file:
1127
1128@example
1129(setq news-reply-mode-hook 'sc-perform-overloads)
1130(setq mail-setup-hook 'sc-perform-overloads)
1131@end example
1132
1133If you are using RNEWS, put this in your @file{.emacs} file:
1134
1135@vindex news-reply-mode-hook
1136@example
1137(setq news-reply-mode-hook 'sc-perform-overloads)
1138@end example
1139
1140If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
1141
1142@example
1143(setq mail-setup-hook 'sc-perform-overloads)
1144@end example
1145
1146If you are using GNEWS, put this in your @file{.emacs} file:
1147
1148@example
1149(setq news-reply-mode-hook 'sc-perform-overloads)
1150(setq gnews-ready-hook 'sc-perform-overloads)
1151@end example
1152
1153Now go back and follow the directions for getting the Emacs 19 MUAs
1154connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes
1155for Emacs 19's @code{add-hook} function.@refill
1156
1157@node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
1158@comment node-name, next, previous, up
1159@chapter Replying and Yanking 799@chapter Replying and Yanking
1160@ifinfo 800@ifinfo
1161 801
@@ -1168,14 +808,10 @@ message from an MUA.
1168@end menu 808@end menu
1169@end ifinfo 809@end ifinfo
1170@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking 810@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
1171@comment node-name, next, previous, up
1172@findex sc-cite-original 811@findex sc-cite-original
1173@findex cite-original (sc-) 812@findex cite-original (sc-)
1174@comment
1175@section Reply Buffer Initialization 813@section Reply Buffer Initialization
1176@ifinfo
1177 814
1178@end ifinfo
1179Executing @code{sc-cite-original} performs the following steps as it 815Executing @code{sc-cite-original} performs the following steps as it
1180initializes the reply buffer: 816initializes the reply buffer:
1181 817
@@ -1329,7 +965,6 @@ reset certain variables set in @code{sc-pre-hook}.@refill
1329@end enumerate 965@end enumerate
1330 966
1331@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking 967@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
1332@comment node-name, next, previous, up
1333@cindex filling paragraphs 968@cindex filling paragraphs
1334@vindex sc-auto-fill-region-p 969@vindex sc-auto-fill-region-p
1335@vindex auto-fill-region-p (sc-) 970@vindex auto-fill-region-p (sc-)
@@ -1340,9 +975,7 @@ reset certain variables set in @code{sc-pre-hook}.@refill
1340@vindex sc-load-hook 975@vindex sc-load-hook
1341@vindex load-hook (sc-) 976@vindex load-hook (sc-)
1342@section Filling Cited Text 977@section Filling Cited Text
1343@ifinfo
1344 978
1345@end ifinfo
1346Supercite will automatically fill newly cited text from the original 979Supercite will automatically fill newly cited text from the original
1347message unless the variable @code{sc-auto-fill-region-p} has a 980message unless the variable @code{sc-auto-fill-region-p} has a
1348@code{nil} value. Supercite will also re-fill paragraphs when you 981@code{nil} value. Supercite will also re-fill paragraphs when you
@@ -1411,15 +1044,11 @@ containing lines greater than about 72 characters. So the default is to
1411fill cited text. 1044fill cited text.
1412 1045
1413@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top 1046@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
1414@comment node-name, next, previous, up
1415@cindex attribution list 1047@cindex attribution list
1416@vindex sc-preferred-attribution-list 1048@vindex sc-preferred-attribution-list
1417@vindex preferred-attribution-list (sc-) 1049@vindex preferred-attribution-list (sc-)
1418@comment
1419@chapter Selecting an Attribution 1050@chapter Selecting an Attribution
1420@ifinfo
1421 1051
1422@end ifinfo
1423As you know, the attribution string is the part of the author's name 1052As you know, the attribution string is the part of the author's name
1424that will be used to composed a non-nested citation string. Supercite 1053that will be used to composed a non-nested citation string. Supercite
1425scans the various mail headers present in the original article and uses 1054scans the various mail headers present in the original article and uses
@@ -1439,11 +1068,8 @@ author's initials, and the author's email terminus.
1439@end ifinfo 1068@end ifinfo
1440 1069
1441@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution 1070@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
1442@comment node-name, next, previous, up
1443@section Attribution Preferences 1071@section Attribution Preferences
1444@ifinfo
1445 1072
1446@end ifinfo
1447When you cite an original message, you can tell Supercite which part of 1073When you cite an original message, you can tell Supercite which part of
1448the author's name you would prefer it to use as the attribution. The 1074the author's name you would prefer it to use as the attribution. The
1449variable @code{sc-preferred-attribution-list} controls this; it contains 1075variable @code{sc-preferred-attribution-list} controls this; it contains
@@ -1544,16 +1170,12 @@ match against a specific mail field, e.g., @samp{From:@:}, allowing you
1544to cite your friend's message with the appropriate attribution. 1170to cite your friend's message with the appropriate attribution.
1545 1171
1546@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution 1172@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
1547@comment node-name, next, previous, up
1548@vindex sc-default-author-name 1173@vindex sc-default-author-name
1549@vindex default-author-name (sc-) 1174@vindex default-author-name (sc-)
1550@vindex sc-default-attribution 1175@vindex sc-default-attribution
1551@vindex default-attribution (sc-) 1176@vindex default-attribution (sc-)
1552@comment
1553@section Anonymous Attributions 1177@section Anonymous Attributions
1554@ifinfo
1555 1178
1556@end ifinfo
1557When the author's name cannot be found in the @samp{From:@:} mail 1179When the author's name cannot be found in the @samp{From:@:} mail
1558header, a fallback author name and attribution string must be supplied. 1180header, a fallback author name and attribution string must be supplied.
1559The fallback author name is contained in the variable 1181The fallback author name is contained in the variable
@@ -1637,18 +1259,14 @@ one character long; e.g. you prefer to use @code{"initials"} but the
1637author only has one name.@refill 1259author only has one name.@refill
1638 1260
1639@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution 1261@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
1640@comment node-name, next, previous, up
1641@cindex author names 1262@cindex author names
1642@section Author Names 1263@section Author Names
1643@ifinfo
1644 1264
1645@end ifinfo
1646Supercite employs a number of heuristics to decipher the author's name 1265Supercite employs a number of heuristics to decipher the author's name
1647based on value of the @samp{From:@:} mail field of the original message. 1266based on value of the @samp{From:@:} mail field of the original message.
1648Supercite can recognize almost all of the common @samp{From:@:} field 1267Supercite can recognize almost all of the common @samp{From:@:} field
1649formats in use. If you encounter a @samp{From:@:} field that Supercite 1268formats in use. If you encounter a @samp{From:@:} field that Supercite
1650cannot parse, please report this bug. 1269cannot parse, please report this bug using @kbd{M-x report-emacs-bug}.
1651@xref{The Supercite Mailing List}.@refill
1652 1270
1653@vindex sc-titlecue-regexp 1271@vindex sc-titlecue-regexp
1654@vindex titlecue-regexp (sc-) 1272@vindex titlecue-regexp (sc-)
@@ -1703,14 +1321,11 @@ word in the name field, while @code{any} matches against every word in
1703the name field. 1321the name field.
1704 1322
1705@node Configuring the Citation Engine, Using Regi, Author Names, Top 1323@node Configuring the Citation Engine, Using Regi, Author Names, Top
1706@comment node-name, next, previous, up
1707@cindex Regi 1324@cindex Regi
1708@cindex frames (Regi) 1325@cindex frames (Regi)
1709@cindex entries (Regi) 1326@cindex entries (Regi)
1710@chapter Configuring the Citation Engine 1327@chapter Configuring the Citation Engine
1711@ifinfo
1712 1328
1713@end ifinfo
1714At the heart of Supercite is a regular expression interpreting engine 1329At the heart of Supercite is a regular expression interpreting engine
1715called @dfn{Regi}. Regi operates by interpreting a data structure 1330called @dfn{Regi}. Regi operates by interpreting a data structure
1716called a Regi-frame (or just @dfn{frame}), which is a list of 1331called a Regi-frame (or just @dfn{frame}), which is a list of
@@ -1744,14 +1359,11 @@ cite or fill those differently than normal text. None of this is
1744currently part of Supercite, but contributions are welcome! 1359currently part of Supercite, but contributions are welcome!
1745 1360
1746@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine 1361@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
1747@comment node-name, next, previous, up
1748@findex regi-interpret 1362@findex regi-interpret
1749@findex eval 1363@findex eval
1750@findex looking-at 1364@findex looking-at
1751@section Using Regi 1365@section Using Regi
1752@ifinfo
1753 1366
1754@end ifinfo
1755Regi works by interpreting frames with the function 1367Regi works by interpreting frames with the function
1756@code{regi-interpret}. A frame is a list of arbitrary size where each 1368@code{regi-interpret}. A frame is a list of arbitrary size where each
1757element is a entry of the following form: 1369element is a entry of the following form:
@@ -1845,12 +1457,9 @@ The current frame entry being interpreted.
1845@end table 1457@end table
1846 1458
1847@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine 1459@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
1848@comment node-name, next, previous, up
1849@vindex sc-nuke-mail-header 1460@vindex sc-nuke-mail-header
1850@section Frames You Can Customize 1461@section Frames You Can Customize
1851@ifinfo
1852 1462
1853@end ifinfo
1854As mentioned earlier, Supercite uses various frames to perform 1463As mentioned earlier, Supercite uses various frames to perform
1855certain jobs such as mail header information extraction and mail header 1464certain jobs such as mail header information extraction and mail header
1856nuking. However, these frames are not available for you to customize, 1465nuking. However, these frames are not available for you to customize,
@@ -1912,14 +1521,11 @@ the appropriate alist and attempts to find a frame to use. If one
1912is not found from the alist, then the appropriate default frame is used. 1521is not found from the alist, then the appropriate default frame is used.
1913 1522
1914@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top 1523@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
1915@comment node-name, next, previous, up
1916@vindex sc-mode-map-prefix 1524@vindex sc-mode-map-prefix
1917@vindex mode-map-prefix (sc-) 1525@vindex mode-map-prefix (sc-)
1918@kindex C-c C-p 1526@kindex C-c C-p
1919@chapter Post-yank Formatting Commands 1527@chapter Post-yank Formatting Commands
1920@ifinfo
1921 1528
1922@end ifinfo
1923Once the original message has been yanked into the reply buffer, and 1529Once the original message has been yanked into the reply buffer, and
1924@code{sc-cite-original} has had a chance to do its thing, a number of 1530@code{sc-cite-original} has had a chance to do its thing, a number of
1925useful Supercite commands will be available to you. Since there is wide 1531useful Supercite commands will be available to you. Since there is wide
@@ -1945,12 +1551,9 @@ prefix.@refill
1945@end ifinfo 1551@end ifinfo
1946 1552
1947@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands 1553@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
1948@comment node-name, next, previous, up
1949@vindex sc-cite-region-limit 1554@vindex sc-cite-region-limit
1950@section Commands to Manually Cite, Recite, and Uncite 1555@section Commands to Manually Cite, Recite, and Uncite
1951@ifinfo
1952 1556
1953@end ifinfo
1954Probably the three most common post-yank formatting operations that you 1557Probably the three most common post-yank formatting operations that you
1955will perform will be the manual citing, reciting, and unciting of 1558will perform will be the manual citing, reciting, and unciting of
1956regions of text in the reply buffer. Often you may want to recite a 1559regions of text in the reply buffer. Often you may want to recite a
@@ -1961,15 +1564,6 @@ perform these functions on the region of text between @samp{point} and
1961the region so that the command can be undone in the standard Emacs 1564the region so that the command can be undone in the standard Emacs
1962way.@refill 1565way.@refill
1963 1566
1964A quick note about Emacs 19. Unlike in Emacs 18, the region delimited
1965by @samp{point} and @samp{mark} can have two states. It can be
1966@dfn{active} or @dfn{inactive}. Although Emacs 19 and Lucid Emacs 19
1967use different terminology and functions, both employ the same convention
1968such that when the region is inactive, commands that modify the region
1969should generate an error. The user needs to explicitly activate the
1970region before successfully executing the command. All Supercite
1971commands conform to this convention.
1972
1973Here is the list of Supercite citing commands: 1567Here is the list of Supercite citing commands:
1974 1568
1975@table @asis 1569@table @asis
@@ -1982,7 +1576,6 @@ Here is the list of Supercite citing commands:
1982@vindex confirm-always-p 1576@vindex confirm-always-p
1983@kindex C-u 1577@kindex C-u
1984@item @code{sc-cite-region} (@kbd{C-c C-p c}) 1578@item @code{sc-cite-region} (@kbd{C-c C-p c})
1985@comment
1986This command cites each line in the region of text by interpreting the 1579This command cites each line in the region of text by interpreting the
1987selected frame from @code{sc-cite-frame-alist}, or the default citing 1580selected frame from @code{sc-cite-frame-alist}, or the default citing
1988frame @code{sc-default-cite-frame}. It runs the hook 1581frame @code{sc-default-cite-frame}. It runs the hook
@@ -1996,7 +1589,6 @@ attribution string for a single manual citing.
1996@findex uncite-region (sc-) 1589@findex uncite-region (sc-)
1997@kindex C-c C-p u 1590@kindex C-c C-p u
1998@item @code{sc-uncite-region} (@kbd{C-c C-p u}) 1591@item @code{sc-uncite-region} (@kbd{C-c C-p u})
1999@comment
2000This command removes any citation strings from the beginning of each 1592This command removes any citation strings from the beginning of each
2001cited line in the region by interpreting the selected frame from 1593cited line in the region by interpreting the selected frame from
2002@code{sc-uncite-frame-alist}, or the default unciting frame 1594@code{sc-uncite-frame-alist}, or the default unciting frame
@@ -2008,7 +1600,6 @@ cited line in the region by interpreting the selected frame from
2008@findex recite-region (sc-) 1600@findex recite-region (sc-)
2009@kindex C-c C-p r 1601@kindex C-c C-p r
2010@item @code{sc-recite-region} (@kbd{C-c C-p r}) 1602@item @code{sc-recite-region} (@kbd{C-c C-p r})
2011@comment
2012This command recites each line the region by interpreting the selected 1603This command recites each line the region by interpreting the selected
2013frame from @code{sc-recite-frame-alist}, or the default reciting frame 1604frame from @code{sc-recite-frame-alist}, or the default reciting frame
2014@code{sc-default-recite-frame}. It runs the hook 1605@code{sc-default-recite-frame}. It runs the hook
@@ -2022,11 +1613,8 @@ region, regardless of the value of @code{sc-confirm-always-p}.
2022@end table 1613@end table
2023 1614
2024@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands 1615@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
2025@comment node-name, next, previous, up
2026@section Insertion Commands 1616@section Insertion Commands
2027@ifinfo
2028 1617
2029@end ifinfo
2030These two functions insert various strings into the reply buffer. 1618These two functions insert various strings into the reply buffer.
2031 1619
2032@table @asis 1620@table @asis
@@ -2034,7 +1622,6 @@ These two functions insert various strings into the reply buffer.
2034@findex insert-reference (sc-) 1622@findex insert-reference (sc-)
2035@kindex C-c C-p w 1623@kindex C-c C-p w
2036@item @code{sc-insert-reference} (@kbd{C-c C-p w}) 1624@item @code{sc-insert-reference} (@kbd{C-c C-p w})
2037@comment
2038@vindex sc-preferred-header-style 1625@vindex sc-preferred-header-style
2039@vindex preferred-header-style (sc-) 1626@vindex preferred-header-style (sc-)
2040Inserts a reference header into the reply buffer at @samp{point}. With 1627Inserts a reference header into the reply buffer at @samp{point}. With
@@ -2050,19 +1637,15 @@ entered, regardless of the value of @code{sc-electric-references-p}.
2050@findex insert-citation (sc-) 1637@findex insert-citation (sc-)
2051@kindex C-c C-p i 1638@kindex C-c C-p i
2052@item @code{sc-insert-citation} (@kbd{C-c C-p i}) 1639@item @code{sc-insert-citation} (@kbd{C-c C-p i})
2053@comment
2054Inserts the current citation string at the beginning of the line that 1640Inserts the current citation string at the beginning of the line that
2055@samp{point} is on. If the line is already cited, Supercite will issue 1641@samp{point} is on. If the line is already cited, Supercite will issue
2056an error and will not cite the line. 1642an error and will not cite the line.
2057@end table 1643@end table
2058 1644
2059@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands 1645@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
2060@comment node-name, next, previous, up
2061@cindex toggling variables 1646@cindex toggling variables
2062@section Variable Toggling Shortcuts 1647@section Variable Toggling Shortcuts
2063@ifinfo
2064 1648
2065@end ifinfo
2066Supercite defines a number of commands that make it easier for you to 1649Supercite defines a number of commands that make it easier for you to
2067toggle and set various Supercite variables as you are editing the reply 1650toggle and set various Supercite variables as you are editing the reply
2068buffer. For example, you may want to turn off filling or whitespace 1651buffer. For example, you may want to turn off filling or whitespace
@@ -2140,11 +1723,8 @@ brings up a Help message on the toggling keymap.
2140 1723
2141 1724
2142@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands 1725@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
2143@comment node-name, next, previous, up
2144@section Mail Field Commands 1726@section Mail Field Commands
2145@ifinfo
2146 1727
2147@end ifinfo
2148These commands allow you to view, modify, add, and delete various bits 1728These commands allow you to view, modify, add, and delete various bits
2149of information from the info alist. 1729of information from the info alist.
2150@xref{Information Keys and the Info Alist}.@refill 1730@xref{Information Keys and the Info Alist}.@refill
@@ -2155,7 +1735,6 @@ of information from the info alist.
2155@findex mail-field-query (sc-) 1735@findex mail-field-query (sc-)
2156@kindex C-c C-p f 1736@kindex C-c C-p f
2157@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) 1737@item @code{sc-mail-field-query} (@kbd{C-c C-p f})
2158@comment
2159Allows you to interactively view, modify, add, and delete info alist 1738Allows you to interactively view, modify, add, and delete info alist
2160key-value pairs. With no argument, you are prompted (with completion) 1739key-value pairs. With no argument, you are prompted (with completion)
2161for a info key. The value associated with that key is displayed in the 1740for a info key. The value associated with that key is displayed in the
@@ -2167,8 +1746,7 @@ If you want to modify the value of a key, Supercite will first prompt
2167you (with completion) for the key of the value you want to change. It 1746you (with completion) for the key of the value you want to change. It
2168will then put you in the minibuffer with the key's current value so you 1747will then put you in the minibuffer with the key's current value so you
2169can edit the value as you wish. When you hit @key{RET}, the key's value 1748can edit the value as you wish. When you hit @key{RET}, the key's value
2170is changed. For those of you running Emacs 19, minibuffer history is 1749is changed. Minibuffer history is kept for the values.
2171kept for the values.
2172 1750
2173If you choose to delete a key-value pair, Supercite will prompt you (with 1751If you choose to delete a key-value pair, Supercite will prompt you (with
2174completion) for the key to delete. 1752completion) for the key to delete.
@@ -2185,7 +1763,6 @@ subsequently delete the key-value pair, the old value will reappear.
2185@findex mail-process-headers (sc-) 1763@findex mail-process-headers (sc-)
2186@kindex C-c C-p g 1764@kindex C-c C-p g
2187@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) 1765@item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
2188@comment
2189This command lets you re-initialize Supercite's info alist from any set 1766This command lets you re-initialize Supercite's info alist from any set
2190of mail headers in the region between @samp{point} and @samp{mark}. 1767of mail headers in the region between @samp{point} and @samp{mark}.
2191This function is especially useful for replying to digest messages where 1768This function is especially useful for replying to digest messages where
@@ -2196,60 +1773,22 @@ old information is lost.@refill
2196@end table 1773@end table
2197 1774
2198@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands 1775@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
2199@comment node-name, next, previous, up
2200@section Miscellaneous Commands 1776@section Miscellaneous Commands
2201@ifinfo
2202 1777
2203@end ifinfo
2204@table @asis 1778@table @asis
2205@findex sc-open-line 1779@findex sc-open-line
2206@findex open-line (sc-) 1780@findex open-line (sc-)
2207@findex open-line 1781@findex open-line
2208@kindex C-c C-p o 1782@kindex C-c C-p o
2209@item @code{sc-open-line} (@kbd{C-c C-p o}) 1783@item @code{sc-open-line} (@kbd{C-c C-p o})
2210@comment
2211Similar to Emacs' standard @code{open-line} commands, but inserts the 1784Similar to Emacs' standard @code{open-line} commands, but inserts the
2212citation string in front of the new line. As with @code{open-line}, 1785citation string in front of the new line. As with @code{open-line},
2213an optional numeric argument inserts that many new lines.@refill 1786an optional numeric argument inserts that many new lines.@refill
2214
2215@findex sc-describe
2216@findex describe (sc-)
2217@kindex C-c C-p ?
2218@kindex C-c C-p h
2219@item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
2220@comment
2221This function has been obsoleted by the @TeX{}info manual you are now
2222reading. It is still provided for compatibility, but it will eventually
2223go away.
2224
2225@findex sc-version
2226@findex version (sc-)
2227@kindex C-c C-p v
2228@item @code{sc-version} (@kbd{C-c C-p v})
2229@comment
2230Echos the version of Supercite you are using. With the optional
2231universal argument (@kbd{C-u}), this command inserts the version
2232information into the current buffer.
2233
2234@findex sc-submit-bug-report
2235@findex submit-bug-report (sc-)
2236@kindex C-c C-p C-b
2237@item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
2238@comment
2239If you encounter a bug, or wish to suggest an enhancement, use this
2240command to set up an outgoing mail buffer, with the proper address to
2241the Supercite maintainer automatically inserted in the @samp{To:@:}
2242field. This command also inserts information that the Supercite
2243maintainer can use to recreate your exact setup, making it easier to
2244verify your bug.
2245@end table 1787@end table
2246 1788
2247@node Hints to MUA Authors, Version 3 Changes, Electric References, Top 1789@node Hints to MUA Authors, Thanks and History, Electric References, Top
2248@comment node-name, next, previous, up
2249@chapter Hints to MUA Authors 1790@chapter Hints to MUA Authors
2250@ifinfo
2251 1791
2252@end ifinfo
2253In June of 1989, some discussion was held between the various MUA 1792In June of 1989, some discussion was held between the various MUA
2254authors, the Supercite author, and other Supercite users. These 1793authors, the Supercite author, and other Supercite users. These
2255discussions centered around the need for a standard interface between 1794discussions centered around the need for a standard interface between
@@ -2282,17 +1821,12 @@ a mail message to the Supercite mailing list:
2282@cindex sendmail.el 1821@cindex sendmail.el
2283@findex mail-yank-original 1822@findex mail-yank-original
2284@findex defvar 1823@findex defvar
2285This specification was adopted, but with the recent release of 1824This specification was adopted, but underwent a slight modification with
2286Emacs 19, it has undergone a slight modification. Instead of the 1825the release of Emacs 19. Instead of the variable
2287variable @code{mail-yank-hooks}, the new preferred hook variable that 1826@code{mail-yank-hooks}, the hook variable that the MUA should provide is
2288the MUA should provide is @code{mail-citation-hook}. 1827@code{mail-citation-hook}. Richard Stallman suggests that the MUAs
2289@code{mail-yank-hooks} can be provided for backward compatibility, but 1828should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform
2290@code{mail-citation-hook} should always take precedence. Richard 1829some default citing when that is the case.@refill
2291Stallman (of the FSF) suggests that the MUAs should @code{defvar}
2292@code{mail-citation-hook} to @code{nil} and perform some default citing
2293when that is the case. Take a look at Emacs 19's @file{sendmail.el}
2294file, specifically the @code{mail-yank-original} defun for
2295details.@refill
2296 1830
2297If you are writing a new MUA package, or maintaining an existing MUA 1831If you are writing a new MUA package, or maintaining an existing MUA
2298package, you should make it conform to this interface so that your users 1832package, you should make it conform to this interface so that your users
@@ -2316,10 +1850,7 @@ message text. It is very important that the region be set around the
2316text Supercite is to modify and that the mail headers are within this 1850text Supercite is to modify and that the mail headers are within this
2317region. Supercite will not venture outside the region for any reason, 1851region. Supercite will not venture outside the region for any reason,
2318and anything within the region is fair game, so don't put anything that 1852and anything within the region is fair game, so don't put anything that
2319@strong{must} remain unchanged inside the region. Further note that for 1853@strong{must} remain unchanged inside the region.@refill
2320Emacs 19, the region need not be set active. Supercite will work
2321properly when the region is inactive, as should any other like-minded
2322package.@refill
2323 1854
2324@item 1855@item
2325Run the hook @code{mail-citation-hook}. You will probably want to 1856Run the hook @code{mail-citation-hook}. You will probably want to
@@ -2333,94 +1864,12 @@ need only add @code{sc-cite-original} to this list of hooks using
2333@code{add-hook}.@refill 1864@code{add-hook}.@refill
2334@end enumerate 1865@end enumerate
2335 1866
2336If you do all this, your users will not need to overload your routines 1867If you do all this your MUA will join the ranks of those that conform to
2337to use Supercite, and your MUA will join the ranks of those that conform 1868this interface ``out of the box.''
2338to this interface ``out of the box.''
2339
2340@node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
2341@comment node-name, next, previous, up
2342@chapter Version 3 Changes
2343@ifinfo
2344
2345@end ifinfo
2346@cindex sc-unsupp.el file
2347With version 3, Supercite has undergone an almost complete rewrite, and
2348has hopefully benefited in a number of ways, including vast
2349improvements in the speed of performance, a big reduction in size of the
2350code and in the use of Emacs resources, and a much cleaner and flexible
2351internal architecture. The central construct of the info alist, and its
2352role in Supercite has been expanded, and the other central concept, the
2353general package Regi, was developed to provide a theoretically unlimited
2354flexibility.
2355
2356But most of this work is internal and not of very great importance to the
2357casual user. There have been some changes at the user-visible level,
2358but for the most part, the Supercite configuration variables from
2359version 2 should still be relevant to version 3. Below, I briefly
2360outline those user-visible things that have changed since version 2. For
2361details, look to other sections of this manual.
2362
2363@enumerate
2364@item
2365@cindex supercite.el file
2366@cindex reporter.el file
2367@cindex regi.el file
2368@cindex sc.el from version 2
2369@cindex sc-elec.el from version 2
2370Supercite proper now comes in a single file, @file{supercite.el}, which
2371contains everything except the unsupported noodlings, overloading (which
2372should be more or less obsolete with the release of Emacs 19), and the
2373general lisp packages @file{reporter.el} and @file{regi.el}. Finally,
2374the @TeX{}info manual comes in its own file as well. In particular, the
2375file @file{sc.el} from the version 2 distribution is obsolete, as is the
2376file @file{sc-elec.el}.
2377 1869
2378@item 1870@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top
2379@code{sc-spacify-name-chars} is gone in version 3.
2380
2381@item
2382@vindex sc-attrib-selection-list
2383@vindex attrib-selection-list
2384@code{sc-nickname-alist} is gone in version 3. The
2385@code{sc-attrib-selection-list} is a more general construct supporting
2386the same basic feature.
2387
2388@item
2389The version 2 variable @code{sc-preferred-attribution} has been changed
2390to @code{sc-preferred-attribution-list}, and has been expanded upon to
2391allow you to specify an ordered list of preferred attributions.
2392
2393@item
2394@code{sc-mail-fields-list} has been removed, and header nuking in
2395general has been greatly improved, giving you wider flexibility in
2396specifying which headers to keep and remove while presenting a
2397simplified interface to commonly chosen defaults.
2398
2399@item
2400Post-yank paragraph filling has been completely removed from Supercite,
2401other packages just do it better than Supercite ever would. Supercite
2402will still fill newly cited paragraphs.
2403
2404@item
2405@vindex sc-cite-region-limit
2406@vindex cite-region-limit
2407The variable @code{sc-all-but-cite-p} has been replaced by
2408@code{sc-cite-region-limit}.
2409
2410@item
2411Keymap hacking in the reply buffer has been greatly simplified, with, I
2412believe, little reduction in functionality.
2413
2414@item
2415Hacking of the reply buffer's docstring has been completely eliminated.
2416@end enumerate
2417
2418@node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
2419@comment node-name, next, previous, up
2420@chapter Thanks and History 1871@chapter Thanks and History
2421@ifinfo
2422 1872
2423@end ifinfo
2424The Supercite package was derived from its predecessor Superyank 1.11 1873The Supercite package was derived from its predecessor Superyank 1.11
2425which was inspired by various bits of code and ideas from Martin Neitzel 1874which was inspired by various bits of code and ideas from Martin Neitzel
2426and Ashwin Ram. They were the folks who came up with the idea of 1875and Ashwin Ram. They were the folks who came up with the idea of
@@ -2428,10 +1877,18 @@ non-nested citations and implemented some rough code to provide this
2428style. Superyank and Supercite version 2 evolved to the point where much 1877style. Superyank and Supercite version 2 evolved to the point where much
2429of the attribution selection mechanism was automatic, and features have 1878of the attribution selection mechanism was automatic, and features have
2430been continuously added through the comments and suggestions of the 1879been continuously added through the comments and suggestions of the
2431Supercite mailing list participants. Supercite version 3 represents a 1880Supercite mailing list participants.
2432nearly complete rewrite with many of the algorithms and coding styles 1881
2433being vastly improved. Hopefully Supercite version 3 is faster, 1882With version 3, Supercite underwent an almost complete rewrite,
2434smaller, and much more flexible than its predecessors. 1883benefitting in a number of ways, including vast improvements in the
1884speed of performance, a big reduction in size of the code and in the use
1885of Emacs resources, and a much cleaner and flexible internal
1886architecture. Most of this work was internal and not of very great
1887importance to the casual user. There were some changes at the
1888user-visible level, but for the most part, the Supercite configuration
1889variables from version 2 should still be relevant to version 3.
1890Hopefully Supercite version 3 is faster, smaller, and much more flexible
1891than its predecessors.
2435 1892
2436In the version 2 manual I thanked some specific people for their help in 1893In the version 2 manual I thanked some specific people for their help in
2437developing Supercite 2. You folks know who you are and your continued 1894developing Supercite 2. You folks know who you are and your continued
@@ -2445,54 +1902,17 @@ for adding the magic lisp to their code to support this.
2445 1902
2446All who have helped and contributed have been greatly appreciated. 1903All who have helped and contributed have been greatly appreciated.
2447 1904
2448@node The Supercite Mailing List, GNU Free Documentation License, Thanks and History, Top 1905Supercite was written by Barry Warsaw.
2449@comment node-name, next, previous, up
2450@cindex supercite mailing list address
2451@cindex mailing list address
2452@chapter The Supercite Mailing List
2453@ifinfo
2454 1906
2455@end ifinfo 1907@node GNU Free Documentation License, Concept Index, Thanks and History, Top
2456The author runs a simple mail expanding mailing list for discussion of
2457issues related to Supercite. This includes enhancement requests, bug
2458reports, general help questions, etc. To subscribe or unsubscribe to
2459the mailing list, send a request to the administrative address:
2460
2461@example
2462supercite-request@@python.org
2463@end example
2464
2465Please be sure to include the most reliable and shortest (preferably
2466Internet) address back to you. To post articles to the list, send your
2467message to this address (you do not need to be a member to post, but be
2468sure to indicate this in your article or replies may not be CC'd to
2469you):
2470
2471@example
2472supercite@@python.org
2473@end example
2474
2475If you are sending bug reports, they should go to the following address,
2476but @emph{please}! use the command @code{sc-submit-bug-report} since it
2477will be much easier for me to duplicate your problem if you do so. It
2478will set up a mail buffer automatically with this address on the
2479@samp{To:@:} line:
2480
2481@example
2482supercite-help@@python.org
2483@end example
2484
2485@node GNU Free Documentation License, Concept Index, The Supercite Mailing List, Top
2486@appendix GNU Free Documentation License 1908@appendix GNU Free Documentation License
2487@include doclicense.texi 1909@include doclicense.texi
2488 1910
2489@node Concept Index, Command Index, GNU Free Documentation License, Top 1911@node Concept Index, Command Index, GNU Free Documentation License, Top
2490@comment node-name, next, previous, up
2491@unnumbered Concept Index 1912@unnumbered Concept Index
2492@printindex cp 1913@printindex cp
2493 1914
2494@node Command Index, Key Index, Concept Index, Top 1915@node Command Index, Key Index, Concept Index, Top
2495@comment node-name, next, previous, up
2496@unnumbered Command Index 1916@unnumbered Command Index
2497@ifinfo 1917@ifinfo
2498 1918
@@ -2506,12 +1926,10 @@ its @var{command} name.
2506@printindex fn 1926@printindex fn
2507 1927
2508@node Key Index, Variable Index, Command Index, Top 1928@node Key Index, Variable Index, Command Index, Top
2509@comment node-name, next, previous, up
2510@unnumbered Key Index 1929@unnumbered Key Index
2511@printindex ky 1930@printindex ky
2512 1931
2513@node Variable Index, , Key Index, Top 1932@node Variable Index, , Key Index, Top
2514@comment node-name, next, previous, up
2515@unnumbered Variable Index 1933@unnumbered Variable Index
2516@ifinfo 1934@ifinfo
2517 1935