9. Post-yank Formatting Commands

Once the original message has been yanked into the reply buffer, and sc-cite-original has had a chance to do its thing, a number of useful Supercite commands will be available to you. Since there is wide variety in the keymaps that MUAs set up in their reply buffers, it is next to impossible for Supercite to properly sprinkle its commands into the existing keymap. For this reason Supercite places its commands on a separate keymap, putting this keymap onto a prefix key in the reply buffer. You can customize the prefix key Supercite uses by changing the variable sc-mode-map-prefix. By default, the sc-mode-map-prefix is C-c C-p; granted, not a great choice, but unfortunately the best general solution so far. In the rest of this chapter, we'll assume you've installed Supercite's keymap on the default prefix.

9.1 Commands to Manually Cite, Recite, and Uncite

Probably the three most common post-yank formatting operations that you will perform will be the manual citing, reciting, and unciting of regions of text in the reply buffer. Often you may want to recite a paragraph to use a nickname, or manually cite a message when setting sc-cite-region-limit to nil. The following commands perform these functions on the region of text between `point' and `mark'. Each of them sets the undo boundary before modifying the region so that the command can be undone in the standard Emacs way.

A quick note about Emacs 19. Unlike in Emacs 18, the region delimited by `point' and `mark' can have two states. It can be active or inactive. Although the FSF Emacs 19 and Lucid Emacs 19 use different terminology and functions, both employ the same convention such that when the region is inactive, commands that modify the region should generate an error. The user needs to explicitly activate the region before successfully executing the command. All Supercite commands conform to this convention.

Here is the list of Supercite citing commands:

sc-cite-region (C-c C-p c)

This command cites each line in the region of text by interpreting the selected frame from sc-cite-frame-alist, or the default citing frame sc-default-cite-frame. It runs the hook sc-pre-cite-hook before interpreting the frame. With an optional universal argument (C-u), it temporarily sets sc-confirm-always-p to t so you can confirm the attribution string for a single manual citing. See section 8. Configuring the Citation Engine.

sc-uncite-region (C-c C-p u)

This command removes any citation strings from the beginning of each cited line in the region by interpreting the selected frame from sc-uncite-frame-alist, or the default unciting frame sc-default-uncite-frame. It runs the hook sc-pre-uncite-hook before interpreting the frame. See section 8. Configuring the Citation Engine.

sc-recite-region (C-c C-p r)

This command recites each line the region by interpreting the selected frame from sc-recite-frame-alist, or the default reciting frame sc-default-recite-frame. It runs the hook sc-pre-recite-hook before interpreting the frame. See section 8. Configuring the Citation Engine.

Supercite will always ask you to confirm the attribution when reciting a region, regardless of the value of sc-confirm-always-p.

9.2 Insertion Commands

These two functions insert various strings into the reply buffer.

sc-insert-reference (C-c C-p w)

Inserts a reference header into the reply buffer at `point'. With no arguments, the header indexed by sc-preferred-header-style is inserted. An optional numeric argument is the index into sc-rewrite-header-list indicating which reference header to write.

With just the universal argument (C-u), electric reference mode is entered, regardless of the value of sc-electric-references-p.

sc-insert-citation (C-c C-p i)

Inserts the current citation string at the beginning of the line that `point' is on. If the line is already cited, Supercite will issue an error and will not cite the line.

9.3 Variable Toggling Shortcuts

Supercite defines a number of commands that make it easier for you to toggle and set various Supercite variables as you are editing the reply buffer. For example, you may want to turn off filling or whitespace cleanup, but only temporarily. These toggling shortcut commands make this easy to do.

Like Supercite commands in general, the toggling commands are placed on a keymap prefix within the greater Supercite keymap. For the default value of sc-mode-map-prefix, this will be C-c C-p C-t.

The following commands toggle the value of certain Supercite variables which take only a binary value:

C-c C-p C-t b

Toggles the variable sc-mail-nuke-blank-lines-p.

