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