# Notes management

Managing notes is very similar to managing references. The commands have analogous names and functionality. If you've familiarized yourself with managing references, the notes part should not be too hard either.

## Add extended notes

Extended notes must be supplied as datasets according to the xnote DTD. Add them to the database using the `addnote` command. Each file supplied to this command may either contain a single xnote element or several of these wrapped into a xnoteset element.

The id attribute, if any, will be ignored when you add extended notes. The database engine will assign each note a new, unique identifier. The citekey attribute will be honored unless there is a clash with an existing note. In this case refdbd will refuse to add the note.

If you want to overwrite or update an existing note, use the `updatenote` command instead.

### Example

Assume the file `foo.xml` contains a couple of extended notes. The following command will add them to the database "bar" (use the full path to `foo.xml` if necessary):

    	refdbc:
    	addnote -d bar foo.xml

## Find and view extended notes

Just as you'd use the `getref` command to locate references, you can use the `getnote` command to view notes. The query language is explained in a separate section.

The notes can be retrieved for screen display, as HTML or XHTML documents, or as xnote documents.

Accessibility of notes is affected by the default note sharing setting of refdbd and by the properties of the individual notes. See below for further details.

## Delete extended notes

Use the `deletenote` command to remove extended notes from the database. The argument to this command is a space-separated list of ID values.

### Example

The following command removes the notes with the IDs 4 and 132 from the database "bar":

    	refdbc:
    	deletenote -d bar 4 132

## Edit extended notes

Use the same strategy as you would for references:

- First retrieve the notes you want to edit with the `getnote` command and write the output to a file:

      	  refdbc:
      	  getnote -d bar -o foo.xml -t xnote :NID:=4 OR :NCK:=biochemistry1999

- Now use your favourite XML editor to edit the notes. Keep the citekey and id elements alone, as at least one of them is required to match the dataset with the existing copy in the database.

- Finally use the `updatenote` command to update the reference in the database:

      	  refdbc:
      	  updatenote -d bar foo.xml

## Link existing notes to other objects in the database

If you want to link an existing extended notes to other objects in your database without modifying the contents of the note, the `addlink` command comes in handy. The command requires at least two arguments. The first argument specifies an existing note by its ID or citation key. The second argument specifies an object in the database, either a reference by ID or citation key, or an author name, a keyword, or a periodical by their names. Removing links works just the same except that you need to provide the `-r` switch.

### Example

The following command links the existing note with the ID 5 to two references which are specified by their citation keys:

    	refdbc:
    	addlink -d bar :NID:=5 :CK:=Miller1999 :CK:=Doe2000

## To share or not to share extended notes

RefDB was written with facilitating the cooperation of users in mind. Therefore extended notes are visible to all users of the system by default. However, situations may arise where you don't want to share any notes or where you want to protect only individual notes from your colleague's prying eyes. RefDB supports all these variants. Accessibility of notes is controlled by two filters: the default server setting and the settings in the individual notes.

### The refdbd default

The refdbd server can be configured to either treat all extended notes as public or as private by default. Use the `-S` command line option or the `share_default` config file option to set the default mode. See the chapter about refdbd administration for further details. As the names imply, public will make all notes available to every user by default. Similarly, private will restrict access to the user who added the note by default. Use the server setting to define a default policy for your installation.

A warning for all admins: switching your server from "private" to "public" without prior announcement will alienate your users. Don't even think about it.

### The share attribute of the extended notes

The xnote.dtd defines an optional share attribute which offers the same choice of values as the server setting above. If the attribute is set, the extended note will be public or private regardless of the server setting. The server setting only kicks in if a note does not set the share attribute. Each user can decide for each note whether or not she wants to share it with the world. The following table summarizes the settings.

Sharing extended notes

| share attribute "public" | share attribute "private" | share attribute not set
--- | --- | --- | ---
share_default "public" | public | private | public
share_default "private" | public | private | private

### Data privacy

The above settings control only the access to the extended notes through the RefDB interface. You should be aware that anyone who can access the database directly with an SQL client will be able to read and change the notes of every user, regardless of the settings mentioned above. The simplest way to secure the data is to run refdbd on a server that no user has shell access to. If the database engine access control is set in a way that users can only connect from the box that runs RefDB, they won't be able to connect from a SQL client running on their workstations.