[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter22.sgml,NONE,1.1

[Markus H. <mho...@us...>]

Update of /cvsroot/refdb/refdb/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv26387

Added Files:
	refdb-manual-chapter22.sgml 
Log Message:
initial version

--- NEW FILE ---
<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY appname "refdb">
]>
<!-- $Id: refdb-manual-chapter22.sgml,v 1.1 2003/12/30 23:54:09 mhoenicka Exp $ -->
<chapter id="chapter-managing-notes">
  <title>Notes management</title>
  <para>Managing notes is very similar to <link linkend="chapter-managing-references">managing references</link>. The commands have analogous names and functionality. If you've familiarized yourself with managing references, the notes part should not be too hard either.</para>
  <sect1 id="sect-add-extended-notes">
    <title>Add extended notes</title>
    <para>Extended notes must be supplied as datasets according to the <ulink url="http://refdb.sourceforge.net/dtd/xnote/xnote.dtd">xnote DTD</ulink>. Add them to the database using the <link linkend="app-c-command-addnote"><command>addnote</command></link> command. Each file supplied to this command may either contain a single <sgmltag class="element">xnote</sgmltag> element or several of these wrapped into a <sgmltag class="element">xnoteset</sgmltag> element.</para>
    <note>
      <para>The <sgmltag class="attribute">id</sgmltag> attribute, if any, will be ignored when you add extended notes. The database engine will assign each note a new, unique identifier. The <sgmltag class="attribute">citekey</sgmltag> attribute will be honored unless there is a clash with an existing note. In this case &appname;d will refuse to add the note.</para>
      <para>If you want to overwrite or update an existing note, use the <link linkend="app-c-command-updatenote"><command>updatenote</command></link> command instead.</para>
    </note>
    <simplesect>
      <title>Example</title>
      <para>Assume the file <filename moreinfo="none">foo.xml</filename> contains a couple of extended notes. The following command will add them to the database "bar" (use the full path to <filename moreinfo="none">foo.xml</filename> if necessary):</para>
      <screen><prompt>&appname;c: </prompt><userinput>addnote -d bar foo.xml</userinput></screen>
    </simplesect>
  </sect1>
  <sect1 id="sect-view-extended-notes">
    <title>Find and view extended notes</title>
    <para>Just as you'd use the <link linkend="app-c-command-getref"><command>getref</command></link> command to locate references, you can use the <link linkend="app-c-command-getnote"><command>getnote</command></link> command to view notes. The query language is explained in a <link linkend="sect-description-notes-query-language">separate section</link>.</para>
    <para>The notes can be retrieved for screen display, as HTML or XHTML documents, or as xnote documents.</para>
  </sect1>
  <sect1 id="sect-delete-extended-notes">
    <title>Delete extended notes</title>
    <para>Use the <link linkend="app-c-command-deletenote"><command>deletenote</command></link> command to remove extended notes from the database. The argument to this command is a space-separated list of ID values.</para>
    <simplesect>
      <title>Example</title>
      <para>The following command removes the notes with the IDs 4 and 132 from the database "bar":</para>
      <screen><prompt>&appname;c: </prompt><userinput>deletenote -d bar 4 132</userinput></screen>
    </simplesect>
  </sect1>
  <sect1 id="sect-edit-extended-notes">
    <title>Edit extended notes</title>
    <para>Use the same strategy as you would for references:</para>
    <itemizedlist>
      <listitem>
	<para>First retrieve the notes you want to edit with the <link linkend="app-c-command-getnote"><command>getnote</command></link> command and write the output to a file:</para>
	<screen format="linespecific"><prompt>&appname;c: </prompt><userinput>getnote -d bar -o foo.xml -t xnote :NID:=4 OR :NCK:=biochemistry1999</userinput></screen>
      </listitem>
      <listitem>
	<para>Now use your favourite XML editor to edit the notes. Keep the <sgmltag class="attribute">citekey</sgmltag> and <sgmltag class="attribute">id</sgmltag> elements alone, as at least one of them is required to match the dataset with the existing copy in the database.</para>
      </listitem>
      <listitem>
	<para>Finally use the <link linkend="app-c-command-updatenote"><command moreinfo="none">updatenote</command></link> command to update the reference in the database:</para>
	<screen format="linespecific"><prompt>&appname;c: </prompt><userinput>updatenote -d bar foo.xml</userinput></screen>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="sect-link-extended-notes">
    <title>Link existing notes to other objects in the database</title>
    <para>If you want to link an existing extended notes to other objects in your database without modifying the contents of the note, the <link linkend="app-c-command-addlink"><command moreinfo="none">addlink</command></link> 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 <option>-r</option> switch.</para>
    <simplesect>
      <title>Example</title>
      <para>The following command links the existing note with the ID 5 to two references which are specified by their citation keys:</para>
	<screen format="linespecific"><prompt>&appname;c: </prompt><userinput>addlink -d bar :NID:=5 :CK:=Miller1999 :CK:=Doe2000</userinput></screen>
    </simplesect>
  </sect1>
</chapter>