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