[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter11.sgml,1.14,1.14.2.1 refdb-manual-chapter14.sgml,1.9

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/refdb/refdb/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15783/doc

Modified Files:
      Tag: Release_0_9_5_stable
	refdb-manual-chapter11.sgml refdb-manual-chapter14.sgml 
	refdb-manual-chapter3.sgml refdb-manual-chapter5.sgml 
	refdb-manual-chapter6.sgml refdb-manual-chapter8.sgml 
	refdb-manual-configopts.sgml refdb-manual.sgml 
Log Message:
updated for 0.9.5

Index: refdb-manual-chapter11.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter11.sgml,v
retrieving revision 1.14
retrieving revision 1.14.2.1
diff -u -U2 -r1.14 -r1.14.2.1

--- refdb-manual-chapter11.sgml	17 Feb 2004 22:14:40 -0000	1.14
+++ refdb-manual-chapter11.sgml	13 Dec 2004 20:24:07 -0000	1.14.2.1
@@ -754,5 +754,5 @@
 	</listitem>
 	<listitem>
-	  <para>Both references and datasets require a unique alphanumeric key. With a few limitations this is an arbitrary string consisting of letters (at least one) and optional digits. If you do not specify a citation key, &appname; will create one automatically. In the case of references, the publication year is appended to the last name of the first author. If this string is not unique, a sequential suffix starting at "a" through "z", then "aa" and so forth, is tested until a unique string is found. The same algorithm is used for extended note keys, but instead of an author name the user name serves as the base.</para>
+	  <para>Both references and extended notes require a unique alphanumeric key. With a few limitations this is an arbitrary string consisting of letters (at least one) and optional digits. If you do not specify a citation key, &appname; will create one automatically. In the case of references, the publication year is appended to the last name of the first author. If this string is not unique, a sequential suffix starting at "a" through "z", then "aa" and so forth, is tested until a unique string is found. The same algorithm is used for extended note keys, but instead of an author name the user name serves as the base.</para>
 	</listitem>
 	<listitem>

Index: refdb-manual-chapter14.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter14.sgml,v
retrieving revision 1.9.2.2
retrieving revision 1.9.2.3
diff -u -U2 -r1.9.2.2 -r1.9.2.3
--- refdb-manual-chapter14.sgml	25 Nov 2004 21:28:41 -0000	1.9.2.2
+++ refdb-manual-chapter14.sgml	13 Dec 2004 20:24:07 -0000	1.9.2.3
@@ -61,6 +61,7 @@
       <arg choice="opt" rep="norepeat">-G <replaceable>css-file</replaceable></arg>
       <arg>-h</arg>
-      <arg rep="repeat">-i <replaceable>includevar</replaceable></arg>
+      <arg rep="repeat">-i <replaceable>server-ip</replaceable></arg>
       <arg choice="opt" rep="norepeat">-I</arg>
+      <arg rep="repeat">-m <replaceable>includevar</replaceable></arg>
       <arg choice="opt" rep="norepeat">-N <replaceable>number</replaceable></arg>
       <arg>-S <replaceable>style</replaceable></arg>
@@ -97,7 +98,7 @@
       </varlistentry>
       <varlistentry>
-	<term>-i <replaceable>includevar</replaceable></term>
+	<term>-i <replaceable>server-ip</replaceable></term>
 	<listitem>
-	  <para>Specify variable names to include marked sections in the source document.</para>
+	  <para>Set the server IP address or hostname.</para>
 	</listitem>
       </varlistentry>
@@ -109,4 +110,10 @@
       </varlistentry>
       <varlistentry>
+	<term>-m <replaceable>includevar</replaceable></term>
+	<listitem>
+	  <para>Specify variable names to include marked sections in the source document.</para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
 	<term>-N <replaceable>number</replaceable></term>
 	<listitem>

Index: refdb-manual-chapter3.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter3.sgml,v
retrieving revision 1.12.2.1
retrieving revision 1.12.2.2
diff -u -U2 -r1.12.2.1 -r1.12.2.2
--- refdb-manual-chapter3.sgml	14 Nov 2004 16:04:49 -0000	1.12.2.1
+++ refdb-manual-chapter3.sgml	13 Dec 2004 20:24:07 -0000	1.12.2.2
@@ -44,5 +44,5 @@
 	<para>Cygwin currently does not support named pipes/FIFOs. &appname;d uses these to implement a child->parent messaging after the application server has forked. On Cygwin, this messaging is emulated with a temporary file. This is a bit slower (and a lot kludgier and error-prone) than a named pipe and almost certainly is a security hole.</para>
 	<note>
-	  <para>As of this writing, support for named pipes appears to be implemented as an experimental feature in Cygwin. </para>
+	  <para>As of this writing, support for named pipes appears to be implemented as an experimental feature in Cygwin. It does not work as expected yet, so as of this writing &appname; still emulates named pipes on Cygwin.</para>
 	</note>
       </listitem>
@@ -51,4 +51,7 @@
       </listitem>
       <listitem>
+	<para>The Cygwin port of SQLite has a problem working with absolute paths. The safest way is to start &appname;d from the root directory (the start script &appname;ctl does this by default) and use a relative path to the database directory (i.e. leave away the leading slash).</para>
+      </listitem>
+      <listitem>
 	<para>As the Cygwin library has to translate all calls to Unix system functions to native Windows function calls, there is a small performance penalty in comparison to native Windows or Linux/Unix applications. My general impression however is that this does not affect the overall performance as most time seems to be spent inside the database server. You may gain some milliseconds by running the application server on a Linux/Unix box, though.</para>
       </listitem>

Index: refdb-manual-chapter5.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter5.sgml,v
retrieving revision 1.24.2.3
retrieving revision 1.24.2.4
diff -u -U2 -r1.24.2.3 -r1.24.2.4
--- refdb-manual-chapter5.sgml	27 Nov 2004 23:11:16 -0000	1.24.2.3
+++ refdb-manual-chapter5.sgml	13 Dec 2004 20:24:07 -0000	1.24.2.4
@@ -437,7 +437,9 @@
 	    <para>Check out the latest &appname; sources with this command:</para>
 	    <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout refdb</userinput></screen>
-	    <para>Other interesting modules are <filename>perlmod</filename> (the Perl modules and the Perl client library) and <filename>elisp</filename> (the Emacs support files).</para>
+	    <para>This will retrieve the HEAD code which is pretty much experimental and unlikely to work at the moment. The more usable stable branch, which receives most of the current development work, can be retrieved with this command:</para>
+	    <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout -r Release_0_9_5_stable refdb</userinput></screen>
+	    <para>Other interesting modules to check out are <filename>perlmod</filename> (the Perl modules and the Perl client library), <filename moreinfo="none">makestyle</filename> (the Perl script to write bibliography styles from scratch), and <filename>elisp</filename> (the Emacs support files).</para>
 	    <para>If you are interested in a particular release or branch, use a command along the lines of this example instead:</para>
-	    <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout -r Release_0_9_1 refdb</userinput></screen>
+	    <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout -r Release_0_9_4 refdb</userinput></screen>
 	  </step>
 	  <step performance="required">
@@ -488,5 +490,5 @@
 	  <procedure>
 	    <step performance="required">
-	      <para>Review the parameters in the script <filename moreinfo="none">&appname;</filename> in the <filename class="directory" moreinfo="none">scripts</filename> directory of the source distribution (this file is not automatically installed). Set the value of the script variable <varname>BSDSTYLE</varname> to "YES" (the sole purpose of this variable is to make the boot message blend in seamlessly). If necessary, change the paths and names to your needs and adapt the following steps.</para>
+	      <para>Review the parameters in the script <filename moreinfo="none">&appname;</filename> in the <filename class="directory" moreinfo="none">scripts</filename> directory of the source distribution (this file is not automatically installed). Set the value of the script variable <varname>BSDSTYLE</varname> to "YES" (the sole purpose of this variable is to make the boot message blend in seamlessly, if you happen to care for aesthetics). If necessary, change the paths and names to your needs and adapt the following steps.</para>
 	    </step>
 	    <step performance="required">
@@ -523,6 +525,5 @@
 	<para>The BSD version of <command moreinfo="none">make</command> cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set CFLAGS=-I/usr/local/include during the configuration step. The full configure command, using the default installation paths for the accessory files and programs, looks like this:</para>
 	<screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">CFLAGS=-I/usr/local/include ./configure --with-expat-lib=/usr/local/lib \
---with-docbook-xsl=/usr/local/share/xsl/docbook --with-classpath-root=/usr/local/share/java/classes \
---with-refdb-url=http://localhost/refdb</userinput></screen>
+--with-classpath-root=/usr/local/share/java/classes --with-refdb-url=http://localhost/refdb</userinput></screen>
 	<para>The shared data end up in <filename class="directory" moreinfo="none">/usr/local/share/refdb</filename>, the configuration files will be in <filename class="directory" moreinfo="none">/usr/local/etc/&appname;</filename>.</para>
       </sect3>
@@ -554,10 +555,10 @@
 	<itemizedlist>
 	  <listitem>
-	    <para><ulink url="http://www.cygwin.com">Cygwin toolkit</ulink>, DLL version 1.5.0 or later (the current "stable" version 1.3.22 does not work with the Cygwin port of PostgreSQL). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.</para>
+	    <para><ulink url="http://www.cygwin.com">Cygwin toolkit</ulink>, DLL version 1.5.0 or later (the current version as of this writing, 1.5.12, has serious problems with PostgreSQL, though). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.</para>
 	  </listitem>
 	  <listitem>
 	    <para>A SQL database engine. Currently you can choose between <ulink url="http://www.mysql.com">MySQL</ulink> (version 3.23 or later) and <ulink url="http://www.postgresql.org">PostgreSQL</ulink> (version 7.1 or later). The database server does not have to physically run on the box(es) where you plan to install &appname;, it is sufficient if it is accessible through the network.</para>
-	    <para>Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which is probably the most convenient way to run a database server on your Cygwin box. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only <ulink url="http://www.neuro.gatech.edu/users/cwilson/cygutils/cygipc/index.hml">here</ulink>.</para>
-	    <para>Other database engines are not supported yet on the Windows platform.</para>
+	    <para>Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which used to be the most convenient way to run a database server on your Cygwin box, but as stated above it may be broke when you try. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only <ulink url="http://www.neuro.gatech.edu/users/cwilson/cygutils/cygipc/index.hml">here</ulink>.</para>
+	    <para>SQLite is not available as a package, but current versions build straight out of the tarball and run with one minor annoyance (absolute paths to database files don't work). MySQL is currently not officially supported on this platform, but you may still get it to work.</para>
 	  </listitem>
 	  <listitem>
@@ -574,5 +575,5 @@
 	<itemizedlist>
 	  <listitem>
-	    <para>The <ulink url="http://sourceforge.net/projects/libdbi">libdbi library</ulink> and headers, along with the <ulink url="http://sourceforge.net/projects/libdbi-drivers">libdbi-drivers</ulink> package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Currently only MySQL and PostgreSQL are supported on Cygwin. The mSQL driver might work too, but is untested. Prebuilt binaries for both libdbi and libdbi-drivers are available <ulink url="http://libdbi.sourceforge.net/downloads/">here</ulink>.</para>
+	    <para>The <ulink url="http://sourceforge.net/projects/libdbi">libdbi library</ulink> and headers, along with the <ulink url="http://sourceforge.net/projects/libdbi-drivers">libdbi-drivers</ulink> package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Prebuilt binaries for both libdbi and libdbi-drivers are available <ulink url="http://libdbi.sourceforge.net/downloads/">here</ulink>.</para>
 	  </listitem>
 	  <listitem>
@@ -605,5 +606,7 @@
 &configopts;
 	  <para>Finally, run <command>./configure</command> with any options that you need. If you build in a separate directory, use the relative path to <filename>configure</filename> in the source directory. A complete set of options might look like this if you use PostgreSQL:</para>
-	  <screen format="linespecific"><prompt moreinfo="none">$~ </prompt><userinput moreinfo="none">./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run --with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook --with-tei-xsl=/usr/local/share/xsl/tei</userinput></screen>
+	  <screen format="linespecific"><prompt moreinfo="none">$~ </prompt><userinput moreinfo="none">./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run \
+--with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook \
+--with-tei-xsl=/usr/local/share/xsl/tei</userinput></screen>
 	</step>
 	<step performance="required">
@@ -774,5 +777,5 @@
 	    <term>Initialized libdbi, but no drivers were found!</term>
 	    <listitem>
-	      <para>The libdbi library was not able to locate or properly load at least one database driver. Please check the libdbi installation and make sure you've installed at least one database driver. Remember that on most systems the libdbi-drivers package is distributed separately from the libdbi package which contains only the framework, but no drivers.</para>
+	      <para>The libdbi library was not able to locate or properly load at least one database driver. Please check the libdbi installation and make sure you've installed at least one database driver. Remember that on most systems the libdbi-drivers package is distributed separately from the libdbi package which contains only the framework, but no drivers. This error also occurs if you install driver versions which are too old for the libdbi framework.</para>
 	    </listitem>
 	  </varlistentry>

Index: refdb-manual-chapter6.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter6.sgml,v
retrieving revision 1.17.2.2
retrieving revision 1.17.2.3
diff -u -U2 -r1.17.2.2 -r1.17.2.3
--- refdb-manual-chapter6.sgml	27 Nov 2004 23:11:17 -0000	1.17.2.2
+++ refdb-manual-chapter6.sgml	13 Dec 2004 20:24:08 -0000	1.17.2.3
@@ -127,4 +127,7 @@
 	    </note>
 	    <para>For embedded database engines, this option sets the directory which contains the database files. The default is <filename class="directory" moreinfo="none">/usr/local/share/&appname;/db</filename>.</para>
+	    <note id="note-sqlite-abspath">
+	      <para>SQLite on Cygwin has a bug which prevents the use of absolute paths. Use a relative path instead by leaving out the leading slash. This assumes that &appname;d is started from the root directory. The start script &appname;ctl does this automatically.</para>
+	    </note>
 	  </listitem>
 	</varlistentry>
@@ -274,5 +277,5 @@
 	    <entry>dbpath</entry>
 	    <entry>/usr/local/share/refdb/db</entry>
-	    <entry>The directory that contains the database files of an embedded database engine.</entry>
+	    <entry>The directory that contains the database files of an embedded database engine. Leave out the leading slash if you use SQLite on Cygwin (see note <link linkend="note-sqlite-abspath">above</link>).</entry>
 	  </row>
 	  <row>
@@ -327,4 +330,9 @@
 	  </row>
 	  <row>
+	    <entry>in_encoding</entry>
+	    <entry>ISO-8859-1</entry>
+	    <entry>Specify the default character encoding for RIS data being added to databases.</entry>
+	  </row>
+	  <row>
 	    <entry>dbi_driverdir</entry>
 	    <entry>(none)</entry>

Index: refdb-manual-chapter8.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter8.sgml,v
retrieving revision 1.13.2.2
retrieving revision 1.13.2.3
diff -u -U2 -r1.13.2.2 -r1.13.2.3
--- refdb-manual-chapter8.sgml	25 Nov 2004 21:28:42 -0000	1.13.2.2
+++ refdb-manual-chapter8.sgml	13 Dec 2004 20:24:08 -0000	1.13.2.3
@@ -436,8 +436,8 @@
   <sect1 id="sect1-backup-data">
     <title>Backup your data</title>
-    <para>If your database crashes for whatever reasons, the first question you'll hear is: "You got a backup, don't you?". At this point in your life you shouldn't even think about <emphasis>not</emphasis> having a backup.</para>
+    <para>If your database crashes for whatever reasons, the first question you'll hear is: "You've got a backup, don't you?". At this point in your life you shouldn't even think about <emphasis>not</emphasis> having a backup.</para>
     <para>There's basically two ways to create a backup of your reference data: Use a risx dump or use a SQL dump. The risx dump is slower but it would allow you to transfer the data to a &appname; installation using a different database server. The SQL dump is faster but you're tied to the database server you're using. If you use SQLite as your database backend, you may simply grab copies of the database files. Each database is stored in one file. This file holds all required information and is platform-independent, so it is suitable for backup purposes.</para>
     <warning>
-      <para>Backups are useful only if you create them regularly. You should work out a schedule based on how often the contents of the database change. Think about setting up a <command moreinfo="none">cron</command> job for a nightly or weekly snapshot.</para>
+      <para>Backups are useful only if you create them regularly. You should work out a schedule based on how often the contents of the database change. Think about setting up a <command moreinfo="none">cron</command> job for nightly or weekly snapshots.</para>
     </warning>
     <sect2>

Index: refdb-manual-configopts.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-configopts.sgml,v
retrieving revision 1.4.2.2
retrieving revision 1.4.2.3
diff -u -U2 -r1.4.2.2 -r1.4.2.3
--- refdb-manual-configopts.sgml	25 Nov 2004 21:28:42 -0000	1.4.2.2
+++ refdb-manual-configopts.sgml	13 Dec 2004 20:24:08 -0000	1.4.2.3
@@ -66,5 +66,5 @@
 		<para>Specify the full path to the root directory of the TEI XSL stylesheets.</para>
       <note>
-	<para>The <ulink url="http://www.tei-c.org/Stylesheets/teixsl.html">TEI Consortium</ulink> ships two archives <filename moreinfo="none">P4/teixsl-fo.zip</filename> and <filename moreinfo="none">P4/teixsl-html.zip</filename>. The corresponding archives for the upcoming TEI P5 release are <filename moreinfo="none">P5/teixsl-fo.zip</filename> and <filename moreinfo="none">P5/teixsl-html.zip</filename>. &appname; expects the contents of these archives in two subdirectories of the TEI XSL stylesheet root directory. If you e.g. unpack the archives in  the TEI XSL stylesheet root directory <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei/P4</filename>, the expected subdirectories <filename class="directory">fo</filename>, <filename class="directory">html</filename>, and <filename class="directory">common</filename> will be created.</para>
+	<para>The <ulink url="http://www.tei-c.org/Stylesheets/teixsl.html">TEI Consortium</ulink> ships two archives <filename moreinfo="none">P4/teixsl-fo.zip</filename> and <filename moreinfo="none">P4/teixsl-html.zip</filename>. The corresponding archives for the upcoming TEI P5 release are <filename moreinfo="none">P5/teixsl-fo.zip</filename> and <filename moreinfo="none">P5/teixsl-html.zip</filename>. &appname; expects the contents of these archives in two subdirectories <filename moreinfo="directory">P4</filename> and <filename moreinfo="directory">P5</filename> of the TEI XSL stylesheet root directory. If you e.g. use the TEI XSL stylesheet root directory <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei</filename>, unpack <filename moreinfo="none">P4/teixsl-fo.zip</filename> in <filename class="directory" moreinfo="none">/usr/local/share/xsl/tei/P4</filename>, and the expected subdirectories <filename class="directory">fo</filename>, <filename class="directory">html</filename>, and <filename class="directory">common</filename> will be created therein.</para>
       </note>
 	      </listitem>

Index: refdb-manual.sgml
===================================================================
RCS file: /cvsroot/refdb/refdb/doc/refdb-manual.sgml,v
retrieving revision 1.16.2.1
retrieving revision 1.16.2.2
diff -u -U2 -r1.16.2.1 -r1.16.2.2
--- refdb-manual.sgml	14 Nov 2004 16:04:51 -0000	1.16.2.1
+++ refdb-manual.sgml	13 Dec 2004 20:24:08 -0000	1.16.2.2
@@ -42,5 +42,5 @@
       <revision>
 	<revnumber>1.19</revnumber>
-	<date>2004-11-14</date>
+	<date>2004-12-12</date>
       </revision>
       <revision>
@@ -125,6 +125,6 @@
     <title>Preface</title>
     <sect1>
-      <title>What is &appname; good for?</title>
-      <para><application>&appname;</application> is a free and portable reference database and bibliography application that serves a similar purpose for SGML, XML, and LaTeX documents like <ulink url="http://www.refman.com">Reference Manager</ulink> or <ulink url="http://www.endnote.com">EndNote</ulink> do for word processor documents. The bibliography part is something like bibtex for markup languages. &appname; consists of an application server which interacts with a relational database on the server side and a variety of clients on the workstation side. These clients perform the common tasks of a reference database, like adding and searching entries, as well as generating bibliographies.</para>
+      <title>&appname; in a nutshell</title>
+      <para><application>&appname;</application> is a free and portable reference and notes database as well as a bibliography application that serves a similar purpose for SGML, XML, and LaTeX documents like <ulink url="http://www.refman.com">Reference Manager</ulink> or <ulink url="http://www.endnote.com">EndNote</ulink> do for word processor documents. The bibliography part is something like bibtex for markup languages. &appname; consists of an application server which interacts with a relational database on the server side and a variety of clients on the workstation side. These clients perform the common tasks of a reference database, like adding and searching entries, as well as generating bibliographies.</para>
     </sect1>
     <sect1>