C-c C-p C-t c

Toggles the variable sc-confirm-always-p.

C-c C-p C-t d

Toggles the variable sc-downcase-p.

C-c C-p C-t e

Toggles the variable sc-electric-references-p.

C-c C-p C-t f

Toggles the variable sc-auto-fill-region-p.

C-c C-p C-t o

Toggles the variable sc-electric-circular-p.

C-c C-p C-t s

Toggles the variable sc-nested-citation-p.

C-c C-p C-t u

Toggles the variable sc-use-only-preferences-p.

C-c C-p C-t w

Toggles the variable sc-fixup-whitespace-p.

The following commands let you set the value of multi-value variables, in the same way that Emacs' set-variable does:

C-c C-p C-t a

Sets the value of the variable sc-preferred-attribution-list.

C-c C-p C-t l

Sets the value of the variable sc-cite-region-limit.

C-c C-p C-t n

Sets the value of the variable sc-mail-nuke-mail-headers.

C-c C-p C-t N

Sets the value of the variable sc-mail-header-nuke-list.

C-c C-p C-t p

Sets the value of the variable sc-preferred-header-style.

One special command is provided to toggle both sc-auto-fill-region-p and sc-fixup-whitespace-p together. This is because you typically want to run Supercite with either variable as nil or non-nil. The command to toggle these variables together is bound on C-c C-p C-p.

Finally, the command C-c C-p C-t h (also C-c C-p C-t ?) brings up a Help message on the toggling keymap.

9.4 Mail Field Commands

These commands allow you to view, modify, add, and delete various bits of information from the info alist. See section 3. Information Keys and the Info Alist.

sc-mail-field-query (C-c C-p f)

Allows you to interactively view, modify, add, and delete info alist key-value pairs. With no argument, you are prompted (with completion) for a info key. The value associated with that key is displayed in the minibuffer. With an argument, this command will first ask if you want to view, modify, add, or delete an info key. Viewing is identical to running the command with no arguments.

If you want to modify the value of a key, Supercite will first prompt you (with completion) for the key of the value you want to change. It will then put you in the minibuffer with the key's current value so you can edit the value as you wish. When you hit RET, the key's value is changed. For those of you running Emacs 19, minibuffer history is kept for the values.

If you choose to delete a key-value pair, Supercite will prompt you (with completion) for the key to delete.

If you choose to add a new key-value pair, Supercite firsts prompts you for the key to add. Note that completion is turned on for this prompt, but you can type any key name here, even one that does not yet exist. After entering the key, Supercite prompts you for the key's value. It is not an error to enter a key that already exists, but the new value will override any old value. It will not replace it though; if you subsequently delete the key-value pair, the old value will reappear.

sc-mail-process-headers (C-c C-p g)

This command lets you re-initialize Supercite's info alist from any set of mail headers in the region between `point' and `mark'. This function is especially useful for replying to digest messages where Supercite will initially set up its information for the digest originator, but you want to cite each component article with the real message author. Note that unless an error during processing occurs, any old information is lost.

9.5 Miscellaneous Commands

sc-open-line (C-c C-p o)

Similar to Emacs' standard open-line commands, but inserts the citation string in front of the new line. As with open-line, an optional numeric argument inserts that many new lines.

sc-describe (C-c C-p h and C-c C-p ?)

This function has been obsoleted by the TeXinfo manual you are now reading. It is still provided for compatibility, but it will eventually go away.

sc-version (C-c C-p v)

Echos the version of Supercite you are using. With the optional universal argument (C-u), this command inserts the version information into the current buffer.

sc-submit-bug-report (C-c C-p C-b)

If you encounter a bug, or wish to suggest an enhancement, use this command to set up an outgoing mail buffer, with the proper address to the Supercite maintainer automatically inserted in the `To:' field. This command also inserts information that the Supercite maintainer can use to recreate your exact setup, making it easier to verify your bug.

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