# Autogeneration Format Syntax

## Syntax of the format

The format is used for autogeneration of certain values, such as the cite key and linked file names. The format is a string containing special format specifiers, which are replaced by strings determined by the bibliography data. Most format specifiers have the form of a %-character followed by a single character. It can be followed by optional digits, and extra optional parameters enclosed in square brackets, which serve as parameters for the format specifier. Possible format specifiers are given in the table below. The specifiers are displayed in blue, the optional parameters in green.

Specifier | Replaced content description | Optional parameters
--- | --- | ---
%a[][]00 | Author last names | name separator, et al., max number of names, max name length
%A[;][.][]0 | Author names with initials | name separator, initial separator, et al., max number of names
%p[][]00 | Author or editor last names | name separator, et al., max number of names, max name length
%P[;][.][]0 | Author or editor names with initials | name separator, initial separator, et al., max number of names
%t 0 | Title | max length
%T[]0 | Title | max length of words to ignore, max number of words
%y | Year without century
%Y | Year with century
%m | Month as decimal number
%k[/][]0 | Keywords concatenated together | slash replacement, separator, max number of keywords
%l | File name of the linked file, without extension
%L | File name of the linked file, with extension
%e | File extension of the linked file, including dot
%E[] | File extension of the linked file, without dot | default extension
%b | Bibliography document file name, without extension
%f{Field}[/]0 | Arbitrary field, also ``Cite Key'` or ``BibTeX Type'` | slash replacement, max length
%w{Field}[ ][/][]0 | Words of arbitrary field | separator characters, slash replacement, separator, max number of words
%c{Field}3 | Arbitrary field as initials (acronym) | max length of words to ignore
%s{Field}[][][]0 | Arbitrary field switch | ``Yes'`/non-empty, ``No'`/empty, ``Mixed'`, max length
%i{Key}0 | Arbitrary document info key | max length
%u[][]1 | Unique lowercase letter (use only once) | prefix, suffix, (min) number of characters
%U[][]1 | Unique uppercase letter (use only once) | prefix, suffix, (min) number of characters
%n[][]1 | Unique number (use only once) | prefix, suffix, (min) number of characters
%0 | Escaped digit (0-9)
%% | Escaped percent character (if allowed)
%[ | Escaped square bracket (if allowed)
%] | Escaped square bracket (if allowed)
%- | Escaped dash (if allowed)

In the table above, green characters after the specifiers indicate the optional parameters. The first number after an author specifier, the number of authors, should be a single digit. It can be negative to indicate last authors. Indicated in the table are the parameter values that are used when they are not entered.

The special value of zero for an optional parameter is interpreted either as all (for the ``author'`, ``title'`, or ``field'` specifiers), sufficient (for the ``unique'` specifiers, i.e., sufficient to create a unique cite key), or none (for the ``random'` specifiers).

The format can contain only a single one of the ``unique'` specifiers %u, %U and %n.

The optional parameters delimited by square brackets after an author specifier can be used to control the separator between author names and an optional ``et al.'` suffix. For %A and %P, the first one is the separator between two author names, and the second one is the separator between the last name and the first initial. The last character of the ``et al.'` option can be a digit inidicating the number of authors used before the ``et al.'` suffix, in case that is smaller than the maximum number of authors.

The optional parameter delimited by square brackets after a title specifier %T denotes the maximum length of words to be dropped. If this arguments is missing, words with length up to 3 are not counted, but they are included.

The optional parameter delimited by square brackets after a file extension specifier %E denotes a default extension used when the file has no extension.

The optional parameters delimited by square brackets after one of the ``unique'` specifiers %u, %U and %n are a prefix and a suffix added before or after the added unique characters. These are not inserted when no unique characters are added.

In the local file format the slash-character (/) has a special meaning, as it is used to build the (UNIX style) folder hierarchy. This is usually not what you want generated parts of the format to do. Therefore in the ``author'` and ``title'` slashes are always replaced by dashes (-) for the local file format. The same replacement is also performed by default for the ``keyword'`, ``field'` or ``words'` specifiers. These latter two however can have an optional parameters delimited by square brackets, which can be used to set the replacement string to another value. In particular, setting the argument between brackets to slash (/), no replacement will be made. This is also the default behavior in the cite key format.

Because a number right after most specifiers is interpreted as an optional parameter, in order to use explicit digits right after a format specifier, one should use one of the escape specifiers %0-%9.

The cite key format can contain, apart from the specifiers, only unaccented alphanumeric characters (a-zA-Z0-9), (semi-)colons (:;), dashes (-), slashes (/) or periods (.). Any generated part of the cite key will be converted to contain only those characters. For example, accents are removed and spaces will be converted to dashes.

Keywords are, by default, separated by one of ;:, (semicolon, colon, or comma.) The precise way keywords are separated and how to change these defaults is described in Field Groups.

The format for the local file can contain any character apart from colons (:). To use an explicit percent character, use the escape specifier %%. Also note the special treatment of the slash (/) noted above.

Inside optional arguments, between square brackets, generic specifiers are not allowed, except for escaped characters.

## Examples

    Bibliography:
    M. McCracken, A. Maxwell, J. Howison, M. Routley, S. Spiegel, S. S. Porst, and C. M. Hofman,
    BibDesk, a great application to manage your bibliographies,
    Source Forge, 1:96, 11 2004.

Format string:
  %a 1:%Y%u 2
Resulting value:

  McCracken:2004yc

Format string:
  %a 1:%Y%u
Resulting value:

  McCracken:2004b

Format string:
  %a 03%y%m
Resulting value:

  McCMaxHowRouSpiPorHof0411

Format string:
  %A[;][.][;etal]2:%y%t 20
Resulting value:

  McCracken.M;Maxwell.A;etal:2004BibDesk-a-great-appl

Format string:
  %a[;][;etal]24:%c{Journal}%f{Volume}
Resulting value:

  McCr;Maxw;etal:SF1

## Setting the cite key format

See the discussion in Cite Key Preferences for details on how to set the cite key format.