aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorXue Fuqiao2013-08-07 21:19:48 +0800
committerXue Fuqiao2013-08-07 21:19:48 +0800
commit998ad848a4f1fd347fdbb1cf181035a0e174eddc (patch)
tree163cd043f2060ea479ea3e46402dfe0d3b8bf9ed /doc
parent98374c9aebd118332e3cb0d7f0a27cc585390c7d (diff)
downloademacs-998ad848a4f1fd347fdbb1cf181035a0e174eddc.tar.gz
emacs-998ad848a4f1fd347fdbb1cf181035a0e174eddc.zip
Index and whitespace fixes for doc/misc/sc.texi.
* sc.texi (Introduction): Fix indexes. (Usage Overview): (Citations, Citation Elements, Recognizing Citations) (Information Keys and the Info Alist, Reference Headers) (The Built-in Header Rewrite Functions) (Electric References, Reply Buffer Initialization) (Filling Cited Text, Selecting an Attribution) (Attribution Preferences) (Anonymous Attributions, Author Names) (Using Regi, Post-yank Formatting Commands) (Citing Commands, Insertion Commands) (Mail Field Commands) (Hints to MUA Authors, Thanks and History): Change from one space between sentences to two.
Diffstat (limited to 'doc')
-rw-r--r--doc/misc/ChangeLog17
-rw-r--r--doc/misc/sc.texi192
2 files changed, 114 insertions, 95 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 84147698029..5721626f4e3 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,5 +1,20 @@
12013-08-07 Xue Fuqiao <xfq.free@gmail.com> 12013-08-07 Xue Fuqiao <xfq.free@gmail.com>
2 2
3 * sc.texi (Introduction): Fix index.
4 (Usage Overview):
5 (Citations, Citation Elements, Recognizing Citations)
6 (Information Keys and the Info Alist, Reference Headers)
7 (The Built-in Header Rewrite Functions)
8 (Electric References, Reply Buffer Initialization)
9 (Filling Cited Text, Selecting an Attribution)
10 (Attribution Preferences)
11 (Anonymous Attributions, Author Names)
12 (Using Regi, Post-yank Formatting Commands)
13 (Citing Commands, Insertion Commands)
14 (Mail Field Commands)
15 (Hints to MUA Authors, Thanks and History): Change from one space
16 between sentences to two.
17
3 * newsticker.texi (Usage): Use @key for RET. 18 * newsticker.texi (Usage): Use @key for RET.
4 19
5 * cl.texi (Argument Lists): 20 * cl.texi (Argument Lists):
@@ -205,7 +220,7 @@
205 220
2062013-05-25 Xue Fuqiao <xfq.free@gmail.com> 2212013-05-25 Xue Fuqiao <xfq.free@gmail.com>
207 222
208 * flymake.texi: Changing from one space between sentences to two. 223 * flymake.texi: Change from one space between sentences to two.
209 224
2102013-05-04 Stefan Monnier <monnier@iro.umontreal.ca> 2252013-05-04 Stefan Monnier <monnier@iro.umontreal.ca>
211 226
diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi
index cfd040f0e82..7d7ef07ed61 100644
--- a/doc/misc/sc.texi
+++ b/doc/misc/sc.texi
@@ -84,12 +84,15 @@ into the following chapters.
84@node Introduction 84@node Introduction
85@chapter Introduction 85@chapter Introduction
86 86
87Supercite is a GNU Emacs package written entirely in Emacs Lisp. It 87@cindex MUA
88@cindex NUA
89Supercite is a GNU Emacs package written entirely in Emacs Lisp. It
88interfaces to most of the commonly used Emacs mail user agents 90interfaces to most of the commonly used Emacs mail user agents
89(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides 91(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
90sophisticated facilities for the citing and attributing of message 92sophisticated facilities for the citing and attributing of message
91replies. Supercite has a very specific and limited role in the process 93replies. Supercite has a very specific and limited role in the
92of composing replies to both USENET network news and electronic mail. 94process of composing replies to both USENET network news and
95electronic mail.
93 96
94The preferred way to spell Supercite is with a capital @samp{S}, 97The preferred way to spell Supercite is with a capital @samp{S},
95lowercase @samp{upercite}. 98lowercase @samp{upercite}.
@@ -100,8 +103,7 @@ lowercase @samp{upercite}.
100* What Supercite Does:: 103* What Supercite Does::
101@end menu 104@end menu
102 105
103@cindex MUA 106@c FIXME: move it above the menu? --xfq
104@cindex NUA
105Supercite is only useful in conjunction with MUAs and NUAs such as VM, 107Supercite is only useful in conjunction with MUAs and NUAs such as VM,
106Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a 108Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a
107reply buffer has been setup. Thereafter, Supercite's many commands and 109reply buffer has been setup. Thereafter, Supercite's many commands and
@@ -118,21 +120,22 @@ sent. Supercite is re-initialized in each new reply buffer.
118@cindex cite, citing 120@cindex cite, citing
119@cindex attribute, attributing 121@cindex attribute, attributing
120 122
121Typical usage is as follows. You want to reply or followup to a message 123Typical usage is as follows. You want to reply or followup to a
122in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} 124message in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'')
123(i.e., ``forward'') to begin composing the reply. In response, the MUA 125or @kbd{f} (i.e., ``forward'') to begin composing the reply. In
124will create a reply buffer and initialize the outgoing mail headers 126response, the MUA will create a reply buffer and initialize the
125appropriately. The body of the reply will usually be empty at this 127outgoing mail headers appropriately. The body of the reply will
126point. You now decide that you would like to include part of the 128usually be empty at this point. You now decide that you would like to
127original message in your reply. To do this, you @dfn{yank} the original 129include part of the original message in your reply. To do this, you
128message into the reply buffer, typically with a key stroke such as 130@dfn{yank} the original message into the reply buffer, typically with
129@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which 131a key stroke such as @kbd{C-c C-y}. This sequence will invoke an
130fills the body of the reply with the original message and then 132MUA-specific function which fills the body of the reply with the
131@dfn{attributes} this text to its author. This is called @dfn{citing} 133original message and then @dfn{attributes} this text to its author.
132and its effect is to prefix every line from the original message with a 134This is called @dfn{citing} and its effect is to prefix every line
133special text tag. Most MUAs provide some default style of citing; by 135from the original message with a special text tag. Most MUAs provide
134using Supercite you gain a wider flexibility in the look and style of 136some default style of citing; by using Supercite you gain a wider
135citations. Supercite's only job is to cite the original message. 137flexibility in the look and style of citations. Supercite's only job
138is to cite the original message.
136 139
137@node What Supercite Does Not Do 140@node What Supercite Does Not Do
138@section What Supercite Doesn't Do 141@section What Supercite Doesn't Do
@@ -253,10 +256,10 @@ make the message very difficult for the eye to scan.
253 256
254@cindex non-nested citations 257@cindex non-nested citations
255In @dfn{non-nested citations}, each cited line begins with an 258In @dfn{non-nested citations}, each cited line begins with an
256informative string attributing that line to the original author. Only 259informative string attributing that line to the original author. Only
257the first level of attribution will be shown; subsequent citations don't 260the first level of attribution will be shown; subsequent citations
258nest the citation strings. The above dialog might look like this when 261don't nest the citation strings. The above dialog might look like
259non-nested citations are used: 262this when non-nested citations are used:
260 263
261@example 264@example
262John> John originally wrote this 265John> John originally wrote this
@@ -272,19 +275,20 @@ message did not result in a line cited with @samp{Jane>John>}.
272@vindex sc-nested-citation-p 275@vindex sc-nested-citation-p
273@vindex nested-citation-p (sc-) 276@vindex nested-citation-p (sc-)
274Supercite supports both styles of citation, and the variable 277Supercite supports both styles of citation, and the variable
275@code{sc-nested-citation-p} controls which style it will use when citing 278@code{sc-nested-citation-p} controls which style it will use when
276previously uncited text. When this variable is @code{nil} (the default), 279citing previously uncited text. When this variable is @code{nil} (the
277non-nested citations are used. When non-@code{nil}, nested citations 280default), non-nested citations are used. When non-@code{nil}, nested
278are used. 281citations are used.
279 282
280 283
281@node Citation Elements 284@node Citation Elements
282@section Citation Elements 285@section Citation Elements
283@cindex citation string 286@cindex citation string
284 287
285@dfn{Citation strings} are composed of one or more elements. Non-nested 288@dfn{Citation strings} are composed of one or more elements.
286citations are composed of four elements, three of which are directly 289Non-nested citations are composed of four elements, three of which are
287user definable. The elements are concatenated together, in this order: 290directly user definable. The elements are concatenated together, in
291this order:
288 292
289@cindex citation leader 293@cindex citation leader
290@vindex citation-leader (sc-) 294@vindex citation-leader (sc-)
@@ -337,10 +341,10 @@ multi-level nested citations.
337@section Recognizing Citations 341@section Recognizing Citations
338 342
339Supercite also recognizes citations in the original article, and can 343Supercite also recognizes citations in the original article, and can
340transform these already cited lines in a number of ways. This is how 344transform these already cited lines in a number of ways. This is how
341Supercite suppresses the multiple citing of non-nested citations. 345Supercite suppresses the multiple citing of non-nested citations.
342Recognition of cited lines is controlled by variables analogous to those 346Recognition of cited lines is controlled by variables analogous to
343that make up the citation string as mentioned previously. 347those that make up the citation string as mentioned previously.
344 348
345@vindex sc-citation-leader-regexp 349@vindex sc-citation-leader-regexp
346@vindex citation-leader-regexp (sc-) 350@vindex citation-leader-regexp (sc-)
@@ -387,16 +391,16 @@ change @code{sc-citation-root-regexp} you should always also change
387 391
388@dfn{Mail header information keys} are nuggets of information that 392@dfn{Mail header information keys} are nuggets of information that
389Supercite extracts from the various mail headers of the original 393Supercite extracts from the various mail headers of the original
390message, placed in the reply buffer by the MUA@. Information is kept in 394message, placed in the reply buffer by the MUA@. Information is kept
391the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in 395in the @dfn{Info Alist} as key-value pairs, and can be retrieved for
392various places within Supercite, such as in header rewrite functions and 396use in various places within Supercite, such as in header rewrite
393attribution selection. Other bits of data, composed and created by 397functions and attribution selection. Other bits of data, composed and
394Supercite, are also kept as key-value pairs in this alist. In the case 398created by Supercite, are also kept as key-value pairs in this alist.
395of mail fields, the key is the name of the field, omitting the trailing 399In the case of mail fields, the key is the name of the field, omitting
396colon. Info keys are always case insensitive (as are mail headers), and 400the trailing colon. Info keys are always case insensitive (as are
397the value for a corresponding key can be retrieved from the alist with 401mail headers), and the value for a corresponding key can be retrieved
398the @code{sc-mail-field} function. Thus, if the following fields were 402from the alist with the @code{sc-mail-field} function. Thus, if the
399present in the original article:@refill 403following fields were present in the original article:@refill
400 404
401@example 405@example
402Date:@: 08 April 1991, 17:32:09 EST 406Date:@: 08 April 1991, 17:32:09 EST
@@ -419,7 +423,7 @@ then, the following lisp constructs return:
419Since the argument to @code{sc-mail-field} can be any string, it is 423Since the argument to @code{sc-mail-field} can be any string, it is
420possible that the mail field will not be present on the info alist 424possible that the mail field will not be present on the info alist
421(possibly because the mail header was not present in the original 425(possibly because the mail header was not present in the original
422message). In this case, @code{sc-mail-field} will return the value of 426message). In this case, @code{sc-mail-field} will return the value of
423the variable @code{sc-mumble}. 427the variable @code{sc-mumble}.
424 428
425Supercite always places all mail fields found in the yanked original 429Supercite always places all mail fields found in the yanked original
@@ -510,8 +514,8 @@ header.
510@vindex sc-rewrite-header-list 514@vindex sc-rewrite-header-list
511@vindex rewrite-header-list (sc-) 515@vindex rewrite-header-list (sc-)
512There are a number of built-in @dfn{header rewrite functions} supplied 516There are a number of built-in @dfn{header rewrite functions} supplied
513by Supercite, but you can write your own custom header rewrite functions 517by Supercite, but you can write your own custom header rewrite
514(perhaps using the built-in ones as examples). The variable 518functions (perhaps using the built-in ones as examples). The variable
515@code{sc-rewrite-header-list} contains the list of such header rewrite 519@code{sc-rewrite-header-list} contains the list of such header rewrite
516functions. This list is consulted both when inserting the initial 520functions. This list is consulted both when inserting the initial
517reference header, and when displaying @dfn{electric references}. 521reference header, and when displaying @dfn{electric references}.
@@ -521,7 +525,7 @@ reference header, and when displaying @dfn{electric references}.
521@vindex preferred-header-style (sc-) 525@vindex preferred-header-style (sc-)
522When Supercite is initially run on a reply buffer (via 526When Supercite is initially run on a reply buffer (via
523@code{sc-cite-original}), it will automatically call one of these 527@code{sc-cite-original}), it will automatically call one of these
524functions. The one it uses is defined in the variable 528functions. The one it uses is defined in the variable
525@code{sc-preferred-header-style}. The value of this variable is an 529@code{sc-preferred-header-style}. The value of this variable is an
526integer which is an index into the @code{sc-rewrite-header-list}, 530integer which is an index into the @code{sc-rewrite-header-list},
527beginning at zero. 531beginning at zero.
@@ -556,9 +560,9 @@ problem either in your MUA or in Supercite's installation).
556@findex sc-no-header 560@findex sc-no-header
557@findex no-header (sc-) 561@findex no-header (sc-)
558@item sc-no-header 562@item sc-no-header
559This function produces no header. It should be used instead of 563This function produces no header. It should be used instead of
560@code{nil} to produce a blank header. This header can possibly contain 564@code{nil} to produce a blank header. This header can possibly
561a blank line after the @code{mail-header-separator} line. 565contain a blank line after the @code{mail-header-separator} line.
562 566
563@item sc-no-blank-line-or-header 567@item sc-no-blank-line-or-header
564@findex sc-no-blank-line-or-header 568@findex sc-no-blank-line-or-header
@@ -612,11 +616,11 @@ line after the @code{mail-header-separator} line will be removed.
612By default, when Supercite cites the original message for the first 616By default, when Supercite cites the original message for the first
613time, it just goes ahead and inserts the reference header indexed by 617time, it just goes ahead and inserts the reference header indexed by
614@code{sc-preferred-header-style}. However, you may want to select 618@code{sc-preferred-header-style}. However, you may want to select
615different reference headers based on the type of reply or forwarding you 619different reference headers based on the type of reply or forwarding
616are doing. You may also want to preview the reference header before 620you are doing. You may also want to preview the reference header
617deciding whether to insert it into the reply buffer or not. Supercite 621before deciding whether to insert it into the reply buffer or
618provides an optional @dfn{electric reference} mode which you can drop 622not. Supercite provides an optional @dfn{electric reference} mode
619into to give you this functionality. 623which you can drop into to give you this functionality.
620 624
621@vindex sc-electric-references-p 625@vindex sc-electric-references-p
622@vindex electric-references-p (sc-) 626@vindex electric-references-p (sc-)
@@ -629,7 +633,7 @@ through all the reference header rewrite functions in your
629@code{sc-rewrite-header-list}. 633@code{sc-rewrite-header-list}.
630 634
631You can also set a new preferred header style, jump to any header, or 635You can also set a new preferred header style, jump to any header, or
632jump to the preferred header. The header will be shown in the electric 636jump to the preferred header. The header will be shown in the electric
633reference buffer and the header index and function name will appear in 637reference buffer and the header index and function name will appear in
634the echo area. 638the echo area.
635 639
@@ -643,7 +647,7 @@ The following commands are available while in electric reference mode
643@kindex n 647@kindex n
644@vindex sc-electric-circular-p 648@vindex sc-electric-circular-p
645@vindex electric-circular-p (sc-) 649@vindex electric-circular-p (sc-)
646Displays the next reference header in the electric reference buffer. If 650Displays the next reference header in the electric reference buffer. If
647the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking 651the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
648@code{sc-eref-next} while viewing the last reference header in the list 652@code{sc-eref-next} while viewing the last reference header in the list
649will wrap around to the first header.@refill 653will wrap around to the first header.@refill
@@ -854,7 +858,7 @@ affect alternative citing styles.
854@vindex mail-warn-if-non-rfc822-p (sc-) 858@vindex mail-warn-if-non-rfc822-p (sc-)
855All previously retrieved info key-value pairs are deleted from the info 859All previously retrieved info key-value pairs are deleted from the info
856alist, then the mail headers in the body of the yanked message are 860alist, then the mail headers in the body of the yanked message are
857scanned. Info key-value pairs are created for each header found. Also, 861scanned. Info key-value pairs are created for each header found. Also,
858such useful information as the author's name and email address are 862such useful information as the author's name and email address are
859extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is 863extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is
860non-@code{nil}, then Supercite will warn you if it finds a mail header 864non-@code{nil}, then Supercite will warn you if it finds a mail header
@@ -931,7 +935,7 @@ in the original message should be cited or not. If this variable is
931non-@code{nil}, blank lines will be cited just like non-blank lines. 935non-@code{nil}, blank lines will be cited just like non-blank lines.
932Otherwise, blank lines will be treated as paragraph separators. 936Otherwise, blank lines will be treated as paragraph separators.
933 937
934Citing of the original message is highly configurable. Supercite's 938Citing of the original message is highly configurable. Supercite's
935default setup does a pretty good job of citing many common forms of 939default setup does a pretty good job of citing many common forms of
936previously cited messages. But there are as many citation styles out 940previously cited messages. But there are as many citation styles out
937there as people on the net, or just about! It would be impossible for 941there as people on the net, or just about! It would be impossible for
@@ -945,8 +949,8 @@ recognize those styles you see often.
945@vindex sc-post-hook 949@vindex sc-post-hook
946@vindex post-hook (sc-) 950@vindex post-hook (sc-)
947This variable is very similar to @code{sc-pre-hook}, except that it runs 951This variable is very similar to @code{sc-pre-hook}, except that it runs
948after @code{sc-cite-original} is finished. This hook is provided mostly 952after @code{sc-cite-original} is finished. This hook is provided mostly
949for completeness and backward compatibility. Perhaps it could be used to 953for completeness and backward compatibility. Perhaps it could be used to
950reset certain variables set in @code{sc-pre-hook}.@refill 954reset certain variables set in @code{sc-pre-hook}.@refill
951@end enumerate 955@end enumerate
952 956
@@ -1012,7 +1016,7 @@ both of these variables is provided on the key binding
1012@pxref{Post-yank Formatting Commands}).@refill 1016@pxref{Post-yank Formatting Commands}).@refill
1013 1017
1014You will noticed that the minor mode string will 1018You will noticed that the minor mode string will
1015show the state of these variables as qualifier characters. When both 1019show the state of these variables as qualifier characters. When both
1016variables are @code{nil}, the Supercite minor mode string will display 1020variables are @code{nil}, the Supercite minor mode string will display
1017@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the 1021@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
1018string will display @samp{SC:f}, and when just 1022string will display @samp{SC:f}, and when just
@@ -1036,11 +1040,11 @@ fill cited text.
1036@vindex preferred-attribution-list (sc-) 1040@vindex preferred-attribution-list (sc-)
1037 1041
1038As you know, the attribution string is the part of the author's name 1042As you know, the attribution string is the part of the author's name
1039that will be used to composed a non-nested citation string. Supercite 1043that will be used to composed a non-nested citation string. Supercite
1040scans the various mail headers present in the original article and uses 1044scans the various mail headers present in the original article and uses
1041a number of heuristics to extract strings which it puts into the 1045a number of heuristics to extract strings which it puts into the
1042@dfn{attribution association list} or @dfn{attribution alist}. This is 1046@dfn{attribution association list} or @dfn{attribution alist}. This is
1043analogous, but different than, the info alist previously mentioned. Each 1047analogous, but different than, the info alist previously mentioned. Each
1044element in the attribution alist is a key-value pair containing such 1048element in the attribution alist is a key-value pair containing such
1045information as the author's first name, middle names, and last name, the 1049information as the author's first name, middle names, and last name, the
1046author's initials, and the author's email terminus. 1050author's initials, and the author's email terminus.
@@ -1083,7 +1087,7 @@ the author's last name.
1083the author's first middle name. 1087the author's first middle name.
1084 1088
1085@item "sc-lastchoice" 1089@item "sc-lastchoice"
1086the last attribution string you have selected. This is useful when you 1090the last attribution string you have selected. This is useful when you
1087recite paragraphs in the reply.@refill 1091recite paragraphs in the reply.@refill
1088 1092
1089@item "sc-consult" 1093@item "sc-consult"
@@ -1094,7 +1098,7 @@ be used to select special attributions based on the value of any info
1094key. See below for details. 1098key. See below for details.
1095 1099
1096@item "x-attribution" 1100@item "x-attribution"
1097the original author's suggestion for attribution string choice. See below 1101the original author's suggestion for attribution string choice. See below
1098for details.@refill 1102for details.@refill
1099@end table 1103@end table
1100 1104
@@ -1141,7 +1145,7 @@ Each element in this list contains lists of the following form:
1141@findex sc-mail-field 1145@findex sc-mail-field
1142@findex mail-field (sc-) 1146@findex mail-field (sc-)
1143where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} 1147where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
1144is a regular expression to match against the @var{infokey}'s value. If 1148is a regular expression to match against the @var{infokey}'s value. If
1145@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is 1149@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
1146used as the attribution string. Actually, @var{attribution} can be a 1150used as the attribution string. Actually, @var{attribution} can be a
1147string or a list; if it is a list, it is @code{eval}uated and the return 1151string or a list; if it is a list, it is @code{eval}uated and the return
@@ -1166,7 +1170,7 @@ The fallback author name is contained in the variable
1166@code{sc-default-author-name} and the fallback attribution string is 1170@code{sc-default-author-name} and the fallback attribution string is
1167contained in the variable @code{sc-default-attribution}. Default values 1171contained in the variable @code{sc-default-attribution}. Default values
1168for these variables are @code{"Anonymous"} and @code{"Anon"}, 1172for these variables are @code{"Anonymous"} and @code{"Anon"},
1169respectively. Note that in most circumstances, getting the default 1173respectively. Note that in most circumstances, getting the default
1170author name or attribution is a sign that something is set up 1174author name or attribution is a sign that something is set up
1171incorrectly. 1175incorrectly.
1172 1176
@@ -1174,7 +1178,7 @@ incorrectly.
1174@vindex use-only-preference-p (sc-) 1178@vindex use-only-preference-p (sc-)
1175Also, if the preferred attribution, which you specified in your 1179Also, if the preferred attribution, which you specified in your
1176@code{sc-preferred-attribution-list} variable cannot be found, a 1180@code{sc-preferred-attribution-list} variable cannot be found, a
1177secondary method can be employed to find a valid attribution string. The 1181secondary method can be employed to find a valid attribution string. The
1178variable @code{sc-use-only-preference-p} controls what happens in this 1182variable @code{sc-use-only-preference-p} controls what happens in this
1179case. If the variable's value is non-@code{nil}, then 1183case. If the variable's value is non-@code{nil}, then
1180@code{sc-default-author-name} and @code{sc-default-attribution} are 1184@code{sc-default-author-name} and @code{sc-default-attribution} are
@@ -1209,11 +1213,11 @@ attribution alist.
1209@vindex sc-confirm-always-p 1213@vindex sc-confirm-always-p
1210@vindex confirm-always-p (sc-) 1214@vindex confirm-always-p (sc-)
1211Once the attribution string has been automatically selected, a number of 1215Once the attribution string has been automatically selected, a number of
1212things can happen. If the variable @code{sc-confirm-always-p} is 1216things can happen. If the variable @code{sc-confirm-always-p} is
1213non-@code{nil}, you are queried for confirmation of the chosen 1217non-@code{nil}, you are queried for confirmation of the chosen
1214attribution string. The possible values for completion are those strings 1218attribution string. The possible values for completion are those strings
1215in the attribution alist, however you are not limited to these choices. 1219in the attribution alist, however you are not limited to these choices.
1216You can type any arbitrary string at the confirmation prompt. The string 1220You can type any arbitrary string at the confirmation prompt. The string
1217you enter becomes the value associated with the @code{"sc-lastchoice"} 1221you enter becomes the value associated with the @code{"sc-lastchoice"}
1218key in the attribution alist. 1222key in the attribution alist.
1219 1223
@@ -1279,7 +1283,7 @@ author's name proper. Examples include the titles ``Dr.'', ``Mr.'',
1279Also, some companies prepend or append the name of the division, 1283Also, some companies prepend or append the name of the division,
1280organization, or project on the author's name. All of these titles are 1284organization, or project on the author's name. All of these titles are
1281noise which should be ignored. The variable @code{sc-name-filter-alist} 1285noise which should be ignored. The variable @code{sc-name-filter-alist}
1282is used for this purpose. As implied by its name, this variable is an 1286is used for this purpose. As implied by its name, this variable is an
1283association list, where each element is a cons cell of the form: 1287association list, where each element is a cons cell of the form:
1284 1288
1285@example 1289@example
@@ -1290,7 +1294,7 @@ association list, where each element is a cons cell of the form:
1290where @var{regexp} is a regular expression that is matched (using 1294where @var{regexp} is a regular expression that is matched (using
1291@code{string-match}) against each element of the @samp{From:@:} field's 1295@code{string-match}) against each element of the @samp{From:@:} field's
1292author name. @var{position} is a position indicator, starting at zero. 1296author name. @var{position} is a position indicator, starting at zero.
1293Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, 1297Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
1294@code{sc-name-filter-alist} would have an entry such as: 1298@code{sc-name-filter-alist} would have an entry such as:
1295 1299
1296@example 1300@example
@@ -1380,10 +1384,10 @@ The four special symbol values for @var{pred} are recognized:
1380@item t 1384@item t
1381Always produces a true outcome. 1385Always produces a true outcome.
1382@item begin 1386@item begin
1383Always executed before the frame is interpreted. This can be used to 1387Always executed before the frame is interpreted. This can be used to
1384initialize some global variables for example. 1388initialize some global variables for example.
1385@item end 1389@item end
1386Always executed after frame interpreting is completed. This can be used 1390Always executed after frame interpreting is completed. This can be used
1387to perform any necessary post-processing. 1391to perform any necessary post-processing.
1388@item every 1392@item every
1389Executes whenever the frame is reset, usually after the entire frame has 1393Executes whenever the frame is reset, usually after the entire frame has
@@ -1406,12 +1410,12 @@ of the following elements:@refill
1406@table @asis 1410@table @asis
1407@item the symbol @code{continue} 1411@item the symbol @code{continue}
1408This tells Regi to continue processing entries after a match, instead of 1412This tells Regi to continue processing entries after a match, instead of
1409resetting the frame and moving @samp{point}. In this way, lines of text 1413resetting the frame and moving @samp{point}. In this way, lines of text
1410can have multiple matches, but you have to be careful to avoid entering 1414can have multiple matches, but you have to be careful to avoid entering
1411infinite loops. 1415infinite loops.
1412 1416
1413@item the symbol @code{abort} 1417@item the symbol @code{abort}
1414This tells Regi to terminate frame processing. However, any @code{end} 1418This tells Regi to terminate frame processing. However, any @code{end}
1415entry is still processed. 1419entry is still processed.
1416 1420
1417@item the list @code{(frame . @var{newframe})} 1421@item the list @code{(frame . @var{newframe})}
@@ -1422,7 +1426,7 @@ can be the frame in-lined.@refill
1422 1426
1423@item the list @code{(step . @var{step})} 1427@item the list @code{(step . @var{step})}
1424Tells Regi to move @var{step} number of lines forward as it continues 1428Tells Regi to move @var{step} number of lines forward as it continues
1425processing. By default, Regi moves forward one line. @var{step} can be 1429processing. By default, Regi moves forward one line. @var{step} can be
1426zero or negative of course, but watch out for infinite loops.@refill 1430zero or negative of course, but watch out for infinite loops.@refill
1427@end table 1431@end table
1428 1432
@@ -1510,12 +1514,12 @@ is not found from the alist, then the appropriate default frame is used.
1510 1514
1511Once the original message has been yanked into the reply buffer, and 1515Once the original message has been yanked into the reply buffer, and
1512@code{sc-cite-original} has had a chance to do its thing, a number of 1516@code{sc-cite-original} has had a chance to do its thing, a number of
1513useful Supercite commands will be available to you. Since there is wide 1517useful Supercite commands will be available to you. Since there is wide
1514variety in the keymaps that MUAs set up in their reply buffers, it is 1518variety in the keymaps that MUAs set up in their reply buffers, it is
1515next to impossible for Supercite to properly sprinkle its commands into 1519next to impossible for Supercite to properly sprinkle its commands into
1516the existing keymap. For this reason Supercite places its commands on a 1520the existing keymap. For this reason Supercite places its commands on a
1517separate keymap, putting this keymap onto a prefix key in the reply 1521separate keymap, putting this keymap onto a prefix key in the reply
1518buffer. You can customize the prefix key Supercite uses by changing the 1522buffer. You can customize the prefix key Supercite uses by changing the
1519variable @code{sc-mode-map-prefix}. By default, the 1523variable @code{sc-mode-map-prefix}. By default, the
1520@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, 1524@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
1521but unfortunately the best general solution so far. In the rest of this 1525but unfortunately the best general solution so far. In the rest of this
@@ -1536,7 +1540,7 @@ prefix.@refill
1536 1540
1537Probably the three most common post-yank formatting operations that you 1541Probably the three most common post-yank formatting operations that you
1538will perform will be the manual citing, reciting, and unciting of 1542will perform will be the manual citing, reciting, and unciting of
1539regions of text in the reply buffer. Often you may want to recite a 1543regions of text in the reply buffer. Often you may want to recite a
1540paragraph to use a nickname, or manually cite a message when setting 1544paragraph to use a nickname, or manually cite a message when setting
1541@code{sc-cite-region-limit} to @code{nil}. The following commands 1545@code{sc-cite-region-limit} to @code{nil}. The following commands
1542perform these functions on the region of text between @samp{point} and 1546perform these functions on the region of text between @samp{point} and
@@ -1582,7 +1586,7 @@ cited line in the region by interpreting the selected frame from
1582@item @code{sc-recite-region} (@kbd{C-c C-p r}) 1586@item @code{sc-recite-region} (@kbd{C-c C-p r})
1583This command recites each line the region by interpreting the selected 1587This command recites each line the region by interpreting the selected
1584frame from @code{sc-recite-frame-alist}, or the default reciting frame 1588frame from @code{sc-recite-frame-alist}, or the default reciting frame
1585@code{sc-default-recite-frame}. It runs the hook 1589@code{sc-default-recite-frame}. It runs the hook
1586@code{sc-pre-recite-hook} before interpreting the frame. 1590@code{sc-pre-recite-hook} before interpreting the frame.
1587@xref{Configuring the Citation Engine}.@refill 1591@xref{Configuring the Citation Engine}.@refill
1588 1592
@@ -1606,7 +1610,7 @@ These two functions insert various strings into the reply buffer.
1606@vindex preferred-header-style (sc-) 1610@vindex preferred-header-style (sc-)
1607Inserts a reference header into the reply buffer at @samp{point}. With 1611Inserts a reference header into the reply buffer at @samp{point}. With
1608no arguments, the header indexed by @code{sc-preferred-header-style} is 1612no arguments, the header indexed by @code{sc-preferred-header-style} is
1609inserted. An optional numeric argument is the index into 1613inserted. An optional numeric argument is the index into
1610@code{sc-rewrite-header-list} indicating which reference header to 1614@code{sc-rewrite-header-list} indicating which reference header to
1611write.@refill 1615write.@refill
1612 1616
@@ -1719,7 +1723,7 @@ Allows you to interactively view, modify, add, and delete info alist
1719key-value pairs. With no argument, you are prompted (with completion) 1723key-value pairs. With no argument, you are prompted (with completion)
1720for a info key. The value associated with that key is displayed in the 1724for a info key. The value associated with that key is displayed in the
1721minibuffer. With an argument, this command will first ask if you want 1725minibuffer. With an argument, this command will first ask if you want
1722to view, modify, add, or delete an info key. Viewing is identical to 1726to view, modify, add, or delete an info key. Viewing is identical to
1723running the command with no arguments. 1727running the command with no arguments.
1724 1728
1725If you want to modify the value of a key, Supercite will first prompt 1729If you want to modify the value of a key, Supercite will first prompt
@@ -1770,7 +1774,7 @@ an optional numeric argument inserts that many new lines.@refill
1770@chapter Hints to MUA Authors 1774@chapter Hints to MUA Authors
1771 1775
1772In June of 1989, some discussion was held between the various MUA 1776In June of 1989, some discussion was held between the various MUA
1773authors, the Supercite author, and other Supercite users. These 1777authors, the Supercite author, and other Supercite users. These
1774discussions centered around the need for a standard interface between 1778discussions centered around the need for a standard interface between
1775MUAs and Supercite (or any future Supercite-like packages). This 1779MUAs and Supercite (or any future Supercite-like packages). This
1776interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in 1780interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in
@@ -1810,14 +1814,14 @@ some default citing when that is the case.@refill
1810 1814
1811If you are writing a new MUA package, or maintaining an existing MUA 1815If you are writing a new MUA package, or maintaining an existing MUA
1812package, you should make it conform to this interface so that your users 1816package, you should make it conform to this interface so that your users
1813will be able to link Supercite easily and seamlessly. To do this, when 1817will be able to link Supercite easily and seamlessly. To do this, when
1814setting up a reply or forward buffer, your MUA should follow these 1818setting up a reply or forward buffer, your MUA should follow these
1815steps: 1819steps:
1816 1820
1817@enumerate 1821@enumerate
1818@item 1822@item
1819Insert the original message, including the mail headers into the reply 1823Insert the original message, including the mail headers into the reply
1820buffer. At this point you should not modify the raw text in any way 1824buffer. At this point you should not modify the raw text in any way
1821(except for any necessary decoding, e.g., of quoted-printable text), and 1825(except for any necessary decoding, e.g., of quoted-printable text), and
1822you should place all the original headers into the body of the reply. 1826you should place all the original headers into the body of the reply.
1823This means that many of the mail headers will be duplicated, one copy 1827This means that many of the mail headers will be duplicated, one copy
@@ -1826,7 +1830,7 @@ there will probably be more headers below this line.@refill
1826 1830
1827@item 1831@item
1828Set @samp{point} to the beginning of the line containing the first mail 1832Set @samp{point} to the beginning of the line containing the first mail
1829header in the body of the reply. Set @samp{mark} at the end of the 1833header in the body of the reply. Set @samp{mark} at the end of the
1830message text. It is very important that the region be set around the 1834message text. It is very important that the region be set around the
1831text Supercite is to modify and that the mail headers are within this 1835text Supercite is to modify and that the mail headers are within this
1832region. Supercite will not venture outside the region for any reason, 1836region. Supercite will not venture outside the region for any reason,
@@ -1834,7 +1838,7 @@ and anything within the region is fair game, so don't put anything that
1834@strong{must} remain unchanged inside the region.@refill 1838@strong{must} remain unchanged inside the region.@refill
1835 1839
1836@item 1840@item
1837Run the hook @code{mail-citation-hook}. You will probably want to 1841Run the hook @code{mail-citation-hook}. You will probably want to
1838provide some kind of default citation functions in cases where the user 1842provide some kind of default citation functions in cases where the user
1839does not have Supercite installed. By default, your MUA should 1843does not have Supercite installed. By default, your MUA should
1840@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your 1844@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
@@ -1853,9 +1857,9 @@ this interface ``out of the box.''
1853 1857
1854The Supercite package was derived from its predecessor Superyank 1.11 1858The Supercite package was derived from its predecessor Superyank 1.11
1855which was inspired by various bits of code and ideas from Martin Neitzel 1859which was inspired by various bits of code and ideas from Martin Neitzel
1856and Ashwin Ram. They were the folks who came up with the idea of 1860and Ashwin Ram. They were the folks who came up with the idea of
1857non-nested citations and implemented some rough code to provide this 1861non-nested citations and implemented some rough code to provide this
1858style. Superyank and Supercite version 2 evolved to the point where much 1862style. Superyank and Supercite version 2 evolved to the point where much
1859of the attribution selection mechanism was automatic, and features have 1863of the attribution selection mechanism was automatic, and features have
1860been continuously added through the comments and suggestions of the 1864been continuously added through the comments and suggestions of the
1861Supercite mailing list participants. 1865Supercite mailing list participants.