\inputtexinfo@comment-*-texinfo-*-@comment3.47@comment%**startofheader(ThisisforrunningTexinfoonaregion.)@setfilename../info/supercite.info@settitleSuperciteVersion3.1User'sManual@direntry*Supercite::Fancycitationsandattributionsforrepliesformailandnewsreadingsystems.@enddirentry@iftex@finalout@endiftex@c@setchapternewpageodd%Forbookstyledoublesidedmanual.@comment%**endofheader(ThisisforrunningTexinfoonaregion.)@c@smallbook@tex\overfullrule=0pt%\global\baselineskip30pt%Forprintingindoublespaces@endtex@ifinfoThisdocumentdescribestheSuperciteVersion3.1packageforcitingandattributingtherepliesforvariousGNUEmacsmailandnewsreadingsubsystems.Copyright@copyright{}1993BarryA@.WarsawPermissionisgrantedtomakeanddistributeverbatimcopiesofthismanualprovidedthecopyrightnoticeandthispermissionnoticearepreservedonallcopies.@ignorePermissionisgrantedtoprocessthisfilethroughTeXandprinttheresults,providedtheprinteddocumentcarriescopyingpermissionnoticeidenticaltothisoneexceptfortheremovalofthisparagraph(thisparagraphnotbeingrelevanttotheprintedmanual).@endignore@endifinfo@c@titlepage@sp6@center@titlefont{SuperciteUser'sManual}@sp2@center@titlefont{SuperciteVersion3.1}@sp4@centerManualRevision:3.47@centerAugust1993@sp5@centerBarryA@.Warsaw@center@t{bwarsaw@@cen.com}@center@t{@dots{}!uunet!cen.com!bwarsaw}@page@vskip0ptplus1filllCopyright@copyright{}1993BarryA@.WarsawPermissionisgrantedtomakeanddistributeverbatimcopiesofthismanualprovidedthecopyrightnoticeandthispermissionnoticearepreservedonallcopies.@endtitlepage@page@ifinfo@nodeTop,Introduction,(dir),(dir)@commentnode-name,next,previous,upThisdocumentdescribestheSuperciteVersion3.1packageforcitingandattributingtherepliesforvariousGNUEmacsmailandnewsreadingsubsystems.Themanualisdividedintothefollowingchapters.@menu*Introduction::*Citations::*GettingConnected::*ReplyingandYanking::*SelectinganAttribution::*ConfiguringtheCitationEngine::*Post-yankFormattingCommands::*InformationKeysandtheInfoAlist::*ReferenceHeaders::*HintstoMUAAuthors::*Version3Changes::*ThanksandHistory::*TheSuperciteMailingList::*ConceptIndex::*CommandIndex::*KeyIndex::*VariableIndex::@endmenu@endifinfo@nodeIntroduction,UsageOverview,Top,Top@commentnode-name,next,previous,up@chapterIntroduction@ifinfo@endifinfoSuperciteversion3.1isaGNUEmacspackagewrittenentirelyinEmacsLisp.ItinterfacestomostofthecommonlyusedEmacsmailuseragents(@dfn{MUAs})andnewsuseragents(@dfn{NUAs}),andprovidessophisticatedfacilitiesforthecitingandattributingofmessagereplies.SupercitehasaveryspecificandlimitedroleintheprocessofcomposingrepliestobothUSENETnetworknewsandelectronicmail.ThepreferredwaytospellSuperciteiswithacapital@samp{S},lowercase@samp{upercite}.ThereareafewalternatespellingsoutthereandIwon'tbeterriblyoffendedifyouusethem.Peopleoftenaskthough@dots{}@ifinfo@menu*UsageOverview::*WhatSuperciteDoesNotDo::*WhatSuperciteDoes::@endmenu@endifinfo@cindexMUA@cindexNUASuperciteisonlyusefulinconjunctionwithMUAsandNUAssuchasVM,GNUS,RMAIL,etc@.(hereafterreferredtocollectivelyasMUAs).SuperciteistypicallycalledbytheMUAafterareplybufferhasbeensetup.Thereafter,Supercite'smanycommandsandformattingstylesareavailableinthatreplybufferuntilthereplyissent.Superciteisre-initializedineachnewreplybuffer.Superciteiscurrentlyatmajorrevision3.1,andisknowntoworkinthefollowingenvironments:@table@asis@itemEmacsen:GNUEmacs18.57through18.59,allcurrentFSFEmacs19,allcurrentLucidEmacs19,andEpoch4.@refill@itemMUAs:VM4.37andbeyond(includingVMversion5),RMAIL,MH-E3.7andbeyond,PCMAIL.@refill@itemNUAs:RNEWS,GNUS3.12andbeyond,GNEWS.@refill@endtableForsystemswithversionnumbers,allknownsubsequentversionsalsoworkwithSupercite.Forthosesystemswithoutversionnumbers,Superciteprobablyworkswithanyrecentlyreleasedversion.NotethatonlysomeofthesesystemswillworkwithSupercite``outofthebox.''Allothersmustoverloadinterfacingroutinestosupplythenecessaryglue.@xref{GettingConnected},formoredetails.@refill@nodeUsageOverview,WhatSuperciteDoesNotDo,Introduction,Introduction@commentnode-name,next,previous,up@kindexr@kindexf@kindexC-cC-y@cindexyank@cindexcite,citing@cindexattribute,attributing@comment@sectionUsageOverview@ifinfo@endifinfoTypicalusageisasfollows.YouwanttoreplyorfollowuptoamessageinyourMUA.Youwillprobablyhit@kbd{r}(i.e.,``reply'')or@kbd{f}(i.e.,``forward'')tobegincomposingthereply.Inresponse,theMUAwillcreateareplybufferandinitializetheoutgoingmailheadersappropriately.Thebodyofthereplywillusuallybeemptyatthispoint.Younowdecidethatyouwouldliketoincludepartoftheoriginalmessageinyourreply.Todothis,you@dfn{yank}theoriginalmessageintothereplybuffer,typicallywithakeystrokesuchas@kbd{C-cC-y}.ThissequencewillinvokeanMUA-specificfunctionwhichfillsthebodyofthereplywiththeoriginalmessageandthen@dfn{attributes}thistexttoitsauthor.Thisiscalled@dfn{citing}anditseffectistoprefixeverylinefromtheoriginalmessagewithaspecialtexttag.MostMUAsprovidesomedefaultstyleofciting;byusingSuperciteyougainawiderflexibilityinthelookandstyleofcitations.Supercite'sonlyjobistocitetheoriginalmessage.@nodeWhatSuperciteDoesNotDo,WhatSuperciteDoes,UsageOverview,Introduction@commentnode-name,next,previous,up@sectionWhatSuperciteDoesn'tDo@ifinfo@endifinfoBecauseofthiscleardivisionoflabor,thereareusefulfeatureswhicharethesoleresponsibilityoftheMUA,eventhoughitmightseemthatSuperciteshouldprovidethem.Forexample,manypeoplewouldliketobeabletoyank(andcite)onlyaportionoftheoriginalmessage.SinceSuperciteonlymodifiesthetextitfindsinthereplybufferassetupbytheMUA,itistheMUA'sresponsibilitytodopartialyanking.@xref{ReplyBufferInitialization}.@refill@vindexmail-header-separator@commentAnotherpotentiallyusefulthingwouldbeforSupercitetosetuptheoutgoingmailheaderswithinformationitgleansfromthereplybuffer.Butbypreviouslyagreeduponconvention,anytextabovethe@code{mail-header-separator}whichseparatesmailheadersfrommessagebodiescannotbemodifiedbySupercite.Supercite,infact,doesn'tknowanythingaboutthemeaningoftheseheaders,andneverventuresoutsidethedesignatedregion.@xref{HintstoMUAAuthors},formoredetails.@refill@nodeWhatSuperciteDoes,Citations,WhatSuperciteDoesNotDo,Introduction@commentnode-name,next,previous,up@findexsc-cite-original@sectionWhatSuperciteDoes@ifinfo@endifinfoSuperciteisinvokedforthefirsttimeonareplybufferviayourMUA'sreplyorforwardcommand.ThiscommandwillactuallyperformcitationsbycallingahookvariabletowhichSupercite'stop-levelfunction@code{sc-cite-original}hasbeenadded.When@code{sc-cite-original}isexecuted,theoriginalmessagemustbesetupinaveryspecificway,butthisishandledautomaticallybytheMUA.@xref{HintstoMUAAuthors}.@refill@cindexinfoalistThefirstthingSupercitedoes,via@code{sc-cite-original},istoparsethroughtheoriginalmessage'smailheaders.Itsavesthisdatainan@dfn{informationassociationlist},or@dfn{infoalist}.TheinformationinthislistisusedinanumberofplacesthroughoutSupercite.@xref{InformationKeysandtheInfoAlist}.@refill@cindexnukingmailheaders@cindexreferenceheaderAfterthemailheaderinfoisextracted,theheadersareoptionallyremoved(@dfn{nuked})fromthereply.Supercitethenwritesa@dfn{referenceheader}intothebuffer.Thisreferenceheaderisastringcarryingdetailsaboutthecitationitisabouttoperform.@cindexmodelineNext,Supercitevisitseachlineinthereply,transformingthelineaccordingtoacustomizable``script''.Lineswhichwerenotpreviouslycitedintheoriginalmessagearegivenacitation,whilealreadycitedlinesremainuntouched,orarecoercedtoyourpreferredstyle.Finally,SuperciteinstallsakeymapintothereplybuffersothatyouhaveaccesstoSupercite'spost-yankformattingandrecitingcommandsasyousubsequentlyedityourreply.YoucantellthatSupercitehasbeeninstalledintothereplybufferbecausethatbuffer'smodelinewilldisplaytheminormodestring@samp{SC}.@cindexfilladapt@cindexgin-mode@vindexfill-prefix@findexfill-paragraph@commentWhentheoriginalmessageiscitedby@code{sc-cite-original},itwill(optionally)befilledbySupercite.However,ifyoumanuallyeditthecitedtextandwanttore-fillit,youmustuseanadd-onpackagesuchas@cite{filladapt}or@cite{gin-mode}.ThesepackagescanrecognizeSupercitedtextandwillfillthemappropriately.Emacs'built-infillingroutines,e.g@.@code{fill-paragraph},donotrecognizecitedtextandwillnotre-fillthemproperlybecauseitcannotguessthe@code{fill-prefix}beingused.@xref{Post-yankFormattingCommands},fordetails.@refillAsmentionedabove,Superciteprovidescommandstoreciteorunciteregionsoftextinthereplybuffer,andcommandstoperformotherbeautificationsonthecitedoriginaltext,maintainingconsistentandinformativecitationsthroughout.Supercitetriestobeasconfigurableaspossibletoallowforawiderangeofpersonalizedcitationstyles,butitisalsoimmediatelyusefulwiththedefaultconfiguration,onceithasbeenproperlyconnectedtoyourMUA.@xref{GettingConnected},formoredetails.@refill@nodeCitations,CitationElements,WhatSuperciteDoes,Top@commentnode-name,next,previous,up@cindexnestedcitations@cindexcitation@comment@chapterCitations@ifinfo@endifinfoA@dfn{citation}istheacknowledgementoftheoriginalauthorofamailmessageinthebodyofthereply.TherearetwobasiccitationstyleswhichSupercitesupports.Thefirst,called@dfn{nestedcitations}isananonymousformofcitation;inotherwords,anindicationismadethatthecitedlinewaswrittenbysomeone@emph{other}thatthecurrentmessageauthor(i.e.,otherthanyou,thepersoncomposingthereply),butnoreferenceismadeastotheidentityoftheoriginalauthor.Thisstyleshouldlookfamiliarsinceitsuseonthenetiswidespread.Here'sanexampleofwhatamessagebufferwouldlooklikeusingnestedcitationsaftermultiplereplies:@example>>Johnoriginallywrotethis>>andthisaswell>JanesaidthatJohndidn'tknow>whathewastalkingaboutAndthat'swhatIthinktoo.@endexample@ifinfo@menu*CitationElements::*RecognizingCitations::@endmenu@endifinfoNotethatmultipleinclusionsoftheoriginalmessagesresultinanestingofthe@samp{@code{>}}characters.Thiscansometimesbequiteconfusingwhenmanylevelsofcitationsareincludedsinceitmaybedifficultorimpossibletofigureoutwhoactuallyparticipatedinthethread,andmultiplenestingof@samp{@code{>}}characterscansometimesmakethemessageverydifficultfortheeyetoscan.@cindexnon-nestedcitationsIn@dfn{non-nestedcitations},eachcitedlinebeginswithaninformativestringattributingthatlinetotheoriginalauthor.Onlythefirstlevelofattributionwillbeshown;subsequentcitationsdon'tnestthecitationstrings.Theabovedialogmightlooklikethiswhennon-nestedcitationsareused:@exampleJohn>JohnoriginallywrotethisJohn>andthisaswellJane>JanesaidthatJohndidn'tknowJane>whathewastalkingaboutAndthat'swhatIthinktoo.@endexampleNoticeherethatmyinclusionofJane'sinclusionofJohn'soriginalmessagedidnotresultinalinecitedwith@samp{Jane>John>}.@vindexsc-nested-citation-p@vindexnested-citation-p(sc-)Supercitesupportsbothstylesofcitation,andthevariable@code{sc-nested-citation-p}controlswhichstyleitwillusewhencitingpreviouslyuncitedtext.Whenthisvariableis@code{nil}(thedefault),non-nestedcitationsareused.Whennon-@code{nil},nestedcitationsareused.@nodeCitationElements,RecognizingCitations,Citations,Citations@commentnode-name,next,previous,up@cindexcitationstring@comment@sectionCitationElements@ifinfo@endifinfo@dfn{Citationstrings}arecomposedofoneormoreelements.Non-nestedcitationsarecomposedoffourelements,threeofwhicharedirectlyuserdefinable.Theelementsareconcatenatedtogether,inthisorder:@cindexcitationleader@vindexcitation-leader(sc-)@vindexsc-citation-leader@enumerate@itemThe@dfn{citationleader}.Thecitationleaderiscontainedinthevariable@code{sc-citation-leader},andhasthedefaultvalueofastringcontainingfourspaces.@cindexattributionstring@itemThe@dfn{attributionstring}.ThiselementissuppliedautomaticallybySupercite,basedonyourpreferencesandtheoriginalmessage'smailheaders,thoughyoumaybeaskedtoconfirmSupercite'schoice.@xref{SelectinganAttribution},formoredetails.@refill@cindexcitationdelimiter@vindexsc-citation-delimiter@vindexcitation-delimiter(sc-)@itemThe@dfn{citationdelimiter}.Thisstring,containedinthevariable@code{sc-citation-delimiter}visuallyseparatesthecitationfromthetextoftheline.Thisvariablehasadefaultvalueof@code{">"}andforbestresults,thestringshouldconsistofonlyasinglecharacter.@cindexcitationseparator@vindexcitation-separator(sc-)@vindexsc-citation-separator@itemThe@dfn{citationseparator}.Thecitationseparatoriscontainedinthevariable@code{sc-citation-separator},andhasthedefaultvalueofastringcontainingasinglespace.@endenumerateForexample,supposeyouwereusingthedefaultvaluesfortheabovevariables,andSuperciteprovidedtheattributionstring@samp{Jane}.Inthiscase,thecomposed,non-nestedcitationstringusedmightbesomethinglike@code{@asis{" Jane> "}}.Thiscitationstringwillbeinsertedinfrontofeverylineintheoriginalmessagethatisnotalreadycited.@refillNestedcitations,beingsimplerthannon-nestedcitations,arecomposedofthesameelements,sanstheattributionstring.Superciteissmartenoughtonotputadditionalspacesbetweencitationdelimitersformulti-levelnestedcitations.@nodeRecognizingCitations,GettingConnected,CitationElements,Citations@commentnode-name,next,previous,up@sectionRecognizingCitations@ifinfo@endifinfoSupercitealsorecognizescitationsintheoriginalarticle,andcantransformthesealreadycitedlinesinanumberofways.ThisishowSupercitesuppressesthemultiplecitingofnon-nestedcitations.Recognitionofcitedlinesiscontrolledbyvariablesanalogoustothosethatmakeupthecitationstringasmentionedpreviously.@vindexsc-citation-leader-regexp@vindexcitation-leader-regexp(sc-)@vindexsc-citation-delimiter-regexp@vindexcitation-delimiter-regexp(sc-)@vindexsc-citation-separator-regexp@vindexcitation-separator-regexp(sc-)@vindexsc-citation-root-regexp@vindexcitation-root-regexp(sc-)@vindexsc-citation-nonnested-root-regexp@vindexcitation-nonnested-root-regexp(sc-)Thevariable@code{sc-citation-leader-regexp}describeshowcitationleaderscanlook,bydefaultitmatchesanynumberofspacesortabs.Notethatsincethelispfunction@code{looking-at}isusedtodothematching,ifyouchangethisvariableitneednotstartwithaleading@code{"^"}.Similarly,thevariables@code{sc-citation-delimiter-regexp}and@code{sc-citation-separator-regexp}respectivelydescribehowcitationdelimitersandseparatorscanlook.Theyfollowthesameruleas@code{sc-citation-leader-regexp}above.WhenSupercitecomposesacitationstring,itprovidestheattributionautomatically.Theanalogousvariablewhichhandlesrecognitionoftheattributionpartofcitationstringsis@code{sc-citation-root-regexp}.Thisvariabledescribestheattributionrootforbothnestedandnon-nestedcitations.Bydefaultitcanmatchzero-to-manyalphanumericcharacters(also``.'',``-'',and``_'').Butinsomesituations,Supercitehastodeterminewhetheritislookingatanestedornon-nestedcitation.Thusthevariable@code{sc-citation-nonnested-root-regexp}isusedtodescribeonlynon-nestedcitationroots.Itisimportanttorememberthatifyouchange@code{sc-citation-root-regexp}youshouldalwaysalsochange@code{sc-citation-nonnested-root-regexp}.@refillNemacsusers:@:Forbestresults,trysetting@code{sc-citation-root-regexp}to:@refill@example"\\([-._a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\|\\ca\\|\\cg\\|\\cr\\|\\cu\\)*"@endexampleMuleusers:@:Forbestresults,trysetting@code{sc-citation-root-regexp}to:@refill@example"\\([-._a-zA-Z0-9]\\|\\cj\\)*"@endexample@nodeInformationKeysandtheInfoAlist,ReferenceHeaders,MiscellaneousCommands,Top@commentnode-name,next,previous,up@cindexinformationkeys@cindexInfoAlist@cindexinformationextractedfrommailfields@findexsc-mail-field@findexmail-field(sc-)@comment@chapterInformationKeysandtheInfoAlist@ifinfo@endifinfo@dfn{Mailheaderinformationkeys}arenuggetsofinformationthatSuperciteextractsfromthevariousmailheadersoftheoriginalmessage,placedinthereplybufferbytheMUA.Informationiskeptinthe@dfn{InfoAlist}askey-valuepairs,andcanberetrievedforuseinvariousplaceswithinSupercite,suchasinheaderrewritefunctionsandattributionselection.Otherbitsofdata,composedandcreatedbySupercite,arealsokeptaskey-valuepairsinthisalist.Inthecaseofmailfields,thekeyisthenameofthefield,omittingthetrailingcolon.Infokeysarealwayscaseinsensitive(asaremailheaders),andthevalueforacorrespondingkeycanberetrievedfromthealistwiththe@code{sc-mail-field}function.Thus,ifthefollowingfieldswerepresentintheoriginalarticle:@refill@exampleDate:@:08April1991,17:32:09ESTSubject:@:Bettergetoutyourasbestossuit@endexample@vindexsc-mumble@vindexmumble(sc-)@noindentthen,thefollowinglispconstructsreturn:@example(sc-mail-field"date")==>"08 April 1991, 17:32:09 EST"(sc-mail-field"subject")==>"Better get out your asbestos suit"@endexampleSincetheargumentto@code{sc-mail-field}canbeanystring,itispossiblethatthemailfieldwillnotbepresentontheinfoalist(possiblybecausethemailheaderwasnotpresentintheoriginalmessage).Inthiscase,@code{sc-mail-field}willreturnthevalueofthevariable@code{sc-mumble}.Supercitealwaysplacesallmailfieldsfoundintheyankedoriginalarticleintotheinfoalist.Ifpossible,Supercitewillalsoplacesthefollowingkeysintotheinfoalist:@table@code@cindexsc-attributioninfofield@cindexattributioninfofield(sc-)@item"sc-attribution"theselectedattributionstring.@cindexsc-citationinfofield@cindexcitationinfofield(sc-)@item"sc-citation"thenon-nestedcitationstring.@cindexsc-from-addressinfofield@cindexfrom-addressinfofield(sc-)@item"sc-from-address"emailaddressextractedfromthe@samp{From:@:}field.@cindexsc-reply-addressinfofield@cindexreply-addressinfofield(sc-)@item"sc-reply-address"emailaddressextractedfromthe@samp{Reply-To:@:}field.@cindexsc-sender-addressinfofield@cindexsender-addressinfofield(sc-)@item"sc-sender-address"emailaddressextractedfromthe@samp{Sender:@:}field.@cindexsc-emailnameinfofield@cindexemailnameinfofield(sc-)@item"sc-emailname"emailterminusextractedfromthe@samp{From:@:}field.@cindexsc-initialsinfofield@cindexinitialsinfofield(sc-)@item"sc-initials"theauthor'sinitials.@cindexsc-authorinfofield@cindexauthorinfofield(sc-)@item"sc-author"theauthor'sfullname.@cindexsc-firstnameinfofield@cindexfirstnameinfofield(sc-)@item"sc-firstname"theauthor'sfirstname.@cindexsc-lastnameinfofield@cindexlastnameinfofield(sc-)@item"sc-lastname"theauthor'slastname.@cindexsc-middlename-1infofield@cindexmiddlename-1infofield(sc-)@item"sc-middlename-1"theauthor'sfirstmiddlename.@endtableIftheauthor'snamehasmorethanonemiddlename,theywillappearasinfokeyswiththeappropriateindex(e.g.,@code{"sc-middlename-2"},@dots{}).@xref{SelectinganAttribution}.@refill@nodeReferenceHeaders,TheBuilt-inHeaderRewriteFunctions,InformationKeysandtheInfoAlist,Top@commentnode-name,next,previous,up@cindexreferenceheaders@chapterReferenceHeaders@ifinfo@endifinfoSupercitewillinsertaninformative@dfn{referenceheader}atthebeginningofthecitedbodyoftext,whichdisplaymoredetailabouttheoriginalarticleandprovidesthemappingbetweentheattributionandtheoriginalauthorinnon-nestedcitations.Whereasthecitationstringusuallyonlycontainsaportionoftheoriginalauthor'sname,thereferenceheadercancontainsuchinformationastheauthor'sfullname,emailaddress,theoriginalarticle'ssubject,etc.Infactanyinformationcontainedintheinfoalistcanbeinsertedintoareferenceheader.@ifinfo@menu*TheBuilt-inHeaderRewriteFunctions::*ElectricReferences::@endmenu@endifinfo@cindexheaderrewritefunctions@vindexsc-rewrite-header-list@vindexrewrite-header-list(sc-)Thereareanumberofbuilt-in@dfn{headerrewritefunctions}suppliedbySupercite,butyoucanwriteyourowncustomheaderrewritefunctions(perhapsusingthebuilt-inonesasexamples).Thevariable@code{sc-rewrite-header-list}containsthelistofsuchheaderrewritefunctions.Thislistisconsultedbothwheninsertingtheinitialreferenceheader,andwhendisplaying@dfn{electricreferences}.@xref{ElectricReferences}.@vindexsc-preferred-header-style@vindexpreferred-header-style(sc-)WhenSuperciteisinitiallyrunonareplybuffer(via@code{sc-cite-original}),itwillautomaticallycalloneofthesefunctions.Theoneitusesisdefinedinthevariable@code{sc-preferred-header-style}.Thevalueofthisvariableisanintegerwhichisanindexintothe@code{sc-rewrite-header-list},beginningatzero.@nodeTheBuilt-inHeaderRewriteFunctions,ElectricReferences,ReferenceHeaders,ReferenceHeaders@commentnode-name,next,previous,up@cindexheaderrewritefunctions,built-in@comment@sectionTheBuilt-inHeaderRewriteFunctions@ifinfo@endifinfoBelowareexamplesofthevariousbuilt-inheaderrewritefunctions.Pleasenotethefollowing:@:first,thetextwhichappearsintheexamplesbelowas@var{infokey}indicatesthatthecorrespondingvalueoftheinfokeyfromtheinfoalistwillbeinsertedthere.(@xref{InformationKeysandtheInfoAlist}.).Forexample,in@code{sc-header-on-said}below,@var{date}and@var{from}correspondtothevaluesofthe@samp{Date:@:}and@samp{From:@:}mailheadersrespectively.@refill@vindexsc-reference-tag-string@vindexreference-tag-string(sc-)Also,thestring@code{">>>>>"}belowisreallythevalueofthevariable@code{sc-reference-tag-string}.Thisvariableisusedinallbuilt-inheaderrewritefunctions,andyoucancustomizeitsvaluetochangethetagstringglobally.Finally,thereferencesheadersactuallywrittenmayomitcertainpartsoftheheaderiftheinfokeyassociatedwith@var{infokey}isnotpresentintheinfoalist.Infact,forallbuilt-inheaders,ifthe@samp{From:@:}fieldisnotpresentinthemailheaders,theentirereferenceheaderwillbeomitted(butthisusuallysignalsaseriousproblemeitherinyourMUAorinSupercite'sinstallation).@table@code@findexsc-no-header@findexno-header(sc-)@itemsc-no-headerThisfunctionproducesnoheader.Itshouldbeusedinsteadof@code{nil}toproduceablankheader.Thisheadercanpossiblycontainablanklineafterthe@code{mail-header-separator}line.@itemsc-no-blank-line-or-header@findexsc-no-blank-line-or-header@findexno-blank-line-or-header(sc-)Thisfunctionissimilarto@code{sc-no-header}exceptthatanyblanklineafterthe@code{mail-header-separator}linewillberemoved.@itemsc-header-on-said@findexsc-header-on-said@findexheader-on-said(sc-)@code{>>>>>On@var{date},@var{from}said:}@itemsc-header-inarticle-writes@findexsc-header-inarticle-writes@findexheader-inarticle-writes(sc-)@code{>>>>>Inarticle@var{message-id},@var{from}writes:}@itemsc-header-regarding-adds@findexsc-header-regarding-adds@findexheader-regarding-adds(sc-)@code{>>>>>Regarding@var{subject};@var{from}adds:}@itemsc-header-attributed-writes@findexsc-header-attributed-writes@findexheader-attributed-writes(sc-)@code{>>>>>"@var{sc-attribution}"==@var{sc-author}<@var{sc-reply-address}>writes:}@itemsc-header-author-writes@findexsc-header-author-writes@findexheader-author-writes(sc-)@code{>>>>>@var{sc-author}writes:}@itemsc-header-verbose@findexsc-header-verbose@findexheader-verbose(sc-)@code{>>>>>On@var{date},}@*@code{>>>>>@var{sc-author}}@*@code{>>>>>fromtheorganizationof@var{organization}}@*@code{>>>>>whocanbereachedat:@:@var{sc-reply-address}}@*@code{>>>>>(whosecommentsarecitedbelowwith:@:"@var{sc-cite}")}@*@code{>>>>>hadthistosayinarticle@var{message-id}}@*@code{>>>>>innewsgroups@var{newsgroups}}@*@code{>>>>>concerningthesubjectof@var{subject}}@*@code{>>>>>see@var{references}formoredetails}@endtable@nodeElectricReferences,HintstoMUAAuthors,TheBuilt-inHeaderRewriteFunctions,ReferenceHeaders@commentnode-name,next,previous,up@cindexelectricreferences@sectionElectricReferences@ifinfo@endifinfoBydefault,whenSupercitecitestheoriginalmessageforthefirsttime,itjustgoesaheadandinsertsthereferenceheaderindexedby@code{sc-preferred-header-style}.However,youmaywanttoselectdifferentreferenceheadersbasedonthetypeofreplyorforwardingyouaredoing.Youmayalsowanttopreviewthereferenceheaderbeforedecidingwhethertoinsertitintothereplybufferornot.Superciteprovidesanoptional@dfn{electricreference}modewhichyoucandropintotogiveyouthisfunctionality.@vindexsc-electric-references-p@vindexelectric-references-p(sc-)Ifthevariable@code{sc-electric-references-p}isnon-@code{nil},Supercitewillbringupanelectricreferencemodebufferandplaceyouintoarecursiveedit.Theelectricreferencebufferisread-only,soyoucannotdirectlymodifythereferencetextuntilyouexitelectricreferencesandinsertthetextintothereplybuffer.Butyoucancyclethroughallthereferenceheaderrewritefunctionsinyour@code{sc-rewrite-header-list}.Youcanalsosetanewpreferredheaderstyle,jumptoanyheader,orjumptothepreferredheader.Theheaderwillbeshownintheelectricreferencebufferandtheheaderindexandfunctionnamewillappearintheechoarea.Thefollowingcommandsareavailablewhileinelectricreferencemode(shownherewiththeirdefaultkeybindings):@table@asis@item@code{sc-eref-next}(@kbd{n})@findexsc-eref-next@findexeref-next(sc-)@kindexn@vindexsc-electric-circular-p@vindexelectric-circular-p(sc-)Displaysthenextreferenceheaderintheelectricreferencebuffer.Ifthevariable@code{sc-electric-circular-p}isnon-@code{nil},invoking@code{sc-eref-next}whileviewingthelastreferenceheaderinthelistwillwraparoundtothefirstheader.@refill@item@code{sc-eref-prev}(@kbd{p})@findexsc-eref-prev@findexeref-prev(sc-)@kindexpDisplaysthepreviousreferenceheaderintheelectricreferencebuffer.Ifthevariable@code{sc-electric-circular-p}isnon-@code{nil},invoking@code{sc-eref-prev}willwraparoundtothelastheader.@refill@item@code{sc-eref-goto}(@kbd{g})@findexsc-eref-goto@findexeref-goto(sc-)@kindexgGoestoaspecifiedreferenceheader.Theindex(intothe@code{sc-rewrite-header-list})canbespecifiedasanumericargumenttothecommand.Otherwise,Supercitewillqueryyoufortheindexintheminibuffer.@refill@item@code{sc-eref-jump}(@kbd{j})@findexsc-eref-jump@findexeref-jump(sc-)@kindexjDisplaythepreferredreferenceheader,i.e.,theoneindexedbythecurrentvalueof@code{sc-preferred-header-style}.@item@code{sc-eref-setn}(@kbd{s})@findexsc-eref-setn@findexeref-setn(sc-)@kindexsSetthepreferredreferenceheader(i.e.,@code{sc-preferred-header-style})tothecurrentlydisplayedheader.@refill@item@code{sc-eref-exit}(@key{LFD},@key{RET},and@key{ESCC-c})@kindexRET@kindexLFD@kindexq@findexsc-eref-exit@findexeref-exit(sc-)Exitfromelectricreferencemodeandinsertthecurrentheaderintothereplybuffer.@refill@item@code{sc-eref-abort}(@kbd{q},@kbd{x})@findexsc-eref-abort@findexeref-abort(sc-)@kindexxExitfromelectricreferencemodewithoutinsertingthecurrentheader.@endtable@vindexsc-electric-mode-hook@vindexelectric-mode-hook(sc-)@noindentSupercitewillexecutethehook@code{sc-electric-mode-hook}beforeenteringelectricreferencemode.@nodeGettingConnected,Emacs19MUAs,RecognizingCitations,Top@commentnode-name,next,previous,up@cindexcitationinterfacespecification@chapterGettingConnected@ifinfo@endifinfoHitting@kbd{C-cC-y}inyourMUA'sreplybufferyanksandcitestheoriginalmessageintothereplybuffer.Inreality,thecitationoftheoriginalmessageisperformedviaacallthroughaconfigurablehookvariable.Thenameofthisvariablehasbeenagreedtoinadvanceaspartofthe@dfn{citationinterfacespecification}.Bydefaultthishookvariablehasa@code{nil}value,whichtheMUArecognizestomean,``useyourdefaultcitationfunction''.WhenyouaddSupercite'scitationfunctiontothehook,therebygivingthevariableanon-@code{nil}value,ittellstheMUAtorunthehookvia@code{run-hooks}insteadofusingthedefaultcitation.@refill@ifinfo@menu*Emacs19MUAs::*Emacs18MUAs::*MH-EwithanyEmacsen::*VMwithanyEmacsen::*GNEWSwithanyEmacsen::*OverloadingforNon-conformingMUAs::@endmenu@endifinfoEarlyinSupercite'sdevelopment,theSuperciteauthor,afewMUAauthors,andsomeearlySuperciteusersgottogetherandagreeduponastandardinterfacebetweenMUAsandcitationpackages(ofwhichSuperciteiscurrentlytheonlyknownadd-on@t{:-)}.WiththerecentreleaseoftheFreeSoftwareFoundation'sGNUEmacs19,theinterfacehasundergonesomemodificationanditispossiblethatnotallMUAssupportthenewinterfaceyet.Somesupportonlytheoldinterfaceandsomedonotsupporttheinterfaceatall.Still,itispossibleforallknownMUAstouseSupercite,andthefollowingsectionswilloutlinetheproceduresyouneedtofollow.TolearnexactlyhowtoconnectSupercitetothesoftwaresystemsyouareusing,readtheappropriatefollowingsections.Fordetailsontheinterfacespecifications,orifyouarewritingormaintaininganMUA,@pxref{HintstoMUAAuthors}.@cindexautoload@cindex.emacsfile@findexsc-cite-original@findexcite-original(sc-)@findexsc-submit-bug-report@findexsubmit-bug-report(sc-)Thefirstthingthateveryoneshoulddo,regardlessoftheMUAyouareusingistosetupEmacssoitwillloadSuperciteattheappropriatetime.YoucaneitherdumpSuperciteintoyourEmacsbinary(askyourlocalEmacsguruhowtodothisifyoudon'tknow),oryoucansetupan@dfn{autoload}forSupercite.Todothelatter,putthefollowinginyour@file{.emacs}file:@example(autoload'sc-cite-original"supercite""Supercite 3.1"t)(autoload'sc-submit-bug-report"supercite""Supercite 3.1"t)@endexample@cindexpoint@cindexmarkThefunction@code{sc-cite-original}isthetop-levelSupercitefunctiondesignedtoberunfromthecitationhook.Itexpects@samp{point}and@samp{mark}tobesetaroundtheregiontocite,anditexpectstheoriginalarticle'smailheaderstobepresentwithinthisregion.NotethatSupercite@emph{never}touchesanytextoutsidethisregion.NotefurtherthatforEmacs19,theregionneednotbeactivefor@code{sc-cite-original}todoitsjob.@xref{HintstoMUAAuthors}.@refillTheotherstepinthegettingconnectedprocessistomakesureyourMUAcalls@code{sc-cite-original}attherighttime.Asmentionedabove,someMUAshandlethisdifferently.ReadthesectionsthatfollowpertainingtotheMUAsyouareusing.@vindexsc-load-hook@vindexload-hook(sc-)@vindexsc-pre-hook@vindexpre-hook(sc-)Onefinalnote.AfterSuperciteisloadedintoyourEmacssession,itrunsthehook@code{sc-load-hook}.Youcanputanycustomizationsintothishooksinceitisonlyrunonce.Thiswillnotwork,however,ifyourEmacsmaintainerhasputSuperciteintoyourdumpedEmacs'image.Inthatcase,youcanusethe@code{sc-pre-hook}variable,butthiswillgetexecutedeverytime@code{sc-cite-original}iscalled.@xref{ReplyBufferInitialization}.@refill@nodeEmacs19MUAs,Emacs18MUAs,GettingConnected,GettingConnected@commentnode-name,next,previous,up@vindexmail-citation-hook@cindex.emacsfile@sectionGNUS,RMAIL,orRNEWSwithanyEmacs19@ifinfo@endifinfoTheseMUAs,distributedwithbothFSFandLucidGNUEmacs19,useEmacs'built-inyankingfacility,whichprovidesthecitinghookvariable@code{mail-citation-hook}.Bydefault,thishook'svalueis@code{nil},butbyaddingthefollowingtoyour@file{.emacs}file,youcantelltheseMUAstouseSupercitetoperformthecitingoftheoriginalmessage:@example(add-hook'mail-citation-hook'sc-cite-original)@endexampleGNUSusersmayalsowanttoaddthefollowingbitoflispaswell.ThispreventsGNUSfrominsertingitsdefaultattributionheader.Otherwise,bothGNUSandSupercitewillinsertanattributionheader:@example(setqnews-reply-header-hooknil)@endexampleNotethatthe@code{mail-citation-hook}interfacedescribedabovewasnotsupportedinFSFEmacs19untilversion19.16andinLucidEmacs19untilversion19.8.IfyouarerunninganearlierversionofoneoftheseEmacsen,youwillneedtoeitherupgradetothelatestversion,orusetheunsupported@dfn{overloading}featureprovidedwithSupercite.@xref{OverloadingforNon-conformingMUAs}.@refill@nodeEmacs18MUAs,MH-EwithanyEmacsen,Emacs19MUAs,GettingConnected@commentnode-name,next,previous,up@vindexmail-citation-hook@cindex.emacsfile@cindexoverloading@cindexsendmail.elfile@sectionGNUS,RMAIL,PCMAIL,RNEWSwithEmacs18orEpoch4@ifinfo@endifinfoTheseMUAsuseEmacs'built-inyankingandcitingroutines,containedinthe@file{sendmail.el}file.@file{sendmail.el}forEmacs18,anditsderivativeEpoch4,donotknowanythingaboutthecitationinterfacerequiredbySupercite.ToconnectSupercitetoanyoftheseMUAsunderEmacs18orEpoch4,youshouldfirst@pxref{OverloadingforNon-conformingMUAs}.ThenfollowthedirectionsforusingtheseMUAsunderEmacs19.@xref{Emacs19MUAs}.@refill@cindexadd-hooksubstitute@cindexsetqasasubstituteforadd-hook@findexsetq@findexadd-hook@cindexsc-unsupp.elfileNotethatthoseinstructionswilltellyoutousethefunction@code{add-hook}.ThisfunctionisnewwithEmacs19andyouwillnothaveitbydefaultifyouarerunningEmacs18orEpoch4.Youcaneithersubstitutetheappropriatecallto@code{setq},oryoucanusethe@code{add-hook}functionthatisprovidedinthe@file{sc-unsupp.el}fileofunsupportedSupercitehacksandideas.OryoucanupgradetosomeEmacs19variant!@t{:-)}@refillTouse@code{setq}insteadof@code{add-hook},youwould,forexample,changethis:@example(add-hook'mail-citation-hook'sc-cite-original)@endexampleto:@example(setqmail-citation-hook'sc-cite-original)@endexampleNotethelackofasinglequoteonthefirstargumentto@code{setq}.@nodeMH-EwithanyEmacsen,VMwithanyEmacsen,Emacs18MUAs,GettingConnected@commentnode-name,next,previous,up@cindex.emacsfile@vindexmh-yank-hooks@findexadd-hook@cindexmail-citation-hook@sectionMH-EwithanyEmacsen@ifinfo@endifinfoMH-E4.xconformstothe@code{mail-citation-hook}interfacesupportedbyotherMUAs.Atthetimeofthiswriting,MH-E4.0hasnotbeenreleased,butifyouhaveit,putthisinyour@file{.emacs}filetoconnectSuperciteandMH-E4.x:@example(add-hook'mail-citation-hook'sc-cite-original)@endexampleNotethatifyouareusingEmacs18orEpoch4,youwillnothavethe@code{add-hook}function.@xref{Emacs18MUAs},fordetailsonhowtoproceedwithout@code{add-hook}.MH-Eversion3.xusesaslightlydifferentinterfacethanotherMUAs.MH-Eprovidesahookvariable@code{mh-yank-hooks},butitdoesn'tactlikeahook,anddoingan@code{add-hook}willnotwork.ToconnectSupercitetoMH-E3.x,youshouldinsteadaddthefollowingtoyour@code{.emacs}file:@example(add-hook'mh-yank-hooks'sc-cite-original)@endexample@vindexmh-yank-from-start-of-msgYoualsoneedtomakesurethatMH-Eincludesalltheoriginalmailheadersintheyankedmessage.Thevariablethatcontrolsthisis@code{mh-yank-from-start-of-msg}.Bydefault,thisvariablehasthevalue@code{t},whichtellsMH-Etoincludeallthemailheaderswhenyankingtheoriginalmessage.BeforeyouswitchedtousingSupercite,youmayhavesetthisvariabletoothervaluessoasnottoincludethemailheadersintheyankedmessage.SinceSuperciterequirestheseheaders(andcleansthemoutforyou),youneedtomakesurethevalueis@code{t}.Thislisp,inyour@file{.emacs}filewilldothetrick:@example(setqmh-yank-from-start-of-msgt)@endexampleNotethatversionsofMH-Ebefore3.7didnotprovidethe@code{mh-yank-hooks}variable.YouronlyoptionistoupgradetoMH-Eversion3.7orlater.@nodeVMwithanyEmacsen,GNEWSwithanyEmacsen,MH-EwithanyEmacsen,GettingConnected@commentnode-name,next,previous,up@cindex.emacsfile@vindexmail-citation-hook@vindexmail-yank-hooks@sectionVMwithanyEmacsen@ifinfo@endifinfoSincerelease4.40,VMhassupportedthecitationinterfacerequiredbySupercite.ButsincetheinterfacehaschangedrecentlythedetailsofgettingconnecteddifferwiththeversionofVMyouareusing.IfyouarerunninganyreleaseofVMafter4.40,youcanaddthefollowingtoyour@file{.emacs}toconnectSupercitewithVM:@example(add-hook'mail-yank-hooks'sc-cite-original)@endexampleNotethatifyouareusingEmacs18orEpoch4,youwillnothavethe@code{add-hook}function.@xref{Emacs18MUAs},fordetailsonhowtoproceedwithout@code{add-hook}.Sinceversion5.34,VMhassupportedthenewer@code{mail-citation-hook}interface,but@code{mail-yank-hooks}isstillbeingsupportedforbackwardcompatibility.IfyouarerunninganewerversionofVMandyouwanttomaintainconsistencywithotherMUAs,usethisbitofcodeinstead:@example(add-hook'mail-citation-hook'sc-cite-original)@endexample@nodeGNEWSwithanyEmacsen,OverloadingforNon-conformingMUAs,VMwithanyEmacsen,GettingConnected@commentnode-name,next,previous,up@cindex.emacsfile@vindexnews-reply-mode-hook@findexsc-perform-overloads@findexperform-overloads(sc-)@vindexgnews-ready-hook@sectionGNEWSwithanyEmacsen@ifinfo@endifinfoAsfarasIknow,noversionofGNEWSsupportsthecitationinterfacerequiredbySupercite.ToconnectSupercitewithGNEWS,pleasefirst@pxref{OverloadingforNon-conformingMUAs}.Afteryouhavefollowedthedirectionsinthatsection.Youshouldaddthefollowinglispcodetoyour@file{.emacs}file:@example(add-hook'mail-citation-hook'sc-cite-original)@endexampleNotethatifyouareusingEmacs18orEpoch4,youwillnothavethe@code{add-hook}function.@xref{Emacs18MUAs},fordetailsonhowtoproceedwithout@code{add-hook}.@nodeOverloadingforNon-conformingMUAs,ReplyingandYanking,GNEWSwithanyEmacsen,GettingConnected@commentnode-name,next,previous,up@cindexoverloading@cindexsc-oloads.el@vindexmail-citation-hook@findexsc-perform-overloads@cindex.emacsfile@sectionOverloadingforNon-conformingMUAs@ifinfo@endifinfoAsmentionedelsewhere,someMUAsdonotprovidethenecessaryhookstoconnectwithSupercite.Superciteversion3.1providesanunsupportedmechanism,called@dfn{overloading}whichredefinescertainkeyfunctionsintheMUA,sothatitwillcallthe@code{mail-citation-hook}variableinsteadoftheMUA'sdefaulthard-codedcitingroutines.SincemostnewerversionsoftheknownMUAssupportthe@code{mail-citation-hook}variable,itisrecommendedthatyouupgradeifatallpossible.Butifyoucan'tupgrade,atleastyou'renotoutofluck!Onceyousetupoverloadingproperly,youshouldfollowthedirectionsforconnectingSupercitetotheEmacs19MUAs.@xref{Emacs19MUAs}.@refill@cindexHyperbole@vindexhyperb:versionUsersofBobWeiner'sHyperbolepackagetakenote.Hyperboleprovidesthenecessaryoverloads(andawholelotmore!)andyoucanpotentiallyclobberitifyouweretoloadSupercite'soverloadingafterHyperbole's.Forthisreason,Supercitewill@emph{not}performanyoverloadingifitfindsthevariable@code{hyperb:version}is@code{boundp}(i.e.itexistsbecauseHyperbolehasbeenloadedintoyourEmacssession).Ifthisisthecase,Supercitewilldisplayawarningmessageintheminibuffer.YoushouldconsulttheHyperbolemanualforfurtherdetails.Overloadinginvolvesthere-definitionofthecitingfunctionwiththenew,@code{mail-citation-hook}savvyversion.Thefunctionin@file{sc-oloads.el}thatdoesthisis@code{sc-perform-overloads}.ThisfunctionissmartenoughtoonlyoverloadtheMUAfunctionswhenitisabsolutelynecessary,basedontheversionnumbersitcanfigureout.Also,@code{sc-perform-overloads}willonlyinstallthenewfunctionsonce.ItisalsosmartenoughtodonothingiftheMUAisnotyetloaded.@refillThetrickypartisfindingtherighttimeandplacetoperformtheoverloading.ItmustbedoneaftertheMUAhasbeenloadedintoyourEmacssession,butbeforethefirsttimeyoutrytoyankinamessage.Fortunately,thishasbeenfiguredoutforyou.Ifyoumustoverload,youshouldputthefollowinglispcodeinyour@file{.emacs}file,tomakesurethe@file{sc-oloads.el}filegetsloadedattherighttime:@example(autoload'sc-perform-overloads"sc-oloads""Supercite 3.1"t)@endexampleThenyoumustmakesurethatthefunction@code{sc-perform-overloads}getsrunattherighttime.ForGNUS,putthisinyour@file{.emacs}file:@example(setqnews-reply-mode-hook'sc-perform-overloads)(setqmail-setup-hook'sc-perform-overloads)@endexampleIfyouareusingRNEWS,putthisinyour@file{.emacs}file:@vindexnews-reply-mode-hook@example(setqnews-reply-mode-hook'sc-perform-overloads)@endexampleIfyouareusingRMAILorPCMAIL,putthisinyour@file{.emacs}file:@example(setqmail-setup-hook'sc-perform-overloads)@endexampleIfyouareusingGNEWS,putthisinyour@file{.emacs}file:@example(setqnews-reply-mode-hook'sc-perform-overloads)(setqgnews-ready-hook'sc-perform-overloads)@endexampleNowgobackandfollowthedirectionsforgettingtheEmacs19MUAsconnectedtoSupercite.Besureto@pxref{Emacs18MUAs}onsubstitutesforEmacs19's@code{add-hook}function.@refill@nodeReplyingandYanking,ReplyBufferInitialization,OverloadingforNon-conformingMUAs,Top@commentnode-name,next,previous,up@chapterReplyingandYanking@ifinfoThischapterexplainswhathappenswhenyoureplyandyankanoriginalmessagefromanMUA.@menu*ReplyBufferInitialization::*FillingCitedText::@endmenu@endifinfo@nodeReplyBufferInitialization,FillingCitedText,ReplyingandYanking,ReplyingandYanking@commentnode-name,next,previous,up@findexsc-cite-original@findexcite-original(sc-)@comment@sectionReplyBufferInitialization@ifinfo@endifinfoExecuting@code{sc-cite-original}performsthefollowingstepsasitinitializesthereplybuffer:@enumerate@item@vindexsc-pre-hook@vindexpre-hook(sc-)@emph{Runs@code{sc-pre-hook}.}Thishookvariableisrunbefore@code{sc-cite-original}doesanyotherwork.YoucouldconceivablyusethishooktosetcertainSupercitevariablesbasedonthereplybuffer'smodeorname(i.e.,todosomethingdifferentbasedonwhetheryouarereplyingorfollowinguptoanarticle).@refill@item@emph{InsertsSupercite'skeymap.}@vindexsc-mode-map-prefix@vindexmode-map-prefix(sc-)@kindexC-cC-p@cindexkeymapprefixSuperciteprovidesanumberofcommandsforperformingpost-yankmodificationstothereplybuffer.ThesecommandsareinstalledonSupercite'stop-levelkeymap.SinceSupercitehastointerfacewithawidevarietyofMUAs,itdoesnotinstallallofitscommandsdirectlyintothereplybuffer'skeymap.Instead,itputsitscommandsonakeymapprefix,theninstallsthisprefixontothebuffer'skeymap.WhatthismeansisthatyoutypicallyhavetotypemorecharacterstoinvokeaSupercitecommand,butSupercite'skeybindingscanbemademuchmoreconsistentacrossMUAs.YoucancontrolwhatkeySuperciteusesasitskeymapprefixbychangingthevariable@code{sc-mode-map-prefix}.Bydefault,thisvariableissetto@code{C-cC-p};afingertwisterperhaps,butunfortunatelythebestdefaultduetothescarcityofavailablekeybindingsinmanyMUAs.@item@emph{TurnsonSuperciteminormode.}@cindexmodelineThemodelineofthereplybuffershouldindicatethatSuperciteisactiveinthatbufferbydisplayingthestring@samp{SC}.@item@emph{Setsthe``UndoBoundary''.}@cindexundoboundarySupercitesetsanundoboundarybeforeitbeginstomodifytheoriginalyankedtext.ThisallowsyoutoeasilyundoSupercite'schangestoaffectalternativecitingstyles.@item@emph{Processesthemailheaders.}@vindexsc-confirm-always-p@vindexconfirm-always-p(sc-)@vindexsc-mail-warn-if-non-rfc822-p@vindexmail-warn-if-non-rfc822-p(sc-)Allpreviouslyretrievedinfokey-valuepairsaredeletedfromtheinfoalist,thenthemailheadersinthebodyoftheyankedmessagearescanned.Infokey-valuepairsarecreatedforeachheaderfound.Also,suchusefulinformationastheauthor'snameandemailaddressareextracted.Ifthevariable@code{sc-mail-warn-if-non-rfc822-p}isnon-@code{nil},thenSupercitewillwarnyouifitfindsamailheaderthatdoesnotconformtoRFC822.ThisisrareandindicatesaproblemeitherwithyourMUAortheoriginalauthor'sMUA,orsomeMTA(mailtransportagent)alongtheway.@vindexsc-nuke-mail-headers@vindexsc-nuke-mail-header-list@vindexnuke-mail-headers(sc-)@vindexnuke-mail-header-list(sc-)Oncetheinfokeyshavebeenextractedfromthemailheaders,theheadersarenukedfromthereplybuffer.Youcancontrolexactlywhichheadersareremovedorkept,butbydefault,allheadersareremoved.Therearetwovariableswhichcontrolmailheadernuking.Thevariable@code{sc-nuke-mail-headers}controlstheoverallbehavioroftheheadernukingroutines.Bysettingthisvariableto@code{'all},youautomaticallynukeallmailheaders.Likewise,settingthisvariableto@code{'none}inhibitsnukingofanymailheaders.Inbetweentheseextremes,youcantellSupercitetonukeonlyaspecifiedlistofmailheadersbysettingthisvariableto@code{'specified},ortokeeponlyaspecifiedlistofheadersbysettingitto@code{'keep}.If@code{sc-nuke-mail-headers}issetto@code{'specified}or@code{'keep},thenthevariable@code{sc-nuke-mail-header-list}isconsultedforthelistofheaderstonukeorkeep.Thisvariablecontainsalistofregularexpressions.Ifthemailheaderlinematchesaregularexpressioninthislist,theheaderwillbenukedorkept.Thelineismatchedagainsttheregexpusing@code{looking-at}rootedatthebeginningoftheline.@vindexsc-blank-lines-after-headers@vindexblank-lines-after-headers(sc-)Ifthevariable@code{sc-blank-lines-after-headers}isnon-@code{nil},itcontainsthenumberofblanklinesremaininginthebufferaftermailheadersarenuked.Bydefault,onlyoneblanklineisleftinthebuffer.@item@emph{Selectstheattributionandcitationstrings.}Oncethemailheadershavebeenprocessed,Superciteselectsaattributionstringandacitationstringwhichitwillusetocitetheoriginalmessage.@xref{SelectinganAttribution},fordetails.@item@emph{Citesthemessagebody.}@vindexsc-cite-region-limit@vindexcite-region-limit(sc-)bAftertheselectionoftheattributionandcitationstrings,Supercitecitestheoriginalmessagebyinsertingthecitationstringprefixinfrontofeveryuncitedline.YoumaynotwantSupercitetoautomaticallyciteverylongmessageshowever.Forexample,someemailcouldcontainasmallerheadersectionfollowedbyahugeuuencodedmessage.Itwouldn'tmakesensetocitetheuuencodedmessagepartwhenrespondingtotheoriginalauthor'sshortpreface.Forthisreason,Superciteprovidesavariablewhichlimitstheautomaticcitationoflongmessagestoacertainmaximumnumberoflines.Thevariableiscalled@code{sc-cite-region-limit}.Ifthisvariablecontainsaninteger,messageswithmorelinesthatthiswillnotbecitedatall,andawarningmessagewillbedisplayed.Supercitehasperformedeverythingnecessary,though,foryoutomanuallyciteonlythesmallportionoftheoriginalmessagethatyouwanttouse.If@code{sc-cite-region-limit}containsanon-@code{nil}value,theoriginalmessagewillalwaysbecited,regardlessofitssize.Ifthevariablecontainsthevalue@code{nil},theregionwillneverbecitedautomatically.Usethisifyoualwayswanttobeabletoeditandcitethemessagemanually.@vindexsc-cite-blank-lines-p@vindexcite-blank-lines-p(sc-)Thevariable@code{sc-cite-blank-lines-p}controlswhetherblanklinesintheoriginalmessageshouldbecitedornot.Ifthisvariableisnon-@code{nil},blanklineswillbecitedjustlikenon-blanklines.Otherwise,blanklineswillbetreatedasparagraphseparators.Citingoftheoriginalmessageishighlyconfigurable.Supercite'sdefaultsetupdoesaprettygoodjobofcitingmanycommonformsofpreviouslycitedmessages.Butthereareasmanycitationstylesoutthereaspeopleonthenet,orjustabout!ItwouldbeimpossibleforSupercitetoanticipateeverystyleinexistence,andyouprobablywouldn'tencounterthemallanyway.ButyoucanconfigureSupercitetorecognizethosestylesyouseeoften.@xref{ConfiguringtheCitationEngine},fordetails.@refill@item@emph{Runs@code{sc-post-hook}.}@vindexsc-post-hook@vindexpost-hook(sc-)Thisvariableisverysimilarto@code{sc-pre-hook},exceptthatitrunsafter@code{sc-cite-original}isfinished.Thishookisprovidedmostlyforcompletenessandbackwardcompatibility.Perhapsitcouldbeusedtoresetcertainvariablessetin@code{sc-pre-hook}.@refill@endenumerate@nodeFillingCitedText,SelectinganAttribution,ReplyBufferInitialization,ReplyingandYanking@commentnode-name,next,previous,up@cindexfillingparagraphs@vindexsc-auto-fill-region-p@vindexauto-fill-region-p(sc-)@cindexfilladapt@cindexgin-mode@findexsc-setup-filladapt@findexsetup-filladapt(sc-)@vindexsc-load-hook@vindexload-hook(sc-)@sectionFillingCitedText@ifinfo@endifinfoSupercitewillautomaticallyfillnewlycitedtextfromtheoriginalmessageunlessthevariable@code{sc-auto-fill-region-p}hasa@code{nil}value.Supercitewillalsore-fillparagraphswhenyoumanuallyciteorre-citetext.However,duringnormalediting,Superciteitselfcannotbeusedtofillparagraphs.Thisisachangefromversion2.Thereareotheradd-onlisppackageswhichdofillingmuchbetterthanSuperciteeverdid.Thetwobestknownare@dfn{filladapt}and@dfn{gin-mode}.BothworkwellwithSuperciteandbothareavailableatthenormalEmacsLisparchivesites.@dfn{gin-mode}worksprettywelloutofthebox,butifyouuse@dfn{filladapt},youmaywanttorunthefunction@code{sc-setup-filladapt}fromyour@code{sc-load-hook}.Thissimplymakes@dfn{filladapt}alittlemoreSupercitesavvythanitsdefaultsetup.@vindexsc-fixup-whitespace-p@vindexfixup-whitespace-p(sc-)Also,Supercitewillcollapseleadingwhitespacebetweenthecitationstringandthetextonalinewhenthevariable@code{sc-fixup-whitespace-p}isnon-@code{nil}.Thedefaultvalueforthisvariableis@code{nil}.@refill@vindexfill-prefixItsimportanttounderstandthatSupercite'sautomaticfilling(duringtheinitialcitationofthereply)isveryfragile.Thatisbecausefiguringoutthe@code{fill-prefix}foraparticularparagraphisareallyhardthingtodoautomatically.Thisisespeciallythecasewhentheoriginalmessagecontainscodeorsomeothertextwhereleadingwhitespaceisimportanttopreserve.Forthisreason,manySuperciteuserstypicallyrunwith@code{sc-auto-fill-region-p}(andpossiblyalso@code{sc-fixup-whitespace-p})setto@code{nil}.Theythenmanuallyfilleachcitedparagraphinthereplybuffer.Iusuallyrunwithboththesevariablescontainingtheirdefaultvalues.WhenSupercite'sautomaticfillingbreaksonaparticularmessage,IwilluseEmacs'undofeaturetoundobackbeforethecitationwasappliedtotheoriginalmessage.ThenI'lltogglethevariablesandmanuallycitethoseparagraphsthatIdon'twanttofillorcollapsewhitespaceon.@xref{VariableTogglingShortcuts}.@refill@kindexC-cC-pC-pIfyoufindthatSupercite'sautomaticfillingisjusttoofragileforyourtastes,youmightconsideroneofthesealternateapproaches.Also,tomakelifeeasier,ashortcutfunctiontotogglethestateofbothofthesevariablesisprovidedonthekeybinding@kbd{C-cC-pC-p}(withthedefaultvalueof@code{sc-mode-map-prefix};@pxref{Post-yankFormattingCommands}).@refillYouwillnoticedthattheminormodestringwillshowthestateofthesevariablesasqualifiercharacters.Whenbothvariablesare@code{nil},theSuperciteminormodestringwilldisplay@samp{SC}.Whenjust@code{sc-auto-fill-region-p}isnon-@code{nil},thestringwilldisplay@samp{SC:f},andwhenjust@code{sc-fixup-whitespace-p}isnon-@code{nil},thestringwilldisplay@samp{SC:w}.Whenbothvariablesarenon-@code{nil},thestringwilldisplay@samp{SC:fw}.Notethatthequalifierschosenaremnemonicsforthedefaultbindingsofthetogglingfunctionforeachrespectivevariable.@xref{VariableTogglingShortcuts}.@refillWhyarethesevariablesnotsetto@code{nil}bydefault?Itisbecausemanyuserswon'tmanuallyfillparagraphsthatareSupercited,andtherehavebeenwidespreadcomplaintsonthenetaboutmailandnewsmessagescontaininglinesgreaterthanabout72characters.Sothedefaultistofillcitedtext.@nodeSelectinganAttribution,AttributionPreferences,FillingCitedText,Top@commentnode-name,next,previous,up@cindexattributionlist@vindexsc-preferred-attribution-list@vindexpreferred-attribution-list(sc-)@comment@chapterSelectinganAttribution@ifinfo@endifinfoAsyouknow,theattributionstringisthepartoftheauthor'snamethatwillbeusedtocomposedanon-nestedcitationstring.Supercitescansthevariousmailheaderspresentintheoriginalarticleandusesanumberofheuristicstoextractstringswhichitputsintothe@dfn{attributionassociationlist}or@dfn{attributionalist}.Thisisanalogous,butdifferentthan,theinfoalistpreviouslymentioned.Eachelementintheattributionalistisakey-valuepaircontainingsuchinformationastheauthor'sfirstname,middlenames,andlastname,theauthor'sinitials,andtheauthor'semailterminus.@ifinfo@menu*AttributionPreferences::*AnonymousAttributions::*AuthorNames::@endmenu@endifinfo@nodeAttributionPreferences,AnonymousAttributions,SelectinganAttribution,SelectinganAttribution@commentnode-name,next,previous,up@sectionAttributionPreferences@ifinfo@endifinfoWhenyouciteanoriginalmessage,youcantellSupercitewhichpartoftheauthor'snameyouwouldpreferittouseastheattribution.Thevariable@code{sc-preferred-attribution-list}controlsthis;itcontainskeyswhicharematchedagainsttheattributionalistinthegivenorder.Thefirstvalueofakeythatproducesanon-@code{nil},non-emptystringmatchisusedastheattributionstring,andifnokeysmatch,asecondarymechanismisusedtogeneratetheattribution.@xref{AnonymousAttributions}.Thefollowingpreferencesarealwaysavailableintheattributionalist(barringerror):@table@code@item"emailname"theauthor'semailterminus.@item"initials"theauthor'sinitials.@item"firstname"theauthor'sfirstname.@item"lastname"theauthor'slastname.@item"middlename-1"theauthor'sfirstmiddlename.@item"sc-lastchoice"thelastattributionstringyouhaveselected.Thisisusefulwhenyoureciteparagraphsinthereply.@refill@item"sc-consult"@vindexsc-attrib-selection-list@vindexattrib-selection-list(sc-)consultsthecustomizablelist@code{sc-attrib-selection-list}whichcanbeusedtoselectspecialattributionsbasedonthevalueofanyinfokey.Seebelowfordetails.@item"x-attribution"theoriginalauthor'ssuggestionforattributionstringchoice.Seebelowfordetails.@refill@endtableMiddlenameindexescanbeanypositiveintegergreaterthanzero,thoughitisunlikelythatmanyauthorswillhavemorethanonemiddlename,ifthatmany.Atthispoint,letmedigressintoadiscussionofetiquette.Itismybeliefthatwhilethestyleofthecitationsisareflectionofthepersonaltastesofthereplier(i.e.,you),theattributionselectionisultimatelythepersonalchoiceoftheoriginalauthor.Inasenseitishisorher``netnickname'',andthereforetheauthorshouldhavesomesayintheselectionofattributionstring.Imaginehowyouwouldfeelifsomeonegaveyouanicknamethatyoudidn'tlike?Forthisreason,Superciterecognizesaspecialmailheader,@samp{X-Attribution:},whichifpresent,tellsSupercitetheattributionstringpreferredbytheoriginalauthor.Itisthevalueofthisheaderthatisassociatedwiththe@code{"x-attribution"}keyintheattributionalist.Currently,youcanoverridethepreferenceofthiskeybychanging@code{sc-preferred-attribution-list},butthatisn'tpolite,andinthefutureSupercitemayhard-codethis.Fornow,itissuggestedthatifyouchangetheorderofthekeysinthislist,that@code{"x-attribution"}alwaysbefirst,orpossiblesecondbehindonly@code{"sc-lastchoice"}.Thislatteristhedefault.@vindexsc-attrib-selection-list@vindexattrib-selection-list(sc-)Thevalue@code{"sc-consult"}in@code{sc-preferred-attribution-list}hasaspecialmeaningduringattributionselection.WhenSuperciteencountersthispreference,itbeginsprocessingacustomizablelistofattributions,containedinthevariable@code{sc-attrib-selection-list}.Eachelementinthislistcontainslistsofthefollowingform:@example@group(@var{infokey}((@var{regexp}@.@var{attribution})(@var{regexp}@.@var{attribution})(@dots{})))@endgroup@endexample@noindent@findexsc-mail-field@findexmail-field(sc-)where@var{infokey}isakeyfor@code{sc-mail-field}and@var{regexp}isaregularexpressiontomatchagainstthe@var{infokey}'svalue.If@var{regexp}matchesthe@var{infokey}'svalue,the@var{attribution}isusedastheattributionstring.Actually,@var{attribution}canbeastringoralist;ifitisalist,itis@code{eval}uatedandthereturnvalue(whichmustbeastring),isusedastheattribution.Thiscanbeveryusefulforwhenyouarereplyingtonetacquaintanceswhodonotusethe@samp{X-Attribution:@:}mailheader.Youmayknowwhatnicknametheywouldprefertouse,andyoucansetupthislisttomatchagainstaspecificmailfield,e.g.,@samp{From:@:},allowingyoutociteyourfriend'smessagewiththeappropriateattribution.@nodeAnonymousAttributions,AuthorNames,AttributionPreferences,SelectinganAttribution@commentnode-name,next,previous,up@vindexsc-default-author-name@vindexdefault-author-name(sc-)@vindexsc-default-attribution@vindexdefault-attribution(sc-)@comment@sectionAnonymousAttributions@ifinfo@endifinfoWhentheauthor'snamecannotbefoundinthe@samp{From:@:}mailheader,afallbackauthornameandattributionstringmustbesupplied.Thefallbackauthornameiscontainedinthevariable@code{sc-default-author-name}andthefallbackattributionstringiscontainedinthevariable@code{sc-default-attribution}.Defaultvaluesforthesevariablesare@code{"Anonymous"}and@code{"Anon"},respectively.Notethatinmostcircumstances,gettingthedefaultauthornameorattributionisasignthatsomethingissetupincorrectly.@vindexsc-use-only-preference-p@vindexuse-only-preference-p(sc-)Also,ifthepreferredattribution,whichyouspecifiedinyour@code{sc-preferred-attribution-alist}variablecannotbefound,asecondarymethodcanbeemployedtofindavalidattributionstring.Thevariable@code{sc-use-only-preference-p}controlswhathappensinthiscase.Ifthevariable'svalueisnon-@code{nil},then@code{sc-default-author-name}and@code{sc-default-attribution}areused,otherwise,thefollowingstepsaretakentofindavalidattributionstring,andthefirststeptoreturnanon-@code{nil},non-emptystringbecomestheattribution:@refill@enumerate@itemUsethelastselectedattribution,ifthereisone.@itemUsethevalueofthe@code{"x-attribution"}key.@itemUsetheauthor'sfirstname.@itemUsetheauthor'slastname.@itemUsetheauthor'sinitials.@itemFindthefirstnon-@code{nil},non-emptyattributionstringintheattributionalist.@item@code{sc-default-attribution}isused.@endenumerate@vindexsc-confirm-always-p@vindexconfirm-always-p(sc-)Oncetheattributionstringhasbeenautomaticallyselected,anumberofthingscanhappen.Ifthevariable@code{sc-confirm-always-p}isnon-@code{nil},youarequeriedforconfirmationofthechosenattributionstring.Thepossiblevaluesforcompletionarethosestringsintheattributionalist,howeveryouarenotlimitedtothesechoices.Youcantypeanyarbitrarystringattheconfirmationprompt.Thestringyouenterbecomesthevalueassociatedwiththe@code{"sc-lastchoice"}keyintheattributionalist.@vindexsc-downcase-p@vindexdowncase-p(sc-)Onceanattributionstringhasbeenselected,Supercitewillforcethestringtolowercaseifthevariable@code{sc-downcase-p}isnon-@code{nil}.@vindexsc-attribs-preselect-hook@vindexattribs-preselect-hook(sc-)@vindexsc-attribs-postselect-hook@vindexattribs-postselect-hook(sc-)Twohookvariablesprovideevengreatercontroloftheattributionselectionprocess.Thehook@code{sc-attribs-preselect-hook}isrunbeforeanyattributionisselected.Likewise,thehook@code{sc-attribs-postselect-hook}isrunaftertheattributionisselected(andthecorrespondingcitationstringisbuilt),butbeforethesevaluesarecommittedforusebySupercite.Duringthepost-selectionhook,thelocalvariables@code{attribution}and@code{citation}areboundtotheappropriatestrings.Bychangingthesevariablesinyourhookfunctions,youchangetheattributionandcitationstringsusedbySupercite.Onepossibleuseofthiswouldbetooverrideanyautomaticallyderivedattributionstringwhenitisonlyonecharacterlong;e.g.youprefertouse@code{"initials"}buttheauthoronlyhasonename.@refill@nodeAuthorNames,ConfiguringtheCitationEngine,AnonymousAttributions,SelectinganAttribution@commentnode-name,next,previous,up@cindexauthornames@sectionAuthorNames@ifinfo@endifinfoSuperciteemploysanumberofheuristicstodeciphertheauthor'snamebasedonvalueofthe@samp{From:@:}mailfieldoftheoriginalmessage.Supercitecanrecognizealmostallofthecommon@samp{From:@:}fieldformatsinuse.Ifyouencountera@samp{From:@:}fieldthatSupercitecannotparse,pleasereportthisbug.@xref{TheSuperciteMailingList}.@refill@vindexsc-titlecue-regexp@vindextitlecue-regexp(sc-)ThereareanumberofSupercitevariablesthatcontrolhowauthornamesareextractedfromthe@samp{From:@:}header.Someheadersmaycontainadescriptivetitleasin:@exampleFrom:@:computer!speedy!doe(JohnXavier-Doe--DecentHacker)@endexampleSuperciteknowswhichpartofthe@samp{From:@:}headerisemailaddressandwhichpartisauthorname,butinthiscasethestring@code{"DecentHacker"} is not part of the author's name. You can tell Supercite toignorethetitle,whilestillrecognizinghyphenatednamesthroughtheuseofaregularexpressioninthevariable@code{sc-titlecue-regexp}.Thisvariablehasthedefaultvalueof@code{"\\\\s +-+\\\\s +"}.Anytextafterthisregexpisencounteredisignoredasnoise.@vindexsc-name-filter-alist@vindexname-filter-alist(sc-)Some@samp{From:@:}headersmaycontainextratitlesinthenamefieldsnotseparatedbyatitlecue,butwhicharenonethelessnotpartoftheauthor'snameproper.Examplesincludethetitles``Dr.'',``Mr.'',``Ms.'',``Jr.'',``Sr.'',and``III''(e.g.,ThurstonHowe,theThird).Also,somecompaniesprependorappendthenameofthedivision,organization,orprojectontheauthor'sname.Allofthesetitlesarenoisewhichshouldbeignored.Thevariable@code{sc-name-filter-alist}isusedforthispurpose.Asimpliedbyitsname,thisvariableisanassociationlist,whereeachelementisaconscelloftheform:@example(@var{regexp}@.@var{position})@endexample@noindentwhere@var{regexp}isaregularexpressionthatismatched(using@code{string-match})againsteachelementofthe@samp{From:@:}field'sauthorname.@var{position}isapositionindicator,startingatzero.Thustostripoutalltitlesof``Dr.'',``Mr.'',etc.fromthename,@code{sc-name-filter-alist}wouldhaveanentrysuchas:@example("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$"@.0)@endexample@noindentwhichonlyremovesthemiftheyappearasthefirstwordinthename.Thepositionindicatorisaninteger,oroneofthetwospecialsymbols@code{last}or@code{any}.@code{last}alwaysmatchesagainstthelastwordinthenamefield,while@code{any}matchesagainsteverywordinthenamefield.@nodeConfiguringtheCitationEngine,UsingRegi,AuthorNames,Top@commentnode-name,next,previous,up@cindexRegi@cindexframes(Regi)@cindexentries(Regi)@chapterConfiguringtheCitationEngine@ifinfo@endifinfoAttheheartofSuperciteisaregularexpressioninterpretingenginecalled@dfn{Regi}.RegioperatesbyinterpretingadatastructurecalledaRegi-frame(orjust@dfn{frame}),whichisalistofRegi-entries(orjust@dfn{entry}).Eachentrycontainsapredicate,typicallyaregularexpression,whichismatchedagainstalineoftextinthecurrentbuffer.Ifthepredicatematchestrue,anassociatedexpressionis@code{eval}uated.Inthisway,anentireregionoftextcanbetransformedinan@emph{awk}-likemanner.RegiisusedthroughoutSupercite,frommailheaderinformationextraction,toheadernuking,tocitingtext.@ifinfo@menu*UsingRegi::*FramesYouCanCustomize::@endmenu@endifinfoWhilethedetailsofRegiarediscussedbelow(@pxref{UsingRegi}),onlythosewhowishtocustomizecertainaspectsofSuperciteneedconcernthemselveswithit.Itisimportanttounderstandthough,thatanyconceivablecitationstylethatcanbedescribedbyaregularexpressioncanberecognizedbySupercite.Thisleadstosomeinterestingapplications.Forexample,ifyouregularlyrecieveemailfromaco-workerthatusesanuncommoncitationstyle(sayonethatemploysa@samp{|}or@samp{@}}characteratthefrontoftheline),itispossibleforSupercitetorecognizethisand@emph{coerce}thecitationtoyourpreferredstyle,forconsistency.Intheory,itispossibleforSupercitetorecognizesuchthingsasuuencodedmessagesorCcodeandciteorfillthosedifferentlythannormaltext.NoneofthisiscurrentlypartofSupercite,butcontributionsarewelcome!@nodeUsingRegi,FramesYouCanCustomize,ConfiguringtheCitationEngine,ConfiguringtheCitationEngine@commentnode-name,next,previous,up@findexregi-interpret@findexeval@findexlooking-at@sectionUsingRegi@ifinfo@endifinfoRegiworksbyinterpretingframeswiththefunction@code{regi-interpret}.Aframeisalistofarbitrarysizewhereeachelementisaentryofthefollowingform:@example(@var{pred}@var{func}[@var{negate-p}[@var{case-fold-search}]])@endexampleRegistartswiththefirstentryinaframe,evaluatingthe@var{pred}ofthatentryagainstthebeginningofthelinethat@samp{point}ison.Ifthe@var{pred}evaluatestotrue(orfalseiftheoptional@var{negate-p}isnon-@code{nil}),thenthe@var{func}forthatentryis@code{eval}uated.Howprocessingcontinuesisdeterminedbythereturnvaluefor@var{func},andisdescribedbelow.If@var{pred}wasfalsethenextentryintheframeischeckeduntilallentrieshavebeenmatchedagainstthecurrentline.Ifnoentrymatches,@samp{point}ismovedforwardonelineandtheframeisresettothefirstentry.@var{pred}canbeastring,avariable,alistoroneofthefollowingsymbols:@code{t},@code{begin},@code{end},or@code{every}.If@var{pred}isastring,oravariableorlistthat@code{eval}uatestoastring,itisinterpretedasaregularexpression.Thisregexpismatchedagainstthecurrentline,fromthebeginning,using@code{looking-at}.Thismatchfoldscaseiftheoptional@var{case-fold-search}isnon-@code{nil}.If@var{pred}isnotastring,ordoesnot@code{eval}uatetoastring,itisinterpretedasabinaryvalue(@code{nil}ornon-@code{nil}).@refillThefourspecialsymbolvaluesfor@var{pred}arerecognized:@table@code@itemtAlwaysproducesatrueoutcome.@itembeginAlwaysexecutedbeforetheframeisinterpreted.Thiscanbeusedtoinitializesomeglobalvariablesforexample.@itemendAlwaysexecutedafterframeinterpretingiscompleted.Thiscanbeusedtoperformanynecessarypost-processing.@itemeveryExecuteswhenevertheframeisreset,usuallyaftertheentireframehasbeenmatchedagainstthecurrentline.@endtableNotethat@var{negate-p}and@var{case-fold-search}areignoredif@var{pred}isoneofthesespecialsymbols.Onlythefirstoccuranceofeachsymbolinaframeisused;anyduplicatesareignored.Alsonotethatforperformancereasons,theentriesassociatedwiththesesymbolsareremovedfromtheframeduringthemaininterpretingloop.Your@var{func}canreturncertainvalueswhichcontrolcontinuedRegiprocessing.Bydefault,ifyour@var{func}returns@code{nil}(asitshouldbecarefultodoexplicitly),Regiwillresettheframetothefirstentry,andadvance@samp{point}tothebeginningofthenextline.Ifalistisreturnedfromyourfunction,itcancontainanycombinationofthefollowingelements:@refill@table@asis@itemthesymbol@code{continue}ThistellsRegitocontinueprocessingentriesafteramatch,insteadofresetingtheframeandmoving@samp{point}.Inthisway,linesoftextcanhavemultiplematches,butyouhavetobecarefultoavoidenteringinfiniteloops.@itemthesymbol@code{abort}ThistellsRegitoterminateframeprocessing.However,any@code{end}entryisstillprocessed.@itemthelist@code{(frame.@var{newframe})}ThistellsRegitosubstitute@var{newframe}astheframeitisinterpreting.Inotherwords,your@var{func}canmodifytheRegiframeonthefly.@var{newframe}canbeavariablecontainingaframe,oritcanbetheframein-lined.@refill@itemthelist@code{(step.@var{step})}TellsRegitomove@var{step}numberoflinesforwardasitcontinuesprocessing.Bydefault,Regimovesforwardoneline.@var{step}canbezeroornegativeofcourse,butwatchoutforinfiniteloops.@refill@endtableDuringexecutionofyour@var{func},thefollowingvariableswillbetemporarilyboundtosomeusefulinformation:@refill@table@code@itemcurlineThecurrentlineinthebufferthatRegiis@code{looking-at},asastring.@itemcurframeThecurrentframebeinginterpreted.@itemcurentryThecurrentframeentrybeinginterpreted.@endtable@nodeFramesYouCanCustomize,Post-yankFormattingCommands,UsingRegi,ConfiguringtheCitationEngine@commentnode-name,next,previous,up@vindexsc-nuke-mail-header@sectionFramesYouCanCustomize@ifinfo@endifinfoAsmentionedearlier,Superciteusesvariousframestoperformcertainjobssuchasmailheaderinformationextractionandmailheadernuking.However,theseframesarenotavailableforyoutocustomize,exceptthroughabstractinterfacessuchas@code{sc-nuke-mail-header},etal.@vindexsc-default-cite-frameHowever,thecitationframesSuperciteusesprovidealotofcustomizingpowerandarethusavailabletoyoutochangetosuityourneeds.Theworkhorseofcitationistheframecontainedinthevariable@code{sc-default-cite-frame}.Thisframerecognizesmanysituations,suchasblanklines,whichitinterpretsasparagraphseparators.Italsorecognizespreviouslycitednestedandnon-nestedcitationsintheoriginalmessage.Bydefaultitwillcoercenon-nestedcitationsintoyourpreferredcitationstyle,anditwilladdalevelofcitationtonestedcitations.Itwillalsosimplyciteuncitedlinesinyourpreferredstyle.@cindexunciting@cindexreciting@vindexsc-default-uncite-frame@vindexsc-default-recite-frameInasimilarvein,therearedefaultframesfor@dfn{unciting}and@dfn{reciting},containedinthevariables@code{sc-default-uncite-frame}and@code{sc-default-recite-frame}respectively.@refillAsmentionedearlier(@pxref{RecognizingCitations}),citationsarerecognizedthroughthevaluesoftheregularexpressions@code{sc-citation-root-regexp},etal.Torecognizeoddstyles,youcouldmodifythesevariables,oryoucouldmodifythedefaultcitingframe.Alternatively,youcouldsetupassociationlistsofframesforrecognizingspecificalternativeforms.@vindexsc-cite-frame-alist@vindexsc-uncite-frame-alist@vindexsc-recite-frame-alistForeachoftheactions--citing,unciting,andreciting--analistisconsultedtofindtheframetouse(@code{sc-cite-frame-alist},@code{sc-uncite-frame-alist},and@code{sc-recite-frame-alist}respectively).Theseframescancontainalistsoftheform:@example((@var{infokey}(@var{regexp}@.@var{frame})(@var{regexp}@.@var{frame})@dots{})(@var{infokey}(@var{regexp}@.@var{frame})(@var{regexp}@.@var{frame})@dots{})(@dots{}))@endexample@vindexsc-mail-field@findexstring-matchWhere@var{infokey}isakeysuitablefor@code{sc-mail-field},@var{regexp}isaregularexpressionwhichis@code{string-match}'dagainstthevalueofthe@code{sc-mail-field}key,and@var{frame}istheframetouseifamatchoccurred.@var{frame}canbeavariablecontainingaframeoraframein-lined.@refillWhenSuperciteisabouttocite,uncite,orrecitearegion,itconsultstheappropriatealistandattemptstofindaframetouse.Ifoneisnotfoundfromthealist,thentheappropriatedefaultframeisused.@nodePost-yankFormattingCommands,CitingCommands,FramesYouCanCustomize,Top@commentnode-name,next,previous,up@vindexsc-mode-map-prefix@vindexmode-map-prefix(sc-)@kindexC-cC-p@chapterPost-yankFormattingCommands@ifinfo@endifinfoOncetheoriginalmessagehasbeenyankedintothereplybuffer,and@code{sc-cite-original}hashadachancetodoitsthing,anumberofusefulSupercitecommandswillbeavailabletoyou.SincethereiswidevarietyinthekeymapsthatMUAssetupintheirreplybuffers,itisnexttoimpossibleforSupercitetoproperlysprinkleitscommandsintotheexistingkeymap.ForthisreasonSuperciteplacesitscommandsonaseparatekeymap,puttingthiskeymapontoaprefixkeyinthereplybuffer.YoucancustomizetheprefixkeySuperciteusesbychangingthevariable@code{sc-mode-map-prefix}.Bydefault,the@code{sc-mode-map-prefix}is@kbd{C-cC-p};granted,notagreatchoice,butunfortunatelythebestgeneralsolutionsofar.Intherestofthischapter,we'llassumeyou'veinstalledSupercite'skeymaponthedefaultprefix.@refill@ifinfo@menu*CitingCommands::*InsertionCommands::*VariableTogglingShortcuts::*MailFieldCommands::*MiscellaneousCommands::@endmenu@endifinfo@nodeCitingCommands,InsertionCommands,Post-yankFormattingCommands,Post-yankFormattingCommands@commentnode-name,next,previous,up@vindexsc-cite-region-limit@sectionCommandstoManuallyCite,Recite,andUncite@ifinfo@endifinfoProbablythethreemostcommonpost-yankformattingoperationsthatyouwillperformwillbethemanualciting,reciting,anduncitingofregionsoftextinthereplybuffer.Oftenyoumaywanttoreciteaparagraphtouseanickname,ormanuallyciteamessagewhensetting@code{sc-cite-region-limit}to@code{nil}.Thefollowingcommandsperformthesefunctionsontheregionoftextbetween@samp{point}and@samp{mark}.Eachofthemsetsthe@dfn{undoboundary}beforemodifyingtheregionsothatthecommandcanbeundoneinthestandardEmacsway.@refillAquicknoteaboutEmacs19.UnlikeinEmacs18,theregiondelimitedby@samp{point}and@samp{mark}canhavetwostates.Itcanbe@dfn{active}or@dfn{inactive}.AlthoughtheFSFEmacs19andLucidEmacs19usedifferentterminologyandfunctions,bothemploythesameconventionsuchthatwhentheregionisinactive,commandsthatmodifytheregionshouldgenerateanerror.Theuserneedstoexplicitlyactivatetheregionbeforesuccessfullyexecutingthecommand.AllSupercitecommandsconformtothisconvention.HereisthelistofSupercitecitingcommands:@table@asis@findexsc-cite-region@findexcite-region(sc-)@kindexC-cC-pc@vindexsc-pre-cite-hook@vindexpre-cite-hook(sc-)@vindexsc-confirm-always-p@vindexconfirm-always-p@kindexC-u@item@code{sc-cite-region}(@kbd{C-cC-pc})@commentThiscommandciteseachlineintheregionoftextbyinterpretingtheselectedframefrom@code{sc-cite-frame-alist},orthedefaultcitingframe@code{sc-default-cite-frame}.Itrunsthehook@code{sc-pre-cite-hook}beforeinterpretingtheframe.Withanoptionaluniversalargument(@kbd{C-u}),ittemporarilysets@code{sc-confirm-always-p}to@code{t}soyoucanconfirmtheattributionstringforasinglemanualciting.@xref{ConfiguringtheCitationEngine}.@refill@findexsc-uncite-region@findexuncite-region(sc-)@kindexC-cC-pu@item@code{sc-uncite-region}(@kbd{C-cC-pu})@commentThiscommandremovesanycitationstringsfromthebeginningofeachcitedlineintheregionbyinterpretingtheselectedframefrom@code{sc-uncite-frame-alist},orthedefaultuncitingframe@code{sc-default-uncite-frame}.Itrunsthehook@code{sc-pre-uncite-hook}beforeinterpretingtheframe.@xref{ConfiguringtheCitationEngine}.@refill@findexsc-recite-region@findexrecite-region(sc-)@kindexC-cC-pr@item@code{sc-recite-region}(@kbd{C-cC-pr})@commentThiscommandreciteseachlinetheregionbyinterpretingtheselectedframefrom@code{sc-recite-frame-alist},orthedefaultrecitingframe@code{sc-default-recite-frame}.Itrunsthehook@code{sc-pre-recite-hook}beforeinterpretingtheframe.@xref{ConfiguringtheCitationEngine}.@refill@vindexsc-confirm-always-p@vindexconfirm-always-p(sc-)Supercitewillalwaysaskyoutoconfirmtheattributionwhenrecitingaregion,regardlessofthevalueof@code{sc-confirm-always-p}.@endtable@nodeInsertionCommands,VariableTogglingShortcuts,CitingCommands,Post-yankFormattingCommands@commentnode-name,next,previous,up@sectionInsertionCommands@ifinfo@endifinfoThesetwofunctionsinsertvariousstringsintothereplybuffer.@table@asis@findexsc-insert-reference@findexinsert-reference(sc-)@kindexC-cC-pw@item@code{sc-insert-reference}(@kbd{C-cC-pw})@comment@vindexsc-preferred-header-style@vindexpreferred-header-style(sc-)Insertsareferenceheaderintothereplybufferat@samp{point}.Withnoarguments,theheaderindexedby@code{sc-preferred-header-style}isinserted.Anoptionalnumericargumentistheindexinto@code{sc-rewrite-header-list}indicatingwhichreferenceheadertowrite.@refillWithjusttheuniversalargument(@kbd{C-u}),electricreferencemodeisentered,regardlessofthevalueof@code{sc-electric-references-p}.@findexsc-insert-citation@findexinsert-citation(sc-)@kindexC-cC-pi@item@code{sc-insert-citation}(@kbd{C-cC-pi})@commentInsertsthecurrentcitationstringatthebeginningofthelinethat@samp{point}ison.Ifthelineisalreadycited,Supercitewillissueanerrorandwillnotcitetheline.@endtable@nodeVariableTogglingShortcuts,MailFieldCommands,InsertionCommands,Post-yankFormattingCommands@commentnode-name,next,previous,up@cindextogglingvariables@sectionVariableTogglingShortcuts@ifinfo@endifinfoSupercitedefinesanumberofcommandsthatmakeiteasierforyoutotoggleandsetvariousSupercitevariablesasyouareeditingthereplybuffer.Forexample,youmaywanttoturnofffillingorwhitespacecleanup,butonlytemporarily.Thesetogglingshortcutcommandsmakethiseasytodo.@kindexC-cC-pC-tLikeSupercitecommandsingeneral,thetogglingcommandsareplacedonakeymapprefixwithinthegreaterSupercitekeymap.Forthedefaultvalueof@code{sc-mode-map-prefix},thiswillbe@kbd{C-cC-pC-t}.@refillThefollowingcommandstogglethevalueofcertainSupercitevariableswhichtakeonlyabinaryvalue:@table@kbd@itemC-cC-pC-tbTogglesthevariable@code{sc-mail-nuke-blank-lines-p}.@itemC-cC-pC-tcTogglesthevariable@code{sc-confirm-always-p}.@itemC-cC-pC-tdTogglesthevariable@code{sc-downcase-p}.@itemC-cC-pC-teTogglesthevariable@code{sc-electric-references-p}.@itemC-cC-pC-tfTogglesthevariable@code{sc-auto-fill-region-p}.@itemC-cC-pC-toTogglesthevariable@code{sc-electric-circular-p}.@itemC-cC-pC-tsTogglesthevariable@code{sc-nested-citation-p}.@itemC-cC-pC-tuTogglesthevariable@code{sc-use-only-preferences-p}.@itemC-cC-pC-twTogglesthevariable@code{sc-fixup-whitespace-p}.@endtable@findexset-variableThefollowingcommandsletyousetthevalueofmulti-valuevariables,inthesamewaythatEmacs'@code{set-variable}does:@table@kbd@itemC-cC-pC-taSetsthevalueofthevariable@code{sc-preferred-attribution-list}.@itemC-cC-pC-tlSetsthevalueofthevariable@code{sc-cite-region-limit}.@itemC-cC-pC-tnSetsthevalueofthevariable@code{sc-mail-nuke-mail-headers}.@itemC-cC-pC-tNSetsthevalueofthevariable@code{sc-mail-header-nuke-list}.@itemC-cC-pC-tpSetsthevalueofthevariable@code{sc-preferred-header-style}.@endtable@kindexC-cC-pC-pOnespecialcommandisprovidedtotoggleboth@code{sc-auto-fill-region-p}and@code{sc-fixup-whitespace-p}together.ThisisbecauseyoutypicallywanttorunSupercitewitheithervariableas@code{nil}ornon-@code{nil}.Thecommandtotogglethesevariablestogetherisboundon@kbd{C-cC-pC-p}.@refillFinally,thecommand@kbd{C-cC-pC-th}(also@kbd{C-cC-pC-t?})bringsupaHelpmessageonthetogglingkeymap.@nodeMailFieldCommands,MiscellaneousCommands,VariableTogglingShortcuts,Post-yankFormattingCommands@commentnode-name,next,previous,up@sectionMailFieldCommands@ifinfo@endifinfoThesecommandsallowyoutoview,modify,add,anddeletevariousbitsofinformationfromtheinfoalist.@xref{InformationKeysandtheInfoAlist}.@refill@table@asis@kindexC-cC-pf@findexsc-mail-field-query@findexmail-field-query(sc-)@kindexC-cC-pf@item@code{sc-mail-field-query}(@kbd{C-cC-pf})@commentAllowsyoutointeractivelyview,modify,add,anddeleteinfoalistkey-valuepairs.Withnoargument,youareprompted(withcompletion)forainfokey.Thevalueassociatedwiththatkeyisdisplayedintheminibuffer.Withanargument,thiscommandwillfirstaskifyouwanttoview,modify,add,ordeleteaninfokey.Viewingisidenticaltorunningthecommandwithnoarguments.Ifyouwanttomodifythevalueofakey,Supercitewillfirstpromptyou(withcompletion)forthekeyofthevalueyouwanttochange.Itwillthenputyouintheminibufferwiththekey'scurrentvaluesoyoucaneditthevalueasyouwish.Whenyouhit@key{RET},thekey'svalueischanged.ForthoseofyourunningEmacs19,minibufferhistoryiskeptforthevalues.Ifyouchoosetodeleteakey-valuepair,Supercitewillpromptyou(withcompletion)forthekeytodelete.Ifyouchoosetoaddanewkey-valuepair,Supercitefirstspromptsyouforthekeytoadd.Notethatcompletionisturnedonforthisprompt,butyoucantypeanykeynamehere,evenonethatdoesnotyetexist.Afterenteringthekey,Supercitepromptsyouforthekey'svalue.Itisnotanerrortoenterakeythatalreadyexists,butthenewvaluewilloverrideanyoldvalue.Itwillnotreplaceitthough;ifyousubsequentlydeletethekey-valuepair,theoldvaluewillreappear.@findexsc-mail-process-headers@findexmail-process-headers(sc-)@kindexC-cC-pg@item@code{sc-mail-process-headers}(@kbd{C-cC-pg})@commentThiscommandletsyoure-initializeSupercite'sinfoalistfromanysetofmailheadersintheregionbetween@samp{point}and@samp{mark}.ThisfunctionisespeciallyusefulforreplyingtodigestmessageswhereSupercitewillinitiallysetupitsinformationforthedigestoriginator,butyouwanttociteeachcomponentarticlewiththerealmessageauthor.Notethatunlessanerrorduringprocessingoccurs,anyoldinformationislost.@refill@endtable@nodeMiscellaneousCommands,InformationKeysandtheInfoAlist,MailFieldCommands,Post-yankFormattingCommands@commentnode-name,next,previous,up@sectionMiscellaneousCommands@ifinfo@endifinfo@table@asis@findexsc-open-line@findexopen-line(sc-)@findexopen-line@kindexC-cC-po@item@code{sc-open-line}(@kbd{C-cC-po})@commentSimilartoEmacs'standard@code{open-line}commands,butinsertsthecitationstringinfrontofthenewline.Aswith@code{open-line},anoptionalnumericargumentinsertsthatmanynewlines.@refill@findexsc-describe@findexdescribe(sc-)@kindexC-cC-p?@kindexC-cC-ph@item@code{sc-describe}(@kbd{C-cC-ph}and@kbd{C-cC-p?})@commentThisfunctionhasbeenobsoletedbythe@TeX{}infomanualyouarenowreading.Itisstillprovidedforcompatibility,butitwilleventuallygoaway.@findexsc-version@findexversion(sc-)@kindexC-cC-pv@item@code{sc-version}(@kbd{C-cC-pv})@commentEchostheversionofSuperciteyouareusing.Withtheoptionaluniversalargument(@kbd{C-u}),thiscommandinsertstheversioninformationintothecurrentbuffer.@findexsc-submit-bug-report@findexsubmit-bug-report(sc-)@kindexC-cC-pC-b@item@code{sc-submit-bug-report}(@kbd{C-cC-pC-b})@commentIfyouencounterabug,orwishtosuggestanenhancement,usethiscommandtosetupanoutgoingmailbuffer,withtheproperaddresstotheSupercitemaintainerautomaticallyinsertedinthe@samp{To:@:}field.ThiscommandalsoinsertsinformationthattheSupercitemaintainercanusetorecreateyourexactsetup,makingiteasiertoverifyyourbug.@endtable@nodeHintstoMUAAuthors,Version3Changes,ElectricReferences,Top@commentnode-name,next,previous,up@chapterHintstoMUAAuthors@ifinfo@endifinfoInJuneof1989,somediscussionwasheldbetweenthevariousMUAauthors,theSuperciteauthor,andotherSuperciteusers.ThesediscussionscenteredaroundtheneedforastandardinterfacebetweenMUAsandSupercite(oranyfutureSupercite-likepackages).ThisinterfacewasformallyproposedbyMartinNeitzelonFri,23Jun89,inamailmessagetotheSupercitemailinglist:@exampleMartin>Eachnews/mail-readershouldprovideaformofMartin>mail-yank-originalthatMartin>1:insertstheoriginalmessageincl.headerintotheMartin>replybuffer;noindentation/prefixingisdone,theheaderMartin>tendstobea"full blown"versionratherthantobeMartin>strippeddown.Martin>2:`point'isatthestartoftheheader,`mark'attheMartin>endofthemessagebody.Martin>3:(run-hooks'mail-yank-hooks)Martin>[Supercite]shouldberunassuchahookandmerelyMartin>rewritethemessage.Thiswayitisn'tanymoreMartin>[Supercite]'sjobtogathertheoriginalfromobscureMartin>sources.[@dots{}]@endexample@vindexmail-citation-hook@vindexmail-yank-hooks@cindexsendmail.el@findexmail-yank-original@findexdefvarThisspecificationwasadopted,butwiththerecentreleaseofFSFGNUEmacs19,ithasundergoneaslightmodification.Insteadofthevariable@code{mail-yank-hooks},thenewpreferredhookvariablethattheMUAshouldprovideis@code{mail-citation-hook}.@code{mail-yank-hooks}canbeprovidedforbackwardcompatibility,but@code{mail-citation-hook}shouldalwaystakeprecedence.RichardStallman(oftheFSF)suggeststhattheMUAsshould@code{defvar}@code{mail-citation-hook}to@code{nil}andperformsomedefaultcitingwhenthatisthecase.TakealookatEmacs19's@file{sendmail.el}file,specificallythe@code{mail-yank-original}defunfordetails.@refillIfyouarewritinganewMUApackage,ormaintaininganexistingMUApackage,youshouldmakeitconformtothisinterfacesothatyouruserswillbeabletolinkSuperciteeasilyandseamlessly.Todothis,whensettingupareplyorforwardbuffer,yourMUAshouldfollowthesesteps:@enumerate@itemInserttheoriginalmessage,includingthemailheadersintothereplybuffer.Atthispointyoushouldnotmodifytherawtextinanyway,andyoushouldplacealltheoriginalheadersintothebodyofthereply.Thismeansthatmanyofthemailheaderswillbeduplicated,onecopyabovethe@code{mail-header-separator}lineandonecopybelow,howevertherewillprobablybemoreheadersbelowthisline.@refill@itemSet@samp{point}tothebeginningofthelinecontainingthefirstmailheaderinthebodyofthereply.Set@samp{mark}attheendofthemessagetext.ItisveryimportantthattheregionbesetaroundthetextSuperciteistomodifyandthatthemailheadersarewithinthisregion.Supercitewillnotventureoutsidetheregionforanyreason,andanythingwithintheregionisfairgame,sodon'tputanythingthat@strong{must}remainunchangedinsidetheregion.FurthernotethatforEmacs19,theregionneednotbesetactive.Supercitewillworkproperlywhentheregionisinactive,asshouldanyotherlike-mindedpackage.@refill@itemRunthehook@code{mail-citation-hook}.YouwillprobablywanttoprovidesomekindofdefaultcitationfunctionsincaseswheretheuserdoesnothaveSuperciteinstalled.Bydefault,yourMUAshould@code{defvar}@code{mail-citation-hook}to@code{nil},andinyouryankingfunction,checkitsvalue.Ifitfinds@code{mail-citation-hook}tobe@code{nil},itshouldperformsomedefaultcitingbehavior.UserwhowanttoconnecttoSupercitethenneedonlyadd@code{sc-cite-original}tothislistofhooksusing@code{add-hook}.@refill@endenumerateIfyoudoallthis,youruserswillnotneedtooverloadyourroutinestouseSupercite,andyourMUAwilljointheranksofthosethatconformtothisinterface``outofthebox.''@nodeVersion3Changes,ThanksandHistory,HintstoMUAAuthors,Top@commentnode-name,next,previous,up@chapterVersion3Changes@ifinfo@endifinfo@cindexsc-unsupp.elfileWithversion3,Supercitehasundergoneanalmostcompleterewrite,andhashopefullybenefittedinanumberofways,includingvastimprovementsinthespeedofperformance,abigreductioninsizeofthecodeandintheuseofEmacsresources,andamuchcleanerandflexibleinternalarchitecture.Thecentralconstructoftheinfoalist,anditsroleinSupercitehasbeenexpanded,andtheothercentralconcept,thegeneralpackageRegi,wasdevelopedtoprovideatheoreticallyunlimitedflexibility.Butmostofthisworkisinternalandnotofverygreatimportancetothecasualuser.Therehavebeensomechangesattheuser-visiblelevel,butforthemostpart,theSuperciteconfigurationvariablesfromversion2shouldstillberelevanttoversion3.Below,Ibrieflyoutlinethoseuser-visiblethingsthathavechangedsinceversion2.Fordetails,looktoothersectionsofthismanual.@enumerate@item@cindexsupercite.elfile@cindexreporter.elfile@cindexregi.elfile@cindexsc.elfromversion2@cindexsc-elec.elfromversion2Supercitepropernowcomesinasinglefile,@file{supercite.el},whichcontainseverythingexcepttheunsupportednoodlings,overloading(whichshouldbemoreorlessobsoletewiththereleaseofEmacs19),andthegenerallisppackages@file{reporter.el}and@file{regi.el}.Finally,the@TeX{}infomanualcomesinitsownfileaswell.Inparticular,thefile@file{sc.el}fromtheversion2distributionisobsolete,asisthefile@file{sc-elec.el}.@item@code{sc-spacify-name-chars}isgoneinversion3.@item@vindexsc-attrib-selection-list@vindexattrib-selection-list@code{sc-nickname-alist}isgoneinversion3.The@code{sc-attrib-selection-list}isamoregeneralconstructsupportingthesamebasicfeature.@itemTheversion2variable@code{sc-preferred-attribution}hasbeenchangedto@code{sc-preferred-attribution-list},andhasbeenexpandedupontoallowyoutospecifyanorderedlistofpreferredattributions.@item@code{sc-mail-fields-list}hasbeenremoved,andheadernukingingeneralhasbeengreatlyimproved,givingyouwiderflexibilityinspecifyingwhichheaderstokeepandremovewhilepresentingasimplifiedinterfacetocommonlychosendefaults.@itemPost-yankparagraphfillinghasbeencompletelyremovedfromSupercite,otherpackagesjustdoitbetterthanSuperciteeverwould.Supercitewillstillfillnewlycitedparagraphs.@item@vindexsc-cite-region-limit@vindexcite-region-limitThevariable@code{sc-all-but-cite-p}hasbeenreplacedby@code{sc-cite-region-limit}.@itemKeymaphackinginthereplybufferhasbeengreatlysimplified,with,Ibelieve,littlereductioninfunctionality.@itemHackingofthereplybuffer'sdocstringhasbeencompletelyeliminated.@endenumerate@nodeThanksandHistory,TheSuperciteMailingList,Version3Changes,Top@commentnode-name,next,previous,up@chapterThanksandHistory@ifinfo@endifinfoTheSupercitepackagewasderivedfromitspredecessorSuperyank1.11whichwasinspiredbyvariousbitsofcodeandideasfromMartinNeitzelandAshwinRam.Theywerethefolkswhocameupwiththeideaofnon-nestedcitationsandimplementedsomeroughcodetoprovidethisstyle.SuperyankandSuperciteversion2evolvedtothepointwheremuchoftheattributionselectionmechanismwasautomatic,andfeatureshavebeencontinuouslyaddedthroughthecommentsandsuggestionsoftheSupercitemailinglistparticipants.Superciteversion3representsanearlycompleterewritewithmanyofthealgorithmsandcodingstylesbeingvastlyimproved.HopefullySuperciteversion3isfaster,smaller,andmuchmoreflexiblethanitspredecessors.Intheversion2manualIthankedsomespecificpeoplefortheirhelpindevelopingSupercite2.Youfolksknowwhoyouareandyourcontinuedsupportisgreatlyappreciated.IwishtothankeveryoneontheSupercitemailinglist,especiallythebravealphatesters,whohelpedconsiderablyintestingouttheconceptsandimplementationofSuperciteversion3.SpecialthanksgoouttotheMUAandEmacsauthorsKyleJones,StephenGildea,RichardStallman,andJamieZawinskiforcomingtoaquickagreementonthenew@code{mail-citation-hook}interface,andforaddingthemagiclisptotheircodetosupportthis.Allwhohavehelpedandcontributedhavebeengreatlyappreciated.@nodeTheSuperciteMailingList,ConceptIndex,ThanksandHistory,Top@commentnode-name,next,previous,up@cindexsupercitemailinglistaddress@cindexmailinglistaddress@chapterTheSuperciteMailingList@ifinfo@endifinfoTheauthorrunsasimplemailexpandingmailinglistfordiscussionofissuesrelatedtoSupercite.Thisincludesenhancementrequests,bugreports,generalhelpquestions,etc.Tosubscribeorunsubscribetothemailinglist,sendarequesttotheadministrativeaddress:@exampleInternet:supercite-request@@python.orgUUCP:uunet!python.org!supercite-request@endexamplePleasebesuretoincludethemostreliableandshortest(preferablyInternet)addressbacktoyou.Topostarticlestothelist,sendyourmessagetothisaddress(youdonotneedtobeamembertopost,butbesuretoindicatethisinyourarticleorrepliesmaynotbeCC'dtoyou):@exampleInternet:supercite@@python.orgUUCP:uunet!python.org!supercite@endexampleIfyouaresendingbugreports,theyshouldgotothefollowingaddress,but@emph{please}!usethecommand@code{sc-submit-bug-report}sinceitwillbemucheasierformetoduplicateyourproblemifyoudoso.Itwillsetupamailbufferautomaticallywiththisaddressonthe@samp{To:@:}line:@exampleInternet:supercite-help@@python.orgUUCP:uunet!python.org!supercite-help@endexample@nodeConceptIndex,CommandIndex,TheSuperciteMailingList,Top@commentnode-name,next,previous,up@unnumberedConceptIndex@printindexcp@nodeCommandIndex,KeyIndex,ConceptIndex,Top@commentnode-name,next,previous,up@unnumberedCommandIndex@ifinfo@endifinfoSinceallsupercitecommandsareprependedwiththestring``@code{sc-}'',eachappearsunderits@code{sc-}@var{command}nameandits@var{command}name.@iftex@sp2@endiftex@printindexfn@nodeKeyIndex,VariableIndex,CommandIndex,Top@commentnode-name,next,previous,up@unnumberedKeyIndex@printindexky@nodeVariableIndex,,KeyIndex,Top@commentnode-name,next,previous,up@unnumberedVariableIndex@ifinfo@endifinfoSinceallsupercitevariablesareprependedwiththestring``@code{sc-}'',eachappearsunderits@code{sc-}@var{variable}nameandits@var{variable}name.@iftex@sp2@endiftex@printindexvr@summarycontents@contents@bye