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