1 \input texinfo @comment -*-texinfo-*-
3 @comment %**start of header (This is for running Texinfo on a region.)
4 @setfilename ../info/supercite.info
5 @settitle Supercite Version 3.1 User's Manual
7 * Supercite:: Fancy citations and attributions for replies for
8 mail and news reading systems.
13 @c @setchapternewpage odd % For book style double sided manual.
14 @comment %**end of header (This is for running Texinfo on a region.)
18 %\global\baselineskip 30pt % For printing in double spaces
21 This document describes the Supercite Version 3.1 package for citing and
22 attributing the replies for various GNU Emacs mail and news reading
25 Copyright @copyright{} 1993 Barry A@. Warsaw
27 Permission is granted to make and distribute verbatim copies of
28 this manual provided the copyright notice and this permission notice
29 are preserved on all copies.
32 Permission is granted to process this file through TeX and print the
33 results, provided the printed document carries copying permission
34 notice identical to this one except for the removal of this paragraph
35 (this paragraph not being relevant to the printed manual).
42 @center @titlefont{Supercite User's Manual}
44 @center @titlefont{Supercite Version 3.1}
46 @center Manual Revision: 3.47
49 @center Barry A@. Warsaw
50 @center @t{bwarsaw@@cen.com}
51 @center @t{@dots{}!uunet!cen.com!bwarsaw}
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1993 Barry A@. Warsaw
56 Permission is granted to make and distribute verbatim copies of
57 this manual provided the copyright notice and this permission notice
58 are preserved on all copies.
63 @node Top, Introduction, (dir), (dir)
64 @comment node-name, next, previous, up
66 This document describes the Supercite Version 3.1 package for citing and
67 attributing the replies for various GNU Emacs mail and news reading
68 subsystems. The manual is divided into the following chapters.
74 * Replying and Yanking::
75 * Selecting an Attribution::
76 * Configuring the Citation Engine::
77 * Post-yank Formatting Commands::
78 * Information Keys and the Info Alist::
80 * Hints to MUA Authors::
82 * Thanks and History::
83 * The Supercite Mailing List::
92 @node Introduction, Usage Overview, Top, Top
93 @comment node-name, next, previous, up
98 Supercite version 3.1 is a GNU Emacs package written entirely in Emacs
99 Lisp. It interfaces to most of the commonly used Emacs mail user agents
100 (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
101 sophisticated facilities for the citing and attributing of message
102 replies. Supercite has a very specific and limited role in the process
103 of composing replies to both USENET network news and electronic mail.
105 The preferred way to spell Supercite is with a capital @samp{S},
106 lowercase @samp{upercite}. There are a few alternate spellings out there
107 and I won't be terribly offended if you use them. People often ask
113 * What Supercite Does Not Do::
114 * What Supercite Does::
120 Supercite is only useful in conjunction with MUAs and NUAs such as VM,
121 GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs).
122 Supercite is typically called by the MUA after a reply buffer has been
123 setup. Thereafter, Supercite's many commands and formatting styles are
124 available in that reply buffer until the reply is sent. Supercite is
125 re-initialized in each new reply buffer.
127 Supercite is currently at major revision 3.1, and is known to work in the
128 following environments:
132 GNU Emacs 18.57 through 18.59, all current FSF Emacs 19,
133 all current Lucid Emacs 19, and Epoch 4.@refill
136 VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
137 beyond, PCMAIL.@refill
140 RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
143 For systems with version numbers, all known subsequent versions also
144 work with Supercite. For those systems without version numbers,
145 Supercite probably works with any recently released version. Note that
146 only some of these systems will work with Supercite ``out of the box.''
147 All others must overload interfacing routines to supply the necessary
148 glue. @xref{Getting Connected}, for more details.@refill
151 @node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
152 @comment node-name, next, previous, up
158 @cindex attribute, attributing
160 @section Usage Overview
164 Typical usage is as follows. You want to reply or followup to a message
165 in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
166 (i.e., ``forward'') to begin composing the reply. In response, the MUA
167 will create a reply buffer and initialize the outgoing mail headers
168 appropriately. The body of the reply will usually be empty at this
169 point. You now decide that you would like to include part of the
170 original message in your reply. To do this, you @dfn{yank} the original
171 message into the reply buffer, typically with a key stroke such as
172 @kbd{C-c C-y}. This sequence will invoke an MUA-specific function which
173 fills the body of the reply with the original message and then
174 @dfn{attributes} this text to its author. This is called @dfn{citing}
175 and its effect is to prefix every line from the original message with a
176 special text tag. Most MUAs provide some default style of citing; by
177 using Supercite you gain a wider flexibility in the look and style of
178 citations. Supercite's only job is to cite the original message.
180 @node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
181 @comment node-name, next, previous, up
182 @section What Supercite Doesn't Do
186 Because of this clear division of labor, there are useful features which
187 are the sole responsibility of the MUA, even though it might seem that
188 Supercite should provide them. For example, many people would like to
189 be able to yank (and cite) only a portion of the original message.
190 Since Supercite only modifies the text it finds in the reply buffer as
191 set up by the MUA, it is the MUA's responsibility to do partial yanking.
192 @xref{Reply Buffer Initialization}.@refill
194 @vindex mail-header-separator
196 Another potentially useful thing would be for Supercite to set up the
197 outgoing mail headers with information it gleans from the reply buffer.
198 But by previously agreed upon convention, any text above the
199 @code{mail-header-separator} which separates mail headers from message
200 bodies cannot be modified by Supercite. Supercite, in fact, doesn't
201 know anything about the meaning of these headers, and never ventures
202 outside the designated region. @xref{Hints to MUA Authors}, for more
205 @node What Supercite Does, Citations, What Supercite Does Not Do, Introduction
206 @comment node-name, next, previous, up
207 @findex sc-cite-original
208 @section What Supercite Does
212 Supercite is invoked for the first time on a reply buffer via your MUA's
213 reply or forward command. This command will actually perform citations
214 by calling a hook variable to which Supercite's top-level function
215 @code{sc-cite-original} has been added. When @code{sc-cite-original} is
216 executed, the original message must be set up in a very specific way,
217 but this is handled automatically by the MUA. @xref{Hints to MUA
221 The first thing Supercite does, via @code{sc-cite-original}, is to parse
222 through the original message's mail headers. It saves this data in an
223 @dfn{information association list}, or @dfn{info alist}. The information
224 in this list is used in a number of places throughout Supercite.
225 @xref{Information Keys and the Info Alist}.@refill
227 @cindex nuking mail headers
228 @cindex reference header
229 After the mail header info is extracted, the headers are optionally
230 removed (@dfn{nuked}) from the reply. Supercite then writes a
231 @dfn{reference header} into the buffer. This reference header is a
232 string carrying details about the citation it is about to perform.
235 Next, Supercite visits each line in the reply, transforming the line
236 according to a customizable ``script''. Lines which were not previously
237 cited in the original message are given a citation, while already cited
238 lines remain untouched, or are coerced to your preferred style.
239 Finally, Supercite installs a keymap into the reply buffer so that you
240 have access to Supercite's post-yank formatting and reciting commands as
241 you subsequently edit your reply. You can tell that Supercite has been
242 installed into the reply buffer because that buffer's modeline will
243 display the minor mode string @samp{SC}.
248 @findex fill-paragraph
250 When the original message is cited by @code{sc-cite-original}, it will
251 (optionally) be filled by Supercite. However, if you manually edit the
252 cited text and want to re-fill it, you must use an add-on package such
253 as @cite{filladapt} or @cite{gin-mode}. These packages can recognize
254 Supercited text and will fill them appropriately. Emacs' built-in
255 filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
256 text and will not re-fill them properly because it cannot guess the
257 @code{fill-prefix} being used.
258 @xref{Post-yank Formatting Commands}, for details.@refill
260 As mentioned above, Supercite provides commands to recite or uncite
261 regions of text in the reply buffer, and commands to perform other
262 beautifications on the cited original text, maintaining consistent and
263 informative citations throughout. Supercite tries to be as configurable
264 as possible to allow for a wide range of personalized citation styles,
265 but it is also immediately useful with the default configuration, once
266 it has been properly connected to your MUA. @xref{Getting Connected},
267 for more details.@refill
269 @node Citations, Citation Elements, What Supercite Does, Top
270 @comment node-name, next, previous, up
271 @cindex nested citations
278 A @dfn{citation} is the acknowledgement of the original author of a mail
279 message in the body of the reply. There are two basic citation styles
280 which Supercite supports. The first, called @dfn{nested citations} is
281 an anonymous form of citation; in other words, an indication is made
282 that the cited line was written by someone @emph{other} that the current
283 message author (i.e., other than you, the person composing the reply),
284 but no reference is made as to the identity of the original author.
285 This style should look familiar since its use on the net is widespread.
286 Here's an example of what a message buffer would look like using nested
287 citations after multiple replies:
290 >> John originally wrote this
292 > Jane said that John didn't know
293 > what he was talking about
294 And that's what I think too.
299 * Citation Elements::
300 * Recognizing Citations::
304 Note that multiple inclusions of the original messages result in a
305 nesting of the @samp{@code{>}} characters. This can sometimes be quite
306 confusing when many levels of citations are included since it may be
307 difficult or impossible to figure out who actually participated in the
308 thread, and multiple nesting of @samp{@code{>}} characters can sometimes
309 make the message very difficult for the eye to scan.
311 @cindex non-nested citations
312 In @dfn{non-nested citations}, each cited line begins with an
313 informative string attributing that line to the original author. Only
314 the first level of attribution will be shown; subsequent citations don't
315 nest the citation strings. The above dialog might look like this when
316 non-nested citations are used:
319 John> John originally wrote this
320 John> and this as well
321 Jane> Jane said that John didn't know
322 Jane> what he was talking about
323 And that's what I think too.
326 Notice here that my inclusion of Jane's inclusion of John's original
327 message did not result in a line cited with @samp{Jane>John>}.
329 @vindex sc-nested-citation-p
330 @vindex nested-citation-p (sc-)
331 Supercite supports both styles of citation, and the variable
332 @code{sc-nested-citation-p} controls which style it will use when citing
333 previously uncited text. When this variable is @code{nil} (the default),
334 non-nested citations are used. When non-@code{nil}, nested citations
338 @node Citation Elements, Recognizing Citations, Citations, Citations
339 @comment node-name, next, previous, up
340 @cindex citation string
342 @section Citation Elements
346 @dfn{Citation strings} are composed of one or more elements. Non-nested
347 citations are composed of four elements, three of which are directly
348 user definable. The elements are concatenated together, in this order:
350 @cindex citation leader
351 @vindex citation-leader (sc-)
352 @vindex sc-citation-leader
355 The @dfn{citation leader}. The citation leader is contained in the
356 variable @code{sc-citation-leader}, and has the default value of a
357 string containing four spaces.
359 @cindex attribution string
361 The @dfn{attribution string}. This element is supplied automatically by
362 Supercite, based on your preferences and the original message's mail
363 headers, though you may be asked to confirm Supercite's choice.
364 @xref{Selecting an Attribution}, for more details.@refill
366 @cindex citation delimiter
367 @vindex sc-citation-delimiter
368 @vindex citation-delimiter (sc-)
370 The @dfn{citation delimiter}. This string, contained in the variable
371 @code{sc-citation-delimiter} visually separates the citation from the
372 text of the line. This variable has a default value of @code{">"} and
373 for best results, the string should consist of only a single character.
375 @cindex citation separator
376 @vindex citation-separator (sc-)
377 @vindex sc-citation-separator
379 The @dfn{citation separator}. The citation separator is contained in
380 the variable @code{sc-citation-separator}, and has the default value of
381 a string containing a single space.
384 For example, suppose you were using the default values for the above
385 variables, and Supercite provided the attribution string @samp{Jane}.
386 In this case, the composed, non-nested citation string used might be
388 @code{@asis{" Jane> "}}.
389 This citation string will be inserted in front of
390 every line in the original message that is not already cited.@refill
392 Nested citations, being simpler than non-nested citations, are composed
393 of the same elements, sans the attribution string. Supercite is smart
394 enough to not put additional spaces between citation delimiters for
395 multi-level nested citations.
397 @node Recognizing Citations, Getting Connected, Citation Elements, Citations
398 @comment node-name, next, previous, up
399 @section Recognizing Citations
403 Supercite also recognizes citations in the original article, and can
404 transform these already cited lines in a number of ways. This is how
405 Supercite suppresses the multiple citing of non-nested citations.
406 Recognition of cited lines is controlled by variables analogous to those
407 that make up the citation string as mentioned previously.
409 @vindex sc-citation-leader-regexp
410 @vindex citation-leader-regexp (sc-)
411 @vindex sc-citation-delimiter-regexp
412 @vindex citation-delimiter-regexp (sc-)
413 @vindex sc-citation-separator-regexp
414 @vindex citation-separator-regexp (sc-)
415 @vindex sc-citation-root-regexp
416 @vindex citation-root-regexp (sc-)
417 @vindex sc-citation-nonnested-root-regexp
418 @vindex citation-nonnested-root-regexp (sc-)
420 The variable @code{sc-citation-leader-regexp} describes how citation
421 leaders can look, by default it matches any number of spaces or tabs.
422 Note that since the lisp function @code{looking-at} is used to do the
423 matching, if you change this variable it need not start with a leading
426 Similarly, the variables @code{sc-citation-delimiter-regexp} and
427 @code{sc-citation-separator-regexp} respectively describe how citation
428 delimiters and separators can look. They follow the same rule as
429 @code{sc-citation-leader-regexp} above.
431 When Supercite composes a citation string, it provides the attribution
432 automatically. The analogous variable which handles recognition of the
433 attribution part of citation strings is @code{sc-citation-root-regexp}.
434 This variable describes the attribution root for both nested and
435 non-nested citations. By default it can match zero-to-many alphanumeric
436 characters (also ``.'', ``-'', and ``_''). But in some situations,
437 Supercite has to determine whether it is looking at a nested or
438 non-nested citation. Thus the variable
439 @code{sc-citation-nonnested-root-regexp} is used to describe only
440 non-nested citation roots. It is important to remember that if you
441 change @code{sc-citation-root-regexp} you should always also change
442 @code{sc-citation-nonnested-root-regexp}.@refill
444 Nemacs users:@: For best results, try setting
445 @code{sc-citation-root-regexp} to:@refill
448 "\\([-._a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\|\\ca\\|\\cg\\|\\cr\\|\\cu\\)*"
451 Mule users:@: For best results, try setting
452 @code{sc-citation-root-regexp} to:@refill
455 "\\([-._a-zA-Z0-9]\\|\\cj\\)*"
458 @node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
459 @comment node-name, next, previous, up
460 @cindex information keys
462 @cindex information extracted from mail fields
463 @findex sc-mail-field
464 @findex mail-field (sc-)
466 @chapter Information Keys and the Info Alist
470 @dfn{Mail header information keys} are nuggets of information that
471 Supercite extracts from the various mail headers of the original
472 message, placed in the reply buffer by the MUA. Information is kept in
473 the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
474 various places within Supercite, such as in header rewrite functions and
475 attribution selection. Other bits of data, composed and created by
476 Supercite, are also kept as key-value pairs in this alist. In the case
477 of mail fields, the key is the name of the field, omitting the trailing
478 colon. Info keys are always case insensitive (as are mail headers), and
479 the value for a corresponding key can be retrieved from the alist with
480 the @code{sc-mail-field} function. Thus, if the following fields were
481 present in the original article:@refill
484 Date:@: 08 April 1991, 17:32:09 EST
485 Subject:@: Better get out your asbestos suit
491 then, the following lisp constructs return:
494 (sc-mail-field "date")
495 ==> "08 April 1991, 17:32:09 EST"
497 (sc-mail-field "subject")
498 ==> "Better get out your asbestos suit"
501 Since the argument to @code{sc-mail-field} can be any string, it is
502 possible that the mail field will not be present on the info alist
503 (possibly because the mail header was not present in the original
504 message). In this case, @code{sc-mail-field} will return the value of
505 the variable @code{sc-mumble}.
507 Supercite always places all mail fields found in the yanked original
508 article into the info alist. If possible, Supercite will also places
509 the following keys into the info alist:
512 @cindex sc-attribution info field
513 @cindex attribution info field (sc-)
514 @item "sc-attribution"
515 the selected attribution string.
517 @cindex sc-citation info field
518 @cindex citation info field (sc-)
520 the non-nested citation string.
522 @cindex sc-from-address info field
523 @cindex from-address info field (sc-)
524 @item "sc-from-address"
525 email address extracted from the @samp{From:@:} field.
527 @cindex sc-reply-address info field
528 @cindex reply-address info field (sc-)
529 @item "sc-reply-address"
530 email address extracted from the @samp{Reply-To:@:} field.
532 @cindex sc-sender-address info field
533 @cindex sender-address info field (sc-)
534 @item "sc-sender-address"
535 email address extracted from the @samp{Sender:@:} field.
537 @cindex sc-emailname info field
538 @cindex emailname info field (sc-)
540 email terminus extracted from the @samp{From:@:} field.
542 @cindex sc-initials info field
543 @cindex initials info field (sc-)
545 the author's initials.
547 @cindex sc-author info field
548 @cindex author info field (sc-)
550 the author's full name.
552 @cindex sc-firstname info field
553 @cindex firstname info field (sc-)
555 the author's first name.
557 @cindex sc-lastname info field
558 @cindex lastname info field (sc-)
560 the author's last name.
562 @cindex sc-middlename-1 info field
563 @cindex middlename-1 info field (sc-)
564 @item "sc-middlename-1"
565 the author's first middle name.
568 If the author's name has more than one middle name, they will appear as
569 info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
570 @dots{}). @xref{Selecting an Attribution}.@refill
572 @node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
573 @comment node-name, next, previous, up
574 @cindex reference headers
575 @chapter Reference Headers
579 Supercite will insert an informative @dfn{reference header} at the
580 beginning of the cited body of text, which display more detail about the
581 original article and provides the mapping between the attribution and
582 the original author in non-nested citations. Whereas the citation
583 string usually only contains a portion of the original author's name,
584 the reference header can contain such information as the author's full
585 name, email address, the original article's subject, etc. In fact any
586 information contained in the info alist can be inserted into a reference
591 * The Built-in Header Rewrite Functions::
592 * Electric References::
596 @cindex header rewrite functions
597 @vindex sc-rewrite-header-list
598 @vindex rewrite-header-list (sc-)
599 There are a number of built-in @dfn{header rewrite functions} supplied
600 by Supercite, but you can write your own custom header rewrite functions
601 (perhaps using the built-in ones as examples). The variable
602 @code{sc-rewrite-header-list} contains the list of such header rewrite
603 functions. This list is consulted both when inserting the initial
604 reference header, and when displaying @dfn{electric references}.
605 @xref{Electric References}.
607 @vindex sc-preferred-header-style
608 @vindex preferred-header-style (sc-)
609 When Supercite is initially run on a reply buffer (via
610 @code{sc-cite-original}), it will automatically call one of these
611 functions. The one it uses is defined in the variable
612 @code{sc-preferred-header-style}. The value of this variable is an
613 integer which is an index into the @code{sc-rewrite-header-list},
616 @node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
617 @comment node-name, next, previous, up
618 @cindex header rewrite functions, built-in
620 @section The Built-in Header Rewrite Functions
624 Below are examples of the various built-in header rewrite functions.
625 Please note the following:@: first, the text which appears in the
626 examples below as @var{infokey} indicates that the corresponding value
627 of the info key from the info alist will be inserted there.
628 (@xref{Information Keys and the Info Alist}.). For example, in @code{sc-header-on-said}
629 below, @var{date} and @var{from} correspond to the values of the
630 @samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill
632 @vindex sc-reference-tag-string
633 @vindex reference-tag-string (sc-)
634 Also, the string @code{">>>>>"} below is really the value of the
635 variable @code{sc-reference-tag-string}. This variable is used in all
636 built-in header rewrite functions, and you can customize its value to
637 change the tag string globally.
639 Finally, the references headers actually written may omit certain parts
640 of the header if the info key associated with @var{infokey} is not
641 present in the info alist. In fact, for all built-in headers, if the
642 @samp{From:@:} field is not present in the mail headers, the entire
643 reference header will be omitted (but this usually signals a serious
644 problem either in your MUA or in Supercite's installation).
648 @findex no-header (sc-)
650 This function produces no header. It should be used instead of
651 @code{nil} to produce a blank header. This header can possibly contain
652 a blank line after the @code{mail-header-separator} line.
654 @item sc-no-blank-line-or-header
655 @findex sc-no-blank-line-or-header
656 @findex no-blank-line-or-header (sc-)
657 This function is similar to @code{sc-no-header} except that any blank
658 line after the @code{mail-header-separator} line will be removed.
660 @item sc-header-on-said
661 @findex sc-header-on-said
662 @findex header-on-said (sc-)
663 @code{>>>>> On @var{date}, @var{from} said:}
665 @item sc-header-inarticle-writes
666 @findex sc-header-inarticle-writes
667 @findex header-inarticle-writes (sc-)
668 @code{>>>>> In article @var{message-id}, @var{from} writes:}
670 @item sc-header-regarding-adds
671 @findex sc-header-regarding-adds
672 @findex header-regarding-adds (sc-)
673 @code{>>>>> Regarding @var{subject}; @var{from} adds:}
675 @item sc-header-attributed-writes
676 @findex sc-header-attributed-writes
677 @findex header-attributed-writes (sc-)
678 @code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:}
680 @item sc-header-author-writes
681 @findex sc-header-author-writes
682 @findex header-author-writes (sc-)
683 @code{>>>>> @var{sc-author} writes:}
685 @item sc-header-verbose
686 @findex sc-header-verbose
687 @findex header-verbose (sc-)
688 @code{>>>>> On @var{date},}@*
689 @code{>>>>> @var{sc-author}}@*
690 @code{>>>>> from the organization of @var{organization}}@*
691 @code{>>>>> who can be reached at:@: @var{sc-reply-address}}@*
692 @code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@*
693 @code{>>>>> had this to say in article @var{message-id}}@*
694 @code{>>>>> in newsgroups @var{newsgroups}}@*
695 @code{>>>>> concerning the subject of @var{subject}}@*
696 @code{>>>>> see @var{references} for more details}
699 @node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
700 @comment node-name, next, previous, up
701 @cindex electric references
702 @section Electric References
706 By default, when Supercite cites the original message for the first
707 time, it just goes ahead and inserts the reference header indexed by
708 @code{sc-preferred-header-style}. However, you may want to select
709 different reference headers based on the type of reply or forwarding you
710 are doing. You may also want to preview the reference header before
711 deciding whether to insert it into the reply buffer or not. Supercite
712 provides an optional @dfn{electric reference} mode which you can drop
713 into to give you this functionality.
715 @vindex sc-electric-references-p
716 @vindex electric-references-p (sc-)
717 If the variable @code{sc-electric-references-p} is non-@code{nil},
718 Supercite will bring up an electric reference mode buffer and place you
719 into a recursive edit. The electric reference buffer is read-only, so
720 you cannot directly modify the reference text until you exit electric
721 references and insert the text into the reply buffer. But you can cycle
722 through all the reference header rewrite functions in your
723 @code{sc-rewrite-header-list}.
725 You can also set a new preferred header style, jump to any header, or
726 jump to the preferred header. The header will be shown in the electric
727 reference buffer and the header index and function name will appear in
730 The following commands are available while in electric reference mode
731 (shown here with their default key bindings):
734 @item @code{sc-eref-next} (@kbd{n})
736 @findex eref-next (sc-)
738 @vindex sc-electric-circular-p
739 @vindex electric-circular-p (sc-)
740 Displays the next reference header in the electric reference buffer. If
741 the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
742 @code{sc-eref-next} while viewing the last reference header in the list
743 will wrap around to the first header.@refill
745 @item @code{sc-eref-prev} (@kbd{p})
747 @findex eref-prev (sc-)
749 Displays the previous reference header in the electric reference buffer.
750 If the variable @code{sc-electric-circular-p} is non-@code{nil},
751 invoking @code{sc-eref-prev} will wrap around to the last header.@refill
753 @item @code{sc-eref-goto} (@kbd{g})
755 @findex eref-goto (sc-)
757 Goes to a specified reference header. The index (into the
758 @code{sc-rewrite-header-list}) can be specified as a numeric argument to
759 the command. Otherwise, Supercite will query you for the index in the
762 @item @code{sc-eref-jump} (@kbd{j})
764 @findex eref-jump (sc-)
766 Display the preferred reference header, i.e., the one indexed by the current
767 value of @code{sc-preferred-header-style}.
769 @item @code{sc-eref-setn} (@kbd{s})
771 @findex eref-setn (sc-)
773 Set the preferred reference header (i.e.,
774 @code{sc-preferred-header-style}) to the currently displayed header.@refill
776 @item @code{sc-eref-exit} (@key{LFD}, @key{RET}, and @key{ESC C-c})
781 @findex eref-exit (sc-)
782 Exit from electric reference mode and insert the current header into the
785 @item @code{sc-eref-abort} (@kbd{q}, @kbd{x})
786 @findex sc-eref-abort
787 @findex eref-abort (sc-)
789 Exit from electric reference mode without inserting the current header.
792 @vindex sc-electric-mode-hook
793 @vindex electric-mode-hook (sc-)
795 Supercite will execute the hook @code{sc-electric-mode-hook} before
796 entering electric reference mode.
798 @node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top
799 @comment node-name, next, previous, up
800 @cindex citation interface specification
801 @chapter Getting Connected
805 Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
806 original message into the reply buffer. In reality, the citation of the
807 original message is performed via a call through a configurable hook
808 variable. The name of this variable has been agreed to in advance as
809 part of the @dfn{citation interface specification}. By default this
810 hook variable has a @code{nil} value, which the MUA recognizes to mean,
811 ``use your default citation function''. When you add Supercite's
812 citation function to the hook, thereby giving the variable a
813 non-@code{nil} value, it tells the MUA to run the hook via
814 @code{run-hooks} instead of using the default citation.@refill
820 * MH-E with any Emacsen::
821 * VM with any Emacsen::
822 * GNEWS with any Emacsen::
823 * Overloading for Non-conforming MUAs::
827 Early in Supercite's development, the Supercite author, a few MUA
828 authors, and some early Supercite users got together and agreed upon a
829 standard interface between MUAs and citation packages (of which
830 Supercite is currently the only known add-on @t{:-)}. With the recent
831 release of the Free Software Foundation's GNU Emacs 19, the interface
832 has undergone some modification and it is possible that not all MUAs
833 support the new interface yet. Some support only the old interface and
834 some do not support the interface at all. Still, it is possible for all
835 known MUAs to use Supercite, and the following sections will outline the
836 procedures you need to follow.
838 To learn exactly how to connect Supercite to the software systems you
839 are using, read the appropriate following sections. For details on the
840 interface specifications, or if you are writing or maintaining an MUA,
841 @pxref{Hints to MUA Authors}.
845 @findex sc-cite-original
846 @findex cite-original (sc-)
847 @findex sc-submit-bug-report
848 @findex submit-bug-report (sc-)
849 The first thing that everyone should do, regardless of the MUA you are
850 using is to set up Emacs so it will load Supercite at the appropriate
851 time. You can either dump Supercite into your Emacs binary (ask your
852 local Emacs guru how to do this if you don't know), or you can set up an
853 @dfn{autoload} for Supercite. To do the latter, put the following in
854 your @file{.emacs} file:
857 (autoload 'sc-cite-original "supercite" "Supercite 3.1" t)
858 (autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
863 The function @code{sc-cite-original} is the top-level Supercite function
864 designed to be run from the citation hook. It expects
865 @samp{point} and @samp{mark} to be set around the region to cite, and it
866 expects the original article's mail headers to be present within this
867 region. Note that Supercite @emph{never} touches any text outside this
868 region. Note further that for Emacs 19, the region need not be active
869 for @code{sc-cite-original} to do its job.
870 @xref{Hints to MUA Authors}.@refill
872 The other step in the getting connected process is to make sure your
873 MUA calls @code{sc-cite-original} at the right time. As mentioned
874 above, some MUAs handle this differently. Read the sections that follow
875 pertaining to the MUAs you are using.
878 @vindex load-hook (sc-)
880 @vindex pre-hook (sc-)
881 One final note. After Supercite is loaded into your Emacs session, it
882 runs the hook @code{sc-load-hook}. You can put any customizations into
883 this hook since it is only run once. This will not work, however, if
884 your Emacs maintainer has put Supercite into your dumped Emacs' image.
885 In that case, you can use the @code{sc-pre-hook} variable, but this will
886 get executed every time @code{sc-cite-original} is called. @xref{Reply
887 Buffer Initialization}.@refill
889 @node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected
890 @comment node-name, next, previous, up
891 @vindex mail-citation-hook
893 @section GNUS, RMAIL, or RNEWS with any Emacs 19
897 These MUAs, distributed with both FSF and Lucid GNU Emacs 19, use Emacs'
898 built-in yanking facility, which provides the citing hook variable
899 @code{mail-citation-hook}. By default, this hook's value is @code{nil},
900 but by adding the following to your @file{.emacs} file, you can tell
901 these MUAs to use Supercite to perform the citing of the original
905 (add-hook 'mail-citation-hook 'sc-cite-original)
908 GNUS users may also want to add the following bit of lisp as well. This
909 prevents GNUS from inserting its default attribution header. Otherwise,
910 both GNUS and Supercite will insert an attribution header:
913 (setq news-reply-header-hook nil)
916 Note that the @code{mail-citation-hook} interface described above was
917 not supported in FSF Emacs 19 until version 19.16 and in Lucid Emacs 19
918 until version 19.8. If you are running an earlier version of one of
919 these Emacsen, you will need to either upgrade to the latest version, or
920 use the unsupported @dfn{overloading} feature provided with Supercite.
921 @xref{Overloading for Non-conforming MUAs}.@refill
923 @node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
924 @comment node-name, next, previous, up
925 @vindex mail-citation-hook
928 @cindex sendmail.el file
929 @section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
933 These MUAs use Emacs' built-in yanking and citing routines, contained in
934 the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its
935 derivative Epoch 4, do not know anything about the citation interface
936 required by Supercite. To connect Supercite to any of these MUAs under
937 Emacs 18 or Epoch 4, you should first
938 @pxref{Overloading for Non-conforming MUAs}. Then follow the directions
939 for using these MUAs under Emacs 19.
940 @xref{Emacs 19 MUAs}.@refill
942 @cindex add-hook substitute
943 @cindex setq as a substitute for add-hook
946 @cindex sc-unsupp.el file
947 Note that those instructions will tell you to use the function
948 @code{add-hook}. This function is new with Emacs 19 and you will not
949 have it by default if you are running Emacs 18 or Epoch 4. You can
950 either substitute the appropriate call to @code{setq}, or you can use
951 the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
952 file of unsupported Supercite hacks and ideas. Or you can upgrade to
953 some Emacs 19 variant! @t{:-)}@refill
955 To use @code{setq} instead of @code{add-hook}, you would, for example,
959 (add-hook 'mail-citation-hook 'sc-cite-original)
965 (setq mail-citation-hook 'sc-cite-original)
968 Note the lack of a single quote on the first argument to @code{setq}.
970 @node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
971 @comment node-name, next, previous, up
973 @vindex mh-yank-hooks
975 @cindex mail-citation-hook
976 @section MH-E with any Emacsen
980 MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
981 by other MUAs. At the time of this writing, MH-E 4.0 has not been
982 released, but if you have it, put this in your @file{.emacs} file to
983 connect Supercite and MH-E 4.x:
986 (add-hook 'mail-citation-hook 'sc-cite-original)
989 Note that if you are using Emacs 18 or Epoch 4, you will not have the
990 @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
991 proceed without @code{add-hook}.
993 MH-E version 3.x uses a slightly different interface than other MUAs.
994 MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
995 like a hook, and doing an @code{add-hook} will not work.
997 To connect Supercite to MH-E 3.x, you should instead add the following
998 to your @code{.emacs} file:
1001 (add-hook 'mh-yank-hooks 'sc-cite-original)
1004 @vindex mh-yank-from-start-of-msg
1005 You also need to make sure that MH-E includes all the original mail
1006 headers in the yanked message. The variable that controls this is
1007 @code{mh-yank-from-start-of-msg}. By default, this variable has the
1008 value @code{t}, which tells MH-E to include all the mail headers when
1009 yanking the original message. Before you switched to using Supercite,
1010 you may have set this variable to other values so as not to include the
1011 mail headers in the yanked message. Since Supercite requires these
1012 headers (and cleans them out for you), you need to make sure the value
1013 is @code{t}. This lisp, in your @file{.emacs} file will do the trick:
1016 (setq mh-yank-from-start-of-msg t)
1019 Note that versions of MH-E before 3.7 did not provide the
1020 @code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E
1021 version 3.7 or later.
1023 @node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
1024 @comment node-name, next, previous, up
1026 @vindex mail-citation-hook
1027 @vindex mail-yank-hooks
1028 @section VM with any Emacsen
1032 Since release 4.40, VM has supported the citation interface required by
1033 Supercite. But since the interface has changed recently the details of
1034 getting connected differ with the version of VM you are using.
1036 If you are running any release of VM after 4.40, you can add the
1037 following to your @file{.emacs} to connect Supercite with VM:
1040 (add-hook 'mail-yank-hooks 'sc-cite-original)
1043 Note that if you are using Emacs 18 or Epoch 4, you will not have the
1044 @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
1045 proceed without @code{add-hook}.
1047 Since version 5.34, VM has supported the newer @code{mail-citation-hook}
1048 interface, but @code{mail-yank-hooks} is still being supported for
1049 backward compatibility. If you are running a newer version of VM and
1050 you want to maintain consistency with other MUAs, use this bit of code
1054 (add-hook 'mail-citation-hook 'sc-cite-original)
1057 @node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
1058 @comment node-name, next, previous, up@cindex .emacs file
1059 @vindex news-reply-mode-hook
1060 @findex sc-perform-overloads
1061 @findex perform-overloads (sc-)
1062 @vindex gnews-ready-hook
1063 @section GNEWS with any Emacsen
1067 As far as I know, no version of GNEWS supports the citation interface
1068 required by Supercite. To connect Supercite with GNEWS, please first
1069 @pxref{Overloading for Non-conforming MUAs}.
1071 After you have followed the directions in that section. You should add
1072 the following lisp code to your @file{.emacs} file:
1075 (add-hook 'mail-citation-hook 'sc-cite-original)
1078 Note that if you are using Emacs 18 or Epoch 4, you will not have the
1079 @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
1080 proceed without @code{add-hook}.
1082 @node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
1083 @comment node-name, next, previous, up
1085 @cindex sc-oloads.el
1086 @vindex mail-citation-hook
1087 @findex sc-perform-overloads
1089 @section Overloading for Non-conforming MUAs
1093 As mentioned elsewhere, some MUAs do not provide the necessary hooks to
1094 connect with Supercite. Supercite version 3.1 provides an unsupported
1095 mechanism, called @dfn{overloading} which redefines certain key
1096 functions in the MUA, so that it will call the @code{mail-citation-hook}
1097 variable instead of the MUA's default hard-coded citing routines. Since
1098 most newer versions of the known MUAs support the
1099 @code{mail-citation-hook} variable, it is recommended that you upgrade
1100 if at all possible. But if you can't upgrade, at least you're not out
1101 of luck! Once you set up overloading properly, you should follow the
1102 directions for connecting Supercite to the Emacs 19 MUAs.
1103 @xref{Emacs 19 MUAs}.@refill
1106 @vindex hyperb:version
1107 Users of Bob Weiner's Hyperbole package take note. Hyperbole provides
1108 the necessary overloads (and a whole lot more!) and you can potentially
1109 clobber it if you were to load Supercite's overloading after
1110 Hyperbole's. For this reason, Supercite will @emph{not} perform any
1111 overloading if it finds the variable @code{hyperb:version} is
1112 @code{boundp} (i.e. it exists because Hyperbole has been loaded into
1113 your Emacs session). If this is the case, Supercite will display a
1114 warning message in the minibuffer. You should consult the Hyperbole
1115 manual for further details.
1117 Overloading involves the re-definition of the citing function with the
1118 new, @code{mail-citation-hook} savvy version. The function in
1119 @file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This
1120 function is smart enough to only overload the MUA functions when it is
1121 absolutely necessary, based on the version numbers it can figure out.
1122 Also, @code{sc-perform-overloads} will only install the new functions
1123 once. It is also smart enough to do nothing if the MUA is not yet
1126 The tricky part is finding the right time and place to perform the
1127 overloading. It must be done after the MUA has been loaded into your
1128 Emacs session, but before the first time you try to yank in a message.
1129 Fortunately, this has been figured out for you.
1131 If you must overload, you should put the following lisp code in your
1132 @file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
1133 loaded at the right time:
1136 (autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
1139 Then you must make sure that the function @code{sc-perform-overloads}
1140 gets run at the right time. For GNUS, put this in your @file{.emacs}
1144 (setq news-reply-mode-hook 'sc-perform-overloads)
1145 (setq mail-setup-hook 'sc-perform-overloads)
1148 If you are using RNEWS, put this in your @file{.emacs} file:
1150 @vindex news-reply-mode-hook
1152 (setq news-reply-mode-hook 'sc-perform-overloads)
1155 If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
1158 (setq mail-setup-hook 'sc-perform-overloads)
1161 If you are using GNEWS, put this in your @file{.emacs} file:
1164 (setq news-reply-mode-hook 'sc-perform-overloads)
1165 (setq gnews-ready-hook 'sc-perform-overloads)
1168 Now go back and follow the directions for getting the Emacs 19 MUAs
1169 connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes
1170 for Emacs 19's @code{add-hook} function.@refill
1172 @node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
1173 @comment node-name, next, previous, up
1174 @chapter Replying and Yanking
1177 This chapter explains what happens when you reply and yank an original
1178 message from an MUA.
1181 * Reply Buffer Initialization::
1182 * Filling Cited Text::
1185 @node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
1186 @comment node-name, next, previous, up
1187 @findex sc-cite-original
1188 @findex cite-original (sc-)
1190 @section Reply Buffer Initialization
1194 Executing @code{sc-cite-original} performs the following steps as it
1195 initializes the reply buffer:
1200 @vindex pre-hook (sc-)
1201 @emph{Runs @code{sc-pre-hook}.}
1202 This hook variable is run before @code{sc-cite-original} does any other
1203 work. You could conceivably use this hook to set certain Supercite
1204 variables based on the reply buffer's mode or name (i.e., to do
1205 something different based on whether you are replying or following up to
1209 @emph{Inserts Supercite's keymap.}
1210 @vindex sc-mode-map-prefix
1211 @vindex mode-map-prefix (sc-)
1213 @cindex keymap prefix
1214 Supercite provides a number of commands for performing post-yank
1215 modifications to the reply buffer. These commands are installed on
1216 Supercite's top-level keymap. Since Supercite has to interface with a
1217 wide variety of MUAs, it does not install all of its commands directly
1218 into the reply buffer's keymap. Instead, it puts its commands on a
1219 keymap prefix, then installs this prefix onto the buffer's keymap. What
1220 this means is that you typically have to type more characters to invoke
1221 a Supercite command, but Supercite's keybindings can be made much more
1222 consistent across MUAs.
1224 You can control what key Supercite uses as its keymap prefix by changing
1225 the variable @code{sc-mode-map-prefix}. By default, this variable is
1226 set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the
1227 best default due to the scarcity of available keybindings in many MUAs.
1230 @emph{Turns on Supercite minor mode.}
1232 The modeline of the reply buffer should indicate that Supercite is
1233 active in that buffer by displaying the string @samp{SC}.
1236 @emph{Sets the ``Undo Boundary''.}
1237 @cindex undo boundary
1238 Supercite sets an undo boundary before it begins to modify the original
1239 yanked text. This allows you to easily undo Supercite's changes to
1240 affect alternative citing styles.
1243 @emph{Processes the mail headers.}
1244 @vindex sc-confirm-always-p
1245 @vindex confirm-always-p (sc-)
1246 @vindex sc-mail-warn-if-non-rfc822-p
1247 @vindex mail-warn-if-non-rfc822-p (sc-)
1248 All previously retrieved info key-value pairs are deleted from the info
1249 alist, then the mail headers in the body of the yanked message are
1250 scanned. Info key-value pairs are created for each header found. Also,
1251 such useful information as the author's name and email address are
1252 extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is
1253 non-@code{nil}, then Supercite will warn you if it finds a mail header
1254 that does not conform to RFC822. This is rare and indicates a problem
1255 either with your MUA or the original author's MUA, or some MTA (mail
1256 transport agent) along the way.
1258 @vindex sc-nuke-mail-headers
1259 @vindex sc-nuke-mail-header-list
1260 @vindex nuke-mail-headers (sc-)
1261 @vindex nuke-mail-header-list (sc-)
1262 Once the info keys have been extracted from the mail headers, the
1263 headers are nuked from the reply buffer. You can control exactly which
1264 headers are removed or kept, but by default, all headers are removed.
1266 There are two variables which control mail header nuking. The variable
1267 @code{sc-nuke-mail-headers} controls the overall behavior of the header
1268 nuking routines. By setting this variable to @code{'all}, you
1269 automatically nuke all mail headers. Likewise, setting this variable to
1270 @code{'none} inhibits nuking of any mail headers. In between these
1271 extremes, you can tell Supercite to nuke only a specified list of mail
1272 headers by setting this variable to @code{'specified}, or to keep only a
1273 specified list of headers by setting it to @code{'keep}.
1275 If @code{sc-nuke-mail-headers} is set to @code{'specified} or
1276 @code{'keep}, then the variable @code{sc-nuke-mail-header-list} is
1277 consulted for the list of headers to nuke or keep. This variable
1278 contains a list of regular expressions. If the mail header line matches
1279 a regular expression in this list, the header will be nuked or kept.
1280 The line is matched against the regexp using @code{looking-at} rooted at
1281 the beginning of the line.
1283 @vindex sc-blank-lines-after-headers
1284 @vindex blank-lines-after-headers (sc-)
1285 If the variable @code{sc-blank-lines-after-headers} is non-@code{nil},
1286 it contains the number of blank lines remaining in the buffer after mail
1287 headers are nuked. By default, only one blank line is left in the buffer.
1290 @emph{Selects the attribution and citation strings.}
1291 Once the mail headers have been processed, Supercite selects a
1292 attribution string and a citation string which it will use to cite the
1293 original message. @xref{Selecting an Attribution}, for details.
1296 @emph{Cites the message body.}
1297 @vindex sc-cite-region-limit
1298 @vindex cite-region-limit (sc-)b
1299 After the selection of the attribution and citation strings, Supercite
1300 cites the original message by inserting the citation string prefix in
1301 front of every uncited line. You may not want Supercite to
1302 automatically cite very long messages however. For example, some email
1303 could contain a smaller header section followed by a huge uuencoded
1304 message. It wouldn't make sense to cite the uuencoded message part when
1305 responding to the original author's short preface. For this reason,
1306 Supercite provides a variable which limits the automatic citation of
1307 long messages to a certain maximum number of lines. The variable is
1308 called @code{sc-cite-region-limit}. If this variable contains an
1309 integer, messages with more lines that this will not be cited at all,
1310 and a warning message will be displayed. Supercite has performed
1311 everything necessary, though, for you to manually cite only the small
1312 portion of the original message that you want to use.
1314 If @code{sc-cite-region-limit} contains a non-@code{nil} value, the
1315 original message will always be cited, regardless of its size. If the
1316 variable contains the value @code{nil}, the region will never be cited
1317 automatically. Use this if you always want to be able to edit and cite
1318 the message manually.
1320 @vindex sc-cite-blank-lines-p
1321 @vindex cite-blank-lines-p (sc-)
1322 The variable @code{sc-cite-blank-lines-p} controls whether blank lines
1323 in the original message should be cited or not. If this variable is
1324 non-@code{nil}, blank lines will be cited just like non-blank lines.
1325 Otherwise, blank lines will be treated as paragraph separators.
1327 Citing of the original message is highly configurable. Supercite's
1328 default setup does a pretty good job of citing many common forms of
1329 previously cited messages. But there are as many citation styles out
1330 there as people on the net, or just about! It would be impossible for
1331 Supercite to anticipate every style in existence, and you probably
1332 wouldn't encounter them all anyway. But you can configure Supercite to
1333 recognize those styles you see often.
1334 @xref{Configuring the Citation Engine}, for details.@refill
1337 @emph{Runs @code{sc-post-hook}.}
1338 @vindex sc-post-hook
1339 @vindex post-hook (sc-)
1340 This variable is very similar to @code{sc-pre-hook}, except that it runs
1341 after @code{sc-cite-original} is finished. This hook is provided mostly
1342 for completeness and backward compatibility. Perhaps it could be used to
1343 reset certain variables set in @code{sc-pre-hook}.@refill
1346 @node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
1347 @comment node-name, next, previous, up
1348 @cindex filling paragraphs
1349 @vindex sc-auto-fill-region-p
1350 @vindex auto-fill-region-p (sc-)
1353 @findex sc-setup-filladapt
1354 @findex setup-filladapt (sc-)
1355 @vindex sc-load-hook
1356 @vindex load-hook (sc-)
1357 @section Filling Cited Text
1361 Supercite will automatically fill newly cited text from the original
1362 message unless the variable @code{sc-auto-fill-region-p} has a
1363 @code{nil} value. Supercite will also re-fill paragraphs when you
1364 manually cite or re-cite text.
1366 However, during normal editing, Supercite itself cannot be used to fill
1367 paragraphs. This is a change from version 2. There are other add-on
1368 lisp packages which do filling much better than Supercite ever did. The
1369 two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well
1370 with Supercite and both are available at the normal Emacs Lisp archive
1371 sites. @dfn{gin-mode} works pretty well out of the box, but if you use
1372 @dfn{filladapt}, you may want to run the function
1373 @code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply
1374 makes @dfn{filladapt} a little more Supercite savvy than its default
1377 @vindex sc-fixup-whitespace-p
1378 @vindex fixup-whitespace-p (sc-)
1379 Also, Supercite will collapse leading whitespace between the citation
1380 string and the text on a line when the variable
1381 @code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for
1382 this variable is @code{nil}.@refill
1385 Its important to understand that Supercite's automatic filling (during
1386 the initial citation of the reply) is very fragile. That is because
1387 figuring out the @code{fill-prefix} for a particular paragraph is a
1388 really hard thing to do automatically. This is especially the case when
1389 the original message contains code or some other text where leading
1390 whitespace is important to preserve. For this reason, many Supercite
1391 users typically run with @code{sc-auto-fill-region-p} (and possibly also
1392 @code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually
1393 fill each cited paragraph in the reply buffer.
1395 I usually run with both these variables containing their default values.
1396 When Supercite's automatic filling breaks on a particular message, I
1397 will use Emacs' undo feature to undo back before the citation was
1398 applied to the original message. Then I'll toggle the variables and
1399 manually cite those paragraphs that I don't want to fill or collapse
1400 whitespace on. @xref{Variable Toggling Shortcuts}.@refill
1403 If you find that Supercite's automatic filling is just too fragile for
1404 your tastes, you might consider one of these alternate approaches.
1405 Also, to make life easier, a shortcut function to toggle the state of
1406 both of these variables is provided on the key binding
1407 @kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix};
1408 @pxref{Post-yank Formatting Commands}).@refill
1410 You will noticed that the minor mode string will
1411 show the state of these variables as qualifier characters. When both
1412 variables are @code{nil}, the Supercite minor mode string will display
1413 @samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
1414 string will display @samp{SC:f}, and when just
1415 @code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display
1416 @samp{SC:w}. When both variables are non-@code{nil}, the string will
1417 display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for
1418 the default bindings of the toggling function for each respective
1420 @xref{Variable Toggling Shortcuts}.@refill
1422 Why are these variables not set to @code{nil} by default? It is because
1423 many users won't manually fill paragraphs that are Supercited, and there
1424 have been widespread complaints on the net about mail and news messages
1425 containing lines greater than about 72 characters. So the default is to
1428 @node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
1429 @comment node-name, next, previous, up
1430 @cindex attribution list
1431 @vindex sc-preferred-attribution-list
1432 @vindex preferred-attribution-list (sc-)
1434 @chapter Selecting an Attribution
1438 As you know, the attribution string is the part of the author's name
1439 that will be used to composed a non-nested citation string. Supercite
1440 scans the various mail headers present in the original article and uses
1441 a number of heuristics to extract strings which it puts into the
1442 @dfn{attribution association list} or @dfn{attribution alist}. This is
1443 analogous, but different than, the info alist previously mentioned. Each
1444 element in the attribution alist is a key-value pair containing such
1445 information as the author's first name, middle names, and last name, the
1446 author's initials, and the author's email terminus.
1450 * Attribution Preferences::
1451 * Anonymous Attributions::
1456 @node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
1457 @comment node-name, next, previous, up
1458 @section Attribution Preferences
1462 When you cite an original message, you can tell Supercite which part of
1463 the author's name you would prefer it to use as the attribution. The
1464 variable @code{sc-preferred-attribution-list} controls this; it contains
1465 keys which are matched against the attribution alist in the given order.
1466 The first value of a key that produces a non-@code{nil}, non-empty
1467 string match is used as the attribution string, and if no keys match, a
1468 secondary mechanism is used to generate the attribution.
1469 @xref{Anonymous Attributions}.
1471 The following preferences are always available in the attribution alist
1476 the author's email terminus.
1479 the author's initials.
1482 the author's first name.
1485 the author's last name.
1487 @item "middlename-1"
1488 the author's first middle name.
1490 @item "sc-lastchoice"
1491 the last attribution string you have selected. This is useful when you
1492 recite paragraphs in the reply.@refill
1495 @vindex sc-attrib-selection-list
1496 @vindex attrib-selection-list (sc-)
1497 consults the customizable list @code{sc-attrib-selection-list} which can
1498 be used to select special attributions based on the value of any info
1499 key. See below for details.
1501 @item "x-attribution"
1502 the original author's suggestion for attribution string choice. See below
1506 Middle name indexes can be any positive integer greater than zero,
1507 though it is unlikely that many authors will have more than one middle
1510 At this point, let me digress into a discussion of etiquette. It is my
1511 belief that while the style of the citations is a reflection of the
1512 personal tastes of the replier (i.e., you), the attribution selection is
1513 ultimately the personal choice of the original author. In a sense it is
1514 his or her ``net nickname'', and therefore the author should have some
1515 say in the selection of attribution string. Imagine how you would feel
1516 if someone gave you a nickname that you didn't like?
1518 For this reason, Supercite recognizes a special mail header,
1519 @samp{X-Attribution:}, which if present, tells Supercite the attribution
1520 string preferred by the original author. It is the value of this header
1521 that is associated with the @code{"x-attribution"} key in the
1522 attribution alist. Currently, you can override the preference of this
1523 key by changing @code{sc-preferred-attribution-list}, but that isn't
1524 polite, and in the future Supercite may hard-code this. For now, it is
1525 suggested that if you change the order of the keys in this list, that
1526 @code{"x-attribution"} always be first, or possible second behind only
1527 @code{"sc-lastchoice"}. This latter is the default.
1529 @vindex sc-attrib-selection-list
1530 @vindex attrib-selection-list (sc-)
1531 The value @code{"sc-consult"} in @code{sc-preferred-attribution-list}
1532 has a special meaning during attribution selection. When Supercite
1533 encounters this preference, it begins processing a customizable list of
1534 attributions, contained in the variable @code{sc-attrib-selection-list}.
1535 Each element in this list contains lists of the following form:
1539 (@var{infokey} ((@var{regexp} @. @var{attribution})
1540 (@var{regexp} @. @var{attribution})
1546 @findex sc-mail-field
1547 @findex mail-field (sc-)
1548 where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
1549 is a regular expression to match against the @var{infokey}'s value. If
1550 @var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
1551 used as the attribution string. Actually, @var{attribution} can be a
1552 string or a list; if it is a list, it is @code{eval}uated and the return
1553 value (which must be a string), is used as the attribution.
1555 This can be very useful for when you are replying to net acquaintances
1556 who do not use the @samp{X-Attribution:@:} mail header. You may know
1557 what nickname they would prefer to use, and you can set up this list to
1558 match against a specific mail field, e.g., @samp{From:@:}, allowing you
1559 to cite your friend's message with the appropriate attribution.
1561 @node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
1562 @comment node-name, next, previous, up
1563 @vindex sc-default-author-name
1564 @vindex default-author-name (sc-)
1565 @vindex sc-default-attribution
1566 @vindex default-attribution (sc-)
1568 @section Anonymous Attributions
1572 When the author's name cannot be found in the @samp{From:@:} mail
1573 header, a fallback author name and attribution string must be supplied.
1574 The fallback author name is contained in the variable
1575 @code{sc-default-author-name} and the fallback attribution string is
1576 contained in the variable @code{sc-default-attribution}. Default values
1577 for these variables are @code{"Anonymous"} and @code{"Anon"},
1578 respectively. Note that in most circumstances, getting the default
1579 author name or attribution is a sign that something is set up
1582 @vindex sc-use-only-preference-p
1583 @vindex use-only-preference-p (sc-)
1584 Also, if the preferred attribution, which you specified in your
1585 @code{sc-preferred-attribution-alist} variable cannot be found, a
1586 secondary method can be employed to find a valid attribution string. The
1587 variable @code{sc-use-only-preference-p} controls what happens in this
1588 case. If the variable's value is non-@code{nil}, then
1589 @code{sc-default-author-name} and @code{sc-default-attribution} are
1590 used, otherwise, the following steps are taken to find a valid
1591 attribution string, and the first step to return a non-@code{nil},
1592 non-empty string becomes the attribution:@refill
1596 Use the last selected attribution, if there is one.
1599 Use the value of the @code{"x-attribution"} key.
1602 Use the author's first name.
1605 Use the author's last name.
1608 Use the author's initials.
1611 Find the first non-@code{nil}, non-empty attribution string in the
1615 @code{sc-default-attribution} is used.
1618 @vindex sc-confirm-always-p
1619 @vindex confirm-always-p (sc-)
1620 Once the attribution string has been automatically selected, a number of
1621 things can happen. If the variable @code{sc-confirm-always-p} is
1622 non-@code{nil}, you are queried for confirmation of the chosen
1623 attribution string. The possible values for completion are those strings
1624 in the attribution alist, however you are not limited to these choices.
1625 You can type any arbitrary string at the confirmation prompt. The string
1626 you enter becomes the value associated with the @code{"sc-lastchoice"}
1627 key in the attribution alist.
1629 @vindex sc-downcase-p
1630 @vindex downcase-p (sc-)
1631 Once an attribution string has been selected, Supercite will force the
1632 string to lower case if the variable @code{sc-downcase-p} is
1635 @vindex sc-attribs-preselect-hook
1636 @vindex attribs-preselect-hook (sc-)
1637 @vindex sc-attribs-postselect-hook
1638 @vindex attribs-postselect-hook (sc-)
1640 Two hook variables provide even greater control of the attribution
1641 selection process. The hook @code{sc-attribs-preselect-hook} is run
1642 before any attribution is selected. Likewise, the hook
1643 @code{sc-attribs-postselect-hook} is run after the attribution is
1644 selected (and the corresponding citation string is built), but before
1645 these values are committed for use by Supercite. During the
1646 post-selection hook, the local variables @code{attribution} and
1647 @code{citation} are bound to the appropriate strings. By changing these
1648 variables in your hook functions, you change the attribution and
1649 citation strings used by Supercite. One possible use of this would be
1650 to override any automatically derived attribution string when it is only
1651 one character long; e.g. you prefer to use @code{"initials"} but the
1652 author only has one name.@refill
1654 @node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
1655 @comment node-name, next, previous, up
1656 @cindex author names
1657 @section Author Names
1661 Supercite employs a number of heuristics to decipher the author's name
1662 based on value of the @samp{From:@:} mail field of the original message.
1663 Supercite can recognize almost all of the common @samp{From:@:} field
1664 formats in use. If you encounter a @samp{From:@:} field that Supercite
1665 cannot parse, please report this bug.
1666 @xref{The Supercite Mailing List}.@refill
1668 @vindex sc-titlecue-regexp
1669 @vindex titlecue-regexp (sc-)
1670 There are a number of Supercite variables that control how author names
1671 are extracted from the @samp{From:@:} header. Some headers may contain a
1672 descriptive title as in:
1675 From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
1678 Supercite knows which part of the @samp{From:@:} header is email address
1679 and which part is author name, but in this case the string @code{"Decent
1680 Hacker"} is not part of the author's name. You can tell Supercite to
1681 ignore the title, while still recognizing hyphenated names through the
1682 use of a regular expression in the variable @code{sc-titlecue-regexp}.
1683 This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any
1684 text after this regexp is encountered is ignored as noise.
1686 @vindex sc-name-filter-alist
1687 @vindex name-filter-alist (sc-)
1688 Some @samp{From:@:} headers may contain extra titles in the name fields
1689 not separated by a title cue, but which are nonetheless not part of the
1690 author's name proper. Examples include the titles ``Dr.'', ``Mr.'',
1691 ``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third).
1692 Also, some companies prepend or append the name of the division,
1693 organization, or project on the author's name. All of these titles are
1694 noise which should be ignored. The variable @code{sc-name-filter-alist}
1695 is used for this purpose. As implied by its name, this variable is an
1696 association list, where each element is a cons cell of the form:
1699 (@var{regexp} @. @var{position})
1703 where @var{regexp} is a regular expression that is matched (using
1704 @code{string-match}) against each element of the @samp{From:@:} field's
1705 author name. @var{position} is a position indicator, starting at zero.
1706 Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
1707 @code{sc-name-filter-alist} would have an entry such as:
1710 ("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
1714 which only removes them if they appear as the first word in the name.
1715 The position indicator is an integer, or one of the two special symbols
1716 @code{last} or @code{any}. @code{last} always matches against the last
1717 word in the name field, while @code{any} matches against every word in
1720 @node Configuring the Citation Engine, Using Regi, Author Names, Top
1721 @comment node-name, next, previous, up
1723 @cindex frames (Regi)
1724 @cindex entries (Regi)
1725 @chapter Configuring the Citation Engine
1729 At the heart of Supercite is a regular expression interpreting engine
1730 called @dfn{Regi}. Regi operates by interpreting a data structure
1731 called a Regi-frame (or just @dfn{frame}), which is a list of
1732 Regi-entries (or just @dfn{entry}). Each entry contains a predicate,
1733 typically a regular expression, which is matched against a line of text
1734 in the current buffer. If the predicate matches true, an associated
1735 expression is @code{eval}uated. In this way, an entire region of text
1736 can be transformed in an @emph{awk}-like manner. Regi is used
1737 throughout Supercite, from mail header information extraction, to header
1738 nuking, to citing text.
1743 * Frames You Can Customize::
1747 While the details of Regi are discussed below (@pxref{Using Regi}), only
1748 those who wish to customize certain aspects of Supercite need concern
1749 themselves with it. It is important to understand though, that any
1750 conceivable citation style that can be described by a regular expression
1751 can be recognized by Supercite. This leads to some interesting
1752 applications. For example, if you regularly recieve email from a
1753 co-worker that uses an uncommon citation style (say one that employs a
1754 @samp{|} or @samp{@}} character at the front of the line), it is
1755 possible for Supercite to recognize this and @emph{coerce} the citation
1756 to your preferred style, for consistency. In theory, it is possible for
1757 Supercite to recognize such things as uuencoded messages or C code and
1758 cite or fill those differently than normal text. None of this is
1759 currently part of Supercite, but contributions are welcome!
1761 @node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
1762 @comment node-name, next, previous, up
1763 @findex regi-interpret
1770 Regi works by interpreting frames with the function
1771 @code{regi-interpret}. A frame is a list of arbitrary size where each
1772 element is a entry of the following form:
1775 (@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]])
1778 Regi starts with the first entry in a frame, evaluating the @var{pred}
1779 of that entry against the beginning of the line that @samp{point} is on.
1780 If the @var{pred} evaluates to true (or false if the optional
1781 @var{negate-p} is non-@code{nil}), then the @var{func} for that entry is
1782 @code{eval}uated. How processing continues is determined by the return
1783 value for @var{func}, and is described below. If @var{pred} was false
1784 the next entry in the frame is checked until all entries have been
1785 matched against the current line. If no entry matches, @samp{point} is
1786 moved forward one line and the frame is reset to the first entry.
1788 @var{pred} can be a string, a variable, a list or one of the following
1789 symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If
1790 @var{pred} is a string, or a variable or list that @code{eval}uates to a
1791 string, it is interpreted as a regular expression. This regexp is
1792 matched against the current line, from the beginning, using
1793 @code{looking-at}. This match folds case if the optional
1794 @var{case-fold-search} is non-@code{nil}. If @var{pred} is not a
1795 string, or does not @code{eval}uate to a string, it is interpreted as a
1796 binary value (@code{nil} or non-@code{nil}).@refill
1798 The four special symbol values for @var{pred} are recognized:
1802 Always produces a true outcome.
1804 Always executed before the frame is interpreted. This can be used to
1805 initialize some global variables for example.
1807 Always executed after frame interpreting is completed. This can be used
1808 to perform any necessary post-processing.
1810 Executes whenever the frame is reset, usually after the entire frame has
1811 been matched against the current line.
1814 Note that @var{negate-p} and @var{case-fold-search} are ignored if
1815 @var{pred} is one of these special symbols. Only the first occurance of
1816 each symbol in a frame is used; any duplicates are ignored. Also
1817 note that for performance reasons, the entries associated with these
1818 symbols are removed from the frame during the main interpreting loop.
1820 Your @var{func} can return certain values which control continued Regi
1821 processing. By default, if your @var{func} returns @code{nil} (as it
1822 should be careful to do explicitly), Regi will reset the frame to the
1823 first entry, and advance @samp{point} to the beginning of the next line.
1824 If a list is returned from your function, it can contain any combination
1825 of the following elements:@refill
1828 @item the symbol @code{continue}
1829 This tells Regi to continue processing entries after a match, instead of
1830 reseting the frame and moving @samp{point}. In this way, lines of text
1831 can have multiple matches, but you have to be careful to avoid entering
1834 @item the symbol @code{abort}
1835 This tells Regi to terminate frame processing. However, any @code{end}
1836 entry is still processed.
1838 @item the list @code{(frame . @var{newframe})}
1839 This tells Regi to substitute @var{newframe} as the frame it is
1840 interpreting. In other words, your @var{func} can modify the Regi frame
1841 on the fly. @var{newframe} can be a variable containing a frame, or it
1842 can be the frame in-lined.@refill
1844 @item the list @code{(step . @var{step})}
1845 Tells Regi to move @var{step} number of lines forward as it continues
1846 processing. By default, Regi moves forward one line. @var{step} can be
1847 zero or negative of course, but watch out for infinite loops.@refill
1850 During execution of your @var{func}, the following variables will be
1851 temporarily bound to some useful information:@refill
1855 The current line in the buffer that Regi is @code{looking-at}, as a string.
1857 The current frame being interpreted.
1859 The current frame entry being interpreted.
1862 @node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
1863 @comment node-name, next, previous, up
1864 @vindex sc-nuke-mail-header
1865 @section Frames You Can Customize
1869 As mentioned earlier, Supercite uses various frames to perform
1870 certain jobs such as mail header information extraction and mail header
1871 nuking. However, these frames are not available for you to customize,
1872 except through abstract interfaces such as @code{sc-nuke-mail-header},
1875 @vindex sc-default-cite-frame
1876 However, the citation frames Supercite uses provide a lot of customizing
1877 power and are thus available to you to change to suit your needs. The
1878 workhorse of citation is the frame contained in the variable
1879 @code{sc-default-cite-frame}. This frame recognizes many situations,
1880 such as blank lines, which it interprets as paragraph separators. It
1881 also recognizes previously cited nested and non-nested citations in the
1882 original message. By default it will coerce non-nested citations into
1883 your preferred citation style, and it will add a level of citation to
1884 nested citations. It will also simply cite uncited lines in your
1889 @vindex sc-default-uncite-frame
1890 @vindex sc-default-recite-frame
1891 In a similar vein, there are default frames for @dfn{unciting} and
1892 @dfn{reciting}, contained in the variables
1893 @code{sc-default-uncite-frame} and @code{sc-default-recite-frame}
1894 respectively.@refill
1896 As mentioned earlier (@pxref{Recognizing Citations}), citations are
1897 recognized through the values of the regular expressions
1898 @code{sc-citation-root-regexp}, et al. To recognize odd styles, you
1899 could modify these variables, or you could modify the default citing
1900 frame. Alternatively, you could set up association lists of frames for
1901 recognizing specific alternative forms.
1903 @vindex sc-cite-frame-alist
1904 @vindex sc-uncite-frame-alist
1905 @vindex sc-recite-frame-alist
1906 For each of the actions -- citing, unciting, and reciting -- an alist is
1907 consulted to find the frame to use (@code{sc-cite-frame-alist},
1908 @code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
1909 respectively). These frames can contain alists of the form:
1912 ((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
1913 (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
1917 @vindex sc-mail-field
1918 @findex string-match
1919 Where @var{infokey} is a key suitable for @code{sc-mail-field},
1920 @var{regexp} is a regular expression which is @code{string-match}'d
1921 against the value of the @code{sc-mail-field} key, and @var{frame} is
1922 the frame to use if a match occurred. @var{frame} can be a variable
1923 containing a frame or a frame in-lined.@refill
1925 When Supercite is about to cite, uncite, or recite a region, it consults
1926 the appropriate alist and attempts to find a frame to use. If one
1927 is not found from the alist, then the appropriate default frame is used.
1929 @node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
1930 @comment node-name, next, previous, up
1931 @vindex sc-mode-map-prefix
1932 @vindex mode-map-prefix (sc-)
1934 @chapter Post-yank Formatting Commands
1938 Once the original message has been yanked into the reply buffer, and
1939 @code{sc-cite-original} has had a chance to do its thing, a number of
1940 useful Supercite commands will be available to you. Since there is wide
1941 variety in the keymaps that MUAs set up in their reply buffers, it is
1942 next to impossible for Supercite to properly sprinkle its commands into
1943 the existing keymap. For this reason Supercite places its commands on a
1944 separate keymap, putting this keymap onto a prefix key in the reply
1945 buffer. You can customize the prefix key Supercite uses by changing the
1946 variable @code{sc-mode-map-prefix}. By default, the
1947 @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
1948 but unfortunately the best general solution so far. In the rest of this
1949 chapter, we'll assume you've installed Supercite's keymap on the default
1955 * Insertion Commands::
1956 * Variable Toggling Shortcuts::
1957 * Mail Field Commands::
1958 * Miscellaneous Commands::
1962 @node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
1963 @comment node-name, next, previous, up
1964 @vindex sc-cite-region-limit
1965 @section Commands to Manually Cite, Recite, and Uncite
1969 Probably the three most common post-yank formatting operations that you
1970 will perform will be the manual citing, reciting, and unciting of
1971 regions of text in the reply buffer. Often you may want to recite a
1972 paragraph to use a nickname, or manually cite a message when setting
1973 @code{sc-cite-region-limit} to @code{nil}. The following commands
1974 perform these functions on the region of text between @samp{point} and
1975 @samp{mark}. Each of them sets the @dfn{undo boundary} before modifying
1976 the region so that the command can be undone in the standard Emacs
1979 A quick note about Emacs 19. Unlike in Emacs 18, the region delimited
1980 by @samp{point} and @samp{mark} can have two states. It can be
1981 @dfn{active} or @dfn{inactive}. Although the FSF Emacs 19 and Lucid
1982 Emacs 19 use different terminology and functions, both employ the same
1983 convention such that when the region is inactive, commands that modify
1984 the region should generate an error. The user needs to explicitly
1985 activate the region before successfully executing the command. All
1986 Supercite commands conform to this convention.
1988 Here is the list of Supercite citing commands:
1991 @findex sc-cite-region
1992 @findex cite-region (sc-)
1994 @vindex sc-pre-cite-hook
1995 @vindex pre-cite-hook (sc-)
1996 @vindex sc-confirm-always-p
1997 @vindex confirm-always-p
1999 @item @code{sc-cite-region} (@kbd{C-c C-p c})
2001 This command cites each line in the region of text by interpreting the
2002 selected frame from @code{sc-cite-frame-alist}, or the default citing
2003 frame @code{sc-default-cite-frame}. It runs the hook
2004 @code{sc-pre-cite-hook} before interpreting the frame. With an optional
2005 universal argument (@kbd{C-u}), it temporarily sets
2006 @code{sc-confirm-always-p} to @code{t} so you can confirm the
2007 attribution string for a single manual citing.
2008 @xref{Configuring the Citation Engine}.@refill
2010 @findex sc-uncite-region
2011 @findex uncite-region (sc-)
2013 @item @code{sc-uncite-region} (@kbd{C-c C-p u})
2015 This command removes any citation strings from the beginning of each
2016 cited line in the region by interpreting the selected frame from
2017 @code{sc-uncite-frame-alist}, or the default unciting frame
2018 @code{sc-default-uncite-frame}. It runs the hook
2019 @code{sc-pre-uncite-hook} before interpreting the frame.
2020 @xref{Configuring the Citation Engine}.@refill
2022 @findex sc-recite-region
2023 @findex recite-region (sc-)
2025 @item @code{sc-recite-region} (@kbd{C-c C-p r})
2027 This command recites each line the region by interpreting the selected
2028 frame from @code{sc-recite-frame-alist}, or the default reciting frame
2029 @code{sc-default-recite-frame}. It runs the hook
2030 @code{sc-pre-recite-hook} before interpreting the frame.
2031 @xref{Configuring the Citation Engine}.@refill
2033 @vindex sc-confirm-always-p
2034 @vindex confirm-always-p (sc-)
2035 Supercite will always ask you to confirm the attribution when reciting a
2036 region, regardless of the value of @code{sc-confirm-always-p}.
2039 @node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
2040 @comment node-name, next, previous, up
2041 @section Insertion Commands
2045 These two functions insert various strings into the reply buffer.
2048 @findex sc-insert-reference
2049 @findex insert-reference (sc-)
2051 @item @code{sc-insert-reference} (@kbd{C-c C-p w})
2053 @vindex sc-preferred-header-style
2054 @vindex preferred-header-style (sc-)
2055 Inserts a reference header into the reply buffer at @samp{point}. With
2056 no arguments, the header indexed by @code{sc-preferred-header-style} is
2057 inserted. An optional numeric argument is the index into
2058 @code{sc-rewrite-header-list} indicating which reference header to
2061 With just the universal argument (@kbd{C-u}), electric reference mode is
2062 entered, regardless of the value of @code{sc-electric-references-p}.
2064 @findex sc-insert-citation
2065 @findex insert-citation (sc-)
2067 @item @code{sc-insert-citation} (@kbd{C-c C-p i})
2069 Inserts the current citation string at the beginning of the line that
2070 @samp{point} is on. If the line is already cited, Supercite will issue
2071 an error and will not cite the line.
2074 @node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
2075 @comment node-name, next, previous, up
2076 @cindex toggling variables
2077 @section Variable Toggling Shortcuts
2081 Supercite defines a number of commands that make it easier for you to
2082 toggle and set various Supercite variables as you are editing the reply
2083 buffer. For example, you may want to turn off filling or whitespace
2084 cleanup, but only temporarily. These toggling shortcut commands make
2088 Like Supercite commands in general, the toggling commands are placed on
2089 a keymap prefix within the greater Supercite keymap. For the default
2090 value of @code{sc-mode-map-prefix}, this will be
2091 @kbd{C-c C-p C-t}.@refill
2093 The following commands toggle the value of certain Supercite variables
2094 which take only a binary value:
2098 Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
2101 Toggles the variable @code{sc-confirm-always-p}.
2104 Toggles the variable @code{sc-downcase-p}.
2107 Toggles the variable @code{sc-electric-references-p}.
2110 Toggles the variable @code{sc-auto-fill-region-p}.
2113 Toggles the variable @code{sc-electric-circular-p}.
2116 Toggles the variable @code{sc-nested-citation-p}.
2119 Toggles the variable @code{sc-use-only-preferences-p}.
2122 Toggles the variable @code{sc-fixup-whitespace-p}.
2125 @findex set-variable
2126 The following commands let you set the value of multi-value variables,
2127 in the same way that Emacs' @code{set-variable} does:
2131 Sets the value of the variable @code{sc-preferred-attribution-list}.
2134 Sets the value of the variable @code{sc-cite-region-limit}.
2137 Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
2140 Sets the value of the variable @code{sc-mail-header-nuke-list}.
2143 Sets the value of the variable @code{sc-preferred-header-style}.
2147 One special command is provided to toggle both
2148 @code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together.
2149 This is because you typically want to run Supercite with either variable
2150 as @code{nil} or non-@code{nil}. The command to toggle these variables
2151 together is bound on @kbd{C-c C-p C-p}.@refill
2153 Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?})
2154 brings up a Help message on the toggling keymap.
2157 @node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
2158 @comment node-name, next, previous, up
2159 @section Mail Field Commands
2163 These commands allow you to view, modify, add, and delete various bits
2164 of information from the info alist.
2165 @xref{Information Keys and the Info Alist}.@refill
2169 @findex sc-mail-field-query
2170 @findex mail-field-query (sc-)
2172 @item @code{sc-mail-field-query} (@kbd{C-c C-p f})
2174 Allows you to interactively view, modify, add, and delete info alist
2175 key-value pairs. With no argument, you are prompted (with completion)
2176 for a info key. The value associated with that key is displayed in the
2177 minibuffer. With an argument, this command will first ask if you want
2178 to view, modify, add, or delete an info key. Viewing is identical to
2179 running the command with no arguments.
2181 If you want to modify the value of a key, Supercite will first prompt
2182 you (with completion) for the key of the value you want to change. It
2183 will then put you in the minibuffer with the key's current value so you
2184 can edit the value as you wish. When you hit @key{RET}, the key's value
2185 is changed. For those of you running Emacs 19, minibuffer history is
2186 kept for the values.
2188 If you choose to delete a key-value pair, Supercite will prompt you (with
2189 completion) for the key to delete.
2191 If you choose to add a new key-value pair, Supercite firsts prompts you
2192 for the key to add. Note that completion is turned on for this prompt,
2193 but you can type any key name here, even one that does not yet exist.
2194 After entering the key, Supercite prompts you for the key's value. It
2195 is not an error to enter a key that already exists, but the new value
2196 will override any old value. It will not replace it though; if you
2197 subsequently delete the key-value pair, the old value will reappear.
2199 @findex sc-mail-process-headers
2200 @findex mail-process-headers (sc-)
2202 @item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
2204 This command lets you re-initialize Supercite's info alist from any set
2205 of mail headers in the region between @samp{point} and @samp{mark}.
2206 This function is especially useful for replying to digest messages where
2207 Supercite will initially set up its information for the digest
2208 originator, but you want to cite each component article with the real
2209 message author. Note that unless an error during processing occurs, any
2210 old information is lost.@refill
2213 @node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
2214 @comment node-name, next, previous, up
2215 @section Miscellaneous Commands
2220 @findex sc-open-line
2221 @findex open-line (sc-)
2224 @item @code{sc-open-line} (@kbd{C-c C-p o})
2226 Similar to Emacs' standard @code{open-line} commands, but inserts the
2227 citation string in front of the new line. As with @code{open-line},
2228 an optional numeric argument inserts that many new lines.@refill
2231 @findex describe (sc-)
2234 @item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
2236 This function has been obsoleted by the @TeX{}info manual you are now
2237 reading. It is still provided for compatibility, but it will eventually
2241 @findex version (sc-)
2243 @item @code{sc-version} (@kbd{C-c C-p v})
2245 Echos the version of Supercite you are using. With the optional
2246 universal argument (@kbd{C-u}), this command inserts the version
2247 information into the current buffer.
2249 @findex sc-submit-bug-report
2250 @findex submit-bug-report (sc-)
2252 @item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
2254 If you encounter a bug, or wish to suggest an enhancement, use this
2255 command to set up an outgoing mail buffer, with the proper address to
2256 the Supercite maintainer automatically inserted in the @samp{To:@:}
2257 field. This command also inserts information that the Supercite
2258 maintainer can use to recreate your exact setup, making it easier to
2262 @node Hints to MUA Authors, Version 3 Changes, Electric References, Top
2263 @comment node-name, next, previous, up
2264 @chapter Hints to MUA Authors
2268 In June of 1989, some discussion was held between the various MUA
2269 authors, the Supercite author, and other Supercite users. These
2270 discussions centered around the need for a standard interface between
2271 MUAs and Supercite (or any future Supercite-like packages). This
2272 interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in
2273 a mail message to the Supercite mailing list:
2276 Martin> Each news/mail-reader should provide a form of
2277 Martin> mail-yank-original that
2279 Martin> 1: inserts the original message incl. header into the
2280 Martin> reply buffer; no indentation/prefixing is done, the header
2281 Martin> tends to be a "full blown" version rather than to be
2282 Martin> stripped down.
2284 Martin> 2: `point' is at the start of the header, `mark' at the
2285 Martin> end of the message body.
2287 Martin> 3: (run-hooks 'mail-yank-hooks)
2289 Martin> [Supercite] should be run as such a hook and merely
2290 Martin> rewrite the message. This way it isn't anymore
2291 Martin> [Supercite]'s job to gather the original from obscure
2292 Martin> sources. [@dots{}]
2295 @vindex mail-citation-hook
2296 @vindex mail-yank-hooks
2298 @findex mail-yank-original
2300 This specification was adopted, but with the recent release of FSF GNU
2301 Emacs 19, it has undergone a slight modification. Instead of the
2302 variable @code{mail-yank-hooks}, the new preferred hook variable that
2303 the MUA should provide is @code{mail-citation-hook}.
2304 @code{mail-yank-hooks} can be provided for backward compatibility, but
2305 @code{mail-citation-hook} should always take precedence. Richard
2306 Stallman (of the FSF) suggests that the MUAs should @code{defvar}
2307 @code{mail-citation-hook} to @code{nil} and perform some default citing
2308 when that is the case. Take a look at Emacs 19's @file{sendmail.el}
2309 file, specifically the @code{mail-yank-original} defun for
2312 If you are writing a new MUA package, or maintaining an existing MUA
2313 package, you should make it conform to this interface so that your users
2314 will be able to link Supercite easily and seamlessly. To do this, when
2315 setting up a reply or forward buffer, your MUA should follow these
2320 Insert the original message, including the mail headers into the reply
2321 buffer. At this point you should not modify the raw text in any way, and
2322 you should place all the original headers into the body of the reply.
2323 This means that many of the mail headers will be duplicated, one copy
2324 above the @code{mail-header-separator} line and one copy below,
2325 however there will probably be more headers below this line.@refill
2328 Set @samp{point} to the beginning of the line containing the first mail
2329 header in the body of the reply. Set @samp{mark} at the end of the
2330 message text. It is very important that the region be set around the
2331 text Supercite is to modify and that the mail headers are within this
2332 region. Supercite will not venture outside the region for any reason,
2333 and anything within the region is fair game, so don't put anything that
2334 @strong{must} remain unchanged inside the region. Further note that for
2335 Emacs 19, the region need not be set active. Supercite will work
2336 properly when the region is inactive, as should any other like-minded
2340 Run the hook @code{mail-citation-hook}. You will probably want to
2341 provide some kind of default citation functions in cases where the user
2342 does not have Supercite installed. By default, your MUA should
2343 @code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
2344 yanking function, check its value. If it finds
2345 @code{mail-citation-hook} to be @code{nil}, it should perform some
2346 default citing behavior. User who want to connect to Supercite then
2347 need only add @code{sc-cite-original} to this list of hooks using
2348 @code{add-hook}.@refill
2351 If you do all this, your users will not need to overload your routines
2352 to use Supercite, and your MUA will join the ranks of those that conform
2353 to this interface ``out of the box.''
2355 @node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
2356 @comment node-name, next, previous, up
2357 @chapter Version 3 Changes
2361 @cindex sc-unsupp.el file
2362 With version 3, Supercite has undergone an almost complete rewrite, and
2363 has hopefully benefitted in a number of ways, including vast
2364 improvements in the speed of performance, a big reduction in size of the
2365 code and in the use of Emacs resources, and a much cleaner and flexible
2366 internal architecture. The central construct of the info alist, and its
2367 role in Supercite has been expanded, and the other central concept, the
2368 general package Regi, was developed to provide a theoretically unlimited
2371 But most of this work is internal and not of very great importance to the
2372 casual user. There have been some changes at the user-visible level,
2373 but for the most part, the Supercite configuration variables from
2374 version 2 should still be relevant to version 3. Below, I briefly
2375 outline those user-visible things that have changed since version 2. For
2376 details, look to other sections of this manual.
2380 @cindex supercite.el file
2381 @cindex reporter.el file
2382 @cindex regi.el file
2383 @cindex sc.el from version 2
2384 @cindex sc-elec.el from version 2
2385 Supercite proper now comes in a single file, @file{supercite.el}, which
2386 contains everything except the unsupported noodlings, overloading (which
2387 should be more or less obsolete with the release of Emacs 19), and the
2388 general lisp packages @file{reporter.el} and @file{regi.el}. Finally,
2389 the @TeX{}info manual comes in its own file as well. In particular, the
2390 file @file{sc.el} from the version 2 distribution is obsolete, as is the
2391 file @file{sc-elec.el}.
2394 @code{sc-spacify-name-chars} is gone in version 3.
2397 @vindex sc-attrib-selection-list
2398 @vindex attrib-selection-list
2399 @code{sc-nickname-alist} is gone in version 3. The
2400 @code{sc-attrib-selection-list} is a more general construct supporting
2401 the same basic feature.
2404 The version 2 variable @code{sc-preferred-attribution} has been changed
2405 to @code{sc-preferred-attribution-list}, and has been expanded upon to
2406 allow you to specify an ordered list of preferred attributions.
2409 @code{sc-mail-fields-list} has been removed, and header nuking in
2410 general has been greatly improved, giving you wider flexibility in
2411 specifying which headers to keep and remove while presenting a
2412 simplified interface to commonly chosen defaults.
2415 Post-yank paragraph filling has been completely removed from Supercite,
2416 other packages just do it better than Supercite ever would. Supercite
2417 will still fill newly cited paragraphs.
2420 @vindex sc-cite-region-limit
2421 @vindex cite-region-limit
2422 The variable @code{sc-all-but-cite-p} has been replaced by
2423 @code{sc-cite-region-limit}.
2426 Keymap hacking in the reply buffer has been greatly simplified, with, I
2427 believe, little reduction in functionality.
2430 Hacking of the reply buffer's docstring has been completely eliminated.
2433 @node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
2434 @comment node-name, next, previous, up
2435 @chapter Thanks and History
2439 The Supercite package was derived from its predecessor Superyank 1.11
2440 which was inspired by various bits of code and ideas from Martin Neitzel
2441 and Ashwin Ram. They were the folks who came up with the idea of
2442 non-nested citations and implemented some rough code to provide this
2443 style. Superyank and Supercite version 2 evolved to the point where much
2444 of the attribution selection mechanism was automatic, and features have
2445 been continuously added through the comments and suggestions of the
2446 Supercite mailing list participants. Supercite version 3 represents a
2447 nearly complete rewrite with many of the algorithms and coding styles
2448 being vastly improved. Hopefully Supercite version 3 is faster,
2449 smaller, and much more flexible than its predecessors.
2451 In the version 2 manual I thanked some specific people for their help in
2452 developing Supercite 2. You folks know who you are and your continued
2453 support is greatly appreciated. I wish to thank everyone on the
2454 Supercite mailing list, especially the brave alpha testers, who helped
2455 considerably in testing out the concepts and implementation of Supercite
2456 version 3. Special thanks go out to the MUA and Emacs authors Kyle
2457 Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming
2458 to a quick agreement on the new @code{mail-citation-hook} interface, and
2459 for adding the magic lisp to their code to support this.
2461 All who have helped and contributed have been greatly appreciated.
2463 @node The Supercite Mailing List, Concept Index, Thanks and History, Top
2464 @comment node-name, next, previous, up
2465 @cindex supercite mailing list address
2466 @cindex mailing list address
2467 @chapter The Supercite Mailing List
2471 Supercite is currently an orphan, and the mailing list has been
2472 decommissioned (see the message from the author below). The XEmacs
2473 package version of Supercite is maintained by the XEmacs Development
2474 Team, and you may contact them by filing a bug report with @kbd{M-x
2475 report-emacs-bug}, or by mailing to the XEmacs Developers' mailing list,
2476 @samp{xemacs-beta@@xemacs.org}.
2478 The Supercite mailing list has been replaced with an autoresponder; the
2479 message it returns follows.
2482 From: The Python Replybot <replybot@@python.org>
2485 On 01-Nov-1999 I decommissioned the supercite@@python.org mailing list.
2486 I no longer have time to support or develop Supercite, so it is best
2487 that any further discussion of the package occur on the related GNU
2488 Emacs newsgroups and/or mailing lists. The Supercite archives will be
2489 retained for posterity. You can find them at
2491 http://www.python.org/pipermail/supercite
2493 I thank everyone who's helped me improve Supercite over the years, and
2494 given me very valuable feedback, bug fixes, suggestions, code
2497 Recently, I made available my last snapshot of an alpha version of
2498 Supercite 4.0. This is essentially what I use every day, and it shows
2499 the direction I was taking the development when my other duties and
2500 interests forced me to stop working on the code. It would be cool if
2501 someone else was fired up enough to adopt Supercite. You can grab the
2502 4.0 alpha snapshot by visiting
2504 http://www.python.org/~bwarsaw/betas/
2506 If you would like to adopt Supercite, please contact me first at
2507 supercite-help@@python.org. Please do not send me other questions
2508 about Supercite -- I will probably ignore them.
2513 If you would like to take over maintenance of the Supercite package, but
2514 are worried about infrastructure issues (like CVS repository, mailing
2515 lists, FTP distribution, a home page, and so on), one obvious approach
2516 would be to create a Supercite project at SourceForge
2517 (@samp{http://www.sourceforge.net/}). However, another approach would be to
2518 use the XEmacs facilities, since we already maintain a Supercite
2519 package. Contact the XEmacs Development Team for information.
2521 @node Concept Index, Command Index, The Supercite Mailing List, Top
2522 @comment node-name, next, previous, up
2523 @unnumbered Concept Index
2526 @node Command Index, Key Index, Concept Index, Top
2527 @comment node-name, next, previous, up
2528 @unnumbered Command Index
2532 Since all supercite commands are prepended with the string
2533 ``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
2534 its @var{command} name.
2540 @node Key Index, Variable Index, Command Index, Top
2541 @comment node-name, next, previous, up
2542 @unnumbered Key Index
2545 @node Variable Index, , Key Index, Top
2546 @comment node-name, next, previous, up
2547 @unnumbered Variable Index
2551 Since all supercite variables are prepended with the string
2552 ``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
2553 its @var{variable} name.