Using Bibus

Using Bibus

First Start

After installation, a menu item should be present in your "Start Menu" under Windows or under the menu item "Office". Starting bibus the first time will open the FirstTime Wizard:

Just answer the questions. For more detailled instructions with screenshots have a look at the wiki page.

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/Antibodies/Therapy', the reference selected is 'Brodie2009' and this reference is displayed.

The bottom Reference view has 4 choices:

Style As formatted using the current style.
Details Detailed view of the fields.
Keys All the keys associated with the currently selected reference.
Modif Author and Date of the creation and last modification of the reference.

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.

Keytree

The keys are orderer in a non rooted tree. There are 8 main categories. You cannot modify or add any key at this level. Let first describe these main categories:

All my references. This keys contains all your references.
References. It is where you can classify your references. You can add subkeys, modify their names, move them using drag&drop, etc... To do that you can either use the popup menu that appears when you right click on the keys or the third menu 'Reference'. The preferred way is to right click on the key since there are more choices than in the menu and only the available choices will be displayed.
Tagged. This category allows quick organization of your references. When you go through your reference, you may sometimes need to 'tag' a reference to remember it. In such a case, just select the reference and hit "Ctrl + T" and the reference will be copied under the key 'tagged'.
Queries. We will see later how to define queries. You can see them as 'live search'. You can define a search and save it. When you click on this query, Bibus looks in the database and show the references that fulfill the search. If you change the database, the search will be automatically updated. In fact a query is simply an SQL query.
PubMed Search. When you do a PubMed search, the result is available here.
Import buffer. When you import a file (Medline or EndNote/Refer), the result is available here.
Cited. If the connection with OOo is active, all the citations cited in the current OOo document are displayed under this key.
Unclassified. The reference available in the database but that you did not drop under any key under the key References is listed here.

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) (Briodie2009) with the key 'References/Cancer'. 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:

You don't really move the reference. In fact you just create a link between the reference and the key. You can see that as a shortcut under windows or a symbolic link under linux.
You can drag from any key but you can only drop to the key 'References' and its children simply because it does not make sense to drag on the other keys since their content is defined by Bibus.
By default, drag & drop is equivalent to Cut/Paste, but in some cases (when the reference cannot be deleted from the source) it is Copy/Paste. In fact when the source is References and its children it is a Cut/Paste, and otherwise Copy/Paste. As usual, you can force Copy/Paste by holding down the Ctrl key when dragging.
Because we are just creating links it is very economic in term of disk usage. So, don't hesitate to associate a reference with several keys.
Since it is a link, if you modify the reference under any of the keys, you will also modify the reference in the other places (in 'All' and in the other keys) not only for yourself but also for the other users of the database.

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.

Finally the last popup menu choice is 'openURL' (or Middle click with the mouse under linux). 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.

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

file:///home/toto/pdf/Marx.pdf

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

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:

In the menu File, choosing Import/Refer (Import/RIS or Import/Medline) will open a File chooser. Just select the file containing your references, click OK, select the encoding in the next dialog (the selected default should be OK in most cases), and the references will be imported in Bibus.
In the menu File, choosing 'Import/Text Window' will open a text window in which you can paste your reference. Select the correct format and click 'Import'.

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.

Searching

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:

Normal: The mode seen in the figure above
Expert: In this mode, you can enter any search string. You must enter the where clause of the SQL query. Normally, you don't need to use this mode. An easy way to use it is, first to use the Normal mode, then click on expert: you will get the SQL translation of your actual query. Just modify it.

On top right you have the choice between:

Current key. The search will be restricted to the currently selected key. If the selected key does not allow search (Online, Import, Queries), this choice won't have any effect. As the dialog is non modal, you can change the selected key while the dialog is open. If 'Current key' is selected, the search will be done on the key selected when you hit the Search button.
All references. The search will be done on the whole database.

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

