|
0
|
1 \input texinfo @comment -*-texinfo-*-
|
|
|
2 @comment 3.47
|
|
|
3 @comment %**start of header (This is for running Texinfo on a region.)
|
|
|
4 @setfilename ../info/supercite.info
|
|
|
5 @settitle Supercite Version 3.1 User's Manual
|
|
|
6 @iftex
|
|
|
7 @finalout
|
|
|
8 @end iftex
|
|
|
9 @c @setchapternewpage odd % For book style double sided manual.
|
|
|
10 @comment %**end of header (This is for running Texinfo on a region.)
|
|
|
11 @c @smallbook
|
|
|
12 @tex
|
|
|
13 \overfullrule=0pt
|
|
|
14 %\global\baselineskip 30pt % For printing in double spaces
|
|
|
15 @end tex
|
|
|
16 @ifinfo
|
|
|
17 This document describes the Supercite Version 3.1 package for citing and
|
|
|
18 attributing the replies for various GNU Emacs mail and news reading
|
|
|
19 subsystems.
|
|
|
20
|
|
|
21 Copyright @copyright{} 1993 Barry A@. Warsaw
|
|
|
22
|
|
|
23 Permission is granted to make and distribute verbatim copies of
|
|
|
24 this manual provided the copyright notice and this permission notice
|
|
|
25 are preserved on all copies.
|
|
|
26
|
|
|
27 @ignore
|
|
|
28 Permission is granted to process this file through TeX and print the
|
|
|
29 results, provided the printed document carries copying permission
|
|
|
30 notice identical to this one except for the removal of this paragraph
|
|
|
31 (this paragraph not being relevant to the printed manual).
|
|
|
32
|
|
|
33 @end ignore
|
|
|
34 @end ifinfo
|
|
|
35 @c
|
|
|
36 @titlepage
|
|
|
37 @sp 6
|
|
|
38 @center @titlefont{Supercite User's Manual}
|
|
|
39 @sp 2
|
|
|
40 @center @titlefont{Supercite Version 3.1}
|
|
|
41 @sp 4
|
|
|
42 @center Manual Revision: 3.47
|
|
|
43 @center August 1993
|
|
|
44 @sp 5
|
|
|
45 @center Barry A@. Warsaw
|
|
|
46 @center @t{bwarsaw@@cen.com}
|
|
|
47 @center @t{@dots{}!uunet!cen.com!bwarsaw}
|
|
|
48 @page
|
|
|
49 @vskip 0pt plus 1filll
|
|
|
50 Copyright @copyright{} 1993 Barry A@. Warsaw
|
|
|
51
|
|
|
52 Permission is granted to make and distribute verbatim copies of
|
|
|
53 this manual provided the copyright notice and this permission notice
|
|
|
54 are preserved on all copies.
|
|
|
55
|
|
|
56 @end titlepage
|
|
|
57 @page
|
|
|
58 @ifinfo
|
|
|
59 @node Top, Introduction, (dir), (dir)
|
|
|
60 @comment node-name, next, previous, up
|
|
|
61
|
|
|
62 This document describes the Supercite Version 3.1 package for citing and
|
|
|
63 attributing the replies for various GNU Emacs mail and news reading
|
|
|
64 subsystems. The manual is divided into the following chapters.
|
|
|
65
|
|
|
66 @menu
|
|
|
67 * Introduction::
|
|
|
68 * Citations::
|
|
|
69 * Getting Connected::
|
|
|
70 * Replying and Yanking::
|
|
|
71 * Selecting an Attribution::
|
|
|
72 * Configuring the Citation Engine::
|
|
|
73 * Post-yank Formatting Commands::
|
|
|
74 * Information Keys and the Info Alist::
|
|
|
75 * Reference Headers::
|
|
|
76 * Hints to MUA Authors::
|
|
|
77 * Version 3 Changes::
|
|
|
78 * Thanks and History::
|
|
|
79 * The Supercite Mailing List::
|
|
|
80
|
|
|
81 * Concept Index::
|
|
|
82 * Command Index::
|
|
|
83 * Key Index::
|
|
|
84 * Variable Index::
|
|
|
85 @end menu
|
|
|
86 @end ifinfo
|
|
|
87
|
|
|
88 @node Introduction, Usage Overview, Top, Top
|
|
|
89 @comment node-name, next, previous, up
|
|
|
90 @chapter Introduction
|
|
|
91 @ifinfo
|
|
|
92
|
|
|
93 @end ifinfo
|
|
|
94 Supercite version 3.1 is a GNU Emacs package written entirely in Emacs
|
|
|
95 Lisp. It interfaces to most of the commonly used Emacs mail user agents
|
|
|
96 (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
|
|
|
97 sophisticated facilities for the citing and attributing of message
|
|
|
98 replies. Supercite has a very specific and limited role in the process
|
|
|
99 of composing replies to both USENET network news and electronic mail.
|
|
|
100
|
|
|
101 The preferred way to spell Supercite is with a capital @samp{S},
|
|
|
102 lowercase @samp{upercite}. There are a few alternate spellings out there
|
|
|
103 and I won't be terribly offended if you use them. People often ask
|
|
|
104 though@dots{}
|
|
|
105
|
|
|
106 @ifinfo
|
|
|
107 @menu
|
|
|
108 * Usage Overview::
|
|
|
109 * What Supercite Does Not Do::
|
|
|
110 * What Supercite Does::
|
|
|
111 @end menu
|
|
|
112 @end ifinfo
|
|
|
113
|
|
|
114 @cindex MUA
|
|
|
115 @cindex NUA
|
|
|
116 Supercite is only useful in conjunction with MUAs and NUAs such as VM,
|
|
|
117 GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs).
|
|
|
118 Supercite is typically called by the MUA after a reply buffer has been
|
|
|
119 setup. Thereafter, Supercite's many commands and formatting styles are
|
|
|
120 available in that reply buffer until the reply is sent. Supercite is
|
|
|
121 re-initialized in each new reply buffer.
|
|
|
122
|
|
|
123 Supercite is currently at major revision 3.1, and is known to work in the
|
|
|
124 following environments:
|
|
|
125
|
|
|
126 @table @asis
|
|
|
127 @item Emacsen:
|
|
|
128 GNU Emacs 18.57 through 18.59, all current FSF Emacs 19,
|
|
|
129 all current Lucid Emacs 19, and Epoch 4.@refill
|
|
|
130
|
|
|
131 @item MUAs:
|
|
|
132 VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
|
|
|
133 beyond, PCMAIL.@refill
|
|
|
134
|
|
|
135 @item NUAs:
|
|
|
136 RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
|
|
|
137
|
|
|
138 @end table
|
|
|
139 For systems with version numbers, all known subsequent versions also
|
|
|
140 work with Supercite. For those systems without version numbers,
|
|
|
141 Supercite probably works with any recently released version. Note that
|
|
|
142 only some of these systems will work with Supercite ``out of the box.''
|
|
|
143 All others must overload interfacing routines to supply the necessary
|
|
|
144 glue. @xref{Getting Connected} for more details.@refill
|
|
|
145
|
|
|
146
|
|
|
147 @node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
|
|
|
148 @comment node-name, next, previous, up
|
|
|
149 @kindex r
|
|
|
150 @kindex f
|
|
|
151 @kindex C-c C-y
|
|
|
152 @cindex yank
|
|
|
153 @cindex cite, citing
|
|
|
154 @cindex attribute, attributing
|
|
|
155 @comment
|
|
|
156 @section Usage Overview
|
|
|
157 @ifinfo
|
|
|
158
|
|
|
159 @end ifinfo
|
|
|
160 Typical usage is as follows. You want to reply or followup to a message
|
|
|
161 in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
|
|
|
162 (i.e., ``forward'') to begin composing the reply. In response, the MUA
|
|
|
163 will create a reply buffer and initialize the outgoing mail headers
|
|
|
164 appropriately. The body of the reply will usually be empty at this
|
|
|
165 point. You now decide that you would like to include part of the
|
|
|
166 original message in your reply. To do this, you @dfn{yank} the original
|
|
|
167 message into the reply buffer, typically with a key stroke such as
|
|
|
168 @kbd{C-c C-y}. This sequence will invoke an MUA-specific function which
|
|
|
169 fills the body of the reply with the original message and then
|
|
|
170 @dfn{attributes} this text to its author. This is called @dfn{citing}
|
|
|
171 and its effect is to prefix every line from the original message with a
|
|
|
172 special text tag. Most MUAs provide some default style of citing; by
|
|
|
173 using Supercite you gain a wider flexibility in the look and style of
|
|
|
174 citations. Supercite's only job is to cite the original message.
|
|
|
175
|
|
|
176 @node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
|
|
|
177 @comment node-name, next, previous, up
|
|
|
178 @section What Supercite Doesn't Do
|
|
|
179 @ifinfo
|
|
|
180
|
|
|
181 @end ifinfo
|
|
|
182 Because of this clear division of labor, there are useful features which
|
|
|
183 are the sole responsibility of the MUA, even though it might seem that
|
|
|
184 Supercite should provide them. For example, many people would like to
|
|
|
185 be able to yank (and cite) only a portion of the original message.
|
|
|
186 Since Supercite only modifies the text it finds in the reply buffer as
|
|
|
187 set up by the MUA, it is the MUA's responsibility to do partial yanking.
|
|
|
188 @xref{Reply Buffer Initialization}.@refill
|
|
|
189
|
|
|
190 @vindex mail-header-separator
|
|
|
191 @comment
|
|
|
192 Another potentially useful thing would be for Supercite to set up the
|
|
|
193 outgoing mail headers with information it gleans from the reply buffer.
|
|
|
194 But by previously agreed upon convention, any text above the
|
|
|
195 @code{mail-header-separator} which separates mail headers from message
|
|
|
196 bodies cannot be modified by Supercite. Supercite, in fact, doesn't
|
|
|
197 know anything about the meaning of these headers, and never ventures
|
|
|
198 outside the designated region. @xref{Hints to MUA Authors} for more
|
|
|
199 details.@refill
|
|
|
200
|
|
|
201 @node What Supercite Does, Citations, What Supercite Does Not Do, Introduction
|
|
|
202 @comment node-name, next, previous, up
|
|
|
203 @findex sc-cite-original
|
|
|
204 @section What Supercite Does
|
|
|
205 @ifinfo
|
|
|
206
|
|
|
207 @end ifinfo
|
|
|
208 Supercite is invoked for the first time on a reply buffer via your MUA's
|
|
|
209 reply or forward command. This command will actually perform citations
|
|
|
210 by calling a hook variable to which Supercite's top-level function
|
|
|
211 @code{sc-cite-original} has been added. When @code{sc-cite-original} is
|
|
|
212 executed, the original message must be set up in a very specific way,
|
|
|
213 but this is handled automatically by the MUA. @xref{Hints to MUA
|
|
|
214 Authors}.@refill
|
|
|
215
|
|
|
216 @cindex info alist
|
|
|
217 The first thing Supercite does, via @code{sc-cite-original}, is to parse
|
|
|
218 through the original message's mail headers. It saves this data in an
|
|
|
219 @dfn{information association list}, or @dfn{info alist}. The information
|
|
|
220 in this list is used in a number of places throughout Supercite.
|
|
|
221 @xref{Information Keys and the Info Alist}.@refill
|
|
|
222
|
|
|
223 @cindex nuking mail headers
|
|
|
224 @cindex reference header
|
|
|
225 After the mail header info is extracted, the headers are optionally
|
|
|
226 removed (@dfn{nuked}) from the reply. Supercite then writes a
|
|
|
227 @dfn{reference header} into the buffer. This reference header is a
|
|
|
228 string carrying details about the citation it is about to perform.
|
|
|
229
|
|
|
230 @cindex modeline
|
|
|
231 Next, Supercite visits each line in the reply, transforming the line
|
|
|
232 according to a customizable ``script''. Lines which were not previously
|
|
|
233 cited in the original message are given a citation, while already cited
|
|
|
234 lines remain untouched, or are coerced to your preferred style.
|
|
|
235 Finally, Supercite installs a keymap into the reply buffer so that you
|
|
|
236 have access to Supercite's post-yank formatting and reciting commands as
|
|
|
237 you subsequently edit your reply. You can tell that Supercite has been
|
|
|
238 installed into the reply buffer because that buffer's modeline will
|
|
|
239 display the minor mode string @samp{SC}.
|
|
|
240
|
|
|
241 @cindex filladapt
|
|
|
242 @cindex gin-mode
|
|
|
243 @vindex fill-prefix
|
|
|
244 @findex fill-paragraph
|
|
|
245 @comment
|
|
|
246 When the original message is cited by @code{sc-cite-original}, it will
|
|
|
247 (optionally) be filled by Supercite. However, if you manually edit the
|
|
|
248 cited text and want to re-fill it, you must use an add-on package such
|
|
|
249 as @cite{filladapt} or @cite{gin-mode}. These packages can recognize
|
|
|
250 Supercited text and will fill them appropriately. Emacs' built-in
|
|
|
251 filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
|
|
|
252 text and will not re-fill them properly because it cannot guess the
|
|
|
253 @code{fill-prefix} being used.
|
|
|
254 @xref{Post-yank Formatting Commands} for details.@refill
|
|
|
255
|
|
|
256 As mentioned above, Supercite provides commands to recite or uncite
|
|
|
257 regions of text in the reply buffer, and commands to perform other
|
|
|
258 beautifications on the cited original text, maintaining consistent and
|
|
|
259 informative citations throughout. Supercite tries to be as configurable
|
|
|
260 as possible to allow for a wide range of personalized citation styles,
|
|
|
261 but it is also immediately useful with the default configuration, once
|
|
|
262 it has been properly connected to your MUA. @xref{Getting Connected}
|
|
|
263 for more details.@refill
|
|
|
264
|
|
|
265 @node Citations, Citation Elements, What Supercite Does, Top
|
|
|
266 @comment node-name, next, previous, up
|
|
|
267 @cindex nested citations
|
|
|
268 @cindex citation
|
|
|
269 @comment
|
|
|
270 @chapter Citations
|
|
|
271 @ifinfo
|
|
|
272
|
|
|
273 @end ifinfo
|
|
|
274 A @dfn{citation} is the acknowledgement of the original author of a mail
|
|
|
275 message in the body of the reply. There are two basic citation styles
|
|
|
276 which Supercite supports. The first, called @dfn{nested citations} is
|
|
|
277 an anonymous form of citation; in other words, an indication is made
|
|
|
278 that the cited line was written by someone @emph{other} that the current
|
|
|
279 message author (i.e., other than you, the person composing the reply),
|
|
|
280 but no reference is made as to the identity of the original author.
|
|
|
281 This style should look familiar since its use on the net is widespread.
|
|
|
282 Here's an example of what a message buffer would look like using nested
|
|
|
283 citations after multiple replies:
|
|
|
284
|
|
|
285 @example
|
|
|
286 >> John originally wrote this
|
|
|
287 >> and this as well
|
|
|
288 > Jane said that John didn't know
|
|
|
289 > what he was talking about
|
|
|
290 And that's what I think too.
|
|
|
291 @end example
|
|
|
292
|
|
|
293 @ifinfo
|
|
|
294 @menu
|
|
|
295 * Citation Elements::
|
|
|
296 * Recognizing Citations::
|
|
|
297 @end menu
|
|
|
298 @end ifinfo
|
|
|
299
|
|
|
300 Note that multiple inclusions of the original messages result in a
|
|
|
301 nesting of the @samp{@code{>}} characters. This can sometimes be quite
|
|
|
302 confusing when many levels of citations are included since it may be
|
|
|
303 difficult or impossible to figure out who actually participated in the
|
|
|
304 thread, and multiple nesting of @samp{@code{>}} characters can sometimes
|
|
|
305 make the message very difficult for the eye to scan.
|
|
|
306
|
|
|
307 @cindex non-nested citations
|
|
|
308 In @dfn{non-nested citations}, each cited line begins with an
|
|
|
309 informative string attributing that line to the original author. Only
|
|
|
310 the first level of attribution will be shown; subsequent citations don't
|
|
|
311 nest the citation strings. The above dialog might look like this when
|
|
|
312 non-nested citations are used:
|
|
|
313
|
|
|
314 @example
|
|
|
315 John> John originally wrote this
|
|
|
316 John> and this as well
|
|
|
317 Jane> Jane said that John didn't know
|
|
|
318 Jane> what he was talking about
|
|
|
319 And that's what I think too.
|
|
|
320 @end example
|
|
|
321
|
|
|
322 Notice here that my inclusion of Jane's inclusion of John's original
|
|
|
323 message did not result in a line cited with @samp{Jane>John>}.
|
|
|
324
|
|
|
325 @vindex sc-nested-citation-p
|
|
|
326 @vindex nested-citation-p (sc-)
|
|
|
327 Supercite supports both styles of citation, and the variable
|
|
|
328 @code{sc-nested-citation-p} controls which style it will use when citing
|
|
|
329 previously uncited text. When this variable is @code{nil} (the default),
|
|
|
330 non-nested citations are used. When non-@code{nil}, nested citations
|
|
|
331 are used.
|
|
|
332
|
|
|
333
|
|
|
334 @node Citation Elements, Recognizing Citations, Citations, Citations
|
|
|
335 @comment node-name, next, previous, up
|
|
|
336 @cindex citation string
|
|
|
337 @comment
|
|
|
338 @section Citation Elements
|
|
|
339 @ifinfo
|
|
|
340
|
|
|
341 @end ifinfo
|
|
|
342 @dfn{Citation strings} are composed of one or more elements. Non-nested
|
|
|
343 citations are composed of four elements, three of which are directly
|
|
|
344 user definable. The elements are concatenated together, in this order:
|
|
|
345
|
|
|
346 @cindex citation leader
|
|
|
347 @vindex citation-leader (sc-)
|
|
|
348 @vindex sc-citation-leader
|
|
|
349 @enumerate
|
|
|
350 @item
|
|
|
351 The @dfn{citation leader}. The citation leader is contained in the
|
|
|
352 variable @code{sc-citation-leader}, and has the default value of a
|
|
|
353 string containing four spaces.
|
|
|
354
|
|
|
355 @cindex attribution string
|
|
|
356 @item
|
|
|
357 The @dfn{attribution string}. This element is supplied automatically by
|
|
|
358 Supercite, based on your preferences and the original message's mail
|
|
|
359 headers, though you may be asked to confirm Supercite's choice.
|
|
|
360 @xref{Selecting an Attribution} for more details.@refill
|
|
|
361
|
|
|
362 @cindex citation delimiter
|
|
|
363 @vindex sc-citation-delimiter
|
|
|
364 @vindex citation-delimiter (sc-)
|
|
|
365 @item
|
|
|
366 The @dfn{citation delimiter}. This string, contained in the variable
|
|
|
367 @code{sc-citation-delimiter} visually separates the citation from the
|
|
|
368 text of the line. This variable has a default value of @code{">"} and
|
|
|
369 for best results, the string should consist of only a single character.
|
|
|
370
|
|
|
371 @cindex citation separator
|
|
|
372 @vindex citation-separator (sc-)
|
|
|
373 @vindex sc-citation-separator
|
|
|
374 @item
|
|
|
375 The @dfn{citation separator}. The citation separator is contained in
|
|
|
376 the variable @code{sc-citation-separator}, and has the default value of
|
|
|
377 a string containing a single space.
|
|
|
378 @end enumerate
|
|
|
379
|
|
|
380 For example, suppose you were using the default values for the above
|
|
|
381 variables, and Supercite provided the attribution string @samp{Jane}.
|
|
|
382 In this case, the composed, non-nested citation string used might be
|
|
|
383 something like
|
|
|
384 @code{@asis{" Jane> "}}.
|
|
|
385 This citation string will be inserted in front of
|
|
|
386 every line in the original message that is not already cited.@refill
|
|
|
387
|
|
|
388 Nested citations, being simpler than non-nested citations, are composed
|
|
|
389 of the same elements, sans the attribution string. Supercite is smart
|
|
|
390 enough to not put additional spaces between citation delimiters for
|
|
|
391 multi-level nested citations.
|
|
|
392
|
|
|
393 @node Recognizing Citations, Getting Connected, Citation Elements, Citations
|
|
|
394 @comment node-name, next, previous, up
|
|
|
395 @section Recognizing Citations
|
|
|
396 @ifinfo
|
|
|
397
|
|
|
398 @end ifinfo
|
|
|
399 Supercite also recognizes citations in the original article, and can
|
|
|
400 transform these already cited lines in a number of ways. This is how
|
|
|
401 Supercite suppresses the multiple citing of non-nested citations.
|
|
|
402 Recognition of cited lines is controlled by variables analogous to those
|
|
|
403 that make up the citation string as mentioned previously.
|
|
|
404
|
|
|
405 @vindex sc-citation-leader-regexp
|
|
|
406 @vindex citation-leader-regexp (sc-)
|
|
|
407 @vindex sc-citation-delimiter-regexp
|
|
|
408 @vindex citation-delimiter-regexp (sc-)
|
|
|
409 @vindex sc-citation-separator-regexp
|
|
|
410 @vindex citation-separator-regexp (sc-)
|
|
|
411 @vindex sc-citation-root-regexp
|
|
|
412 @vindex citation-root-regexp (sc-)
|
|
|
413 @vindex sc-citation-nonnested-root-regexp
|
|
|
414 @vindex citation-nonnested-root-regexp (sc-)
|
|
|
415
|
|
|
416 The variable @code{sc-citation-leader-regexp} describes how citation
|
|
|
417 leaders can look, by default it matches any number of spaces or tabs.
|
|
|
418 Note that since the lisp function @code{looking-at} is used to do the
|
|
|
419 matching, if you change this variable it need not start with a leading
|
|
|
420 @code{"^"}.
|
|
|
421
|
|
|
422 Similarly, the variables @code{sc-citation-delimiter-regexp} and
|
|
|
423 @code{sc-citation-separator-regexp} respectively describe how citation
|
|
|
424 delimiters and separators can look. They follow the same rule as
|
|
|
425 @code{sc-citation-leader-regexp} above.
|
|
|
426
|
|
|
427 When Supercite composes a citation string, it provides the attribution
|
|
|
428 automatically. The analogous variable which handles recognition of the
|
|
|
429 attribution part of citation strings is @code{sc-citation-root-regexp}.
|
|
|
430 This variable describes the attribution root for both nested and
|
|
|
431 non-nested citations. By default it can match zero-to-many alphanumeric
|
|
|
432 characters (also ``.'', ``-'', and ``_''). But in some situations,
|
|
|
433 Supercite has to determine whether it is looking at a nested or
|
|
|
434 non-nested citation. Thus the variable
|
|
|
435 @code{sc-citation-nonnested-root-regexp} is used to describe only
|
|
|
436 non-nested citation roots. It is important to remember that if you
|
|
|
437 change @code{sc-citation-root-regexp} you should always also change
|
|
|
438 @code{sc-citation-nonnested-root-regexp}.@refill
|
|
|
439
|
|
|
440 Nemacs users:@: For best results, try setting
|
|
|
441 @code{sc-citation-root-regexp} to:@refill
|
|
|
442
|
|
|
443 @example
|
|
|
444 "\\([-._a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\|\\ca\\|\\cg\\|\\cr\\|\\cu\\)*"
|
|
|
445 @end example
|
|
|
446
|
|
|
447 Mule users:@: For best results, try setting
|
|
|
448 @code{sc-citation-root-regexp} to:@refill
|
|
|
449
|
|
|
450 @example
|
|
|
451 "\\([-._a-zA-Z0-9]\\|\\cj\\)*"
|
|
|
452 @end example
|
|
|
453
|
|
|
454 @node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
|
|
|
455 @comment node-name, next, previous, up
|
|
|
456 @cindex information keys
|
|
|
457 @cindex Info Alist
|
|
|
458 @cindex information extracted from mail fields
|
|
|
459 @findex sc-mail-field
|
|
|
460 @findex mail-field (sc-)
|
|
|
461 @comment
|
|
|
462 @chapter Information Keys and the Info Alist
|
|
|
463 @ifinfo
|
|
|
464
|
|
|
465 @end ifinfo
|
|
|
466 @dfn{Mail header information keys} are nuggets of information that
|
|
|
467 Supercite extracts from the various mail headers of the original
|
|
|
468 message, placed in the reply buffer by the MUA. Information is kept in
|
|
|
469 the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
|
|
|
470 various places within Supercite, such as in header rewrite functions and
|
|
|
471 attribution selection. Other bits of data, composed and created by
|
|
|
472 Supercite, are also kept as key-value pairs in this alist. In the case
|
|
|
473 of mail fields, the key is the name of the field, omitting the trailing
|
|
|
474 colon. Info keys are always case insensitive (as are mail headers), and
|
|
|
475 the value for a corresponding key can be retrieved from the alist with
|
|
|
476 the @code{sc-mail-field} function. Thus, if the following fields were
|
|
|
477 present in the original article:@refill
|
|
|
478
|
|
|
479 @example
|
|
|
480 Date:@: 08 April 1991, 17:32:09 EST
|
|
|
481 Subject:@: Better get out your asbestos suit
|
|
|
482 @end example
|
|
|
483
|
|
|
484 @vindex sc-mumble
|
|
|
485 @vindex mumble (sc-)
|
|
|
486 @noindent
|
|
|
487 then, the following lisp constructs return:
|
|
|
488
|
|
|
489 @example
|
|
|
490 (sc-mail-field "date")
|
|
|
491 ==> "08 April 1991, 17:32:09 EST"
|
|
|
492
|
|
|
493 (sc-mail-field "subject")
|
|
|
494 ==> "Better get out your asbestos suit"
|
|
|
495 @end example
|
|
|
496
|
|
|
497 Since the argument to @code{sc-mail-field} can be any string, it is
|
|
|
498 possible that the mail field will not be present on the info alist
|
|
|
499 (possibly because the mail header was not present in the original
|
|
|
500 message). In this case, @code{sc-mail-field} will return the value of
|
|
|
501 the variable @code{sc-mumble}.
|
|
|
502
|
|
|
503 Supercite always places all mail fields found in the yanked original
|
|
|
504 article into the info alist. If possible, Supercite will also places
|
|
|
505 the following keys into the info alist:
|
|
|
506
|
|
|
507 @table @code
|
|
|
508 @cindex sc-attribution info field
|
|
|
509 @cindex attribution info field (sc-)
|
|
|
510 @item "sc-attribution"
|
|
|
511 the selected attribution string.
|
|
|
512
|
|
|
513 @cindex sc-citation info field
|
|
|
514 @cindex citation info field (sc-)
|
|
|
515 @item "sc-citation"
|
|
|
516 the non-nested citation string.
|
|
|
517
|
|
|
518 @cindex sc-from-address info field
|
|
|
519 @cindex from-address info field (sc-)
|
|
|
520 @item "sc-from-address"
|
|
|
521 email address extracted from the @samp{From:@:} field.
|
|
|
522
|
|
|
523 @cindex sc-reply-address info field
|
|
|
524 @cindex reply-address info field (sc-)
|
|
|
525 @item "sc-reply-address"
|
|
|
526 email address extracted from the @samp{Reply-To:@:} field.
|
|
|
527
|
|
|
528 @cindex sc-sender-address info field
|
|
|
529 @cindex sender-address info field (sc-)
|
|
|
530 @item "sc-sender-address"
|
|
|
531 email address extracted from the @samp{Sender:@:} field.
|
|
|
532
|
|
|
533 @cindex sc-emailname info field
|
|
|
534 @cindex emailname info field (sc-)
|
|
|
535 @item "sc-emailname"
|
|
|
536 email terminus extracted from the @samp{From:@:} field.
|
|
|
537
|
|
|
538 @cindex sc-initials info field
|
|
|
539 @cindex initials info field (sc-)
|
|
|
540 @item "sc-initials"
|
|
|
541 the author's initials.
|
|
|
542
|
|
|
543 @cindex sc-author info field
|
|
|
544 @cindex author info field (sc-)
|
|
|
545 @item "sc-author"
|
|
|
546 the author's full name.
|
|
|
547
|
|
|
548 @cindex sc-firstname info field
|
|
|
549 @cindex firstname info field (sc-)
|
|
|
550 @item "sc-firstname"
|
|
|
551 the author's first name.
|
|
|
552
|
|
|
553 @cindex sc-lastname info field
|
|
|
554 @cindex lastname info field (sc-)
|
|
|
555 @item "sc-lastname"
|
|
|
556 the author's last name.
|
|
|
557
|
|
|
558 @cindex sc-middlename-1 info field
|
|
|
559 @cindex middlename-1 info field (sc-)
|
|
|
560 @item "sc-middlename-1"
|
|
|
561 the author's first middle name.
|
|
|
562 @end table
|
|
|
563
|
|
|
564 If the author's name has more than one middle name, they will appear as
|
|
|
565 info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
|
|
|
566 @dots{}). @xref{Selecting an Attribution}.@refill
|
|
|
567
|
|
|
568 @node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
|
|
|
569 @comment node-name, next, previous, up
|
|
|
570 @cindex reference headers
|
|
|
571 @chapter Reference Headers
|
|
|
572 @ifinfo
|
|
|
573
|
|
|
574 @end ifinfo
|
|
|
575 Supercite will insert an informative @dfn{reference header} at the
|
|
|
576 beginning of the cited body of text, which display more detail about the
|
|
|
577 original article and provides the mapping between the attribution and
|
|
|
578 the original author in non-nested citations. Whereas the citation
|
|
|
579 string usually only contains a portion of the original author's name,
|
|
|
580 the reference header can contain such information as the author's full
|
|
|
581 name, email address, the original article's subject, etc. In fact any
|
|
|
582 information contained in the info alist can be inserted into a reference
|
|
|
583 header.
|
|
|
584
|
|
|
585 @ifinfo
|
|
|
586 @menu
|
|
|
587 * The Built-in Header Rewrite Functions::
|
|
|
588 * Electric References::
|
|
|
589 @end menu
|
|
|
590 @end ifinfo
|
|
|
591
|
|
|
592 @cindex header rewrite functions
|
|
|
593 @vindex sc-rewrite-header-list
|
|
|
594 @vindex rewrite-header-list (sc-)
|
|
|
595 There are a number of built-in @dfn{header rewrite functions} supplied
|
|
|
596 by Supercite, but you can write your own custom header rewrite functions
|
|
|
597 (perhaps using the built-in ones as examples). The variable
|
|
|
598 @code{sc-rewrite-header-list} contains the list of such header rewrite
|
|
|
599 functions. This list is consulted both when inserting the initial
|
|
|
600 reference header, and when displaying @dfn{electric references}.
|
|
|
601 @xref{Electric References}.
|
|
|
602
|
|
|
603 @vindex sc-preferred-header-style
|
|
|
604 @vindex preferred-header-style (sc-)
|
|
|
605 When Supercite is initially run on a reply buffer (via
|
|
|
606 @code{sc-cite-original}), it will automatically call one of these
|
|
|
607 functions. The one it uses is defined in the variable
|
|
|
608 @code{sc-preferred-header-style}. The value of this variable is an
|
|
|
609 integer which is an index into the @code{sc-rewrite-header-list},
|
|
|
610 beginning at zero.
|
|
|
611
|
|
|
612 @node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
|
|
|
613 @comment node-name, next, previous, up
|
|
|
614 @cindex header rewrite functions, built-in
|
|
|
615 @comment
|
|
|
616 @section The Built-in Header Rewrite Functions
|
|
|
617 @ifinfo
|
|
|
618
|
|
|
619 @end ifinfo
|
|
|
620 Below are examples of the various built-in header rewrite functions.
|
|
|
621 Please note the following:@: first, the text which appears in the
|
|
|
622 examples below as @var{infokey} indicates that the corresponding value
|
|
|
623 of the info key from the info alist will be inserted there.
|
|
|
624 (@xref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said}
|
|
|
625 below, @var{date} and @var{from} correspond to the values of the
|
|
|
626 @samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill
|
|
|
627
|
|
|
628 @vindex sc-reference-tag-string
|
|
|
629 @vindex reference-tag-string (sc-)
|
|
|
630 Also, the string @code{">>>>>"} below is really the value of the
|
|
|
631 variable @code{sc-reference-tag-string}. This variable is used in all
|
|
|
632 built-in header rewrite functions, and you can customize its value to
|
|
|
633 change the tag string globally.
|
|
|
634
|
|
|
635 Finally, the references headers actually written may omit certain parts
|
|
|
636 of the header if the info key associated with @var{infokey} is not
|
|
|
637 present in the info alist. In fact, for all built-in headers, if the
|
|
|
638 @samp{From:@:} field is not present in the mail headers, the entire
|
|
|
639 reference header will be omitted (but this usually signals a serious
|
|
|
640 problem either in your MUA or in Supercite's installation).
|
|
|
641
|
|
|
642 @table @code
|
|
|
643 @findex sc-no-header
|
|
|
644 @findex no-header (sc-)
|
|
|
645 @item sc-no-header
|
|
|
646 This function produces no header. It should be used instead of
|
|
|
647 @code{nil} to produce a blank header. This header can possibly contain
|
|
|
648 a blank line after the @code{mail-header-separator} line.
|
|
|
649
|
|
|
650 @item sc-no-blank-line-or-header
|
|
|
651 @findex sc-no-blank-line-or-header
|
|
|
652 @findex no-blank-line-or-header (sc-)
|
|
|
653 This function is similar to @code{sc-no-header} except that any blank
|
|
|
654 line after the @code{mail-header-separator} line will be removed.
|
|
|
655
|
|
|
656 @item sc-header-on-said
|
|
|
657 @findex sc-header-on-said
|
|
|
658 @findex header-on-said (sc-)
|
|
|
659 @code{>>>>> On @var{date}, @var{from} said:}
|
|
|
660
|
|
|
661 @item sc-header-inarticle-writes
|
|
|
662 @findex sc-header-inarticle-writes
|
|
|
663 @findex header-inarticle-writes (sc-)
|
|
|
664 @code{>>>>> In article @var{message-id}, @var{from} writes:}
|
|
|
665
|
|
|
666 @item sc-header-regarding-adds
|
|
|
667 @findex sc-header-regarding-adds
|
|
|
668 @findex header-regarding-adds (sc-)
|
|
|
669 @code{>>>>> Regarding @var{subject}; @var{from} adds:}
|
|
|
670
|
|
|
671 @item sc-header-attributed-writes
|
|
|
672 @findex sc-header-attributed-writes
|
|
|
673 @findex header-attributed-writes (sc-)
|
|
|
674 @code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:}
|
|
|
675
|
|
|
676 @item sc-header-author-writes
|
|
|
677 @findex sc-header-author-writes
|
|
|
678 @findex header-author-writes (sc-)
|
|
|
679 @code{>>>>> @var{sc-author} writes:}
|
|
|
680
|
|
|
681 @item sc-header-verbose
|
|
|
682 @findex sc-header-verbose
|
|
|
683 @findex header-verbose (sc-)
|
|
|
684 @code{>>>>> On @var{date},}@*
|
|
|
685 @code{>>>>> @var{sc-author}}@*
|
|
|
686 @code{>>>>> from the organization of @var{organization}}@*
|
|
|
687 @code{>>>>> who can be reached at:@: @var{sc-reply-address}}@*
|
|
|
688 @code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@*
|
|
|
689 @code{>>>>> had this to say in article @var{message-id}}@*
|
|
|
690 @code{>>>>> in newsgroups @var{newsgroups}}@*
|
|
|
691 @code{>>>>> concerning the subject of @var{subject}}@*
|
|
|
692 @code{>>>>> see @var{references} for more details}
|
|
|
693 @end table
|
|
|
694
|
|
|
695 @node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
|
|
|
696 @comment node-name, next, previous, up
|
|
|
697 @cindex electric references
|
|
|
698 @section Electric References
|
|
|
699 @ifinfo
|
|
|
700
|
|
|
701 @end ifinfo
|
|
|
702 By default, when Supercite cites the original message for the first
|
|
|
703 time, it just goes ahead and inserts the reference header indexed by
|
|
|
704 @code{sc-preferred-header-style}. However, you may want to select
|
|
|
705 different reference headers based on the type of reply or forwarding you
|
|
|
706 are doing. You may also want to preview the reference header before
|
|
|
707 deciding whether to insert it into the reply buffer or not. Supercite
|
|
|
708 provides an optional @dfn{electric reference} mode which you can drop
|
|
|
709 into to give you this functionality.
|
|
|
710
|
|
|
711 @vindex sc-electric-references-p
|
|
|
712 @vindex electric-references-p (sc-)
|
|
|
713 If the variable @code{sc-electric-references-p} is non-@code{nil},
|
|
|
714 Supercite will bring up an electric reference mode buffer and place you
|
|
|
715 into a recursive edit. The electric reference buffer is read-only, so
|
|
|
716 you cannot directly modify the reference text until you exit electric
|
|
|
717 references and insert the text into the reply buffer. But you can cycle
|
|
|
718 through all the reference header rewrite functions in your
|
|
|
719 @code{sc-rewrite-header-list}.
|
|
|
720
|
|
|
721 You can also set a new preferred header style, jump to any header, or
|
|
|
722 jump to the preferred header. The header will be shown in the electric
|
|
|
723 reference buffer and the header index and function name will appear in
|
|
|
724 the echo area.
|
|
|
725
|
|
|
726 The following commands are available while in electric reference mode
|
|
|
727 (shown here with their default key bindings):
|
|
|
728
|
|
|
729 @table @asis
|
|
|
730 @item @code{sc-eref-next} (@kbd{n})
|
|
|
731 @findex sc-eref-next
|
|
|
732 @findex eref-next (sc-)
|
|
|
733 @kindex n
|
|
|
734 @vindex sc-electric-circular-p
|
|
|
735 @vindex electric-circular-p (sc-)
|
|
|
736 Displays the next reference header in the electric reference buffer. If
|
|
|
737 the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
|
|
|
738 @code{sc-eref-next} while viewing the last reference header in the list
|
|
|
739 will wrap around to the first header.@refill
|
|
|
740
|
|
|
741 @item @code{sc-eref-prev} (@kbd{p})
|
|
|
742 @findex sc-eref-prev
|
|
|
743 @findex eref-prev (sc-)
|
|
|
744 @kindex p
|
|
|
745 Displays the previous reference header in the electric reference buffer.
|
|
|
746 If the variable @code{sc-electric-circular-p} is non-@code{nil},
|
|
|
747 invoking @code{sc-eref-prev} will wrap around to the last header.@refill
|
|
|
748
|
|
|
749 @item @code{sc-eref-goto} (@kbd{g})
|
|
|
750 @findex sc-eref-goto
|
|
|
751 @findex eref-goto (sc-)
|
|
|
752 @kindex g
|
|
|
753 Goes to a specified reference header. The index (into the
|
|
|
754 @code{sc-rewrite-header-list}) can be specified as a numeric argument to
|
|
|
755 the command. Otherwise, Supercite will query you for the index in the
|
|
|
756 minibuffer.@refill
|
|
|
757
|
|
|
758 @item @code{sc-eref-jump} (@kbd{j})
|
|
|
759 @findex sc-eref-jump
|
|
|
760 @findex eref-jump (sc-)
|
|
|
761 @kindex j
|
|
|
762 Display the preferred reference header, i.e., the one indexed by the current
|
|
|
763 value of @code{sc-preferred-header-style}.
|
|
|
764
|
|
|
765 @item @code{sc-eref-setn} (@kbd{s})
|
|
|
766 @findex sc-eref-setn
|
|
|
767 @findex eref-setn (sc-)
|
|
|
768 @kindex s
|
|
|
769 Set the preferred reference header (i.e.,
|
|
|
770 @code{sc-preferred-header-style}) to the currently displayed header.@refill
|
|
|
771
|
|
|
772 @item @code{sc-eref-exit} (@key{LFD}, @key{RET}, and @key{ESC C-c})
|
|
|
773 @kindex RET
|
|
|
774 @kindex LFD
|
|
|
775 @kindex q
|
|
|
776 @findex sc-eref-exit
|
|
|
777 @findex eref-exit (sc-)
|
|
|
778 Exit from electric reference mode and insert the current header into the
|
|
|
779 reply buffer.@refill
|
|
|
780
|
|
|
781 @item @code{sc-eref-abort} (@kbd{q}, @kbd{x})
|
|
|
782 @findex sc-eref-abort
|
|
|
783 @findex eref-abort (sc-)
|
|
|
784 @kindex x
|
|
|
785 Exit from electric reference mode without inserting the current header.
|
|
|
786 @end table
|
|
|
787
|
|
|
788 @vindex sc-electric-mode-hook
|
|
|
789 @vindex electric-mode-hook (sc-)
|
|
|
790 @noindent
|
|
|
791 Supercite will execute the hook @code{sc-electric-mode-hook} before
|
|
|
792 entering electric reference mode.
|
|
|
793
|
|
|
794 @node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top
|
|
|
795 @comment node-name, next, previous, up
|
|
|
796 @cindex citation interface specification
|
|
|
797 @chapter Getting Connected
|
|
|
798 @ifinfo
|
|
|
799
|
|
|
800 @end ifinfo
|
|
|
801 Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
|
|
|
802 original message into the reply buffer. In reality, the citation of the
|
|
|
803 original message is performed via a call through a configurable hook
|
|
|
804 variable. The name of this variable has been agreed to in advance as
|
|
|
805 part of the @dfn{citation interface specification}. By default this
|
|
|
806 hook variable has a @code{nil} value, which the MUA recognizes to mean,
|
|
|
807 ``use your default citation function''. When you add Supercite's
|
|
|
808 citation function to the hook, thereby giving the variable a
|
|
|
809 non-@code{nil} value, it tells the MUA to run the hook via
|
|
|
810 @code{run-hooks} instead of using the default citation.@refill
|
|
|
811
|
|
|
812 @ifinfo
|
|
|
813 @menu
|
|
|
814 * Emacs 19 MUAs::
|
|
|
815 * Emacs 18 MUAs::
|
|
|
816 * MH-E with any Emacsen::
|
|
|
817 * VM with any Emacsen::
|
|
|
818 * GNEWS with any Emacsen::
|
|
|
819 * Overloading for Non-conforming MUAs::
|
|
|
820 @end menu
|
|
|
821 @end ifinfo
|
|
|
822
|
|
|
823 Early in Supercite's development, the Supercite author, a few MUA
|
|
|
824 authors, and some early Supercite users got together and agreed upon a
|
|
|
825 standard interface between MUAs and citation packages (of which
|
|
|
826 Supercite is currently the only known add-on @t{:-)}. With the recent
|
|
|
827 release of the Free Software Foundation's GNU Emacs 19, the interface
|
|
|
828 has undergone some modification and it is possible that not all MUAs
|
|
|
829 support the new interface yet. Some support only the old interface and
|
|
|
830 some do not support the interface at all. Still, it is possible for all
|
|
|
831 known MUAs to use Supercite, and the following sections will outline the
|
|
|
832 procedures you need to follow.
|
|
|
833
|
|
|
834 To learn exactly how to connect Supercite to the software systems you
|
|
|
835 are using, read the appropriate following sections. For details on the
|
|
|
836 interface specifications, or if you are writing or maintaining an MUA,
|
|
|
837 @pxref{Hints to MUA Authors}.
|
|
|
838
|
|
|
839 @cindex autoload
|
|
|
840 @cindex .emacs file
|
|
|
841 @findex sc-cite-original
|
|
|
842 @findex cite-original (sc-)
|
|
|
843 @findex sc-submit-bug-report
|
|
|
844 @findex submit-bug-report (sc-)
|
|
|
845 The first thing that everyone should do, regardless of the MUA you are
|
|
|
846 using is to set up Emacs so it will load Supercite at the appropriate
|
|
|
847 time. You can either dump Supercite into your Emacs binary (ask your
|
|
|
848 local Emacs guru how to do this if you don't know), or you can set up an
|
|
|
849 @dfn{autoload} for Supercite. To do the latter, put the following in
|
|
|
850 your @file{.emacs} file:
|
|
|
851
|
|
|
852 @example
|
|
|
853 (autoload 'sc-cite-original "supercite" "Supercite 3.1" t)
|
|
|
854 (autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
|
|
|
855 @end example
|
|
|
856
|
|
|
857 @cindex point
|
|
|
858 @cindex mark
|
|
|
859 The function @code{sc-cite-original} is the top-level Supercite function
|
|
|
860 designed to be run from the citation hook. It expects
|
|
|
861 @samp{point} and @samp{mark} to be set around the region to cite, and it
|
|
|
862 expects the original article's mail headers to be present within this
|
|
|
863 region. Note that Supercite @emph{never} touches any text outside this
|
|
|
864 region. Note further that for Emacs 19, the region need not be active
|
|
|
865 for @code{sc-cite-original} to do its job.
|
|
|
866 @xref{Hints to MUA Authors}.@refill
|
|
|
867
|
|
|
868 The other step in the getting connected process is to make sure your
|
|
|
869 MUA calls @code{sc-cite-original} at the right time. As mentioned
|
|
|
870 above, some MUAs handle this differently. Read the sections that follow
|
|
|
871 pertaining to the MUAs you are using.
|
|
|
872
|
|
|
873 @vindex sc-load-hook
|
|
|
874 @vindex load-hook (sc-)
|
|
|
875 @vindex sc-pre-hook
|
|
|
876 @vindex pre-hook (sc-)
|
|
|
877 One final note. After Supercite is loaded into your Emacs session, it
|
|
|
878 runs the hook @code{sc-load-hook}. You can put any customizations into
|
|
|
879 this hook since it is only run once. This will not work, however, if
|
|
|
880 your Emacs maintainer has put Supercite into your dumped Emacs' image.
|
|
|
881 In that case, you can use the @code{sc-pre-hook} variable, but this will
|
|
|
882 get executed every time @code{sc-cite-original} is called. @xref{Reply
|
|
|
883 Buffer Initialization}.@refill
|
|
|
884
|
|
|
885 @node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected
|
|
|
886 @comment node-name, next, previous, up
|
|
|
887 @vindex mail-citation-hook
|
|
|
888 @cindex .emacs file
|
|
|
889 @section GNUS, RMAIL, or RNEWS with any Emacs 19
|
|
|
890 @ifinfo
|
|
|
891
|
|
|
892 @end ifinfo
|
|
|
893 These MUAs, distributed with both FSF and Lucid GNU Emacs 19, use Emacs'
|
|
|
894 built-in yanking facility, which provides the citing hook variable
|
|
|
895 @code{mail-citation-hook}. By default, this hook's value is @code{nil},
|
|
|
896 but by adding the following to your @file{.emacs} file, you can tell
|
|
|
897 these MUAs to use Supercite to perform the citing of the original
|
|
|
898 message:
|
|
|
899
|
|
|
900 @example
|
|
|
901 (add-hook 'mail-citation-hook 'sc-cite-original)
|
|
|
902 @end example
|
|
|
903
|
|
|
904 GNUS users may also want to add the following bit of lisp as well. This
|
|
|
905 prevents GNUS from inserting its default attribution header. Otherwise,
|
|
|
906 both GNUS and Supercite will insert an attribution header:
|
|
|
907
|
|
|
908 @example
|
|
|
909 (setq news-reply-header-hook nil)
|
|
|
910 @end example
|
|
|
911
|
|
|
912 Note that the @code{mail-citation-hook} interface described above was
|
|
|
913 not supported in FSF Emacs 19 until version 19.16 and in Lucid Emacs 19
|
|
|
914 until version 19.8. If you are running an earlier version of one of
|
|
|
915 these Emacsen, you will need to either upgrade to the latest version, or
|
|
|
916 use the unsupported @dfn{overloading} feature provided with Supercite.
|
|
|
917 @xref{Overloading for Non-conforming MUAs}.@refill
|
|
|
918
|
|
|
919 @node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
|
|
|
920 @comment node-name, next, previous, up
|
|
|
921 @vindex mail-citation-hook
|
|
|
922 @cindex .emacs file
|
|
|
923 @cindex overloading
|
|
|
924 @cindex sendmail.el file
|
|
|
925 @section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
|
|
|
926 @ifinfo
|
|
|
927
|
|
|
928 @end ifinfo
|
|
|
929 These MUAs use Emacs' built-in yanking and citing routines, contained in
|
|
|
930 the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its
|
|
|
931 derivative Epoch 4, do not know anything about the citation interface
|
|
|
932 required by Supercite. To connect Supercite to any of these MUAs under
|
|
|
933 Emacs 18 or Epoch 4, you should first
|
|
|
934 @pxref{Overloading for Non-conforming MUAs}. Then follow the directions
|
|
|
935 for using these MUAs under Emacs 19.
|
|
|
936 @xref{Emacs 19 MUAs}.@refill
|
|
|
937
|
|
|
938 @cindex add-hook substitute
|
|
|
939 @cindex setq as a substitute for add-hook
|
|
|
940 @findex setq
|
|
|
941 @findex add-hook
|
|
|
942 @cindex sc-unsupp.el file
|
|
|
943 Note that those instructions will tell you to use the function
|
|
|
944 @code{add-hook}. This function is new with Emacs 19 and you will not
|
|
|
945 have it by default if you are running Emacs 18 or Epoch 4. You can
|
|
|
946 either substitute the appropriate call to @code{setq}, or you can use
|
|
|
947 the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
|
|
|
948 file of unsupported Supercite hacks and ideas. Or you can upgrade to
|
|
|
949 some Emacs 19 variant! @t{:-)}@refill
|
|
|
950
|
|
|
951 To use @code{setq} instead of @code{add-hook}, you would, for example,
|
|
|
952 change this:
|
|
|
953
|
|
|
954 @example
|
|
|
955 (add-hook 'mail-citation-hook 'sc-cite-original)
|
|
|
956 @end example
|
|
|
957
|
|
|
958 to:
|
|
|
959
|
|
|
960 @example
|
|
|
961 (setq mail-citation-hook 'sc-cite-original)
|
|
|
962 @end example
|
|
|
963
|
|
2
|
964 Note the lack of a single quote on the first argument to @code{setq}.
|
|
0
|
965
|
|
|
966 @node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
|
|
|
967 @comment node-name, next, previous, up
|
|
|
968 @cindex .emacs file
|
|
|
969 @vindex mh-yank-hooks
|
|
|
970 @findex add-hook
|
|
|
971 @cindex mail-citation-hook
|
|
|
972 @section MH-E with any Emacsen
|
|
|
973 @ifinfo
|
|
|
974
|
|
|
975 @end ifinfo
|
|
|
976 MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
|
|
|
977 by other MUAs. At the time of this writing, MH-E 4.0 has not been
|
|
|
978 released, but if you have it, put this in your @file{.emacs} file to
|
|
|
979 connect Supercite and MH-E 4.x:
|
|
|
980
|
|
|
981 @example
|
|
|
982 (add-hook 'mail-citation-hook 'sc-cite-original)
|
|
|
983 @end example
|
|
|
984
|
|
|
985 Note that if you are using Emacs 18 or Epoch 4, you will not have the
|
|
|
986 @code{add-hook} function. @xref{Emacs 18 MUAs} for details on how to
|
|
|
987 proceed without @code{add-hook}.
|
|
|
988
|
|
|
989 MH-E version 3.x uses a slightly different interface than other MUAs.
|
|
|
990 MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
|
|
|
991 like a hook, and doing an @code{add-hook} will not work.
|
|
|
992
|
|
|
993 To connect Supercite to MH-E 3.x, you should instead add the following
|
|
|
994 to your @code{.emacs} file:
|
|
|
995
|
|
|
996 @example
|
|
|
997 (add-hook 'mh-yank-hooks 'sc-cite-original)
|
|
|
998 @end example
|
|
|
999
|
|
|
1000 @vindex mh-yank-from-start-of-msg
|
|
|
1001 You also need to make sure that MH-E includes all the original mail
|
|
|
1002 headers in the yanked message. The variable that controls this is
|
|
|
1003 @code{mh-yank-from-start-of-msg}. By default, this variable has the
|
|
|
1004 value @code{t}, which tells MH-E to include all the mail headers when
|
|
|
1005 yanking the original message. Before you switched to using Supercite,
|
|
|
1006 you may have set this variable to other values so as not to include the
|
|
|
1007 mail headers in the yanked message. Since Supercite requires these
|
|
|
1008 headers (and cleans them out for you), you need to make sure the value
|
|
|
1009 is @code{t}. This lisp, in your @file{.emacs} file will do the trick:
|
|
|
1010
|
|
|
1011 @example
|
|
|
1012 (setq mh-yank-from-start-of-msg t)
|
|
|
1013 @end example
|
|
|
1014
|
|
|
1015 Note that versions of MH-E before 3.7 did not provide the
|
|
|
1016 @code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E
|
|
|
1017 version 3.7 or later.
|
|
|
1018
|
|
|
1019 @node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
|
|
|
1020 @comment node-name, next, previous, up
|
|
|
1021 @cindex .emacs file
|
|
|
1022 @vindex mail-citation-hook
|
|
|
1023 @vindex mail-yank-hooks
|
|
|
1024 @section VM with any Emacsen
|
|
|
1025 @ifinfo
|
|
|
1026
|
|
|
1027 @end ifinfo
|
|
|
1028 Since release 4.40, VM has supported the citation interface required by
|
|
|
1029 Supercite. But since the interface has changed recently the details of
|
|
|
1030 getting connected differ with the version of VM you are using.
|
|
|
1031
|
|
|
1032 If you are running any release of VM after 4.40, you can add the
|
|
|
1033 following to your @file{.emacs} to connect Supercite with VM:
|
|
|
1034
|
|
|
1035 @example
|
|
|
1036 (add-hook 'mail-yank-hooks 'sc-cite-original)
|
|
|
1037 @end example
|
|
|
1038
|
|
|
1039 Note that if you are using Emacs 18 or Epoch 4, you will not have the
|
|
|
1040 @code{add-hook} function. @xref{Emacs 18 MUAs} for details on how to
|
|
|
1041 proceed without @code{add-hook}.
|
|
|
1042
|
|
|
1043 Since version 5.34, VM has supported the newer @code{mail-citation-hook}
|
|
|
1044 interface, but @code{mail-yank-hooks} is still being supported for
|
|
|
1045 backward compatibility. If you are running a newer version of VM and
|
|
|
1046 you want to maintain consistency with other MUAs, use this bit of code
|
|
|
1047 instead:
|
|
|
1048
|
|
|
1049 @example
|
|
|
1050 (add-hook 'mail-citation-hook 'sc-cite-original)
|
|
|
1051 @end example
|
|
|
1052
|
|
|
1053 @node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
|
|
|
1054 @comment node-name, next, previous, up@cindex .emacs file
|
|
|
1055 @vindex news-reply-mode-hook
|
|
|
1056 @findex sc-perform-overloads
|
|
|
1057 @findex perform-overloads (sc-)
|
|
|
1058 @vindex gnews-ready-hook
|
|
|
1059 @section GNEWS with any Emacsen
|
|
|
1060 @ifinfo
|
|
|
1061
|
|
|
1062 @end ifinfo
|
|
|
1063 As far as I know, no version of GNEWS supports the citation interface
|
|
|
1064 required by Supercite. To connect Supercite with GNEWS, please first
|
|
|
1065 @pxref{Overloading for Non-conforming MUAs}.
|
|
|
1066
|
|
|
1067 After you have followed the directions in that section. You should add
|
|
|
1068 the following lisp code to your @file{.emacs} file:
|
|
|
1069
|
|
|
1070 @example
|
|
|
1071 (add-hook 'mail-citation-hook 'sc-cite-original)
|
|
|
1072 @end example
|
|
|
1073
|
|
|
1074 Note that if you are using Emacs 18 or Epoch 4, you will not have the
|
|
|
1075 @code{add-hook} function. @xref{Emacs 18 MUAs} for details on how to
|
|
|
1076 proceed without @code{add-hook}.
|
|
|
1077
|
|
|
1078 @node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
|
|
|
1079 @comment node-name, next, previous, up
|
|
|
1080 @cindex overloading
|
|
|
1081 @cindex sc-oloads.el
|
|
|
1082 @vindex mail-citation-hook
|
|
|
1083 @findex sc-perform-overloads
|
|
|
1084 @cindex .emacs file
|
|
|
1085 @section Overloading for Non-conforming MUAs
|
|
|
1086 @ifinfo
|
|
|
1087
|
|
|
1088 @end ifinfo
|
|
|
1089 As mentioned elsewhere, some MUAs do not provide the necessary hooks to
|
|
|
1090 connect with Supercite. Supercite version 3.1 provides an unsupported
|
|
|
1091 mechanism, called @dfn{overloading} which redefines certain key
|
|
|
1092 functions in the MUA, so that it will call the @code{mail-citation-hook}
|
|
|
1093 variable instead of the MUA's default hard-coded citing routines. Since
|
|
|
1094 most newer versions of the known MUAs support the
|
|
|
1095 @code{mail-citation-hook} variable, it is recommended that you upgrade
|
|
|
1096 if at all possible. But if you can't upgrade, at least you're not out
|
|
|
1097 of luck! Once you set up overloading properly, you should follow the
|
|
|
1098 directions for connecting Supercite to the Emacs 19 MUAs.
|
|
|
1099 @xref{Emacs 19 MUAs}.@refill
|
|
|
1100
|
|
|
1101 @cindex Hyperbole
|
|
|
1102 @vindex hyperb:version
|
|
|
1103 Users of Bob Weiner's Hyperbole package take note. Hyperbole provides
|
|
|
1104 the necessary overloads (and a whole lot more!) and you can potentially
|
|
|
1105 clobber it if you were to load Supercite's overloading after
|
|
|
1106 Hyperbole's. For this reason, Supercite will @emph{not} perform any
|
|
|
1107 overloading if it finds the variable @code{hyperb:version} is
|
|
|
1108 @code{boundp} (i.e. it exists because Hyperbole has been loaded into
|
|
|
1109 your Emacs session). If this is the case, Supercite will display a
|
|
|
1110 warning message in the minibuffer. You should consult the Hyperbole
|
|
|
1111 manual for further details.
|
|
|
1112
|
|
|
1113 Overloading involves the re-definition of the citing function with the
|
|
|
1114 new, @code{mail-citation-hook} savvy version. The function in
|
|
|
1115 @file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This
|
|
|
1116 function is smart enough to only overload the MUA functions when it is
|
|
|
1117 absolutely necessary, based on the version numbers it can figure out.
|
|
|
1118 Also, @code{sc-perform-overloads} will only install the new functions
|
|
|
1119 once. It is also smart enough to do nothing if the MUA is not yet
|
|
|
1120 loaded.@refill
|
|
|
1121
|
|
|
1122 The tricky part is finding the right time and place to perform the
|
|
|
1123 overloading. It must be done after the MUA has been loaded into your
|
|
|
1124 Emacs session, but before the first time you try to yank in a message.
|
|
|
1125 Fortunately, this has been figured out for you.
|
|
|
1126
|
|
|
1127 If you must overload, you should put the following lisp code in your
|
|
|
1128 @file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
|
|
|
1129 loaded at the right time:
|
|
|
1130
|
|
|
1131 @example
|
|
|
1132 (autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
|
|
|
1133 @end example
|
|
|
1134
|
|
|
1135 Then you must make sure that the function @code{sc-perform-overloads}
|
|
|
1136 gets run at the right time. For GNUS, put this in your @file{.emacs}
|
|
|
1137 file:
|
|
|
1138
|
|
|
1139 @example
|
|
|
1140 (setq news-reply-mode-hook 'sc-perform-overloads)
|
|
|
1141 (setq mail-setup-hook 'sc-perform-overloads)
|
|
|
1142 @end example
|
|
|
1143
|
|
|
1144 If you are using RNEWS, put this in your @file{.emacs} file:
|
|
|
1145
|
|
|
1146 @vindex news-reply-mode-hook
|
|
|
1147 @example
|
|
|
1148 (setq news-reply-mode-hook 'sc-perform-overloads)
|
|
|
1149 @end example
|
|
|
1150
|
|
|
1151 If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
|
|
|
1152
|
|
|
1153 @example
|
|
|
1154 (setq mail-setup-hook 'sc-perform-overloads)
|
|
|
1155 @end example
|
|
|
1156
|
|
|
1157 If you are using GNEWS, put this in your @file{.emacs} file:
|
|
|
1158
|
|
|
1159 @example
|
|
|
1160 (setq news-reply-mode-hook 'sc-perform-overloads)
|
|
|
1161 (setq gnews-ready-hook 'sc-perform-overloads)
|
|
|
1162 @end example
|
|
|
1163
|
|
|
1164 Now go back and follow the directions for getting the Emacs 19 MUAs
|
|
|
1165 connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes
|
|
|
1166 for Emacs 19's @code{add-hook} function.@refill
|
|
|
1167
|
|
|
1168 @node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
|
|
|
1169 @comment node-name, next, previous, up
|
|
|
1170 @chapter Replying and Yanking
|
|
|
1171 @ifinfo
|
|
|
1172
|
|
|
1173 This chapter explains what happens when you reply and yank an original
|
|
|
1174 message from an MUA.
|
|
|
1175
|
|
|
1176 @menu
|
|
|
1177 * Reply Buffer Initialization::
|
|
|
1178 * Filling Cited Text::
|
|
|
1179 @end menu
|
|
|
1180 @end ifinfo
|
|
|
1181 @node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
|
|
|
1182 @comment node-name, next, previous, up
|
|
|
1183 @findex sc-cite-original
|
|
|
1184 @findex cite-original (sc-)
|
|
|
1185 @comment
|
|
|
1186 @section Reply Buffer Initialization
|
|
|
1187 @ifinfo
|
|
|
1188
|
|
|
1189 @end ifinfo
|
|
|
1190 Executing @code{sc-cite-original} performs the following steps as it
|
|
|
1191 initializes the reply buffer:
|
|
|
1192
|
|
|
1193 @enumerate
|
|
|
1194 @item
|
|
|
1195 @vindex sc-pre-hook
|
|
|
1196 @vindex pre-hook (sc-)
|
|
|
1197 @emph{Runs @code{sc-pre-hook}.}
|
|
|
1198 This hook variable is run before @code{sc-cite-original} does any other
|
|
|
1199 work. You could conceivably use this hook to set certain Supercite
|
|
|
1200 variables based on the reply buffer's mode or name (i.e., to do
|
|
|
1201 something different based on whether you are replying or following up to
|
|
|
1202 an article).@refill
|
|
|
1203
|
|
|
1204 @item
|
|
|
1205 @emph{Inserts Supercite's keymap.}
|
|
|
1206 @vindex sc-mode-map-prefix
|
|
|
1207 @vindex mode-map-prefix (sc-)
|
|
|
1208 @kindex C-c C-p
|
|
|
1209 @cindex keymap prefix
|
|
|
1210 Supercite provides a number of commands for performing post-yank
|
|
|
1211 modifications to the reply buffer. These commands are installed on
|
|
|
1212 Supercite's top-level keymap. Since Supercite has to interface with a
|
|
|
1213 wide variety of MUAs, it does not install all of its commands directly
|
|
|
1214 into the reply buffer's keymap. Instead, it puts its commands on a
|
|
|
1215 keymap prefix, then installs this prefix onto the buffer's keymap. What
|
|
|
1216 this means is that you typically have to type more characters to invoke
|
|
|
1217 a Supercite command, but Supercite's keybindings can be made much more
|
|
|
1218 consistent across MUAs.
|
|
|
1219
|
|
|
1220 You can control what key Supercite uses as its keymap prefix by changing
|
|
|
1221 the variable @code{sc-mode-map-prefix}. By default, this variable is
|
|
|
1222 set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the
|
|
|
1223 best default due to the scarcity of available keybindings in many MUAs.
|
|
|
1224
|
|
|
1225 @item
|
|
|
1226 @emph{Turns on Supercite minor mode.}
|
|
|
1227 @cindex modeline
|
|
|
1228 The modeline of the reply buffer should indicate that Supercite is
|
|
|
1229 active in that buffer by displaying the string @samp{SC}.
|
|
|
1230
|
|
|
1231 @item
|
|
|
1232 @emph{Sets the ``Undo Boundary''.}
|
|
|
1233 @cindex undo boundary
|
|
|
1234 Supercite sets an undo boundary before it begins to modify the original
|
|
|
1235 yanked text. This allows you to easily undo Supercite's changes to
|
|
|
1236 affect alternative citing styles.
|
|
|
1237
|
|
|
1238 @item
|
|
2
|
1239 @emph{Processes the mail headers.}
|
|
0
|
1240 @vindex sc-confirm-always-p
|
|
|
1241 @vindex confirm-always-p (sc-)
|
|
|
1242 @vindex sc-mail-warn-if-non-rfc822-p
|
|
|
1243 @vindex mail-warn-if-non-rfc822-p (sc-)
|
|
|
1244 All previously retrieved info key-value pairs are deleted from the info
|
|
|
1245 alist, then the mail headers in the body of the yanked message are
|
|
|
1246 scanned. Info key-value pairs are created for each header found. Also,
|
|
|
1247 such useful information as the author's name and email address are
|
|
|
1248 extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is
|
|
|
1249 non-@code{nil}, then Supercite will warn you if it finds a mail header
|
|
|
1250 that does not conform to RFC822. This is rare and indicates a problem
|
|
|
1251 either with your MUA or the original author's MUA, or some MTA (mail
|
|
|
1252 transport agent) along the way.
|
|
|
1253
|
|
|
1254 @vindex sc-nuke-mail-headers
|
|
|
1255 @vindex sc-nuke-mail-header-list
|
|
|
1256 @vindex nuke-mail-headers (sc-)
|
|
|
1257 @vindex nuke-mail-header-list (sc-)
|
|
|
1258 Once the info keys have been extracted from the mail headers, the
|
|
|
1259 headers are nuked from the reply buffer. You can control exactly which
|
|
|
1260 headers are removed or kept, but by default, all headers are removed.
|
|
|
1261
|
|
|
1262 There are two variables which control mail header nuking. The variable
|
|
|
1263 @code{sc-nuke-mail-headers} controls the overall behavior of the header
|
|
|
1264 nuking routines. By setting this variable to @code{'all}, you
|
|
|
1265 automatically nuke all mail headers. Likewise, setting this variable to
|
|
|
1266 @code{'none} inhibits nuking of any mail headers. In between these
|
|
|
1267 extremes, you can tell Supercite to nuke only a specified list of mail
|
|
|
1268 headers by setting this variable to @code{'specified}, or to keep only a
|
|
|
1269 specified list of headers by setting it to @code{'keep}.
|
|
|
1270
|
|
|
1271 If @code{sc-nuke-mail-headers} is set to @code{'specified} or
|
|
|
1272 @code{'keep}, then the variable @code{sc-nuke-mail-header-list} is
|
|
|
1273 consulted for the list of headers to nuke or keep. This variable
|
|
|
1274 contains a list of regular expressions. If the mail header line matches
|
|
|
1275 a regular expression in this list, the header will be nuked or kept.
|
|
|
1276 The line is matched against the regexp using @code{looking-at} rooted at
|
|
|
1277 the beginning of the line.
|
|
|
1278
|
|
|
1279 @vindex sc-blank-lines-after-headers
|
|
|
1280 @vindex blank-lines-after-headers (sc-)
|
|
|
1281 If the variable @code{sc-blank-lines-after-headers} is non-@code{nil},
|
|
|
1282 it contains the number of blank lines remaining in the buffer after mail
|
|
|
1283 headers are nuked. By default, only one blank line is left in the buffer.
|
|
|
1284
|
|
|
1285 @item
|
|
|
1286 @emph{Selects the attribution and citation strings.}
|
|
|
1287 Once the mail headers have been processed, Supercite selects a
|
|
|
1288 attribution string and a citation string which it will use to cite the
|
|
|
1289 original message. @xref{Selecting an Attribution} for details.
|
|
|
1290
|
|
|
1291 @item
|
|
|
1292 @emph{Cites the message body.}
|
|
|
1293 @vindex sc-cite-region-limit
|
|
|
1294 @vindex cite-region-limit (sc-)b
|
|
|
1295 After the selection of the attribution and citation strings, Supercite
|
|
|
1296 cites the original message by inserting the citation string prefix in
|
|
|
1297 front of every uncited line. You may not want Supercite to
|
|
|
1298 automatically cite very long messages however. For example, some email
|
|
|
1299 could contain a smaller header section followed by a huge uuencoded
|
|
|
1300 message. It wouldn't make sense to cite the uuencoded message part when
|
|
|
1301 responding to the original author's short preface. For this reason,
|
|
|
1302 Supercite provides a variable which limits the automatic citation of
|
|
|
1303 long messages to a certain maximum number of lines. The variable is
|
|
|
1304 called @code{sc-cite-region-limit}. If this variable contains an
|
|
|
1305 integer, messages with more lines that this will not be cited at all,
|
|
|
1306 and a warning message will be displayed. Supercite has performed
|
|
|
1307 everything necessary, though, for you to manually cite only the small
|
|
|
1308 portion of the original message that you want to use.
|
|
|
1309
|
|
|
1310 If @code{sc-cite-region-limit} contains a non-@code{nil} value, the
|
|
|
1311 original message will always be cited, regardless of its size. If the
|
|
|
1312 variable contains the value @code{nil}, the region will never be cited
|
|
|
1313 automatically. Use this if you always want to be able to edit and cite
|
|
|
1314 the message manually.
|
|
|
1315
|
|
|
1316 @vindex sc-cite-blank-lines-p
|
|
|
1317 @vindex cite-blank-lines-p (sc-)
|
|
|
1318 The variable @code{sc-cite-blank-lines-p} controls whether blank lines
|
|
|
1319 in the original message should be cited or not. If this variable is
|
|
|
1320 non-@code{nil}, blank lines will be cited just like non-blank lines.
|
|
|
1321 Otherwise, blank lines will be treated as paragraph separators.
|
|
|
1322
|
|
|
1323 Citing of the original message is highly configurable. Supercite's
|
|
|
1324 default setup does a pretty good job of citing many common forms of
|
|
|
1325 previously cited messages. But there are as many citation styles out
|
|
|
1326 there as people on the net, or just about! It would be impossible for
|
|
|
1327 Supercite to anticipate every style in existence, and you probably
|
|
|
1328 wouldn't encounter them all anyway. But you can configure Supercite to
|
|
|
1329 recognize those styles you see often.
|
|
|
1330 @xref{Configuring the Citation Engine} for details.@refill
|
|
|
1331
|
|
|
1332 @item
|
|
|
1333 @emph{Runs @code{sc-post-hook}.}
|
|
|
1334 @vindex sc-post-hook
|
|
|
1335 @vindex post-hook (sc-)
|
|
|
1336 This variable is very similar to @code{sc-pre-hook}, except that it runs
|
|
|
1337 after @code{sc-cite-original} is finished. This hook is provided mostly
|
|
|
1338 for completeness and backward compatibility. Perhaps it could be used to
|
|
|
1339 reset certain variables set in @code{sc-pre-hook}.@refill
|
|
|
1340 @end enumerate
|
|
|
1341
|
|
|
1342 @node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
|
|
|
1343 @comment node-name, next, previous, up
|
|
|
1344 @cindex filling paragraphs
|
|
|
1345 @vindex sc-auto-fill-region-p
|
|
|
1346 @vindex auto-fill-region-p (sc-)
|
|
|
1347 @cindex filladapt
|
|
|
1348 @cindex gin-mode
|
|
|
1349 @findex sc-setup-filladapt
|
|
|
1350 @findex setup-filladapt (sc-)
|
|
|
1351 @vindex sc-load-hook
|
|
|
1352 @vindex load-hook (sc-)
|
|
|
1353 @section Filling Cited Text
|
|
|
1354 @ifinfo
|
|
|
1355
|
|
|
1356 @end ifinfo
|
|
|
1357 Supercite will automatically fill newly cited text from the original
|
|
|
1358 message unless the variable @code{sc-auto-fill-region-p} has a
|
|
|
1359 @code{nil} value. Supercite will also re-fill paragraphs when you
|
|
|
1360 manually cite or re-cite text.
|
|
|
1361
|
|
|
1362 However, during normal editing, Supercite itself cannot be used to fill
|
|
|
1363 paragraphs. This is a change from version 2. There are other add-on
|
|
|
1364 lisp packages which do filling much better than Supercite ever did. The
|
|
|
1365 two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well
|
|
|
1366 with Supercite and both are available at the normal Emacs Lisp archive
|
|
|
1367 sites. @dfn{gin-mode} works pretty well out of the box, but if you use
|
|
|
1368 @dfn{filladapt}, you may want to run the function
|
|
|
1369 @code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply
|
|
|
1370 makes @dfn{filladapt} a little more Supercite savvy than its default
|
|
|
1371 setup.
|
|
|
1372
|
|
|
1373 @vindex sc-fixup-whitespace-p
|
|
|
1374 @vindex fixup-whitespace-p (sc-)
|
|
|
1375 Also, Supercite will collapse leading whitespace between the citation
|
|
|
1376 string and the text on a line when the variable
|
|
|
1377 @code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for
|
|
|
1378 this variable is @code{nil}.@refill
|
|
|
1379
|
|
|
1380 @vindex fill-prefix
|
|
|
1381 Its important to understand that Supercite's automatic filling (during
|
|
|
1382 the initial citation of the reply) is very fragile. That is because
|
|
|
1383 figuring out the @code{fill-prefix} for a particular paragraph is a
|
|
|
1384 really hard thing to do automatically. This is especially the case when
|
|
|
1385 the original message contains code or some other text where leading
|
|
|
1386 whitespace is important to preserve. For this reason, many Supercite
|
|
|
1387 users typically run with @code{sc-auto-fill-region-p} (and possibly also
|
|
|
1388 @code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually
|
|
|
1389 fill each cited paragraph in the reply buffer.
|
|
|
1390
|
|
|
1391 I usually run with both these variables containing their default values.
|
|
|
1392 When Supercite's automatic filling breaks on a particular message, I
|
|
|
1393 will use Emacs' undo feature to undo back before the citation was
|
|
|
1394 applied to the original message. Then I'll toggle the variables and
|
|
|
1395 manually cite those paragraphs that I don't want to fill or collapse
|
|
|
1396 whitespace on. @xref{Variable Toggling Shortcuts}.@refill
|
|
|
1397
|
|
|
1398 @kindex C-c C-p C-p
|
|
|
1399 If you find that Supercite's automatic filling is just too fragile for
|
|
|
1400 your tastes, you might consider one of these alternate approaches.
|
|
|
1401 Also, to make life easier, a shortcut function to toggle the state of
|
|
|
1402 both of these variables is provided on the key binding
|
|
|
1403 @kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix};
|
|
|
1404 @pxref{Post-yank Formatting Commands}).@refill
|
|
|
1405
|
|
|
1406 You will noticed that the minor mode string will
|
|
|
1407 show the state of these variables as qualifier characters. When both
|
|
|
1408 variables are @code{nil}, the Supercite minor mode string will display
|
|
|
1409 @samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
|
|
|
1410 string will display @samp{SC:f}, and when just
|
|
|
1411 @code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display
|
|
|
1412 @samp{SC:w}. When both variables are non-@code{nil}, the string will
|
|
|
1413 display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for
|
|
|
1414 the default bindings of the toggling function for each respective
|
|
|
1415 variable.
|
|
|
1416 @xref{Variable Toggling Shortcuts}.@refill
|
|
|
1417
|
|
|
1418 Why are these variables not set to @code{nil} by default? It is because
|
|
|
1419 many users won't manually fill paragraphs that are Supercited, and there
|
|
|
1420 have been widespread complaints on the net about mail and news messages
|
|
|
1421 containing lines greater than about 72 characters. So the default is to
|
|
|
1422 fill cited text.
|
|
|
1423
|
|
|
1424 @node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
|
|
|
1425 @comment node-name, next, previous, up
|
|
|
1426 @cindex attribution list
|
|
|
1427 @vindex sc-preferred-attribution-list
|
|
|
1428 @vindex preferred-attribution-list (sc-)
|
|
|
1429 @comment
|
|
|
1430 @chapter Selecting an Attribution
|
|
|
1431 @ifinfo
|
|
|
1432
|
|
|
1433 @end ifinfo
|
|
|
1434 As you know, the attribution string is the part of the author's name
|
|
|
1435 that will be used to composed a non-nested citation string. Supercite
|
|
|
1436 scans the various mail headers present in the original article and uses
|
|
|
1437 a number of heuristics to extract strings which it puts into the
|
|
|
1438 @dfn{attribution association list} or @dfn{attribution alist}. This is
|
|
|
1439 analogous, but different than, the info alist previously mentioned. Each
|
|
|
1440 element in the attribution alist is a key-value pair containing such
|
|
|
1441 information as the author's first name, middle names, and last name, the
|
|
|
1442 author's initials, and the author's email terminus.
|
|
|
1443
|
|
|
1444 @ifinfo
|
|
|
1445 @menu
|
|
|
1446 * Attribution Preferences::
|
|
|
1447 * Anonymous Attributions::
|
|
|
1448 * Author Names::
|
|
|
1449 @end menu
|
|
|
1450 @end ifinfo
|
|
|
1451
|
|
|
1452 @node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
|
|
|
1453 @comment node-name, next, previous, up
|
|
|
1454 @section Attribution Preferences
|
|
|
1455 @ifinfo
|
|
|
1456
|
|
|
1457 @end ifinfo
|
|
|
1458 When you cite an original message, you can tell Supercite which part of
|
|
|
1459 the author's name you would prefer it to use as the attribution. The
|
|
|
1460 variable @code{sc-preferred-attribution-list} controls this; it contains
|
|
|
1461 keys which are matched against the attribution alist in the given order.
|
|
|
1462 The first value of a key that produces a non-@code{nil}, non-empty
|
|
|
1463 string match is used as the attribution string, and if no keys match, a
|
|
|
1464 secondary mechanism is used to generate the attribution.
|
|
|
1465 @xref{Anonymous Attributions}.
|
|
|
1466
|
|
|
1467 The following preferences are always available in the attribution alist
|
|
|
1468 (barring error):
|
|
|
1469
|
|
|
1470 @table @code
|
|
|
1471 @item "emailname"
|
|
|
1472 the author's email terminus.
|
|
|
1473
|
|
|
1474 @item "initials"
|
|
|
1475 the author's initials.
|
|
|
1476
|
|
|
1477 @item "firstname"
|
|
|
1478 the author's first name.
|
|
|
1479
|
|
|
1480 @item "lastname"
|
|
|
1481 the author's last name.
|
|
|
1482
|
|
|
1483 @item "middlename-1"
|
|
|
1484 the author's first middle name.
|
|
|
1485
|
|
|
1486 @item "sc-lastchoice"
|
|
|
1487 the last attribution string you have selected. This is useful when you
|
|
|
1488 recite paragraphs in the reply.@refill
|
|
|
1489
|
|
|
1490 @item "sc-consult"
|
|
|
1491 @vindex sc-attrib-selection-list
|
|
|
1492 @vindex attrib-selection-list (sc-)
|
|
|
1493 consults the customizable list @code{sc-attrib-selection-list} which can
|
|
|
1494 be used to select special attributions based on the value of any info
|
|
|
1495 key. See below for details.
|
|
|
1496
|
|
|
1497 @item "x-attribution"
|
|
|
1498 the original author's suggestion for attribution string choice. See below
|
|
|
1499 for details.@refill
|
|
|
1500 @end table
|
|
|
1501
|
|
|
1502 Middle name indexes can be any positive integer greater than zero,
|
|
|
1503 though it is unlikely that many authors will have more than one middle
|
|
|
1504 name, if that many.
|
|
|
1505
|
|
|
1506 At this point, let me digress into a discussion of etiquette. It is my
|
|
|
1507 belief that while the style of the citations is a reflection of the
|
|
|
1508 personal tastes of the replier (i.e., you), the attribution selection is
|
|
|
1509 ultimately the personal choice of the original author. In a sense it is
|
|
|
1510 his or her ``net nickname'', and therefore the author should have some
|
|
|
1511 say in the selection of attribution string. Imagine how you would feel
|
|
|
1512 if someone gave you a nickname that you didn't like?
|
|
|
1513
|
|
|
1514 For this reason, Supercite recognizes a special mail header,
|
|
|
1515 @samp{X-Attribution:}, which if present, tells Supercite the attribution
|
|
|
1516 string preferred by the original author. It is the value of this header
|
|
|
1517 that is associated with the @code{"x-attribution"} key in the
|
|
|
1518 attribution alist. Currently, you can override the preference of this
|
|
|
1519 key by changing @code{sc-preferred-attribution-list}, but that isn't
|
|
|
1520 polite, and in the future Supercite may hard-code this. For now, it is
|
|
|
1521 suggested that if you change the order of the keys in this list, that
|
|
|
1522 @code{"x-attribution"} always be first, or possible second behind only
|
|
|
1523 @code{"sc-lastchoice"}. This latter is the default.
|
|
|
1524
|
|
|
1525 @vindex sc-attrib-selection-list
|
|
|
1526 @vindex attrib-selection-list (sc-)
|
|
|
1527 The value @code{"sc-consult"} in @code{sc-preferred-attribution-list}
|
|
|
1528 has a special meaning during attribution selection. When Supercite
|
|
|
1529 encounters this preference, it begins processing a customizable list of
|
|
|
1530 attributions, contained in the variable @code{sc-attrib-selection-list}.
|
|
|
1531 Each element in this list contains lists of the following form:
|
|
|
1532
|
|
|
1533 @example
|
|
|
1534 @group
|
|
|
1535 (@var{infokey} ((@var{regexp} @. @var{attribution})
|
|
|
1536 (@var{regexp} @. @var{attribution})
|
|
|
1537 (@dots{})))
|
|
|
1538 @end group
|
|
|
1539 @end example
|
|
|
1540
|
|
|
1541 @noindent
|
|
|
1542 @findex sc-mail-field
|
|
|
1543 @findex mail-field (sc-)
|
|
|
1544 where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
|
|
|
1545 is a regular expression to match against the @var{infokey}'s value. If
|
|
|
1546 @var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
|
|
|
1547 used as the attribution string. Actually, @var{attribution} can be a
|
|
|
1548 string or a list; if it is a list, it is @code{eval}uated and the return
|
|
|
1549 value (which must be a string), is used as the attribution.
|
|
|
1550
|
|
|
1551 This can be very useful for when you are replying to net acquaintances
|
|
|
1552 who do not use the @samp{X-Attribution:@:} mail header. You may know
|
|
|
1553 what nickname they would prefer to use, and you can set up this list to
|
|
|
1554 match against a specific mail field, e.g., @samp{From:@:}, allowing you
|
|
|
1555 to cite your friend's message with the appropriate attribution.
|
|
|
1556
|
|
|
1557 @node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
|
|
|
1558 @comment node-name, next, previous, up
|
|
|
1559 @vindex sc-default-author-name
|
|
|
1560 @vindex default-author-name (sc-)
|
|
|
1561 @vindex sc-default-attribution
|
|
|
1562 @vindex default-attribution (sc-)
|
|
|
1563 @comment
|
|
|
1564 @section Anonymous Attributions
|
|
|
1565 @ifinfo
|
|
|
1566
|
|
|
1567 @end ifinfo
|
|
|
1568 When the author's name cannot be found in the @samp{From:@:} mail
|
|
|
1569 header, a fallback author name and attribution string must be supplied.
|
|
|
1570 The fallback author name is contained in the variable
|
|
|
1571 @code{sc-default-author-name} and the fallback attribution string is
|
|
|
1572 contained in the variable @code{sc-default-attribution}. Default values
|
|
|
1573 for these variables are @code{"Anonymous"} and @code{"Anon"},
|
|
|
1574 respectively. Note that in most circumstances, getting the default
|
|
|
1575 author name or attribution is a sign that something is set up
|
|
|
1576 incorrectly.
|
|
|
1577
|
|
|
1578 @vindex sc-use-only-preference-p
|
|
|
1579 @vindex use-only-preference-p (sc-)
|
|
|
1580 Also, if the preferred attribution, which you specified in your
|
|
|
1581 @code{sc-preferred-attribution-alist} variable cannot be found, a
|
|
|
1582 secondary method can be employed to find a valid attribution string. The
|
|
|
1583 variable @code{sc-use-only-preference-p} controls what happens in this
|
|
|
1584 case. If the variable's value is non-@code{nil}, then
|
|
|
1585 @code{sc-default-author-name} and @code{sc-default-attribution} are
|
|
|
1586 used, otherwise, the following steps are taken to find a valid
|
|
|
1587 attribution string, and the first step to return a non-@code{nil},
|
|
|
1588 non-empty string becomes the attribution:@refill
|
|
|
1589
|
|
|
1590 @enumerate
|
|
|
1591 @item
|
|
|
1592 Use the last selected attribution, if there is one.
|
|
|
1593
|
|
|
1594 @item
|
|
|
1595 Use the value of the @code{"x-attribution"} key.
|
|
|
1596
|
|
|
1597 @item
|
|
|
1598 Use the author's first name.
|
|
|
1599
|
|
|
1600 @item
|
|
|
1601 Use the author's last name.
|
|
|
1602
|
|
|
1603 @item
|
|
|
1604 Use the author's initials.
|
|
|
1605
|
|
|
1606 @item
|
|
|
1607 Find the first non-@code{nil}, non-empty attribution string in the
|
|
|
1608 attribution alist.
|
|
|
1609
|
|
|
1610 @item
|
|
|
1611 @code{sc-default-attribution} is used.
|
|
|
1612 @end enumerate
|
|
|
1613
|
|
|
1614 @vindex sc-confirm-always-p
|
|
|
1615 @vindex confirm-always-p (sc-)
|
|
|
1616 Once the attribution string has been automatically selected, a number of
|
|
|
1617 things can happen. If the variable @code{sc-confirm-always-p} is
|
|
|
1618 non-@code{nil}, you are queried for confirmation of the chosen
|
|
|
1619 attribution string. The possible values for completion are those strings
|
|
|
1620 in the attribution alist, however you are not limited to these choices.
|
|
|
1621 You can type any arbitrary string at the confirmation prompt. The string
|
|
|
1622 you enter becomes the value associated with the @code{"sc-lastchoice"}
|
|
|
1623 key in the attribution alist.
|
|
|
1624
|
|
|
1625 @vindex sc-downcase-p
|
|
|
1626 @vindex downcase-p (sc-)
|
|
|
1627 Once an attribution string has been selected, Supercite will force the
|
|
|
1628 string to lower case if the variable @code{sc-downcase-p} is
|
|
|
1629 non-@code{nil}.
|
|
|
1630
|
|
|
1631 @vindex sc-attribs-preselect-hook
|
|
|
1632 @vindex attribs-preselect-hook (sc-)
|
|
|
1633 @vindex sc-attribs-postselect-hook
|
|
|
1634 @vindex attribs-postselect-hook (sc-)
|
|
|
1635
|
|
|
1636 Two hook variables provide even greater control of the attribution
|
|
|
1637 selection process. The hook @code{sc-attribs-preselect-hook} is run
|
|
|
1638 before any attribution is selected. Likewise, the hook
|
|
|
1639 @code{sc-attribs-postselect-hook} is run after the attribution is
|
|
|
1640 selected (and the corresponding citation string is built), but before
|
|
|
1641 these values are committed for use by Supercite. During the
|
|
|
1642 post-selection hook, the local variables @code{attribution} and
|
|
|
1643 @code{citation} are bound to the appropriate strings. By changing these
|
|
|
1644 variables in your hook functions, you change the attribution and
|
|
|
1645 citation strings used by Supercite. One possible use of this would be
|
|
|
1646 to override any automatically derived attribution string when it is only
|
|
|
1647 one character long; e.g. you prefer to use @code{"initials"} but the
|
|
|
1648 author only has one name.@refill
|
|
|
1649
|
|
|
1650 @node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
|
|
|
1651 @comment node-name, next, previous, up
|
|
|
1652 @cindex author names
|
|
|
1653 @section Author Names
|
|
|
1654 @ifinfo
|
|
|
1655
|
|
|
1656 @end ifinfo
|
|
|
1657 Supercite employs a number of heuristics to decipher the author's name
|
|
|
1658 based on value of the @samp{From:@:} mail field of the original message.
|
|
|
1659 Supercite can recognize almost all of the common @samp{From:@:} field
|
|
|
1660 formats in use. If you encounter a @samp{From:@:} field that Supercite
|
|
|
1661 cannot parse, please report this bug.
|
|
|
1662 @xref{The Supercite Mailing List}.@refill
|
|
|
1663
|
|
|
1664 @vindex sc-titlecue-regexp
|
|
|
1665 @vindex titlecue-regexp (sc-)
|
|
|
1666 There are a number of Supercite variables that control how author names
|
|
|
1667 are extracted from the @samp{From:@:} header. Some headers may contain a
|
|
|
1668 descriptive title as in:
|
|
|
1669
|
|
|
1670 @example
|
|
|
1671 From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
|
|
|
1672 @end example
|
|
|
1673
|
|
|
1674 Supercite knows which part of the @samp{From:@:} header is email address
|
|
|
1675 and which part is author name, but in this case the string @code{"Decent
|
|
|
1676 Hacker"} is not part of the author's name. You can tell Supercite to
|
|
|
1677 ignore the title, while still recognizing hyphenated names through the
|
|
|
1678 use of a regular expression in the variable @code{sc-titlecue-regexp}.
|
|
|
1679 This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any
|
|
|
1680 text after this regexp is encountered is ignored as noise.
|
|
|
1681
|
|
|
1682 @vindex sc-name-filter-alist
|
|
|
1683 @vindex name-filter-alist (sc-)
|
|
|
1684 Some @samp{From:@:} headers may contain extra titles in the name fields
|
|
|
1685 not separated by a title cue, but which are nonetheless not part of the
|
|
|
1686 author's name proper. Examples include the titles ``Dr.'', ``Mr.'',
|
|
|
1687 ``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third).
|
|
|
1688 Also, some companies prepend or append the name of the division,
|
|
|
1689 organization, or project on the author's name. All of these titles are
|
|
|
1690 noise which should be ignored. The variable @code{sc-name-filter-alist}
|
|
|
1691 is used for this purpose. As implied by its name, this variable is an
|
|
|
1692 association list, where each element is a cons cell of the form:
|
|
|
1693
|
|
|
1694 @example
|
|
|
1695 (@var{regexp} @. @var{position})
|
|
|
1696 @end example
|
|
|
1697
|
|
|
1698 @noindent
|
|
|
1699 where @var{regexp} is a regular expression that is matched (using
|
|
|
1700 @code{string-match}) against each element of the @samp{From:@:} field's
|
|
|
1701 author name. @var{position} is a position indicator, starting at zero.
|
|
|
1702 Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
|
|
|
1703 @code{sc-name-filter-alist} would have an entry such as:
|
|
|
1704
|
|
|
1705 @example
|
|
|
1706 ("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
|
|
|
1707 @end example
|
|
|
1708
|
|
|
1709 @noindent
|
|
|
1710 which only removes them if they appear as the first word in the name.
|
|
|
1711 The position indicator is an integer, or one of the two special symbols
|
|
|
1712 @code{last} or @code{any}. @code{last} always matches against the last
|
|
|
1713 word in the name field, while @code{any} matches against every word in
|
|
|
1714 the name field.
|
|
|
1715
|
|
|
1716 @node Configuring the Citation Engine, Using Regi, Author Names, Top
|
|
|
1717 @comment node-name, next, previous, up
|
|
|
1718 @cindex Regi
|
|
|
1719 @cindex frames (Regi)
|
|
|
1720 @cindex entries (Regi)
|
|
|
1721 @chapter Configuring the Citation Engine
|
|
|
1722 @ifinfo
|
|
|
1723
|
|
|
1724 @end ifinfo
|
|
|
1725 At the heart of Supercite is a regular expression interpreting engine
|
|
|
1726 called @dfn{Regi}. Regi operates by interpreting a data structure
|
|
|
1727 called a Regi-frame (or just @dfn{frame}), which is a list of
|
|
|
1728 Regi-entries (or just @dfn{entry}). Each entry contains a predicate,
|
|
|
1729 typically a regular expression, which is matched against a line of text
|
|
|
1730 in the current buffer. If the predicate matches true, an associated
|
|
|
1731 expression is @code{eval}uated. In this way, an entire region of text
|
|
|
1732 can be transformed in an @emph{awk}-like manner. Regi is used
|
|
|
1733 throughout Supercite, from mail header information extraction, to header
|
|
|
1734 nuking, to citing text.
|
|
|
1735
|
|
|
1736 @ifinfo
|
|
|
1737 @menu
|
|
|
1738 * Using Regi::
|
|
|
1739 * Frames You Can Customize::
|
|
|
1740 @end menu
|
|
|
1741 @end ifinfo
|
|
|
1742
|
|
|
1743 While the details of Regi are discussed below (@pxref{Using Regi}), only
|
|
|
1744 those who wish to customize certain aspects of Supercite need concern
|
|
|
1745 themselves with it. It is important to understand though, that any
|
|
|
1746 conceivable citation style that can be described by a regular expression
|
|
|
1747 can be recognized by Supercite. This leads to some interesting
|
|
|
1748 applications. For example, if you regularly recieve email from a
|
|
|
1749 co-worker that uses an uncommon citation style (say one that employs a
|
|
|
1750 @samp{|} or @samp{@}} character at the front of the line), it is
|
|
|
1751 possible for Supercite to recognize this and @emph{coerce} the citation
|
|
|
1752 to your preferred style, for consistency. In theory, it is possible for
|
|
|
1753 Supercite to recognize such things as uuencoded messages or C code and
|
|
|
1754 cite or fill those differently than normal text. None of this is
|
|
|
1755 currently part of Supercite, but contributions are welcome!
|
|
|
1756
|
|
|
1757 @node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
|
|
|
1758 @comment node-name, next, previous, up
|
|
|
1759 @findex regi-interpret
|
|
|
1760 @findex eval
|
|
|
1761 @findex looking-at
|
|
|
1762 @section Using Regi
|
|
|
1763 @ifinfo
|
|
|
1764
|
|
|
1765 @end ifinfo
|
|
|
1766 Regi works by interpreting frames with the function
|
|
|
1767 @code{regi-interpret}. A frame is a list of arbitrary size where each
|
|
|
1768 element is a entry of the following form:
|
|
|
1769
|
|
|
1770 @example
|
|
|
1771 (@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]])
|
|
|
1772 @end example
|
|
|
1773
|
|
|
1774 Regi starts with the first entry in a frame, evaluating the @var{pred}
|
|
|
1775 of that entry against the beginning of the line that @samp{point} is on.
|
|
|
1776 If the @var{pred} evaluates to true (or false if the optional
|
|
|
1777 @var{negate-p} is non-@code{nil}), then the @var{func} for that entry is
|
|
|
1778 @code{eval}uated. How processing continues is determined by the return
|
|
|
1779 value for @var{func}, and is described below. If @var{pred} was false
|
|
|
1780 the next entry in the frame is checked until all entries have been
|
|
|
1781 matched against the current line. If no entry matches, @samp{point} is
|
|
|
1782 moved forward one line and the frame is reset to the first entry.
|
|
|
1783
|
|
|
1784 @var{pred} can be a string, a variable, a list or one of the following
|
|
|
1785 symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If
|
|
|
1786 @var{pred} is a string, or a variable or list that @code{eval}uates to a
|
|
|
1787 string, it is interpreted as a regular expression. This regexp is
|
|
|
1788 matched against the current line, from the beginning, using
|
|
|
1789 @code{looking-at}. This match folds case if the optional
|
|
|
1790 @var{case-fold-search} is non-@code{nil}. If @var{pred} is not a
|
|
|
1791 string, or does not @code{eval}uate to a string, it is interpreted as a
|
|
|
1792 binary value (@code{nil} or non-@code{nil}).@refill
|
|
|
1793
|
|
|
1794 The four special symbol values for @var{pred} are recognized:
|
|
|
1795
|
|
|
1796 @table @code
|
|
|
1797 @item t
|
|
|
1798 Always produces a true outcome.
|
|
|
1799 @item begin
|
|
|
1800 Always executed before the frame is interpreted. This can be used to
|
|
|
1801 initialize some global variables for example.
|
|
|
1802 @item end
|
|
|
1803 Always executed after frame interpreting is completed. This can be used
|
|
|
1804 to perform any necessary post-processing.
|
|
|
1805 @item every
|
|
|
1806 Executes whenever the frame is reset, usually after the entire frame has
|
|
|
1807 been matched against the current line.
|
|
|
1808 @end table
|
|
|
1809
|
|
|
1810 Note that @var{negate-p} and @var{case-fold-search} are ignored if
|
|
|
1811 @var{pred} is one of these special symbols. Only the first occurance of
|
|
|
1812 each symbol in a frame is used; any duplicates are ignored. Also
|
|
|
1813 note that for performance reasons, the entries associated with these
|
|
|
1814 symbols are removed from the frame during the main interpreting loop.
|
|
|
1815
|
|
|
1816 Your @var{func} can return certain values which control continued Regi
|
|
|
1817 processing. By default, if your @var{func} returns @code{nil} (as it
|
|
|
1818 should be careful to do explicitly), Regi will reset the frame to the
|
|
|
1819 first entry, and advance @samp{point} to the beginning of the next line.
|
|
|
1820 If a list is returned from your function, it can contain any combination
|
|
|
1821 of the following elements:@refill
|
|
|
1822
|
|
|
1823 @table @asis
|
|
|
1824 @item the symbol @code{continue}
|
|
|
1825 This tells Regi to continue processing entries after a match, instead of
|
|
|
1826 reseting the frame and moving @samp{point}. In this way, lines of text
|
|
|
1827 can have multiple matches, but you have to be careful to avoid entering
|
|
|
1828 infinite loops.
|
|
|
1829
|
|
|
1830 @item the symbol @code{abort}
|
|
|
1831 This tells Regi to terminate frame processing. However, any @code{end}
|
|
|
1832 entry is still processed.
|
|
|
1833
|
|
|
1834 @item the list @code{(frame . @var{newframe})}
|
|
|
1835 This tells Regi to substitute @var{newframe} as the frame it is
|
|
|
1836 interpreting. In other words, your @var{func} can modify the Regi frame
|
|
|
1837 on the fly. @var{newframe} can be a variable containing a frame, or it
|
|
|
1838 can be the frame in-lined.@refill
|
|
|
1839
|
|
|
1840 @item the list @code{(step . @var{step})}
|
|
|
1841 Tells Regi to move @var{step} number of lines forward as it continues
|
|
|
1842 processing. By default, Regi moves forward one line. @var{step} can be
|
|
|
1843 zero or negative of course, but watch out for infinite loops.@refill
|
|
|
1844 @end table
|
|
|
1845
|
|
|
1846 During execution of your @var{func}, the following variables will be
|
|
|
1847 temporarily bound to some useful information:@refill
|
|
|
1848
|
|
|
1849 @table @code
|
|
|
1850 @item curline
|
|
|
1851 The current line in the buffer that Regi is @code{looking-at}, as a string.
|
|
|
1852 @item curframe
|
|
|
1853 The current frame being interpreted.
|
|
|
1854 @item curentry
|
|
|
1855 The current frame entry being interpreted.
|
|
|
1856 @end table
|
|
|
1857
|
|
|
1858 @node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
|
|
|
1859 @comment node-name, next, previous, up
|
|
|
1860 @vindex sc-nuke-mail-header
|
|
|
1861 @section Frames You Can Customize
|
|
|
1862 @ifinfo
|
|
|
1863
|
|
|
1864 @end ifinfo
|
|
|
1865 As mentioned earlier, Supercite uses various frames to perform
|
|
|
1866 certain jobs such as mail header information extraction and mail header
|
|
|
1867 nuking. However, these frames are not available for you to customize,
|
|
|
1868 except through abstract interfaces such as @code{sc-nuke-mail-header},
|
|
|
1869 et al.
|
|
|
1870
|
|
|
1871 @vindex sc-default-cite-frame
|
|
|
1872 However, the citation frames Supercite uses provide a lot of customizing
|
|
|
1873 power and are thus available to you to change to suit your needs. The
|
|
|
1874 workhorse of citation is the frame contained in the variable
|
|
|
1875 @code{sc-default-cite-frame}. This frame recognizes many situations,
|
|
|
1876 such as blank lines, which it interprets as paragraph separators. It
|
|
|
1877 also recognizes previously cited nested and non-nested citations in the
|
|
|
1878 original message. By default it will coerce non-nested citations into
|
|
|
1879 your preferred citation style, and it will add a level of citation to
|
|
|
1880 nested citations. It will also simply cite uncited lines in your
|
|
|
1881 preferred style.
|
|
|
1882
|
|
|
1883 @cindex unciting
|
|
|
1884 @cindex reciting
|
|
|
1885 @vindex sc-default-uncite-frame
|
|
|
1886 @vindex sc-default-recite-frame
|
|
|
1887 In a similar vein, there are default frames for @dfn{unciting} and
|
|
|
1888 @dfn{reciting}, contained in the variables
|
|
|
1889 @code{sc-default-uncite-frame} and @code{sc-default-recite-frame}
|
|
|
1890 respectively.@refill
|
|
|
1891
|
|
|
1892 As mentioned earlier (@pxref{Recognizing Citations}), citations are
|
|
|
1893 recognized through the values of the regular expressions
|
|
|
1894 @code{sc-citation-root-regexp}, et al. To recognize odd styles, you
|
|
|
1895 could modify these variables, or you could modify the default citing
|
|
|
1896 frame. Alternatively, you could set up association lists of frames for
|
|
|
1897 recognizing specific alternative forms.
|
|
|
1898
|
|
|
1899 @vindex sc-cite-frame-alist
|
|
|
1900 @vindex sc-uncite-frame-alist
|
|
|
1901 @vindex sc-recite-frame-alist
|
|
|
1902 For each of the actions -- citing, unciting, and reciting -- an alist is
|
|
|
1903 consulted to find the frame to use (@code{sc-cite-frame-alist},
|
|
|
1904 @code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
|
|
|
1905 respectively). These frames can contain alists of the form:
|
|
|
1906
|
|
|
1907 @example
|
|
|
1908 ((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
|
|
|
1909 (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
|
|
|
1910 (@dots{}))
|
|
|
1911 @end example
|
|
|
1912
|
|
|
1913 @vindex sc-mail-field
|
|
|
1914 @findex string-match
|
|
|
1915 Where @var{infokey} is a key suitable for @code{sc-mail-field},
|
|
|
1916 @var{regexp} is a regular expression which is @code{string-match}'d
|
|
|
1917 against the value of the @code{sc-mail-field} key, and @var{frame} is
|
|
|
1918 the frame to use if a match occurred. @var{frame} can be a variable
|
|
|
1919 containing a frame or a frame in-lined.@refill
|
|
|
1920
|
|
|
1921 When Supercite is about to cite, uncite, or recite a region, it consults
|
|
|
1922 the appropriate alist and attempts to find a frame to use. If one
|
|
|
1923 is not found from the alist, then the appropriate default frame is used.
|
|
|
1924
|
|
|
1925 @node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
|
|
|
1926 @comment node-name, next, previous, up
|
|
|
1927 @vindex sc-mode-map-prefix
|
|
|
1928 @vindex mode-map-prefix (sc-)
|
|
|
1929 @kindex C-c C-p
|
|
|
1930 @chapter Post-yank Formatting Commands
|
|
|
1931 @ifinfo
|
|
|
1932
|
|
|
1933 @end ifinfo
|
|
|
1934 Once the original message has been yanked into the reply buffer, and
|
|
|
1935 @code{sc-cite-original} has had a chance to do its thing, a number of
|
|
|
1936 useful Supercite commands will be available to you. Since there is wide
|
|
|
1937 variety in the keymaps that MUAs set up in their reply buffers, it is
|
|
|
1938 next to impossible for Supercite to properly sprinkle its commands into
|
|
|
1939 the existing keymap. For this reason Supercite places its commands on a
|
|
|
1940 separate keymap, putting this keymap onto a prefix key in the reply
|
|
|
1941 buffer. You can customize the prefix key Supercite uses by changing the
|
|
|
1942 variable @code{sc-mode-map-prefix}. By default, the
|
|
|
1943 @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
|
|
|
1944 but unfortunately the best general solution so far. In the rest of this
|
|
|
1945 chapter, we'll assume you've installed Supercite's keymap on the default
|
|
|
1946 prefix.@refill
|
|
|
1947
|
|
|
1948 @ifinfo
|
|
|
1949 @menu
|
|
|
1950 * Citing Commands::
|
|
|
1951 * Insertion Commands::
|
|
|
1952 * Variable Toggling Shortcuts::
|
|
|
1953 * Mail Field Commands::
|
|
|
1954 * Miscellaneous Commands::
|
|
|
1955 @end menu
|
|
|
1956 @end ifinfo
|
|
|
1957
|
|
|
1958 @node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
|
|
|
1959 @comment node-name, next, previous, up
|
|
|
1960 @vindex sc-cite-region-limit
|
|
|
1961 @section Commands to Manually Cite, Recite, and Uncite
|
|
|
1962 @ifinfo
|
|
|
1963
|
|
|
1964 @end ifinfo
|
|
|
1965 Probably the three most common post-yank formatting operations that you
|
|
|
1966 will perform will be the manual citing, reciting, and unciting of
|
|
|
1967 regions of text in the reply buffer. Often you may want to recite a
|
|
|
1968 paragraph to use a nickname, or manually cite a message when setting
|
|
|
1969 @code{sc-cite-region-limit} to @code{nil}. The following commands
|
|
|
1970 perform these functions on the region of text between @samp{point} and
|
|
|
1971 @samp{mark}. Each of them sets the @dfn{undo boundary} before modifying
|
|
|
1972 the region so that the command can be undone in the standard Emacs
|
|
|
1973 way.@refill
|
|
|
1974
|
|
|
1975 A quick note about Emacs 19. Unlike in Emacs 18, the region delimited
|
|
|
1976 by @samp{point} and @samp{mark} can have two states. It can be
|
|
|
1977 @dfn{active} or @dfn{inactive}. Although the FSF Emacs 19 and Lucid
|
|
|
1978 Emacs 19 use different terminology and functions, both employ the same
|
|
|
1979 convention such that when the region is inactive, commands that modify
|
|
|
1980 the region should generate an error. The user needs to explicitly
|
|
|
1981 activate the region before successfully executing the command. All
|
|
|
1982 Supercite commands conform to this convention.
|
|
|
1983
|
|
|
1984 Here is the list of Supercite citing commands:
|
|
|
1985
|
|
|
1986 @table @asis
|
|
|
1987 @findex sc-cite-region
|
|
|
1988 @findex cite-region (sc-)
|
|
|
1989 @kindex C-c C-p c
|
|
|
1990 @vindex sc-pre-cite-hook
|
|
|
1991 @vindex pre-cite-hook (sc-)
|
|
|
1992 @vindex sc-confirm-always-p
|
|
|
1993 @vindex confirm-always-p
|
|
|
1994 @kindex C-u
|
|
|
1995 @item @code{sc-cite-region} (@kbd{C-c C-p c})
|
|
|
1996 @comment
|
|
|
1997 This command cites each line in the region of text by interpreting the
|
|
|
1998 selected frame from @code{sc-cite-frame-alist}, or the default citing
|
|
|
1999 frame @code{sc-default-cite-frame}. It runs the hook
|
|
|
2000 @code{sc-pre-cite-hook} before interpreting the frame. With an optional
|
|
|
2001 universal argument (@kbd{C-u}), it temporarily sets
|
|
|
2002 @code{sc-confirm-always-p} to @code{t} so you can confirm the
|
|
|
2003 attribution string for a single manual citing.
|
|
|
2004 @xref{Configuring the Citation Engine}.@refill
|
|
|
2005
|
|
|
2006 @findex sc-uncite-region
|
|
|
2007 @findex uncite-region (sc-)
|
|
|
2008 @kindex C-c C-p u
|
|
|
2009 @item @code{sc-uncite-region} (@kbd{C-c C-p u})
|
|
|
2010 @comment
|
|
|
2011 This command removes any citation strings from the beginning of each
|
|
|
2012 cited line in the region by interpreting the selected frame from
|
|
|
2013 @code{sc-uncite-frame-alist}, or the default unciting frame
|
|
|
2014 @code{sc-default-uncite-frame}. It runs the hook
|
|
|
2015 @code{sc-pre-uncite-hook} before interpreting the frame.
|
|
|
2016 @xref{Configuring the Citation Engine}.@refill
|
|
|
2017
|
|
|
2018 @findex sc-recite-region
|
|
|
2019 @findex recite-region (sc-)
|
|
|
2020 @kindex C-c C-p r
|
|
|
2021 @item @code{sc-recite-region} (@kbd{C-c C-p r})
|
|
|
2022 @comment
|
|
|
2023 This command recites each line the region by interpreting the selected
|
|
|
2024 frame from @code{sc-recite-frame-alist}, or the default reciting frame
|
|
|
2025 @code{sc-default-recite-frame}. It runs the hook
|
|
|
2026 @code{sc-pre-recite-hook} before interpreting the frame.
|
|
|
2027 @xref{Configuring the Citation Engine}.@refill
|
|
|
2028
|
|
|
2029 @vindex sc-confirm-always-p
|
|
|
2030 @vindex confirm-always-p (sc-)
|
|
|
2031 Supercite will always ask you to confirm the attribution when reciting a
|
|
|
2032 region, regardless of the value of @code{sc-confirm-always-p}.
|
|
|
2033 @end table
|
|
|
2034
|
|
|
2035 @node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
|
|
|
2036 @comment node-name, next, previous, up
|
|
|
2037 @section Insertion Commands
|
|
|
2038 @ifinfo
|
|
|
2039
|
|
|
2040 @end ifinfo
|
|
|
2041 These two functions insert various strings into the reply buffer.
|
|
|
2042
|
|
|
2043 @table @asis
|
|
|
2044 @findex sc-insert-reference
|
|
|
2045 @findex insert-reference (sc-)
|
|
|
2046 @kindex C-c C-p w
|
|
|
2047 @item @code{sc-insert-reference} (@kbd{C-c C-p w})
|
|
|
2048 @comment
|
|
|
2049 @vindex sc-preferred-header-style
|
|
|
2050 @vindex preferred-header-style (sc-)
|
|
|
2051 Inserts a reference header into the reply buffer at @samp{point}. With
|
|
|
2052 no arguments, the header indexed by @code{sc-preferred-header-style} is
|
|
|
2053 inserted. An optional numeric argument is the index into
|
|
|
2054 @code{sc-rewrite-header-list} indicating which reference header to
|
|
|
2055 write.@refill
|
|
|
2056
|
|
|
2057 With just the universal argument (@kbd{C-u}), electric reference mode is
|
|
|
2058 entered, regardless of the value of @code{sc-electric-references-p}.
|
|
|
2059
|
|
|
2060 @findex sc-insert-citation
|
|
|
2061 @findex insert-citation (sc-)
|
|
|
2062 @kindex C-c C-p i
|
|
|
2063 @item @code{sc-insert-citation} (@kbd{C-c C-p i})
|
|
|
2064 @comment
|
|
|
2065 Inserts the current citation string at the beginning of the line that
|
|
|
2066 @samp{point} is on. If the line is already cited, Supercite will issue
|
|
|
2067 an error and will not cite the line.
|
|
|
2068 @end table
|
|
|
2069
|
|
|
2070 @node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
|
|
|
2071 @comment node-name, next, previous, up
|
|
|
2072 @cindex toggling variables
|
|
|
2073 @section Variable Toggling Shortcuts
|
|
|
2074 @ifinfo
|
|
|
2075
|
|
|
2076 @end ifinfo
|
|
|
2077 Supercite defines a number of commands that make it easier for you to
|
|
|
2078 toggle and set various Supercite variables as you are editing the reply
|
|
|
2079 buffer. For example, you may want to turn off filling or whitespace
|
|
|
2080 cleanup, but only temporarily. These toggling shortcut commands make
|
|
|
2081 this easy to do.
|
|
|
2082
|
|
|
2083 @kindex C-c C-p C-t
|
|
|
2084 Like Supercite commands in general, the toggling commands are placed on
|
|
|
2085 a keymap prefix within the greater Supercite keymap. For the default
|
|
|
2086 value of @code{sc-mode-map-prefix}, this will be
|
|
|
2087 @kbd{C-c C-p C-t}.@refill
|
|
|
2088
|
|
|
2089 The following commands toggle the value of certain Supercite variables
|
|
|
2090 which take only a binary value:
|
|
|
2091
|
|
|
2092 @table @kbd
|
|
|
2093 @item C-c C-p C-t b
|
|
|
2094 Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
|
|
|
2095
|
|
|
2096 @item C-c C-p C-t c
|
|
|
2097 Toggles the variable @code{sc-confirm-always-p}.
|
|
|
2098
|
|
|
2099 @item C-c C-p C-t d
|
|
|
2100 Toggles the variable @code{sc-downcase-p}.
|
|
|
2101
|
|
|
2102 @item C-c C-p C-t e
|
|
|
2103 Toggles the variable @code{sc-electric-references-p}.
|
|
|
2104
|
|
|
2105 @item C-c C-p C-t f
|
|
|
2106 Toggles the variable @code{sc-auto-fill-region-p}.
|
|
|
2107
|
|
|
2108 @item C-c C-p C-t o
|
|
|
2109 Toggles the variable @code{sc-electric-circular-p}.
|
|
|
2110
|
|
|
2111 @item C-c C-p C-t s
|
|
|
2112 Toggles the variable @code{sc-nested-citation-p}.
|
|
|
2113
|
|
|
2114 @item C-c C-p C-t u
|
|
|
2115 Toggles the variable @code{sc-use-only-preferences-p}.
|
|
|
2116
|
|
|
2117 @item C-c C-p C-t w
|
|
|
2118 Toggles the variable @code{sc-fixup-whitespace-p}.
|
|
|
2119 @end table
|
|
|
2120
|
|
|
2121 @findex set-variable
|
|
|
2122 The following commands let you set the value of multi-value variables,
|
|
|
2123 in the same way that Emacs' @code{set-variable} does:
|
|
|
2124
|
|
|
2125 @table @kbd
|
|
|
2126 @item C-c C-p C-t a
|
|
|
2127 Sets the value of the variable @code{sc-preferred-attribution-list}.
|
|
|
2128
|
|
|
2129 @item C-c C-p C-t l
|
|
|
2130 Sets the value of the variable @code{sc-cite-region-limit}.
|
|
|
2131
|
|
|
2132 @item C-c C-p C-t n
|
|
|
2133 Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
|
|
|
2134
|
|
|
2135 @item C-c C-p C-t N
|
|
|
2136 Sets the value of the variable @code{sc-mail-header-nuke-list}.
|
|
|
2137
|
|
|
2138 @item C-c C-p C-t p
|
|
|
2139 Sets the value of the variable @code{sc-preferred-header-style}.
|
|
|
2140 @end table
|
|
|
2141
|
|
|
2142 @kindex C-c C-p C-p
|
|
|
2143 One special command is provided to toggle both
|
|
|
2144 @code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together.
|
|
|
2145 This is because you typically want to run Supercite with either variable
|
|
|
2146 as @code{nil} or non-@code{nil}. The command to toggle these variables
|
|
|
2147 together is bound on @kbd{C-c C-p C-p}.@refill
|
|
|
2148
|
|
|
2149 Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?})
|
|
|
2150 brings up a Help message on the toggling keymap.
|
|
|
2151
|
|
|
2152
|
|
|
2153 @node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
|
|
|
2154 @comment node-name, next, previous, up
|
|
|
2155 @section Mail Field Commands
|
|
|
2156 @ifinfo
|
|
|
2157
|
|
|
2158 @end ifinfo
|
|
|
2159 These commands allow you to view, modify, add, and delete various bits
|
|
|
2160 of information from the info alist.
|
|
|
2161 @xref{Information Keys and the Info Alist}.@refill
|
|
|
2162
|
|
|
2163 @table @asis
|
|
|
2164 @kindex C-c C-p f
|
|
|
2165 @findex sc-mail-field-query
|
|
|
2166 @findex mail-field-query (sc-)
|
|
|
2167 @kindex C-c C-p f
|
|
|
2168 @item @code{sc-mail-field-query} (@kbd{C-c C-p f})
|
|
|
2169 @comment
|
|
|
2170 Allows you to interactively view, modify, add, and delete info alist
|
|
|
2171 key-value pairs. With no argument, you are prompted (with completion)
|
|
|
2172 for a info key. The value associated with that key is displayed in the
|
|
|
2173 minibuffer. With an argument, this command will first ask if you want
|
|
|
2174 to view, modify, add, or delete an info key. Viewing is identical to
|
|
|
2175 running the command with no arguments.
|
|
|
2176
|
|
|
2177 If you want to modify the value of a key, Supercite will first prompt
|
|
|
2178 you (with completion) for the key of the value you want to change. It
|
|
|
2179 will then put you in the minibuffer with the key's current value so you
|
|
|
2180 can edit the value as you wish. When you hit @key{RET}, the key's value
|
|
|
2181 is changed. For those of you running Emacs 19, minibuffer history is
|
|
|
2182 kept for the values.
|
|
|
2183
|
|
|
2184 If you choose to delete a key-value pair, Supercite will prompt you (with
|
|
|
2185 completion) for the key to delete.
|
|
|
2186
|
|
|
2187 If you choose to add a new key-value pair, Supercite firsts prompts you
|
|
|
2188 for the key to add. Note that completion is turned on for this prompt,
|
|
|
2189 but you can type any key name here, even one that does not yet exist.
|
|
|
2190 After entering the key, Supercite prompts you for the key's value. It
|
|
|
2191 is not an error to enter a key that already exists, but the new value
|
|
|
2192 will override any old value. It will not replace it though; if you
|
|
|
2193 subsequently delete the key-value pair, the old value will reappear.
|
|
|
2194
|
|
|
2195 @findex sc-mail-process-headers
|
|
|
2196 @findex mail-process-headers (sc-)
|
|
|
2197 @kindex C-c C-p g
|
|
|
2198 @item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
|
|
|
2199 @comment
|
|
|
2200 This command lets you re-initialize Supercite's info alist from any set
|
|
|
2201 of mail headers in the region between @samp{point} and @samp{mark}.
|
|
|
2202 This function is especially useful for replying to digest messages where
|
|
|
2203 Supercite will initially set up its information for the digest
|
|
|
2204 originator, but you want to cite each component article with the real
|
|
|
2205 message author. Note that unless an error during processing occurs, any
|
|
|
2206 old information is lost.@refill
|
|
|
2207 @end table
|
|
|
2208
|
|
|
2209 @node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
|
|
|
2210 @comment node-name, next, previous, up
|
|
|
2211 @section Miscellaneous Commands
|
|
|
2212 @ifinfo
|
|
|
2213
|
|
|
2214 @end ifinfo
|
|
|
2215 @table @asis
|
|
|
2216 @findex sc-open-line
|
|
|
2217 @findex open-line (sc-)
|
|
|
2218 @findex open-line
|
|
|
2219 @kindex C-c C-p o
|
|
|
2220 @item @code{sc-open-line} (@kbd{C-c C-p o})
|
|
|
2221 @comment
|
|
|
2222 Similar to Emacs' standard @code{open-line} commands, but inserts the
|
|
|
2223 citation string in front of the new line. As with @code{open-line},
|
|
|
2224 an optional numeric argument inserts that many new lines.@refill
|
|
|
2225
|
|
|
2226 @findex sc-describe
|
|
|
2227 @findex describe (sc-)
|
|
|
2228 @kindex C-c C-p ?
|
|
|
2229 @kindex C-c C-p h
|
|
|
2230 @item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
|
|
|
2231 @comment
|
|
|
2232 This function has been obsoleted by the @TeX{}info manual you are now
|
|
|
2233 reading. It is still provided for compatibility, but it will eventually
|
|
|
2234 go away.
|
|
|
2235
|
|
|
2236 @findex sc-version
|
|
|
2237 @findex version (sc-)
|
|
|
2238 @kindex C-c C-p v
|
|
|
2239 @item @code{sc-version} (@kbd{C-c C-p v})
|
|
|
2240 @comment
|
|
|
2241 Echos the version of Supercite you are using. With the optional
|
|
|
2242 universal argument (@kbd{C-u}), this command inserts the version
|
|
|
2243 information into the current buffer.
|
|
|
2244
|
|
|
2245 @findex sc-submit-bug-report
|
|
|
2246 @findex submit-bug-report (sc-)
|
|
|
2247 @kindex C-c C-p C-b
|
|
|
2248 @item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
|
|
|
2249 @comment
|
|
|
2250 If you encounter a bug, or wish to suggest an enhancement, use this
|
|
|
2251 command to set up an outgoing mail buffer, with the proper address to
|
|
|
2252 the Supercite maintainer automatically inserted in the @samp{To:@:}
|
|
|
2253 field. This command also inserts information that the Supercite
|
|
|
2254 maintainer can use to recreate your exact setup, making it easier to
|
|
|
2255 verify your bug.
|
|
|
2256 @end table
|
|
|
2257
|
|
|
2258 @node Hints to MUA Authors, Version 3 Changes, Electric References, Top
|
|
|
2259 @comment node-name, next, previous, up
|
|
|
2260 @chapter Hints to MUA Authors
|
|
|
2261 @ifinfo
|
|
|
2262
|
|
|
2263 @end ifinfo
|
|
|
2264 In June of 1989, some discussion was held between the various MUA
|
|
|
2265 authors, the Supercite author, and other Supercite users. These
|
|
|
2266 discussions centered around the need for a standard interface between
|
|
|
2267 MUAs and Supercite (or any future Supercite-like packages). This
|
|
|
2268 interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in
|
|
|
2269 a mail message to the Supercite mailing list:
|
|
|
2270
|
|
|
2271 @example
|
|
|
2272 Martin> Each news/mail-reader should provide a form of
|
|
|
2273 Martin> mail-yank-original that
|
|
|
2274
|
|
|
2275 Martin> 1: inserts the original message incl. header into the
|
|
|
2276 Martin> reply buffer; no indentation/prefixing is done, the header
|
|
|
2277 Martin> tends to be a "full blown" version rather than to be
|
|
|
2278 Martin> stripped down.
|
|
|
2279
|
|
|
2280 Martin> 2: `point' is at the start of the header, `mark' at the
|
|
|
2281 Martin> end of the message body.
|
|
|
2282
|
|
|
2283 Martin> 3: (run-hooks 'mail-yank-hooks)
|
|
|
2284
|
|
|
2285 Martin> [Supercite] should be run as such a hook and merely
|
|
|
2286 Martin> rewrite the message. This way it isn't anymore
|
|
|
2287 Martin> [Supercite]'s job to gather the original from obscure
|
|
|
2288 Martin> sources. [@dots{}]
|
|
|
2289 @end example
|
|
|
2290
|
|
|
2291 @vindex mail-citation-hook
|
|
|
2292 @vindex mail-yank-hooks
|
|
|
2293 @cindex sendmail.el
|
|
|
2294 @findex mail-yank-original
|
|
|
2295 @findex defvar
|
|
|
2296 This specification was adopted, but with the recent release of FSF GNU
|
|
|
2297 Emacs 19, it has undergone a slight modification. Instead of the
|
|
|
2298 variable @code{mail-yank-hooks}, the new preferred hook variable that
|
|
|
2299 the MUA should provide is @code{mail-citation-hook}.
|
|
|
2300 @code{mail-yank-hooks} can be provided for backward compatibility, but
|
|
|
2301 @code{mail-citation-hook} should always take precedence. Richard
|
|
|
2302 Stallman (of the FSF) suggests that the MUAs should @code{defvar}
|
|
|
2303 @code{mail-citation-hook} to @code{nil} and perform some default citing
|
|
|
2304 when that is the case. Take a look at Emacs 19's @file{sendmail.el}
|
|
|
2305 file, specifically the @code{mail-yank-original} defun for
|
|
|
2306 details.@refill
|
|
|
2307
|
|
|
2308 If you are writing a new MUA package, or maintaining an existing MUA
|
|
|
2309 package, you should make it conform to this interface so that your users
|
|
|
2310 will be able to link Supercite easily and seamlessly. To do this, when
|
|
|
2311 setting up a reply or forward buffer, your MUA should follow these
|
|
|
2312 steps:
|
|
|
2313
|
|
|
2314 @enumerate
|
|
|
2315 @item
|
|
|
2316 Insert the original message, including the mail headers into the reply
|
|
|
2317 buffer. At this point you should not modify the raw text in any way, and
|
|
|
2318 you should place all the original headers into the body of the reply.
|
|
|
2319 This means that many of the mail headers will be duplicated, one copy
|
|
|
2320 above the @code{mail-header-separator} line and one copy below,
|
|
|
2321 however there will probably be more headers below this line.@refill
|
|
|
2322
|
|
|
2323 @item
|
|
|
2324 Set @samp{point} to the beginning of the line containing the first mail
|
|
|
2325 header in the body of the reply. Set @samp{mark} at the end of the
|
|
|
2326 message text. It is very important that the region be set around the
|
|
|
2327 text Supercite is to modify and that the mail headers are within this
|
|
|
2328 region. Supercite will not venture outside the region for any reason,
|
|
|
2329 and anything within the region is fair game, so don't put anything that
|
|
|
2330 @strong{must} remain unchanged inside the region. Further note that for
|
|
|
2331 Emacs 19, the region need not be set active. Supercite will work
|
|
|
2332 properly when the region is inactive, as should any other like-minded
|
|
|
2333 package.@refill
|
|
|
2334
|
|
|
2335 @item
|
|
|
2336 Run the hook @code{mail-citation-hook}. You will probably want to
|
|
|
2337 provide some kind of default citation functions in cases where the user
|
|
|
2338 does not have Supercite installed. By default, your MUA should
|
|
|
2339 @code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
|
|
|
2340 yanking function, check its value. If it finds
|
|
|
2341 @code{mail-citation-hook} to be @code{nil}, it should perform some
|
|
|
2342 default citing behavior. User who want to connect to Supercite then
|
|
|
2343 need only add @code{sc-cite-original} to this list of hooks using
|
|
|
2344 @code{add-hook}.@refill
|
|
|
2345 @end enumerate
|
|
|
2346
|
|
|
2347 If you do all this, your users will not need to overload your routines
|
|
|
2348 to use Supercite, and your MUA will join the ranks of those that conform
|
|
|
2349 to this interface ``out of the box.''
|
|
|
2350
|
|
|
2351 @node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
|
|
|
2352 @comment node-name, next, previous, up
|
|
|
2353 @chapter Version 3 Changes
|
|
|
2354 @ifinfo
|
|
|
2355
|
|
|
2356 @end ifinfo
|
|
|
2357 @cindex sc-unsupp.el file
|
|
|
2358 With version 3, Supercite has undergone an almost complete rewrite, and
|
|
|
2359 has hopefully benefitted in a number of ways, including vast
|
|
|
2360 improvements in the speed of performance, a big reduction in size of the
|
|
|
2361 code and in the use of Emacs resources, and a much cleaner and flexible
|
|
|
2362 internal architecture. The central construct of the info alist, and its
|
|
|
2363 role in Supercite has been expanded, and the other central concept, the
|
|
|
2364 general package Regi, was developed to provide a theoretically unlimited
|
|
|
2365 flexibility.
|
|
|
2366
|
|
|
2367 But most of this work is internal and not of very great importance to the
|
|
|
2368 casual user. There have been some changes at the user-visible level,
|
|
|
2369 but for the most part, the Supercite configuration variables from
|
|
|
2370 version 2 should still be relevant to version 3. Below, I briefly
|
|
|
2371 outline those user-visible things that have changed since version 2. For
|
|
|
2372 details, look to other sections of this manual.
|
|
|
2373
|
|
|
2374 @enumerate
|
|
|
2375 @item
|
|
|
2376 @cindex supercite.el file
|
|
|
2377 @cindex reporter.el file
|
|
|
2378 @cindex regi.el file
|
|
|
2379 @cindex sc.el from version 2
|
|
|
2380 @cindex sc-elec.el from version 2
|
|
|
2381 Supercite proper now comes in a single file, @file{supercite.el}, which
|
|
|
2382 contains everything except the unsupported noodlings, overloading (which
|
|
|
2383 should be more or less obsolete with the release of Emacs 19), and the
|
|
|
2384 general lisp packages @file{reporter.el} and @file{regi.el}. Finally,
|
|
|
2385 the @TeX{}info manual comes in its own file as well. In particular, the
|
|
|
2386 file @file{sc.el} from the version 2 distribution is obsolete, as is the
|
|
|
2387 file @file{sc-elec.el}.
|
|
|
2388
|
|
|
2389 @item
|
|
|
2390 @code{sc-spacify-name-chars} is gone in version 3.
|
|
|
2391
|
|
|
2392 @item
|
|
|
2393 @vindex sc-attrib-selection-list
|
|
|
2394 @vindex attrib-selection-list
|
|
|
2395 @code{sc-nickname-alist} is gone in version 3. The
|
|
|
2396 @code{sc-attrib-selection-list} is a more general construct supporting
|
|
|
2397 the same basic feature.
|
|
|
2398
|
|
|
2399 @item
|
|
|
2400 The version 2 variable @code{sc-preferred-attribution} has been changed
|
|
|
2401 to @code{sc-preferred-attribution-list}, and has been expanded upon to
|
|
|
2402 allow you to specify an ordered list of preferred attributions.
|
|
|
2403
|
|
|
2404 @item
|
|
|
2405 @code{sc-mail-fields-list} has been removed, and header nuking in
|
|
|
2406 general has been greatly improved, giving you wider flexibility in
|
|
|
2407 specifying which headers to keep and remove while presenting a
|
|
|
2408 simplified interface to commonly chosen defaults.
|
|
|
2409
|
|
|
2410 @item
|
|
|
2411 Post-yank paragraph filling has been completely removed from Supercite,
|
|
|
2412 other packages just do it better than Supercite ever would. Supercite
|
|
|
2413 will still fill newly cited paragraphs.
|
|
|
2414
|
|
|
2415 @item
|
|
|
2416 @vindex sc-cite-region-limit
|
|
|
2417 @vindex cite-region-limit
|
|
|
2418 The variable @code{sc-all-but-cite-p} has been replaced by
|
|
|
2419 @code{sc-cite-region-limit}.
|
|
|
2420
|
|
|
2421 @item
|
|
|
2422 Keymap hacking in the reply buffer has been greatly simplified, with, I
|
|
|
2423 believe, little reduction in functionality.
|
|
|
2424
|
|
|
2425 @item
|
|
|
2426 Hacking of the reply buffer's docstring has been completely eliminated.
|
|
|
2427 @end enumerate
|
|
|
2428
|
|
|
2429 @node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
|
|
|
2430 @comment node-name, next, previous, up
|
|
|
2431 @chapter Thanks and History
|
|
|
2432 @ifinfo
|
|
|
2433
|
|
|
2434 @end ifinfo
|
|
|
2435 The Supercite package was derived from its predecessor Superyank 1.11
|
|
|
2436 which was inspired by various bits of code and ideas from Martin Neitzel
|
|
|
2437 and Ashwin Ram. They were the folks who came up with the idea of
|
|
|
2438 non-nested citations and implemented some rough code to provide this
|
|
|
2439 style. Superyank and Supercite version 2 evolved to the point where much
|
|
|
2440 of the attribution selection mechanism was automatic, and features have
|
|
|
2441 been continuously added through the comments and suggestions of the
|
|
|
2442 Supercite mailing list participants. Supercite version 3 represents a
|
|
|
2443 nearly complete rewrite with many of the algorithms and coding styles
|
|
|
2444 being vastly improved. Hopefully Supercite version 3 is faster,
|
|
|
2445 smaller, and much more flexible than its predecessors.
|
|
|
2446
|
|
|
2447 In the version 2 manual I thanked some specific people for their help in
|
|
|
2448 developing Supercite 2. You folks know who you are and your continued
|
|
|
2449 support is greatly appreciated. I wish to thank everyone on the
|
|
|
2450 Supercite mailing list, especially the brave alpha testers, who helped
|
|
|
2451 considerably in testing out the concepts and implementation of Supercite
|
|
|
2452 version 3. Special thanks go out to the MUA and Emacs authors Kyle
|
|
|
2453 Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming
|
|
|
2454 to a quick agreement on the new @code{mail-citation-hook} interface, and
|
|
|
2455 for adding the magic lisp to their code to support this.
|
|
|
2456
|
|
|
2457 All who have helped and contributed have been greatly appreciated.
|
|
|
2458
|
|
|
2459 @node The Supercite Mailing List, Concept Index, Thanks and History, Top
|
|
|
2460 @comment node-name, next, previous, up
|
|
|
2461 @cindex supercite mailing list address
|
|
|
2462 @cindex mailing list address
|
|
|
2463 @chapter The Supercite Mailing List
|
|
|
2464 @ifinfo
|
|
|
2465
|
|
|
2466 @end ifinfo
|
|
|
2467 The author runs a simple mail expanding mailing list for discussion of
|
|
|
2468 issues related to Supercite. This includes enhancement requests, bug
|
|
|
2469 reports, general help questions, etc. To subscribe or unsubscribe to
|
|
|
2470 the mailing list, send a request to the administrative address:
|
|
|
2471
|
|
|
2472 @example
|
|
|
2473 Internet: supercite-request@@anthem.nlm.nih.gov
|
|
|
2474 UUCP: uunet!anthem.nlm.nih.gov!supercite-request
|
|
|
2475 @end example
|
|
|
2476
|
|
|
2477 Please be sure to include the most reliable and shortest (preferably
|
|
|
2478 Internet) address back to you. To post articles to the list, send your
|
|
|
2479 message to this address (you do not need to be a member to post, but be
|
|
|
2480 sure to indicate this in your article or replies may not be CC'd to
|
|
|
2481 you):
|
|
|
2482
|
|
|
2483 @example
|
|
|
2484 Internet: supercite@@anthem.nlm.nih.gov
|
|
|
2485 UUCP: uunet!anthem.nlm.nih.gov!supercite
|
|
|
2486 @end example
|
|
|
2487
|
|
|
2488 If you are sending bug reports, they should go to the following address,
|
|
|
2489 but @emph{please}! use the command @code{sc-submit-bug-report} since it
|
|
|
2490 will be much easier for me to duplicate your problem if you do so. It
|
|
|
2491 will set up a mail buffer automatically with this address on the
|
|
|
2492 @samp{To:@:} line:
|
|
|
2493
|
|
|
2494 @example
|
|
|
2495 Internet: supercite-help@@anthem.nlm.nih.gov
|
|
|
2496 UUCP: uunet!anthem.nlm.nih.gov!supercite-help
|
|
|
2497 @end example
|
|
|
2498
|
|
|
2499 @node Concept Index, Command Index, The Supercite Mailing List, Top
|
|
|
2500 @comment node-name, next, previous, up
|
|
|
2501 @unnumbered Concept Index
|
|
|
2502 @printindex cp
|
|
|
2503
|
|
|
2504 @node Command Index, Key Index, Concept Index, Top
|
|
|
2505 @comment node-name, next, previous, up
|
|
|
2506 @unnumbered Command Index
|
|
|
2507 @ifinfo
|
|
|
2508
|
|
|
2509 @end ifinfo
|
|
|
2510 Since all supercite commands are prepended with the string
|
|
|
2511 ``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
|
|
|
2512 its @var{command} name.
|
|
|
2513 @iftex
|
|
|
2514 @sp 2
|
|
|
2515 @end iftex
|
|
|
2516 @printindex fn
|
|
|
2517
|
|
|
2518 @node Key Index, Variable Index, Command Index, Top
|
|
|
2519 @comment node-name, next, previous, up
|
|
|
2520 @unnumbered Key Index
|
|
|
2521 @printindex ky
|
|
|
2522
|
|
|
2523 @node Variable Index, , Key Index, Top
|
|
|
2524 @comment node-name, next, previous, up
|
|
|
2525 @unnumbered Variable Index
|
|
|
2526 @ifinfo
|
|
|
2527
|
|
|
2528 @end ifinfo
|
|
|
2529 Since all supercite variables are prepended with the string
|
|
|
2530 ``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
|
|
|
2531 its @var{variable} name.
|
|
|
2532 @iftex
|
|
|
2533 @sp 2
|
|
|
2534 @end iftex
|
|
|
2535 @printindex vr
|
|
|
2536 @summarycontents
|
|
|
2537 @contents
|
|
|
2538 @bye
|
