This step is necessary for all platforms. You have to create some databases for refdb to start with and you should make the refdb SGML/XML support files known to your system.
The default installation of all supported database engines should be just fine for running refdb. However, in some cases a little extra work is needed.
The MySQL engine earlier than version 4.1 supports only one character encoding per server instance. The default encoding is ISO-8859-1, aka Latin-1. If you prefer a different encoding, you have to configure the server at startup. Either use the mysqld command-line option --default-character-set=charset, or add a "default-character-set=charset" entry to a suitable MySQL configuration file. A list of available encodings is usually installed as /usr/local/share/mysql/charsets/Index. In MySQL versions 4.1 and later each database (in fact, each table) may have one of various character encodings.
For security reasons many default installation allow only local connections. If refdbd has to connect to the database server from a different box, make sure to remove the --skip_networking option from the MySQL start script or from the appropriate MySQL configuration file.
Most default installations of this database server allow only local Unix sockets connections due to security concerns. However, the refdbd application server will always talk to the database server via a TCP/IP connection. Please make sure to start postmaster with the -i command line option to switch on TCP/IP support.
The embedded database engine SQLite supports two character encodings as a compile-time option: ISO-8859-1 (Latin-1) and UTF-8. The former is the default if you don't use any configure options and if you use prebuilt binaries. If you need Unicode support, you'll have to recompile SQLite using the proper configure switch.
The refdb database contains common information that is shared by all reference databases.
Note: If mysqld (the MySQL database server) is installed on a remote box or if the security settings require it, you may have to use the
-h hostnameand/or the-u username/-p passwordoptions to run the mysql client as shown below (most fresh MySQL installations use "root" with no password as the default database administrator). mysqld needs to be up and running and you need the appropriate permissions, of course. See the MySQL documentation for further details.
In a command line window, run the following command to create the database "refdb":
~$ mysql -u root -e "CREATE DATABASE refdb" |
Then create the tables and fill in the data. For MySQL older than 4.1, run:
~$ mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump |
For MySQL 4.1 and later, run this instead:
~$ mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump41 |
Adapt the path to the script accordingly if you configured refdb to put the data directory somewhere else.
The above command will create the tables using the MyISAM engine. This is the fastest of the supported engines, but it does not support transactions. If you prefer to use the InnoDB engine instead, use this command:
~$ sed 's/MyISAM/InnoDB/' < /usr/local/share/refdb/sql/refdb.dump41|mysql -u root refdb/usr/local/share/refdb/sql/refdb.dump |
See the MySQL documentation for further information about the table engines available with MySQL.
Note: If postmaster (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the
-h hostnameand/or the-U usernameoptions to run the psql client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator". On Debian you need to be logged in as user "postgres": first su root, then su postgres). postmaster needs to be up and running and you need the appropriate permissions, of course. See the PostgreSQL documentation for further details.
In a command line window, run the command:
~$ createdb -U pgsql -E UNICODE refdb |
The data that you will import in the following steps are UTF-8 data. If you wish to use a different encoding, convert the dump file and adapt the above command accordingly.
Then run this command:
~$ psql -U pgsql refdb < /usr/local/share/refdb/sql/refdb.dump.pgsql |
Adapt the path to the script accordingly if you configured refdb to put the data directory somewhere else. This SQL script will generate the necessary table definitions and fill in a few values. PostgreSQL will notice you that it is going to truncate a few identifier names. It is safe to ignore these messages.
The default database directory is /usr/local/share/refdb/db. refdb will look here unless you selected a different data directory when configuring the application. If you want to keep your databases somewhere else, use the dbpath variable in refdbdrc and modify the following instructions accordingly.
~$ cd /usr/local/share/refdb/db |
Run the following command to create the database and load the data:
~$ sqlite refdb < /usr/local/share/refdb/sql/refdb.dump.sqlite |
Now is the time to create the global configuration files described in the configuration file section. Create these files in /usr/local/etc/refdb (or whatever you chose during configuration). It is recommended to copy and modify the commented example configuration files in the same directory. These files are installed with the suffix ".example" to avoid overwriting existing configuration files. All required paths are automatically configured during the installation, so these files are a good starting point for your local modifications.
The refdb package comes with a few additional scripts and stylesheets for the creation of bibliographies. These files are installed in the package data directory (usually /usr/local/share/refdb) and its subdirectories, but you should spend a little time to integrate them into your SGML system.
To this end, add the catalog file /usr/local/share/refdb/refdb.cat to your SGML_CATALOG_FILES environment variable. This is a master catalog with CATALOG directives for all catalog files supplied by refdb.
The refdb shell scripts (db2ris, refdbjade, runbib, refdbxml, and the Perl scripts tex2mail and marc2ris.pl) were installed in /usr/local/bin unless you chose a different install root during configure. As refdb attempts to insert the correct settings during the build process, it should not be necessary to manually customize these scripts. If you still want to fiddle with the settings, the variables are clearly marked within a "user-customizable section" at the top of each script.
Note: If you want to use a Java XSL processor with the refdbxml script, you'll have to check the value of
CLASSPATHin the script. The value must match the actual location of your .jar files and the current versions you've installed.