diff options
| author | Xue Fuqiao | 2013-08-07 21:19:48 +0800 |
|---|---|---|
| committer | Xue Fuqiao | 2013-08-07 21:19:48 +0800 |
| commit | 998ad848a4f1fd347fdbb1cf181035a0e174eddc (patch) | |
| tree | 163cd043f2060ea479ea3e46402dfe0d3b8bf9ed /doc | |
| parent | 98374c9aebd118332e3cb0d7f0a27cc585390c7d (diff) | |
| download | emacs-998ad848a4f1fd347fdbb1cf181035a0e174eddc.tar.gz emacs-998ad848a4f1fd347fdbb1cf181035a0e174eddc.zip | |
Index and whitespace fixes for doc/misc/sc.texi.
* sc.texi (Introduction): Fix indexes.
(Usage Overview):
(Citations, Citation Elements, Recognizing Citations)
(Information Keys and the Info Alist, Reference Headers)
(The Built-in Header Rewrite Functions)
(Electric References, Reply Buffer Initialization)
(Filling Cited Text, Selecting an Attribution)
(Attribution Preferences)
(Anonymous Attributions, Author Names)
(Using Regi, Post-yank Formatting Commands)
(Citing Commands, Insertion Commands)
(Mail Field Commands)
(Hints to MUA Authors, Thanks and History): Change from one space
between sentences to two.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/misc/ChangeLog | 17 | ||||
| -rw-r--r-- | doc/misc/sc.texi | 192 |
2 files changed, 114 insertions, 95 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 84147698029..5721626f4e3 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog | |||
| @@ -1,5 +1,20 @@ | |||
| 1 | 2013-08-07 Xue Fuqiao <xfq.free@gmail.com> | 1 | 2013-08-07 Xue Fuqiao <xfq.free@gmail.com> |
| 2 | 2 | ||
| 3 | * sc.texi (Introduction): Fix index. | ||
| 4 | (Usage Overview): | ||
| 5 | (Citations, Citation Elements, Recognizing Citations) | ||
| 6 | (Information Keys and the Info Alist, Reference Headers) | ||
| 7 | (The Built-in Header Rewrite Functions) | ||
| 8 | (Electric References, Reply Buffer Initialization) | ||
| 9 | (Filling Cited Text, Selecting an Attribution) | ||
| 10 | (Attribution Preferences) | ||
| 11 | (Anonymous Attributions, Author Names) | ||
| 12 | (Using Regi, Post-yank Formatting Commands) | ||
| 13 | (Citing Commands, Insertion Commands) | ||
| 14 | (Mail Field Commands) | ||
| 15 | (Hints to MUA Authors, Thanks and History): Change from one space | ||
| 16 | between sentences to two. | ||
| 17 | |||
| 3 | * newsticker.texi (Usage): Use @key for RET. | 18 | * newsticker.texi (Usage): Use @key for RET. |
| 4 | 19 | ||
| 5 | * cl.texi (Argument Lists): | 20 | * cl.texi (Argument Lists): |
| @@ -205,7 +220,7 @@ | |||
| 205 | 220 | ||
| 206 | 2013-05-25 Xue Fuqiao <xfq.free@gmail.com> | 221 | 2013-05-25 Xue Fuqiao <xfq.free@gmail.com> |
| 207 | 222 | ||
| 208 | * flymake.texi: Changing from one space between sentences to two. | 223 | * flymake.texi: Change from one space between sentences to two. |
| 209 | 224 | ||
| 210 | 2013-05-04 Stefan Monnier <monnier@iro.umontreal.ca> | 225 | 2013-05-04 Stefan Monnier <monnier@iro.umontreal.ca> |
| 211 | 226 | ||
diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index cfd040f0e82..7d7ef07ed61 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi | |||
| @@ -84,12 +84,15 @@ into the following chapters. | |||
| 84 | @node Introduction | 84 | @node Introduction |
| 85 | @chapter Introduction | 85 | @chapter Introduction |
| 86 | 86 | ||
| 87 | Supercite is a GNU Emacs package written entirely in Emacs Lisp. It | 87 | @cindex MUA |
| 88 | @cindex NUA | ||
| 89 | Supercite is a GNU Emacs package written entirely in Emacs Lisp. It | ||
| 88 | interfaces to most of the commonly used Emacs mail user agents | 90 | interfaces to most of the commonly used Emacs mail user agents |
| 89 | (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides | 91 | (@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides |
| 90 | sophisticated facilities for the citing and attributing of message | 92 | sophisticated facilities for the citing and attributing of message |
| 91 | replies. Supercite has a very specific and limited role in the process | 93 | replies. Supercite has a very specific and limited role in the |
| 92 | of composing replies to both USENET network news and electronic mail. | 94 | process of composing replies to both USENET network news and |
| 95 | electronic mail. | ||
| 93 | 96 | ||
| 94 | The preferred way to spell Supercite is with a capital @samp{S}, | 97 | The preferred way to spell Supercite is with a capital @samp{S}, |
| 95 | lowercase @samp{upercite}. | 98 | lowercase @samp{upercite}. |
| @@ -100,8 +103,7 @@ lowercase @samp{upercite}. | |||
| 100 | * What Supercite Does:: | 103 | * What Supercite Does:: |
| 101 | @end menu | 104 | @end menu |
| 102 | 105 | ||
| 103 | @cindex MUA | 106 | @c FIXME: move it above the menu? --xfq |
| 104 | @cindex NUA | ||
| 105 | Supercite is only useful in conjunction with MUAs and NUAs such as VM, | 107 | Supercite is only useful in conjunction with MUAs and NUAs such as VM, |
| 106 | Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a | 108 | Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a |
| 107 | reply buffer has been setup. Thereafter, Supercite's many commands and | 109 | reply buffer has been setup. Thereafter, Supercite's many commands and |
| @@ -118,21 +120,22 @@ sent. Supercite is re-initialized in each new reply buffer. | |||
| 118 | @cindex cite, citing | 120 | @cindex cite, citing |
| 119 | @cindex attribute, attributing | 121 | @cindex attribute, attributing |
| 120 | 122 | ||
| 121 | Typical usage is as follows. You want to reply or followup to a message | 123 | Typical usage is as follows. You want to reply or followup to a |
| 122 | in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} | 124 | message in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') |
| 123 | (i.e., ``forward'') to begin composing the reply. In response, the MUA | 125 | or @kbd{f} (i.e., ``forward'') to begin composing the reply. In |
| 124 | will create a reply buffer and initialize the outgoing mail headers | 126 | response, the MUA will create a reply buffer and initialize the |
| 125 | appropriately. The body of the reply will usually be empty at this | 127 | outgoing mail headers appropriately. The body of the reply will |
| 126 | point. You now decide that you would like to include part of the | 128 | usually be empty at this point. You now decide that you would like to |
| 127 | original message in your reply. To do this, you @dfn{yank} the original | 129 | include part of the original message in your reply. To do this, you |
| 128 | message into the reply buffer, typically with a key stroke such as | 130 | @dfn{yank} the original message into the reply buffer, typically with |
| 129 | @kbd{C-c C-y}. This sequence will invoke an MUA-specific function which | 131 | a key stroke such as @kbd{C-c C-y}. This sequence will invoke an |
| 130 | fills the body of the reply with the original message and then | 132 | MUA-specific function which fills the body of the reply with the |
| 131 | @dfn{attributes} this text to its author. This is called @dfn{citing} | 133 | original message and then @dfn{attributes} this text to its author. |
| 132 | and its effect is to prefix every line from the original message with a | 134 | This is called @dfn{citing} and its effect is to prefix every line |
| 133 | special text tag. Most MUAs provide some default style of citing; by | 135 | from the original message with a special text tag. Most MUAs provide |
| 134 | using Supercite you gain a wider flexibility in the look and style of | 136 | some default style of citing; by using Supercite you gain a wider |
| 135 | citations. Supercite's only job is to cite the original message. | 137 | flexibility in the look and style of citations. Supercite's only job |
| 138 | is to cite the original message. | ||
| 136 | 139 | ||
| 137 | @node What Supercite Does Not Do | 140 | @node What Supercite Does Not Do |
| 138 | @section What Supercite Doesn't Do | 141 | @section What Supercite Doesn't Do |
| @@ -253,10 +256,10 @@ make the message very difficult for the eye to scan. | |||
| 253 | 256 | ||
| 254 | @cindex non-nested citations | 257 | @cindex non-nested citations |
| 255 | In @dfn{non-nested citations}, each cited line begins with an | 258 | In @dfn{non-nested citations}, each cited line begins with an |
| 256 | informative string attributing that line to the original author. Only | 259 | informative string attributing that line to the original author. Only |
| 257 | the first level of attribution will be shown; subsequent citations don't | 260 | the first level of attribution will be shown; subsequent citations |
| 258 | nest the citation strings. The above dialog might look like this when | 261 | don't nest the citation strings. The above dialog might look like |
| 259 | non-nested citations are used: | 262 | this when non-nested citations are used: |
| 260 | 263 | ||
| 261 | @example | 264 | @example |
| 262 | John> John originally wrote this | 265 | John> John originally wrote this |
| @@ -272,19 +275,20 @@ message did not result in a line cited with @samp{Jane>John>}. | |||
| 272 | @vindex sc-nested-citation-p | 275 | @vindex sc-nested-citation-p |
| 273 | @vindex nested-citation-p (sc-) | 276 | @vindex nested-citation-p (sc-) |
| 274 | Supercite supports both styles of citation, and the variable | 277 | Supercite supports both styles of citation, and the variable |
| 275 | @code{sc-nested-citation-p} controls which style it will use when citing | 278 | @code{sc-nested-citation-p} controls which style it will use when |
| 276 | previously uncited text. When this variable is @code{nil} (the default), | 279 | citing previously uncited text. When this variable is @code{nil} (the |
| 277 | non-nested citations are used. When non-@code{nil}, nested citations | 280 | default), non-nested citations are used. When non-@code{nil}, nested |
| 278 | are used. | 281 | citations are used. |
| 279 | 282 | ||
| 280 | 283 | ||
| 281 | @node Citation Elements | 284 | @node Citation Elements |
| 282 | @section Citation Elements | 285 | @section Citation Elements |
| 283 | @cindex citation string | 286 | @cindex citation string |
| 284 | 287 | ||
| 285 | @dfn{Citation strings} are composed of one or more elements. Non-nested | 288 | @dfn{Citation strings} are composed of one or more elements. |
| 286 | citations are composed of four elements, three of which are directly | 289 | Non-nested citations are composed of four elements, three of which are |
| 287 | user definable. The elements are concatenated together, in this order: | 290 | directly user definable. The elements are concatenated together, in |
| 291 | this order: | ||
| 288 | 292 | ||
| 289 | @cindex citation leader | 293 | @cindex citation leader |
| 290 | @vindex citation-leader (sc-) | 294 | @vindex citation-leader (sc-) |
| @@ -337,10 +341,10 @@ multi-level nested citations. | |||
| 337 | @section Recognizing Citations | 341 | @section Recognizing Citations |
| 338 | 342 | ||
| 339 | Supercite also recognizes citations in the original article, and can | 343 | Supercite also recognizes citations in the original article, and can |
| 340 | transform these already cited lines in a number of ways. This is how | 344 | transform these already cited lines in a number of ways. This is how |
| 341 | Supercite suppresses the multiple citing of non-nested citations. | 345 | Supercite suppresses the multiple citing of non-nested citations. |
| 342 | Recognition of cited lines is controlled by variables analogous to those | 346 | Recognition of cited lines is controlled by variables analogous to |
| 343 | that make up the citation string as mentioned previously. | 347 | those that make up the citation string as mentioned previously. |
| 344 | 348 | ||
| 345 | @vindex sc-citation-leader-regexp | 349 | @vindex sc-citation-leader-regexp |
| 346 | @vindex citation-leader-regexp (sc-) | 350 | @vindex citation-leader-regexp (sc-) |
| @@ -387,16 +391,16 @@ change @code{sc-citation-root-regexp} you should always also change | |||
| 387 | 391 | ||
| 388 | @dfn{Mail header information keys} are nuggets of information that | 392 | @dfn{Mail header information keys} are nuggets of information that |
| 389 | Supercite extracts from the various mail headers of the original | 393 | Supercite extracts from the various mail headers of the original |
| 390 | message, placed in the reply buffer by the MUA@. Information is kept in | 394 | message, placed in the reply buffer by the MUA@. Information is kept |
| 391 | the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in | 395 | in the @dfn{Info Alist} as key-value pairs, and can be retrieved for |
| 392 | various places within Supercite, such as in header rewrite functions and | 396 | use in various places within Supercite, such as in header rewrite |
| 393 | attribution selection. Other bits of data, composed and created by | 397 | functions and attribution selection. Other bits of data, composed and |
| 394 | Supercite, are also kept as key-value pairs in this alist. In the case | 398 | created by Supercite, are also kept as key-value pairs in this alist. |
| 395 | of mail fields, the key is the name of the field, omitting the trailing | 399 | In the case of mail fields, the key is the name of the field, omitting |
| 396 | colon. Info keys are always case insensitive (as are mail headers), and | 400 | the trailing colon. Info keys are always case insensitive (as are |
| 397 | the value for a corresponding key can be retrieved from the alist with | 401 | mail headers), and the value for a corresponding key can be retrieved |
| 398 | the @code{sc-mail-field} function. Thus, if the following fields were | 402 | from the alist with the @code{sc-mail-field} function. Thus, if the |
| 399 | present in the original article:@refill | 403 | following fields were present in the original article:@refill |
| 400 | 404 | ||
| 401 | @example | 405 | @example |
| 402 | Date:@: 08 April 1991, 17:32:09 EST | 406 | Date:@: 08 April 1991, 17:32:09 EST |
| @@ -419,7 +423,7 @@ then, the following lisp constructs return: | |||
| 419 | Since the argument to @code{sc-mail-field} can be any string, it is | 423 | Since the argument to @code{sc-mail-field} can be any string, it is |
| 420 | possible that the mail field will not be present on the info alist | 424 | possible that the mail field will not be present on the info alist |
| 421 | (possibly because the mail header was not present in the original | 425 | (possibly because the mail header was not present in the original |
| 422 | message). In this case, @code{sc-mail-field} will return the value of | 426 | message). In this case, @code{sc-mail-field} will return the value of |
| 423 | the variable @code{sc-mumble}. | 427 | the variable @code{sc-mumble}. |
| 424 | 428 | ||
| 425 | Supercite always places all mail fields found in the yanked original | 429 | Supercite always places all mail fields found in the yanked original |
| @@ -510,8 +514,8 @@ header. | |||
| 510 | @vindex sc-rewrite-header-list | 514 | @vindex sc-rewrite-header-list |
| 511 | @vindex rewrite-header-list (sc-) | 515 | @vindex rewrite-header-list (sc-) |
| 512 | There are a number of built-in @dfn{header rewrite functions} supplied | 516 | There are a number of built-in @dfn{header rewrite functions} supplied |
| 513 | by Supercite, but you can write your own custom header rewrite functions | 517 | by Supercite, but you can write your own custom header rewrite |
| 514 | (perhaps using the built-in ones as examples). The variable | 518 | functions (perhaps using the built-in ones as examples). The variable |
| 515 | @code{sc-rewrite-header-list} contains the list of such header rewrite | 519 | @code{sc-rewrite-header-list} contains the list of such header rewrite |
| 516 | functions. This list is consulted both when inserting the initial | 520 | functions. This list is consulted both when inserting the initial |
| 517 | reference header, and when displaying @dfn{electric references}. | 521 | reference header, and when displaying @dfn{electric references}. |
| @@ -521,7 +525,7 @@ reference header, and when displaying @dfn{electric references}. | |||
| 521 | @vindex preferred-header-style (sc-) | 525 | @vindex preferred-header-style (sc-) |
| 522 | When Supercite is initially run on a reply buffer (via | 526 | When Supercite is initially run on a reply buffer (via |
| 523 | @code{sc-cite-original}), it will automatically call one of these | 527 | @code{sc-cite-original}), it will automatically call one of these |
| 524 | functions. The one it uses is defined in the variable | 528 | functions. The one it uses is defined in the variable |
| 525 | @code{sc-preferred-header-style}. The value of this variable is an | 529 | @code{sc-preferred-header-style}. The value of this variable is an |
| 526 | integer which is an index into the @code{sc-rewrite-header-list}, | 530 | integer which is an index into the @code{sc-rewrite-header-list}, |
| 527 | beginning at zero. | 531 | beginning at zero. |
| @@ -556,9 +560,9 @@ problem either in your MUA or in Supercite's installation). | |||
| 556 | @findex sc-no-header | 560 | @findex sc-no-header |
| 557 | @findex no-header (sc-) | 561 | @findex no-header (sc-) |
| 558 | @item sc-no-header | 562 | @item sc-no-header |
| 559 | This function produces no header. It should be used instead of | 563 | This function produces no header. It should be used instead of |
| 560 | @code{nil} to produce a blank header. This header can possibly contain | 564 | @code{nil} to produce a blank header. This header can possibly |
| 561 | a blank line after the @code{mail-header-separator} line. | 565 | contain a blank line after the @code{mail-header-separator} line. |
| 562 | 566 | ||
| 563 | @item sc-no-blank-line-or-header | 567 | @item sc-no-blank-line-or-header |
| 564 | @findex sc-no-blank-line-or-header | 568 | @findex sc-no-blank-line-or-header |
| @@ -612,11 +616,11 @@ line after the @code{mail-header-separator} line will be removed. | |||
| 612 | By default, when Supercite cites the original message for the first | 616 | By default, when Supercite cites the original message for the first |
| 613 | time, it just goes ahead and inserts the reference header indexed by | 617 | time, it just goes ahead and inserts the reference header indexed by |
| 614 | @code{sc-preferred-header-style}. However, you may want to select | 618 | @code{sc-preferred-header-style}. However, you may want to select |
| 615 | different reference headers based on the type of reply or forwarding you | 619 | different reference headers based on the type of reply or forwarding |
| 616 | are doing. You may also want to preview the reference header before | 620 | you are doing. You may also want to preview the reference header |
| 617 | deciding whether to insert it into the reply buffer or not. Supercite | 621 | before deciding whether to insert it into the reply buffer or |
| 618 | provides an optional @dfn{electric reference} mode which you can drop | 622 | not. Supercite provides an optional @dfn{electric reference} mode |
| 619 | into to give you this functionality. | 623 | which you can drop into to give you this functionality. |
| 620 | 624 | ||
| 621 | @vindex sc-electric-references-p | 625 | @vindex sc-electric-references-p |
| 622 | @vindex electric-references-p (sc-) | 626 | @vindex electric-references-p (sc-) |
| @@ -629,7 +633,7 @@ through all the reference header rewrite functions in your | |||
| 629 | @code{sc-rewrite-header-list}. | 633 | @code{sc-rewrite-header-list}. |
| 630 | 634 | ||
| 631 | You can also set a new preferred header style, jump to any header, or | 635 | You can also set a new preferred header style, jump to any header, or |
| 632 | jump to the preferred header. The header will be shown in the electric | 636 | jump to the preferred header. The header will be shown in the electric |
| 633 | reference buffer and the header index and function name will appear in | 637 | reference buffer and the header index and function name will appear in |
| 634 | the echo area. | 638 | the echo area. |
| 635 | 639 | ||
| @@ -643,7 +647,7 @@ The following commands are available while in electric reference mode | |||
| 643 | @kindex n | 647 | @kindex n |
| 644 | @vindex sc-electric-circular-p | 648 | @vindex sc-electric-circular-p |
| 645 | @vindex electric-circular-p (sc-) | 649 | @vindex electric-circular-p (sc-) |
| 646 | Displays the next reference header in the electric reference buffer. If | 650 | Displays the next reference header in the electric reference buffer. If |
| 647 | the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking | 651 | the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking |
| 648 | @code{sc-eref-next} while viewing the last reference header in the list | 652 | @code{sc-eref-next} while viewing the last reference header in the list |
| 649 | will wrap around to the first header.@refill | 653 | will wrap around to the first header.@refill |
| @@ -854,7 +858,7 @@ affect alternative citing styles. | |||
| 854 | @vindex mail-warn-if-non-rfc822-p (sc-) | 858 | @vindex mail-warn-if-non-rfc822-p (sc-) |
| 855 | All previously retrieved info key-value pairs are deleted from the info | 859 | All previously retrieved info key-value pairs are deleted from the info |
| 856 | alist, then the mail headers in the body of the yanked message are | 860 | alist, then the mail headers in the body of the yanked message are |
| 857 | scanned. Info key-value pairs are created for each header found. Also, | 861 | scanned. Info key-value pairs are created for each header found. Also, |
| 858 | such useful information as the author's name and email address are | 862 | such useful information as the author's name and email address are |
| 859 | extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is | 863 | extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is |
| 860 | non-@code{nil}, then Supercite will warn you if it finds a mail header | 864 | non-@code{nil}, then Supercite will warn you if it finds a mail header |
| @@ -931,7 +935,7 @@ in the original message should be cited or not. If this variable is | |||
| 931 | non-@code{nil}, blank lines will be cited just like non-blank lines. | 935 | non-@code{nil}, blank lines will be cited just like non-blank lines. |
| 932 | Otherwise, blank lines will be treated as paragraph separators. | 936 | Otherwise, blank lines will be treated as paragraph separators. |
| 933 | 937 | ||
| 934 | Citing of the original message is highly configurable. Supercite's | 938 | Citing of the original message is highly configurable. Supercite's |
| 935 | default setup does a pretty good job of citing many common forms of | 939 | default setup does a pretty good job of citing many common forms of |
| 936 | previously cited messages. But there are as many citation styles out | 940 | previously cited messages. But there are as many citation styles out |
| 937 | there as people on the net, or just about! It would be impossible for | 941 | there as people on the net, or just about! It would be impossible for |
| @@ -945,8 +949,8 @@ recognize those styles you see often. | |||
| 945 | @vindex sc-post-hook | 949 | @vindex sc-post-hook |
| 946 | @vindex post-hook (sc-) | 950 | @vindex post-hook (sc-) |
| 947 | This variable is very similar to @code{sc-pre-hook}, except that it runs | 951 | This variable is very similar to @code{sc-pre-hook}, except that it runs |
| 948 | after @code{sc-cite-original} is finished. This hook is provided mostly | 952 | after @code{sc-cite-original} is finished. This hook is provided mostly |
| 949 | for completeness and backward compatibility. Perhaps it could be used to | 953 | for completeness and backward compatibility. Perhaps it could be used to |
| 950 | reset certain variables set in @code{sc-pre-hook}.@refill | 954 | reset certain variables set in @code{sc-pre-hook}.@refill |
| 951 | @end enumerate | 955 | @end enumerate |
| 952 | 956 | ||
| @@ -1012,7 +1016,7 @@ both of these variables is provided on the key binding | |||
| 1012 | @pxref{Post-yank Formatting Commands}).@refill | 1016 | @pxref{Post-yank Formatting Commands}).@refill |
| 1013 | 1017 | ||
| 1014 | You will noticed that the minor mode string will | 1018 | You will noticed that the minor mode string will |
| 1015 | show the state of these variables as qualifier characters. When both | 1019 | show the state of these variables as qualifier characters. When both |
| 1016 | variables are @code{nil}, the Supercite minor mode string will display | 1020 | variables are @code{nil}, the Supercite minor mode string will display |
| 1017 | @samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the | 1021 | @samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the |
| 1018 | string will display @samp{SC:f}, and when just | 1022 | string will display @samp{SC:f}, and when just |
| @@ -1036,11 +1040,11 @@ fill cited text. | |||
| 1036 | @vindex preferred-attribution-list (sc-) | 1040 | @vindex preferred-attribution-list (sc-) |
| 1037 | 1041 | ||
| 1038 | As you know, the attribution string is the part of the author's name | 1042 | As you know, the attribution string is the part of the author's name |
| 1039 | that will be used to composed a non-nested citation string. Supercite | 1043 | that will be used to composed a non-nested citation string. Supercite |
| 1040 | scans the various mail headers present in the original article and uses | 1044 | scans the various mail headers present in the original article and uses |
| 1041 | a number of heuristics to extract strings which it puts into the | 1045 | a number of heuristics to extract strings which it puts into the |
| 1042 | @dfn{attribution association list} or @dfn{attribution alist}. This is | 1046 | @dfn{attribution association list} or @dfn{attribution alist}. This is |
| 1043 | analogous, but different than, the info alist previously mentioned. Each | 1047 | analogous, but different than, the info alist previously mentioned. Each |
| 1044 | element in the attribution alist is a key-value pair containing such | 1048 | element in the attribution alist is a key-value pair containing such |
| 1045 | information as the author's first name, middle names, and last name, the | 1049 | information as the author's first name, middle names, and last name, the |
| 1046 | author's initials, and the author's email terminus. | 1050 | author's initials, and the author's email terminus. |
| @@ -1083,7 +1087,7 @@ the author's last name. | |||
| 1083 | the author's first middle name. | 1087 | the author's first middle name. |
| 1084 | 1088 | ||
| 1085 | @item "sc-lastchoice" | 1089 | @item "sc-lastchoice" |
| 1086 | the last attribution string you have selected. This is useful when you | 1090 | the last attribution string you have selected. This is useful when you |
| 1087 | recite paragraphs in the reply.@refill | 1091 | recite paragraphs in the reply.@refill |
| 1088 | 1092 | ||
| 1089 | @item "sc-consult" | 1093 | @item "sc-consult" |
| @@ -1094,7 +1098,7 @@ be used to select special attributions based on the value of any info | |||
| 1094 | key. See below for details. | 1098 | key. See below for details. |
| 1095 | 1099 | ||
| 1096 | @item "x-attribution" | 1100 | @item "x-attribution" |
| 1097 | the original author's suggestion for attribution string choice. See below | 1101 | the original author's suggestion for attribution string choice. See below |
| 1098 | for details.@refill | 1102 | for details.@refill |
| 1099 | @end table | 1103 | @end table |
| 1100 | 1104 | ||
| @@ -1141,7 +1145,7 @@ Each element in this list contains lists of the following form: | |||
| 1141 | @findex sc-mail-field | 1145 | @findex sc-mail-field |
| 1142 | @findex mail-field (sc-) | 1146 | @findex mail-field (sc-) |
| 1143 | where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} | 1147 | where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} |
| 1144 | is a regular expression to match against the @var{infokey}'s value. If | 1148 | is a regular expression to match against the @var{infokey}'s value. If |
| 1145 | @var{regexp} matches the @var{infokey}'s value, the @var{attribution} is | 1149 | @var{regexp} matches the @var{infokey}'s value, the @var{attribution} is |
| 1146 | used as the attribution string. Actually, @var{attribution} can be a | 1150 | used as the attribution string. Actually, @var{attribution} can be a |
| 1147 | string or a list; if it is a list, it is @code{eval}uated and the return | 1151 | string or a list; if it is a list, it is @code{eval}uated and the return |
| @@ -1166,7 +1170,7 @@ The fallback author name is contained in the variable | |||
| 1166 | @code{sc-default-author-name} and the fallback attribution string is | 1170 | @code{sc-default-author-name} and the fallback attribution string is |
| 1167 | contained in the variable @code{sc-default-attribution}. Default values | 1171 | contained in the variable @code{sc-default-attribution}. Default values |
| 1168 | for these variables are @code{"Anonymous"} and @code{"Anon"}, | 1172 | for these variables are @code{"Anonymous"} and @code{"Anon"}, |
| 1169 | respectively. Note that in most circumstances, getting the default | 1173 | respectively. Note that in most circumstances, getting the default |
| 1170 | author name or attribution is a sign that something is set up | 1174 | author name or attribution is a sign that something is set up |
| 1171 | incorrectly. | 1175 | incorrectly. |
| 1172 | 1176 | ||
| @@ -1174,7 +1178,7 @@ incorrectly. | |||
| 1174 | @vindex use-only-preference-p (sc-) | 1178 | @vindex use-only-preference-p (sc-) |
| 1175 | Also, if the preferred attribution, which you specified in your | 1179 | Also, if the preferred attribution, which you specified in your |
| 1176 | @code{sc-preferred-attribution-list} variable cannot be found, a | 1180 | @code{sc-preferred-attribution-list} variable cannot be found, a |
| 1177 | secondary method can be employed to find a valid attribution string. The | 1181 | secondary method can be employed to find a valid attribution string. The |
| 1178 | variable @code{sc-use-only-preference-p} controls what happens in this | 1182 | variable @code{sc-use-only-preference-p} controls what happens in this |
| 1179 | case. If the variable's value is non-@code{nil}, then | 1183 | case. If the variable's value is non-@code{nil}, then |
| 1180 | @code{sc-default-author-name} and @code{sc-default-attribution} are | 1184 | @code{sc-default-author-name} and @code{sc-default-attribution} are |
| @@ -1209,11 +1213,11 @@ attribution alist. | |||
| 1209 | @vindex sc-confirm-always-p | 1213 | @vindex sc-confirm-always-p |
| 1210 | @vindex confirm-always-p (sc-) | 1214 | @vindex confirm-always-p (sc-) |
| 1211 | Once the attribution string has been automatically selected, a number of | 1215 | Once the attribution string has been automatically selected, a number of |
| 1212 | things can happen. If the variable @code{sc-confirm-always-p} is | 1216 | things can happen. If the variable @code{sc-confirm-always-p} is |
| 1213 | non-@code{nil}, you are queried for confirmation of the chosen | 1217 | non-@code{nil}, you are queried for confirmation of the chosen |
| 1214 | attribution string. The possible values for completion are those strings | 1218 | attribution string. The possible values for completion are those strings |
| 1215 | in the attribution alist, however you are not limited to these choices. | 1219 | in the attribution alist, however you are not limited to these choices. |
| 1216 | You can type any arbitrary string at the confirmation prompt. The string | 1220 | You can type any arbitrary string at the confirmation prompt. The string |
| 1217 | you enter becomes the value associated with the @code{"sc-lastchoice"} | 1221 | you enter becomes the value associated with the @code{"sc-lastchoice"} |
| 1218 | key in the attribution alist. | 1222 | key in the attribution alist. |
| 1219 | 1223 | ||
| @@ -1279,7 +1283,7 @@ author's name proper. Examples include the titles ``Dr.'', ``Mr.'', | |||
| 1279 | Also, some companies prepend or append the name of the division, | 1283 | Also, some companies prepend or append the name of the division, |
| 1280 | organization, or project on the author's name. All of these titles are | 1284 | organization, or project on the author's name. All of these titles are |
| 1281 | noise which should be ignored. The variable @code{sc-name-filter-alist} | 1285 | noise which should be ignored. The variable @code{sc-name-filter-alist} |
| 1282 | is used for this purpose. As implied by its name, this variable is an | 1286 | is used for this purpose. As implied by its name, this variable is an |
| 1283 | association list, where each element is a cons cell of the form: | 1287 | association list, where each element is a cons cell of the form: |
| 1284 | 1288 | ||
| 1285 | @example | 1289 | @example |
| @@ -1290,7 +1294,7 @@ association list, where each element is a cons cell of the form: | |||
| 1290 | where @var{regexp} is a regular expression that is matched (using | 1294 | where @var{regexp} is a regular expression that is matched (using |
| 1291 | @code{string-match}) against each element of the @samp{From:@:} field's | 1295 | @code{string-match}) against each element of the @samp{From:@:} field's |
| 1292 | author name. @var{position} is a position indicator, starting at zero. | 1296 | author name. @var{position} is a position indicator, starting at zero. |
| 1293 | Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, | 1297 | Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, |
| 1294 | @code{sc-name-filter-alist} would have an entry such as: | 1298 | @code{sc-name-filter-alist} would have an entry such as: |
| 1295 | 1299 | ||
| 1296 | @example | 1300 | @example |
| @@ -1380,10 +1384,10 @@ The four special symbol values for @var{pred} are recognized: | |||
| 1380 | @item t | 1384 | @item t |
| 1381 | Always produces a true outcome. | 1385 | Always produces a true outcome. |
| 1382 | @item begin | 1386 | @item begin |
| 1383 | Always executed before the frame is interpreted. This can be used to | 1387 | Always executed before the frame is interpreted. This can be used to |
| 1384 | initialize some global variables for example. | 1388 | initialize some global variables for example. |
| 1385 | @item end | 1389 | @item end |
| 1386 | Always executed after frame interpreting is completed. This can be used | 1390 | Always executed after frame interpreting is completed. This can be used |
| 1387 | to perform any necessary post-processing. | 1391 | to perform any necessary post-processing. |
| 1388 | @item every | 1392 | @item every |
| 1389 | Executes whenever the frame is reset, usually after the entire frame has | 1393 | Executes whenever the frame is reset, usually after the entire frame has |
| @@ -1406,12 +1410,12 @@ of the following elements:@refill | |||
| 1406 | @table @asis | 1410 | @table @asis |
| 1407 | @item the symbol @code{continue} | 1411 | @item the symbol @code{continue} |
| 1408 | This tells Regi to continue processing entries after a match, instead of | 1412 | This tells Regi to continue processing entries after a match, instead of |
| 1409 | resetting the frame and moving @samp{point}. In this way, lines of text | 1413 | resetting the frame and moving @samp{point}. In this way, lines of text |
| 1410 | can have multiple matches, but you have to be careful to avoid entering | 1414 | can have multiple matches, but you have to be careful to avoid entering |
| 1411 | infinite loops. | 1415 | infinite loops. |
| 1412 | 1416 | ||
| 1413 | @item the symbol @code{abort} | 1417 | @item the symbol @code{abort} |
| 1414 | This tells Regi to terminate frame processing. However, any @code{end} | 1418 | This tells Regi to terminate frame processing. However, any @code{end} |
| 1415 | entry is still processed. | 1419 | entry is still processed. |
| 1416 | 1420 | ||
| 1417 | @item the list @code{(frame . @var{newframe})} | 1421 | @item the list @code{(frame . @var{newframe})} |
| @@ -1422,7 +1426,7 @@ can be the frame in-lined.@refill | |||
| 1422 | 1426 | ||
| 1423 | @item the list @code{(step . @var{step})} | 1427 | @item the list @code{(step . @var{step})} |
| 1424 | Tells Regi to move @var{step} number of lines forward as it continues | 1428 | Tells Regi to move @var{step} number of lines forward as it continues |
| 1425 | processing. By default, Regi moves forward one line. @var{step} can be | 1429 | processing. By default, Regi moves forward one line. @var{step} can be |
| 1426 | zero or negative of course, but watch out for infinite loops.@refill | 1430 | zero or negative of course, but watch out for infinite loops.@refill |
| 1427 | @end table | 1431 | @end table |
| 1428 | 1432 | ||
| @@ -1510,12 +1514,12 @@ is not found from the alist, then the appropriate default frame is used. | |||
| 1510 | 1514 | ||
| 1511 | Once the original message has been yanked into the reply buffer, and | 1515 | Once the original message has been yanked into the reply buffer, and |
| 1512 | @code{sc-cite-original} has had a chance to do its thing, a number of | 1516 | @code{sc-cite-original} has had a chance to do its thing, a number of |
| 1513 | useful Supercite commands will be available to you. Since there is wide | 1517 | useful Supercite commands will be available to you. Since there is wide |
| 1514 | variety in the keymaps that MUAs set up in their reply buffers, it is | 1518 | variety in the keymaps that MUAs set up in their reply buffers, it is |
| 1515 | next to impossible for Supercite to properly sprinkle its commands into | 1519 | next to impossible for Supercite to properly sprinkle its commands into |
| 1516 | the existing keymap. For this reason Supercite places its commands on a | 1520 | the existing keymap. For this reason Supercite places its commands on a |
| 1517 | separate keymap, putting this keymap onto a prefix key in the reply | 1521 | separate keymap, putting this keymap onto a prefix key in the reply |
| 1518 | buffer. You can customize the prefix key Supercite uses by changing the | 1522 | buffer. You can customize the prefix key Supercite uses by changing the |
| 1519 | variable @code{sc-mode-map-prefix}. By default, the | 1523 | variable @code{sc-mode-map-prefix}. By default, the |
| 1520 | @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, | 1524 | @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, |
| 1521 | but unfortunately the best general solution so far. In the rest of this | 1525 | but unfortunately the best general solution so far. In the rest of this |
| @@ -1536,7 +1540,7 @@ prefix.@refill | |||
| 1536 | 1540 | ||
| 1537 | Probably the three most common post-yank formatting operations that you | 1541 | Probably the three most common post-yank formatting operations that you |
| 1538 | will perform will be the manual citing, reciting, and unciting of | 1542 | will perform will be the manual citing, reciting, and unciting of |
| 1539 | regions of text in the reply buffer. Often you may want to recite a | 1543 | regions of text in the reply buffer. Often you may want to recite a |
| 1540 | paragraph to use a nickname, or manually cite a message when setting | 1544 | paragraph to use a nickname, or manually cite a message when setting |
| 1541 | @code{sc-cite-region-limit} to @code{nil}. The following commands | 1545 | @code{sc-cite-region-limit} to @code{nil}. The following commands |
| 1542 | perform these functions on the region of text between @samp{point} and | 1546 | perform these functions on the region of text between @samp{point} and |
| @@ -1582,7 +1586,7 @@ cited line in the region by interpreting the selected frame from | |||
| 1582 | @item @code{sc-recite-region} (@kbd{C-c C-p r}) | 1586 | @item @code{sc-recite-region} (@kbd{C-c C-p r}) |
| 1583 | This command recites each line the region by interpreting the selected | 1587 | This command recites each line the region by interpreting the selected |
| 1584 | frame from @code{sc-recite-frame-alist}, or the default reciting frame | 1588 | frame from @code{sc-recite-frame-alist}, or the default reciting frame |
| 1585 | @code{sc-default-recite-frame}. It runs the hook | 1589 | @code{sc-default-recite-frame}. It runs the hook |
| 1586 | @code{sc-pre-recite-hook} before interpreting the frame. | 1590 | @code{sc-pre-recite-hook} before interpreting the frame. |
| 1587 | @xref{Configuring the Citation Engine}.@refill | 1591 | @xref{Configuring the Citation Engine}.@refill |
| 1588 | 1592 | ||
| @@ -1606,7 +1610,7 @@ These two functions insert various strings into the reply buffer. | |||
| 1606 | @vindex preferred-header-style (sc-) | 1610 | @vindex preferred-header-style (sc-) |
| 1607 | Inserts a reference header into the reply buffer at @samp{point}. With | 1611 | Inserts a reference header into the reply buffer at @samp{point}. With |
| 1608 | no arguments, the header indexed by @code{sc-preferred-header-style} is | 1612 | no arguments, the header indexed by @code{sc-preferred-header-style} is |
| 1609 | inserted. An optional numeric argument is the index into | 1613 | inserted. An optional numeric argument is the index into |
| 1610 | @code{sc-rewrite-header-list} indicating which reference header to | 1614 | @code{sc-rewrite-header-list} indicating which reference header to |
| 1611 | write.@refill | 1615 | write.@refill |
| 1612 | 1616 | ||
| @@ -1719,7 +1723,7 @@ Allows you to interactively view, modify, add, and delete info alist | |||
| 1719 | key-value pairs. With no argument, you are prompted (with completion) | 1723 | key-value pairs. With no argument, you are prompted (with completion) |
| 1720 | for a info key. The value associated with that key is displayed in the | 1724 | for a info key. The value associated with that key is displayed in the |
| 1721 | minibuffer. With an argument, this command will first ask if you want | 1725 | minibuffer. With an argument, this command will first ask if you want |
| 1722 | to view, modify, add, or delete an info key. Viewing is identical to | 1726 | to view, modify, add, or delete an info key. Viewing is identical to |
| 1723 | running the command with no arguments. | 1727 | running the command with no arguments. |
| 1724 | 1728 | ||
| 1725 | If you want to modify the value of a key, Supercite will first prompt | 1729 | If you want to modify the value of a key, Supercite will first prompt |
| @@ -1770,7 +1774,7 @@ an optional numeric argument inserts that many new lines.@refill | |||
| 1770 | @chapter Hints to MUA Authors | 1774 | @chapter Hints to MUA Authors |
| 1771 | 1775 | ||
| 1772 | In June of 1989, some discussion was held between the various MUA | 1776 | In June of 1989, some discussion was held between the various MUA |
| 1773 | authors, the Supercite author, and other Supercite users. These | 1777 | authors, the Supercite author, and other Supercite users. These |
| 1774 | discussions centered around the need for a standard interface between | 1778 | discussions centered around the need for a standard interface between |
| 1775 | MUAs and Supercite (or any future Supercite-like packages). This | 1779 | MUAs and Supercite (or any future Supercite-like packages). This |
| 1776 | interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in | 1780 | interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in |
| @@ -1810,14 +1814,14 @@ some default citing when that is the case.@refill | |||
| 1810 | 1814 | ||
| 1811 | If you are writing a new MUA package, or maintaining an existing MUA | 1815 | If you are writing a new MUA package, or maintaining an existing MUA |
| 1812 | package, you should make it conform to this interface so that your users | 1816 | package, you should make it conform to this interface so that your users |
| 1813 | will be able to link Supercite easily and seamlessly. To do this, when | 1817 | will be able to link Supercite easily and seamlessly. To do this, when |
| 1814 | setting up a reply or forward buffer, your MUA should follow these | 1818 | setting up a reply or forward buffer, your MUA should follow these |
| 1815 | steps: | 1819 | steps: |
| 1816 | 1820 | ||
| 1817 | @enumerate | 1821 | @enumerate |
| 1818 | @item | 1822 | @item |
| 1819 | Insert the original message, including the mail headers into the reply | 1823 | Insert the original message, including the mail headers into the reply |
| 1820 | buffer. At this point you should not modify the raw text in any way | 1824 | buffer. At this point you should not modify the raw text in any way |
| 1821 | (except for any necessary decoding, e.g., of quoted-printable text), and | 1825 | (except for any necessary decoding, e.g., of quoted-printable text), and |
| 1822 | you should place all the original headers into the body of the reply. | 1826 | you should place all the original headers into the body of the reply. |
| 1823 | This means that many of the mail headers will be duplicated, one copy | 1827 | This means that many of the mail headers will be duplicated, one copy |
| @@ -1826,7 +1830,7 @@ there will probably be more headers below this line.@refill | |||
| 1826 | 1830 | ||
| 1827 | @item | 1831 | @item |
| 1828 | Set @samp{point} to the beginning of the line containing the first mail | 1832 | Set @samp{point} to the beginning of the line containing the first mail |
| 1829 | header in the body of the reply. Set @samp{mark} at the end of the | 1833 | header in the body of the reply. Set @samp{mark} at the end of the |
| 1830 | message text. It is very important that the region be set around the | 1834 | message text. It is very important that the region be set around the |
| 1831 | text Supercite is to modify and that the mail headers are within this | 1835 | text Supercite is to modify and that the mail headers are within this |
| 1832 | region. Supercite will not venture outside the region for any reason, | 1836 | region. Supercite will not venture outside the region for any reason, |
| @@ -1834,7 +1838,7 @@ and anything within the region is fair game, so don't put anything that | |||
| 1834 | @strong{must} remain unchanged inside the region.@refill | 1838 | @strong{must} remain unchanged inside the region.@refill |
| 1835 | 1839 | ||
| 1836 | @item | 1840 | @item |
| 1837 | Run the hook @code{mail-citation-hook}. You will probably want to | 1841 | Run the hook @code{mail-citation-hook}. You will probably want to |
| 1838 | provide some kind of default citation functions in cases where the user | 1842 | provide some kind of default citation functions in cases where the user |
| 1839 | does not have Supercite installed. By default, your MUA should | 1843 | does not have Supercite installed. By default, your MUA should |
| 1840 | @code{defvar} @code{mail-citation-hook} to @code{nil}, and in your | 1844 | @code{defvar} @code{mail-citation-hook} to @code{nil}, and in your |
| @@ -1853,9 +1857,9 @@ this interface ``out of the box.'' | |||
| 1853 | 1857 | ||
| 1854 | The Supercite package was derived from its predecessor Superyank 1.11 | 1858 | The Supercite package was derived from its predecessor Superyank 1.11 |
| 1855 | which was inspired by various bits of code and ideas from Martin Neitzel | 1859 | which was inspired by various bits of code and ideas from Martin Neitzel |
| 1856 | and Ashwin Ram. They were the folks who came up with the idea of | 1860 | and Ashwin Ram. They were the folks who came up with the idea of |
| 1857 | non-nested citations and implemented some rough code to provide this | 1861 | non-nested citations and implemented some rough code to provide this |
| 1858 | style. Superyank and Supercite version 2 evolved to the point where much | 1862 | style. Superyank and Supercite version 2 evolved to the point where much |
| 1859 | of the attribution selection mechanism was automatic, and features have | 1863 | of the attribution selection mechanism was automatic, and features have |
| 1860 | been continuously added through the comments and suggestions of the | 1864 | been continuously added through the comments and suggestions of the |
| 1861 | Supercite mailing list participants. | 1865 | Supercite mailing list participants. |