LIKE is a substring search. LIKE antibod will match antibodies, antibody, etc.. (For MySQL experts: Bibus automatically adds % before and after the string).
= is exact match. This means that the whole field must be equal to your query.

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.

The 'Normal' mode is simple to use.
In the 'Expert' mode, the text is sent directly to PubMed. It is up to you to correctly format it. See the PubMed site if you need to use this mode. Again, as for search, you can start with the 'Normal' mode, click on 'Expert' and then just modify the text to suit your needs. This is a kind of assisted 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. You can change this default of 20 records in the PubMed search dialog, bibus will remember your choice.

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:

Select some text in a fields and choose "Capture selection". The current selection will then appear at the bottom of the menu.
Select "Edit shortcuts ...". In the window that appear you can edit any shortcut, sort them and capture them from the database. This last option os explained below.

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:

Create in the preference/Shortcuts a category called 'Journal' (or anything else)
Click the "Edit ..." button
Click the "Capture ..." button
Select "Journal" in the menuChoice
Don't check "using separator"
Click OK
All the journals available in the database will now appear in the Shortcut window
Close the Preference editor by clicking OK

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:

Journals. This is a list of Journal names and abbreviations. You must use the first column "PubMed Journal name" to enter the journal in your references. You will be then able to automatically convert by chosing the correct option in your style definition, either to the "ISO abbreviation" or the "Full journal name" when you insert your citation in OOo/Word. See the next chapter to see how to define/modify a style.
Shortcuts. You can define here categories of shortcuts. These shortcuts will appear has menu item in the reference editor. You can define the list of shortcuts associated with any of the categories by double-clicking a category of the "Edit ..." button. See the reference editor help to know how to use them.
Paths. This setting contains for the moment a single path. You can set this path if you want to put all your cited paper in a single location (usually as Acrobat pdf files). By default, when you click in the "URL/File" button in the reference editor, the file dialog will open this directory. In addition, the file location is saved as file:///$FILE/toto.pdf instead of the absolute path. You can thus move the directory containing you pdf files to a new location and have all your references still pointing to the correct location by changing this setting.

There are extra preferences that you can access by clicking "Advanced Preferences" at the bottom-left:

Display options. This first tab will change the way the Main window is displayed. You can change the fields displayed in the list, their order and the sort order of the references. You can also at the bottom change the colors of the displayed reference (panel at the bottom right of the Main view) and to choose if the column width must be fixed or automatically adjusted.
Printing options. You can choose which fields will be printed for each reference type and the color and style of the fields.
Search options. It is where you define what 'Main fields' means in the search and query dialogs.
Duplicates options. If you set this option, when you copy a reference in Bibus using copy/paste or drag&drop (after an import or a Search in PubMed), Bibus will look in the current database for an identical record. You set here what an identical record is, that is which fields must be identical and if the comparison is case sensitive or not. If Bibus find an identical record, Bibus will either not copy the new reference in the database ("keep the old reference") or replace the old record with the new one ("keep the new reference"). The first option is presumably the better and it is the default, but the second option may be used to update references in the database with new updated or more complete records.
Reference Editor. You can define in this dialog for each reference type the Main and Supplementary fields. This affect 2 aspects of Bibus:

It will change the fields present in the tabs of the reference editor when you double-click a reference
It will change the fields displayed at the bottom-right of the Main window (main fields of the current reference).

Database options.

On top-left you can choose the type of database engine used, MySQL or SQLite.
Database used at startup. The default is to use the last database used (the one used when you exited Bibus for the last time). However you can also select 'default' and define the database. This is useful if you want to always connect to the same database, but from time to time want connect to another one without changing your default settings.
Finally, If you have chosen 'MySQL' you can decide to store your password. This way you won't have to enter your MySQL password when you start Bibus. This is not secure at all however since your password is written in the .bibus configuration file (or in a registry key). If you know a good way to store passwords securely, please let me know.

Word Processor. You can change your choice between Word and OOo.