4. Reference Headers

Supercite will insert an informative reference header at the beginning of the cited body of text, which display more detail about the original article and provides the mapping between the attribution and the original author in non-nested citations. Whereas the citation string usually only contains a portion of the original author's name, the reference header can contain such information as the author's full name, email address, the original article's subject, etc. In fact any information contained in the info alist can be inserted into a reference header.

There are a number of built-in header rewrite functions supplied by Supercite, but you can write your own custom header rewrite functions (perhaps using the built-in ones as examples). The variable sc-rewrite-header-list contains the list of such header rewrite functions. This list is consulted both when inserting the initial reference header, and when displaying electric references. See section 4.2 Electric References.

When Supercite is initially run on a reply buffer (via sc-cite-original), it will automatically call one of these functions. The one it uses is defined in the variable sc-preferred-header-style. The value of this variable is an integer which is an index into the sc-rewrite-header-list, beginning at zero.

4.1 The Built-in Header Rewrite Functions

Below are examples of the various built-in header rewrite functions. Please note the following: first, the text which appears in the examples below as infokey indicates that the corresponding value of the info key from the info alist will be inserted there. (See section 3. Information Keys and the Info Alist.). For example, in sc-header-on-said below, date and from correspond to the values of the `Date:' and `From:' mail headers respectively.

Also, the string ">>>>>" below is really the value of the variable sc-reference-tag-string. This variable is used in all built-in header rewrite functions, and you can customize its value to change the tag string globally.

Finally, the references headers actually written may omit certain parts of the header if the info key associated with infokey is not present in the info alist. In fact, for all built-in headers, if the `From:' field is not present in the mail headers, the entire reference header will be omitted (but this usually signals a serious problem either in your MUA or in Supercite's installation).

sc-no-header

This function produces no header. It should be used instead of nil to produce a blank header. This header can possibly contain a blank line after the mail-header-separator line.

sc-no-blank-line-or-header

This function is similar to sc-no-header except that any blank line after the mail-header-separator line will be removed.

sc-header-on-said

>>>>> On date, from said:

sc-header-inarticle-writes

>>>>> In article message-id, from writes:

sc-header-regarding-adds

>>>>> Regarding subject; from adds:

sc-header-attributed-writes

>>>>> "sc-attribution" == sc-author <sc-reply-address> writes:

sc-header-author-writes

>>>>> sc-author writes:

sc-header-verbose

>>>>> On date,
>>>>> sc-author
>>>>> from the organization of organization
>>>>> who can be reached at: sc-reply-address
>>>>> (whose comments are cited below with: "sc-cite")
>>>>> had this to say in article message-id
>>>>> in newsgroups newsgroups
>>>>> concerning the subject of subject
>>>>> see references for more details

4.2 Electric References

By default, when Supercite cites the original message for the first time, it just goes ahead and inserts the reference header indexed by sc-preferred-header-style. However, you may want to select different reference headers based on the type of reply or forwarding you are doing. You may also want to preview the reference header before deciding whether to insert it into the reply buffer or not. Supercite provides an optional electric reference mode which you can drop into to give you this functionality.

If the variable sc-electric-references-p is non-nil, Supercite will bring up an electric reference mode buffer and place you into a recursive edit. The electric reference buffer is read-only, so you cannot directly modify the reference text until you exit electric references and insert the text into the reply buffer. But you can cycle through all the reference header rewrite functions in your sc-rewrite-header-list.

You can also set a new preferred header style, jump to any header, or jump to the preferred header. The header will be shown in the electric reference buffer and the header index and function name will appear in the echo area.

The following commands are available while in electric reference mode (shown here with their default key bindings):

sc-eref-next (n)

Displays the next reference header in the electric reference buffer. If the variable sc-electric-circular-p is non-nil, invoking sc-eref-next while viewing the last reference header in the list will wrap around to the first header.

sc-eref-prev (p)

Displays the previous reference header in the electric reference buffer. If the variable sc-electric-circular-p is non-nil, invoking sc-eref-prev will wrap around to the last header.

sc-eref-goto (g)

Goes to a specified reference header. The index (into the sc-rewrite-header-list) can be specified as a numeric argument to the command. Otherwise, Supercite will query you for the index in the minibuffer.

sc-eref-jump (j)

Display the preferred reference header, i.e., the one indexed by the current value of sc-preferred-header-style.

sc-eref-setn (s)

Set the preferred reference header (i.e., sc-preferred-header-style) to the currently displayed header.

sc-eref-exit (LFD, RET, and ESC C-c)

Exit from electric reference mode and insert the current header into the reply buffer.

sc-eref-abort (q, x)

Exit from electric reference mode without inserting the current header.

Supercite will execute the hook sc-electric-mode-hook before entering electric reference mode.

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