bibliography-organizer-sebastian-achim-mueller 1.1.4
Organize your bibliography
License: MIT
Requires Python: >=3

Bibliography Organizer
======================
|BlackStyle|

Helps you to organize and search your local bibliography. ``biborg`` is not invasive, it does not touch your cited documents or bibtex-files. ``biborg`` only offers suggestions to organize your files, as well as a full-text-search.
``biborg`` acts in the filesystem. Its interface is motivated by the version-control-tool ``git``.

Commands
--------
A set of command-line-tools to help you managing your bibliography. The interface is similar to ``git``.

``bib status``
~~~~~~~~~~~~~~
Prints a list of errors and warnings when your entries are not structrured as expected, or when entries are missing crucial parts.

``bib update``
~~~~~~~~~~~~~~
Tries to update the optical-character-recognition ``ocr``, the ``icon.jpg`` in each entry. Finally updates the search-index in your bibliography directory.
When new originals were added, they are read and added to the ``ocr``. Likewise ``ocr``-records will be ignored when the corresponding original does not longer exist.
The ``icon.jpg`` is extracted from the primary original.

``bib search``
~~~~~~~~~~~~~~
Searches for your search-``PHRASE`` in the search-index. Results are printed to the command-line. The search-``PHRASE`` may contain logical operators such as ``AND``, ``OR``, ``NOT``, ``ANDNOT``, ``ANDMAYBE``, ``(``, and ``)``. See documnetation of ``Whoosh``.


Structure
---------

The ``bibliography_organizer``, or ``biborg`` for short, acts in your bibliography directory ``bib_dir``.
The ``bib_dir`` can be any directory in your filesystem. ``biborg``'s command-line-interface expects the current working directory to be a ``bib_dir``.


.. code::

    bib_dir
    |-- citekey_A
    |   |-- original
    |   |   |-- citekey_A.pdf
    |   |   |-- comments.ps
    |   |   |-- preprint.pdf
    |   |
    |   |-- reference.bib
    |
    |-- citekey_B                       <-- you
    |   |-- original                    <-- you
    |   |   |-- citekey_B.html          <-- you
    |   |
    |   |-- reference.bib               <-- you
    |   | 
    |   |-- ocr                         <-- biborg
    |   |   |-- citekey_B.html.tar      <-- biborg
    |   |
    |   |-- icon.jpg                    <-- biborg
    |
    |-- .bibliography_organizer         <-- biborg
        |-- full_text_search_index

Terminology
-----------

``citekey``
~~~~~~~~~~~
The ``citekey`` is a string to identify your reference, e.g. 'darwin1859origin'. In LaTex you use ``\cite{citekey}``.

``bib_dir``
~~~~~~~~~~~
The base directory of your local bibliography. Here, you create and collect your entries in ``entry_dir``s.  ``biborg`` will create a hidden cache in here named ``.bibliography_organizer``.

``entry_dir``
~~~~~~~~~~~~~
An ``entry_dir`` is directory inside your ``bib_dir``. An ``entry_dir`` has the name of the ``citekey``. The ``entry_dir`` contains the original files and a bibtex reference. You create, and populate the ``entry_dir``s in your ``bib_dir``.

``original``
~~~~~~~~~~~~
In every ``entry_dir`` is the original directory. It contains the original files to be cited. Usually, there is only one original-file corresponding to one ``citekey``. But sometimes the original might be a collection of files like a web-page or such. You create the original directory and populate it with your originals.

``reference.bib``
~~~~~~~~~~~~~~~~~
A bibtex-file in the ``entry_dir`` that you create. It contains exactly one bibtex-entry. The ``citekey`` in the bibtex-entry is expected to match the ``entry_dir``.

``ocr``
~~~~~~~~
The ``ocr`` directory is created and updated by ``biborg``. The ``ocr`` directory contains the extracted text from the original files. The text is extracted using optical character recognition. Each original file has one archive in the ``ocr`` directory. The archive contains the text of the individual pages from the original.
This is used to fill the search-index.

``icon``
~~~~~~~~
The ``icon.jpg`` is a small image rendered from the first page of the primary original-file. The ``icon.jpg`` is created by ``biborg``.
The primary original file has the ``citekey`` as its basename.

``full_text_search_index``
~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a hidden directory in ``bib_dir/.bibliography_organizer/full_text_search_index``. It is a cache for the search created and updated by ``biborg``.

To use optical character recognition
------------------------------------

.. code::

    sudo apt-get install tesseract-ocr
    sudo apt-get install imagemagig


.. |BlackStyle| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black