Package: bibtexvcs
**********************The BibTeX VCS Package**********************`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.Introduction============Collecting and managing bibliography information can be cumbersone. Therefore it makes sense to maintaina single BibTeX database within a research group that focusses on the same topic and thus has a lot ofcommon bibliography. Furthermore, tools like JabRef_ allow to link PDF documents to BibTeX entries, turningthe ``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 databaseused by several people over a long period of time tends to become messy. Furthermore, most people are nottrained, 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 eachcommit 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, andeach PDF document is linked to by at least one BibTeX entry. For information on the default checks and how toadd custom ones, see :ref:`checksModule`.Installation============`BibTeX VCS` needs a Python_ interpreter. Python version 3.x is recommended, but the package will alsorun with Python 2.7. The easiest way to install it is using pip_::pip install bibtexvcsYou 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.Installation on Linux---------------------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 bibtexvcsTo start the GUI, either run the executable created by pip_ (default location: ``$HOME/.local/bin/btvcs``), orinvoke::python3 -m bibtexvcs.guiInstallation on Mac-------------------Install PySide_ according to the instructions on the home page. Then run the ``pip`` command as described above.Installation on Windows-----------------------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 bibtexvcsThis 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`.Repository (Database) Layout============================A `BibTeX VCS` database consists of a repository of supported type (currently, this is only Mercurial_, butother 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``-typeconfiguration 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 areplaced. Default: ``Documents``.``name`` (optional)A title for the database (e.g., `Literature of the Optimization Research Group`)... _journalstxt:``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_).GUI===`BibTeX VCS` includes a graphical user interface (GUI), based on Qt_, that allows to perform the mostcommont 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.guiThe GUI needs either PyQt5_, PyQt4_ or PySide_ for Python 3 to be installed.Journal Abbreviations=====================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 doesnot support specifying both versions in the same entry, a common workaround is the use of `macros`. In theBibTeX file, the ``journal`` entry is defined as a macro reference (say, `J_COM_SS`). Then, there are twoadditional BibTeX files, one containing macro (string) definitions for the full, one for the abbreviatedjournal names. In your paper, you then include the main bibfile and the corresponding macro definitionfile. 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 Nameabbr = Abbrev. J. NameThe GUI_ allows to conveniently edit journal macros in a table structure.`BibTeX VCS` then automatically generates the BibTeX files containing macro definitions for full andabbreviated journal names, respectively. They will be named like the main bibfile but augmented by ``_full``and ``_abbr``, respectively... _Exporting:Exporting=========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 havingaccess to the version control system, and without having to install the `BibTeX VCS` package... _BibTeX : http://www.bibtex.org.. _JabRef: http://jabref.sourceforge.net.. _Mercurial: http://mercurial.selenic.com.. _Jinja2: http://jinja.pocoo.org.. _Qt: http://qt-project.org.. _PyQt5: http://riverbankcomputing.com/software/pyqt/download5.. _PyQt4: http://riverbankcomputing.com/software/pyqt/download.. _PySide: http://qt-project.org/wiki/PySide.. _Python: http://www.python.org.. _pip: http://www.pip-installer.org