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 :ref:`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).
journals
- Name of the journals file. See Journal Abbreviations. Default:
journals.txt
. publicLink
(optional)- URL of a web page containing an exported version of the database (see Exporting).
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,
- :ref:`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 :ref:`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.