[Refdb-users] Comments on first installation of RefDB

[Nicolas B. <br...@in...>]

Hi all,

I am new on RefDB.

I downloaded version 0.8.5, found the refdbib segmentation fault bug and
downloaded latest version 0.8.6 which suppresses the bug. RefDb is now
working on my linux box and I want to make some comments on the
documentation and on the product itself which could be easily improved by a
better documentation (the implementation of Postgresql is a secondary
priority).

 - At first, there is no sample files in order to test the local
installation. This is a pity.
For example, my BibTeX file could not be input from the refdb WEB interface
for an unknown reason (with a javascript warning saying that it was not a
BibTeX file!); and I had liked to see how is a standard BibTeX/refdb input
(is it with { or ( etc.?). Also there is no documentation on what refdb does
with the "\citekey" field.
I name citekey the text as in: @article(citekey,

The citekey appears as the ID field of the RIS file after a bib2ris
conversion but it disappears in the database and is replaced by a numbered
ID
 @article(db-1,

It is a severe limitation and truncation of your bibtex file which has to be
documented.

 - The first description and advertisement of RefDB on sourceforge.net
compares RefDB with Reference Manager and EndNote; it is far from real. The
main two advantages of these commercial products (and Procite too) consist
in my view in: (1-import) on the "rapid" selection and "automatic" inclusion
in an temporary database of references obtained from a search on Medline (or
whatever bibliographic server), (2-export) on the "cite while you type"
facility which you can use from Word or Word perfect by querying your
reference manager.

As far as I understand refdb today in order to simulate the first feature
(1-import) you have to search your Medline with your own browser, copy and
paste the different parts of the text of interest into your refdb browser
(same browser but another and appropriate window). You can do it also from
the command line but it doesn't seem to be more simple.

Feature (2-export) can only be done with LaTeX/BibTeX (I am happy because
LaTeX was what I wanted but most of the people here would like to use the
refdb database with Word!). In most of these commercial products you can
enter some "citekeys" into your text and if you don't remember the exact ID
of your reference you can enter an author and/or a keyword and/or a date
(which have to be enclosed by braces or something like that) and then by
clicking from Word on the "Scan document" button you can select from your
reference database one or more exact references to be inserted. Also refdb
is not a Z39.50 server and can't be used with such, commercial or not,
reference seekers. It has to be documented.

 o Comments and questions on the installation documentation

 - Why during the make install, the style files (bibtex-full.xml etc.) are
copied to /usr/local/share/refdb/styles ? It seems that during a:
  refdbib -u username -d foo -S bibtex-full -t bibtex foo.aux
command, refdbib does not look at that style file directory. Ok, I
understand that the styles have to be loaded into the refdb mysql database
but why, again, the refdba command:
  addstyle bibtex-full.xml
does not look at that special directory? The only way I found to add styles
was to enter the complete path
  addstyle /usr/local/share/refdb/styles/bibtex-full.xml
Is there another way? (I spent hours on this!)
What means the line
 stylespecdir $REFDBLIB/stylespec
in refdbibrc?

It is not clear in your README or INSTALL file that after "make install" you
should have a refdbd running...
...and refdba works without a refdbd running...
I mean that there is no error message if you create a database with refdba
without a refdbd running!
Many of the refdb client don't have error messages (like refdbib if the
foo.aux does not exist).

What is the default style of refdbib?
Why isn't the default style not included into the mysql database during the
make install, or during the input of a mysql install dump.

In fact you could add also the inclusion of a sample database (foo) whith a
dump.

Instead of long documentation sections on how to implement refdbd daemon
which every one knows (/etc/rc.d/init.d/refdbd start) you could simply tell
people to launch refdbd as:
  refdbd -s -V -e 0 -l 7
in order to test the connection.

For example the creation of 'root' and other user is not clear. Even if I
use mysql for other product like the 'sympa' mailing list server,
phpmyAdmin, and other private services I spent a lot of time until it works.

For example, refdb seems to need "localhost.localdomain" as the local host.
It is not true with other standard mysql services where simply "localhost"
is the host. I have had to create a root user for localhost.localdomain,
because the standard one did not work: only an interactive (-e 0) refdbd
launch can help you to see the:
  Access denied root@localhost.localdomain
messages.

Also, there is no documentation on the port that you use and, if you are
protected by a firewall, which one you can use. Is port 9734 planned to be
included in /etc/services like 3306 is for mysql?

It seems to me that if you use a WebInterface of refdb the access are done
from localhost so you don't need to open the 9734 port for input with your
firewall.

Your documentation is mainly written as if clients were all on Unix boxes in
a World without firewalls. I think that reality changed. It is not necessary
to create users with -H % privileges if your mysql databases are used for
other purposes like confidential mailing lists with protected passwords.

There is no section on "Common Errors" like "What to do if
you get Access denied" or other things like that. The use of phpMyAdmin
could be mentioned and emphasized as it really simplifies the management of
databases.

Also I don't understand the personal reference list. What is the hierarchy
between users? What are the privileges to setup? If someone uploads a
bibliography from the Web interface, would it be a common database or a
personal database? Also a guided tour could be nice.

Your documentation is not numbered and its structure is not clear.
For example in your Table of Contents you have Parts and Chapters but
chapters are not renumbered from one after each part. Under each chapter,
sections are not numbered at all. It is very confusing with subsections. For
example why "Finishing the refdb installation" which is a major section is
before the "Seting up the refdb web services". Again "Add or delete
bibliography styles" should be partly dupplicated in a sub-section of
Finishing the refdb installation if not setup through a mysql command file
or dump.

There is actually no documentation on the Web interface which is what I am
interested mostly in. The "login" button is confusing: whatever username and
password you enter, the message is that "Your are logged in". What is this
button doing? The java script could be included in the HTML to be more
clear. I understand that you need a username, a password and a database to
submit a query. So the Login button is not mandatory. In your simple query a
book title is not searched, only a title of an article is searched.

I know that criticism is easy but when I see that the todo list is mostly
concerned by new facilities I am afraid that many potential users,
sourceforge downloaders, did not try the product only because the
documentation is not clear and not because of the limitations of refdb.

Also it is not difficult to describe briefly in the introduction what are
the other softwares or concepts that you use (BibTeX, SGML, XML, TEI,
DocBook etc.). Even LaTeX is not described at all.

"TeX and LaTeX (one of the first markup language) are mostly but heavily
used by people who needs to type mathematics. BiBTeX was included in the
LaTeX package to manage scientific bibliography databases. Since libraries
have been computerized, the BibTeX format was too simple to locate physical
books in a real library and many formats have been used in the world, like
the RIS format used in RefDB. Also Internet offered the possibility to
exchange documents and bibliographies, markup languages like SGML HTML and
now XML are more and more used and sometimes output by bibliographic web
servers like Medline but also RefDB.
The Z39.50 protocol is actually the most important protocol used to query a
bibliographic server even if its possibilities of searching documents are
poor (ISI said that recently). RefDB is actually not a Z39.50 server like
Zebra/Zap (opensource) is but it can output XML as well as formatted
bibliographies. Unlike Reference Manager, Endnote, Procite and other
commercial products it has no automatic procedure to query the Medline
server and to select and store results in a refdb database but it can import
results of internet queries through a Web Interface as well as through
unix-like typed commands. For example you can export from Reference Manager
or Endnote, your databases as Ris-Export-Text files and then import them
into a refdb database with a simple refdbc client. But the main adavantage
of RefDB is probably for LaTeX users who want to share a local bibliographic
database. In fact a LaTeX user, who can use LaTeX on an Unix box as on a PC
or Mac, can search the refdb database (named "db" for example) with a
browser (http://foo.net/refdbquery.html) , locate the appropriate reference
ID ("243" for example), insert the \cite{db-243} command in her LaTeX text
to get a correct bibliography with the \bibliography{db} command. The
"refdbib" client is only the additional step (before bibtex) to extract the
references cited in the ".aux" file from the "db" refdb database, create a
local db.bib bibtex file which can be used by BibTeX to create a db.bbl
which, finally, is used by latex.
Refdbib clients (on Pc or whatever box) should be able to query a refdb
server through the 9734 tcp port. As far as I understand refdb, the refdb
server (not refdbib itself) calls the mysql server on port 3306 (it is not
necessary to open 3306 outside a firewall). RefDB is only at a very early
stage of functionning. We are waiting for the implementation of a Z39.50
protocol in order to allow easy search/download from commercial products
like Reference Manager, EndNote, ProCite and others."

I know that English is not my native language but I had like to find some
explanations like the above to know more precisely some of the features of
refdb.

I hope that my remarks and comments were helpful and not offensive because
refdb is probably one of the most "opensource" innovative product for
scientists I have found.

Nicolas Brouard
Institut national d'études démographiques
Mortality, Health and Epidemiology Research Unit
Paris
br...@in...