So far you've heard only the very basic stuff. Some more advanced issues are discussed in this chapter. You'll learn how to manage your personal reference list, how to use the pdfroot configuration variable, and how to customize the HTML output of the getref command.
If you share a common reference database with other users, you should know about the concept of personal reference lists. If you don't share your reference database with someone else, you can safely skip this section.
Each refdb database keeps a personal reference list for each user who adds references to this database. The reason you didn't notice so far is that it all happens automatically. If you add a reference with the citation key "miller1999asteroids" to the database, this reference will be tagged with your database username. That is, the database knows that the user "markus" added this particular dataset. However, by default refdb ignores this information when you run queries. This is by design, as it allows you to benefit from the references (and offprints) that others added. But if you want to, refdb allows you to restrict all database queries to only those references that you personally added. There are a few cases where this might be useful:
You're about to move on in your nomadic life as a scientist. You want to take your collection of offprints with you, along with your part of the database. The personal reference list allows you to retrieve selectively those references in the common database that you added.
If your queries return too many hits, you can use the personal reference list to cut down the number of results to those that you added.
All you need to do is to use the -P switch with the getref. Without that option, refdb will search the entire database. With the option, refdb will search only those entries that you added.
Of course refdb offers commands to manage your personal reference list. You can manually include existing references that someone else added to the database into your personal reference list. If you feel a reference is no longer of interest for you, you can remove it from the list.
Note: Removing a reference from your personal reference list does not delete the reference data from the database. The reference will still show up if you search the entire database. In general this is preferable to deleting a reference because someone else might be interested in that reference. It is so much preferable that this little tutorial doesn't even tell you how to delete references.
The command to manage your personal reference list is called pickref. If you use the -r command line option, the specified references will be removed from your personal reference list. If you do not use this switch, the specified references will be added to your personal reference list. Let us assume someone else added a paper written by Dr. Miller in 1999 to the database that both of you share. Let's see what getref tells us about this entry:
refdbc: getref :AU:~Miller AND :PY:=1999
ID:5 (1999)
Key: Miller1999
Miller,J.D.
Recent advances in sleeping disorder research
Int.J.Sleep Res. 14(2):121-7
|
If you run the same command with the -P option, this reference would not show up in your result list. To add this reference to your personal interest list, run the command:
refdbc: pickref 5
ID 5 successfully picked
1 datasets added to personal interest list, 0 ignored
|
If you now re-run the previous getref command, you should see the following:
refdbc: getref :AU:~Miller AND :PY:=1999
ID*:5 (1999)
Key: Miller1999
Miller,J.D.
Recent advances in sleeping disorder research
Int.J.Sleep Res. 14(2):121-7
|
The little asterisk (*) now tells you that this reference is part of your personal reference list.
Like most other bibliographic tools, refdb can manage collections of electronic offprints. You can store a path to an electronic file along with the bibliographic information in the AV field. refdb can use this path to construct a hyperlink in both the HTML output and in the web interface, so your offprint is accessible with a single mouseclick.
While this sounds like a piece of cake, you should think twice. If you store a full path to the file, what happens if you access your database from a different computer? If you (or the IT guys of your department) keep the offprints on a web server and have to move the server to a different machine? Will you still be able to access your offprints? Keep in mind that changing the paths of several thousand references does not sound like much fun.
refdb uses a simple feature to take most of the hassle out of this. The URLs used in the HTML pages generated by refdb are made up of two components: A (potentially variable) root path and a (supposedly static) relative path. What you store along with the reference is only the relative path. The root path can be provided to refdbc as a command-line option or by a setting in its configuration file.
Let's look at an example. You keep your PDF and Postscript offprints in ~/references/ and subdirectories thereof, so the full path of one example file might be /home/markus/references/surgery/miller1999cirrhosis.pdf. Of course you could keep all files in one subdirectory, but this example shows that you're not limited to that. The AV field for this reference should then read:
AV - PATH:surgery/miller1999cirrhosis.pdf |
The appropriate setting for the root path for local access is /home/markus/references/, as simple concatenation of these paths would return the full path of the file in question (please note the trailing slash in the root path). The following entry in your ~/.refdbcrc configuration file would set this as your default pdfroot:
pdfroot /home/markus/references/ |
Now you're doing some interesting lab work. You're way too lazy to walk over to your office but you still need that offprint real quick. Just go ahead and mount your drive remotely (you might need root permissions to do that):
~$ mount dogear:/home /mnt |
assuming that your box is named "dogear". Your references directory is now accessible as /mnt/markus/references. All you need to do is to start refdbc with the -R option set to this new pdfroot:
~$ refdbc -R /mnt/markus/references |
For the current session you will be able to access your offprints with a mouseclick in the HTML query output although you use a different computer.
Along the same lines, if your department convinces you to donate all offprints to a central repository which will be made accessible through a web server, all you need to do is to change your ~/.refdbcrc accordingly:
pdfroot http://serverbox.labnet/offprints/markus/ |
assuming that the web server is accessible with the host name "serverbox.labnet" in your local network and that you get your own subdirectory, thus keeping your subdirectory structure intact.
You've learned earlier in this tutorial that you can display refdbc query results in a web browser. The HTML that refdb creates is suitable for use with CSS stylesheets. By default, an example stylesheet (installed as /usr/local/share/refdb/css/refdb.css) is used for this purpose. If you don't like how the HTML output looks, you can hack your personal stylesheet and use that instead.
It is probably the easiest way to get a copy of the default stylesheet and edit that:
~$ cp /usr/local/share/refdb/css/refdb.css ~/ |
Then use your favourite text editor to change the visual appearance of the HTML pages. In order to test your new stylesheet you need to tell refdbc about it with the -G option:.
~$ refdbc -G /home/markus/refdb.css |
Now you can retrieve some references in HTML format and save them to a file:
refdbc: getref -o test.html -t html :ID:<10 |
Now open the file test.html in your web browser and see whether you like it. You can change the stylesheet and redisplay the file until you like the results.
To make your new stylesheet the permanent default, add the following line to your ~/.refdbcrc:
cssurl /home/markus/refdb.css |
If you have access to a web server in your local network, you could leave your stylesheet there and enter its URL as the cssurl value. This way you could enjoy the benefits of your stylesheet from any computer in your local network.