While it is possible for each user to keep a personal note along with each dataset in a database, this mechanism is not very flexible. Extended notes go far beyond these simple notes:
You can attach several notes to a single reference. Of course several users can attach notes to the same references.
You can attach each note to several references. This way you can create a note about a topic and link all relevant references to it.
You're not even restricted to references: you can attach notes to author/editor names, to journal names, and to keywords as well.
The extended notes are accessible with a similar query language like the one you use to retrieve references.
Just like the risx reference data, extended notes use a particular XML format. It is best explained with a short example:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE xnoteset PUBLIC "-//Markus Hoenicka//DTD Xnote V1.1//EN" "http://refdb.sourceforge.net/dtd/xnote-1.1/xnote.dtd" [
<!ENTITY lt "&#60;">
<!ENTITY gt ">">
<!ENTITY amp "&#38;">
]>
<xnoteset>
<xnote key="notekey">
<title>mynote</title>
<content type="application/xhtml+xml" xml:lang="en-us"><para id='2' style='bold'>the note proper</para></content>
<keyword>biochemistry</keyword>
<keyword>enzymes</keyword>
<link type="reference" target="Phadke1994"/>
<link type="author" target="Walsh,N."/>
<link type="journalabbrev" target="Biochem.Pharmacol."/>
</xnote>
</xnoteset>
|
We can easily recognize the following features:
Just like with any other XML file, the processing instructions (the very first line in the file) may carry an encoding attribute. The value can be one of utf-8 (the default if none is specified), utf-16, ascii, and iso-8859-1.
The xnoteset is a wrapper for one or more extended notes, each of which consists of one xnote element.
Each xnote requires a key attribute. This is a mnemonic handle, like a citation key of a reference. If you export extended notes, you'll also see a date attribute as well as an id attribute which is managed by refdb. You should just leave it alone.
The note itself is wrapped into a content element. This can hold either plain text, or markup as shown in the example above. The optional type attribute can be used to tell a processing application about the nature of the contents. Use the optional xml:lang attribute to specify the language of the contents.
Just like references, extended notes may contain keyword elements to make notes searchable.
The link elements connect a note to an unlimited number of references, keywords, authors/editors, or journals. If the link target does not exist in the database, the extended note is still added, but you'll get a warning.
You'll notice that managing extended notes is very similar to managing references. There are analogous commands to add and update extended notes. However, there is also one command specific to extended notes that helps you maintain the links to other database objects. Let's first go ahead and add a file containing extended notes:
refdbc: addnote /usr/local/share/refdb/examples/xnoteset.xml try to add set as note 1 Note key: markus2003 Adding input set 1 successful try to add set as note 2 Note key: secondnote Adding input set 2 successful 2 note(s) added, 0 skipped, 0 failed |
If you want to edit an existing note, you've got two options, depending on what you want to change. If you want to change the contents proper, or maybe add or change keywords, use the following commands:
Note: In this example we'll assume that you already know the ID of the note that you want to change. You'll learn later how to find a note by all sorts of criteria like title, keywords and the like. This section also has additional information on the getnote command used here.
refdbc: getnote -t xnote :NID:=1 -o editme.xml 543 byte written to /usr/home/markus/refdb/editme.xml 1 note(s) retrieved |
This command will retrieve the note with the ID 1 in the xnote XML format and write the data to the file editme.xml. Now you can edit this file to your liking, and then send it back to the database like this:
refdbc: updatenote editme.xml try to replace note 1 Note key: firstnote Updating input set 1 successful 1 note(s) updated, 0 added, 0 skipped, 0 failed |
If you want to add or remove links within an existing extended note, you may also find the following command helpful:
refdbc: addlink :NID:=1 :CK:=Miller1999 :NID: 1 -> :CK: Miller1999 1 link(s) added, 0 skipped, 0 failed |
The first argument to this command must be either the ID of an extended note (":NID:") or the key (":NCK:"). The following arguments are interpreted as a list of objects that the note should be linked to. In this case, the citation key of a reference is specified. If you use the -r option with this command, the specified links will be removed.