refdb README
============

[Please scroll down for backwards incompatible changes]

Overview
========

refdb is a reference database and bibliography software. It helps
scientists, publishers, and anyone else writing publications to keep
track of journal articles, books, and other printed or electronic
material, to associate notes with their material, and to automatically
generate bibliographies for all kinds of publications. The primary
output formats are RIS, DocBook SGML/XML, TEI XML, and TeX compatible
with bibtex/natbib. Other SGML and XML document types can be added by
creating suitable stylesheets.

refdb runs on Linux, FreeBSD, NetBSD, Darwin/OSX, Solaris,
Windows/Cygwin, and probably a bunch of other Unixish
systems. Precompiled binaries are (sometimes) available for Cygwin,
Linux, and Solaris

refdb uses MySQL or PostgreSQL as external database servers, or SQLite
as an embedded database engine.

Creating DocBook SGML documents with automatically generated
bibliographies requires a DSSSL engine and DSSSL
stylesheets. Jade/OpenJade and Norm Walsh's DocBook stylesheets are a
good choice here.

Creating DocBook or TEI XML documents with automatically generated
bibliographies requires a XSLT engine and DocBook or TEI XSL
stylesheets, respectively. xsltproc is an excellent choice.

refdb is at home at http://refdb.sourceforge.net.
refdb is maintained by Markus Hoenicka <mhoenicka@users.sourceforge.net>


******************************
Backwards incompatible changes
******************************
_______
V 0.9.6

The client/server communication protocol has changed as of
0.9.6-pre2. Old clients cannot talk to new servers and vice versa.

The Perl scripts en2ris.pl, marc2ris.pl, and med2ris.pl were renamed
to en2ris, marc2ris, and med2ris, respectively. The scripts dos2unix
and tex2mail were renamed to refdb_dos2unix and refdb_tex2mail,
respectively.

The default locations of the default SQLite database directory has
changed. It is now {prefix}/var/lib/refdb/db in compliance with the
Filesystem Hierarchy Standard.

The builtin web interface has been removed.

_______
V 0.9.5

The system database uses a different layout compared
to previous versions. If you upgrade, make sure to create a new system
database using the supplied dump files.

Running older and newer versions of RefDB in parallel now works a
little different. By default, the system database is always called
"refdb" but you can change this with the --with-main-db configure
switch.

The TEI stylesheets as supplied by www.tei-c.org now use a different
directory layout than in the past. RefDB now assumes this new layout
which looks like this:

value of --with-tei-xsl|generated by unpacking stylesheets
|______________________|_________|
/usr/local/share/xsl/tei/P4/fo
                           /html
                           /common


The default FO processor used to be PassiveTeX. Due to ongoing
incompatibilities of this tool with recent DocBook stylesheets I've
switched to FOP as the default processor. Please edit refdbxmlrc
accordingly if you want to keep PassiveTeX as your processor of
choice.

The in-text citation format had to be changed in order to avoid
ambiguities. The refdbxp tool was adapted accordingly. Documents using
the short citation style are not affected by this change.

runbib now uses the new -m option to set one or more include variables
for marked sections. The previously used -i option now sets the server
IP or hostname, just as in most other tools.

_______
V 0.9.4

Both the system database (now called refdb instead of refdb1 to allow
parallel installations of new and older versions) and the reference
databases use different layouts compared to older versions. In order
to use your existing reference data with 0.9.4, make sure to follow
the instructions in UPGRADING.

For security reasons refdbd no longer accepts remote connections by
default. If you want to continue accessing refdbd from a remote
box, make sure to start refdbd with the -I switch or use the
"remoteconnect" variable in refdbdrc.

The query language now performs literal string matches by default. Use
the new operator "~" to request a regular expression match.

_______
V 0.9.3

The med2ris.pl script now uses the uppercase "-T" switch to manually
select the input data type. The lowercase "-t" switch is now used to
select the output character encoding.

_______
V 0.9.2

A minor change in the client/server communication protocol was
required to allow displaying the number of retrieved references with
the refdbc:getref command. The server of this version accommodates
both new and old clients. New clients will not be able to talk to
older servers, though.

_______
V 0.9.0

The configuration files moved again. This time they were collected
into a subdirectory 'refdb' below the system configuration directory
specified in the configuration step. E.g. if you specify
--sysconfdir=/usr/local/etc (the default), the configuration files
will end up in /usr/local/etc/refdb. This cleans up the system
configuration directory and makes all global RefDB configuration files
easier to access.

The schema of the common database refdb has changed. To allow old and
new RefDB versions to run in parallel, versions 0.9 and later use
refdb1 as the common database. Create this database after installation
of the refdb components according to the user manual.

The refdbvar database used by refdb versions prior to 0.9 is
obsolete. After upgrading to 0.9 you may safely drop this database.

The schema of the reference databases has changed. The main table
t_refdb now has an additional column for the citation keys. In order
to use your existing reference databases, please follow the
instructions in the file UPGRADING.

The remoteadmin configuration variable for refdbd now uses 't' and 'f'
as argument instead of '1' and '0'.

The cgiurl configuration variable for refdbc was renamed to cssurl
which better reflects its purpose (it was a braino to call it cgiurl
in the first place).

There are a few new configuration variables and command line switches
to allow usage with PostgreSQL. However, all defaults still assume
MySQL so your configuration should keep working.

The DocBook export format has changed considerably. Any applications
or stylesheets that you wrote for the old format need to be adapted.

_______
V 0.8.4

All RefDB applications now look into /usr/local/etc to find their
global configuration files (this can be changed during
configuration). Only if they're not found there, the apps will consult
$REFDBLIB. The latter is done in order not to break existing
installations, but you should move your config files to the proper
location now. This change was made to separate shareable data from
machine-specific configuration data.


_______
V 0.8.2

The DocBook bibliographic output was changed again to allow textual
citations. Due to this change, citations in existing documents need to
be slightly changed to work with new bibliographies. The new
stylesheets will not work with old documents and vice versa.

The SGML versions of the CiteStyle DTD and the CitationList DTD were
dropped. The XML versions are now authoritative.

_______
V 0.8.1

refdbib now generates DSSSL files (.dsl) instead of style
specification files (.spc). These DSSSL files act as driver files for
the RefDB DSSSL stylesheets which in turn are driver files for the
original DocBook DSSSL stylesheets. For this to work, a new catalog
file must be included in your SGML_CATALOG_FILES environment variable.
The refdbjade script was changed and will no longer work with .spc
files.

The DocBook bibliographic output was slightly changed to make it more
suitable for transformations into e.g. TEI. The DSSSL stylesheets were
adapted accordingly. Use only old stylesheets for documents containing
old-style bibliographies, or re-create them with the current version.

_______
V 0.7.2

Now refdbd also uses -T instead of -t for the timeout switch, just
like the clients. -t is still supported by this release but it will be
dropped in upcoming versions.

_______
V 0.7.1

Now all clients including refdbc and refdba support logging and a
batch mode for use in scripts. Due to these modifications some command
line option letters had to be changed. All options are now consistent in
all applications. Use the -h switch of the applications or of the
interactive commands to view the updated option lists.

_______
V 0.7.0

All configuration files have been renamed to <progname>rc. The global
files no longer have a leading dot, e.g. .refdbd-init is now
refdbdrc. The personal configuration files may have a leading dot (the
apps first look for a hidden config file, then for a non-hidden file
if the former is not found).

_______
V 0.6.0

The client-server communication protocol was changed. Old clients
don't work with the new application server and vice versa



