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