Usage

Command Line Usage

bibtex2bibtex makes the following assumptions about BibTeX entries:

• some additional (non-standard) BibTeX field names are optionally used: coworkers, and copy
• a coworkers field consists of no, one, or more separe coworker entries. These are separated by a colon.
• a copy field consists of no, one, or more separate copy entries. If a copy of the literature paper described by the BibTeX entry exists, and has been given an identifying label, this is listed here. Each of the entries must have the following canonical form: it starts with an identifier (non-numeric, may include a blank), followed by a sequential numerating code (numbers + possibly some pre- and appended non-numeric characters), followed by a blank and a comment. Thus, the copy entry is separated into (up to) three parts by (1) the occurrence of the first numeric character, and (2) a blank after this (and possibly additional) numeric characters. The copy entries are separated by a semicolon.

bibtex2bibtex may be invoked from the command line in three forms:

bibtex2bibtex --version

This prints the version number of the program.

bibtex2bibtex --help

This prints a help menu. This information is also shown if bibtex2bibtex is called without any argument.

bibtex2bibtex [options] [-c criterion] -f inputfile [-[p]m mergefile]

This will read an input file inputfile in BibTeX format and use it according to the options. If some sorting is required, the criterion given is used. A mergefile can be merged with the input file, again using the criterion.

Options:

Options starting with -- can be used with only giving an inputfile. Options --version and --help (see above) must be the first arguments to bibtex2bibtex (in case of their use, all other arguments are ignored). Those arguments starting with - must be accompanied by a criterion.

--count
print the number of BibTeX entries in file inputfile.

--genkey
generate keys for those entries in inputfile which have an empty key. The key is generated from the lastnames of the authors and the year of publication in analogy to the rules adopted for WoStransform.

--verbose
verbose action; writes a lot of output to stdout.

-v
same as --verbose.

-n
write sorted results to a new file. This file has the name of inputfile with the string .sorted appended.

-d
detect duplicate entries (as defined by identical BibTeX keys) and copy them into a separate file. This file has the name of inputfile with the string .duplicates appended. This option has only an effect if used with -c key and -c copy.

-c criterion
the sorting criterion; must be one of key, coworkers, copy, or source.

key sorts the entries according to the BibTeX keys. The keys are assumed to be of the structure adopted by WoStransform (see Introduction to WoStransform). Two keys are sorted according to their tokens (last names, "etal_" string, year of publication) without taking into account upper and lower case letters in last names. The tokens are compared in order first last name, second last name, year. If a key key1 has less tokens than a key key2, but one or two last names are equal, it is less than key2.

If sorting according to keys is selected, a mergefile can be included into the inputfile. In this case, all entries in mergefile are compared to the entries in inputfile in order to detect duplicates (see -d above). Such duplicates between inputfile and mergefile are excluded from the merging process and are copied to a file with the name of the mergefile with the string .duplicates appended.

coworkers sorts the entries according to the coworkers field (non-standard in BibTeX). Coworkers in the coworkers field are separated by ",". The entries which are connected to a particular coworker are collected in a file with the name of the inputfile with the string .x appended, where "x" is substituted by the coworker's name.

copy sorts according to the contents of the copy field (see above; non-standard in BibTeX). Each entry in the copy field is analyzed and gives rise to a separate listing. The sorting algorithm first checks the identifier and collates all entries with respect to this non-numeric information. For example, this identifier can be used to mark all entries collected by a certain person or stored in a certain library. Within the resulting list, entries are sorted with respect to the numerating code. Together with the identifier this code generates a unique label designating a certain copy of the respective literature paper. If several physical copies of a paper exist, more than one such label will be present. The numerating code will mostly consist of a number, but this can be augmented (for example, if the physical copy of a paper with number 1234 consists of three parts due to excessive size, these could be coded with `1234a,b,c'). On the other hand, no label can be given to more than one paper. The comment part is following the numerating code after a blank. It is only used for generating the sequence of the sorted list, but is not further interpreted. The sorted list is written to a file with the name of the inputfile with the string .copies appended. If the -d option is given, duplicates with respect to the labels are detected and written to a file with the name of the inputfile with the string .duplicates appended. The comment part of the copy entries is not used for duplicate detection. Thus, two copy entries which only differ with respect to the comment part are regarded as duplicates.

source sorts the entries according to the source of the publication, e.g. the journal in which it was published. All entries from the same source are collected in a file with the name of the inputfile with the string .x appended, where "x" is substituted by the name of the source with all blanks removed. This is advantageously used for checking correct spelling and consistency of source names.

Examples

• bibtex2bibtex --version
  

  print the version number of bibtex2bibtex

• bibtex2bibtex --count -f databasefile.bib
  

  count the BibTeX entries in databasefile.bib and print the result

• bibtex2bibtex -c key -f databasefile.bib
  

  sort the entries in databasefile.bib according to the keys of the entries. Replace the contents of the original file with the sorted version.

• bibtex2bibtex -c key -n -f databasefile.bib
  

  sort the entries in databasefile.bib according to the keys of the entries. Leave the contents of the original file intact and write the sorted entries to a new file.

• bibtex2bibtex -c key -n -d -f databasefile.bib
  

  sort the entries in databasefile.bib according to the keys of the entries and detect duplicates. Leave the contents of the original file intact and write the sorted entries to a new file.

• bibtex2bibtex -c key -f databasefile.bib -m new.bib
  

  merge the entries in new.bib into databasefile.bib according to the key. In this case duplicates (as defined by identical keys) between the two files are always detected and written to a separate file. The duplicates should always be checked with the entries in databasefile.bib. In some cases, e.g. the references pointed to by the keys are indeed different, and only the keys are identical. In such a case human intervention is warranted to change one of the keys.

• bibtex2bibtex -c key -f databasefile.bib -pm new.bib
  

  Similiar as before, but the program only pretends to merge the contents of the files. It leaves databasefile.bib alone and sorts the entries in new.bib into two files new.bib.merge_duplicates (containing those entries which are assumed to be duplicates) and new.bib.merge_includes (containing those entries which normaly would be included by the merging process). This is helpful if the user is not sure whether the entries to be merged are all correct and wants to check them before they are really included. In particular, this can be used to detect duplicates. Note, that such duplicates in terms of BibTeX keys are not necessarily meaning that the same reference is listed twice. In many such cases, the automatic key generation is using a too simple algorithm (see above). In such a case again, human intervention is necessary to change one of the keys. A second run with -m new.bib.merge_includes then completes the task.

Exit Status

• 0
  successful execution of the program
• 1
  file or argument error

Error Messages

Error messages of bibtex2bibtex are mostly self explanatory.

• can't open file: xxx
inputfile xxx does not exist or has insufficient privileges.
  
  

• can't open file to merge: xxx


mergefile xxx does not exist or has insufficient privileges.

• no input file given
  an argument -f inputfile is missing from the argument list.

• no or illegal criterion given
  The criterion passed with option -c does not equal coworkers, key, or source.

Warning Messages

The following warnings may occur:

• illegal Key structure: xxx
  
  key xxx does not conform to the rules (see above, option --genkey). Sorting may be erroneous. Key should be corrected.

---