annotate man/sc.texi @ 65878:011947140bc7

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