Mercurial > emacs
comparison doc/misc/sc.texi @ 92246:6184e70102de
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".
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Wed, 27 Feb 2008 04:42:14 +0000 |
parents | 5d58981e6690 |
children | eafbd7a5c9be |
comparison
equal
deleted
inserted
replaced
92245:e9a26eb89067 | 92246:6184e70102de |
---|---|
1 \input texinfo @comment -*-texinfo-*- | 1 \input texinfo @comment -*-texinfo-*- |
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 |
9 | 9 |
10 @c @setchapternewpage odd % For book style double sided manual. | 10 @c @setchapternewpage odd % For book style double sided manual. |
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. |
20 | 19 |
21 @quotation | 20 @quotation |
45 * SC: (sc). Supercite lets you cite parts of messages you're | 44 * SC: (sc). Supercite lets you cite parts of messages you're |
46 replying to, in flexible ways. | 45 replying to, in flexible ways. |
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 |
64 @end titlepage | 56 @end titlepage |
65 | 57 |
66 @ifnottex | 58 @ifnottex |
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:: |
76 * Citations:: | 68 * Citations:: |
77 * Getting Connected:: | 69 * Getting Connected:: |
80 * Configuring the Citation Engine:: | 72 * Configuring the Citation Engine:: |
81 * Post-yank Formatting Commands:: | 73 * Post-yank Formatting Commands:: |
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:: |
91 * Command Index:: | 81 * Command Index:: |
92 * Key Index:: | 82 * Key Index:: |
94 @end menu | 84 @end menu |
95 @end ifnottex | 85 @end ifnottex |
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 | 90 |
102 | 91 Supercite is a GNU Emacs package written entirely in Emacs Lisp. It |
103 @end ifinfo | 92 interfaces to most of the commonly used Emacs mail user agents |
104 Supercite version 3.1 is a GNU Emacs package written entirely in Emacs | |
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 |
118 * Usage Overview:: | 103 * Usage Overview:: |
119 * What Supercite Does Not Do:: | 104 * What Supercite Does Not Do:: |
122 @end ifinfo | 107 @end ifinfo |
123 | 108 |
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 | 126 |
168 | |
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 |
173 will create a reply buffer and initialize the outgoing mail headers | 130 will create a reply buffer and initialize the outgoing mail headers |
174 appropriately. The body of the reply will usually be empty at this | 131 appropriately. The body of the reply will usually be empty at this |
182 special text tag. Most MUAs provide some default style of citing; by | 139 special text tag. Most MUAs provide some default style of citing; by |
183 using Supercite you gain a wider flexibility in the look and style of | 140 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 | 145 |
190 | |
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 |
195 be able to yank (and cite) only a portion of the original message. | 149 be able to yank (and cite) only a portion of the original message. |
196 Since Supercite only modifies the text it finds in the reply buffer as | 150 Since Supercite only modifies the text it finds in the reply buffer as |
197 set up by the MUA, it is the MUA's responsibility to do partial yanking. | 151 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 |
205 @code{mail-header-separator} which separates mail headers from message | 158 @code{mail-header-separator} which separates mail headers from message |
206 bodies cannot be modified by Supercite. Supercite, in fact, doesn't | 159 bodies cannot be modified by Supercite. Supercite, in fact, doesn't |
207 know anything about the meaning of these headers, and never ventures | 160 know anything about the meaning of these headers, and never ventures |
208 outside the designated region. @xref{Hints to MUA Authors}, for more | 161 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 | 167 |
216 | |
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 |
221 @code{sc-cite-original} has been added. When @code{sc-cite-original} is | 171 @code{sc-cite-original} has been added. When @code{sc-cite-original} is |
222 executed, the original message must be set up in a very specific way, | 172 executed, the original message must be set up in a very specific way, |
250 | 200 |
251 @cindex filladapt | 201 @cindex filladapt |
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 |
259 as @cite{filladapt} or @cite{gin-mode}. These packages can recognize | 208 as @cite{filladapt} or @cite{gin-mode}. These packages can recognize |
260 Supercited text and will fill them appropriately. Emacs' built-in | 209 Supercited text and will fill them appropriately. Emacs' built-in |
271 but it is also immediately useful with the default configuration, once | 220 but it is also immediately useful with the default configuration, once |
272 it has been properly connected to your MUA. @xref{Getting Connected}, | 221 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 | 228 |
282 | |
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 |
287 an anonymous form of citation; in other words, an indication is made | 232 an anonymous form of citation; in other words, an indication is made |
288 that the cited line was written by someone @emph{other} that the current | 233 that the cited line was written by someone @emph{other} that the current |
340 non-nested citations are used. When non-@code{nil}, nested citations | 285 non-nested citations are used. When non-@code{nil}, nested citations |
341 are used. | 286 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 | 292 |
350 | |
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: |
355 | 296 |
356 @cindex citation leader | 297 @cindex citation leader |
399 of the same elements, sans the attribution string. Supercite is smart | 340 of the same elements, sans the attribution string. Supercite is smart |
400 enough to not put additional spaces between citation delimiters for | 341 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 | 346 |
407 | |
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. |
412 Recognition of cited lines is controlled by variables analogous to those | 350 Recognition of cited lines is controlled by variables analogous to those |
413 that make up the citation string as mentioned previously. | 351 that make up the citation string as mentioned previously. |
446 non-nested citation roots. It is important to remember that if you | 384 non-nested citation roots. It is important to remember that if you |
447 change @code{sc-citation-root-regexp} you should always also change | 385 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 | 395 |
460 | |
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 |
465 the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in | 399 the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in |
466 various places within Supercite, such as in header rewrite functions and | 400 various places within Supercite, such as in header rewrite functions and |
560 If the author's name has more than one middle name, they will appear as | 494 If the author's name has more than one middle name, they will appear as |
561 info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, | 495 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 | 501 |
569 | |
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 |
574 the original author in non-nested citations. Whereas the citation | 505 the original author in non-nested citations. Whereas the citation |
575 string usually only contains a portion of the original author's name, | 506 string usually only contains a portion of the original author's name, |
604 @code{sc-preferred-header-style}. The value of this variable is an | 535 @code{sc-preferred-header-style}. The value of this variable is an |
605 integer which is an index into the @code{sc-rewrite-header-list}, | 536 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 | 542 |
614 | |
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 |
619 of the info key from the info alist will be inserted there. | 546 of the info key from the info alist will be inserted there. |
620 (@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} | 547 (@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} |
687 @code{>>>>> concerning the subject of @var{subject}}@* | 614 @code{>>>>> concerning the subject of @var{subject}}@* |
688 @code{>>>>> see @var{references} for more details} | 615 @code{>>>>> see @var{references} for more details} |
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 | 621 |
696 | |
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 |
701 different reference headers based on the type of reply or forwarding you | 625 different reference headers based on the type of reply or forwarding you |
702 are doing. You may also want to preview the reference header before | 626 are doing. You may also want to preview the reference header before |
785 @vindex electric-mode-hook (sc-) | 709 @vindex electric-mode-hook (sc-) |
786 @noindent | 710 @noindent |
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 | 717 |
795 | 718 |
796 @end ifinfo | 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 |
800 variable. The name of this variable has been agreed to in advance as | 733 variable. The name of this variable has been agreed to in advance as |
801 part of the @dfn{citation interface specification}. By default this | 734 part of the @dfn{citation interface specification}. By default this |
803 ``use your default citation function.'' When you add Supercite's | 736 ``use your default citation function.'' When you add Supercite's |
804 citation function to the hook, thereby giving the variable a | 737 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 |
832 interface specifications, or if you are writing or maintaining an MUA, | 750 interface specifications, or if you are writing or maintaining an MUA, |
833 @pxref{Hints to MUA Authors}. | 751 @pxref{Hints to MUA Authors}. |
838 @findex cite-original (sc-) | 756 @findex cite-original (sc-) |
839 @findex sc-submit-bug-report | 757 @findex sc-submit-bug-report |
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 |
854 @cindex mark | 771 @cindex mark |
855 The function @code{sc-cite-original} is the top-level Supercite function | 772 The function @code{sc-cite-original} is the top-level Supercite function |
856 designed to be run from the citation hook. It expects | 773 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 |
864 The other step in the getting connected process is to make sure your | 781 The other step in the getting connected process is to make sure your |
865 MUA calls @code{sc-cite-original} at the right time. As mentioned | 782 MUA calls @code{sc-cite-original} at the right time. As mentioned |
876 your Emacs maintainer has put Supercite into your dumped Emacs' image. | 793 your Emacs maintainer has put Supercite into your dumped Emacs' image. |
877 In that case, you can use the @code{sc-pre-hook} variable, but this will | 794 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 |
1162 This chapter explains what happens when you reply and yank an original | 802 This chapter explains what happens when you reply and yank an original |
1163 message from an MUA. | 803 message from an MUA. |
1166 * Reply Buffer Initialization:: | 806 * Reply Buffer Initialization:: |
1167 * Filling Cited Text:: | 807 * Filling Cited Text:: |
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 | 814 |
1177 | |
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 |
1182 @enumerate | 818 @enumerate |
1183 @item | 819 @item |
1327 for completeness and backward compatibility. Perhaps it could be used to | 963 for completeness and backward compatibility. Perhaps it could be used to |
1328 reset certain variables set in @code{sc-pre-hook}.@refill | 964 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-) |
1336 @cindex filladapt | 971 @cindex filladapt |
1337 @cindex gin-mode | 972 @cindex gin-mode |
1338 @findex sc-setup-filladapt | 973 @findex sc-setup-filladapt |
1339 @findex setup-filladapt (sc-) | 974 @findex setup-filladapt (sc-) |
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 | 978 |
1344 | |
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 |
1349 manually cite or re-cite text. | 982 manually cite or re-cite text. |
1350 | 983 |
1409 have been widespread complaints on the net about mail and news messages | 1042 have been widespread complaints on the net about mail and news messages |
1410 containing lines greater than about 72 characters. So the default is to | 1043 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 | 1051 |
1421 | |
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 |
1426 a number of heuristics to extract strings which it puts into the | 1055 a number of heuristics to extract strings which it puts into the |
1427 @dfn{attribution association list} or @dfn{attribution alist}. This is | 1056 @dfn{attribution association list} or @dfn{attribution alist}. This is |
1437 * Author Names:: | 1066 * Author Names:: |
1438 @end menu | 1067 @end menu |
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 | 1072 |
1445 | |
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 |
1450 keys which are matched against the attribution alist in the given order. | 1076 keys which are matched against the attribution alist in the given order. |
1451 The first value of a key that produces a non-@code{nil}, non-empty | 1077 The first value of a key that produces a non-@code{nil}, non-empty |
1542 what nickname they would prefer to use, and you can set up this list to | 1168 what nickname they would prefer to use, and you can set up this list to |
1543 match against a specific mail field, e.g., @samp{From:@:}, allowing you | 1169 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 | 1178 |
1555 | |
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 |
1560 @code{sc-default-author-name} and the fallback attribution string is | 1182 @code{sc-default-author-name} and the fallback attribution string is |
1561 contained in the variable @code{sc-default-attribution}. Default values | 1183 contained in the variable @code{sc-default-attribution}. Default values |
1635 to override any automatically derived attribution string when it is only | 1257 to override any automatically derived attribution string when it is only |
1636 one character long; e.g. you prefer to use @code{"initials"} but the | 1258 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 | 1264 |
1644 | |
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-) |
1655 There are a number of Supercite variables that control how author names | 1273 There are a number of Supercite variables that control how author names |
1656 are extracted from the @samp{From:@:} header. Some headers may contain a | 1274 are extracted from the @samp{From:@:} header. Some headers may contain a |
1701 @code{last} or @code{any}. @code{last} always matches against the last | 1319 @code{last} or @code{any}. @code{last} always matches against the last |
1702 word in the name field, while @code{any} matches against every word in | 1320 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 | 1328 |
1712 | |
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 |
1717 Regi-entries (or just @dfn{entry}). Each entry contains a predicate, | 1332 Regi-entries (or just @dfn{entry}). Each entry contains a predicate, |
1718 typically a regular expression, which is matched against a line of text | 1333 typically a regular expression, which is matched against a line of text |
1742 Supercite to recognize such things as uuencoded messages or C code and | 1357 Supercite to recognize such things as uuencoded messages or C code and |
1743 cite or fill those differently than normal text. None of this is | 1358 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 | 1366 |
1753 | |
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: |
1758 | 1370 |
1759 @example | 1371 @example |
1843 @item curentry | 1455 @item curentry |
1844 The current frame entry being interpreted. | 1456 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 | 1462 |
1852 | |
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, |
1857 except through abstract interfaces such as @code{sc-nuke-mail-header}, | 1466 except through abstract interfaces such as @code{sc-nuke-mail-header}, |
1858 et al. | 1467 et al. |
1910 When Supercite is about to cite, uncite, or recite a region, it consults | 1519 When Supercite is about to cite, uncite, or recite a region, it consults |
1911 the appropriate alist and attempts to find a frame to use. If one | 1520 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 | 1528 |
1921 | |
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 |
1926 variety in the keymaps that MUAs set up in their reply buffers, it is | 1532 variety in the keymaps that MUAs set up in their reply buffers, it is |
1927 next to impossible for Supercite to properly sprinkle its commands into | 1533 next to impossible for Supercite to properly sprinkle its commands into |
1943 * Miscellaneous Commands:: | 1549 * Miscellaneous Commands:: |
1944 @end menu | 1550 @end menu |
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 | 1556 |
1952 | |
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 |
1957 paragraph to use a nickname, or manually cite a message when setting | 1560 paragraph to use a nickname, or manually cite a message when setting |
1958 @code{sc-cite-region-limit} to @code{nil}. The following commands | 1561 @code{sc-cite-region-limit} to @code{nil}. The following commands |
1959 perform these functions on the region of text between @samp{point} and | 1562 perform these functions on the region of text between @samp{point} and |
1960 @samp{mark}. Each of them sets the @dfn{undo boundary} before modifying | 1563 @samp{mark}. Each of them sets the @dfn{undo boundary} before modifying |
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 | |
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 | 1566 |
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 |
1976 @findex sc-cite-region | 1570 @findex sc-cite-region |
1980 @vindex pre-cite-hook (sc-) | 1574 @vindex pre-cite-hook (sc-) |
1981 @vindex sc-confirm-always-p | 1575 @vindex sc-confirm-always-p |
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 |
1989 @code{sc-pre-cite-hook} before interpreting the frame. With an optional | 1582 @code{sc-pre-cite-hook} before interpreting the frame. With an optional |
1990 universal argument (@kbd{C-u}), it temporarily sets | 1583 universal argument (@kbd{C-u}), it temporarily sets |
1994 | 1587 |
1995 @findex sc-uncite-region | 1588 @findex sc-uncite-region |
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 |
2003 @code{sc-default-uncite-frame}. It runs the hook | 1595 @code{sc-default-uncite-frame}. It runs the hook |
2004 @code{sc-pre-uncite-hook} before interpreting the frame. | 1596 @code{sc-pre-uncite-hook} before interpreting the frame. |
2006 | 1598 |
2007 @findex sc-recite-region | 1599 @findex sc-recite-region |
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 |
2015 @code{sc-pre-recite-hook} before interpreting the frame. | 1606 @code{sc-pre-recite-hook} before interpreting the frame. |
2016 @xref{Configuring the Citation Engine}.@refill | 1607 @xref{Configuring the Citation Engine}.@refill |
2020 Supercite will always ask you to confirm the attribution when reciting a | 1611 Supercite will always ask you to confirm the attribution when reciting a |
2021 region, regardless of the value of @code{sc-confirm-always-p}. | 1612 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 | 1617 |
2028 | |
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 |
2033 @findex sc-insert-reference | 1621 @findex sc-insert-reference |
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 |
2041 no arguments, the header indexed by @code{sc-preferred-header-style} is | 1628 no arguments, the header indexed by @code{sc-preferred-header-style} is |
2042 inserted. An optional numeric argument is the index into | 1629 inserted. An optional numeric argument is the index into |
2048 | 1635 |
2049 @findex sc-insert-citation | 1636 @findex sc-insert-citation |
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 | 1648 |
2064 | |
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 |
2069 cleanup, but only temporarily. These toggling shortcut commands make | 1652 cleanup, but only temporarily. These toggling shortcut commands make |
2070 this easy to do. | 1653 this easy to do. |
2138 Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) | 1721 Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) |
2139 brings up a Help message on the toggling keymap. | 1722 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 | 1727 |
2146 | |
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 |
2151 | 1731 |
2152 @table @asis | 1732 @table @asis |
2153 @kindex C-c C-p f | 1733 @kindex C-c C-p f |
2154 @findex sc-mail-field-query | 1734 @findex sc-mail-field-query |
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 |
2162 minibuffer. With an argument, this command will first ask if you want | 1741 minibuffer. With an argument, this command will first ask if you want |
2163 to view, modify, add, or delete an info key. Viewing is identical to | 1742 to view, modify, add, or delete an info key. Viewing is identical to |
2165 | 1744 |
2166 If you want to modify the value of a key, Supercite will first prompt | 1745 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. |
2175 | 1753 |
2176 If you choose to add a new key-value pair, Supercite firsts prompts you | 1754 If you choose to add a new key-value pair, Supercite firsts prompts you |
2183 | 1761 |
2184 @findex sc-mail-process-headers | 1762 @findex sc-mail-process-headers |
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 |
2192 Supercite will initially set up its information for the digest | 1769 Supercite will initially set up its information for the digest |
2193 originator, but you want to cite each component article with the real | 1770 originator, but you want to cite each component article with the real |
2194 message author. Note that unless an error during processing occurs, any | 1771 message author. Note that unless an error during processing occurs, any |
2195 old information is lost.@refill | 1772 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 | 1777 |
2202 | |
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 | 1791 |
2251 | |
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 |
2256 MUAs and Supercite (or any future Supercite-like packages). This | 1795 MUAs and Supercite (or any future Supercite-like packages). This |
2257 interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in | 1796 interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in |
2280 @vindex mail-citation-hook | 1819 @vindex mail-citation-hook |
2281 @vindex mail-yank-hooks | 1820 @vindex mail-yank-hooks |
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 |
2299 will be able to link Supercite easily and seamlessly. To do this, when | 1833 will be able to link Supercite easily and seamlessly. To do this, when |
2300 setting up a reply or forward buffer, your MUA should follow these | 1834 setting up a reply or forward buffer, your MUA should follow these |
2314 header in the body of the reply. Set @samp{mark} at the end of the | 1848 header in the body of the reply. Set @samp{mark} at the end of the |
2315 message text. It is very important that the region be set around the | 1849 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 |
2326 provide some kind of default citation functions in cases where the user | 1857 provide some kind of default citation functions in cases where the user |
2327 does not have Supercite installed. By default, your MUA should | 1858 does not have Supercite installed. By default, your MUA should |
2331 default citing behavior. User who want to connect to Supercite then | 1862 default citing behavior. User who want to connect to Supercite then |
2332 need only add @code{sc-cite-original} to this list of hooks using | 1863 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.'' | 1869 |
2339 | 1870 @node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top |
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 | |
2378 @item | |
2379 @code{sc-spacify-name-chars} is gone in version 3. | |
2380 | |
2381 @item | |
2382 @vindex sc-attrib-selection-list | |
2383 @vindex attrib-selection-list | |
2384 @code{sc-nickname-alist} is gone in version 3. The | |
2385 @code{sc-attrib-selection-list} is a more general construct supporting | |
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 | 1872 |
2422 | |
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 |
2427 non-nested citations and implemented some rough code to provide this | 1876 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 |
2438 support is greatly appreciated. I wish to thank everyone on the | 1895 support is greatly appreciated. I wish to thank everyone on the |
2439 Supercite mailing list, especially the brave alpha testers, who helped | 1896 Supercite mailing list, especially the brave alpha testers, who helped |
2443 to a quick agreement on the new @code{mail-citation-hook} interface, and | 1900 to a quick agreement on the new @code{mail-citation-hook} interface, and |
2444 for adding the magic lisp to their code to support this. | 1901 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 | 1906 |
2450 @cindex supercite mailing list address | 1907 @node GNU Free Documentation License, Concept Index, Thanks and History, Top |
2451 @cindex mailing list address | |
2452 @chapter The Supercite Mailing List | |
2453 @ifinfo | |
2454 | |
2455 @end ifinfo | |
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 |
2499 @end ifinfo | 1919 @end ifinfo |
2500 Since all supercite commands are prepended with the string | 1920 Since all supercite commands are prepended with the string |
2504 @sp 2 | 1924 @sp 2 |
2505 @end iftex | 1925 @end iftex |
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 |
2518 @end ifinfo | 1936 @end ifinfo |
2519 Since all supercite variables are prepended with the string | 1937 Since all supercite variables are prepended with the string |