diff options
| author | Glenn Morris | 2008-02-27 04:42:33 +0000 |
|---|---|---|
| committer | Glenn Morris | 2008-02-27 04:42:33 +0000 |
| commit | 52151df0ac7a4b0c900df93f4711cc72bbf6d737 (patch) | |
| tree | d6ee0f37e3174722a8acc05218b62f07f3176ab2 | |
| parent | 34b5f6df51ef655c4719ce2f0bf57440b21a7c66 (diff) | |
| download | emacs-52151df0ac7a4b0c900df93f4711cc72bbf6d737.tar.gz emacs-52151df0ac7a4b0c900df93f4711cc72bbf6d737.zip | |
Remove a lot of old and obsolete info.
(titlepage): Simplify.
(Emacs 19 MUAs, Emacs 18 MUAs, MH-E with any Emacsen)
(VM with any Emacsen, GNEWS with any Emacsen)
(Overloading for Non-conforming MUAs, Version 3 Changes)
(The Supercite Mailing List): Delete nodes.
(Introduction): Remove info about old packages.
(Getting Connected): Simplify. Remove info about old packages.
(Citing Commands): Delete Emacs 19 info.
(Hints to MUA Authors): Simplify.
(Thanks and History): Merge in some info from the deleted node
"Version 3 Changes".
| -rw-r--r-- | doc/misc/ChangeLog | 15 | ||||
| -rw-r--r-- | doc/misc/sc.texi | 716 |
2 files changed, 82 insertions, 649 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index b611cb324c9..e9f3ada1c02 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog | |||
| @@ -1,3 +1,18 @@ | |||
| 1 | 2008-02-27 Glenn Morris <rgm@gnu.org> | ||
| 2 | |||
| 3 | * sc.texi: Remove a lot of old and obsolete info. | ||
| 4 | (titlepage): Simplify. | ||
| 5 | (Emacs 19 MUAs, Emacs 18 MUAs, MH-E with any Emacsen) | ||
| 6 | (VM with any Emacsen, GNEWS with any Emacsen) | ||
| 7 | (Overloading for Non-conforming MUAs, Version 3 Changes) | ||
| 8 | (The Supercite Mailing List): Delete nodes. | ||
| 9 | (Introduction): Remove info about old packages. | ||
| 10 | (Getting Connected): Simplify. Remove info about old packages. | ||
| 11 | (Citing Commands): Delete Emacs 19 info. | ||
| 12 | (Hints to MUA Authors): Simplify. | ||
| 13 | (Thanks and History): Merge in some info from the deleted node | ||
| 14 | "Version 3 Changes". | ||
| 15 | |||
| 1 | 2008-02-05 Juanma Barranquero <lekktu@gmail.com> | 16 | 2008-02-05 Juanma Barranquero <lekktu@gmail.com> |
| 2 | 17 | ||
| 3 | * org.texi (Setting tags, In-buffer settings): | 18 | * org.texi (Setting tags, In-buffer settings): |
diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index f98b63b628e..e23e9e4ea58 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi | |||
| @@ -2,7 +2,7 @@ | |||
| 2 | @comment 3.48 | 2 | @comment 3.48 |
| 3 | @comment %**start of header (This is for running Texinfo on a region.) | 3 | @comment %**start of header (This is for running Texinfo on a region.) |
| 4 | @setfilename ../../info/sc | 4 | @setfilename ../../info/sc |
| 5 | @settitle Supercite Version 3.1 User's Manual | 5 | @settitle Supercite User's Manual |
| 6 | @iftex | 6 | @iftex |
| 7 | @finalout | 7 | @finalout |
| 8 | @end iftex | 8 | @end iftex |
| @@ -11,9 +11,8 @@ | |||
| 11 | @comment %**end of header (This is for running Texinfo on a region.) | 11 | @comment %**end of header (This is for running Texinfo on a region.) |
| 12 | 12 | ||
| 13 | @copying | 13 | @copying |
| 14 | This document describes the Supercite Version 3.1 package for citing and | 14 | This document describes Supercite, an Emacs package for citing and |
| 15 | attributing the replies for various GNU Emacs mail and news reading | 15 | attributing replies to mail and news messages. |
| 16 | subsystems. | ||
| 17 | 16 | ||
| 18 | Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, | 17 | Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, |
| 19 | 2005, 2006, 2007, 2008 Free Software Foundation, Inc. | 18 | 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
| @@ -47,17 +46,10 @@ license to the document, as described in section 6 of the license. | |||
| 47 | @end direntry | 46 | @end direntry |
| 48 | 47 | ||
| 49 | @titlepage | 48 | @titlepage |
| 50 | @sp 6 | 49 | @title Supercite User's Manual |
| 51 | @center @titlefont{Supercite User's Manual} | 50 | @subtitle cite and attribute mail and |
| 52 | @sp 2 | 51 | @subtitle news, in flexible ways |
| 53 | @center @titlefont{Supercite Version 3.1} | 52 | |
| 54 | @sp 4 | ||
| 55 | @center Manual Revision: 3.48 | ||
| 56 | @center April 2007 | ||
| 57 | @sp 5 | ||
| 58 | @center Barry A@. Warsaw | ||
| 59 | @center @t{bwarsaw@@cen.com} | ||
| 60 | @center @t{@dots{}!uunet!cen.com!bwarsaw} | ||
| 61 | @page | 53 | @page |
| 62 | @vskip 0pt plus 1filll | 54 | @vskip 0pt plus 1filll |
| 63 | @insertcopying | 55 | @insertcopying |
| @@ -67,9 +59,9 @@ license to the document, as described in section 6 of the license. | |||
| 67 | @node Top, Introduction, (dir), (dir) | 59 | @node Top, Introduction, (dir), (dir) |
| 68 | @comment node-name, next, previous, up | 60 | @comment node-name, next, previous, up |
| 69 | 61 | ||
| 70 | This document describes the Supercite Version 3.1 package for citing and | 62 | This document describes Supercite, an Emacs package for citing and |
| 71 | attributing the replies for various GNU Emacs mail and news reading | 63 | attributing replies to mail and news messages. The manual is divided |
| 72 | subsystems. The manual is divided into the following chapters. | 64 | into the following chapters. |
| 73 | 65 | ||
| 74 | @menu | 66 | @menu |
| 75 | * Introduction:: | 67 | * Introduction:: |
| @@ -82,9 +74,7 @@ subsystems. The manual is divided into the following chapters. | |||
| 82 | * Information Keys and the Info Alist:: | 74 | * Information Keys and the Info Alist:: |
| 83 | * Reference Headers:: | 75 | * Reference Headers:: |
| 84 | * Hints to MUA Authors:: | 76 | * Hints to MUA Authors:: |
| 85 | * Version 3 Changes:: | ||
| 86 | * Thanks and History:: | 77 | * Thanks and History:: |
| 87 | * The Supercite Mailing List:: | ||
| 88 | 78 | ||
| 89 | * GNU Free Documentation License:: | 79 | * GNU Free Documentation License:: |
| 90 | * Concept Index:: | 80 | * Concept Index:: |
| @@ -96,22 +86,17 @@ subsystems. The manual is divided into the following chapters. | |||
| 96 | 86 | ||
| 97 | 87 | ||
| 98 | @node Introduction, Usage Overview, Top, Top | 88 | @node Introduction, Usage Overview, Top, Top |
| 99 | @comment node-name, next, previous, up | ||
| 100 | @chapter Introduction | 89 | @chapter Introduction |
| 101 | @ifinfo | ||
| 102 | 90 | ||
| 103 | @end ifinfo | 91 | Supercite is a GNU Emacs package written entirely in Emacs Lisp. It |
| 104 | Supercite version 3.1 is a GNU Emacs package written entirely in Emacs | 92 | interfaces to most of the commonly used Emacs mail user agents |
| 105 | Lisp. It interfaces to most of the commonly used Emacs mail user agents | ||
| 106 | (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides | 93 | (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides |
| 107 | sophisticated facilities for the citing and attributing of message | 94 | sophisticated facilities for the citing and attributing of message |
| 108 | replies. Supercite has a very specific and limited role in the process | 95 | replies. Supercite has a very specific and limited role in the process |
| 109 | of composing replies to both USENET network news and electronic mail. | 96 | of composing replies to both USENET network news and electronic mail. |
| 110 | 97 | ||
| 111 | The preferred way to spell Supercite is with a capital @samp{S}, | 98 | The preferred way to spell Supercite is with a capital @samp{S}, |
| 112 | lowercase @samp{upercite}. There are a few alternate spellings out there | 99 | lowercase @samp{upercite}. |
| 113 | and I won't be terribly offended if you use them. People often ask | ||
| 114 | though@dots{} | ||
| 115 | 100 | ||
| 116 | @ifinfo | 101 | @ifinfo |
| 117 | @menu | 102 | @menu |
| @@ -124,49 +109,21 @@ though@dots{} | |||
| 124 | @cindex MUA | 109 | @cindex MUA |
| 125 | @cindex NUA | 110 | @cindex NUA |
| 126 | Supercite is only useful in conjunction with MUAs and NUAs such as VM, | 111 | Supercite is only useful in conjunction with MUAs and NUAs such as VM, |
| 127 | GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs). | 112 | Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a |
| 128 | Supercite is typically called by the MUA after a reply buffer has been | 113 | reply buffer has been setup. Thereafter, Supercite's many commands and |
| 129 | setup. Thereafter, Supercite's many commands and formatting styles are | 114 | formatting styles are available in that reply buffer until the reply is |
| 130 | available in that reply buffer until the reply is sent. Supercite is | 115 | sent. Supercite is re-initialized in each new reply buffer. |
| 131 | re-initialized in each new reply buffer. | ||
| 132 | |||
| 133 | Supercite is currently at major revision 3.1, and is known to work in the | ||
| 134 | following environments: | ||
| 135 | |||
| 136 | @table @asis | ||
| 137 | @item Emacs versions: | ||
| 138 | GNU Emacs 18.57 through 18.59, all Emacs 19, | ||
| 139 | all current Lucid Emacs, and Epoch 4.@refill | ||
| 140 | |||
| 141 | @item MUAs: | ||
| 142 | VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and | ||
| 143 | beyond, PCMAIL.@refill | ||
| 144 | |||
| 145 | @item NUAs: | ||
| 146 | RNEWS, GNUS 3.12 and beyond, GNEWS.@refill | ||
| 147 | |||
| 148 | @end table | ||
| 149 | For systems with version numbers, all known subsequent versions also | ||
| 150 | work with Supercite. For those systems without version numbers, | ||
| 151 | Supercite probably works with any recently released version. Note that | ||
| 152 | only some of these systems will work with Supercite ``out of the box.'' | ||
| 153 | All others must overload interfacing routines to supply the necessary | ||
| 154 | glue. @xref{Getting Connected}, for more details.@refill | ||
| 155 | 116 | ||
| 156 | 117 | ||
| 157 | @node Usage Overview, What Supercite Does Not Do, Introduction, Introduction | 118 | @node Usage Overview, What Supercite Does Not Do, Introduction, Introduction |
| 158 | @comment node-name, next, previous, up | ||
| 159 | @kindex r | 119 | @kindex r |
| 160 | @kindex f | 120 | @kindex f |
| 161 | @kindex C-c C-y | 121 | @kindex C-c C-y |
| 162 | @cindex yank | 122 | @cindex yank |
| 163 | @cindex cite, citing | 123 | @cindex cite, citing |
| 164 | @cindex attribute, attributing | 124 | @cindex attribute, attributing |
| 165 | @comment | ||
| 166 | @section Usage Overview | 125 | @section Usage Overview |
| 167 | @ifinfo | ||
| 168 | 126 | ||
| 169 | @end ifinfo | ||
| 170 | Typical usage is as follows. You want to reply or followup to a message | 127 | Typical usage is as follows. You want to reply or followup to a message |
| 171 | in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} | 128 | in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} |
| 172 | (i.e., ``forward'') to begin composing the reply. In response, the MUA | 129 | (i.e., ``forward'') to begin composing the reply. In response, the MUA |
| @@ -184,11 +141,8 @@ using Supercite you gain a wider flexibility in the look and style of | |||
| 184 | citations. Supercite's only job is to cite the original message. | 141 | citations. Supercite's only job is to cite the original message. |
| 185 | 142 | ||
| 186 | @node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction | 143 | @node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction |
| 187 | @comment node-name, next, previous, up | ||
| 188 | @section What Supercite Doesn't Do | 144 | @section What Supercite Doesn't Do |
| 189 | @ifinfo | ||
| 190 | 145 | ||
| 191 | @end ifinfo | ||
| 192 | Because of this clear division of labor, there are useful features which | 146 | Because of this clear division of labor, there are useful features which |
| 193 | are the sole responsibility of the MUA, even though it might seem that | 147 | are the sole responsibility of the MUA, even though it might seem that |
| 194 | Supercite should provide them. For example, many people would like to | 148 | Supercite should provide them. For example, many people would like to |
| @@ -198,7 +152,6 @@ set up by the MUA, it is the MUA's responsibility to do partial yanking. | |||
| 198 | @xref{Reply Buffer Initialization}.@refill | 152 | @xref{Reply Buffer Initialization}.@refill |
| 199 | 153 | ||
| 200 | @vindex mail-header-separator | 154 | @vindex mail-header-separator |
| 201 | @comment | ||
| 202 | Another potentially useful thing would be for Supercite to set up the | 155 | Another potentially useful thing would be for Supercite to set up the |
| 203 | outgoing mail headers with information it gleans from the reply buffer. | 156 | outgoing mail headers with information it gleans from the reply buffer. |
| 204 | But by previously agreed upon convention, any text above the | 157 | But by previously agreed upon convention, any text above the |
| @@ -209,12 +162,9 @@ outside the designated region. @xref{Hints to MUA Authors}, for more | |||
| 209 | details.@refill | 162 | details.@refill |
| 210 | 163 | ||
| 211 | @node What Supercite Does, Citations, What Supercite Does Not Do, Introduction | 164 | @node What Supercite Does, Citations, What Supercite Does Not Do, Introduction |
| 212 | @comment node-name, next, previous, up | ||
| 213 | @findex sc-cite-original | 165 | @findex sc-cite-original |
| 214 | @section What Supercite Does | 166 | @section What Supercite Does |
| 215 | @ifinfo | ||
| 216 | 167 | ||
| 217 | @end ifinfo | ||
| 218 | Supercite is invoked for the first time on a reply buffer via your MUA's | 168 | Supercite is invoked for the first time on a reply buffer via your MUA's |
| 219 | reply or forward command. This command will actually perform citations | 169 | reply or forward command. This command will actually perform citations |
| 220 | by calling a hook variable to which Supercite's top-level function | 170 | by calling a hook variable to which Supercite's top-level function |
| @@ -252,7 +202,6 @@ display the minor mode string @samp{SC}. | |||
| 252 | @cindex gin-mode | 202 | @cindex gin-mode |
| 253 | @vindex fill-prefix | 203 | @vindex fill-prefix |
| 254 | @findex fill-paragraph | 204 | @findex fill-paragraph |
| 255 | @comment | ||
| 256 | When the original message is cited by @code{sc-cite-original}, it will | 205 | When the original message is cited by @code{sc-cite-original}, it will |
| 257 | (optionally) be filled by Supercite. However, if you manually edit the | 206 | (optionally) be filled by Supercite. However, if you manually edit the |
| 258 | cited text and want to re-fill it, you must use an add-on package such | 207 | cited text and want to re-fill it, you must use an add-on package such |
| @@ -273,14 +222,10 @@ it has been properly connected to your MUA. @xref{Getting Connected}, | |||
| 273 | for more details.@refill | 222 | for more details.@refill |
| 274 | 223 | ||
| 275 | @node Citations, Citation Elements, What Supercite Does, Top | 224 | @node Citations, Citation Elements, What Supercite Does, Top |
| 276 | @comment node-name, next, previous, up | ||
| 277 | @cindex nested citations | 225 | @cindex nested citations |
| 278 | @cindex citation | 226 | @cindex citation |
| 279 | @comment | ||
| 280 | @chapter Citations | 227 | @chapter Citations |
| 281 | @ifinfo | ||
| 282 | 228 | ||
| 283 | @end ifinfo | ||
| 284 | A @dfn{citation} is the acknowledgement of the original author of a mail | 229 | A @dfn{citation} is the acknowledgement of the original author of a mail |
| 285 | message in the body of the reply. There are two basic citation styles | 230 | message in the body of the reply. There are two basic citation styles |
| 286 | which Supercite supports. The first, called @dfn{nested citations} is | 231 | which Supercite supports. The first, called @dfn{nested citations} is |
| @@ -342,13 +287,9 @@ are used. | |||
| 342 | 287 | ||
| 343 | 288 | ||
| 344 | @node Citation Elements, Recognizing Citations, Citations, Citations | 289 | @node Citation Elements, Recognizing Citations, Citations, Citations |
| 345 | @comment node-name, next, previous, up | ||
| 346 | @cindex citation string | 290 | @cindex citation string |
| 347 | @comment | ||
| 348 | @section Citation Elements | 291 | @section Citation Elements |
| 349 | @ifinfo | ||
| 350 | 292 | ||
| 351 | @end ifinfo | ||
| 352 | @dfn{Citation strings} are composed of one or more elements. Non-nested | 293 | @dfn{Citation strings} are composed of one or more elements. Non-nested |
| 353 | citations are composed of four elements, three of which are directly | 294 | citations are composed of four elements, three of which are directly |
| 354 | user definable. The elements are concatenated together, in this order: | 295 | user definable. The elements are concatenated together, in this order: |
| @@ -401,11 +342,8 @@ enough to not put additional spaces between citation delimiters for | |||
| 401 | multi-level nested citations. | 342 | multi-level nested citations. |
| 402 | 343 | ||
| 403 | @node Recognizing Citations, Getting Connected, Citation Elements, Citations | 344 | @node Recognizing Citations, Getting Connected, Citation Elements, Citations |
| 404 | @comment node-name, next, previous, up | ||
| 405 | @section Recognizing Citations | 345 | @section Recognizing Citations |
| 406 | @ifinfo | ||
| 407 | 346 | ||
| 408 | @end ifinfo | ||
| 409 | Supercite also recognizes citations in the original article, and can | 347 | Supercite also recognizes citations in the original article, and can |
| 410 | transform these already cited lines in a number of ways. This is how | 348 | transform these already cited lines in a number of ways. This is how |
| 411 | Supercite suppresses the multiple citing of non-nested citations. | 349 | Supercite suppresses the multiple citing of non-nested citations. |
| @@ -448,17 +386,13 @@ change @code{sc-citation-root-regexp} you should always also change | |||
| 448 | @code{sc-citation-nonnested-root-regexp}.@refill | 386 | @code{sc-citation-nonnested-root-regexp}.@refill |
| 449 | 387 | ||
| 450 | @node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top | 388 | @node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top |
| 451 | @comment node-name, next, previous, up | ||
| 452 | @cindex information keys | 389 | @cindex information keys |
| 453 | @cindex Info Alist | 390 | @cindex Info Alist |
| 454 | @cindex information extracted from mail fields | 391 | @cindex information extracted from mail fields |
| 455 | @findex sc-mail-field | 392 | @findex sc-mail-field |
| 456 | @findex mail-field (sc-) | 393 | @findex mail-field (sc-) |
| 457 | @comment | ||
| 458 | @chapter Information Keys and the Info Alist | 394 | @chapter Information Keys and the Info Alist |
| 459 | @ifinfo | ||
| 460 | 395 | ||
| 461 | @end ifinfo | ||
| 462 | @dfn{Mail header information keys} are nuggets of information that | 396 | @dfn{Mail header information keys} are nuggets of information that |
| 463 | Supercite extracts from the various mail headers of the original | 397 | Supercite extracts from the various mail headers of the original |
| 464 | message, placed in the reply buffer by the MUA. Information is kept in | 398 | message, placed in the reply buffer by the MUA. Information is kept in |
| @@ -562,12 +496,9 @@ info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, | |||
| 562 | @dots{}). @xref{Selecting an Attribution}.@refill | 496 | @dots{}). @xref{Selecting an Attribution}.@refill |
| 563 | 497 | ||
| 564 | @node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top | 498 | @node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top |
| 565 | @comment node-name, next, previous, up | ||
| 566 | @cindex reference headers | 499 | @cindex reference headers |
| 567 | @chapter Reference Headers | 500 | @chapter Reference Headers |
| 568 | @ifinfo | ||
| 569 | 501 | ||
| 570 | @end ifinfo | ||
| 571 | Supercite will insert an informative @dfn{reference header} at the | 502 | Supercite will insert an informative @dfn{reference header} at the |
| 572 | beginning of the cited body of text, which display more detail about the | 503 | beginning of the cited body of text, which display more detail about the |
| 573 | original article and provides the mapping between the attribution and | 504 | original article and provides the mapping between the attribution and |
| @@ -606,13 +537,9 @@ integer which is an index into the @code{sc-rewrite-header-list}, | |||
| 606 | beginning at zero. | 537 | beginning at zero. |
| 607 | 538 | ||
| 608 | @node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers | 539 | @node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers |
| 609 | @comment node-name, next, previous, up | ||
| 610 | @cindex header rewrite functions, built-in | 540 | @cindex header rewrite functions, built-in |
| 611 | @comment | ||
| 612 | @section The Built-in Header Rewrite Functions | 541 | @section The Built-in Header Rewrite Functions |
| 613 | @ifinfo | ||
| 614 | 542 | ||
| 615 | @end ifinfo | ||
| 616 | Below are examples of the various built-in header rewrite functions. | 543 | Below are examples of the various built-in header rewrite functions. |
| 617 | Please note the following:@: first, the text which appears in the | 544 | Please note the following:@: first, the text which appears in the |
| 618 | examples below as @var{infokey} indicates that the corresponding value | 545 | examples below as @var{infokey} indicates that the corresponding value |
| @@ -689,12 +616,9 @@ line after the @code{mail-header-separator} line will be removed. | |||
| 689 | @end table | 616 | @end table |
| 690 | 617 | ||
| 691 | @node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers | 618 | @node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers |
| 692 | @comment node-name, next, previous, up | ||
| 693 | @cindex electric references | 619 | @cindex electric references |
| 694 | @section Electric References | 620 | @section Electric References |
| 695 | @ifinfo | ||
| 696 | 621 | ||
| 697 | @end ifinfo | ||
| 698 | By default, when Supercite cites the original message for the first | 622 | By default, when Supercite cites the original message for the first |
| 699 | time, it just goes ahead and inserts the reference header indexed by | 623 | time, it just goes ahead and inserts the reference header indexed by |
| 700 | @code{sc-preferred-header-style}. However, you may want to select | 624 | @code{sc-preferred-header-style}. However, you may want to select |
| @@ -787,13 +711,22 @@ Exit from electric reference mode without inserting the current header. | |||
| 787 | Supercite will execute the hook @code{sc-electric-mode-hook} before | 711 | Supercite will execute the hook @code{sc-electric-mode-hook} before |
| 788 | entering electric reference mode. | 712 | entering electric reference mode. |
| 789 | 713 | ||
| 790 | @node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top | 714 | @node Getting Connected, Replying and Yanking, Recognizing Citations, Top |
| 791 | @comment node-name, next, previous, up | ||
| 792 | @cindex citation interface specification | 715 | @cindex citation interface specification |
| 793 | @chapter Getting Connected | 716 | @chapter Getting Connected |
| 794 | @ifinfo | ||
| 795 | 717 | ||
| 796 | @end ifinfo | 718 | |
| 719 | @vindex mail-citation-hook | ||
| 720 | @cindex .emacs file | ||
| 721 | In most cases, all that is necessary to begin using Supercite is to add | ||
| 722 | the following to @file{~.emacs}: | ||
| 723 | |||
| 724 | @example | ||
| 725 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 726 | @end example | ||
| 727 | |||
| 728 | @noindent For more details of the process, read on@dots{} | ||
| 729 | |||
| 797 | Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the | 730 | Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the |
| 798 | original message into the reply buffer. In reality, the citation of the | 731 | original message into the reply buffer. In reality, the citation of the |
| 799 | original message is performed via a call through a configurable hook | 732 | original message is performed via a call through a configurable hook |
| @@ -805,27 +738,12 @@ citation function to the hook, thereby giving the variable a | |||
| 805 | non-@code{nil} value, it tells the MUA to run the hook via | 738 | non-@code{nil} value, it tells the MUA to run the hook via |
| 806 | @code{run-hooks} instead of using the default citation.@refill | 739 | @code{run-hooks} instead of using the default citation.@refill |
| 807 | 740 | ||
| 808 | @ifinfo | ||
| 809 | @menu | ||
| 810 | * Emacs 19 MUAs:: | ||
| 811 | * Emacs 18 MUAs:: | ||
| 812 | * MH-E with any Emacsen:: | ||
| 813 | * VM with any Emacsen:: | ||
| 814 | * GNEWS with any Emacsen:: | ||
| 815 | * Overloading for Non-conforming MUAs:: | ||
| 816 | @end menu | ||
| 817 | @end ifinfo | ||
| 818 | |||
| 819 | Early in Supercite's development, the Supercite author, a few MUA | 741 | Early in Supercite's development, the Supercite author, a few MUA |
| 820 | authors, and some early Supercite users got together and agreed upon a | 742 | authors, and some early Supercite users got together and agreed upon a |
| 821 | standard interface between MUAs and citation packages (of which | 743 | standard interface between MUAs and citation packages (of which |
| 822 | Supercite is currently the only known add-on @t{:-)}. With the recent | 744 | Supercite is currently the only known add-on @t{:-)}. Supercite can |
| 823 | release of the Free Software Foundation's GNU Emacs 19, the interface | 745 | probably be used with most Emacs MUAs, with a greater or lesser degree |
| 824 | has undergone some modification and it is possible that not all MUAs | 746 | of effort. |
| 825 | support the new interface yet. Some support only the old interface and | ||
| 826 | some do not support the interface at all. Still, it is possible for all | ||
| 827 | known MUAs to use Supercite, and the following sections will outline the | ||
| 828 | procedures you need to follow. | ||
| 829 | 747 | ||
| 830 | To learn exactly how to connect Supercite to the software systems you | 748 | To learn exactly how to connect Supercite to the software systems you |
| 831 | are using, read the appropriate following sections. For details on the | 749 | are using, read the appropriate following sections. For details on the |
| @@ -840,14 +758,13 @@ interface specifications, or if you are writing or maintaining an MUA, | |||
| 840 | @findex submit-bug-report (sc-) | 758 | @findex submit-bug-report (sc-) |
| 841 | The first thing that everyone should do, regardless of the MUA you are | 759 | The first thing that everyone should do, regardless of the MUA you are |
| 842 | using is to set up Emacs so it will load Supercite at the appropriate | 760 | using is to set up Emacs so it will load Supercite at the appropriate |
| 843 | time. You can either dump Supercite into your Emacs binary (ask your | 761 | time. This happens automatically if Supercite is distributed with your |
| 844 | local Emacs guru how to do this if you don't know), or you can set up an | 762 | Emacs version. If not, you can set up an @dfn{autoload} for Supercite. |
| 845 | @dfn{autoload} for Supercite. To do the latter, put the following in | 763 | |
| 846 | your @file{.emacs} file: | 764 | To do the latter, put the following in your @file{.emacs} file: |
| 847 | 765 | ||
| 848 | @example | 766 | @example |
| 849 | (autoload 'sc-cite-original "supercite" "Supercite 3.1" t) | 767 | (autoload 'sc-cite-original "supercite" nil t) |
| 850 | (autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t) | ||
| 851 | @end example | 768 | @end example |
| 852 | 769 | ||
| 853 | @cindex point | 770 | @cindex point |
| @@ -857,7 +774,7 @@ designed to be run from the citation hook. It expects | |||
| 857 | @samp{point} and @samp{mark} to be set around the region to cite, and it | 774 | @samp{point} and @samp{mark} to be set around the region to cite, and it |
| 858 | expects the original article's mail headers to be present within this | 775 | expects the original article's mail headers to be present within this |
| 859 | region. Note that Supercite @emph{never} touches any text outside this | 776 | region. Note that Supercite @emph{never} touches any text outside this |
| 860 | region. Note further that for Emacs 19, the region need not be active | 777 | region. Note further that the region need not be active |
| 861 | for @code{sc-cite-original} to do its job. | 778 | for @code{sc-cite-original} to do its job. |
| 862 | @xref{Hints to MUA Authors}.@refill | 779 | @xref{Hints to MUA Authors}.@refill |
| 863 | 780 | ||
| @@ -878,284 +795,7 @@ In that case, you can use the @code{sc-pre-hook} variable, but this will | |||
| 878 | get executed every time @code{sc-cite-original} is called. @xref{Reply | 795 | get executed every time @code{sc-cite-original} is called. @xref{Reply |
| 879 | Buffer Initialization}.@refill | 796 | Buffer Initialization}.@refill |
| 880 | 797 | ||
| 881 | @node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected | 798 | @node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top |
| 882 | @comment node-name, next, previous, up | ||
| 883 | @vindex mail-citation-hook | ||
| 884 | @cindex .emacs file | ||
| 885 | @section GNUS, RMAIL, or RNEWS with any Emacs 19 | ||
| 886 | @ifinfo | ||
| 887 | |||
| 888 | @end ifinfo | ||
| 889 | These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's | ||
| 890 | built-in yanking facility, which provides the citing hook variable | ||
| 891 | @code{mail-citation-hook}. By default, this hook's value is @code{nil}, | ||
| 892 | but by adding the following to your @file{.emacs} file, you can tell | ||
| 893 | these MUAs to use Supercite to perform the citing of the original | ||
| 894 | message: | ||
| 895 | |||
| 896 | @example | ||
| 897 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 898 | @end example | ||
| 899 | |||
| 900 | GNUS users may also want to add the following bit of lisp as well. This | ||
| 901 | prevents GNUS from inserting its default attribution header. Otherwise, | ||
| 902 | both GNUS and Supercite will insert an attribution header: | ||
| 903 | |||
| 904 | @example | ||
| 905 | (setq news-reply-header-hook nil) | ||
| 906 | @end example | ||
| 907 | |||
| 908 | @node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected | ||
| 909 | @comment node-name, next, previous, up | ||
| 910 | @vindex mail-citation-hook | ||
| 911 | @cindex .emacs file | ||
| 912 | @cindex overloading | ||
| 913 | @cindex sendmail.el file | ||
| 914 | @section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 | ||
| 915 | @ifinfo | ||
| 916 | |||
| 917 | @end ifinfo | ||
| 918 | These MUAs use Emacs' built-in yanking and citing routines, contained in | ||
| 919 | the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its | ||
| 920 | derivative Epoch 4, do not know anything about the citation interface | ||
| 921 | required by Supercite. To connect Supercite to any of these MUAs under | ||
| 922 | Emacs 18 or Epoch 4, you should first | ||
| 923 | @pxref{Overloading for Non-conforming MUAs}. Then follow the directions | ||
| 924 | for using these MUAs under Emacs 19. | ||
| 925 | @xref{Emacs 19 MUAs}.@refill | ||
| 926 | |||
| 927 | @cindex add-hook substitute | ||
| 928 | @cindex setq as a substitute for add-hook | ||
| 929 | @findex setq | ||
| 930 | @findex add-hook | ||
| 931 | @cindex sc-unsupp.el file | ||
| 932 | Note that those instructions will tell you to use the function | ||
| 933 | @code{add-hook}. This function is new with Emacs 19 and you will not | ||
| 934 | have it by default if you are running Emacs 18 or Epoch 4. You can | ||
| 935 | either substitute the appropriate call to @code{setq}, or you can use | ||
| 936 | the @code{add-hook} function that is provided in the @file{sc-unsupp.el} | ||
| 937 | file of unsupported Supercite hacks and ideas. Or you can upgrade to | ||
| 938 | some Emacs 19 variant! @t{:-)}@refill | ||
| 939 | |||
| 940 | To use @code{setq} instead of @code{add-hook}, you would, for example, | ||
| 941 | change this: | ||
| 942 | |||
| 943 | @example | ||
| 944 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 945 | @end example | ||
| 946 | |||
| 947 | to: | ||
| 948 | |||
| 949 | @example | ||
| 950 | (setq mail-citation-hook 'sc-cite-original) | ||
| 951 | @end example | ||
| 952 | |||
| 953 | Note the lack of a single quote on the first argument to @code{setq}. | ||
| 954 | |||
| 955 | @node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected | ||
| 956 | @comment node-name, next, previous, up | ||
| 957 | @cindex .emacs file | ||
| 958 | @vindex mh-yank-hooks | ||
| 959 | @findex add-hook | ||
| 960 | @cindex mail-citation-hook | ||
| 961 | @section MH-E with any Emacsen | ||
| 962 | @ifinfo | ||
| 963 | |||
| 964 | @end ifinfo | ||
| 965 | MH-E 4.x conforms to the @code{mail-citation-hook} interface supported | ||
| 966 | by other MUAs. At the time of this writing, MH-E 4.0 has not been | ||
| 967 | released, but if you have it, put this in your @file{.emacs} file to | ||
| 968 | connect Supercite and MH-E 4.x: | ||
| 969 | |||
| 970 | @example | ||
| 971 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 972 | @end example | ||
| 973 | |||
| 974 | Note that if you are using Emacs 18 or Epoch 4, you will not have the | ||
| 975 | @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to | ||
| 976 | proceed without @code{add-hook}. | ||
| 977 | |||
| 978 | MH-E version 3.x uses a slightly different interface than other MUAs. | ||
| 979 | MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act | ||
| 980 | like a hook, and doing an @code{add-hook} will not work. | ||
| 981 | |||
| 982 | To connect Supercite to MH-E 3.x, you should instead add the following | ||
| 983 | to your @code{.emacs} file: | ||
| 984 | |||
| 985 | @example | ||
| 986 | (add-hook 'mh-yank-hooks 'sc-cite-original) | ||
| 987 | @end example | ||
| 988 | |||
| 989 | @vindex mh-yank-from-start-of-msg | ||
| 990 | You also need to make sure that MH-E includes all the original mail | ||
| 991 | headers in the yanked message. The variable that controls this is | ||
| 992 | @code{mh-yank-from-start-of-msg}. By default, this variable has the | ||
| 993 | value @code{t}, which tells MH-E to include all the mail headers when | ||
| 994 | yanking the original message. Before you switched to using Supercite, | ||
| 995 | you may have set this variable to other values so as not to include the | ||
| 996 | mail headers in the yanked message. Since Supercite requires these | ||
| 997 | headers (and cleans them out for you), you need to make sure the value | ||
| 998 | is @code{t}. This lisp, in your @file{.emacs} file will do the trick: | ||
| 999 | |||
| 1000 | @example | ||
| 1001 | (setq mh-yank-from-start-of-msg t) | ||
| 1002 | @end example | ||
| 1003 | |||
| 1004 | Note that versions of MH-E before 3.7 did not provide the | ||
| 1005 | @code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E | ||
| 1006 | version 3.7 or later. | ||
| 1007 | |||
| 1008 | @node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected | ||
| 1009 | @comment node-name, next, previous, up | ||
| 1010 | @cindex .emacs file | ||
| 1011 | @vindex mail-citation-hook | ||
| 1012 | @vindex mail-yank-hooks | ||
| 1013 | @section VM with any Emacsen | ||
| 1014 | @ifinfo | ||
| 1015 | |||
| 1016 | @end ifinfo | ||
| 1017 | Since release 4.40, VM has supported the citation interface required by | ||
| 1018 | Supercite. But since the interface has changed recently the details of | ||
| 1019 | getting connected differ with the version of VM you are using. | ||
| 1020 | |||
| 1021 | If you are running any release of VM after 4.40, you can add the | ||
| 1022 | following to your @file{.emacs} to connect Supercite with VM: | ||
| 1023 | |||
| 1024 | @example | ||
| 1025 | (add-hook 'mail-yank-hooks 'sc-cite-original) | ||
| 1026 | @end example | ||
| 1027 | |||
| 1028 | Note that if you are using Emacs 18 or Epoch 4, you will not have the | ||
| 1029 | @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to | ||
| 1030 | proceed without @code{add-hook}. | ||
| 1031 | |||
| 1032 | Since version 5.34, VM has supported the newer @code{mail-citation-hook} | ||
| 1033 | interface, but @code{mail-yank-hooks} is still being supported for | ||
| 1034 | backward compatibility. If you are running a newer version of VM and | ||
| 1035 | you want to maintain consistency with other MUAs, use this bit of code | ||
| 1036 | instead: | ||
| 1037 | |||
| 1038 | @example | ||
| 1039 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 1040 | @end example | ||
| 1041 | |||
| 1042 | @node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected | ||
| 1043 | @comment node-name, next, previous, up@cindex .emacs file | ||
| 1044 | @vindex news-reply-mode-hook | ||
| 1045 | @findex sc-perform-overloads | ||
| 1046 | @findex perform-overloads (sc-) | ||
| 1047 | @vindex gnews-ready-hook | ||
| 1048 | @section GNEWS with any Emacsen | ||
| 1049 | @ifinfo | ||
| 1050 | |||
| 1051 | @end ifinfo | ||
| 1052 | As far as I know, no version of GNEWS supports the citation interface | ||
| 1053 | required by Supercite. To connect Supercite with GNEWS, please first | ||
| 1054 | @pxref{Overloading for Non-conforming MUAs}. | ||
| 1055 | |||
| 1056 | After you have followed the directions in that section. You should add | ||
| 1057 | the following lisp code to your @file{.emacs} file: | ||
| 1058 | |||
| 1059 | @example | ||
| 1060 | (add-hook 'mail-citation-hook 'sc-cite-original) | ||
| 1061 | @end example | ||
| 1062 | |||
| 1063 | Note that if you are using Emacs 18 or Epoch 4, you will not have the | ||
| 1064 | @code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to | ||
| 1065 | proceed without @code{add-hook}. | ||
| 1066 | |||
| 1067 | @node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected | ||
| 1068 | @comment node-name, next, previous, up | ||
| 1069 | @cindex overloading | ||
| 1070 | @cindex sc-oloads.el | ||
| 1071 | @vindex mail-citation-hook | ||
| 1072 | @findex sc-perform-overloads | ||
| 1073 | @cindex .emacs file | ||
| 1074 | @section Overloading for Non-conforming MUAs | ||
| 1075 | @ifinfo | ||
| 1076 | |||
| 1077 | @end ifinfo | ||
| 1078 | As mentioned elsewhere, some MUAs do not provide the necessary hooks to | ||
| 1079 | connect with Supercite. Supercite version 3.1 provides an unsupported | ||
| 1080 | mechanism, called @dfn{overloading} which redefines certain key | ||
| 1081 | functions in the MUA, so that it will call the @code{mail-citation-hook} | ||
| 1082 | variable instead of the MUA's default hard-coded citing routines. Since | ||
| 1083 | most newer versions of the known MUAs support the | ||
| 1084 | @code{mail-citation-hook} variable, it is recommended that you upgrade | ||
| 1085 | if at all possible. But if you can't upgrade, at least you're not out | ||
| 1086 | of luck! Once you set up overloading properly, you should follow the | ||
| 1087 | directions for connecting Supercite to the Emacs 19 MUAs. | ||
| 1088 | @xref{Emacs 19 MUAs}.@refill | ||
| 1089 | |||
| 1090 | @cindex Hyperbole | ||
| 1091 | @vindex hyperb:version | ||
| 1092 | Users of Bob Weiner's Hyperbole package take note. Hyperbole provides | ||
| 1093 | the necessary overloads (and a whole lot more!) and you can potentially | ||
| 1094 | clobber it if you were to load Supercite's overloading after | ||
| 1095 | Hyperbole's. For this reason, Supercite will @emph{not} perform any | ||
| 1096 | overloading if it finds the variable @code{hyperb:version} is | ||
| 1097 | @code{boundp} (i.e. it exists because Hyperbole has been loaded into | ||
| 1098 | your Emacs session). If this is the case, Supercite will display a | ||
| 1099 | warning message in the minibuffer. You should consult the Hyperbole | ||
| 1100 | manual for further details. | ||
| 1101 | |||
| 1102 | Overloading involves the re-definition of the citing function with the | ||
| 1103 | new, @code{mail-citation-hook} savvy version. The function in | ||
| 1104 | @file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This | ||
| 1105 | function is smart enough to only overload the MUA functions when it is | ||
| 1106 | absolutely necessary, based on the version numbers it can figure out. | ||
| 1107 | Also, @code{sc-perform-overloads} will only install the new functions | ||
| 1108 | once. It is also smart enough to do nothing if the MUA is not yet | ||
| 1109 | loaded.@refill | ||
| 1110 | |||
| 1111 | The tricky part is finding the right time and place to perform the | ||
| 1112 | overloading. It must be done after the MUA has been loaded into your | ||
| 1113 | Emacs session, but before the first time you try to yank in a message. | ||
| 1114 | Fortunately, this has been figured out for you. | ||
| 1115 | |||
| 1116 | If you must overload, you should put the following lisp code in your | ||
| 1117 | @file{.emacs} file, to make sure the @file{sc-oloads.el} file gets | ||
| 1118 | loaded at the right time: | ||
| 1119 | |||
| 1120 | @example | ||
| 1121 | (autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t) | ||
| 1122 | @end example | ||
| 1123 | |||
| 1124 | Then you must make sure that the function @code{sc-perform-overloads} | ||
| 1125 | gets run at the right time. For GNUS, put this in your @file{.emacs} | ||
| 1126 | file: | ||
| 1127 | |||
| 1128 | @example | ||
| 1129 | (setq news-reply-mode-hook 'sc-perform-overloads) | ||
| 1130 | (setq mail-setup-hook 'sc-perform-overloads) | ||
| 1131 | @end example | ||
| 1132 | |||
| 1133 | If you are using RNEWS, put this in your @file{.emacs} file: | ||
| 1134 | |||
| 1135 | @vindex news-reply-mode-hook | ||
| 1136 | @example | ||
| 1137 | (setq news-reply-mode-hook 'sc-perform-overloads) | ||
| 1138 | @end example | ||
| 1139 | |||
| 1140 | If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file: | ||
| 1141 | |||
| 1142 | @example | ||
| 1143 | (setq mail-setup-hook 'sc-perform-overloads) | ||
| 1144 | @end example | ||
| 1145 | |||
| 1146 | If you are using GNEWS, put this in your @file{.emacs} file: | ||
| 1147 | |||
| 1148 | @example | ||
| 1149 | (setq news-reply-mode-hook 'sc-perform-overloads) | ||
| 1150 | (setq gnews-ready-hook 'sc-perform-overloads) | ||
| 1151 | @end example | ||
| 1152 | |||
| 1153 | Now go back and follow the directions for getting the Emacs 19 MUAs | ||
| 1154 | connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes | ||
| 1155 | for Emacs 19's @code{add-hook} function.@refill | ||
| 1156 | |||
| 1157 | @node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top | ||
| 1158 | @comment node-name, next, previous, up | ||
| 1159 | @chapter Replying and Yanking | 799 | @chapter Replying and Yanking |
| 1160 | @ifinfo | 800 | @ifinfo |
| 1161 | 801 | ||
| @@ -1168,14 +808,10 @@ message from an MUA. | |||
| 1168 | @end menu | 808 | @end menu |
| 1169 | @end ifinfo | 809 | @end ifinfo |
| 1170 | @node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking | 810 | @node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking |
| 1171 | @comment node-name, next, previous, up | ||
| 1172 | @findex sc-cite-original | 811 | @findex sc-cite-original |
| 1173 | @findex cite-original (sc-) | 812 | @findex cite-original (sc-) |
| 1174 | @comment | ||
| 1175 | @section Reply Buffer Initialization | 813 | @section Reply Buffer Initialization |
| 1176 | @ifinfo | ||
| 1177 | 814 | ||
| 1178 | @end ifinfo | ||
| 1179 | Executing @code{sc-cite-original} performs the following steps as it | 815 | Executing @code{sc-cite-original} performs the following steps as it |
| 1180 | initializes the reply buffer: | 816 | initializes the reply buffer: |
| 1181 | 817 | ||
| @@ -1329,7 +965,6 @@ reset certain variables set in @code{sc-pre-hook}.@refill | |||
| 1329 | @end enumerate | 965 | @end enumerate |
| 1330 | 966 | ||
| 1331 | @node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking | 967 | @node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking |
| 1332 | @comment node-name, next, previous, up | ||
| 1333 | @cindex filling paragraphs | 968 | @cindex filling paragraphs |
| 1334 | @vindex sc-auto-fill-region-p | 969 | @vindex sc-auto-fill-region-p |
| 1335 | @vindex auto-fill-region-p (sc-) | 970 | @vindex auto-fill-region-p (sc-) |
| @@ -1340,9 +975,7 @@ reset certain variables set in @code{sc-pre-hook}.@refill | |||
| 1340 | @vindex sc-load-hook | 975 | @vindex sc-load-hook |
| 1341 | @vindex load-hook (sc-) | 976 | @vindex load-hook (sc-) |
| 1342 | @section Filling Cited Text | 977 | @section Filling Cited Text |
| 1343 | @ifinfo | ||
| 1344 | 978 | ||
| 1345 | @end ifinfo | ||
| 1346 | Supercite will automatically fill newly cited text from the original | 979 | Supercite will automatically fill newly cited text from the original |
| 1347 | message unless the variable @code{sc-auto-fill-region-p} has a | 980 | message unless the variable @code{sc-auto-fill-region-p} has a |
| 1348 | @code{nil} value. Supercite will also re-fill paragraphs when you | 981 | @code{nil} value. Supercite will also re-fill paragraphs when you |
| @@ -1411,15 +1044,11 @@ containing lines greater than about 72 characters. So the default is to | |||
| 1411 | fill cited text. | 1044 | fill cited text. |
| 1412 | 1045 | ||
| 1413 | @node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top | 1046 | @node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top |
| 1414 | @comment node-name, next, previous, up | ||
| 1415 | @cindex attribution list | 1047 | @cindex attribution list |
| 1416 | @vindex sc-preferred-attribution-list | 1048 | @vindex sc-preferred-attribution-list |
| 1417 | @vindex preferred-attribution-list (sc-) | 1049 | @vindex preferred-attribution-list (sc-) |
| 1418 | @comment | ||
| 1419 | @chapter Selecting an Attribution | 1050 | @chapter Selecting an Attribution |
| 1420 | @ifinfo | ||
| 1421 | 1051 | ||
| 1422 | @end ifinfo | ||
| 1423 | As you know, the attribution string is the part of the author's name | 1052 | As you know, the attribution string is the part of the author's name |
| 1424 | that will be used to composed a non-nested citation string. Supercite | 1053 | that will be used to composed a non-nested citation string. Supercite |
| 1425 | scans the various mail headers present in the original article and uses | 1054 | scans the various mail headers present in the original article and uses |
| @@ -1439,11 +1068,8 @@ author's initials, and the author's email terminus. | |||
| 1439 | @end ifinfo | 1068 | @end ifinfo |
| 1440 | 1069 | ||
| 1441 | @node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution | 1070 | @node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution |
| 1442 | @comment node-name, next, previous, up | ||
| 1443 | @section Attribution Preferences | 1071 | @section Attribution Preferences |
| 1444 | @ifinfo | ||
| 1445 | 1072 | ||
| 1446 | @end ifinfo | ||
| 1447 | When you cite an original message, you can tell Supercite which part of | 1073 | When you cite an original message, you can tell Supercite which part of |
| 1448 | the author's name you would prefer it to use as the attribution. The | 1074 | the author's name you would prefer it to use as the attribution. The |
| 1449 | variable @code{sc-preferred-attribution-list} controls this; it contains | 1075 | variable @code{sc-preferred-attribution-list} controls this; it contains |
| @@ -1544,16 +1170,12 @@ match against a specific mail field, e.g., @samp{From:@:}, allowing you | |||
| 1544 | to cite your friend's message with the appropriate attribution. | 1170 | to cite your friend's message with the appropriate attribution. |
| 1545 | 1171 | ||
| 1546 | @node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution | 1172 | @node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution |
| 1547 | @comment node-name, next, previous, up | ||
| 1548 | @vindex sc-default-author-name | 1173 | @vindex sc-default-author-name |
| 1549 | @vindex default-author-name (sc-) | 1174 | @vindex default-author-name (sc-) |
| 1550 | @vindex sc-default-attribution | 1175 | @vindex sc-default-attribution |
| 1551 | @vindex default-attribution (sc-) | 1176 | @vindex default-attribution (sc-) |
| 1552 | @comment | ||
| 1553 | @section Anonymous Attributions | 1177 | @section Anonymous Attributions |
| 1554 | @ifinfo | ||
| 1555 | 1178 | ||
| 1556 | @end ifinfo | ||
| 1557 | When the author's name cannot be found in the @samp{From:@:} mail | 1179 | When the author's name cannot be found in the @samp{From:@:} mail |
| 1558 | header, a fallback author name and attribution string must be supplied. | 1180 | header, a fallback author name and attribution string must be supplied. |
| 1559 | The fallback author name is contained in the variable | 1181 | The fallback author name is contained in the variable |
| @@ -1637,18 +1259,14 @@ one character long; e.g. you prefer to use @code{"initials"} but the | |||
| 1637 | author only has one name.@refill | 1259 | author only has one name.@refill |
| 1638 | 1260 | ||
| 1639 | @node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution | 1261 | @node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution |
| 1640 | @comment node-name, next, previous, up | ||
| 1641 | @cindex author names | 1262 | @cindex author names |
| 1642 | @section Author Names | 1263 | @section Author Names |
| 1643 | @ifinfo | ||
| 1644 | 1264 | ||
| 1645 | @end ifinfo | ||
| 1646 | Supercite employs a number of heuristics to decipher the author's name | 1265 | Supercite employs a number of heuristics to decipher the author's name |
| 1647 | based on value of the @samp{From:@:} mail field of the original message. | 1266 | based on value of the @samp{From:@:} mail field of the original message. |
| 1648 | Supercite can recognize almost all of the common @samp{From:@:} field | 1267 | Supercite can recognize almost all of the common @samp{From:@:} field |
| 1649 | formats in use. If you encounter a @samp{From:@:} field that Supercite | 1268 | formats in use. If you encounter a @samp{From:@:} field that Supercite |
| 1650 | cannot parse, please report this bug. | 1269 | cannot parse, please report this bug using @kbd{M-x report-emacs-bug}. |
| 1651 | @xref{The Supercite Mailing List}.@refill | ||
| 1652 | 1270 | ||
| 1653 | @vindex sc-titlecue-regexp | 1271 | @vindex sc-titlecue-regexp |
| 1654 | @vindex titlecue-regexp (sc-) | 1272 | @vindex titlecue-regexp (sc-) |
| @@ -1703,14 +1321,11 @@ word in the name field, while @code{any} matches against every word in | |||
| 1703 | the name field. | 1321 | the name field. |
| 1704 | 1322 | ||
| 1705 | @node Configuring the Citation Engine, Using Regi, Author Names, Top | 1323 | @node Configuring the Citation Engine, Using Regi, Author Names, Top |
| 1706 | @comment node-name, next, previous, up | ||
| 1707 | @cindex Regi | 1324 | @cindex Regi |
| 1708 | @cindex frames (Regi) | 1325 | @cindex frames (Regi) |
| 1709 | @cindex entries (Regi) | 1326 | @cindex entries (Regi) |
| 1710 | @chapter Configuring the Citation Engine | 1327 | @chapter Configuring the Citation Engine |
| 1711 | @ifinfo | ||
| 1712 | 1328 | ||
| 1713 | @end ifinfo | ||
| 1714 | At the heart of Supercite is a regular expression interpreting engine | 1329 | At the heart of Supercite is a regular expression interpreting engine |
| 1715 | called @dfn{Regi}. Regi operates by interpreting a data structure | 1330 | called @dfn{Regi}. Regi operates by interpreting a data structure |
| 1716 | called a Regi-frame (or just @dfn{frame}), which is a list of | 1331 | called a Regi-frame (or just @dfn{frame}), which is a list of |
| @@ -1744,14 +1359,11 @@ cite or fill those differently than normal text. None of this is | |||
| 1744 | currently part of Supercite, but contributions are welcome! | 1359 | currently part of Supercite, but contributions are welcome! |
| 1745 | 1360 | ||
| 1746 | @node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine | 1361 | @node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine |
| 1747 | @comment node-name, next, previous, up | ||
| 1748 | @findex regi-interpret | 1362 | @findex regi-interpret |
| 1749 | @findex eval | 1363 | @findex eval |
| 1750 | @findex looking-at | 1364 | @findex looking-at |
| 1751 | @section Using Regi | 1365 | @section Using Regi |
| 1752 | @ifinfo | ||
| 1753 | 1366 | ||
| 1754 | @end ifinfo | ||
| 1755 | Regi works by interpreting frames with the function | 1367 | Regi works by interpreting frames with the function |
| 1756 | @code{regi-interpret}. A frame is a list of arbitrary size where each | 1368 | @code{regi-interpret}. A frame is a list of arbitrary size where each |
| 1757 | element is a entry of the following form: | 1369 | element is a entry of the following form: |
| @@ -1845,12 +1457,9 @@ The current frame entry being interpreted. | |||
| 1845 | @end table | 1457 | @end table |
| 1846 | 1458 | ||
| 1847 | @node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine | 1459 | @node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine |
| 1848 | @comment node-name, next, previous, up | ||
| 1849 | @vindex sc-nuke-mail-header | 1460 | @vindex sc-nuke-mail-header |
| 1850 | @section Frames You Can Customize | 1461 | @section Frames You Can Customize |
| 1851 | @ifinfo | ||
| 1852 | 1462 | ||
| 1853 | @end ifinfo | ||
| 1854 | As mentioned earlier, Supercite uses various frames to perform | 1463 | As mentioned earlier, Supercite uses various frames to perform |
| 1855 | certain jobs such as mail header information extraction and mail header | 1464 | certain jobs such as mail header information extraction and mail header |
| 1856 | nuking. However, these frames are not available for you to customize, | 1465 | nuking. However, these frames are not available for you to customize, |
| @@ -1912,14 +1521,11 @@ the appropriate alist and attempts to find a frame to use. If one | |||
| 1912 | is not found from the alist, then the appropriate default frame is used. | 1521 | is not found from the alist, then the appropriate default frame is used. |
| 1913 | 1522 | ||
| 1914 | @node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top | 1523 | @node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top |
| 1915 | @comment node-name, next, previous, up | ||
| 1916 | @vindex sc-mode-map-prefix | 1524 | @vindex sc-mode-map-prefix |
| 1917 | @vindex mode-map-prefix (sc-) | 1525 | @vindex mode-map-prefix (sc-) |
| 1918 | @kindex C-c C-p | 1526 | @kindex C-c C-p |
| 1919 | @chapter Post-yank Formatting Commands | 1527 | @chapter Post-yank Formatting Commands |
| 1920 | @ifinfo | ||
| 1921 | 1528 | ||
| 1922 | @end ifinfo | ||
| 1923 | Once the original message has been yanked into the reply buffer, and | 1529 | Once the original message has been yanked into the reply buffer, and |
| 1924 | @code{sc-cite-original} has had a chance to do its thing, a number of | 1530 | @code{sc-cite-original} has had a chance to do its thing, a number of |
| 1925 | useful Supercite commands will be available to you. Since there is wide | 1531 | useful Supercite commands will be available to you. Since there is wide |
| @@ -1945,12 +1551,9 @@ prefix.@refill | |||
| 1945 | @end ifinfo | 1551 | @end ifinfo |
| 1946 | 1552 | ||
| 1947 | @node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands | 1553 | @node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands |
| 1948 | @comment node-name, next, previous, up | ||
| 1949 | @vindex sc-cite-region-limit | 1554 | @vindex sc-cite-region-limit |
| 1950 | @section Commands to Manually Cite, Recite, and Uncite | 1555 | @section Commands to Manually Cite, Recite, and Uncite |
| 1951 | @ifinfo | ||
| 1952 | 1556 | ||
| 1953 | @end ifinfo | ||
| 1954 | Probably the three most common post-yank formatting operations that you | 1557 | Probably the three most common post-yank formatting operations that you |
| 1955 | will perform will be the manual citing, reciting, and unciting of | 1558 | will perform will be the manual citing, reciting, and unciting of |
| 1956 | regions of text in the reply buffer. Often you may want to recite a | 1559 | regions of text in the reply buffer. Often you may want to recite a |
| @@ -1961,15 +1564,6 @@ perform these functions on the region of text between @samp{point} and | |||
| 1961 | the region so that the command can be undone in the standard Emacs | 1564 | the region so that the command can be undone in the standard Emacs |
| 1962 | way.@refill | 1565 | way.@refill |
| 1963 | 1566 | ||
| 1964 | A quick note about Emacs 19. Unlike in Emacs 18, the region delimited | ||
| 1965 | by @samp{point} and @samp{mark} can have two states. It can be | ||
| 1966 | @dfn{active} or @dfn{inactive}. Although Emacs 19 and Lucid Emacs 19 | ||
| 1967 | use different terminology and functions, both employ the same convention | ||
| 1968 | such that when the region is inactive, commands that modify the region | ||
| 1969 | should generate an error. The user needs to explicitly activate the | ||
| 1970 | region before successfully executing the command. All Supercite | ||
| 1971 | commands conform to this convention. | ||
| 1972 | |||
| 1973 | Here is the list of Supercite citing commands: | 1567 | Here is the list of Supercite citing commands: |
| 1974 | 1568 | ||
| 1975 | @table @asis | 1569 | @table @asis |
| @@ -1982,7 +1576,6 @@ Here is the list of Supercite citing commands: | |||
| 1982 | @vindex confirm-always-p | 1576 | @vindex confirm-always-p |
| 1983 | @kindex C-u | 1577 | @kindex C-u |
| 1984 | @item @code{sc-cite-region} (@kbd{C-c C-p c}) | 1578 | @item @code{sc-cite-region} (@kbd{C-c C-p c}) |
| 1985 | @comment | ||
| 1986 | This command cites each line in the region of text by interpreting the | 1579 | This command cites each line in the region of text by interpreting the |
| 1987 | selected frame from @code{sc-cite-frame-alist}, or the default citing | 1580 | selected frame from @code{sc-cite-frame-alist}, or the default citing |
| 1988 | frame @code{sc-default-cite-frame}. It runs the hook | 1581 | frame @code{sc-default-cite-frame}. It runs the hook |
| @@ -1996,7 +1589,6 @@ attribution string for a single manual citing. | |||
| 1996 | @findex uncite-region (sc-) | 1589 | @findex uncite-region (sc-) |
| 1997 | @kindex C-c C-p u | 1590 | @kindex C-c C-p u |
| 1998 | @item @code{sc-uncite-region} (@kbd{C-c C-p u}) | 1591 | @item @code{sc-uncite-region} (@kbd{C-c C-p u}) |
| 1999 | @comment | ||
| 2000 | This command removes any citation strings from the beginning of each | 1592 | This command removes any citation strings from the beginning of each |
| 2001 | cited line in the region by interpreting the selected frame from | 1593 | cited line in the region by interpreting the selected frame from |
| 2002 | @code{sc-uncite-frame-alist}, or the default unciting frame | 1594 | @code{sc-uncite-frame-alist}, or the default unciting frame |
| @@ -2008,7 +1600,6 @@ cited line in the region by interpreting the selected frame from | |||
| 2008 | @findex recite-region (sc-) | 1600 | @findex recite-region (sc-) |
| 2009 | @kindex C-c C-p r | 1601 | @kindex C-c C-p r |
| 2010 | @item @code{sc-recite-region} (@kbd{C-c C-p r}) | 1602 | @item @code{sc-recite-region} (@kbd{C-c C-p r}) |
| 2011 | @comment | ||
| 2012 | This command recites each line the region by interpreting the selected | 1603 | This command recites each line the region by interpreting the selected |
| 2013 | frame from @code{sc-recite-frame-alist}, or the default reciting frame | 1604 | frame from @code{sc-recite-frame-alist}, or the default reciting frame |
| 2014 | @code{sc-default-recite-frame}. It runs the hook | 1605 | @code{sc-default-recite-frame}. It runs the hook |
| @@ -2022,11 +1613,8 @@ region, regardless of the value of @code{sc-confirm-always-p}. | |||
| 2022 | @end table | 1613 | @end table |
| 2023 | 1614 | ||
| 2024 | @node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands | 1615 | @node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands |
| 2025 | @comment node-name, next, previous, up | ||
| 2026 | @section Insertion Commands | 1616 | @section Insertion Commands |
| 2027 | @ifinfo | ||
| 2028 | 1617 | ||
| 2029 | @end ifinfo | ||
| 2030 | These two functions insert various strings into the reply buffer. | 1618 | These two functions insert various strings into the reply buffer. |
| 2031 | 1619 | ||
| 2032 | @table @asis | 1620 | @table @asis |
| @@ -2034,7 +1622,6 @@ These two functions insert various strings into the reply buffer. | |||
| 2034 | @findex insert-reference (sc-) | 1622 | @findex insert-reference (sc-) |
| 2035 | @kindex C-c C-p w | 1623 | @kindex C-c C-p w |
| 2036 | @item @code{sc-insert-reference} (@kbd{C-c C-p w}) | 1624 | @item @code{sc-insert-reference} (@kbd{C-c C-p w}) |
| 2037 | @comment | ||
| 2038 | @vindex sc-preferred-header-style | 1625 | @vindex sc-preferred-header-style |
| 2039 | @vindex preferred-header-style (sc-) | 1626 | @vindex preferred-header-style (sc-) |
| 2040 | Inserts a reference header into the reply buffer at @samp{point}. With | 1627 | Inserts a reference header into the reply buffer at @samp{point}. With |
| @@ -2050,19 +1637,15 @@ entered, regardless of the value of @code{sc-electric-references-p}. | |||
| 2050 | @findex insert-citation (sc-) | 1637 | @findex insert-citation (sc-) |
| 2051 | @kindex C-c C-p i | 1638 | @kindex C-c C-p i |
| 2052 | @item @code{sc-insert-citation} (@kbd{C-c C-p i}) | 1639 | @item @code{sc-insert-citation} (@kbd{C-c C-p i}) |
| 2053 | @comment | ||
| 2054 | Inserts the current citation string at the beginning of the line that | 1640 | Inserts the current citation string at the beginning of the line that |
| 2055 | @samp{point} is on. If the line is already cited, Supercite will issue | 1641 | @samp{point} is on. If the line is already cited, Supercite will issue |
| 2056 | an error and will not cite the line. | 1642 | an error and will not cite the line. |
| 2057 | @end table | 1643 | @end table |
| 2058 | 1644 | ||
| 2059 | @node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands | 1645 | @node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands |
| 2060 | @comment node-name, next, previous, up | ||
| 2061 | @cindex toggling variables | 1646 | @cindex toggling variables |
| 2062 | @section Variable Toggling Shortcuts | 1647 | @section Variable Toggling Shortcuts |
| 2063 | @ifinfo | ||
| 2064 | 1648 | ||
| 2065 | @end ifinfo | ||
| 2066 | Supercite defines a number of commands that make it easier for you to | 1649 | Supercite defines a number of commands that make it easier for you to |
| 2067 | toggle and set various Supercite variables as you are editing the reply | 1650 | toggle and set various Supercite variables as you are editing the reply |
| 2068 | buffer. For example, you may want to turn off filling or whitespace | 1651 | buffer. For example, you may want to turn off filling or whitespace |
| @@ -2140,11 +1723,8 @@ brings up a Help message on the toggling keymap. | |||
| 2140 | 1723 | ||
| 2141 | 1724 | ||
| 2142 | @node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands | 1725 | @node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands |
| 2143 | @comment node-name, next, previous, up | ||
| 2144 | @section Mail Field Commands | 1726 | @section Mail Field Commands |
| 2145 | @ifinfo | ||
| 2146 | 1727 | ||
| 2147 | @end ifinfo | ||
| 2148 | These commands allow you to view, modify, add, and delete various bits | 1728 | These commands allow you to view, modify, add, and delete various bits |
| 2149 | of information from the info alist. | 1729 | of information from the info alist. |
| 2150 | @xref{Information Keys and the Info Alist}.@refill | 1730 | @xref{Information Keys and the Info Alist}.@refill |
| @@ -2155,7 +1735,6 @@ of information from the info alist. | |||
| 2155 | @findex mail-field-query (sc-) | 1735 | @findex mail-field-query (sc-) |
| 2156 | @kindex C-c C-p f | 1736 | @kindex C-c C-p f |
| 2157 | @item @code{sc-mail-field-query} (@kbd{C-c C-p f}) | 1737 | @item @code{sc-mail-field-query} (@kbd{C-c C-p f}) |
| 2158 | @comment | ||
| 2159 | Allows you to interactively view, modify, add, and delete info alist | 1738 | Allows you to interactively view, modify, add, and delete info alist |
| 2160 | key-value pairs. With no argument, you are prompted (with completion) | 1739 | key-value pairs. With no argument, you are prompted (with completion) |
| 2161 | for a info key. The value associated with that key is displayed in the | 1740 | for a info key. The value associated with that key is displayed in the |
| @@ -2167,8 +1746,7 @@ If you want to modify the value of a key, Supercite will first prompt | |||
| 2167 | you (with completion) for the key of the value you want to change. It | 1746 | you (with completion) for the key of the value you want to change. It |
| 2168 | will then put you in the minibuffer with the key's current value so you | 1747 | will then put you in the minibuffer with the key's current value so you |
| 2169 | can edit the value as you wish. When you hit @key{RET}, the key's value | 1748 | can edit the value as you wish. When you hit @key{RET}, the key's value |
| 2170 | is changed. For those of you running Emacs 19, minibuffer history is | 1749 | is changed. Minibuffer history is kept for the values. |
| 2171 | kept for the values. | ||
| 2172 | 1750 | ||
| 2173 | If you choose to delete a key-value pair, Supercite will prompt you (with | 1751 | If you choose to delete a key-value pair, Supercite will prompt you (with |
| 2174 | completion) for the key to delete. | 1752 | completion) for the key to delete. |
| @@ -2185,7 +1763,6 @@ subsequently delete the key-value pair, the old value will reappear. | |||
| 2185 | @findex mail-process-headers (sc-) | 1763 | @findex mail-process-headers (sc-) |
| 2186 | @kindex C-c C-p g | 1764 | @kindex C-c C-p g |
| 2187 | @item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) | 1765 | @item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) |
| 2188 | @comment | ||
| 2189 | This command lets you re-initialize Supercite's info alist from any set | 1766 | This command lets you re-initialize Supercite's info alist from any set |
| 2190 | of mail headers in the region between @samp{point} and @samp{mark}. | 1767 | of mail headers in the region between @samp{point} and @samp{mark}. |
| 2191 | This function is especially useful for replying to digest messages where | 1768 | This function is especially useful for replying to digest messages where |
| @@ -2196,60 +1773,22 @@ old information is lost.@refill | |||
| 2196 | @end table | 1773 | @end table |
| 2197 | 1774 | ||
| 2198 | @node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands | 1775 | @node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands |
| 2199 | @comment node-name, next, previous, up | ||
| 2200 | @section Miscellaneous Commands | 1776 | @section Miscellaneous Commands |
| 2201 | @ifinfo | ||
| 2202 | 1777 | ||
| 2203 | @end ifinfo | ||
| 2204 | @table @asis | 1778 | @table @asis |
| 2205 | @findex sc-open-line | 1779 | @findex sc-open-line |
| 2206 | @findex open-line (sc-) | 1780 | @findex open-line (sc-) |
| 2207 | @findex open-line | 1781 | @findex open-line |
| 2208 | @kindex C-c C-p o | 1782 | @kindex C-c C-p o |
| 2209 | @item @code{sc-open-line} (@kbd{C-c C-p o}) | 1783 | @item @code{sc-open-line} (@kbd{C-c C-p o}) |
| 2210 | @comment | ||
| 2211 | Similar to Emacs' standard @code{open-line} commands, but inserts the | 1784 | Similar to Emacs' standard @code{open-line} commands, but inserts the |
| 2212 | citation string in front of the new line. As with @code{open-line}, | 1785 | citation string in front of the new line. As with @code{open-line}, |
| 2213 | an optional numeric argument inserts that many new lines.@refill | 1786 | an optional numeric argument inserts that many new lines.@refill |
| 2214 | |||
| 2215 | @findex sc-describe | ||
| 2216 | @findex describe (sc-) | ||
| 2217 | @kindex C-c C-p ? | ||
| 2218 | @kindex C-c C-p h | ||
| 2219 | @item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?}) | ||
| 2220 | @comment | ||
| 2221 | This function has been obsoleted by the @TeX{}info manual you are now | ||
| 2222 | reading. It is still provided for compatibility, but it will eventually | ||
| 2223 | go away. | ||
| 2224 | |||
| 2225 | @findex sc-version | ||
| 2226 | @findex version (sc-) | ||
| 2227 | @kindex C-c C-p v | ||
| 2228 | @item @code{sc-version} (@kbd{C-c C-p v}) | ||
| 2229 | @comment | ||
| 2230 | Echos the version of Supercite you are using. With the optional | ||
| 2231 | universal argument (@kbd{C-u}), this command inserts the version | ||
| 2232 | information into the current buffer. | ||
| 2233 | |||
| 2234 | @findex sc-submit-bug-report | ||
| 2235 | @findex submit-bug-report (sc-) | ||
| 2236 | @kindex C-c C-p C-b | ||
| 2237 | @item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b}) | ||
| 2238 | @comment | ||
| 2239 | If you encounter a bug, or wish to suggest an enhancement, use this | ||
| 2240 | command to set up an outgoing mail buffer, with the proper address to | ||
| 2241 | the Supercite maintainer automatically inserted in the @samp{To:@:} | ||
| 2242 | field. This command also inserts information that the Supercite | ||
| 2243 | maintainer can use to recreate your exact setup, making it easier to | ||
| 2244 | verify your bug. | ||
| 2245 | @end table | 1787 | @end table |
| 2246 | 1788 | ||
| 2247 | @node Hints to MUA Authors, Version 3 Changes, Electric References, Top | 1789 | @node Hints to MUA Authors, Thanks and History, Electric References, Top |
| 2248 | @comment node-name, next, previous, up | ||
| 2249 | @chapter Hints to MUA Authors | 1790 | @chapter Hints to MUA Authors |
| 2250 | @ifinfo | ||
| 2251 | 1791 | ||
| 2252 | @end ifinfo | ||
| 2253 | In June of 1989, some discussion was held between the various MUA | 1792 | In June of 1989, some discussion was held between the various MUA |
| 2254 | authors, the Supercite author, and other Supercite users. These | 1793 | authors, the Supercite author, and other Supercite users. These |
| 2255 | discussions centered around the need for a standard interface between | 1794 | discussions centered around the need for a standard interface between |
| @@ -2282,17 +1821,12 @@ a mail message to the Supercite mailing list: | |||
| 2282 | @cindex sendmail.el | 1821 | @cindex sendmail.el |
| 2283 | @findex mail-yank-original | 1822 | @findex mail-yank-original |
| 2284 | @findex defvar | 1823 | @findex defvar |
| 2285 | This specification was adopted, but with the recent release of | 1824 | This specification was adopted, but underwent a slight modification with |
| 2286 | Emacs 19, it has undergone a slight modification. Instead of the | 1825 | the release of Emacs 19. Instead of the variable |
| 2287 | variable @code{mail-yank-hooks}, the new preferred hook variable that | 1826 | @code{mail-yank-hooks}, the hook variable that the MUA should provide is |
| 2288 | the MUA should provide is @code{mail-citation-hook}. | 1827 | @code{mail-citation-hook}. Richard Stallman suggests that the MUAs |
| 2289 | @code{mail-yank-hooks} can be provided for backward compatibility, but | 1828 | should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform |
| 2290 | @code{mail-citation-hook} should always take precedence. Richard | 1829 | some default citing when that is the case.@refill |
| 2291 | Stallman (of the FSF) suggests that the MUAs should @code{defvar} | ||
| 2292 | @code{mail-citation-hook} to @code{nil} and perform some default citing | ||
| 2293 | when that is the case. Take a look at Emacs 19's @file{sendmail.el} | ||
| 2294 | file, specifically the @code{mail-yank-original} defun for | ||
| 2295 | details.@refill | ||
| 2296 | 1830 | ||
| 2297 | If you are writing a new MUA package, or maintaining an existing MUA | 1831 | If you are writing a new MUA package, or maintaining an existing MUA |
| 2298 | package, you should make it conform to this interface so that your users | 1832 | package, you should make it conform to this interface so that your users |
| @@ -2316,10 +1850,7 @@ message text. It is very important that the region be set around the | |||
| 2316 | text Supercite is to modify and that the mail headers are within this | 1850 | text Supercite is to modify and that the mail headers are within this |
| 2317 | region. Supercite will not venture outside the region for any reason, | 1851 | region. Supercite will not venture outside the region for any reason, |
| 2318 | and anything within the region is fair game, so don't put anything that | 1852 | and anything within the region is fair game, so don't put anything that |
| 2319 | @strong{must} remain unchanged inside the region. Further note that for | 1853 | @strong{must} remain unchanged inside the region.@refill |
| 2320 | Emacs 19, the region need not be set active. Supercite will work | ||
| 2321 | properly when the region is inactive, as should any other like-minded | ||
| 2322 | package.@refill | ||
| 2323 | 1854 | ||
| 2324 | @item | 1855 | @item |
| 2325 | Run the hook @code{mail-citation-hook}. You will probably want to | 1856 | Run the hook @code{mail-citation-hook}. You will probably want to |
| @@ -2333,94 +1864,12 @@ need only add @code{sc-cite-original} to this list of hooks using | |||
| 2333 | @code{add-hook}.@refill | 1864 | @code{add-hook}.@refill |
| 2334 | @end enumerate | 1865 | @end enumerate |
| 2335 | 1866 | ||
| 2336 | If you do all this, your users will not need to overload your routines | 1867 | If you do all this your MUA will join the ranks of those that conform to |
| 2337 | to use Supercite, and your MUA will join the ranks of those that conform | 1868 | this interface ``out of the box.'' |
| 2338 | to this interface ``out of the box.'' | ||
| 2339 | |||
| 2340 | @node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top | ||
| 2341 | @comment node-name, next, previous, up | ||
| 2342 | @chapter Version 3 Changes | ||
| 2343 | @ifinfo | ||
| 2344 | |||
| 2345 | @end ifinfo | ||
| 2346 | @cindex sc-unsupp.el file | ||
| 2347 | With version 3, Supercite has undergone an almost complete rewrite, and | ||
| 2348 | has hopefully benefited in a number of ways, including vast | ||
| 2349 | improvements in the speed of performance, a big reduction in size of the | ||
| 2350 | code and in the use of Emacs resources, and a much cleaner and flexible | ||
| 2351 | internal architecture. The central construct of the info alist, and its | ||
| 2352 | role in Supercite has been expanded, and the other central concept, the | ||
| 2353 | general package Regi, was developed to provide a theoretically unlimited | ||
| 2354 | flexibility. | ||
| 2355 | |||
| 2356 | But most of this work is internal and not of very great importance to the | ||
| 2357 | casual user. There have been some changes at the user-visible level, | ||
| 2358 | but for the most part, the Supercite configuration variables from | ||
| 2359 | version 2 should still be relevant to version 3. Below, I briefly | ||
| 2360 | outline those user-visible things that have changed since version 2. For | ||
| 2361 | details, look to other sections of this manual. | ||
| 2362 | |||
| 2363 | @enumerate | ||
| 2364 | @item | ||
| 2365 | @cindex supercite.el file | ||
| 2366 | @cindex reporter.el file | ||
| 2367 | @cindex regi.el file | ||
| 2368 | @cindex sc.el from version 2 | ||
| 2369 | @cindex sc-elec.el from version 2 | ||
| 2370 | Supercite proper now comes in a single file, @file{supercite.el}, which | ||
| 2371 | contains everything except the unsupported noodlings, overloading (which | ||
| 2372 | should be more or less obsolete with the release of Emacs 19), and the | ||
| 2373 | general lisp packages @file{reporter.el} and @file{regi.el}. Finally, | ||
| 2374 | the @TeX{}info manual comes in its own file as well. In particular, the | ||
| 2375 | file @file{sc.el} from the version 2 distribution is obsolete, as is the | ||
| 2376 | file @file{sc-elec.el}. | ||
| 2377 | 1869 | ||
| 2378 | @item | 1870 | @node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top |
| 2379 | @code{sc-spacify-name-chars} is gone in version 3. | ||
| 2380 | |||
| 2381 | @item | ||
| 2382 | @vindex sc-attrib-selection-list | ||
| 2383 | @vindex attrib-selection-list | ||
| 2384 | @code{sc-nickname-alist} is gone in version 3. The | ||
| 2385 | @code{sc-attrib-selection-list} is a more general construct supporting | ||
| 2386 | the same basic feature. | ||
| 2387 | |||
| 2388 | @item | ||
| 2389 | The version 2 variable @code{sc-preferred-attribution} has been changed | ||
| 2390 | to @code{sc-preferred-attribution-list}, and has been expanded upon to | ||
| 2391 | allow you to specify an ordered list of preferred attributions. | ||
| 2392 | |||
| 2393 | @item | ||
| 2394 | @code{sc-mail-fields-list} has been removed, and header nuking in | ||
| 2395 | general has been greatly improved, giving you wider flexibility in | ||
| 2396 | specifying which headers to keep and remove while presenting a | ||
| 2397 | simplified interface to commonly chosen defaults. | ||
| 2398 | |||
| 2399 | @item | ||
| 2400 | Post-yank paragraph filling has been completely removed from Supercite, | ||
| 2401 | other packages just do it better than Supercite ever would. Supercite | ||
| 2402 | will still fill newly cited paragraphs. | ||
| 2403 | |||
| 2404 | @item | ||
| 2405 | @vindex sc-cite-region-limit | ||
| 2406 | @vindex cite-region-limit | ||
| 2407 | The variable @code{sc-all-but-cite-p} has been replaced by | ||
| 2408 | @code{sc-cite-region-limit}. | ||
| 2409 | |||
| 2410 | @item | ||
| 2411 | Keymap hacking in the reply buffer has been greatly simplified, with, I | ||
| 2412 | believe, little reduction in functionality. | ||
| 2413 | |||
| 2414 | @item | ||
| 2415 | Hacking of the reply buffer's docstring has been completely eliminated. | ||
| 2416 | @end enumerate | ||
| 2417 | |||
| 2418 | @node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top | ||
| 2419 | @comment node-name, next, previous, up | ||
| 2420 | @chapter Thanks and History | 1871 | @chapter Thanks and History |
| 2421 | @ifinfo | ||
| 2422 | 1872 | ||
| 2423 | @end ifinfo | ||
| 2424 | The Supercite package was derived from its predecessor Superyank 1.11 | 1873 | The Supercite package was derived from its predecessor Superyank 1.11 |
| 2425 | which was inspired by various bits of code and ideas from Martin Neitzel | 1874 | which was inspired by various bits of code and ideas from Martin Neitzel |
| 2426 | and Ashwin Ram. They were the folks who came up with the idea of | 1875 | and Ashwin Ram. They were the folks who came up with the idea of |
| @@ -2428,10 +1877,18 @@ non-nested citations and implemented some rough code to provide this | |||
| 2428 | style. Superyank and Supercite version 2 evolved to the point where much | 1877 | style. Superyank and Supercite version 2 evolved to the point where much |
| 2429 | of the attribution selection mechanism was automatic, and features have | 1878 | of the attribution selection mechanism was automatic, and features have |
| 2430 | been continuously added through the comments and suggestions of the | 1879 | been continuously added through the comments and suggestions of the |
| 2431 | Supercite mailing list participants. Supercite version 3 represents a | 1880 | Supercite mailing list participants. |
| 2432 | nearly complete rewrite with many of the algorithms and coding styles | 1881 | |
| 2433 | being vastly improved. Hopefully Supercite version 3 is faster, | 1882 | With version 3, Supercite underwent an almost complete rewrite, |
| 2434 | smaller, and much more flexible than its predecessors. | 1883 | benefitting in a number of ways, including vast improvements in the |
| 1884 | speed of performance, a big reduction in size of the code and in the use | ||
| 1885 | of Emacs resources, and a much cleaner and flexible internal | ||
| 1886 | architecture. Most of this work was internal and not of very great | ||
| 1887 | importance to the casual user. There were some changes at the | ||
| 1888 | user-visible level, but for the most part, the Supercite configuration | ||
| 1889 | variables from version 2 should still be relevant to version 3. | ||
| 1890 | Hopefully Supercite version 3 is faster, smaller, and much more flexible | ||
| 1891 | than its predecessors. | ||
| 2435 | 1892 | ||
| 2436 | In the version 2 manual I thanked some specific people for their help in | 1893 | In the version 2 manual I thanked some specific people for their help in |
| 2437 | developing Supercite 2. You folks know who you are and your continued | 1894 | developing Supercite 2. You folks know who you are and your continued |
| @@ -2445,54 +1902,17 @@ for adding the magic lisp to their code to support this. | |||
| 2445 | 1902 | ||
| 2446 | All who have helped and contributed have been greatly appreciated. | 1903 | All who have helped and contributed have been greatly appreciated. |
| 2447 | 1904 | ||
| 2448 | @node The Supercite Mailing List, GNU Free Documentation License, Thanks and History, Top | 1905 | Supercite was written by Barry Warsaw. |
| 2449 | @comment node-name, next, previous, up | ||
| 2450 | @cindex supercite mailing list address | ||
| 2451 | @cindex mailing list address | ||
| 2452 | @chapter The Supercite Mailing List | ||
| 2453 | @ifinfo | ||
| 2454 | 1906 | ||
| 2455 | @end ifinfo | 1907 | @node GNU Free Documentation License, Concept Index, Thanks and History, Top |
| 2456 | The author runs a simple mail expanding mailing list for discussion of | ||
| 2457 | issues related to Supercite. This includes enhancement requests, bug | ||
| 2458 | reports, general help questions, etc. To subscribe or unsubscribe to | ||
| 2459 | the mailing list, send a request to the administrative address: | ||
| 2460 | |||
| 2461 | @example | ||
| 2462 | supercite-request@@python.org | ||
| 2463 | @end example | ||
| 2464 | |||
| 2465 | Please be sure to include the most reliable and shortest (preferably | ||
| 2466 | Internet) address back to you. To post articles to the list, send your | ||
| 2467 | message to this address (you do not need to be a member to post, but be | ||
| 2468 | sure to indicate this in your article or replies may not be CC'd to | ||
| 2469 | you): | ||
| 2470 | |||
| 2471 | @example | ||
| 2472 | supercite@@python.org | ||
| 2473 | @end example | ||
| 2474 | |||
| 2475 | If you are sending bug reports, they should go to the following address, | ||
| 2476 | but @emph{please}! use the command @code{sc-submit-bug-report} since it | ||
| 2477 | will be much easier for me to duplicate your problem if you do so. It | ||
| 2478 | will set up a mail buffer automatically with this address on the | ||
| 2479 | @samp{To:@:} line: | ||
| 2480 | |||
| 2481 | @example | ||
| 2482 | supercite-help@@python.org | ||
| 2483 | @end example | ||
| 2484 | |||
| 2485 | @node GNU Free Documentation License, Concept Index, The Supercite Mailing List, Top | ||
| 2486 | @appendix GNU Free Documentation License | 1908 | @appendix GNU Free Documentation License |
| 2487 | @include doclicense.texi | 1909 | @include doclicense.texi |
| 2488 | 1910 | ||
| 2489 | @node Concept Index, Command Index, GNU Free Documentation License, Top | 1911 | @node Concept Index, Command Index, GNU Free Documentation License, Top |
| 2490 | @comment node-name, next, previous, up | ||
| 2491 | @unnumbered Concept Index | 1912 | @unnumbered Concept Index |
| 2492 | @printindex cp | 1913 | @printindex cp |
| 2493 | 1914 | ||
| 2494 | @node Command Index, Key Index, Concept Index, Top | 1915 | @node Command Index, Key Index, Concept Index, Top |
| 2495 | @comment node-name, next, previous, up | ||
| 2496 | @unnumbered Command Index | 1916 | @unnumbered Command Index |
| 2497 | @ifinfo | 1917 | @ifinfo |
| 2498 | 1918 | ||
| @@ -2506,12 +1926,10 @@ its @var{command} name. | |||
| 2506 | @printindex fn | 1926 | @printindex fn |
| 2507 | 1927 | ||
| 2508 | @node Key Index, Variable Index, Command Index, Top | 1928 | @node Key Index, Variable Index, Command Index, Top |
| 2509 | @comment node-name, next, previous, up | ||
| 2510 | @unnumbered Key Index | 1929 | @unnumbered Key Index |
| 2511 | @printindex ky | 1930 | @printindex ky |
| 2512 | 1931 | ||
| 2513 | @node Variable Index, , Key Index, Top | 1932 | @node Variable Index, , Key Index, Top |
| 2514 | @comment node-name, next, previous, up | ||
| 2515 | @unnumbered Variable Index | 1933 | @unnumbered Variable Index |
| 2516 | @ifinfo | 1934 | @ifinfo |
| 2517 | 1935 | ||