Introduction to Bibolamazi¶

What Bibolamazi Does¶

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}

Graphical Application and Command-Line¶

Bibolamazi comes in two flavors: a graphical application and a command-line interface. If you’re unsure, go for the graphical application. To install it, download the version suitable for your system (Mac OS X or Windows) on the github releases page.

You can install the command-line version using pip install bibolamazi. On Linux, you can also install the graphical application via pip install bibolamazigui. For more information, see Downloading and Installing Bibolamazi.

Example Usage Scenario¶

A typical scenario of Bibolamazi usage might be:

You use a bibliography manager, such as Mendeley, to store all your references. You have maybe configured e.g. Mendeley to keep a BibTeX file Documents/bib/MyLibrary.bib in sync with your library;
You’re working, say on a document mydoc.tex, which cites entries from MyLibrary.bib;
You like to keep URLs in your entries in your Mendeley library, because it lets you open the journal page easily, but you don’t want the URLs to be displayed in the bibliography of your document mydoc.tex. But you’ve gone through all the bibliography styles, and really, the one you prefer unfortunatly does display those URLs.
You don’t want to edit the file MyLibrary.bib, because it would just be overwritten again the next time you open Mendeley. The low-tech solution (what people generally do!) would then be to export the required citations from Mendeley to a new bibtex file, or copy MyLibrary.bib to a new file, and edit that file manually.
To avoid having to perform this tedious task manually, you can use Bibolamazi to prepare the BibTeX file as you would like it to be. For this specific task, for example, you would perform the following steps:
- Create a bibolamazi file, say, mydoc.bibolamazi.bib;
- Specify as a source your original MyLibrary.bib:
```
src: ~/Documents/bib/MyLibrary.bib
```
- Give the following filter command:
```
filter: url -dStrip
```
  which instructs to strip all urls (check out the documentation of the url filter in the Help & Reference Browser)
- Run bibolamazi.
- Use this file as your bibtex bibliography, i.e. in your LaTeX document, use:
```
\bibliography{mydoc.bibolamazi}
```
Note that you can then run Bibolamazi as many times as you like, to update your file, should there have been changes to your original MyLibrary.bib, for example.

Getting started¶

The bibolamazi application provides an interactive way of creating a new bibolamazi file that will guide you through a standard selection of clean-ups that you can choose from. Open the app, click on Create New Bibolamazi File …, and follow the instructions.

The Bibolamazi Configuration Section¶

If you open the Bibolamazi application and open your bibolamazi file (or create a new one), you’ll immediately be prompted to edit its configuration section.

Sources are the normal bibtex files from which bibtex entries are read. A source is specified using the bibolamazi command

src: source-file.bib  [ alternative-source-file.bib  ... ]

Alternative source locations can be specified, in case the first file does not exist. This is convenient to locate a file which might be in different locations on different computers. Each source file name can be an absolute path or a relative path (relative to the bibolamazi file). It can also be an HTTP URL which will be downloaded automatically.

You can specify several sources by repeating the src: command.

src: first-source.bib  alternative-first-source.bib
src: second-source.bib
...

Remember: the first readable source of each source command will be read, and merged into the bibolamazi file.

Filters are rules to apply on the whole bibliography database. Their syntax is

filter: filter_name  <filter-options>

The filter is usually meant to deal with a particular task, such as for example changing all first names of authors into initials.

For a list of filters and what they do, please refer the first page of this help browser.

You can usually fine-tune the behavior of the filter by providing options. For a list of options for a particular filter, please refer again to the help page of that filter.

Teaser: Features¶

The most prominent features of Bibolamazi include:

A duplicates filter allows you to efficiently collaborate on LaTeX documents: in your shared LaTeX document, each collaborator may cite entries in his own bibliography database (each a source in the bibolamazi file). Then, if instructed to do so, bibolamazi will detect when two entries are duplicates of each other, merge their information, and produce LaTeX definitions such that the entries become aliases of one another. Then both entry keys will refer to the same entry in the bibliography.

Catch: there is one catch to this, though, which we can do nothing about: if two entries in two different database share the same key, but refer to different entries. This may happen, for example, if you have automatic citation keys of the form AuthorYYYY, and if the author published several papers that same year.
A powerful arxiv filter, which can normalize the way entries refer to the arXiv.org online preprint repository. It can distinguish between published and unpublished entries, and its output is highly customizable.
A general-purpose fixes filter provides general fixes that are usually welcome in a BibTeX files. For example, revtex doesn’t like Mendeley’s way of exporting swedish ‘Å’, for example in Åberg, as \AA berg, and introduces a space between the ‘Å’ and the ‘berg’. This filter allows you to fix this.
Many more! Check out the filter list in the Help & Reference Browser window of Bibolamazi!