X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fpazpar2.xml;h=ae08fe88f10b79a5764f27c1c2ac1e12d53e2543;hb=7c2c72339e8d1f6ada2de74870bcc8ae038d062e;hp=40d4e93c280f83dee9e9e93c2ceedd6322e234a4;hpb=cf880fac8c1c2805136cb463dc3d1b7d05826741;p=pazpar2-moved-to-github.git

diff --git a/doc/pazpar2.xml b/doc/pazpar2.xml
index 40d4e93..ae08fe8 100644
--- a/doc/pazpar2.xml
+++ b/doc/pazpar2.xml
@@ -8,7 +8,7 @@
      <!ENTITY % idcommon SYSTEM "common/common.ent">
      %idcommon;
 ]>
-<!-- $Id: pazpar2.xml,v 1.5 2007-06-04 10:34:06 adam Exp $ -->
+<!-- $Id: pazpar2.xml,v 1.12 2007-09-10 08:42:48 adam Exp $ -->
 <refentry id="pazpar2">
  <refentryinfo>
   <productname>Pazpar2</productname>
@@ -16,7 +16,7 @@
  </refentryinfo>
  <refmeta>
   <refentrytitle>Pazpar2</refentrytitle>
-  <manvolnum>1</manvolnum>
+  <manvolnum>8</manvolnum>
  </refmeta>
  
  <refnamediv>
@@ -27,33 +27,184 @@
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pazpar2</command>
+   <arg choice="opt"><option>-d</option></arg>
+   <arg choice="opt"><option>-D</option></arg>
+   <arg choice="opt"><option>-f <replaceable>config</replaceable></option></arg>
+   <arg choice="opt"><option>-h <replaceable>ip:port</replaceable></option></arg>
+   <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
+   <arg choice="opt"><option>-p <replaceable>pidfile</replaceable></option></arg>
+   <arg choice="opt"><option>-t <replaceable>path</replaceable></option></arg>
+   <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
+   <arg choice="opt"><option>-V</option></arg>
+   <arg choice="opt"><option>-X</option></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsect1><title>DESCRIPTION</title>
-  <para></para>
+  <para><command>pazpar2</command> is the Pazpar2 Metasearch daemon
+   and server.
+   In normal operation it acts as a simple HTTP server which serves
+   the Pazpar2 protocol.
+   The HTTP listener address may be given on the command line using
+   option <option>-h</option> or in the main configuration
+   file. The main configuration must be specified using option
+   <option>-f</option>.
+  </para>
  </refsect1>
  
  <refsect1><title>OPTIONS</title>
   <para></para>
- </refsect1>
+  
+  <variablelist>
+   <varlistentry>
+    <term><option>-d</option></term>
+    <listitem>
+     <para>
+      Enables dump of XML records to the current log file.
+      It is useful if stylesheets are being debugged.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-D</option></term>
+    <listitem>
+     <para>Puts the Pazpar2 server in the background.</para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-f <replaceable>config</replaceable></option></term>
+    <listitem>
+     <para>
+      Specifies main configuration. This option must be specified
+      in order for Pazpar2 to operate normally.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-h <replaceable>ip:port</replaceable></option></term>
+    <listitem>
+     <para>
+      Specifies the HTTP listener binding address.
+      The <replaceable>ip</replaceable>
+      may be a hostname or <literal>@</literal> for "any" address.
+      The <replaceable>port</replaceable> is an integer.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-l <replaceable>logfile</replaceable></option></term>
+    <listitem>
+     <para>
+      Specifies log file. The log file must be specified when Pazpar2
+      is running in the background (-D).
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-p <replaceable>pidfile</replaceable></option></term>
+    <listitem>
+     <para>
+      Specifies PID file. If Pazpar2 is started and configured properly
+      the file given holds the process ID of the Pazpar2 process.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><option>-t <replaceable>path</replaceable></option></term>
+    <listitem>
+     <para>
+      Specifies a file or directory with alternative settings. This
+      overrides the <literal>settings</literal> element in the main
+      configuration.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-u <replaceable>uid</replaceable></option></term>
+    <listitem>
+     <para>
+      Makes the Pazpar2 server change user ID to the
+      <replaceable>uid</replaceable> given.
+      This, normally, require root privilege.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-V</option></term>
+    <listitem>
+     <para>
+      Shows Pazpar2 version and versions of some of the components that it
+      is using (ICU and YAZ). Pazpar2 will not exit immediately after
+      displaying the version information (no daemon started).
+     </para>
+    </listitem>
+   </varlistentry>
 
+   <varlistentry>
+    <term><option>-X</option></term>
+    <listitem>
+     <para>
+      Makes the Pazpar2 server operate in debugging mode.
+      This prevents Pazpar2 from making separate threads and processes.
+      This option should not be used in production.
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+  
+ </refsect1>
+ 
  <refsect1><title>EXAMPLES</title>
-  <para></para>
+  <para>The Debian package of pazpar2 starts the server with:
+   <screen>
+    pazpar2 -D -f /etc/pazpar2/pazpar2.cfg -l /var/log/pazpar2.log -p /var/run/pazpar2.pid -u nobody
+   </screen>
+   (one line). 
+  </para>
+  <para>
+   This will put pazpar2 in the background (-D), read config from from
+   <filename>/etc/pazpar2/pazpar2.cfg</filename>, log messages to
+   <filename>/var/log/pazpar2.log</filename>, create PID file
+   <filename>/var/run/pazpar2.pid</filename>. When the daemon is properly
+   started, the server will change effective user ID to nobody.
+  </para>
+  <para>
+   The server can be terminated with:
+   <screen>
+    kill `cat /var/run/pazpar2.pid`
+   </screen>
+  </para>
+  <para>
+   If Pazpar2 is to be debugged using GDB, we use option -X:
+   <screen>
+    cd pazpar2/src
+    gdb ./pazpar2
+    (gdb) run -X -f ../etc/pazpar2.cfg
+   </screen>
+  </para>
  </refsect1> 
  
  <refsect1><title>FILES</title>
-  <para></para>
+  <para><filename>/usr/sbin/pazpar2</filename>: pazpar2 daemon</para>
+
+  <para><filename>/usr/share/pazpar2</filename>: pazpar2 shared files</para>
+
+  <para><filename>/etc/pazpar2</filename>: pazpar2 config area</para>
  </refsect1>
  
  <refsect1><title>SEE ALSO</title>
   <para>
+   Pazpar2 configuration:
    <citerefentry>
     <refentrytitle>pazpar2_conf</refentrytitle>
     <manvolnum>5</manvolnum>
    </citerefentry>
   </para>
   <para>
+   Pazpar2 protocol:
    <citerefentry>
     <refentrytitle>pazpar2_protocol</refentrytitle>
     <manvolnum>7</manvolnum>