.. _using-bibolamazi-app:

Using the Bibolamazi Application
================================

Bibolamazi Operating Mode
-------------------------

Bibolamazi works by reading your reference bibtex files---the 'sources', which might for
example have been generated by your favorite bibliography manager or provided by your
collaborators---and merging them all into a new file, applying specific rules, or
'filters', such as turning all the first names into initials or normalizing the way arxiv
IDs are presented.

The Bibolamazi file is this new file, in which all the required bibtex entries will be
merged. When you prepare you LaTeX document, you should create a new bibolamazi file, and
provide that bibolamazi file as the bibtex file for the bibliography.

When you open a bibolamazi file, you will be prompted to edit its configuration.  This is
the set of rules which will tell bibolamazi where to look for your bibtex entries and how
to handle them. You first need to specify all your sources, and then all the filters.

The bibolamazi file is then a valid BibTeX file to include into your LaTeX document, so if
your bibolamazi file is named ``main.bibolamazi.bib``, you would include the bibliography
in your document with a LaTeX command similar to::

    \bibliography{main.bibolamazi}


Getting Started
---------------

The easiest way to get started is to open the bibolamazi graphical application,
and click on "Create new bibolamazi file".  A sequence of prompts will allow you
to specify where your source bibtex files are, and how you'd like to
standardize/normalize/transform those entries.  Finally, you will be asked where
to save the new bibolamazi file.  Then, the file will be opened for you.

The code that is displayed is the bibolamazi configuration section. The
Bibolamazi program reads this configuration section and parses the corresponding
instructions in order fetch and perform the necessary tasks on your bibliography
entries.  The new file will already contain a valid configuration section.

Try the "Run Bibolamazi" button at the top: This should run the given filters on
the source files you have specified.  In order to view the run-time messages,
click on the "Messages" tab on the lower part of the window.

You can view the resulting, processed bibtex entries in the "Preview Bibtex
Entries" tab.  The "Bibolamazi File Info" tab contains some general information
about the parsed configuration section.

You may edit the configuration section if you are not happy with the results.
In the configuration section, lines that start with ``filter:`` instruct
bibolamazi to apply a filter to all the bibliography entries.  The word
immediately after ``filter:`` (for instance, ``filter: arxiv``) specifies which
filter to apply.  The rest of the line are options which alter the filter's behavior.

For instance, click on a line that starts with ``filter:``.  The right part of
the screen will change so that you can select different options for that filter.
If you click on an option in the table, you will see a description of what that
option does below the table.  Double-click on the right part of the table to
edit an option's value.

Don't forget to include the bibolamazi file in place of your bibliography in
your LaTeX document. So, if the bibolamazi file is named
``main.bibolamazi.bib``, include a line like so in your LaTeX document::

  \bibliography{main.bibolamazi}


Editing the configuration section
---------------------------------

For precise instructions on the configuration section, see
:ref:`bibolamazi-configuration-section`.