Key Generation

BibTool Manual

Reference Manual

Key Generation

Key Generation

The key generation facility provides a mean to uniformly replace the reference keys by generated values. Some algorithms are hardwired, namely the generation of short keys or long keys either unconditionally or only when they are needed. Additionally a free formatting facility is provided. This can be used to specify your own algorithm to generate keys. The generation of new keys can be enabled using the command line option -f in the following way:

bibtool -f format

This command adds format disjunctively to the formatting instructions already given. The same effect can be achieved with the resource key.format.

key.format = {format}

Some values of format have a special meaning. Fixed formatting rules are used when one of them is in effect. The special values are described below. To illustrate their results we consider the following BibTeX database entries:

@Unpublished{unpublished-key,
  author   = "First A. U. Thor and Seco N. D. Author and Third A. Uthor
              and others",
  title    = "This is a rather long title of an unpublished entry which
              exceeds one line",
  ...
}
@Article{,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   ...
}
@BOOK{whole-collection,
   editor = "David J. Lipcoll and D. H. Lawrie and A. H. Sameh",
   title = "High Speed Computer and Algorithm Organization",
   ...
}
@MISC{misc-minimal,
   key = "Missilany",
   note = "This is a minimal MISC entry"
}

short

If a field named key is present then its value is used. Otherwise if an author or editor field are present, then this field is used. The short version uses last names only. Afterwards a title or booktitle field is appended, after the fmt.name.title separator has been inserted. Finally if all else fails then the default key default.key is used. The result is disambiguated (cf. key.base).

To see the effect we apply BibTool to the example entries given earlier with the command line argument -- key.format=short. This results in the following keys (remaining lines skipped):

@Unpublished{     thor.author.ea:this,
@Article{         aamport:gnats,
@Book{            lipcoll.lawrie.ea:high,
@Misc{            missilany,

long

The long version acts like the short version but incorporates initials when formatting names.

If BibTool is applied to the example entries given earlier with the command line argument -- key.format=long we get the following keys:

@Unpublished{     thor.fau.author.snd.ea:this,
@Article{         aamport.la:gnats,
@Book{            lipcoll.dj.lawrie.dh.ea:high,
@Misc{            missilany,

new.short

This version formats like short but only if the given key field is empty. This is obsoleted by the resource preserve.keys and will be withdrawn in a future release.

If BibTool is applied to the example entries given earlier with the command line argument -- key.format=short.need we get the following keys:

@Unpublished{     unpublished-key,
@Article{         aamport:gnats,
@Book{            whole-collection,
@Misc{            misc-minimal,

new.long

This version formats like long but only if the given key field is empty. This is obsoleted by the resource preserve.keys and will be withdrawn in a future release.

If BibTool is applied to the example entries given earlier with the command line argument -- key.format=short.need we get the following keys:

@Unpublished{     unpublished-key,
@Article{         aamport.la:gnats,
@Book{            whole-collection,
@Misc{            misc-minimal,

empty

The empty version clears the key entirely. The result does not conform to the BibTeX syntax rules. This feature can be useful if a resource file must be used which generates only new keys. In this case a first pass can clear the keys and the given resource file acn be applied in a second pass to generate all keys.

If BibTool is applied to the example entries given earlier with the command line argument -- key.format=empty we get the following keys:

@Unpublished{	  ,
@Article{	  ,
@Book{		  ,
@Misc{		  ,

In contrast to the command line option, the resource instruction only modifies the formatting specification. The key generation has to be activated explicitly. This can be done using the command line option -F as in

bibtool -F

Alternatively the boolean resource key.generation can be used in a resource file:

key.generation = on

Usually all keys are regenerated. This can have the unpleasant side-effect to invalidate citations in old documents. For this situation the resource preserve.keys is meant. This resource is usually off. If it is turned on then only those entries receive new keys if they do not have a key already. This means that the input contains only a sequence of whitespace characters (which is not accepted by BibTeX) as in the following example:

@Article{,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   journal = {\mbox{G-Animal's} Journal},
   year = 1986,
   volume = 41,
   number = 7,
   pages = "73+",
   month = jul,
   note = "This is a full ARTICLE entry",
}

Even if preserve.keys is on, BibTool still changes all keys to lower case by default. This can be suppressed by switching preserve.key.case to on (see section Parsing and Pretty Printing).

When the key.format is not empty then the keys are disambiguated by appending letters or numbers. Thus there can not occur a conflict which would arise when two entries have the same key. The disambiguation uses the resource key.number.separator. If a key is found (during the generation) which is already been used then the valid characters from the value of this resource is appended. Additionally a number is added. The appearance of the number can be controlled with the resource key.base. This resource can take the values upper, lower, and digit. The effect can be seen in the following table:

generated key	digit	lower	upper
`key`	`key`	`key`	`key`
`key`	`key*1`	`key*a`	`key*A`
`key`	`key*2`	`key*b`	`key*B`
`key`	`key*3`	`key*c`	`key*C`
`key`	`key*4`	`key*d`	`key*D`

As we have seen there are options to adapt the behavior of formatting. Before we explain the free formating specification in section Format Specification we will present the formatting options. Those options can be activated from a resource file or with the corresponding feature to specify resource instructions on the command line.

preserve.keys: This boolean resource determines whether existing keys should be left unchanged when new keys are generated. The default value is off.
preserve.key.case: This boolean resource determines whether keys should be recorded and used exactly as read as opposed to normalizing them by translating all uppercase letters to lower case. The default value is off.
default.key: The value of this resource is used if nothing else fits. The default value is **key*.
key.base: The value of this resource is used to determine the kind of formatting the disambiguating number. Possible values are upper, lower, and digit. Uppercase letters, lower case letters, or digits are used respectively.
key.number.separator: The value of this resource is used to separate the disambiguating number from the rest of the key. The default value is *.
key.expand.macros: The value of this boolean resource is used to indicate whether macros should be expanded while generating a key. The default value is off.
fmt.name.title: The value of this resource is used by the styles short and long to separate names and titles. The default value is :.
fmt.title.title: The value of this resource is used to separate words inside titles. The default value is :.
fmt.name.name: The value of this resource is used to separate different names (where the BibTeX file has and) when formatting names. The default value is ..
fmt.inter.name: The value of this resource is used to separate parts of multi-word names when formatting names. The default value is -.
fmt.name.pre: The value of this resource is used to separate names and first names when formatting names. The default value is ..
fmt.et.al: The value of this resource is used to format and others parts of a name list. The default value is .ea.

The key style short can be formulated in terms of the format specification given in section Format Specification as follows:

{
  { %-2n(author)
  # %-2n(editor)
  }
  { %s($fmt.name.title) %-1T(title)
  # %s($fmt.name.title) %-1T(booktitle)
  #
  }
}
#
{ { %s($fmt.name.title) %-1T(title)
  # %s($fmt.name.title) %-1T(booktitle)
  }
}
# %s($default.key)

The syntax and meaning of such format specifications is explained in section Format Specification.

Summary

BibTool Manual

Reference Manual

Key Generation