As you know, the attribution string is the part of the author's name that will be used to composed a non-nested citation string. Supercite scans the various mail headers present in the original article and uses a number of heuristics to extract strings which it puts into the attribution association list or attribution alist. This is analogous, but different than, the info alist previously mentioned. Each element in the attribution alist is a key-value pair containing such information as the author's first name, middle names, and last name, the author's initials, and the author's email terminus.
When you cite an original message, you can tell Supercite which part of
the author's name you would prefer it to use as the attribution. The
variable sc-preferred-attribution-list controls this; it contains
keys which are matched against the attribution alist in the given order.
The first value of a key that produces a non-nil, non-empty
string match is used as the attribution string, and if no keys match, a
secondary mechanism is used to generate the attribution.
See section Anonymous Attributions.
The following preferences are always available in the attribution alist (barring error):
"emailname"
"initials"
"firstname"
"lastname"
"middlename-1"
"sc-lastchoice"
"sc-consult"
sc-attrib-selection-list which can
be used to select special attributions based on the value of any info
key. See below for details.
"x-attribution"
Middle name indexes can be any positive integer greater than zero, though it is unlikely that many authors will have more than one middle name, if that many.
At this point, let me digress into a discussion of etiquette. It is my belief that while the style of the citations is a reflection of the personal tastes of the replier (i.e., you), the attribution selection is ultimately the personal choice of the original author. In a sense it is his or her "net nickname", and therefore the author should have some say in the selection of attribution string. Imagine how you would feel if someone gave you a nickname that you didn't like?
For this reason, Supercite recognizes a special mail header,
`X-Attribution:', which if present, tells Supercite the attribution
string preferred by the original author. It is the value of this header
that is associated with the "x-attribution" key in the
attribution alist. Currently, you can override the preference of this
key by changing sc-preferred-attribution-list, but that isn't
polite, and in the future Supercite may hard-code this. For now, it is
suggested that if you change the order of the keys in this list, that
"x-attribution" always be first, or possible second behind only
"sc-lastchoice". This latter is the default.
The value "sc-consult" in sc-preferred-attribution-list
has a special meaning during attribution selection. When Supercite
encounters this preference, it begins processing a customizable list of
attributions, contained in the variable sc-attrib-selection-list.
Each element in this list contains lists of the following form:
(infokey ((regexp . attribution)
(regexp . attribution)
(...)))
where infokey is a key for sc-mail-field and regexp
is a regular expression to match against the infokey's value. If
regexp matches the infokey's value, the attribution is
used as the attribution string. Actually, attribution can be a
string or a list; if it is a list, it is evaluated and the return
value (which must be a string), is used as the attribution.
This can be very useful for when you are replying to net acquaintances who do not use the `X-Attribution:' mail header. You may know what nickname they would prefer to use, and you can set up this list to match against a specific mail field, e.g., `From:', allowing you to cite your friend's message with the appropriate attribution.
When the author's name cannot be found in the `From:' mail
header, a fallback author name and attribution string must be supplied.
The fallback author name is contained in the variable
sc-default-author-name and the fallback attribution string is
contained in the variable sc-default-attribution. Default values
for these variables are "Anonymous" and "Anon",
respectively. Note that in most circumstances, getting the default
author name or attribution is a sign that something is set up
incorrectly.
Also, if the preferred attribution, which you specified in your
sc-preferred-attribution-alist variable cannot be found, a
secondary method can be employed to find a valid attribution string. The
variable sc-use-only-preference-p controls what happens in this
case. If the variable's value is non-nil, then
sc-default-author-name and sc-default-attribution are
used, otherwise, the following steps are taken to find a valid
attribution string, and the first step to return a non-nil,
non-empty string becomes the attribution:
"x-attribution" key.
nil, non-empty attribution string in the
attribution alist.
sc-default-attribution is used.
Once the attribution string has been automatically selected, a number of
things can happen. If the variable sc-confirm-always-p is
non-nil, you are queried for confirmation of the chosen
attribution string. The possible values for completion are those strings
in the attribution alist, however you are not limited to these choices.
You can type any arbitrary string at the confirmation prompt. The string
you enter becomes the value associated with the "sc-lastchoice"
key in the attribution alist.
Once an attribution string has been selected, Supercite will force the
string to lower case if the variable sc-downcase-p is
non-nil.
Two hook variables provide even greater control of the attribution
selection process. The hook sc-attribs-preselect-hook is run
before any attribution is selected. Likewise, the hook
sc-attribs-postselect-hook is run after the attribution is
selected (and the corresponding citation string is built), but before
these values are committed for use by Supercite. During the
post-selection hook, the local variables attribution and
citation are bound to the appropriate strings. By changing these
variables in your hook functions, you change the attribution and
citation strings used by Supercite. One possible use of this would be
to override any automatically derived attribution string when it is only
one character long; e.g. you prefer to use "initials" but the
author only has one name.
Supercite employs a number of heuristics to decipher the author's name based on value of the `From:' mail field of the original message. Supercite can recognize almost all of the common `From:' field formats in use. If you encounter a `From:' field that Supercite cannot parse, please report this bug. See section The Supercite Mailing List.
There are a number of Supercite variables that control how author names are extracted from the `From:' header. Some headers may contain a descriptive title as in:
From: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
Supercite knows which part of the `From:' header is email address
and which part is author name, but in this case the string "Decent
Hacker" is not part of the author's name. You can tell Supercite to
ignore the title, while still recognizing hyphenated names through the
use of a regular expression in the variable sc-titlecue-regexp.
This variable has the default value of "\\\\s +-+\\\\s +". Any
text after this regexp is encountered is ignored as noise.
Some `From:' headers may contain extra titles in the name fields
not separated by a title cue, but which are nonetheless not part of the
author's name proper. Examples include the titles "Dr.", "Mr.",
"Ms.", "Jr.", "Sr.", and "III" (e.g., Thurston Howe, the Third).
Also, some companies prepend or append the name of the division,
organization, or project on the author's name. All of these titles are
noise which should be ignored. The variable sc-name-filter-alist
is used for this purpose. As implied by its name, this variable is an
association list, where each element is a cons cell of the form:
(regexp . position)
where regexp is a regular expression that is matched (using
string-match) against each element of the `From:' field's
author name. position is a position indicator, starting at zero.
Thus to strip out all titles of "Dr.", "Mr.", etc. from the name,
sc-name-filter-alist would have an entry such as:
("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" . 0)
which only removes them if they appear as the first word in the name.
The position indicator is an integer, or one of the two special symbols
last or any. last always matches against the last
word in the name field, while any matches against every word in
the name field.