gistfile1.txt

Disambiguation
''''''''''''''

There are five methods to disambiguate cites that otherwise can not be
unambiguously linked to their target bibliographic entries:

1. Showing more names.
2. Adding given names.
3. Replacing initials with full given names.
4. Adding a year-suffix.
5. Rendering the cite with the ``disambiguate`` attribute of ``cs:choose``
   conditions testing "true".

Methods 2 and 3 can be used for the broader purpose of disambiguating *names*.

Disambiguation methods are activated with the following optional attributes, and
are always tried in the listed order:

``disambiguate-add-names`` [Step (1)]
    If set to "true" ("false" is the default), names that would otherwise be
    hidden as a result of et-al abbreviation are added one by one until
    disambiguation is achieved. If adding names does not lead to disambiguation,
    no names are added, except when ``disambiguate-add-names`` is used in
    combination with ``disambiguate-add-givenname``. In this case, all names are
    added.

``disambiguate-add-givenname`` [Steps (2) & (3)]
    If set to "true" ("false" is the default), given names are added or
    expanded. For example:

    ================================  ===================================
    Original ambiguous cites          Disambiguated cites
    ================================  ===================================
    (Simpson 2005; Simpson 2005)      (H. Simpson 2005; B. Simpson 2005)
    (Doe 1950; Doe 1950)              (John Doe 1950; Jane Doe 1950)
    ================================  ===================================

    The value of ``givenname-disambiguation-rule`` determines a) how names are
    expanded, and b) whether unambiguous cites that contain ambiguous names
    (e.g. "(Doe 1950; Doe 2000)" referring to works by respectively Jane and
    John Doe) are also subject to this type of disambiguation.

``givenname-disambiguation-rule``
    Specifies whether ``disambiguate-add-givenname`` affects unambiguous cites,
    how individual names are expanded, and which names within a cite are
    affected.

    **Ambiguous Names in Unambiguous Cites**
        If ``givenname-disambiguation-rule`` is set to "all-names",
        "all-names-with-initials", "primary-name", or
        "primary-name-with-initials", disambiguation is attempted for all
        ambiguous names, including those within unambiguous cites.

        If set to "by-cite", disambiguation is limited to ambiguous names within
        ambiguous cites.

    **Expansion of Individual Names**
        The steps by which individual names can be disambiguated are (the value
        of ``givenname-disambiguation-rule`` determines which steps are used):

        1. If ``initialize-with`` is set, then:

           \(a) Initials can be shown by rendering the name with ``form`` set to
           "long" instead of "short" (e.g. "Doe" becomes "J. Doe").
           
           \(b) Full given names can be shown instead of initials by ignoring
           ``initialize-with`` (e.g. "J. Doe" becomes "John Doe").

        2. If ``initialize-with`` is *not* set, full given names can be shown
           by rendering the name with ``form`` set to "long" instead of "short"
           (e.g. "Doe" becomes "John Doe").
    
    **Given Name Disambiguation Rules**
        For all five given name disambiguation rules, described below, names are
        only expanded if they lead to disambiguation. When name disambiguation
        is successful, any names added by ``disambiguate-add-names`` following
        the first disambiguating name are discarded. When name disambiguation is
        unsuccessful, all names added by ``disambiguate-add-names`` are
        discarded.

        "all-names"
            Default. Ambiguous names are progressively transformed until they
            are disambiguated (e.g. "(A. Doe 2000; B. Doe 2001)" instead of
            "(Doe 2000; Doe 2001)"). If disambiguation cannot be achieved, names
            remain in their original form.

        "all-names-with-initials"
            As "all-names", but name expansion is limited to step 1(a). If
            ``initialize-with`` is not set, no disambiguation attempt is made.

        "primary-name"
            As "all-names", but disambiguation is limited to the first name of
            each cite.

        "primary-name-with-initials"
            As "primary-name", but name expansion is limited to step 1(a). If
            ``initialize-with`` is not set, no disambiguation attempt is made.

        "by-cite"
            As "all-names", but name expansion is limited to ambiguous names in
            ambiguous cites.

``disambiguate-add-year-suffix`` [Step (4)]
    If set to "true" ("false" is the default), an alphabetic year-suffix is
    added to ambiguous cites (e.g. "Doe 2007, Doe 2007" becomes "Doe 2007a, Doe
    2007b") and to their corresponding bibliographic entries. The assignment of
    the year-suffixes follows the order of the bibliographies entries, and
    additional letters are used once "z" is reached ("z", "aa", "ab", ..., "az",
    "ba", etc.). By default the year-suffix is appended to the cite, and to the
    first year rendered through ``cs:date`` in the bibliographic entry, but its
    location can be controlled by explicitly rendering the "year-suffix"
    variable using ``cs:text``. If "year-suffix" is rendered through ``cs:text``
    in the scope of ``cs:citation``, it is suppressed for ``cs:bibliography``,
    unless it is also rendered through ``cs:text`` in the scope of
    ``cs:bibliography``, and vice versa.

If ambiguous cites remain after applying the selected disambiguation methods
described above, a final disambiguation attempt is made by rendering these cites
with the ``disambiguate`` condition testing "true" [Step (5)] (see `Choose`_).