C-x 5 1
[emacs.git] / man / sc.texi
bloba940dcd8fb95dee06c4428d08a7a9935df9693ef
1 \input texinfo  @comment -*-texinfo-*-
2 @comment 3.47
3 @comment %**start of header (This is for running Texinfo on a region.)
4 @setfilename ../info/sc
5 @settitle Supercite Version 3.1 User's Manual
6 @iftex
7 @finalout
8 @end iftex
10 @dircategory Emacs
11 @direntry
12 * SC: (sc).             Supercite lets you cite parts of messages you're 
13                           replying to, in flexible ways.
14 @end direntry
16 @c @setchapternewpage odd               % For book style double sided manual.
17 @comment %**end of header (This is for running Texinfo on a region.)
18 @c      @smallbook
19 @tex
20 \overfullrule=0pt
21 %\global\baselineskip 30pt      % For printing in double spaces
22 @end tex
23 @ifinfo
24 This document describes the Supercite Version 3.1 package for citing and
25 attributing the replies for various GNU Emacs mail and news reading
26 subsystems.
28 Copyright @copyright{} 1993 Barry A@. Warsaw
30 Permission is granted to make and distribute verbatim copies of
31 this manual provided the copyright notice and this permission notice
32 are preserved on all copies.
34 @ignore
35 Permission is granted to process this file through TeX and print the
36 results, provided the printed document carries copying permission
37 notice identical to this one except for the removal of this paragraph
38 (this paragraph not being relevant to the printed manual).
40 @end ignore
41 @end ifinfo
43 @titlepage
44 @sp 6
45 @center @titlefont{Supercite User's Manual}
46 @sp 2
47 @center @titlefont{Supercite Version 3.1}
48 @sp 4
49 @center Manual Revision: 3.47
50 @center August 1993
51 @sp 5
52 @center Barry A@. Warsaw
53 @center @t{bwarsaw@@cen.com}
54 @center @t{@dots{}!uunet!cen.com!bwarsaw}
55 @page
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 1993 Barry A@. Warsaw
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
63 @end titlepage
64 @page
65 @ifinfo
66 @node Top, Introduction, (dir), (dir)
67 @comment  node-name,  next,  previous,  up
69 This document describes the Supercite Version 3.1 package for citing and
70 attributing the replies for various GNU Emacs mail and news reading
71 subsystems.  The manual is divided into the following chapters.
73 @menu
74 * Introduction::
75 * Citations::
76 * Getting Connected::
77 * Replying and Yanking::
78 * Selecting an Attribution::
79 * Configuring the Citation Engine::
80 * Post-yank Formatting Commands::
81 * Information Keys and the Info Alist::
82 * Reference Headers::
83 * Hints to MUA Authors::
84 * Version 3 Changes::
85 * Thanks and History::
86 * The Supercite Mailing List::
88 * Concept Index::
89 * Command Index::
90 * Key Index::
91 * Variable Index::
92 @end menu
93 @end ifinfo
95 @node  Introduction, Usage Overview, Top, Top
96 @comment  node-name,  next,  previous,  up
97 @chapter Introduction
98 @ifinfo
100 @end ifinfo
101 Supercite version 3.1 is a GNU Emacs package written entirely in Emacs
102 Lisp. It interfaces to most of the commonly used Emacs mail user agents
103 (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
104 sophisticated facilities for the citing and attributing of message
105 replies.  Supercite has a very specific and limited role in the process
106 of composing replies to both USENET network news and electronic mail.
108 The preferred way to spell Supercite is with a capital @samp{S},
109 lowercase @samp{upercite}.  There are a few alternate spellings out there
110 and I won't be terribly offended if you use them.  People often ask
111 though@dots{}
113 @ifinfo
114 @menu
115 * Usage Overview::
116 * What Supercite Does Not Do::
117 * What Supercite Does::
118 @end menu
119 @end ifinfo
121 @cindex MUA
122 @cindex NUA
123 Supercite is only useful in conjunction with MUAs and NUAs such as VM,
124 GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs).
125 Supercite is typically called by the MUA after a reply buffer has been
126 setup.  Thereafter, Supercite's many commands and formatting styles are
127 available in that reply buffer until the reply is sent.  Supercite is
128 re-initialized in each new reply buffer.
130 Supercite is currently at major revision 3.1, and is known to work in the
131 following environments:
133 @table @asis
134 @item Emacs versions:
135         GNU Emacs 18.57 through 18.59, all Emacs 19,
136         all current Lucid Emacs, and Epoch 4.@refill
138 @item MUAs:
139         VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
140         beyond, PCMAIL.@refill
142 @item NUAs:
143         RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
145 @end table
146 For systems with version numbers, all known subsequent versions also
147 work with Supercite.  For those systems without version numbers,
148 Supercite probably works with any recently released version.  Note that
149 only some of these systems will work with Supercite ``out of the box.''
150 All others must overload interfacing routines to supply the necessary
151 glue.  @xref{Getting Connected}, for more details.@refill
154 @node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
155 @comment  node-name,  next,  previous,  up
156 @kindex r
157 @kindex f
158 @kindex C-c C-y
159 @cindex yank
160 @cindex cite, citing
161 @cindex attribute, attributing
162 @comment
163 @section Usage Overview
164 @ifinfo
166 @end ifinfo
167 Typical usage is as follows. You want to reply or followup to a message
168 in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
169 (i.e., ``forward'') to begin composing the reply.  In response, the MUA
170 will create a reply buffer and initialize the outgoing mail headers
171 appropriately.  The body of the reply will usually be empty at this
172 point.  You now decide that you would like to include part of the
173 original message in your reply. To do this, you @dfn{yank} the original
174 message into the reply buffer, typically with a key stroke such as
175 @kbd{C-c C-y}.  This sequence will invoke an MUA-specific function which
176 fills the body of the reply with the original message and then
177 @dfn{attributes} this text to its author.  This is called @dfn{citing}
178 and its effect is to prefix every line from the original message with a
179 special text tag.  Most MUAs provide some default style of citing; by
180 using Supercite you gain a wider flexibility in the look and style of
181 citations.  Supercite's only job is to cite the original message.
183 @node  What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
184 @comment  node-name,  next,  previous,  up
185 @section What Supercite Doesn't Do
186 @ifinfo
188 @end ifinfo
189 Because of this clear division of labor, there are useful features which
190 are the sole responsibility of the MUA, even though it might seem that
191 Supercite should provide them.  For example, many people would like to
192 be able to yank (and cite) only a portion of the original message.
193 Since Supercite only modifies the text it finds in the reply buffer as
194 set up by the MUA, it is the MUA's responsibility to do partial yanking.
195 @xref{Reply Buffer Initialization}.@refill
197 @vindex mail-header-separator
198 @comment
199 Another potentially useful thing would be for Supercite to set up the
200 outgoing mail headers with information it gleans from the reply buffer.
201 But by previously agreed upon convention, any text above the
202 @code{mail-header-separator} which separates mail headers from message
203 bodies cannot be modified by Supercite.  Supercite, in fact, doesn't
204 know anything about the meaning of these headers, and never ventures
205 outside the designated region. @xref{Hints to MUA Authors}, for more
206 details.@refill
208 @node  What Supercite Does, Citations, What Supercite Does Not Do, Introduction
209 @comment  node-name,  next,  previous,  up
210 @findex sc-cite-original
211 @section What Supercite Does
212 @ifinfo
214 @end ifinfo
215 Supercite is invoked for the first time on a reply buffer via your MUA's
216 reply or forward command.  This command will actually perform citations
217 by calling a hook variable to which Supercite's top-level function
218 @code{sc-cite-original} has been added.  When @code{sc-cite-original} is
219 executed, the original message must be set up in a very specific way,
220 but this is handled automatically by the MUA.  @xref{Hints to MUA
221 Authors}.@refill
223 @cindex info alist
224 The first thing Supercite does, via @code{sc-cite-original}, is to parse
225 through the original message's mail headers.  It saves this data in an
226 @dfn{information association list}, or @dfn{info alist}.  The information
227 in this list is used in a number of places throughout Supercite.
228 @xref{Information Keys and the Info Alist}.@refill
230 @cindex nuking mail headers
231 @cindex reference header
232 After the mail header info is extracted, the headers are optionally
233 removed (@dfn{nuked}) from the reply.  Supercite then writes a
234 @dfn{reference header} into the buffer.  This reference header is a
235 string carrying details about the citation it is about to perform.
237 @cindex modeline
238 Next, Supercite visits each line in the reply, transforming the line
239 according to a customizable ``script''.  Lines which were not previously
240 cited in the original message are given a citation, while already cited
241 lines remain untouched, or are coerced to your preferred style.
242 Finally, Supercite installs a keymap into the reply buffer so that you
243 have access to Supercite's post-yank formatting and reciting commands as
244 you subsequently edit your reply.  You can tell that Supercite has been
245 installed into the reply buffer because that buffer's modeline will
246 display the minor mode string @samp{SC}.
248 @cindex filladapt
249 @cindex gin-mode
250 @vindex fill-prefix
251 @findex fill-paragraph
252 @comment
253 When the original message is cited by @code{sc-cite-original}, it will
254 (optionally) be filled by Supercite.  However, if you manually edit the
255 cited text and want to re-fill it, you must use an add-on package such
256 as @cite{filladapt} or @cite{gin-mode}.  These packages can recognize
257 Supercited text and will fill them appropriately.  Emacs' built-in
258 filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
259 text and will not re-fill them properly because it cannot guess the
260 @code{fill-prefix} being used.
261 @xref{Post-yank Formatting Commands}, for details.@refill
263 As mentioned above, Supercite provides commands to recite or uncite
264 regions of text in the reply buffer, and commands to perform other
265 beautifications on the cited original text, maintaining consistent and
266 informative citations throughout.  Supercite tries to be as configurable
267 as possible to allow for a wide range of personalized citation styles,
268 but it is also immediately useful with the default configuration, once
269 it has been properly connected to your MUA.  @xref{Getting Connected},
270 for more details.@refill
272 @node  Citations, Citation Elements, What Supercite Does, Top
273 @comment  node-name,  next,  previous,  up
274 @cindex nested citations
275 @cindex citation
276 @comment
277 @chapter Citations
278 @ifinfo
280 @end ifinfo
281 A @dfn{citation} is the acknowledgement of the original author of a mail
282 message in the body of the reply.  There are two basic citation styles
283 which Supercite supports.  The first, called @dfn{nested citations} is
284 an anonymous form of citation; in other words, an indication is made
285 that the cited line was written by someone @emph{other} that the current
286 message author (i.e., other than you, the person composing the reply),
287 but no reference is made as to the identity of the original author.
288 This style should look familiar since its use on the net is widespread.
289 Here's an example of what a message buffer would look like using nested
290 citations after multiple replies:
292 @example
293 >> John originally wrote this
294 >> and this as well
295 > Jane said that John didn't know
296 > what he was talking about
297 And that's what I think too.
298 @end example
300 @ifinfo
301 @menu
302 * Citation Elements::
303 * Recognizing Citations::
304 @end menu
305 @end ifinfo
307 Note that multiple inclusions of the original messages result in a
308 nesting of the @samp{@code{>}} characters.  This can sometimes be quite
309 confusing when many levels of citations are included since it may be
310 difficult or impossible to figure out who actually participated in the
311 thread, and multiple nesting of @samp{@code{>}} characters can sometimes
312 make the message very difficult for the eye to scan.
314 @cindex non-nested citations
315 In @dfn{non-nested citations}, each cited line begins with an
316 informative string attributing that line to the original author. Only
317 the first level of attribution will be shown; subsequent citations don't
318 nest the citation strings. The above dialog might look like this when
319 non-nested citations are used:
321 @example
322 John> John originally wrote this
323 John> and this as well
324 Jane> Jane said that John didn't know
325 Jane> what he was talking about
326 And that's what I think too.
327 @end example
329 Notice here that my inclusion of Jane's inclusion of John's original
330 message did not result in a line cited with @samp{Jane>John>}.
332 @vindex sc-nested-citation-p
333 @vindex nested-citation-p (sc-)
334 Supercite supports both styles of citation, and the variable
335 @code{sc-nested-citation-p} controls which style it will use when citing
336 previously uncited text. When this variable is @code{nil} (the default),
337 non-nested citations are used.  When non-@code{nil}, nested citations
338 are used.
341 @node  Citation Elements, Recognizing Citations, Citations, Citations
342 @comment  node-name,  next,  previous,  up
343 @cindex citation string
344 @comment
345 @section Citation Elements
346 @ifinfo
348 @end ifinfo
349 @dfn{Citation strings} are composed of one or more elements. Non-nested
350 citations are composed of four elements, three of which are directly
351 user definable.  The elements are concatenated together, in this order:
353 @cindex citation leader
354 @vindex citation-leader (sc-)
355 @vindex sc-citation-leader
356 @enumerate
357 @item
358 The @dfn{citation leader}.  The citation leader is contained in the
359 variable @code{sc-citation-leader}, and has the default value of a
360 string containing four spaces.
362 @cindex attribution string
363 @item
364 The @dfn{attribution string}.  This element is supplied automatically by
365 Supercite, based on your preferences and the original message's mail
366 headers, though you may be asked to confirm Supercite's choice.
367 @xref{Selecting an Attribution}, for more details.@refill
369 @cindex citation delimiter
370 @vindex sc-citation-delimiter
371 @vindex citation-delimiter (sc-)
372 @item
373 The @dfn{citation delimiter}.  This string, contained in the variable
374 @code{sc-citation-delimiter} visually separates the citation from the
375 text of the line.  This variable has a default value of @code{">"} and
376 for best results, the string should consist of only a single character.
378 @cindex citation separator
379 @vindex citation-separator (sc-)
380 @vindex sc-citation-separator
381 @item
382 The @dfn{citation separator}.  The citation separator is contained in
383 the variable @code{sc-citation-separator}, and has the default value of
384 a string containing a single space.
385 @end enumerate
387 For example, suppose you were using the default values for the above
388 variables, and Supercite provided the attribution string @samp{Jane}.
389 In this case, the composed, non-nested citation string used might be
390 something like
391 @code{@asis{"    Jane> "}}.
392 This citation string will be inserted in front of
393 every line in the original message that is not already cited.@refill
395 Nested citations, being simpler than non-nested citations, are composed
396 of the same elements, sans the attribution string.  Supercite is smart
397 enough to not put additional spaces between citation delimiters for
398 multi-level nested citations.
400 @node  Recognizing Citations, Getting Connected, Citation Elements, Citations
401 @comment  node-name,  next,  previous,  up
402 @section Recognizing Citations
403 @ifinfo
405 @end ifinfo
406 Supercite also recognizes citations in the original article, and can
407 transform these already cited lines in a number of ways. This is how
408 Supercite suppresses the multiple citing of non-nested citations.
409 Recognition of cited lines is controlled by variables analogous to those
410 that make up the citation string as mentioned previously.
412 @vindex sc-citation-leader-regexp
413 @vindex citation-leader-regexp (sc-)
414 @vindex sc-citation-delimiter-regexp
415 @vindex citation-delimiter-regexp (sc-)
416 @vindex sc-citation-separator-regexp
417 @vindex citation-separator-regexp (sc-)
418 @vindex sc-citation-root-regexp
419 @vindex citation-root-regexp (sc-)
420 @vindex sc-citation-nonnested-root-regexp
421 @vindex citation-nonnested-root-regexp (sc-)
423 The variable @code{sc-citation-leader-regexp} describes how citation
424 leaders can look, by default it matches any number of spaces or tabs.
425 Note that since the lisp function @code{looking-at} is used to do the
426 matching, if you change this variable it need not start with a leading
427 @code{"^"}.
429 Similarly, the variables @code{sc-citation-delimiter-regexp} and
430 @code{sc-citation-separator-regexp} respectively describe how citation
431 delimiters and separators can look.  They follow the same rule as
432 @code{sc-citation-leader-regexp} above.
434 When Supercite composes a citation string, it provides the attribution
435 automatically.  The analogous variable which handles recognition of the
436 attribution part of citation strings is @code{sc-citation-root-regexp}.
437 This variable describes the attribution root for both nested and
438 non-nested citations.  By default it can match zero-to-many alphanumeric
439 characters (also ``.'', ``-'', and ``_'').  But in some situations,
440 Supercite has to determine whether it is looking at a nested or
441 non-nested citation.  Thus the variable
442 @code{sc-citation-nonnested-root-regexp} is used to describe only
443 non-nested citation roots.  It is important to remember that if you
444 change @code{sc-citation-root-regexp} you should always also change
445 @code{sc-citation-nonnested-root-regexp}.@refill
447 @node  Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
448 @comment  node-name,  next,  previous,  up
449 @cindex information keys
450 @cindex Info Alist
451 @cindex information extracted from mail fields
452 @findex sc-mail-field
453 @findex mail-field (sc-)
454 @comment
455 @chapter Information Keys and the Info Alist
456 @ifinfo
458 @end ifinfo
459 @dfn{Mail header information keys} are nuggets of information that
460 Supercite extracts from the various mail headers of the original
461 message, placed in the reply buffer by the MUA.  Information is kept in
462 the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
463 various places within Supercite, such as in header rewrite functions and
464 attribution selection.  Other bits of data, composed and created by
465 Supercite, are also kept as key-value pairs in this alist. In the case
466 of mail fields, the key is the name of the field, omitting the trailing
467 colon.  Info keys are always case insensitive (as are mail headers), and
468 the value for a corresponding key can be retrieved from the alist with
469 the @code{sc-mail-field} function.  Thus, if the following fields were
470 present in the original article:@refill
472 @example
473 Date:@: 08 April 1991, 17:32:09 EST
474 Subject:@: Better get out your asbestos suit
475 @end example
477 @vindex sc-mumble
478 @vindex mumble (sc-)
479 @noindent
480 then, the following lisp constructs return:
482 @example
483 (sc-mail-field "date")
484 ==> "08 April 1991, 17:32:09 EST"
486 (sc-mail-field "subject")
487 ==> "Better get out your asbestos suit"
488 @end example
490 Since the argument to @code{sc-mail-field} can be any string, it is
491 possible that the mail field will not be present on the info alist
492 (possibly because the mail header was not present in the original
493 message). In this case, @code{sc-mail-field} will return the value of
494 the variable @code{sc-mumble}.
496 Supercite always places all mail fields found in the yanked original
497 article into the info alist.  If possible, Supercite will also places
498 the following keys into the info alist:
500 @table @code
501 @cindex sc-attribution info field
502 @cindex attribution info field (sc-)
503 @item "sc-attribution"
504 the selected attribution string.
506 @cindex sc-citation info field
507 @cindex citation info field (sc-)
508 @item "sc-citation"
509 the non-nested citation string.
511 @cindex sc-from-address info field
512 @cindex from-address info field (sc-)
513 @item "sc-from-address"
514 email address extracted from the @samp{From:@:} field.
516 @cindex sc-reply-address info field
517 @cindex reply-address info field (sc-)
518 @item "sc-reply-address"
519 email address extracted from the @samp{Reply-To:@:} field.
521 @cindex sc-sender-address info field
522 @cindex sender-address info field (sc-)
523 @item "sc-sender-address"
524 email address extracted from the @samp{Sender:@:} field.
526 @cindex sc-emailname info field
527 @cindex emailname info field (sc-)
528 @item "sc-emailname"
529 email terminus extracted from the @samp{From:@:} field.
531 @cindex sc-initials info field
532 @cindex initials info field (sc-)
533 @item "sc-initials"
534 the author's initials.
536 @cindex sc-author info field
537 @cindex author info field (sc-)
538 @item "sc-author"
539 the author's full name.
541 @cindex sc-firstname info field
542 @cindex firstname info field (sc-)
543 @item "sc-firstname"
544 the author's first name.
546 @cindex sc-lastname info field
547 @cindex lastname info field (sc-)
548 @item "sc-lastname"
549 the author's last name.
551 @cindex sc-middlename-1 info field
552 @cindex middlename-1 info field (sc-)
553 @item "sc-middlename-1"
554 the author's first middle name.
555 @end table
557 If the author's name has more than one middle name, they will appear as
558 info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
559 @dots{}).  @xref{Selecting an Attribution}.@refill
561 @node  Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
562 @comment  node-name,  next,  previous,  up
563 @cindex reference headers
564 @chapter Reference Headers
565 @ifinfo
567 @end ifinfo
568 Supercite will insert an informative @dfn{reference header} at the
569 beginning of the cited body of text, which display more detail about the
570 original article and provides the mapping between the attribution and
571 the original author in non-nested citations.  Whereas the citation
572 string usually only contains a portion of the original author's name,
573 the reference header can contain such information as the author's full
574 name, email address, the original article's subject, etc.  In fact any
575 information contained in the info alist can be inserted into a reference
576 header.
578 @ifinfo
579 @menu
580 * The Built-in Header Rewrite Functions::
581 * Electric References::
582 @end menu
583 @end ifinfo
585 @cindex header rewrite functions
586 @vindex sc-rewrite-header-list
587 @vindex rewrite-header-list (sc-)
588 There are a number of built-in @dfn{header rewrite functions} supplied
589 by Supercite, but you can write your own custom header rewrite functions
590 (perhaps using the built-in ones as examples). The variable
591 @code{sc-rewrite-header-list} contains the list of such header rewrite
592 functions.  This list is consulted both when inserting the initial
593 reference header, and when displaying @dfn{electric references}.
594 @xref{Electric References}.
596 @vindex sc-preferred-header-style
597 @vindex preferred-header-style (sc-)
598 When Supercite is initially run on a reply buffer (via
599 @code{sc-cite-original}), it will automatically call one of these
600 functions. The one it uses is defined in the variable
601 @code{sc-preferred-header-style}.  The value of this variable is an
602 integer which is an index into the @code{sc-rewrite-header-list},
603 beginning at zero.
605 @node  The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
606 @comment  node-name,  next,  previous,  up
607 @cindex header rewrite functions, built-in
608 @comment
609 @section The Built-in Header Rewrite Functions
610 @ifinfo
612 @end ifinfo
613 Below are examples of the various built-in header rewrite functions.
614 Please note the following:@: first, the text which appears in the
615 examples below as @var{infokey} indicates that the corresponding value
616 of the info key from the info alist will be inserted there.
617 (@pxref{Information Keys and the Info Alist}).  For example, in @code{sc-header-on-said}
618 below, @var{date} and @var{from} correspond to the values of the
619 @samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill
621 @vindex sc-reference-tag-string
622 @vindex reference-tag-string (sc-)
623 Also, the string @code{">>>>>"} below is really the value of the
624 variable @code{sc-reference-tag-string}.  This variable is used in all
625 built-in header rewrite functions, and you can customize its value to
626 change the tag string globally.
628 Finally, the references headers actually written may omit certain parts
629 of the header if the info key associated with @var{infokey} is not
630 present in the info alist.  In fact, for all built-in headers, if the
631 @samp{From:@:} field is not present in the mail headers, the entire
632 reference header will be omitted (but this usually signals a serious
633 problem either in your MUA or in Supercite's installation).
635 @table @code
636 @findex sc-no-header
637 @findex no-header (sc-)
638 @item sc-no-header
639 This function produces no header. It should be used instead of
640 @code{nil} to produce a blank header.  This header can possibly contain
641 a blank line after the @code{mail-header-separator} line.
643 @item sc-no-blank-line-or-header
644 @findex sc-no-blank-line-or-header
645 @findex no-blank-line-or-header (sc-)
646 This function is similar to @code{sc-no-header} except that any blank
647 line after the @code{mail-header-separator} line will be removed.
649 @item sc-header-on-said
650 @findex sc-header-on-said
651 @findex header-on-said (sc-)
652 @code{>>>>> On @var{date}, @var{from} said:}
654 @item sc-header-inarticle-writes
655 @findex sc-header-inarticle-writes
656 @findex header-inarticle-writes (sc-)
657 @code{>>>>> In article @var{message-id}, @var{from} writes:}
659 @item sc-header-regarding-adds
660 @findex sc-header-regarding-adds
661 @findex header-regarding-adds (sc-)
662 @code{>>>>> Regarding @var{subject}; @var{from} adds:}
664 @item sc-header-attributed-writes
665 @findex sc-header-attributed-writes
666 @findex header-attributed-writes (sc-)
667 @code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:}
669 @item sc-header-author-writes
670 @findex sc-header-author-writes
671 @findex header-author-writes (sc-)
672 @code{>>>>> @var{sc-author} writes:}
674 @item sc-header-verbose
675 @findex sc-header-verbose
676 @findex header-verbose (sc-)
677 @code{>>>>> On @var{date},}@*
678 @code{>>>>> @var{sc-author}}@*
679 @code{>>>>> from the organization of @var{organization}}@*
680 @code{>>>>> who can be reached at:@: @var{sc-reply-address}}@*
681 @code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@*
682 @code{>>>>> had this to say in article @var{message-id}}@*
683 @code{>>>>> in newsgroups @var{newsgroups}}@*
684 @code{>>>>> concerning the subject of @var{subject}}@*
685 @code{>>>>> see @var{references} for more details}
686 @end table
688 @node  Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
689 @comment  node-name,  next,  previous,  up
690 @cindex electric references
691 @section Electric References
692 @ifinfo
694 @end ifinfo
695 By default, when Supercite cites the original message for the first
696 time, it just goes ahead and inserts the reference header indexed by
697 @code{sc-preferred-header-style}.  However, you may want to select
698 different reference headers based on the type of reply or forwarding you
699 are doing. You may also want to preview the reference header before
700 deciding whether to insert it into the reply buffer or not. Supercite
701 provides an optional @dfn{electric reference} mode which you can drop
702 into to give you this functionality.
704 @vindex sc-electric-references-p
705 @vindex electric-references-p (sc-)
706 If the variable @code{sc-electric-references-p} is non-@code{nil},
707 Supercite will bring up an electric reference mode buffer and place you
708 into a recursive edit.  The electric reference buffer is read-only, so
709 you cannot directly modify the reference text until you exit electric
710 references and insert the text into the reply buffer.  But you can cycle
711 through all the reference header rewrite functions in your
712 @code{sc-rewrite-header-list}.
714 You can also set a new preferred header style, jump to any header, or
715 jump to the preferred header. The header will be shown in the electric
716 reference buffer and the header index and function name will appear in
717 the echo area.
719 The following commands are available while in electric reference mode
720 (shown here with their default key bindings):
722 @table @asis
723 @item @code{sc-eref-next} (@kbd{n})
724 @findex sc-eref-next
725 @findex eref-next (sc-)
726 @kindex n
727 @vindex sc-electric-circular-p
728 @vindex electric-circular-p (sc-)
729 Displays the next reference header in the electric reference buffer. If
730 the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
731 @code{sc-eref-next} while viewing the last reference header in the list
732 will wrap around to the first header.@refill
734 @item @code{sc-eref-prev} (@kbd{p})
735 @findex sc-eref-prev
736 @findex eref-prev (sc-)
737 @kindex p
738 Displays the previous reference header in the electric reference buffer.
739 If the variable @code{sc-electric-circular-p} is non-@code{nil},
740 invoking @code{sc-eref-prev} will wrap around to the last header.@refill
742 @item @code{sc-eref-goto} (@kbd{g})
743 @findex sc-eref-goto
744 @findex eref-goto (sc-)
745 @kindex g
746 Goes to a specified reference header.  The index (into the
747 @code{sc-rewrite-header-list}) can be specified as a numeric argument to
748 the command.  Otherwise, Supercite will query you for the index in the
749 minibuffer.@refill
751 @item @code{sc-eref-jump} (@kbd{j})
752 @findex sc-eref-jump
753 @findex eref-jump (sc-)
754 @kindex j
755 Display the preferred reference header, i.e., the one indexed by the current
756 value of @code{sc-preferred-header-style}.
758 @item @code{sc-eref-setn} (@kbd{s})
759 @findex sc-eref-setn
760 @findex eref-setn (sc-)
761 @kindex s
762 Set the preferred reference header (i.e.,
763 @code{sc-preferred-header-style}) to the currently displayed header.@refill
765 @item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c})
766 @kindex RET
767 @kindex C-j
768 @kindex q
769 @findex sc-eref-exit
770 @findex eref-exit (sc-)
771 Exit from electric reference mode and insert the current header into the
772 reply buffer.@refill
774 @item @code{sc-eref-abort} (@kbd{q}, @kbd{x})
775 @findex sc-eref-abort
776 @findex eref-abort (sc-)
777 @kindex x
778 Exit from electric reference mode without inserting the current header.
779 @end table
781 @vindex sc-electric-mode-hook
782 @vindex electric-mode-hook (sc-)
783 @noindent
784 Supercite will execute the hook @code{sc-electric-mode-hook} before
785 entering electric reference mode.
787 @node  Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top
788 @comment  node-name,  next,  previous,  up
789 @cindex citation interface specification
790 @chapter Getting Connected
791 @ifinfo
793 @end ifinfo
794 Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
795 original message into the reply buffer.  In reality, the citation of the
796 original message is performed via a call through a configurable hook
797 variable.  The name of this variable has been agreed to in advance as
798 part of the @dfn{citation interface specification}.  By default this
799 hook variable has a @code{nil} value, which the MUA recognizes to mean,
800 ``use your default citation function''.  When you add Supercite's
801 citation function to the hook, thereby giving the variable a
802 non-@code{nil} value, it tells the MUA to run the hook via
803 @code{run-hooks} instead of using the default citation.@refill
805 @ifinfo
806 @menu
807 * Emacs 19 MUAs::
808 * Emacs 18 MUAs::
809 * MH-E with any Emacsen::
810 * VM with any Emacsen::
811 * GNEWS with any Emacsen::
812 * Overloading for Non-conforming MUAs::
813 @end menu
814 @end ifinfo
816 Early in Supercite's development, the Supercite author, a few MUA
817 authors, and some early Supercite users got together and agreed upon a
818 standard interface between MUAs and citation packages (of which
819 Supercite is currently the only known add-on @t{:-)}.  With the recent
820 release of the Free Software Foundation's GNU Emacs 19, the interface
821 has undergone some modification and it is possible that not all MUAs
822 support the new interface yet.  Some support only the old interface and
823 some do not support the interface at all.  Still, it is possible for all
824 known MUAs to use Supercite, and the following sections will outline the
825 procedures you need to follow.
827 To learn exactly how to connect Supercite to the software systems you
828 are using, read the appropriate following sections.  For details on the
829 interface specifications, or if you are writing or maintaining an MUA,
830 @pxref{Hints to MUA Authors}.
832 @cindex autoload
833 @cindex .emacs file
834 @findex sc-cite-original
835 @findex cite-original (sc-)
836 @findex sc-submit-bug-report
837 @findex submit-bug-report (sc-)
838 The first thing that everyone should do, regardless of the MUA you are
839 using is to set up Emacs so it will load Supercite at the appropriate
840 time.  You can either dump Supercite into your Emacs binary (ask your
841 local Emacs guru how to do this if you don't know), or you can set up an
842 @dfn{autoload} for Supercite.  To do the latter, put the following in
843 your @file{.emacs} file:
845 @example
846 (autoload 'sc-cite-original     "supercite" "Supercite 3.1" t)
847 (autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
848 @end example
850 @cindex point
851 @cindex mark
852 The function @code{sc-cite-original} is the top-level Supercite function
853 designed to be run from the citation hook.  It expects
854 @samp{point} and @samp{mark} to be set around the region to cite, and it
855 expects the original article's mail headers to be present within this
856 region.  Note that Supercite @emph{never} touches any text outside this
857 region.  Note further that for Emacs 19, the region need not be active
858 for @code{sc-cite-original} to do its job.
859 @xref{Hints to MUA Authors}.@refill
861 The other step in the getting connected process is to make sure your
862 MUA calls @code{sc-cite-original} at the right time.  As mentioned
863 above, some MUAs handle this differently.  Read the sections that follow
864 pertaining to the MUAs you are using.
866 @vindex sc-load-hook
867 @vindex load-hook (sc-)
868 @vindex sc-pre-hook
869 @vindex pre-hook (sc-)
870 One final note.  After Supercite is loaded into your Emacs session, it
871 runs the hook @code{sc-load-hook}.  You can put any customizations into
872 this hook since it is only run once.  This will not work, however, if
873 your Emacs maintainer has put Supercite into your dumped Emacs' image.
874 In that case, you can use the @code{sc-pre-hook} variable, but this will
875 get executed every time @code{sc-cite-original} is called.  @xref{Reply
876 Buffer Initialization}.@refill
878 @node   Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected
879 @comment  node-name,  next,  previous,  up
880 @vindex mail-citation-hook
881 @cindex .emacs file
882 @section GNUS, RMAIL, or RNEWS with any Emacs 19
883 @ifinfo
885 @end ifinfo
886 These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
887 built-in yanking facility, which provides the citing hook variable
888 @code{mail-citation-hook}.  By default, this hook's value is @code{nil},
889 but by adding the following to your @file{.emacs} file, you can tell
890 these MUAs to use Supercite to perform the citing of the original
891 message:
893 @example
894 (add-hook 'mail-citation-hook 'sc-cite-original)
895 @end example
897 GNUS users may also want to add the following bit of lisp as well.  This
898 prevents GNUS from inserting its default attribution header.  Otherwise,
899 both GNUS and Supercite will insert an attribution header:
901 @example
902 (setq news-reply-header-hook nil)
903 @end example
905 @node   Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
906 @comment  node-name,  next,  previous,  up
907 @vindex mail-citation-hook
908 @cindex .emacs file
909 @cindex overloading
910 @cindex sendmail.el file
911 @section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
912 @ifinfo
914 @end ifinfo
915 These MUAs use Emacs' built-in yanking and citing routines, contained in
916 the @file{sendmail.el} file.  @file{sendmail.el} for Emacs 18, and its
917 derivative Epoch 4, do not know anything about the citation interface
918 required by Supercite.  To connect Supercite to any of these MUAs under
919 Emacs 18 or Epoch 4, you should first
920 @pxref{Overloading for Non-conforming MUAs}.  Then follow the directions
921 for using these MUAs under Emacs 19.
922 @xref{Emacs 19 MUAs}.@refill
924 @cindex add-hook substitute
925 @cindex setq as a substitute for add-hook
926 @findex setq
927 @findex add-hook
928 @cindex sc-unsupp.el file
929 Note that those instructions will tell you to use the function
930 @code{add-hook}. This function is new with Emacs 19 and you will not
931 have it by default if you are running Emacs 18 or Epoch 4.  You can
932 either substitute the appropriate call to @code{setq}, or you can use
933 the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
934 file of unsupported Supercite hacks and ideas.  Or you can upgrade to
935 some Emacs 19 variant!  @t{:-)}@refill
937 To use @code{setq} instead of @code{add-hook}, you would, for example,
938 change this:
940 @example
941 (add-hook 'mail-citation-hook 'sc-cite-original)
942 @end example
946 @example
947 (setq mail-citation-hook 'sc-cite-original)
948 @end example
950 Note the lack of of a single quote on the first argument to @code{setq}.
952 @node  MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
953 @comment  node-name,  next,  previous,  up
954 @cindex .emacs file
955 @vindex mh-yank-hooks
956 @findex add-hook
957 @cindex mail-citation-hook
958 @section MH-E with any Emacsen
959 @ifinfo
961 @end ifinfo
962 MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
963 by other MUAs.  At the time of this writing, MH-E 4.0 has not been
964 released, but if you have it, put this in your @file{.emacs} file to
965 connect Supercite and MH-E 4.x:
967 @example
968 (add-hook 'mail-citation-hook 'sc-cite-original)
969 @end example
971 Note that if you are using Emacs 18 or Epoch 4, you will not have the
972 @code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
973 proceed without @code{add-hook}.
975 MH-E version 3.x uses a slightly different interface than other MUAs.
976 MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
977 like a hook, and doing an @code{add-hook} will not work.
979 To connect Supercite to MH-E 3.x, you should instead add the following
980 to your @code{.emacs} file:
982 @example
983 (add-hook 'mh-yank-hooks 'sc-cite-original)
984 @end example
986 @vindex mh-yank-from-start-of-msg
987 You also need to make sure that MH-E includes all the original mail
988 headers in the yanked message.  The variable that controls this is
989 @code{mh-yank-from-start-of-msg}.  By default, this variable has the
990 value @code{t}, which tells MH-E to include all the mail headers when
991 yanking the original message.  Before you switched to using Supercite,
992 you may have set this variable to other values so as not to include the
993 mail headers in the yanked message.  Since Supercite requires these
994 headers (and cleans them out for you), you need to make sure the value
995 is @code{t}.  This lisp, in your @file{.emacs} file will do the trick:
997 @example
998 (setq mh-yank-from-start-of-msg t)
999 @end example
1001 Note that versions of MH-E before 3.7 did not provide the
1002 @code{mh-yank-hooks} variable.  Your only option is to upgrade to MH-E
1003 version 3.7 or later.
1005 @node  VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
1006 @comment  node-name,  next,  previous,  up
1007 @cindex .emacs file
1008 @vindex mail-citation-hook
1009 @vindex mail-yank-hooks
1010 @section VM with any Emacsen
1011 @ifinfo
1013 @end ifinfo
1014 Since release 4.40, VM has supported the citation interface required by
1015 Supercite.  But since the interface has changed recently the details of
1016 getting connected differ with the version of VM you are using.
1018 If you are running any release of VM after 4.40, you can add the
1019 following to your @file{.emacs} to connect Supercite with VM:
1021 @example
1022 (add-hook 'mail-yank-hooks 'sc-cite-original)
1023 @end example
1025 Note that if you are using Emacs 18 or Epoch 4, you will not have the
1026 @code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
1027 proceed without @code{add-hook}.
1029 Since version 5.34, VM has supported the newer @code{mail-citation-hook}
1030 interface, but @code{mail-yank-hooks} is still being supported for
1031 backward compatibility.  If you are running a newer version of VM and
1032 you want to maintain consistency with other MUAs, use this bit of code
1033 instead:
1035 @example
1036 (add-hook 'mail-citation-hook 'sc-cite-original)
1037 @end example
1039 @node  GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
1040 @comment  node-name,  next,  previous,  up@cindex .emacs file
1041 @vindex news-reply-mode-hook
1042 @findex sc-perform-overloads
1043 @findex perform-overloads (sc-)
1044 @vindex gnews-ready-hook
1045 @section GNEWS with any Emacsen
1046 @ifinfo
1048 @end ifinfo
1049 As far as I know, no version of GNEWS supports the citation interface
1050 required by Supercite.  To connect Supercite with GNEWS, please first
1051 @pxref{Overloading for Non-conforming MUAs}.
1053 After you have followed the directions in that section.  You should add
1054 the following lisp code to your @file{.emacs} file:
1056 @example
1057 (add-hook 'mail-citation-hook 'sc-cite-original)
1058 @end example
1060 Note that if you are using Emacs 18 or Epoch 4, you will not have the
1061 @code{add-hook} function.  @xref{Emacs 18 MUAs}, for details on how to
1062 proceed without @code{add-hook}.
1064 @node  Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
1065 @comment  node-name,  next,  previous,  up
1066 @cindex overloading
1067 @cindex sc-oloads.el
1068 @vindex mail-citation-hook
1069 @findex sc-perform-overloads
1070 @cindex .emacs file
1071 @section Overloading for Non-conforming MUAs
1072 @ifinfo
1074 @end ifinfo
1075 As mentioned elsewhere, some MUAs do not provide the necessary hooks to
1076 connect with Supercite.  Supercite version 3.1 provides an unsupported
1077 mechanism, called @dfn{overloading} which redefines certain key
1078 functions in the MUA, so that it will call the @code{mail-citation-hook}
1079 variable instead of the MUA's default hard-coded citing routines.  Since
1080 most newer versions of the known MUAs support the
1081 @code{mail-citation-hook} variable, it is recommended that you upgrade
1082 if at all possible.  But if you can't upgrade, at least you're not out
1083 of luck!  Once you set up overloading properly, you should follow the
1084 directions for connecting Supercite to the Emacs 19 MUAs.
1085 @xref{Emacs 19 MUAs}.@refill
1087 @cindex Hyperbole
1088 @vindex hyperb:version
1089 Users of Bob Weiner's Hyperbole package take note.  Hyperbole provides
1090 the necessary overloads (and a whole lot more!) and you can potentially
1091 clobber it if you were to load Supercite's overloading after
1092 Hyperbole's.  For this reason, Supercite will @emph{not} perform any
1093 overloading if it finds the variable @code{hyperb:version} is
1094 @code{boundp} (i.e. it exists because Hyperbole has been loaded into
1095 your Emacs session).  If this is the case, Supercite will display a
1096 warning message in the minibuffer.  You should consult the Hyperbole
1097 manual for further details.
1099 Overloading involves the re-definition of the citing function with the
1100 new, @code{mail-citation-hook} savvy version.  The function in
1101 @file{sc-oloads.el} that does this is @code{sc-perform-overloads}.  This
1102 function is smart enough to only overload the MUA functions when it is
1103 absolutely necessary, based on the version numbers it can figure out.
1104 Also, @code{sc-perform-overloads} will only install the new functions
1105 once.  It is also smart enough to do nothing if the MUA is not yet
1106 loaded.@refill
1108 The tricky part is finding the right time and place to perform the
1109 overloading.  It must be done after the MUA has been loaded into your
1110 Emacs session, but before the first time you try to yank in a message.
1111 Fortunately, this has been figured out for you.
1113 If you must overload, you should put the following lisp code in your
1114 @file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
1115 loaded at the right time:
1117 @example
1118 (autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
1119 @end example
1121 Then you must make sure that the function @code{sc-perform-overloads}
1122 gets run at the right time.  For GNUS, put this in your @file{.emacs}
1123 file:
1125 @example
1126 (setq news-reply-mode-hook 'sc-perform-overloads)
1127 (setq mail-setup-hook 'sc-perform-overloads)
1128 @end example
1130 If you are using RNEWS, put this in your @file{.emacs} file:
1132 @vindex news-reply-mode-hook
1133 @example
1134 (setq news-reply-mode-hook 'sc-perform-overloads)
1135 @end example
1137 If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
1139 @example
1140 (setq mail-setup-hook 'sc-perform-overloads)
1141 @end example
1143 If you are using GNEWS, put this in your @file{.emacs} file:
1145 @example
1146 (setq news-reply-mode-hook 'sc-perform-overloads)
1147 (setq gnews-ready-hook 'sc-perform-overloads)
1148 @end example
1150 Now go back and follow the directions for getting the Emacs 19 MUAs
1151 connected to Supercite.  Be sure to @pxref{Emacs 18 MUAs} on substitutes
1152 for Emacs 19's @code{add-hook} function.@refill
1154 @node  Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
1155 @comment  node-name,  next,  previous,  up
1156 @chapter Replying and Yanking
1157 @ifinfo
1159 This chapter explains what happens when you reply and yank an original
1160 message from an MUA.
1162 @menu
1163 * Reply Buffer Initialization::
1164 * Filling Cited Text::
1165 @end menu
1166 @end ifinfo
1167 @node  Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
1168 @comment  node-name,  next,  previous,  up
1169 @findex sc-cite-original
1170 @findex cite-original (sc-)
1171 @comment
1172 @section Reply Buffer Initialization
1173 @ifinfo
1175 @end ifinfo
1176 Executing @code{sc-cite-original} performs the following steps as it
1177 initializes the reply buffer:
1179 @enumerate
1180 @item 
1181 @vindex sc-pre-hook
1182 @vindex pre-hook (sc-)
1183 @emph{Runs @code{sc-pre-hook}.}
1184 This hook variable is run before @code{sc-cite-original} does any other
1185 work.  You could conceivably use this hook to set certain Supercite
1186 variables based on the reply buffer's mode or name (i.e., to do
1187 something different based on whether you are replying or following up to
1188 an article).@refill
1190 @item
1191 @emph{Inserts Supercite's keymap.}
1192 @vindex sc-mode-map-prefix
1193 @vindex mode-map-prefix (sc-)
1194 @kindex C-c C-p
1195 @cindex keymap prefix
1196 Supercite provides a number of commands for performing post-yank
1197 modifications to the reply buffer.  These commands are installed on
1198 Supercite's top-level keymap.  Since Supercite has to interface with a
1199 wide variety of MUAs, it does not install all of its commands directly
1200 into the reply buffer's keymap.  Instead, it puts its commands on a
1201 keymap prefix, then installs this prefix onto the buffer's keymap.  What
1202 this means is that you typically have to type more characters to invoke
1203 a Supercite command, but Supercite's keybindings can be made much more
1204 consistent across MUAs.
1206 You can control what key Supercite uses as its keymap prefix by changing
1207 the variable @code{sc-mode-map-prefix}.  By default, this variable is
1208 set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the
1209 best default due to the scarcity of available keybindings in many MUAs.
1211 @item
1212 @emph{Turns on Supercite minor mode.}
1213 @cindex modeline
1214 The modeline of the reply buffer should indicate that Supercite is
1215 active in that buffer by displaying the string @samp{SC}.
1217 @item
1218 @emph{Sets the ``Undo Boundary''.}
1219 @cindex undo boundary
1220 Supercite sets an undo boundary before it begins to modify the original
1221 yanked text.  This allows you to easily undo Supercite's changes to
1222 affect alternative citing styles.
1224 @item 
1225 @emph{Processes the mail headers.}
1226 @vindex sc-confirm-always-p
1227 @vindex confirm-always-p (sc-)
1228 @vindex sc-mail-warn-if-non-rfc822-p
1229 @vindex mail-warn-if-non-rfc822-p (sc-)
1230 All previously retrieved info key-value pairs are deleted from the info
1231 alist, then the mail headers in the body of the yanked message are
1232 scanned. Info key-value pairs are created for each header found. Also,
1233 such useful information as the author's name and email address are
1234 extracted.  If the variable @code{sc-mail-warn-if-non-rfc822-p} is
1235 non-@code{nil}, then Supercite will warn you if it finds a mail header
1236 that does not conform to RFC822.  This is rare and indicates a problem
1237 either with your MUA or the original author's MUA, or some MTA (mail
1238 transport agent) along the way.
1240 @vindex sc-nuke-mail-headers
1241 @vindex sc-nuke-mail-header-list
1242 @vindex nuke-mail-headers (sc-)
1243 @vindex nuke-mail-header-list (sc-)
1244 Once the info keys have been extracted from the mail headers, the
1245 headers are nuked from the reply buffer.  You can control exactly which
1246 headers are removed or kept, but by default, all headers are removed.
1248 There are two variables which control mail header nuking.  The variable
1249 @code{sc-nuke-mail-headers} controls the overall behavior of the header
1250 nuking routines.  By setting this variable to @code{'all}, you
1251 automatically nuke all mail headers.  Likewise, setting this variable to
1252 @code{'none} inhibits nuking of any mail headers.  In between these
1253 extremes, you can tell Supercite to nuke only a specified list of mail
1254 headers by setting this variable to @code{'specified}, or to keep only a
1255 specified list of headers by setting it to @code{'keep}.
1257 If @code{sc-nuke-mail-headers} is set to @code{'specified} or
1258 @code{'keep}, then the variable @code{sc-nuke-mail-header-list} is
1259 consulted for the list of headers to nuke or keep.  This variable
1260 contains a list of regular expressions.  If the mail header line matches
1261 a regular expression in this list, the header will be nuked or kept.
1262 The line is matched against the regexp using @code{looking-at} rooted at
1263 the beginning of the line.
1265 @vindex sc-blank-lines-after-headers
1266 @vindex blank-lines-after-headers (sc-)
1267 If the variable @code{sc-blank-lines-after-headers} is non-@code{nil},
1268 it contains the number of blank lines remaining in the buffer after mail
1269 headers are nuked.  By default, only one blank line is left in the buffer.
1271 @item
1272 @emph{Selects the attribution and citation strings.}
1273 Once the mail headers have been processed, Supercite selects a
1274 attribution string and a citation string which it will use to cite the
1275 original message.  @xref{Selecting an Attribution}, for details.
1277 @item 
1278 @emph{Cites the message body.}
1279 @vindex sc-cite-region-limit
1280 @vindex cite-region-limit (sc-)b
1281 After the selection of the attribution and citation strings, Supercite
1282 cites the original message by inserting the citation string prefix in
1283 front of every uncited line.  You may not want Supercite to
1284 automatically cite very long messages however.  For example, some email
1285 could contain a smaller header section followed by a huge uuencoded
1286 message.  It wouldn't make sense to cite the uuencoded message part when
1287 responding to the original author's short preface.  For this reason,
1288 Supercite provides a variable which limits the automatic citation of
1289 long messages to a certain maximum number of lines.  The variable is
1290 called @code{sc-cite-region-limit}.  If this variable contains an
1291 integer, messages with more lines that this will not be cited at all,
1292 and a warning message will be displayed.  Supercite has performed
1293 everything necessary, though, for you to manually cite only the small
1294 portion of the original message that you want to use.
1296 If @code{sc-cite-region-limit} contains a non-@code{nil} value, the
1297 original message will always be cited, regardless of its size.  If the
1298 variable contains the value @code{nil}, the region will never be cited
1299 automatically.  Use this if you always want to be able to edit and cite
1300 the message manually.
1302 @vindex sc-cite-blank-lines-p
1303 @vindex cite-blank-lines-p (sc-)
1304 The variable @code{sc-cite-blank-lines-p} controls whether blank lines
1305 in the original message should be cited or not.  If this variable is
1306 non-@code{nil}, blank lines will be cited just like non-blank lines.
1307 Otherwise, blank lines will be treated as paragraph separators.
1309 Citing of the original message is highly configurable. Supercite's
1310 default setup does a pretty good job of citing many common forms of
1311 previously cited messages.  But there are as many citation styles out
1312 there as people on the net, or just about!  It would be impossible for
1313 Supercite to anticipate every style in existence, and you probably
1314 wouldn't encounter them all anyway.  But you can configure Supercite to
1315 recognize those styles you see often.
1316 @xref{Configuring the Citation Engine}, for details.@refill
1318 @item 
1319 @emph{Runs @code{sc-post-hook}.}
1320 @vindex sc-post-hook
1321 @vindex post-hook (sc-)
1322 This variable is very similar to @code{sc-pre-hook}, except that it runs
1323 after @code{sc-cite-original} is finished. This hook is provided mostly
1324 for completeness and backward compatibility. Perhaps it could be used to
1325 reset certain variables set in @code{sc-pre-hook}.@refill
1326 @end enumerate
1328 @node  Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
1329 @comment  node-name,  next,  previous,  up
1330 @cindex filling paragraphs
1331 @vindex sc-auto-fill-region-p
1332 @vindex auto-fill-region-p (sc-)
1333 @cindex filladapt
1334 @cindex gin-mode
1335 @findex sc-setup-filladapt
1336 @findex setup-filladapt (sc-)
1337 @vindex sc-load-hook
1338 @vindex load-hook (sc-)
1339 @section Filling Cited Text
1340 @ifinfo
1342 @end ifinfo
1343 Supercite will automatically fill newly cited text from the original
1344 message unless the variable @code{sc-auto-fill-region-p} has a
1345 @code{nil} value.  Supercite will also re-fill paragraphs when you
1346 manually cite or re-cite text.
1348 However, during normal editing, Supercite itself cannot be used to fill
1349 paragraphs.  This is a change from version 2.  There are other add-on
1350 lisp packages which do filling much better than Supercite ever did.  The
1351 two best known are @dfn{filladapt} and @dfn{gin-mode}.  Both work well
1352 with Supercite and both are available at the normal Emacs Lisp archive
1353 sites.  @dfn{gin-mode} works pretty well out of the box, but if you use
1354 @dfn{filladapt}, you may want to run the function
1355 @code{sc-setup-filladapt} from your @code{sc-load-hook}.  This simply
1356 makes @dfn{filladapt} a little more Supercite savvy than its default
1357 setup.
1359 @vindex sc-fixup-whitespace-p
1360 @vindex fixup-whitespace-p (sc-)
1361 Also, Supercite will collapse leading whitespace between the citation
1362 string and the text on a line when the variable
1363 @code{sc-fixup-whitespace-p} is non-@code{nil}.  The default value for
1364 this variable is @code{nil}.@refill
1366 @vindex fill-prefix
1367 Its important to understand that Supercite's automatic filling (during
1368 the initial citation of the reply) is very fragile.  That is because
1369 figuring out the @code{fill-prefix} for a particular paragraph is a
1370 really hard thing to do automatically.  This is especially the case when
1371 the original message contains code or some other text where leading
1372 whitespace is important to preserve.  For this reason, many Supercite
1373 users typically run with @code{sc-auto-fill-region-p} (and possibly also
1374 @code{sc-fixup-whitespace-p}) set to @code{nil}.  They then manually
1375 fill each cited paragraph in the reply buffer.
1377 I usually run with both these variables containing their default values.
1378 When Supercite's automatic filling breaks on a particular message, I
1379 will use Emacs' undo feature to undo back before the citation was
1380 applied to the original message.  Then I'll toggle the variables and
1381 manually cite those paragraphs that I don't want to fill or collapse
1382 whitespace on.  @xref{Variable Toggling Shortcuts}.@refill
1384 @kindex C-c C-p C-p
1385 If you find that Supercite's automatic filling is just too fragile for
1386 your tastes, you might consider one of these alternate approaches.
1387 Also, to make life easier, a shortcut function to toggle the state of
1388 both of these variables is provided on the key binding
1389 @kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix};
1390 @pxref{Post-yank Formatting Commands}).@refill
1392 You will noticed that the minor mode string will
1393 show the state of these variables as qualifier characters. When both
1394 variables are @code{nil}, the Supercite minor mode string will display
1395 @samp{SC}.  When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
1396 string will display @samp{SC:f}, and when just
1397 @code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display
1398 @samp{SC:w}.  When both variables are non-@code{nil}, the string will
1399 display @samp{SC:fw}.  Note that the qualifiers chosen are mnemonics for
1400 the default bindings of the toggling function for each respective
1401 variable.
1402 @xref{Variable Toggling Shortcuts}.@refill
1404 Why are these variables not set to @code{nil} by default?  It is because
1405 many users won't manually fill paragraphs that are Supercited, and there
1406 have been widespread complaints on the net about mail and news messages
1407 containing lines greater than about 72 characters.  So the default is to
1408 fill cited text.
1410 @node  Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
1411 @comment  node-name,  next,  previous,  up
1412 @cindex attribution list
1413 @vindex sc-preferred-attribution-list
1414 @vindex preferred-attribution-list (sc-)
1415 @comment
1416 @chapter Selecting an Attribution
1417 @ifinfo
1419 @end ifinfo
1420 As you know, the attribution string is the part of the author's name
1421 that will be used to composed a non-nested citation string. Supercite
1422 scans the various mail headers present in the original article and uses
1423 a number of heuristics to extract strings which it puts into the
1424 @dfn{attribution association list} or @dfn{attribution alist}. This is
1425 analogous, but different than, the info alist previously mentioned. Each
1426 element in the attribution alist is a key-value pair containing such
1427 information as the author's first name, middle names, and last name, the
1428 author's initials, and the author's email terminus.
1430 @ifinfo
1431 @menu
1432 * Attribution Preferences::
1433 * Anonymous Attributions::
1434 * Author Names::
1435 @end menu
1436 @end ifinfo
1438 @node  Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
1439 @comment  node-name,  next,  previous,  up
1440 @section Attribution Preferences
1441 @ifinfo
1443 @end ifinfo
1444 When you cite an original message, you can tell Supercite which part of
1445 the author's name you would prefer it to use as the attribution.  The
1446 variable @code{sc-preferred-attribution-list} controls this; it contains
1447 keys which are matched against the attribution alist in the given order.
1448 The first value of a key that produces a non-@code{nil}, non-empty
1449 string match is used as the attribution string, and if no keys match, a
1450 secondary mechanism is used to generate the attribution.
1451 @xref{Anonymous Attributions}.
1453 The following preferences are always available in the attribution alist
1454 (barring error):
1456 @table @code
1457 @item "emailname"
1458 the author's email terminus.
1460 @item "initials"
1461 the author's initials.
1463 @item "firstname"
1464 the author's first name.
1466 @item "lastname"
1467 the author's last name.
1469 @item "middlename-1"
1470 the author's first middle name.
1472 @item "sc-lastchoice"
1473 the last attribution string you have selected. This is useful when you
1474 recite paragraphs in the reply.@refill
1476 @item "sc-consult"
1477 @vindex sc-attrib-selection-list
1478 @vindex attrib-selection-list (sc-)
1479 consults the customizable list @code{sc-attrib-selection-list} which can
1480 be used to select special attributions based on the value of any info
1481 key.  See below for details.
1483 @item "x-attribution"
1484 the original author's suggestion for attribution string choice. See below
1485 for details.@refill
1486 @end table
1488 Middle name indexes can be any positive integer greater than zero,
1489 though it is unlikely that many authors will have more than one middle
1490 name, if that many.
1492 At this point, let me digress into a discussion of etiquette.  It is my
1493 belief that while the style of the citations is a reflection of the
1494 personal tastes of the replier (i.e., you), the attribution selection is
1495 ultimately the personal choice of the original author.  In a sense it is
1496 his or her ``net nickname'', and therefore the author should have some
1497 say in the selection of attribution string.  Imagine how you would feel
1498 if someone gave you a nickname that you didn't like?
1500 For this reason, Supercite recognizes a special mail header,
1501 @samp{X-Attribution:}, which if present, tells Supercite the attribution
1502 string preferred by the original author.  It is the value of this header
1503 that is associated with the @code{"x-attribution"} key in the
1504 attribution alist.  Currently, you can override the preference of this
1505 key by changing @code{sc-preferred-attribution-list}, but that isn't
1506 polite, and in the future Supercite may hard-code this.  For now, it is
1507 suggested that if you change the order of the keys in this list, that
1508 @code{"x-attribution"} always be first, or possible second behind only
1509 @code{"sc-lastchoice"}.  This latter is the default.
1511 @vindex sc-attrib-selection-list
1512 @vindex attrib-selection-list (sc-)
1513 The value @code{"sc-consult"} in @code{sc-preferred-attribution-list}
1514 has a special meaning during attribution selection.  When Supercite
1515 encounters this preference, it begins processing a customizable list of
1516 attributions, contained in the variable @code{sc-attrib-selection-list}.
1517 Each element in this list contains lists of the following form:
1519 @example
1520 @group
1521 (@var{infokey} ((@var{regexp} @. @var{attribution})
1522          (@var{regexp} @. @var{attribution})
1523          (@dots{})))
1524 @end group
1525 @end example
1527 @noindent
1528 @findex sc-mail-field
1529 @findex mail-field (sc-)
1530 where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
1531 is a regular expression to match against the @var{infokey}'s value. If
1532 @var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
1533 used as the attribution string.  Actually, @var{attribution} can be a
1534 string or a list; if it is a list, it is @code{eval}uated and the return
1535 value (which must be a string), is used as the attribution.
1537 This can be very useful for when you are replying to net acquaintances
1538 who do not use the @samp{X-Attribution:@:} mail header.  You may know
1539 what nickname they would prefer to use, and you can set up this list to
1540 match against a specific mail field, e.g., @samp{From:@:}, allowing you
1541 to cite your friend's message with the appropriate attribution.
1543 @node  Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
1544 @comment  node-name,  next,  previous,  up
1545 @vindex sc-default-author-name
1546 @vindex default-author-name (sc-)
1547 @vindex sc-default-attribution
1548 @vindex default-attribution (sc-)
1549 @comment
1550 @section Anonymous Attributions
1551 @ifinfo
1553 @end ifinfo
1554 When the author's name cannot be found in the @samp{From:@:} mail
1555 header, a fallback author name and attribution string must be supplied.
1556 The fallback author name is contained in the variable
1557 @code{sc-default-author-name} and the fallback attribution string is
1558 contained in the variable @code{sc-default-attribution}.  Default values
1559 for these variables are @code{"Anonymous"} and @code{"Anon"},
1560 respectively. Note that in most circumstances, getting the default
1561 author name or attribution is a sign that something is set up
1562 incorrectly.
1564 @vindex sc-use-only-preference-p
1565 @vindex use-only-preference-p (sc-)
1566 Also, if the preferred attribution, which you specified in your
1567 @code{sc-preferred-attribution-alist} variable cannot be found, a
1568 secondary method can be employed to find a valid attribution string. The
1569 variable @code{sc-use-only-preference-p} controls what happens in this
1570 case.  If the variable's value is non-@code{nil}, then
1571 @code{sc-default-author-name} and @code{sc-default-attribution} are
1572 used, otherwise, the following steps are taken to find a valid
1573 attribution string, and the first step to return a non-@code{nil},
1574 non-empty string becomes the attribution:@refill
1576 @enumerate
1577 @item
1578 Use the last selected attribution, if there is one.
1580 @item
1581 Use the value of the @code{"x-attribution"} key.
1583 @item 
1584 Use the author's first name.
1586 @item
1587 Use the author's last name.
1589 @item
1590 Use the author's initials.
1592 @item 
1593 Find the first non-@code{nil}, non-empty attribution string in the
1594 attribution alist.
1596 @item 
1597 @code{sc-default-attribution} is used.
1598 @end enumerate
1600 @vindex sc-confirm-always-p
1601 @vindex confirm-always-p (sc-)
1602 Once the attribution string has been automatically selected, a number of
1603 things can happen. If the variable @code{sc-confirm-always-p} is
1604 non-@code{nil}, you are queried for confirmation of the chosen
1605 attribution string. The possible values for completion are those strings
1606 in the attribution alist, however you are not limited to these choices.
1607 You can type any arbitrary string at the confirmation prompt. The string
1608 you enter becomes the value associated with the @code{"sc-lastchoice"}
1609 key in the attribution alist.
1611 @vindex sc-downcase-p
1612 @vindex downcase-p (sc-)
1613 Once an attribution string has been selected, Supercite will force the
1614 string to lower case if the variable @code{sc-downcase-p} is
1615 non-@code{nil}.
1617 @vindex sc-attribs-preselect-hook
1618 @vindex attribs-preselect-hook (sc-)
1619 @vindex sc-attribs-postselect-hook
1620 @vindex attribs-postselect-hook (sc-)
1622 Two hook variables provide even greater control of the attribution
1623 selection process.  The hook @code{sc-attribs-preselect-hook} is run
1624 before any attribution is selected.  Likewise, the hook
1625 @code{sc-attribs-postselect-hook} is run after the attribution is
1626 selected (and the corresponding citation string is built), but before
1627 these values are committed for use by Supercite.  During the
1628 post-selection hook, the local variables @code{attribution} and
1629 @code{citation} are bound to the appropriate strings.  By changing these
1630 variables in your hook functions, you change the attribution and
1631 citation strings used by Supercite.  One possible use of this would be
1632 to override any automatically derived attribution string when it is only
1633 one character long; e.g. you prefer to use @code{"initials"} but the
1634 author only has one name.@refill
1636 @node  Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
1637 @comment  node-name,  next,  previous,  up
1638 @cindex author names
1639 @section Author Names
1640 @ifinfo
1642 @end ifinfo
1643 Supercite employs a number of heuristics to decipher the author's name
1644 based on value of the @samp{From:@:} mail field of the original message.
1645 Supercite can recognize almost all of the common @samp{From:@:} field
1646 formats in use.  If you encounter a @samp{From:@:} field that Supercite
1647 cannot parse, please report this bug.
1648 @xref{The Supercite Mailing List}.@refill
1650 @vindex sc-titlecue-regexp
1651 @vindex titlecue-regexp (sc-)
1652 There are a number of Supercite variables that control how author names
1653 are extracted from the @samp{From:@:} header.  Some headers may contain a
1654 descriptive title as in:
1656 @example
1657 From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
1658 @end example
1660 Supercite knows which part of the @samp{From:@:} header is email address
1661 and which part is author name, but in this case the string @code{"Decent
1662 Hacker"} is not part of the author's name.  You can tell Supercite to
1663 ignore the title, while still recognizing hyphenated names through the
1664 use of a regular expression in the variable @code{sc-titlecue-regexp}.
1665 This variable has the default value of @code{"\\\\s +-+\\\\s +"}.  Any
1666 text after this regexp is encountered is ignored as noise.
1668 @vindex sc-name-filter-alist
1669 @vindex name-filter-alist (sc-)
1670 Some @samp{From:@:} headers may contain extra titles in the name fields
1671 not separated by a title cue, but which are nonetheless not part of the
1672 author's name proper.  Examples include the titles ``Dr.'', ``Mr.'',
1673 ``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third).
1674 Also, some companies prepend or append the name of the division,
1675 organization, or project on the author's name.  All of these titles are
1676 noise which should be ignored.  The variable @code{sc-name-filter-alist}
1677 is used for this purpose. As implied by its name, this variable is an
1678 association list, where each element is a cons cell of the form:
1680 @example
1681 (@var{regexp} @. @var{position})
1682 @end example
1684 @noindent
1685 where @var{regexp} is a regular expression that is matched (using
1686 @code{string-match}) against each element of the @samp{From:@:} field's
1687 author name.  @var{position} is a position indicator, starting at zero.
1688 Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
1689 @code{sc-name-filter-alist} would have an entry such as:
1691 @example
1692 ("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
1693 @end example
1695 @noindent
1696 which only removes them if they appear as the first word in the name.
1697 The position indicator is an integer, or one of the two special symbols
1698 @code{last} or @code{any}.  @code{last} always matches against the last
1699 word in the name field, while @code{any} matches against every word in
1700 the name field.
1702 @node  Configuring the Citation Engine, Using Regi, Author Names, Top
1703 @comment  node-name,  next,  previous,  up
1704 @cindex Regi
1705 @cindex frames (Regi)
1706 @cindex entries (Regi)
1707 @chapter Configuring the Citation Engine
1708 @ifinfo
1710 @end ifinfo
1711 At the heart of Supercite is a regular expression interpreting engine
1712 called @dfn{Regi}.  Regi operates by interpreting a data structure
1713 called a Regi-frame (or just @dfn{frame}), which is a list of
1714 Regi-entries (or just @dfn{entry}).  Each entry contains a predicate,
1715 typically a regular expression, which is matched against a line of text
1716 in the current buffer.  If the predicate matches true, an associated
1717 expression is @code{eval}uated.  In this way, an entire region of text
1718 can be transformed in an @emph{awk}-like manner.  Regi is used
1719 throughout Supercite, from mail header information extraction, to header
1720 nuking, to citing text.
1722 @ifinfo
1723 @menu
1724 * Using Regi::
1725 * Frames You Can Customize::
1726 @end menu
1727 @end ifinfo
1729 While the details of Regi are discussed below (@pxref{Using Regi}), only
1730 those who wish to customize certain aspects of Supercite need concern
1731 themselves with it.  It is important to understand though, that any
1732 conceivable citation style that can be described by a regular expression
1733 can be recognized by Supercite.  This leads to some interesting
1734 applications.  For example, if you regularly receive email from a
1735 co-worker that uses an uncommon citation style (say one that employs a
1736 @samp{|} or @samp{@}} character at the front of the line), it is
1737 possible for Supercite to recognize this and @emph{coerce} the citation
1738 to your preferred style, for consistency.  In theory, it is possible for
1739 Supercite to recognize such things as uuencoded messages or C code and
1740 cite or fill those differently than normal text.  None of this is
1741 currently part of Supercite, but contributions are welcome!
1743 @node  Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
1744 @comment  node-name,  next,  previous,  up
1745 @findex regi-interpret
1746 @findex eval
1747 @findex looking-at
1748 @section Using Regi
1749 @ifinfo
1751 @end ifinfo
1752 Regi works by interpreting frames with the function
1753 @code{regi-interpret}.  A frame is a list of arbitrary size where each
1754 element is a entry of the following form:
1756 @example
1757 (@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]])
1758 @end example
1760 Regi starts with the first entry in a frame, evaluating the @var{pred}
1761 of that entry against the beginning of the line that @samp{point} is on.
1762 If the @var{pred} evaluates to true (or false if the optional
1763 @var{negate-p} is non-@code{nil}), then the @var{func} for that entry is
1764 @code{eval}uated.  How processing continues is determined by the return
1765 value for @var{func}, and is described below.  If @var{pred} was false
1766 the next entry in the frame is checked until all entries have been
1767 matched against the current line.  If no entry matches, @samp{point} is
1768 moved forward one line and the frame is reset to the first entry.
1770 @var{pred} can be a string, a variable, a list or one of the following
1771 symbols: @code{t}, @code{begin}, @code{end}, or @code{every}.  If
1772 @var{pred} is a string, or a variable or list that @code{eval}uates to a
1773 string, it is interpreted as a regular expression.  This regexp is
1774 matched against the current line, from the beginning, using
1775 @code{looking-at}.  This match folds case if the optional
1776 @var{case-fold-search} is non-@code{nil}.  If @var{pred} is not a
1777 string, or does not @code{eval}uate to a string, it is interpreted as a
1778 binary value (@code{nil} or non-@code{nil}).@refill
1780 The four special symbol values for @var{pred} are recognized:
1782 @table @code
1783 @item t
1784 Always produces a true outcome.
1785 @item begin
1786 Always executed before the frame is interpreted. This can be used to
1787 initialize some global variables for example.
1788 @item end
1789 Always executed after frame interpreting is completed. This can be used
1790 to perform any necessary post-processing.
1791 @item every
1792 Executes whenever the frame is reset, usually after the entire frame has
1793 been matched against the current line.
1794 @end table
1796 Note that @var{negate-p} and @var{case-fold-search} are ignored if
1797 @var{pred} is one of these special symbols.  Only the first occurrence of
1798 each symbol in a frame is used; any duplicates are ignored.  Also
1799 note that for performance reasons, the entries associated with these
1800 symbols are removed from the frame during the main interpreting loop.
1802 Your @var{func} can return certain values which control continued Regi
1803 processing.  By default, if your @var{func} returns @code{nil} (as it
1804 should be careful to do explicitly), Regi will reset the frame to the
1805 first entry, and advance @samp{point} to the beginning of the next line.
1806 If a list is returned from your function, it can contain any combination
1807 of the following elements:@refill
1809 @table @asis
1810 @item the symbol @code{continue}
1811 This tells Regi to continue processing entries after a match, instead of
1812 reseting the frame and moving @samp{point}. In this way, lines of text
1813 can have multiple matches, but you have to be careful to avoid entering
1814 infinite loops.
1816 @item the symbol @code{abort}
1817 This tells Regi to terminate frame processing. However, any @code{end}
1818 entry is still processed.
1820 @item the list @code{(frame . @var{newframe})}
1821 This tells Regi to substitute @var{newframe} as the frame it is
1822 interpreting.  In other words, your @var{func} can modify the Regi frame
1823 on the fly.  @var{newframe} can be a variable containing a frame, or it
1824 can be the frame in-lined.@refill
1826 @item the list @code{(step . @var{step})}
1827 Tells Regi to move @var{step} number of lines forward as it continues
1828 processing. By default, Regi moves forward one line.  @var{step} can be
1829 zero or negative of course, but watch out for infinite loops.@refill
1830 @end table
1832 During execution of your @var{func}, the following variables will be
1833 temporarily bound to some useful information:@refill
1835 @table @code
1836 @item curline
1837 The current line in the buffer that Regi is @code{looking-at}, as a string.
1838 @item curframe
1839 The current frame being interpreted.
1840 @item curentry
1841 The current frame entry being interpreted.
1842 @end table
1844 @node  Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
1845 @comment  node-name,  next,  previous,  up
1846 @vindex sc-nuke-mail-header
1847 @section Frames You Can Customize
1848 @ifinfo
1850 @end ifinfo
1851 As mentioned earlier, Supercite uses various frames to perform
1852 certain jobs such as mail header information extraction and mail header
1853 nuking.  However, these frames are not available for you to customize,
1854 except through abstract interfaces such as @code{sc-nuke-mail-header},
1855 et al.
1857 @vindex sc-default-cite-frame
1858 However, the citation frames Supercite uses provide a lot of customizing
1859 power and are thus available to you to change to suit your needs.  The
1860 workhorse of citation is the frame contained in the variable
1861 @code{sc-default-cite-frame}.  This frame recognizes many situations,
1862 such as blank lines, which it interprets as paragraph separators.  It
1863 also recognizes previously cited nested and non-nested citations in the
1864 original message.  By default it will coerce non-nested citations into
1865 your preferred citation style, and it will add a level of citation to
1866 nested citations.  It will also simply cite uncited lines in your
1867 preferred style.
1869 @cindex unciting
1870 @cindex reciting
1871 @vindex sc-default-uncite-frame
1872 @vindex sc-default-recite-frame
1873 In a similar vein, there are default frames for @dfn{unciting} and
1874 @dfn{reciting}, contained in the variables
1875 @code{sc-default-uncite-frame} and @code{sc-default-recite-frame}
1876 respectively.@refill
1878 As mentioned earlier (@pxref{Recognizing Citations}), citations are
1879 recognized through the values of the regular expressions
1880 @code{sc-citation-root-regexp}, et al.  To recognize odd styles, you
1881 could modify these variables, or you could modify the default citing
1882 frame.  Alternatively, you could set up association lists of frames for
1883 recognizing specific alternative forms.
1885 @vindex sc-cite-frame-alist
1886 @vindex sc-uncite-frame-alist
1887 @vindex sc-recite-frame-alist
1888 For each of the actions -- citing, unciting, and reciting -- an alist is
1889 consulted to find the frame to use (@code{sc-cite-frame-alist},
1890 @code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
1891 respectively).  These frames can contain alists of the form:
1893 @example
1894 ((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
1895  (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
1896  (@dots{}))
1897 @end example
1899 @vindex sc-mail-field
1900 @findex string-match
1901 Where @var{infokey} is a key suitable for @code{sc-mail-field},
1902 @var{regexp} is a regular expression which is @code{string-match}'d
1903 against the value of the @code{sc-mail-field} key, and @var{frame} is
1904 the frame to use if a match occurred.  @var{frame} can be a variable
1905 containing a frame or a frame in-lined.@refill
1907 When Supercite is about to cite, uncite, or recite a region, it consults
1908 the appropriate alist and attempts to find a frame to use.  If one
1909 is not found from the alist, then the appropriate default frame is used.
1911 @node  Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
1912 @comment  node-name,  next,  previous,  up
1913 @vindex sc-mode-map-prefix
1914 @vindex mode-map-prefix (sc-)
1915 @kindex C-c C-p
1916 @chapter Post-yank Formatting Commands
1917 @ifinfo
1919 @end ifinfo
1920 Once the original message has been yanked into the reply buffer, and
1921 @code{sc-cite-original} has had a chance to do its thing, a number of
1922 useful Supercite commands will be available to you. Since there is wide
1923 variety in the keymaps that MUAs set up in their reply buffers, it is
1924 next to impossible for Supercite to properly sprinkle its commands into
1925 the existing keymap.  For this reason Supercite places its commands on a
1926 separate keymap, putting this keymap onto a prefix key in the reply
1927 buffer. You can customize the prefix key Supercite uses by changing the
1928 variable @code{sc-mode-map-prefix}.  By default, the
1929 @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
1930 but unfortunately the best general solution so far.  In the rest of this
1931 chapter, we'll assume you've installed Supercite's keymap on the default
1932 prefix.@refill
1934 @ifinfo
1935 @menu
1936 * Citing Commands::
1937 * Insertion Commands::
1938 * Variable Toggling Shortcuts::
1939 * Mail Field Commands::
1940 * Miscellaneous Commands::
1941 @end menu
1942 @end ifinfo
1944 @node   Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
1945 @comment  node-name,  next,  previous,  up
1946 @vindex sc-cite-region-limit
1947 @section Commands to Manually Cite, Recite, and Uncite
1948 @ifinfo
1950 @end ifinfo
1951 Probably the three most common post-yank formatting operations that you
1952 will perform will be the manual citing, reciting, and unciting of
1953 regions of text in the reply buffer. Often you may want to recite a
1954 paragraph to use a nickname, or manually cite a message when setting
1955 @code{sc-cite-region-limit} to @code{nil}.  The following commands
1956 perform these functions on the region of text between @samp{point} and
1957 @samp{mark}.  Each of them sets the @dfn{undo boundary} before modifying
1958 the region so that the command can be undone in the standard Emacs
1959 way.@refill
1961 A quick note about Emacs 19.  Unlike in Emacs 18, the region delimited
1962 by @samp{point} and @samp{mark} can have two states.  It can be
1963 @dfn{active} or @dfn{inactive}.  Although Emacs 19 and Lucid Emacs 19
1964 use different terminology and functions, both employ the same convention
1965 such that when the region is inactive, commands that modify the region
1966 should generate an error.  The user needs to explicitly activate the
1967 region before successfully executing the command.  All Supercite
1968 commands conform to this convention.
1970 Here is the list of Supercite citing commands:
1972 @table @asis
1973 @findex sc-cite-region
1974 @findex cite-region (sc-)
1975 @kindex C-c C-p c
1976 @vindex sc-pre-cite-hook
1977 @vindex pre-cite-hook (sc-)
1978 @vindex sc-confirm-always-p
1979 @vindex confirm-always-p
1980 @kindex C-u
1981 @item @code{sc-cite-region} (@kbd{C-c C-p c})
1982 @comment
1983 This command cites each line in the region of text by interpreting the
1984 selected frame from @code{sc-cite-frame-alist}, or the default citing
1985 frame @code{sc-default-cite-frame}.  It runs the hook
1986 @code{sc-pre-cite-hook} before interpreting the frame.  With an optional
1987 universal argument (@kbd{C-u}), it temporarily sets
1988 @code{sc-confirm-always-p} to @code{t} so you can confirm the
1989 attribution string for a single manual citing.
1990 @xref{Configuring the Citation Engine}.@refill
1992 @findex sc-uncite-region
1993 @findex uncite-region (sc-)
1994 @kindex C-c C-p u
1995 @item @code{sc-uncite-region} (@kbd{C-c C-p u})
1996 @comment
1997 This command removes any citation strings from the beginning of each
1998 cited line in the region by interpreting the selected frame from
1999 @code{sc-uncite-frame-alist}, or the default unciting frame
2000 @code{sc-default-uncite-frame}.  It runs the hook
2001 @code{sc-pre-uncite-hook} before interpreting the frame.
2002 @xref{Configuring the Citation Engine}.@refill
2004 @findex sc-recite-region
2005 @findex recite-region (sc-)
2006 @kindex C-c C-p r
2007 @item @code{sc-recite-region} (@kbd{C-c C-p r})
2008 @comment
2009 This command recites each line the region by interpreting the selected
2010 frame from @code{sc-recite-frame-alist}, or the default reciting frame
2011 @code{sc-default-recite-frame}. It runs the hook
2012 @code{sc-pre-recite-hook} before interpreting the frame.
2013 @xref{Configuring the Citation Engine}.@refill
2015 @vindex sc-confirm-always-p
2016 @vindex confirm-always-p (sc-)
2017 Supercite will always ask you to confirm the attribution when reciting a
2018 region, regardless of the value of @code{sc-confirm-always-p}.
2019 @end table
2021 @node  Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
2022 @comment  node-name,  next,  previous,  up
2023 @section Insertion Commands
2024 @ifinfo
2026 @end ifinfo
2027 These two functions insert various strings into the reply buffer.
2029 @table @asis
2030 @findex sc-insert-reference
2031 @findex insert-reference (sc-)
2032 @kindex C-c C-p w
2033 @item @code{sc-insert-reference} (@kbd{C-c C-p w})
2034 @comment
2035 @vindex sc-preferred-header-style
2036 @vindex preferred-header-style (sc-)
2037 Inserts a reference header into the reply buffer at @samp{point}.  With
2038 no arguments, the header indexed by @code{sc-preferred-header-style} is
2039 inserted. An optional numeric argument is the index into
2040 @code{sc-rewrite-header-list} indicating which reference header to
2041 write.@refill
2043 With just the universal argument (@kbd{C-u}), electric reference mode is
2044 entered, regardless of the value of @code{sc-electric-references-p}.
2046 @findex sc-insert-citation
2047 @findex insert-citation (sc-)
2048 @kindex C-c C-p i
2049 @item @code{sc-insert-citation} (@kbd{C-c C-p i})
2050 @comment
2051 Inserts the current citation string at the beginning of the line that
2052 @samp{point} is on.  If the line is already cited, Supercite will issue
2053 an error and will not cite the line.
2054 @end table
2056 @node  Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
2057 @comment  node-name,  next,  previous,  up
2058 @cindex toggling variables
2059 @section Variable Toggling Shortcuts
2060 @ifinfo
2062 @end ifinfo
2063 Supercite defines a number of commands that make it easier for you to
2064 toggle and set various Supercite variables as you are editing the reply
2065 buffer.  For example, you may want to turn off filling or whitespace
2066 cleanup, but only temporarily.  These toggling shortcut commands make
2067 this easy to do.
2069 @kindex C-c C-p C-t
2070 Like Supercite commands in general, the toggling commands are placed on
2071 a keymap prefix within the greater Supercite keymap.  For the default
2072 value of @code{sc-mode-map-prefix}, this will be
2073 @kbd{C-c C-p C-t}.@refill
2075 The following commands toggle the value of certain Supercite variables
2076 which take only a binary value:
2078 @table @kbd
2079 @item C-c C-p C-t b
2080 Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
2082 @item C-c C-p C-t c
2083 Toggles the variable @code{sc-confirm-always-p}.
2085 @item C-c C-p C-t d
2086 Toggles the variable @code{sc-downcase-p}.
2088 @item C-c C-p C-t e
2089 Toggles the variable @code{sc-electric-references-p}.
2091 @item C-c C-p C-t f
2092 Toggles the variable @code{sc-auto-fill-region-p}.
2094 @item C-c C-p C-t o
2095 Toggles the variable @code{sc-electric-circular-p}.
2097 @item C-c C-p C-t s
2098 Toggles the variable @code{sc-nested-citation-p}.
2100 @item C-c C-p C-t u
2101 Toggles the variable @code{sc-use-only-preferences-p}.
2103 @item C-c C-p C-t w
2104 Toggles the variable @code{sc-fixup-whitespace-p}.
2105 @end table
2107 @findex set-variable
2108 The following commands let you set the value of multi-value variables,
2109 in the same way that Emacs' @code{set-variable} does:
2111 @table @kbd
2112 @item C-c C-p C-t a
2113 Sets the value of the variable @code{sc-preferred-attribution-list}.
2115 @item C-c C-p C-t l
2116 Sets the value of the variable @code{sc-cite-region-limit}.
2118 @item C-c C-p C-t n
2119 Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
2121 @item C-c C-p C-t N
2122 Sets the value of the variable @code{sc-mail-header-nuke-list}.
2124 @item C-c C-p C-t p
2125 Sets the value of the variable @code{sc-preferred-header-style}.
2126 @end table
2128 @kindex C-c C-p C-p
2129 One special command is provided to toggle both
2130 @code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together.
2131 This is because you typically want to run Supercite with either variable
2132 as @code{nil} or non-@code{nil}.  The command to toggle these variables
2133 together is bound on @kbd{C-c C-p C-p}.@refill
2135 Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?})
2136 brings up a Help message on the toggling keymap.
2137   
2139 @node  Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
2140 @comment  node-name,  next,  previous,  up
2141 @section Mail Field Commands
2142 @ifinfo
2144 @end ifinfo
2145 These commands allow you to view, modify, add, and delete various bits
2146 of information from the info alist.
2147 @xref{Information Keys and the Info Alist}.@refill
2149 @table @asis
2150 @kindex C-c C-p f
2151 @findex sc-mail-field-query
2152 @findex mail-field-query (sc-)
2153 @kindex C-c C-p f
2154 @item @code{sc-mail-field-query} (@kbd{C-c C-p f})
2155 @comment
2156 Allows you to interactively view, modify, add, and delete info alist
2157 key-value pairs.  With no argument, you are prompted (with completion)
2158 for a info key.  The value associated with that key is displayed in the
2159 minibuffer.  With an argument, this command will first ask if you want
2160 to view, modify, add, or delete an info key. Viewing is identical to
2161 running the command with no arguments.
2163 If you want to modify the value of a key, Supercite will first prompt
2164 you (with completion) for the key of the value you want to change.  It
2165 will then put you in the minibuffer with the key's current value so you
2166 can edit the value as you wish.  When you hit @key{RET}, the key's value
2167 is changed.  For those of you running Emacs 19, minibuffer history is
2168 kept for the values.
2170 If you choose to delete a key-value pair, Supercite will prompt you (with
2171 completion) for the key to delete.
2173 If you choose to add a new key-value pair, Supercite firsts prompts you
2174 for the key to add.  Note that completion is turned on for this prompt,
2175 but you can type any key name here, even one that does not yet exist.
2176 After entering the key, Supercite prompts you for the key's value.  It
2177 is not an error to enter a key that already exists, but the new value
2178 will override any old value.  It will not replace it though; if you
2179 subsequently delete the key-value pair, the old value will reappear.
2181 @findex sc-mail-process-headers
2182 @findex mail-process-headers (sc-)
2183 @kindex C-c C-p g
2184 @item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
2185 @comment
2186 This command lets you re-initialize Supercite's info alist from any set
2187 of mail headers in the region between @samp{point} and @samp{mark}.
2188 This function is especially useful for replying to digest messages where
2189 Supercite will initially set up its information for the digest
2190 originator, but you want to cite each component article with the real
2191 message author.  Note that unless an error during processing occurs, any
2192 old information is lost.@refill
2193 @end table
2195 @node  Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
2196 @comment  node-name,  next,  previous,  up
2197 @section Miscellaneous Commands
2198 @ifinfo
2200 @end ifinfo
2201 @table @asis
2202 @findex sc-open-line
2203 @findex open-line (sc-)
2204 @findex open-line
2205 @kindex C-c C-p o
2206 @item @code{sc-open-line} (@kbd{C-c C-p o})
2207 @comment
2208 Similar to Emacs' standard @code{open-line} commands, but inserts the
2209 citation string in front of the new line.  As with @code{open-line},
2210 an optional numeric argument inserts that many new lines.@refill
2212 @findex sc-describe
2213 @findex describe (sc-)
2214 @kindex C-c C-p ?
2215 @kindex C-c C-p h
2216 @item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
2217 @comment
2218 This function has been obsoleted by the @TeX{}info manual you are now
2219 reading. It is still provided for compatibility, but it will eventually
2220 go away.
2222 @findex sc-version
2223 @findex version (sc-)
2224 @kindex C-c C-p v
2225 @item @code{sc-version} (@kbd{C-c C-p v})
2226 @comment
2227 Echos the version of Supercite you are using.  With the optional
2228 universal argument (@kbd{C-u}), this command inserts the version
2229 information into the current buffer.
2231 @findex sc-submit-bug-report
2232 @findex submit-bug-report (sc-)
2233 @kindex C-c C-p C-b
2234 @item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
2235 @comment
2236 If you encounter a bug, or wish to suggest an enhancement, use this
2237 command to set up an outgoing mail buffer, with the proper address to
2238 the Supercite maintainer automatically inserted in the @samp{To:@:}
2239 field.  This command also inserts information that the Supercite
2240 maintainer can use to recreate your exact setup, making it easier to
2241 verify your bug.
2242 @end table
2244 @node  Hints to MUA Authors, Version 3 Changes, Electric References, Top
2245 @comment  node-name,  next,  previous,  up
2246 @chapter Hints to MUA Authors
2247 @ifinfo
2249 @end ifinfo
2250 In June of 1989, some discussion was held between the various MUA
2251 authors, the Supercite author, and other Supercite users. These
2252 discussions centered around the need for a standard interface between
2253 MUAs and Supercite (or any future Supercite-like packages).  This
2254 interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in
2255 a mail message to the Supercite mailing list:
2257 @example
2258         Martin> Each news/mail-reader should provide a form of
2259         Martin> mail-yank-original that
2261         Martin> 1: inserts the original message incl. header into the
2262         Martin>    reply buffer; no indentation/prefixing is done, the header
2263         Martin>    tends to be a "full blown" version rather than to be
2264         Martin>    stripped down.
2266         Martin> 2: `point' is at the start of the header, `mark' at the
2267         Martin>    end of the message body.
2269         Martin> 3: (run-hooks 'mail-yank-hooks)
2271         Martin> [Supercite] should be run as such a hook and merely
2272         Martin> rewrite the message.  This way it isn't anymore
2273         Martin> [Supercite]'s job to gather the original from obscure
2274         Martin> sources. [@dots{}]
2275 @end example
2277 @vindex mail-citation-hook
2278 @vindex mail-yank-hooks
2279 @cindex sendmail.el
2280 @findex mail-yank-original
2281 @findex defvar
2282 This specification was adopted, but with the recent release of
2283 Emacs 19, it has undergone a slight modification.  Instead of the
2284 variable @code{mail-yank-hooks}, the new preferred hook variable that
2285 the MUA should provide is @code{mail-citation-hook}.
2286 @code{mail-yank-hooks} can be provided for backward compatibility, but
2287 @code{mail-citation-hook} should always take precedence.  Richard
2288 Stallman (of the FSF) suggests that the MUAs should @code{defvar}
2289 @code{mail-citation-hook} to @code{nil} and perform some default citing
2290 when that is the case.  Take a look at Emacs 19's @file{sendmail.el}
2291 file, specifically the @code{mail-yank-original} defun for
2292 details.@refill
2294 If you are writing a new MUA package, or maintaining an existing MUA
2295 package, you should make it conform to this interface so that your users
2296 will be able to link Supercite easily and seamlessly. To do this, when
2297 setting up a reply or forward buffer, your MUA should follow these
2298 steps:
2300 @enumerate
2301 @item 
2302 Insert the original message, including the mail headers into the reply
2303 buffer. At this point you should not modify the raw text in any way, and
2304 you should place all the original headers into the body of the reply.
2305 This means that many of the mail headers will be duplicated, one copy
2306 above the @code{mail-header-separator} line and one copy below,
2307 however there will probably be more headers below this line.@refill
2309 @item 
2310 Set @samp{point} to the beginning of the line containing the first mail
2311 header in the body of the reply. Set @samp{mark} at the end of the
2312 message text.  It is very important that the region be set around the
2313 text Supercite is to modify and that the mail headers are within this
2314 region.  Supercite will not venture outside the region for any reason,
2315 and anything within the region is fair game, so don't put anything that
2316 @strong{must} remain unchanged inside the region.  Further note that for
2317 Emacs 19, the region need not be set active.  Supercite will work
2318 properly when the region is inactive, as should any other like-minded
2319 package.@refill
2321 @item 
2322 Run the hook @code{mail-citation-hook}. You will probably want to
2323 provide some kind of default citation functions in cases where the user
2324 does not have Supercite installed.  By default, your MUA should
2325 @code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
2326 yanking function, check its value.  If it finds
2327 @code{mail-citation-hook} to be @code{nil}, it should perform some
2328 default citing behavior.  User who want to connect to Supercite then
2329 need only add @code{sc-cite-original} to this list of hooks using
2330 @code{add-hook}.@refill
2331 @end enumerate
2333 If you do all this, your users will not need to overload your routines
2334 to use Supercite, and your MUA will join the ranks of those that conform
2335 to this interface ``out of the box.''
2337 @node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
2338 @comment  node-name,  next,  previous,  up
2339 @chapter Version 3 Changes
2340 @ifinfo
2342 @end ifinfo
2343 @cindex sc-unsupp.el file
2344 With version 3, Supercite has undergone an almost complete rewrite, and
2345 has hopefully benefited in a number of ways, including vast
2346 improvements in the speed of performance, a big reduction in size of the
2347 code and in the use of Emacs resources, and a much cleaner and flexible
2348 internal architecture.  The central construct of the info alist, and its
2349 role in Supercite has been expanded, and the other central concept, the
2350 general package Regi, was developed to provide a theoretically unlimited
2351 flexibility.
2353 But most of this work is internal and not of very great importance to the
2354 casual user. There have been some changes at the user-visible level,
2355 but for the most part, the Supercite configuration variables from
2356 version 2 should still be relevant to version 3.  Below, I briefly
2357 outline those user-visible things that have changed since version 2. For
2358 details, look to other sections of this manual.
2360 @enumerate
2361 @item
2362 @cindex supercite.el file
2363 @cindex reporter.el file
2364 @cindex regi.el file
2365 @cindex sc.el from version 2
2366 @cindex sc-elec.el from version 2
2367 Supercite proper now comes in a single file, @file{supercite.el}, which
2368 contains everything except the unsupported noodlings, overloading (which
2369 should be more or less obsolete with the release of Emacs 19), and the
2370 general lisp packages @file{reporter.el} and @file{regi.el}.  Finally,
2371 the @TeX{}info manual comes in its own file as well.  In particular, the
2372 file @file{sc.el} from the version 2 distribution is obsolete, as is the
2373 file @file{sc-elec.el}.
2375 @item
2376 @code{sc-spacify-name-chars} is gone in version 3.
2378 @item
2379 @vindex sc-attrib-selection-list
2380 @vindex attrib-selection-list
2381 @code{sc-nickname-alist} is gone in version 3.  The
2382 @code{sc-attrib-selection-list} is a more general construct supporting
2383 the same basic feature.
2385 @item
2386 The version 2 variable @code{sc-preferred-attribution} has been changed
2387 to @code{sc-preferred-attribution-list}, and has been expanded upon to
2388 allow you to specify an ordered list of preferred attributions.
2390 @item
2391 @code{sc-mail-fields-list} has been removed, and header nuking in
2392 general has been greatly improved, giving you wider flexibility in
2393 specifying which headers to keep and remove while presenting a
2394 simplified interface to commonly chosen defaults.
2396 @item
2397 Post-yank paragraph filling has been completely removed from Supercite,
2398 other packages just do it better than Supercite ever would.  Supercite
2399 will still fill newly cited paragraphs.
2401 @item
2402 @vindex sc-cite-region-limit
2403 @vindex cite-region-limit
2404 The variable @code{sc-all-but-cite-p} has been replaced by
2405 @code{sc-cite-region-limit}.
2407 @item
2408 Keymap hacking in the reply buffer has been greatly simplified, with, I
2409 believe, little reduction in functionality.
2411 @item
2412 Hacking of the reply buffer's docstring has been completely eliminated.
2413 @end enumerate
2415 @node  Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
2416 @comment  node-name,  next,  previous,  up
2417 @chapter Thanks and History
2418 @ifinfo
2420 @end ifinfo
2421 The Supercite package was derived from its predecessor Superyank 1.11
2422 which was inspired by various bits of code and ideas from Martin Neitzel
2423 and Ashwin Ram. They were the folks who came up with the idea of
2424 non-nested citations and implemented some rough code to provide this
2425 style. Superyank and Supercite version 2 evolved to the point where much
2426 of the attribution selection mechanism was automatic, and features have
2427 been continuously added through the comments and suggestions of the
2428 Supercite mailing list participants.  Supercite version 3 represents a
2429 nearly complete rewrite with many of the algorithms and coding styles
2430 being vastly improved.  Hopefully Supercite version 3 is faster,
2431 smaller, and much more flexible than its predecessors.
2433 In the version 2 manual I thanked some specific people for their help in
2434 developing Supercite 2.  You folks know who you are and your continued
2435 support is greatly appreciated.  I wish to thank everyone on the
2436 Supercite mailing list, especially the brave alpha testers, who helped
2437 considerably in testing out the concepts and implementation of Supercite
2438 version 3.  Special thanks go out to the MUA and Emacs authors Kyle
2439 Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming
2440 to a quick agreement on the new @code{mail-citation-hook} interface, and
2441 for adding the magic lisp to their code to support this.
2443 All who have helped and contributed have been greatly appreciated.
2445 @node  The Supercite Mailing List, Concept Index, Thanks and History, Top
2446 @comment  node-name,  next,  previous,  up
2447 @cindex supercite mailing list address
2448 @cindex mailing list address
2449 @chapter The Supercite Mailing List
2450 @ifinfo
2452 @end ifinfo
2453 The author runs a simple mail expanding mailing list for discussion of
2454 issues related to Supercite. This includes enhancement requests, bug
2455 reports, general help questions, etc.  To subscribe or unsubscribe to
2456 the mailing list, send a request to the administrative address:
2458 @example
2459 supercite-request@@python.org
2460 @end example
2462 Please be sure to include the most reliable and shortest (preferably
2463 Internet) address back to you.  To post articles to the list, send your
2464 message to this address (you do not need to be a member to post, but be
2465 sure to indicate this in your article or replies may not be CC'd to
2466 you):
2468 @example
2469 supercite@@python.org
2470 @end example
2472 If you are sending bug reports, they should go to the following address,
2473 but @emph{please}! use the command @code{sc-submit-bug-report} since it
2474 will be much easier for me to duplicate your problem if you do so.  It
2475 will set up a mail buffer automatically with this address on the
2476 @samp{To:@:} line:
2478 @example
2479 supercite-help@@python.org
2480 @end example
2482 @node  Concept Index, Command Index, The Supercite Mailing List, Top
2483 @comment  node-name,  next,  previous,  up
2484 @unnumbered Concept Index
2485 @printindex cp
2487 @node  Command Index, Key Index, Concept Index, Top
2488 @comment  node-name,  next,  previous,  up
2489 @unnumbered Command Index
2490 @ifinfo
2492 @end ifinfo
2493 Since all supercite commands are prepended with the string
2494 ``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
2495 its @var{command} name.
2496 @iftex
2497 @sp 2
2498 @end iftex
2499 @printindex fn
2501 @node  Key Index, Variable Index, Command Index, Top
2502 @comment  node-name,  next,  previous,  up
2503 @unnumbered Key Index
2504 @printindex ky
2506 @node Variable Index,  , Key Index, Top
2507 @comment  node-name,  next,  previous,  up
2508 @unnumbered Variable Index
2509 @ifinfo
2511 @end ifinfo
2512 Since all supercite variables are prepended with the string
2513 ``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
2514 its @var{variable} name.
2515 @iftex
2516 @sp 2
2517 @end iftex
2518 @printindex vr
2519 @setchapternewpage odd
2520 @summarycontents
2521 @contents
2522 @bye