.. _introduction-to-bibolamazi: 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 :ref:`download-and-install`. 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. .. _Mendeley: http://mendeley.com/ 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 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!