BibTeX VCS is a python package that helps sharing a BibTeX database with a control system (VCS). It is optimized for usage together with the JabRef BibTeX manager.

Collecting and managing bibliography information can be cumbersone. Therefore it makes sense to maintain a single BibTeX database within a research group that focusses on the same topic and thus has a lot of common bibliography. Furthermore, tools like JabRef allow to link PDF documents to BibTeX entries, turning the bib file into a valuable literature database.

Since the bib file is text-based, it can be efficiently put under revision control. However, such a database used by several people over a long period of time tends to become messy. Furthermore, most people are not trained, and even less interested in, the usage of VCS systems.

BibTeX VCS resolves these issues by automating the most common VCS operations and providing a minimalist, platform-independent GUI. It allows to defined a number of database checks that are run prior to each commit operation, in order to enforce consistency and a defined referencing style within the database. For example, there is a check that ensures that the documents linked to BibTeX entries actually exist, and each PDF document is linked to by at least one BibTeX entry. For information on the default checks and how to add custom ones, see checksModule.

BibTeX VCS needs a Python interpreter. Python version 3.x is recommended, but the package will also run with Python 2.7. The easiest way to install it is using pip:

pip install bibtexvcs

You may need to replace pip in the above command by pip-x.y, where x.y denotes the desired Python version. If you want to use the GUI, you need to install either PyQt4, PyQt5, or PySide for the same version of Python. For exporting the database using a template, Jinja2 is an additional requirement.

Below are some platform-specific instructions.

Install Python 3, pip and PyQt5 (both for Python 3) using your distribution's package manager. If available, you can also install the Python 3 version of pyparsing. Then open a terminal and type:

pip3 install --user bibtexvcs

To start the GUI, either run the executable created by pip (default location: $HOME/.local/bin/btvcs), or invoke:

python3 -m bibtexvcs.gui

Install PySide according to the instructions on the home page. Then run the pip command as described above.

Download and install Python. If you choose Python 3.4 or later, be sure to check pip and Add python.exe to Path. Then, download and install either PyQt5 or PySide for the same Python verson. Afterwards open a terminal and type:

pip3 install bibtexvcs

This will install BibTeX VCS and all of its requirements. To start the GUI, either type btvcs into the terminal, or double-click on btvcs.exe in C:\PythonX.Y\Scripts.

A BibTeX VCS database consists of a repository of supported type (currently, this is only Mercurial, but other VCS systems are easy to implement). The toplevel directory of the repository, henceforth called the database directory, must contain a file named bibtexvcs.conf which consists of key = value-type configuration options. The possible configuration options are:

bibfile

name of the BibTeX database file. Defaults to references.bib.

documents

directory in which PDF (and other) documents that are referenced from BibTeX entries are placed. Default: Documents.

name (optional)

A title for the database (e.g., Literature of the Optimization Research Group).

BibTeX VCS includes a graphical user interface (GUI), based on Qt, that allows to perform the most commont tasks without having to use the command line:

• clone a database from a remote repository,
• update the local checkout of a repository
• viewing and editing journal abbreviations,
• commiting changes into the remote repository, thereby running database checks,
• open the BibTeX database with JabRef,
• export <Exporting> the database to HTML using the default template,
• open the public HTML export (if it exists).

The GUI is run by the btvcs command that is installed automatically with the package. Alternatively, you can directly run the gui module by invoking:

python -m bibtexvcs.gui

The GUI needs either PyQt5, PyQt4 or PySide for Python 3 to be installed.

Depending on the publisher's demands, journal names in the references list should either be abbreviated (like in J. Comput. Syst. Sci.) or not (Journal of Computer and Journal Sciences). Since BibTeX does not support specifying both versions in the same entry, a common workaround is the use of macros. In the BibTeX file, the journal entry is defined as a macro reference (say, J_COM_SS). Then, there are two additional BibTeX files, one containing macro (string) definitions for the full, one for the abbreviated journal names. In your paper, you then include the main bibfile and the corresponding macro definition file. That way, the version of journal names does not have to be specified in the shared database.

In order to ease handling of journal abbreviations, BibTeX VCS uses a simple configuration file <journalstxt> that contains, for each journal, an entry of the form:

[MACRO_NAME]
full = Full Journal Name
abbr = Abbrev. J. Name

The GUI allows to conveniently edit journal macros in a table structure.

BibTeX VCS then automatically generates the BibTeX files containing macro definitions for full and abbreviated journal names, respectively. They will be named like the main bibfile but augmented by _full and _abbr, respectively.

A BibTeX VCS database can be exported to HTML and other formats using the Jinja2 templating engine. A default template creates a searchable HTML table containing, for each entry, the most common fields, places a link to the PDF document if that exists, and allows to view the raw BibTeX source for each entry. If you upload the result to a public web space, the database can be used in read-only mode without having access to the version control system, and without having to install the BibTeX VCS package.