1. Using Bibus
    1. Main interface
      1. Key tree
      2. Reference list
        1. About deleting a reference
    2. Connecting to the database
      1. Why do we need a user name under SQLite?
      2. User types
    3. Importing references
    4. Searching
      1. Searching in the database
      2. Live searches
      3. Searching PubMed
    5. Editing references
    6. Setting preferences
      1. System-wide preferences
      2. User preferences

Using Bibus

Main interface

main interface

The main interface of Bibus should be intuitive for anybody used to a mail reader. On the left is a tree with keys. Each key is associated with a list of references. When the key is selected, the references associated with this key are listed in the listView located on the top panel of the right side of the window. When a reference is selected in this list, this reference is shown at the bottom right of the window. In the figure above, the key selected is 'References', the reference selected is 'Martineau1999#12' and this reference is displayed with its abstract etc.. at the bottom right.

In the status bar, the following information is displayed from left to right:
help messages | number of references in the selected key : number of selected references | style selected.

Key tree

The keys are orderer in a non rooted tree. There are five main categories named 'References', 'Queries', 'All', 'Online' and 'Import'. You cannot modify or add any key at this level.
Let first describe these 6 or 7 main categories:

Reference list

Here are displayed all the references associated with the currently selected key. Again, you can manipulate them by right clicking on them or by using the menu 'Reference'.
An important way to manipulate the references is by using drag & drop. For instance in the figure above, I would like to associated the selected reference(s) (Martineau1999#12) with the key 'References/Mes Papiers/Antibodies' because it is one of my papers and it is about antibody expression. I can drag & drop it on the key References/Mes Papiers/Antibodies. If you now select this key, you will see that the dropped reference is there. If you need to unfold a key for dropping the reference, you can move the cursor (during the drag & drop) over the (+) before the key name.
It is important to understand what happens when you do that:

To edit (create) a reference, select Edit (New) in the popup menu or in the menu 'Reference'. You can also double click on the selected reference(s). You will get a reference editor that allow you to modify and see all the fields. You can edit all the fields except the Identifier because it is automatically generated by Bibus by pasting the name of the first author with the year and adding an unique number generated by the database engine (here 12). This is this Identifier that will be used as the citation key in OpenOffice.org and it is why you cannot modify it.
Finally the last popup menu choice is 'openURL' (or Middle click with the mouse). If the URL field of the selected reference(s) is not empty, the  default navigator will open with the URL selected. For instance, the import filter for PubMed automatically put in the URL field the URL of the reference in PubMed. This feature is broken under linux when using the Python webbrowser module included in OpenOffice.org (Python-2.2.2). It woks well under debian since the Python2.2 distribution contains an updated webbrowser module. If you have problems, try to download it from the CVS (Version seems ok) or use the file included in the Python2.3 distribution.
If your navigator is correctly configured, you can use the URL field to put a link to a "locale" copy of the paper. If you have on your disk (or somewhere else) a pdf version of the following paper:

Marx.pdf located in /home/toto/pdf/

put, in the URL field


When you select 'openURL', the webbrowser will be called and will open Acrobat (or xpdf, ...) to handle the document.

About deleting a reference

When a reference is selected, you can "delete" it by right clicking and choosing "delete" in the menu (or in the third main menu). This is however not a true delete. If you click the 'All' key you will see that the "deleted" reference is still in the database. This is not a bug but a feature. Indeed, since Bibus is multi-user, it is not possible to know if somebody else is using the reference. In addition, somebody may have inserted a citation corresponding to this reference in an OpenOffice. org document. Deleting the reference would result in a broken link for this user. If you think however that the database is growing too much, you can manually delete the references which are not linked to any key. Only the database administrator should do that and only if disk space is a real concern. To retrieve all those references you can use, for instance, the following SQL queries (the first query does not work with SQLite because it does not support RIGHT JOIN):

SELECT id from bibrefLink RIGHT JOIN bibref ON (bibref.id=bibrefLink.ref_id) WHERE bibrefLink.key_Id IS NULL;
SELECT id from bibref LEFT JOIN bibrefLink ON (bibref.id=bibrefLink.ref_id) where bibrefLink.key_id is NULL;

Connecting to the database

When you start Bibus the first time a First Connection Wizard will help you to set a SQLite database containing your bibliographic records. Just follow the instructions on screen. Of course you will be able to change everything later if you like.

If you prefer to use a MySQL database:

Bibus will remember these settings and it will just ask for your password at startup for MySQL (you can change this).

Why do we need a user name under SQLite?

You normally don't need a user name to connect to a SQLite database, so why do we need one in Bibus?
An important feature of Bibus is that it is designed with muti-user in mind.  This means that you must identify yourself in order for Bibus to display the correct content. You must understand that there is only one database that contains all the records. It is what you see when you click on 'All'. But the content under the key 'References' is yours and is different from the content of other users. This is because, depending on your interests, you might not want to include a reference in the same sub-keys (under References) as your collaborators. However, since you share the same database, editing a reference will result in a change for all the users. Thus you should not edit a reference except for correcting typing errors or adding informations. If you really want to make important changes it is better to create a new reference. It is easy to experiment with this under SQLite by using two different user names with two bibus instances opened.

User types

Three types of users can access a Bibus database:
The class of the user is defined at the database level and is a bit different for SQLite and MySQL since MySQL is much more flexible.

Importing references

If you have a database of references, Bibus can import them. Bibus understand three formats, Medline, Refer and RIS. You must first change your database to one of these before importing it.
There are two ways to import references:
Once imported, the references will be found under the key 'Import'. If you want to control them, you can double-click to see all the fields.
The imported references are stored in a temporary area. If you quit Bibus they will be lost. To save them definitely, copy them and paste them (or drag/drop) in the References key or in one of its children.


Bibus uses a powerful yet simple search engine. You can either search the database, PubMed on the Web of you can use 'Live queries' for automatic reference classification. The first two types of search are also directly available in the tool bar.

Searching in the database

By choosing the menu Search/Search (Ctrl S) you will get the following dialog:


First on the top left, you can choose the mode:

On top right you have the choice between:

The rest of the dialog is self explanatory. For those unfamiliar with SQL:

Finally, 'Main Fields' allows a search in 'interesting fields'. For instance, usually we are not interested in searching the URL field. The fields included in 'Main Fields' are displayed at the top of the dialog. 'Main Fields' definition can be changed in the preferences.

When you use the tool bar box for searching, the entered string will be search against 'Main Fields' with a LIKE clause. You can also enter an expert search in the tool bar for instance something like :

authors LIKE '%Einstein%' and year = '1912'

You can put any character in the search since the string will be converted from unicode to 'UTF-8' encoding before searching the database.

Live searches

When you right click on the 'Queries' key, you can select 'New query'.  Bibus will first ask you for a name then will open the same dialog than for search except that the search is restricted to the whole database and that you cannot select 'Current key'.
When your search/query is defined, you can save it and an item, corresponding to this search, will appear as a child of 'Queries'. Each time you click on this item, the database is searched and the result displayed. If the database changes, the result of this search will change. It is important to note that if you change the definition of 'Main Fields' the query result won't change because the definition of 'Main Fields' is stored when the query is defined.
You can edit the query by right clicking the key but only in expert mode. So, except for simple modifications, it may be easier to delete the query and define a new one.

Searching PubMed

You can access PubMed on the Web. This is probably only of interest to people working in the fields of biology and medicine. Again you can either use a 'Normal' or an 'Expert' mode.

At the top left you can select the number of results that you want to import. The default is to import the first 20 records. The choices are self explanatory.
The result of the search will be displayed under the key 'Online'. Each search will replace the previous one. It is important to note that it is a temporary storage. If you quit Bibus and start it again, your search will be lost. If you want to copy some of the results in the database, just drag and drop them to the 'Reference' key or one of its children. You can use any of the usual combinations of shift and ctrl to select more than one reference at a time.
You can use the tool bar to perform a PubMed search. Your string will be used as when you use the Web interface to PubMed. Because the search will download only the first 20 records (PubMed default) it is a good idea to narrow your search.

Editing references

You can edit a reference by double-clicking it in the list or by choosing the menu item Reference/Edit or the context menu (Right-click in the list) Edit.
You can also open an empty editor to create a new reference by choosing the menu item Reference/New (Ctrl+N), by right-click in the list and choosing 'New' or by Right-clicking in a tree item and choosing New in the context menu. The new reference will be created under the currently selected key or under the key you Right-clicked.
The Editor look like this:
Reference Editor
There are three tabs.
Main Fields should normally be filled since they correspond to fields needed by most styles.
Supplementary Fields may be partially filled and correspond to less frequently used values for the current reference type (for instance, the issue Number for an article.
Other Fields are the other possible fields.
There is a Choice at the top for the reference type. By default it is ARTICLE. If you change this type, you will notice that the fields change. This is because the Required fields (Main) fields for a BOOK are different than the fields required for an ARTICLE or an URL. If the default values for Main/Supplementary/other fields don't suit your needs, you can change them in the "Preferences" under the "Editor" tab.
When you edit a reference by default you cannot change the Identifier field. This is because changing this field may be dangerous if the edited reference is used in one of your article. Bibus won't be able to find the reference to format your article in OpenOffice.org. You can however change the identifier by first checking the "Edit identifier" check box.
Shortcuts. The window contains a menu bar. When you first start Bibus, this menubar will be empty. To activate it you must set a list of categories in the preference "Shortcuts" tab. In the Screenshot above, we have defined three categories: Journal, Author and Divers. These category names are just to help you classify your shortcuts and don't have to match the fields names. If you click in one of these categories the menu will look like this:
shortcuts menu
To insert any of the menu item in a field, just locate your cursor at the correct position in the correct field then choose the menu item. For instance, you can insert "FEBS Lett" with a single click in the corresponding menu item in the Journal field. This can save you a lot of typing (and errors).
To save a shortcut, you can either:
Capturing shortcuts from the database. Instead of entering each shortcut by hand, you can decide that you want to  capture all the journal names present in the database and put them in your shortcut list called journal. Here is how to do that:
You can do the same in the reference editor by choosing "Edit shortcut" in the menu but only if the shortcut category has been previously defined in the preference/Shortcuts tab.
Finally, the "using separator" option must be used with fields containing multiple items. For instance, if you want to capture all the authors from the database, check this option and choose ";" as the separator. Bibus will split the author fields using this separator before collecting the author names. This is normally what you want since multiple authors in the author field are separated with ";" and you want each author to appear as an independent shortcut.

Setting preferences

System-wide preferences

If you want to set preferences for all users, you can set many variables in the file "bibus.config".
This file is located either in the BIBUS directory or in the /etc/ directory (Debian and other UNIX in the future).
This file is sourced as a Python file after the BIBbase.py file which contains the system-wide constants. Usually you will set in this file new values for the constants defined in BIBbase.py.
For instance, you may have a central MySQL database for all the users named 'biblioDB'. Put in the bibus.config file the following lines:
import BIBbase
BIBbase.DB_STARTUP = 1 # 0 = last used db used at startup. 1 = default db

BIBbase.DB_TYPE MySQL # type of database used 'MySQL','SQlite', etc... => modules dbBibMySQL,dbBibSQLite, etc...

DB_NAME = 'biblioDB' # Default MySQL database name

BIBbase.PORT = 3306 #
server port used by the MySQL deamon
BIBbase.HOST = 'servername' # server running the MySQL deamon

Because this file is read as a  python file, you can of course use python scripts.

User preferences

Select the menu Edit/Preferences to set some Bibus preferences.
There are three tabs: