introduction_old

1. Introduction
   1. Main Features
   2. Changes
   3. Installation
      1. Short installation
         1. Note for users of Bibus < 1.0
         2. Windows
            1. With OpenOffice.org > 1.9.x
            2. With OpenOffice.org 1.1.x
         3. GNU/Linux
            1. Debian packages
               1. Using OOo1.1.x
               2. Using OOo2.0
            2. Using python2.2 or narrow python2.3 (UCS-2)
            3. Using wide python2.3 (UCS-4)
      2. Complete installation
         1. GNU/Linux
      3. Required extensions
      4. Optional extensions
   4. Starting Bibus

# Introduction

Bibus is a bibliographic database.
It has been developed with OpenOffice.org (http://www.openoffice.org/) in mind. This means that the database is modeled on OpenOffice.org bibliographic database engine. As such it has the features and most of the limitations of this format. However, one of the most annoying limitation which is the restriction to 80 characters of any field, has been addressed in bibus where the fields are 255 character long (or even unlimited, depending on the database engine used).
However, Bibus is in development and there are many evolutions planed for the OpenOffice.org bibliographic engine. Bibus will try to evolve alongside these changes.
Is Bibus stable enough for using it on a daily basis? As usual, Bibus is distributed WITHOUT ANY WARRANTY and you must use it at your own risk. However, since the heart of Bibus is the database engine (MySQL and SQLite) and since it is not possible to delete a reference in Bibus, I think the risk to get a catastrophic crash is very low. You must however remember to make regular backups of the database. If you use SQLite, you just have to copy the database file. If you use MySQL the easiest way is probably to use mysqldump (mysqldump -p Biblio > biblio.sql).

## Main Features

- Compatible with two database engines: MySQL <http://www.mysql.com/> and SQLite <http://www.sqlite.org/>.

- Hierarchical organization of the references with user defined keys.

- Drag & drop and Copy/Paste to easily organize references.

- Designed for multiuser:

  - You can share the database between an "unlimited" number of users.

  - Each user will have his/her own classification.

  - You can hav read-only and read-write users

- Powerful and easy to use search engine.

- Live queries, i.e searches that will update when the database changes (this is simply a saved SQL query).

- On-line PubMed access.

- Import PubMed (Medline), EndNote/Refer, RIS and BibTeX records.

- Export to PubMed, Refer and RIS.

- Connection to OpenOffice.org. You can insert references in an open OpenOffice.org text document and format the bibliography directly in Bibus.

- Thanks to Python and wxWidget, Bibus should work on most modern platform (GNU/linux with gtk; Windows; MacOS ?; etc...).

- Foreign language support through unicode and gettext. For the moment, Bibus is available in English, French, Portuguese and Danish. Feel free to translate it in your favorite language, this is easy and fast. It took me about 1 hour to translate the bibus.pot file in French.

## Changes

For a complete listing of the changes, see CHANGELOG.

    Note added after 1.1.0 release:
      * contrary to what is said in the Changelog file, bibus is NOT COMPATIBLE with python-sqlite version 2.

    1.1.0
      * Compatible with OOo2.0 and 1.1
      * Compatible with python-sqlite2
      * Compatible with MySQL4.1
      * Fast display of long lists
      * BibTeX import from Nigel Sim <nigel.sim@jcu.edu.au>
      * New translations (partial)
          * Portugese translation by Vitor Figueiro <vfigueiro@gocial.pt>
          * chinese translation by <max.ouyang@gmail.com>
          * spanish translation by Pablo Rodriguez <ousia@gmx.net>
          * German translation by Andreas Morasch <a.mor@web.de>
          * Czech translation by Daniel Rajdl <rajdl@fnplzen.cz>
      * Gestion of duplicates during import
      * Complete rewrite of the OOo connection for portability and speed
    1.0.0
      * Added new styles for field formatting (free combination of bold, italic, underline, caps, smallcaps)
      * New command to go to the current doc in OpenOffice
      * BibliograpicType is now displayed as 'ARTICLE', 'BOOK', etc... instead of 0,1,2,...
      * Double clicking a imported references allows to see all the fields
      * Possibility to import references without saving them first
      * Column width may now be fixed
      * reference list sorting improved (up/down + arrow)
    pre1.0.0
      * portugese translation
      * complete styles
      * work with wxPython2.5
      * work with mysql-python 1.1.x
      * work with PySQLite 1.1.x
      * remember window position and size
      * simplified install (to be improved)
      * many bug fixes
    0.9.0
      * Greatly improved styles
      * First connection wizard to help setting Bibus
      * First rudimentary author-date implementation
    0.8.2
      * maintenance release
    0.8.1
      * Added connection with OpenOffice.org using Pipe (in addition to TCP/IP)
      * tested on Windows98, 2000 and linux

    0.8.0
      * First public release
      * Tested on debian Gnu/linux unstable and Windows2000

## Installation

### Short installation

#### Note for users of Bibus < 1.0

The installation procedure has changed. You can still start Bibus as previously but the new procedure is more flexible. Delete the environment variable that you set for Bibus <1 then run <Bibus>/Setup/setup.py

#### Windows

##### With OpenOffice.org > 1.9.x

- Install OpenOffice.org from www.openoffice.org. The current version is 2.0

  - By default it should install in C:\Program Files\OpenOffice.org 2.0.0\

- Install python2.3.5 from www.python.org. Use 2.3.x version and not a more recent or earlier release since it will not work with OpenOffice.org 2.0

  - By default it should install in C:\Program Files\Python23\

- Install wxPython2.6.x from www.wxpython.org. Pay attention to get a version with unicode support and compiled for python2.3.

- Depending on the database engine that you choose, download:

- SQLite: PySQLite for python2.3 from <http://pysqlite.org/>. Don't use the last version 2 but the previous 1.1.6 release for python2.3.
- MySQL:

- MySQL from www.mysql.com. The best is to use version 4.0 or 4.1.

- MySQL-python for python2.3 from <http://sourceforge.net/projects/mysql-python>. The last version is 1.2.1c3 and is compatible with MySQL4.1. If you use a previous version, including 1.2.0, you must use MySQL up to 4.0. If you are planing to use MySQL4.1 (or 5.0), please read this.

- Connect to your Windows Box as Administrator

- Follow the setup process

- You can of course make a shortcut on your desktop that points to bibusStart.pyw and eventually use one of the icons in <Bibus>/Pixmap.

##### With OpenOffice.org 1.1.x

- Install OpenOffice.org from www.openoffice.org. The current version is 1.1.5.

  - By default it should install in C:\Program Files\OpenOffice.org1.1.5\

- Install python2.2.3 from www.python.org. Use 2.2.x version and not a more recent release since it will not work with OpenOffice.org.

  - By default it should install in C:\Program Files\Python22\

- Install wxPython2.4.x or wxPython2.5.x from www.wxpython.org. Pay attention to get a version with unicode support and compiled for python2.2.

  - wxPython2.5-win32-unicode-2.5.3.1-py22.exe

  - wxPythonWIN32-2.4.2.4u

- Depending on the database engine that you choose, download:

  - PySQLite for python2.2 from <http://pysqlite.org/> version 1.1.6 for python2.2

  - MySQL:
  - MySQL from www.mysql.com. The must use version 4.0 or a previous one since the python-mysql package below is not compatible with a more recent release.
  - MySQL-python for python2.2 from <http://sourceforge.net/projects/mysql-python>. version 0.9.2

- Connect to your WindowsBox as Administrator

- Follow the setup process

- You can of course make a shortcut on your desktop that points to bibusStart.pyw and eventually use one of the icons in <Bibus>/Pixmap.

#### GNU/Linux

##### Debian packages

Starting with Bibus-1.0.0 you can install Bibus using apt-get. You should be able to use either OOo1.1.x or OOo2.0.
OOo2.0 has just been released in Debian unstable. For the moment you must donwload packages from the bibus site but I'm planing to make them available in the futur directly in Debian Unstable repository.

- Open /etc/apt/sources.list in a text editor
- Add the lines:

      deb http://switch.dl.sourceforge.net/sourceforge/bibus-biblio ./
      deb-src http://switch.dl.sourceforge.net/sourceforge/bibus-biblio ./

    (You can replace 'switch.dl.sourceforge.net' with the address of a Sourceforge mirror near you)

-     apt-get update

###### Using OOo1.1.x

-     apt-get install bibus bibus-doc-en openoffice-pyuno

- If you want to use SQLite:

-     apt-get install libsqliteodbc python-pysqlite1.1

- If you want to use MySQL:

-     apt-get install libmyodbc mysql-server mysql-common mysql-client python-mysqldb

- You can now start Bibus:

- by typing 'bibus' in a terminal
- by choosing the bibus menu in Debian/Applications/Database/

- To activate the Connection with OOo, click on "Activate" when you run Bibus for the first time.

- If you want to use the regular OOo interface to insert citations you still have to configure OOo as described in Using the regular OpenOffice.org interface

###### Using OOo2.0

Openoffice.org2.0 is available in Debian unstable, you must thus run unstable to install bibus with OOo2.
There is a conflict between the old openoffice-pyuno package available with bibus1.0 and the new python-uno package available in Debian unstable. This conflict cannot be solved directly by apt or Synaptic.

- If you previously installed openoffice-pyuno:

-     dpkg -r openoffice-pyuno

-     apt-get install bibus bibus-doc-en

- If you want to use SQLite:

-     apt-get install libsqliteodbc python-pysqlite1.1

- If you want to use MySQL:

-     apt-get install libmyodbc mysql-server mysql-common mysql-client python-mysqldb

- You must install OpenOffice2 python the python-uno bridge

-     apt-get install openoffice.org python-uno

- You can now start Bibus:

- by typing 'bibus' in a terminal
- by choosing the bibus menu in Debian/Applications/Database/

- To activate the Connection with OOo, click on "Activate" when you run Bibus for the first time.

- If you want to use the regular OOo interface to insert citations you still have to configure OOo as described in Using the regular OpenOffice.org interface

##### Using python2.2 or narrow python2.3 (UCS-2)

- Install OpenOffice.org from www.openoffice.org. The current version is 1.1.5.

  - By default it should install in /opt/OpenOffice.org1.1.5/

  - Debian / Mandrake: The debian-openoffice package does not contain the python-uno bridge needed by Bibus to communicate with OpenOffice.org. If you want to insert citations from Bibus in openOffice.org you can either:

    - Install another copy of OpenOffice.org

    - Install just the python-uno bridge by downloading it from the Bibus site

  - The Ximian version of OpenOffice.org is installed into /opt/Ximian-OpenOffice

- Install python2.2.x from www.python.org or from you distribution.

  - You can use python2.3 if it is configured with --enable-unicode=ucs2, see the python-uno bridge FAQ and LinuxInstall.html. Under Debian, the stock python2.3 is configured with --enable-unicode=ucs4 and won't work with the python-uno bridge.

  - Most modern distribution contains only python2.3. This is the case, for instance for Mandrake10. In that case you will have to compile python2.2 or to re-compile python2.3 with --enable-unicode=ucs2.

  - Debian users: apt-get python2.2-xmlbase python2.2-dev python2.2

- Install wxPython2.6.x from www.wxpython.org.

  - It is difficult to find a compiled version for python2.2 with gtk2 and unicode support

  - The best solution is to compile it from source.

  - Debian: the wxPython for python2.2 is gtk1 and does not support unicode.

- Depending on the database engine that you choose, download:

  - PySQLite 1.1 or 1.0 from <http://pysqlite.org>

  - MySQL-python from <http://sourceforge.net/projects/mysql-python>

  - Pay attention to install them in your python2.2 installation if you have also python2.3 installed.

  - Debian: apt-get python2.2-sqlite python2.2-mysqldb

- Open a terminal

  - cd to the Bibus directory

  - su -c "/usr/bin/python2.2 Setup/setup.py"

  - Answer the questions

  - start Bibus with:

    - python bibusStart.py

- To activate the Connection with OOo, click on "Activate" when you run Bibus for the first time.

##### Using wide python2.3 (UCS-4)

Since python2.3, python uses UCS4 encoding for unicode strings by default. This is the case with Debian, Mandrake10 and presumably RedHat. Since OpenOffice.org use UCS2 to maintain java compatibility, you must use a UCS4 enabled python-uno bridge to communicate with OpenOffice.org. This was not possible until recently because it was not possible to compile the bridge in this mode. It is now possible with the current cvs version of OpenOffice.org.
I compiled the pyuno bridge on my Debian system using the system python in UCS4 mode and it seems to work very well. If you feel adventurous and want to have a try, do the following.
These instructions are for a Debian system but they may be easily adapted on another linux. Send me your procedure.

- apt-get python libstlport4.6 wxpython2.5.3 python-mysqldb python-sqlite

- download pyuno-cvs-py23-ucs4.tgz from <http://bibus-biblio.sourceforge.net/>

- prompt> tar -zxf pyuno-cvs-py23-ucs4.tgz

- prompt> cd pyuno-cvs-py23-ucs4/openoffice/

- prompt> cp * /usr/lib/openoffice/program

- download Bibus-1.0.0.tgz from <http://bibus-biblio.sourceforge.net/>

- prompt> tar -zxf Bibus-1.0.0.tgz

- prompt> mv Bibus-1.0.0 /opt/

- su -c "python /opt/Bibus-1.0.0/Setup/setup.py"

- Answer the questions

- Start Bibus with

- prompt> python /opt/Bibus-1.0.0/bibusStart.py

- To activate the Connection with OOo, click on "Activate" when you run Bibus for the first time.

Troubleshouting:
pyuno-cvs-py23-ucs4 has been compiled on my Debian system using the system libraries. It depends on 3 system shared libraries that you must install on your system:

- libstdc++.so.5 => /usr/lib/libstdc++.so.5

- libgcc_s.so.1 => /lib/libgcc_s.so.1

- libstlport_gcc.so.4.6 => /usr/lib/libstlport_gcc.so.4.6

The two first libraries are presumably already present in your linux system but may have a different name and you may need to make a symbolic link for instance in your OpenOffice.org/program directory
The first library (libstlport) may require installing a package. In Debian it is libstlport4.6

### Complete installation

Bibus is entirely written in Python and requires several extensions to give it its full power. The installation procedure is described in the files:

#### GNU/Linux

Follows the instructions included in LinuxInstall.html
WARNING: the following docs have not been upgraded for Bibus-1.0.0. Since the installation procedure has evolved, use them with caution then use the Short installation procedure.

- README.txt

- Gnu/linux: installation.txt (or alternatively installation_alt.txt)

- Windows: installationWin.txt

- WindowsXP installation notes.

- If you want to use MySQL, read mysql_config.txt

### Required extensions

- wxPython >= 2.4 (Earlier versions may work, please let me know). Bibus version pre-1.0.0 is compatible with wxPython2.5. With Windows98 you must use wxPython2.5 with unicode support. Notice however than wxPython2.5 is a developement version and some interfaces may change without notice. If you are looking for stability, use wxPython2.4.

  - Under GNU/linux it is best to use a version build for gtk2 with unicode support.

  - Unicode support is also available for Windows NT/2000/XP. It is also possible to activate it under 95/98/Me. Please have a look at <http://www.wxpython.org/download.php>

  - Under MacOSX, there are binaries available on the wxPython site. I don't know if they include Unicode support. It seems to require a patched Python2.3 install. I have no idea if it can be used with Python2.2 which is included with OpenOffice.org (see below).

- A database engine. Either MySQL or SQLite. The latter seems to be only available on GNU/linux and Windows. Could a Mac user check this?

- A python extension in order to connect to the chosen database.

  - MySQL-python <http://sourceforge.net/projects/mysql-python>

    - For the moment, MySQL-python is not compatible with MySQL versions >= 4.1

  - PySQLite <http://pysqlite.org>

### Optional extensions

- ODBC. You need this if you want to be able to directly connect to the Bibus bibliographic database using the classical OpenOffice.org interface.

  - For MySQL : http://dev.mysql.com/doc/mysql/en/ODBC.html

  - For SQLite : http://www.ch-werner.de/sqliteodbc/

- Python-uno bridge. It is included with OpenOffice.org and you should find it in the $OO/program directory, where $OO is the installation directory of OpenOffice.org office suite on your system. Look for a file like $OO/program/python. This is needed if you want to have access to the OpenOffice.org menu in Bibus that allows you to insert citations and format them directly in the open OpenOffice.org writer document. This is a highly recommended extension if you want to use Bibus to insert citations in OpenOffice.org.

  - If it is not included in your OpenOffice.org installation (Debian, Mandrake10, ??), you can download a copy from the Bibus site.

  ## Starting Bibus

  If you want to use a MySQL database, you need to setup the database BEFORE starting Bibus the first time. It is very simple and is described in mysql_config.txt.
  If you want to use a SQLite database and if everything is installed on your machine, just start Bibus and follow the instructions on screen. If you need more than one SQLite database you can:

- Re-run the wizard in the Help menu.

- Copy the database $BIBUS/Docs/db_models/biblio.sqlite (sqlite version 2) or biblio.sqlite3 (sqlite version 3) to your prefered location and use it (you can of course rename it).