6. Replying and Yanking

This chapter explains what happens when you reply and yank an original message from an MUA.

6.1 Reply Buffer Initialization

Executing sc-cite-original performs the following steps as it initializes the reply buffer:

1. Runs sc-pre-hook. This hook variable is run before sc-cite-original does any other work. You could conceivably use this hook to set certain Supercite variables based on the reply buffer's mode or name (i.e., to do something different based on whether you are replying or following up to an article).

2. Inserts Supercite's keymap. Supercite provides a number of commands for performing post-yank modifications to the reply buffer. These commands are installed on Supercite's top-level keymap. Since Supercite has to interface with a wide variety of MUAs, it does not install all of its commands directly into the reply buffer's keymap. Instead, it puts its commands on a keymap prefix, then installs this prefix onto the buffer's keymap. What this means is that you typically have to type more characters to invoke a Supercite command, but Supercite's keybindings can be made much more consistent across MUAs.

   You can control what key Supercite uses as its keymap prefix by changing the variable sc-mode-map-prefix. By default, this variable is set to C-c C-p; a finger twister perhaps, but unfortunately the best default due to the scarcity of available keybindings in many MUAs.

3. Turns on Supercite minor mode. The modeline of the reply buffer should indicate that Supercite is active in that buffer by displaying the string `SC'.

4. Sets the "Undo Boundary". Supercite sets an undo boundary before it begins to modify the original yanked text. This allows you to easily undo Supercite's changes to affect alternative citing styles.

5. Processes the mail headers. All previously retrieved info key-value pairs are deleted from the info alist, then the mail headers in the body of the yanked message are scanned. Info key-value pairs are created for each header found. Also, such useful information as the author's name and email address are extracted. If the variable sc-mail-warn-if-non-rfc822-p is non-nil, then Supercite will warn you if it finds a mail header that does not conform to RFC822. This is rare and indicates a problem either with your MUA or the original author's MUA, or some MTA (mail transport agent) along the way.

   Once the info keys have been extracted from the mail headers, the headers are nuked from the reply buffer. You can control exactly which headers are removed or kept, but by default, all headers are removed.

   There are two variables which control mail header nuking. The variable sc-nuke-mail-headers controls the overall behavior of the header nuking routines. By setting this variable to 'all, you automatically nuke all mail headers. Likewise, setting this variable to 'none inhibits nuking of any mail headers. In between these extremes, you can tell Supercite to nuke only a specified list of mail headers by setting this variable to 'specified, or to keep only a specified list of headers by setting it to 'keep.

   If sc-nuke-mail-headers is set to 'specified or 'keep, then the variable sc-nuke-mail-header-list is consulted for the list of headers to nuke or keep. This variable contains a list of regular expressions. If the mail header line matches a regular expression in this list, the header will be nuked or kept. The line is matched against the regexp using looking-at rooted at the beginning of the line.

   If the variable sc-blank-lines-after-headers is non-nil, it contains the number of blank lines remaining in the buffer after mail headers are nuked. By default, only one blank line is left in the buffer.

6. Selects the attribution and citation strings. Once the mail headers have been processed, Supercite selects a attribution string and a citation string which it will use to cite the original message. See section 7. Selecting an Attribution, for details.

7. Cites the message body. After the selection of the attribution and citation strings, Supercite cites the original message by inserting the citation string prefix in front of every uncited line. You may not want Supercite to automatically cite very long messages however. For example, some email could contain a smaller header section followed by a huge uuencoded message. It wouldn't make sense to cite the uuencoded message part when responding to the original author's short preface. For this reason, Supercite provides a variable which limits the automatic citation of long messages to a certain maximum number of lines. The variable is called sc-cite-region-limit. If this variable contains an integer, messages with more lines that this will not be cited at all, and a warning message will be displayed. Supercite has performed everything necessary, though, for you to manually cite only the small portion of the original message that you want to use.

   If sc-cite-region-limit contains a non-nil value, the original message will always be cited, regardless of its size. If the variable contains the value nil, the region will never be cited automatically. Use this if you always want to be able to edit and cite the message manually.

   The variable sc-cite-blank-lines-p controls whether blank lines in the original message should be cited or not. If this variable is non-nil, blank lines will be cited just like non-blank lines. Otherwise, blank lines will be treated as paragraph separators.

   Citing of the original message is highly configurable. Supercite's default setup does a pretty good job of citing many common forms of previously cited messages. But there are as many citation styles out there as people on the net, or just about! It would be impossible for Supercite to anticipate every style in existence, and you probably wouldn't encounter them all anyway. But you can configure Supercite to recognize those styles you see often. See section 8. Configuring the Citation Engine, for details.

8. Runs sc-post-hook. This variable is very similar to sc-pre-hook, except that it runs after sc-cite-original is finished. This hook is provided mostly for completeness and backward compatibility. Perhaps it could be used to reset certain variables set in sc-pre-hook.

6.2 Filling Cited Text

Supercite will automatically fill newly cited text from the original message unless the variable sc-auto-fill-region-p has a nil value. Supercite will also re-fill paragraphs when you manually cite or re-cite text.

However, during normal editing, Supercite itself cannot be used to fill paragraphs. This is a change from version 2. There are other add-on lisp packages which do filling much better than Supercite ever did. The two best known are filladapt and gin-mode. Both work well with Supercite and both are available at the normal Emacs Lisp archive sites. gin-mode works pretty well out of the box, but if you use filladapt, you may want to run the function sc-setup-filladapt from your sc-load-hook. This simply makes filladapt a little more Supercite savvy than its default setup.

Also, Supercite will collapse leading whitespace between the citation string and the text on a line when the variable sc-fixup-whitespace-p is non-nil. The default value for this variable is nil.

Its important to understand that Supercite's automatic filling (during the initial citation of the reply) is very fragile. That is because figuring out the fill-prefix for a particular paragraph is a really hard thing to do automatically. This is especially the case when the original message contains code or some other text where leading whitespace is important to preserve. For this reason, many Supercite users typically run with sc-auto-fill-region-p (and possibly also sc-fixup-whitespace-p) set to nil. They then manually fill each cited paragraph in the reply buffer.

I usually run with both these variables containing their default values. When Supercite's automatic filling breaks on a particular message, I will use Emacs' undo feature to undo back before the citation was applied to the original message. Then I'll toggle the variables and manually cite those paragraphs that I don't want to fill or collapse whitespace on. See section 9.3 Variable Toggling Shortcuts.

If you find that Supercite's automatic filling is just too fragile for your tastes, you might consider one of these alternate approaches. Also, to make life easier, a shortcut function to toggle the state of both of these variables is provided on the key binding C-c C-p C-p (with the default value of sc-mode-map-prefix; see section 9. Post-yank Formatting Commands).

You will noticed that the minor mode string will show the state of these variables as qualifier characters. When both variables are nil, the Supercite minor mode string will display `SC'. When just sc-auto-fill-region-p is non-nil, the string will display `SC:f', and when just sc-fixup-whitespace-p is non-nil, the string will display `SC:w'. When both variables are non-nil, the string will display `SC:fw'. Note that the qualifiers chosen are mnemonics for the default bindings of the toggling function for each respective variable. See section 9.3 Variable Toggling Shortcuts.

Why are these variables not set to nil by default? It is because many users won't manually fill paragraphs that are Supercited, and there have been widespread complaints on the net about mail and news messages containing lines greater than about 72 characters. So the default is to fill cited text.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.