Writing extended notes

Both the RIS and the risx formats allow to keep user-supplied notes of unlimited length with each dataset. This is a great way to keep additional explanatory information along with the hard bibliographic data, but this approach is still somewhat limited.

Extended notes are kept separately from the reference data, but there is a mechanism to link each note to an unlimited number of references, author names, keywords, or periodical names. Possible applications of this feature include:

Searching for notes is similar to searching for references. Notes may have keywords, keys, and a title attached to them to easily find them. In addition, you can search for notes that link to a particular reference, author, keyword, or periodical. The inverse works as well: you can search for references that are linked to particular notes.

Extended notes are XML documents according to the xnote DTD. The structure of these documents is simple enough to do without a separate documentation. As usual, start the document with the processing instructions, followed by the document type declaration. Make sure to include the character encoding if it is different from the default (UTF-8). The other encodings supported by RefDB are UTF-16, ISO-8859-1, and US-ASCII. The first line might then read:

<?xml version="1.0" encoding="utf-8"?>

If you want to write several extended notes in a file, start with an xnoteset element. Each individual extended note is kept in an xnote element. This element carries up to four optional attributes:


An unique identifier supplied by the database engine. This attribute is ignored if you add a new note, but it is respected if you update an existing note.


This is a unique short title or tag which identifies a note unambiguously but is more convenient to remember than the id. If you do not supply a citekey, refdbd will create one based on the username and the date.


This is the name of the user that owns the note. If you do not supply a name, refdbd will use the name of the current user, which is most likely what you need anyway.


This is a timestamp (YYYY-MM-DD). refdbd will insert the current date if you do not supply this attribute.

An extended note consists of an optional title, the contents proper encoded in a content element, zero or more keyword elements, and zero or more link elements. The title is a short description of the note. The keywords serve the same purpose as in references.

The content element contains the note proper. The contents of the content element is stored by refdbd as is. It may be plain text or markup. The element uses the following optional attributes:


This description of the content type may be used by processing applications to render the contents properly. Store e.g. the MIME type or the name of a DTD/Schema in this attribute.


This attribute specifies the language of the contents.

The link element is used to link the note to one or more references, keywords, author names, or periodicals. The empty element uses two attributes:


The type of the link target. This may be one of reference, author, keyword, journalfull, journalabbrev, journalcustabbrev1, journalcustabbrev2.


This attribute specifies the database object that the note should be linked to. In the case of a reference, use the ID or citation key. In all other cases, use the name of the author, keyword, or periodical, respectively.

An example set of extended notes is installed into /usr/local/share/refdb/examples.