X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/cce7d53002e8abc346b67ea4100507b0e7c4d68e..ddc412646dbcc51032cf438064d5eb4c8dded906:/doc/misc/sc.texi diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index 8853192af0..95b011cbd7 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -14,7 +14,7 @@ This document describes Supercite, an Emacs package for citing and attributing replies to mail and news messages. -Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001--2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -25,8 +25,7 @@ and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' +modify this GNU manual.'' @end quotation @end copying @@ -52,11 +51,10 @@ developing GNU and promoting software freedom.'' @contents @ifnottex -@node Top, Introduction, (dir), (dir) +@node Top @top Supercite -@comment node-name, next, previous, up -@insertcopying +@insertcopying The manual is divided into the following chapters. @@ -64,13 +62,13 @@ into the following chapters. @menu * Introduction:: * Citations:: +* Information Keys and the Info Alist:: +* Reference Headers:: * Getting Connected:: * Replying and Yanking:: * Selecting an Attribution:: * Configuring the Citation Engine:: * Post-yank Formatting Commands:: -* Information Keys and the Info Alist:: -* Reference Headers:: * Hints to MUA Authors:: * Thanks and History:: @@ -83,7 +81,7 @@ into the following chapters. @end ifnottex -@node Introduction, Usage Overview, Top, Top +@node Introduction @chapter Introduction Supercite is a GNU Emacs package written entirely in Emacs Lisp. It @@ -96,13 +94,11 @@ of composing replies to both USENET network news and electronic mail. The preferred way to spell Supercite is with a capital @samp{S}, lowercase @samp{upercite}. -@ifinfo @menu * Usage Overview:: * What Supercite Does Not Do:: * What Supercite Does:: @end menu -@end ifinfo @cindex MUA @cindex NUA @@ -113,17 +109,17 @@ formatting styles are available in that reply buffer until the reply is sent. Supercite is re-initialized in each new reply buffer. -@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction +@node Usage Overview +@section Usage Overview @kindex r @kindex f @kindex C-c C-y @cindex yank @cindex cite, citing @cindex attribute, attributing -@section Usage Overview Typical usage is as follows. You want to reply or followup to a message -in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} +in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} (i.e., ``forward'') to begin composing the reply. In response, the MUA will create a reply buffer and initialize the outgoing mail headers appropriately. The body of the reply will usually be empty at this @@ -138,7 +134,7 @@ special text tag. Most MUAs provide some default style of citing; by using Supercite you gain a wider flexibility in the look and style of citations. Supercite's only job is to cite the original message. -@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction +@node What Supercite Does Not Do @section What Supercite Doesn't Do Because of this clear division of labor, there are useful features which @@ -159,16 +155,16 @@ know anything about the meaning of these headers, and never ventures outside the designated region. @xref{Hints to MUA Authors}, for more details.@refill -@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction -@findex sc-cite-original +@node What Supercite Does @section What Supercite Does +@findex sc-cite-original Supercite is invoked for the first time on a reply buffer via your MUA's reply or forward command. This command will actually perform citations by calling a hook variable to which Supercite's top-level function @code{sc-cite-original} has been added. When @code{sc-cite-original} is executed, the original message must be set up in a very specific way, -but this is handled automatically by the MUA. @xref{Hints to MUA +but this is handled automatically by the MUA@. @xref{Hints to MUA Authors}.@refill @cindex info alist @@ -204,8 +200,8 @@ When the original message is cited by @code{sc-cite-original}, it will (optionally) be filled by Supercite. However, if you manually edit the cited text and want to re-fill it, you must use an add-on package such as @cite{filladapt} or @cite{gin-mode}. These packages can recognize -Supercited text and will fill them appropriately. Emacs' built-in -filling routines, e.g@. @code{fill-paragraph}, do not recognize cited +Supercited text and will fill them appropriately. Emacs's built-in +filling routines, e.g., @code{fill-paragraph}, do not recognize cited text and will not re-fill them properly because it cannot guess the @code{fill-prefix} being used. @xref{Post-yank Formatting Commands}, for details.@refill @@ -216,15 +212,15 @@ beautifications on the cited original text, maintaining consistent and informative citations throughout. Supercite tries to be as configurable as possible to allow for a wide range of personalized citation styles, but it is also immediately useful with the default configuration, once -it has been properly connected to your MUA. @xref{Getting Connected}, +it has been properly connected to your MUA@. @xref{Getting Connected}, for more details.@refill -@node Citations, Citation Elements, What Supercite Does, Top +@node Citations +@chapter Citations @cindex nested citations @cindex citation -@chapter Citations -A @dfn{citation} is the acknowledgement of the original author of a mail +A @dfn{citation} is the acknowledgment of the original author of a mail message in the body of the reply. There are two basic citation styles which Supercite supports. The first, called @dfn{nested citations} is an anonymous form of citation; in other words, an indication is made @@ -243,12 +239,10 @@ citations after multiple replies: And that's what I think too. @end example -@ifinfo @menu * Citation Elements:: * Recognizing Citations:: @end menu -@end ifinfo Note that multiple inclusions of the original messages result in a nesting of the @samp{@code{>}} characters. This can sometimes be quite @@ -284,9 +278,9 @@ non-nested citations are used. When non-@code{nil}, nested citations are used. -@node Citation Elements, Recognizing Citations, Citations, Citations -@cindex citation string +@node Citation Elements @section Citation Elements +@cindex citation string @dfn{Citation strings} are composed of one or more elements. Non-nested citations are composed of four elements, three of which are directly @@ -339,7 +333,7 @@ of the same elements, sans the attribution string. Supercite is smart enough to not put additional spaces between citation delimiters for multi-level nested citations. -@node Recognizing Citations, Getting Connected, Citation Elements, Citations +@node Recognizing Citations @section Recognizing Citations Supercite also recognizes citations in the original article, and can @@ -383,17 +377,17 @@ non-nested citation roots. It is important to remember that if you change @code{sc-citation-root-regexp} you should always also change @code{sc-citation-nonnested-root-regexp}.@refill -@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top +@node Information Keys and the Info Alist +@chapter Information Keys and the Info Alist @cindex information keys @cindex Info Alist @cindex information extracted from mail fields @findex sc-mail-field @findex mail-field (sc-) -@chapter Information Keys and the Info Alist @dfn{Mail header information keys} are nuggets of information that Supercite extracts from the various mail headers of the original -message, placed in the reply buffer by the MUA. Information is kept in +message, placed in the reply buffer by the MUA@. Information is kept in the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in various places within Supercite, such as in header rewrite functions and attribution selection. Other bits of data, composed and created by @@ -493,9 +487,9 @@ If the author's name has more than one middle name, they will appear as info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, @dots{}). @xref{Selecting an Attribution}.@refill -@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top -@cindex reference headers +@node Reference Headers @chapter Reference Headers +@cindex reference headers Supercite will insert an informative @dfn{reference header} at the beginning of the cited body of text, which display more detail about the @@ -507,12 +501,10 @@ name, email address, the original article's subject, etc. In fact any information contained in the info alist can be inserted into a reference header. -@ifinfo @menu * The Built-in Header Rewrite Functions:: * Electric References:: @end menu -@end ifinfo @cindex header rewrite functions @vindex sc-rewrite-header-list @@ -534,12 +526,12 @@ functions. The one it uses is defined in the variable integer which is an index into the @code{sc-rewrite-header-list}, beginning at zero. -@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers -@cindex header rewrite functions, built-in +@node The Built-in Header Rewrite Functions @section The Built-in Header Rewrite Functions +@cindex header rewrite functions, built-in Below are examples of the various built-in header rewrite functions. -Please note the following:@: first, the text which appears in the +Please note the following: first, the text which appears in the examples below as @var{infokey} indicates that the corresponding value of the info key from the info alist will be inserted there. (@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} @@ -613,9 +605,9 @@ line after the @code{mail-header-separator} line will be removed. @code{>>>>> see @var{references} for more details} @end table -@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers -@cindex electric references +@node Electric References @section Electric References +@cindex electric references By default, when Supercite cites the original message for the first time, it just goes ahead and inserts the reference header indexed by @@ -709,10 +701,9 @@ Exit from electric reference mode without inserting the current header. Supercite will execute the hook @code{sc-electric-mode-hook} before entering electric reference mode. -@node Getting Connected, Replying and Yanking, Recognizing Citations, Top -@cindex citation interface specification +@node Getting Connected @chapter Getting Connected - +@cindex citation interface specification @vindex mail-citation-hook @cindex .emacs file @@ -786,14 +777,13 @@ pertaining to the MUAs you are using. One final note. After Supercite is loaded into your Emacs session, it runs the hook @code{sc-load-hook}. You can put any customizations into this hook since it is only run once. This will not work, however, if -your Emacs maintainer has put Supercite into your dumped Emacs' image. +your Emacs maintainer has put Supercite into your dumped Emacs image. In that case, you can use the @code{sc-pre-hook} variable, but this will get executed every time @code{sc-cite-original} is called. @xref{Reply Buffer Initialization}.@refill -@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top +@node Replying and Yanking @chapter Replying and Yanking -@ifinfo This chapter explains what happens when you reply and yank an original message from an MUA. @@ -802,11 +792,11 @@ message from an MUA. * Reply Buffer Initialization:: * Filling Cited Text:: @end menu -@end ifinfo -@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking + +@node Reply Buffer Initialization +@section Reply Buffer Initialization @findex sc-cite-original @findex cite-original (sc-) -@section Reply Buffer Initialization Executing @code{sc-cite-original} performs the following steps as it initializes the reply buffer: @@ -960,7 +950,8 @@ for completeness and backward compatibility. Perhaps it could be used to reset certain variables set in @code{sc-pre-hook}.@refill @end enumerate -@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking +@node Filling Cited Text +@section Filling Cited Text @cindex filling paragraphs @vindex sc-auto-fill-region-p @vindex auto-fill-region-p (sc-) @@ -970,7 +961,6 @@ reset certain variables set in @code{sc-pre-hook}.@refill @findex setup-filladapt (sc-) @vindex sc-load-hook @vindex load-hook (sc-) -@section Filling Cited Text Supercite will automatically fill newly cited text from the original message unless the variable @code{sc-auto-fill-region-p} has a @@ -1008,7 +998,7 @@ fill each cited paragraph in the reply buffer. I usually run with both these variables containing their default values. When Supercite's automatic filling breaks on a particular message, I -will use Emacs' undo feature to undo back before the citation was +will use Emacs's undo feature to undo back before the citation was applied to the original message. Then I'll toggle the variables and manually cite those paragraphs that I don't want to fill or collapse whitespace on. @xref{Variable Toggling Shortcuts}.@refill @@ -1039,11 +1029,11 @@ have been widespread complaints on the net about mail and news messages containing lines greater than about 72 characters. So the default is to fill cited text. -@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top +@node Selecting an Attribution +@chapter Selecting an Attribution @cindex attribution list @vindex sc-preferred-attribution-list @vindex preferred-attribution-list (sc-) -@chapter Selecting an Attribution As you know, the attribution string is the part of the author's name that will be used to composed a non-nested citation string. Supercite @@ -1055,15 +1045,13 @@ element in the attribution alist is a key-value pair containing such information as the author's first name, middle names, and last name, the author's initials, and the author's email terminus. -@ifinfo @menu * Attribution Preferences:: * Anonymous Attributions:: * Author Names:: @end menu -@end ifinfo -@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution +@node Attribution Preferences @section Attribution Preferences When you cite an original message, you can tell Supercite which part of @@ -1143,8 +1131,8 @@ Each element in this list contains lists of the following form: @example @group -(@var{infokey} ((@var{regexp} @. @var{attribution}) - (@var{regexp} @. @var{attribution}) +(@var{infokey} ((@var{regexp} . @var{attribution}) + (@var{regexp} . @var{attribution}) (@dots{}))) @end group @end example @@ -1165,12 +1153,12 @@ what nickname they would prefer to use, and you can set up this list to match against a specific mail field, e.g., @samp{From:@:}, allowing you to cite your friend's message with the appropriate attribution. -@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution +@node Anonymous Attributions +@section Anonymous Attributions @vindex sc-default-author-name @vindex default-author-name (sc-) @vindex sc-default-attribution @vindex default-attribution (sc-) -@section Anonymous Attributions When the author's name cannot be found in the @samp{From:@:} mail header, a fallback author name and attribution string must be supplied. @@ -1251,12 +1239,12 @@ post-selection hook, the local variables @code{attribution} and variables in your hook functions, you change the attribution and citation strings used by Supercite. One possible use of this would be to override any automatically derived attribution string when it is only -one character long; e.g. you prefer to use @code{"initials"} but the +one character long; e.g., you prefer to use @code{"initials"} but the author only has one name.@refill -@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution -@cindex author names +@node Author Names @section Author Names +@cindex author names Supercite employs a number of heuristics to decipher the author's name based on value of the @samp{From:@:} mail field of the original message. @@ -1295,7 +1283,7 @@ is used for this purpose. As implied by its name, this variable is an association list, where each element is a cons cell of the form: @example -(@var{regexp} @. @var{position}) +(@var{regexp} . @var{position}) @end example @noindent @@ -1306,7 +1294,7 @@ Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, @code{sc-name-filter-alist} would have an entry such as: @example -("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0) +("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" . 0) @end example @noindent @@ -1316,11 +1304,11 @@ The position indicator is an integer, or one of the two special symbols word in the name field, while @code{any} matches against every word in the name field. -@node Configuring the Citation Engine, Using Regi, Author Names, Top +@node Configuring the Citation Engine +@chapter Configuring the Citation Engine @cindex Regi @cindex frames (Regi) @cindex entries (Regi) -@chapter Configuring the Citation Engine At the heart of Supercite is a regular expression interpreting engine called @dfn{Regi}. Regi operates by interpreting a data structure @@ -1333,12 +1321,10 @@ can be transformed in an @emph{awk}-like manner. Regi is used throughout Supercite, from mail header information extraction, to header nuking, to citing text. -@ifinfo @menu * Using Regi:: * Frames You Can Customize:: @end menu -@end ifinfo While the details of Regi are discussed below (@pxref{Using Regi}), only those who wish to customize certain aspects of Supercite need concern @@ -1354,11 +1340,11 @@ Supercite to recognize such things as uuencoded messages or C code and cite or fill those differently than normal text. None of this is currently part of Supercite, but contributions are welcome! -@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine +@node Using Regi +@section Using Regi @findex regi-interpret @findex eval @findex looking-at -@section Using Regi Regi works by interpreting frames with the function @code{regi-interpret}. A frame is a list of arbitrary size where each @@ -1452,9 +1438,9 @@ The current frame being interpreted. The current frame entry being interpreted. @end table -@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine -@vindex sc-nuke-mail-header +@node Frames You Can Customize @section Frames You Can Customize +@vindex sc-nuke-mail-header As mentioned earlier, Supercite uses various frames to perform certain jobs such as mail header information extraction and mail header @@ -1493,14 +1479,14 @@ recognizing specific alternative forms. @vindex sc-cite-frame-alist @vindex sc-uncite-frame-alist @vindex sc-recite-frame-alist -For each of the actions -- citing, unciting, and reciting -- an alist is +For each of the actions---citing, unciting, and reciting---an alist is consulted to find the frame to use (@code{sc-cite-frame-alist}, @code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} respectively). These frames can contain alists of the form: @example -((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) - (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) +((@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{}) + (@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{}) (@dots{})) @end example @@ -1516,11 +1502,11 @@ When Supercite is about to cite, uncite, or recite a region, it consults the appropriate alist and attempts to find a frame to use. If one is not found from the alist, then the appropriate default frame is used. -@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top +@node Post-yank Formatting Commands +@chapter Post-yank Formatting Commands @vindex sc-mode-map-prefix @vindex mode-map-prefix (sc-) @kindex C-c C-p -@chapter Post-yank Formatting Commands Once the original message has been yanked into the reply buffer, and @code{sc-cite-original} has had a chance to do its thing, a number of @@ -1536,7 +1522,6 @@ but unfortunately the best general solution so far. In the rest of this chapter, we'll assume you've installed Supercite's keymap on the default prefix.@refill -@ifinfo @menu * Citing Commands:: * Insertion Commands:: @@ -1544,11 +1529,10 @@ prefix.@refill * Mail Field Commands:: * Miscellaneous Commands:: @end menu -@end ifinfo -@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands -@vindex sc-cite-region-limit +@node Citing Commands @section Commands to Manually Cite, Recite, and Uncite +@vindex sc-cite-region-limit Probably the three most common post-yank formatting operations that you will perform will be the manual citing, reciting, and unciting of @@ -1608,7 +1592,7 @@ Supercite will always ask you to confirm the attribution when reciting a region, regardless of the value of @code{sc-confirm-always-p}. @end table -@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands +@node Insertion Commands @section Insertion Commands These two functions insert various strings into the reply buffer. @@ -1638,9 +1622,9 @@ Inserts the current citation string at the beginning of the line that an error and will not cite the line. @end table -@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands -@cindex toggling variables +@node Variable Toggling Shortcuts @section Variable Toggling Shortcuts +@cindex toggling variables Supercite defines a number of commands that make it easier for you to toggle and set various Supercite variables as you are editing the reply @@ -1688,7 +1672,7 @@ Toggles the variable @code{sc-fixup-whitespace-p}. @findex set-variable The following commands let you set the value of multi-value variables, -in the same way that Emacs' @code{set-variable} does: +in the same way that Emacs's @code{set-variable} does: @table @kbd @item C-c C-p C-t a @@ -1718,7 +1702,7 @@ Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) brings up a Help message on the toggling keymap. -@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands +@node Mail Field Commands @section Mail Field Commands These commands allow you to view, modify, add, and delete various bits @@ -1768,7 +1752,7 @@ message author. Note that unless an error during processing occurs, any old information is lost.@refill @end table -@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands +@node Miscellaneous Commands @section Miscellaneous Commands @table @asis @@ -1777,12 +1761,12 @@ old information is lost.@refill @findex open-line @kindex C-c C-p o @item @code{sc-open-line} (@kbd{C-c C-p o}) -Similar to Emacs' standard @code{open-line} commands, but inserts the +Similar to Emacs's standard @code{open-line} commands, but inserts the citation string in front of the new line. As with @code{open-line}, an optional numeric argument inserts that many new lines.@refill @end table -@node Hints to MUA Authors, Thanks and History, Electric References, Top +@node Hints to MUA Authors @chapter Hints to MUA Authors In June of 1989, some discussion was held between the various MUA @@ -1834,7 +1818,7 @@ steps: @item Insert the original message, including the mail headers into the reply buffer. At this point you should not modify the raw text in any way -(except for any necessary decoding, e.g. of quoted-printable text), and +(except for any necessary decoding, e.g., of quoted-printable text), and you should place all the original headers into the body of the reply. This means that many of the mail headers will be duplicated, one copy above the @code{mail-header-separator} line and one copy below, however @@ -1864,7 +1848,7 @@ need only add @code{sc-cite-original} to this list of hooks using If you do all this your MUA will join the ranks of those that conform to this interface ``out of the box.'' -@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top +@node Thanks and History @chapter Thanks and History The Supercite package was derived from its predecessor Superyank 1.11 @@ -1877,7 +1861,7 @@ been continuously added through the comments and suggestions of the Supercite mailing list participants. With version 3, Supercite underwent an almost complete rewrite, -benefitting in a number of ways, including vast improvements in the +benefiting in a number of ways, including vast improvements in the speed of performance, a big reduction in size of the code and in the use of Emacs resources, and a much cleaner and flexible internal architecture. Most of this work was internal and not of very great @@ -1901,19 +1885,17 @@ All who have helped and contributed have been greatly appreciated. Supercite was written by Barry Warsaw. -@node GNU Free Documentation License, Concept Index, Thanks and History, Top +@node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi -@node Concept Index, Command Index, GNU Free Documentation License, Top +@node Concept Index @unnumbered Concept Index @printindex cp -@node Command Index, Key Index, Concept Index, Top +@node Command Index @unnumbered Command Index -@ifinfo -@end ifinfo Since all supercite commands are prepended with the string ``@code{sc-}'', each appears under its @code{sc-}@var{command} name and its @var{command} name. @@ -1922,15 +1904,13 @@ its @var{command} name. @end iftex @printindex fn -@node Key Index, Variable Index, Command Index, Top +@node Key Index @unnumbered Key Index @printindex ky -@node Variable Index, , Key Index, Top +@node Variable Index @unnumbered Variable Index -@ifinfo -@end ifinfo Since all supercite variables are prepended with the string ``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and its @var{variable} name.