Go to the first, previous, next, last section, table of contents.

# Selecting an Attribution

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.

## Attribution Preferences

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"`
  the author's email terminus.
`"initials"`
  the author's initials.
`"firstname"`
  the author's first name.
`"lastname"`
  the author's last name.
`"middlename-1"`
  the author's first middle name.
`"sc-lastchoice"`
  the last attribution string you have selected. This is useful when you recite paragraphs in the reply.
`"sc-consult"`
  consults the customizable list `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"`
  the original author's suggestion for attribution string choice. See below for details.

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 `eval`uated 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.

## Anonymous Attributions

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:

1. Use the last selected attribution, if there is one.
2. Use the value of the `"x-attribution"` key.
3. Use the author's first name.
4. Use the author's last name.
5. Use the author's initials.
6. Find the first non-`nil`, non-empty attribution string in the attribution alist.
7. `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.

## Author Names

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.

Go to the first, previous, next, last section, table of contents.