More admin clean up...
[working/Evergreen.git] / 1.6 / admin / z3950.xml
index f2d99dd..2f5b769 100644 (file)
@@ -2,44 +2,42 @@
 <chapter xml:id="z3950" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
     <info>\r
-        <title>SRU and Z39.50 Server</title>\r
+        <title><systemitem class="protocol">SRU</systemitem> and <systemitem class="protocol">Z39.50</systemitem> Server</title>\r
     </info>\r
-\r
     <para>Evergreen is extremely scalable and can serve the need of a large range of libraries. The specific requirements and configuration of your system should be determined based on your \r
        specific needs of your organization or consortium.</para>\r
-               \r
-    \r
        <section xml:id="Testing_SRU_yaz-client">\r
                <info>\r
-                   <title>Testing SRU with yaz-client</title>\r
+                   <title>Testing SRU with yaz-client</title><indexterm><primary>yaz</primary></indexterm>\r
                </info> \r
-                        <para>yaz-client is installed as a part of Index Data's YAZ software. Recent versions include support for querying SRU servers. Evergreen ships an SRU configuration \r
-                       that works out of the box. To search Evergreen with yaz-client, choose the <emphasis>GET</emphasis> query method and issue the <emphasis>find</emphasis> command. \r
-                       In the following example, we connect to the Evergreen test server <emphasis>dev.gapines.org</emphasis>; substitute this hostname with your own Evergreen server \r
-                       hostname:</para>\r
-                       <note><para>Some older versions of yaz-client have known issues with SRU. Ensure that you are using the latest edition of yaz from \r
+                        <para>yaz-client is installed as a part of Index Data's YAZ software. Recent versions include support for querying <systemitem class="protocol">SRU</systemitem> servers. \r
+                       Evergreen ships an <systemitem class="protocol">SRU</systemitem> configuration <indexterm><primary>SRU</primary></indexterm>\r
+                       that works out of the box. To search Evergreen with yaz-client, choose the <emphasis>GET</emphasis> query method and issue the <command>find</command> command. \r
+                       In the following example, we connect to the Evergreen test server <systemitem class="domainname">dev.gapines.org</systemitem> - substitute this hostname with your own \r
+                       Evergreen server hostname:</para>\r
+                       <note><para>Some older versions of yaz-client have known issues with <systemitem class="protocol">SRU</systemitem>. Ensure that you are using the latest edition of yaz from \r
                        <link xlink:href="http://www.indexdata.com/yaz">http://www.indexdata.com/yaz</link>.</para></note>\r
-                       <screen>$ yaz-client http://dev.gapines.org/opac/extras/sru</screen>\r
-                       <screen>Z> sru GET 1.1</screen>\r
-                       <screen>Z> find hemingway</screen>\r
+                       <screen><userinput>$ yaz-client http://dev.gapines.org/opac/extras/sru</userinput></screen>\r
+                       <screen><prompt>Z></prompt> <userinput>sru GET 1.1</userinput></screen>\r
+                       <screen><prompt>Z></prompt> <userinput>find hemingway</userinput></screen>\r
                        \r
-                        <para>If your database has records that match that term, you will get the corresponding MARCXML records in your response from yaz-client.</para>\r
+                        <para>If your database has records that match that term, you will get the corresponding <systemitem>MARCXML</systemitem> records \r
+                       in your response from yaz-client.</para><indexterm><primary>MARCXML</primary></indexterm>\r
                         <para>Here's what the SRU request looks like as sent to the Evergreen web server:</para>\r
-                        <screen>GET /opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</screen>\r
+                        <screen><userinput>GET /opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</userinput></screen>\r
                        <para>You can see what the response looks like by hitting the same URL in your Web browser: \r
                        <ulink url="http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0">\r
                        http://dev.gapines.org/opac/extras/sru?version=1.1&amp;operation=searchRetrieve&amp;query=hemingway&amp;maximumRecords=0</ulink>\r
-                       CQL queries</para>\r
-                        <para>Evergreen supports some CQL index-sets for advanced queries such as a subset of Dublin Core (DC) elements. Those DC elements that are \r
-                       supported map to Evergreen default indexes as follows:</para>\r
-                       <informaltable xml:id="dc_elements">\r
-                       \r
+                       <systemitem>CQL</systemitem> queries</para>\r
+                        <para>Evergreen supports some <systemitem>CQL</systemitem> <indexterm><primary>CQL</primary></indexterm> index-sets for advanced queries such as a subset of \r
+                       <systemitem>Dublin Core</systemitem> (DC) elements. Those DC elements that are \r
+                       supported map to Evergreen default indexes as follows:</para><indexterm><primary>Dublin Core</primary></indexterm>\r
+                       <informaltable xml:id="dc_elements">    \r
                        <tgroup cols="2">\r
                                <thead>\r
                                        <row>\r
                                                <entry>DC element </entry>\r
                                                <entry>Evergreen index</entry>\r
-                                               \r
                                        </row>\r
                                </thead>\r
                                <tbody>\r
                                </tbody>\r
                        </tgroup>\r
                        </informaltable>\r
-                       <para>Here are a few examples of SRU searches against some of these indexes:</para>\r
+                       <para>Here are a few examples of <systemitem class="protocol">SRU</systemitem> searches against some of these indexes:</para>\r
                        <itemizedlist>\r
                                <listitem>dc.title all <quote>complete dinosaur</quote></listitem>\r
                                <listitem>dc.subject all <quote>britain france</quote></listitem>\r
                                <listitem>dc.title exact <quote>The Empire Strikes Back</quote></listitem>\r
                                <listitem>dc.author=king and dc.title=zone</listitem>\r
                        </itemizedlist>\r
-\r
        </section>\r
        <section xml:id="Z3950serversupport">\r
                <info>\r
-                   <title>Setting up Z39.50 server support</title>\r
+                   <title>Setting up <systemitem class="protocol">Z39.50</systemitem> server support</title><indexterm><primary>Z39.50</primary></indexterm>\r
                </info> \r
 \r
-                       <note><para>You must have Evergreen's SRU server running before you can enable Z39.50 server support.</para></note>                      \r
-                       <para>This support uses an Z39.50-to-SRU translator service supplied by the <emphasis>Net::Z3950::Simple2ZOOM</emphasis> Perl module to enable Evergreen to act as a Z39.50 server. \r
-                       You could run the Z39.50 server on a different machine. It just needs to be able to connect to the Evergreen SRU server.</para>\r
+                       <note><para>You must have Evergreen's <systemitem class="protocol">SRU</systemitem> server running before you can enable <systemitem>Z39.50</systemitem> server support.</para>\r
+                       </note>                  \r
+                       <para>This support uses an <systemitem class="protocol">Z39.50</systemitem>-to-<systemitem class="protocol">SRU</systemitem> translator service supplied \r
+                       by the <systemitem>Net::Z3950::Simple2ZOOM</systemitem><indexterm><primary>Simple2ZOOM</primary></indexterm> Perl module to enable Evergreen to act as a <systemitem                            class="protocol">Z39.50</systemitem> server. \r
+                       You could run the <systemitem class="protocol">Z39.50</systemitem> server on a different machine. It just needs to be able to connect to the \r
+                       Evergreen <systemitem class="protocol">SRU</systemitem> server.</para>\r
                        <procedure>\r
-                               <title>Setting up the Z39.50 server</title>\r
+                               <title>Setting up the <systemitem class="protocol">Z39.50</systemitem> server</title>\r
                                <step>\r
                                        <para>Install a recent version of yaz (the Makefile.install should have installed a suitable version).</para></step>\r
                                <step>\r
-                                       <para>Install Net::Z3950::Simple2ZOOM (sudo cpan Net::Z3950::Simple2ZOOM)</para></step>\r
+                                       <para>Install <systemitem>Net::Z3950::Simple2ZOOM</systemitem> (<userinput>sudo cpan Net::Z3950::Simple2ZOOM</userinput>)</para></step>\r
                                <step>\r
-                                       <para>Create a Simple2ZOOM configuration file. Something like the following is a good start, and is based on the Simple2ZOOM documentation example. \r
-                                       We'll name the file dgo.conf for our example:</para>    \r
-                                       <programlisting>\r
-                                       &lt;client&gt;\r
-                                               &lt;database name="gapines"&gt;\r
-                                                       &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
-                                                       &lt;option name="sru"&gt;get&lt;/option&gt;\r
-                                                       &lt;charset&gt;marc-8&lt;/charset&gt;\r
-                                                       &lt;search&gt;\r
-                                                               &lt;querytype&gt;cql&lt;/querytype&gt;\r
-                                                               &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
-                                                               &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
-                                                       &lt;/search&gt;\r
-                                               &lt;/database&gt;\r
-                                       &lt;/client&gt;\r
-                                       </programlisting>\r
+                                       <para>Create a <systemitem class="daemon">Simple2ZOOM</systemitem> configuration file. Something like the following is a good start, and is \r
+                                       based on the <systemitem class="daemon">Simple2ZOOM</systemitem> \r
+                                       documentation example. We'll name the file <filename>dgo.conf</filename> for our example:</para>        \r
+<programlisting>\r
+&lt;client&gt;\r
+       &lt;database name="gapines"&gt;\r
+               &lt;zurl&gt;http://dev.gapines.org/opac/extras/sru&lt;/zurl&gt;\r
+               &lt;option name="sru"&gt;get&lt;/option&gt;\r
+               &lt;charset&gt;marc-8&lt;/charset&gt;\r
+               &lt;search&gt;\r
+                       &lt;querytype&gt;cql&lt;/querytype&gt;\r
+                       &lt;map use="4"&gt;&lt;index&gt;eg.title&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="7"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="8"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="21"&gt;&lt;index&gt;eg.subject&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="1003"&gt;&lt;index&gt;eg.author&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="1018"&gt;&lt;index&gt;eg.publisher&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="1035"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
+                       &lt;map use="1016"&gt;&lt;index&gt;eg.keyword&lt;/index&gt;&lt;/map&gt;\r
+               &lt;/search&gt;\r
+       &lt;/database&gt;\r
+&lt;/client&gt;\r
+</programlisting>\r
                                        <para>You can have multiple &lt;database&gt; sections in a single file, each pointing to a different scope of your consortium. The name attribute on \r
-                                       the &lt;database&gt; element is used in your Z39.50 connection string to name the database. The &lt;zurl&gt; element must point to \r
-                                       <emphasis>http://hostname/opac/extras/sru</emphasis>. As of Evergreen 1.6, you can append an optional organization unit shortname for search \r
+                                       the &lt;database&gt; element is used in your <systemitem class="protocol">Z39.50</systemitem> connection string to name the database. The \r
+                                       <systemitem>&lt;zurl&gt;</systemitem>  element must point to \r
+                                       <uri>http://hostname/opac/extras/sru</uri>. As of Evergreen 1.6, you can append an optional organization unit shortname for search \r
                                        scoping purposes, and you can also append <emphasis>/holdings</emphasis> if you want to expose the holdings for any returned records. So your zurl \r
-                                       could be <emphasis>http://dev.gapines.org/opac/extras/sru/BR1/holdings</emphasis> to limit the search scope to BR1 and its children, and \r
+                                       could be <uri>http://dev.gapines.org/opac/extras/sru/BR1/holdings</uri> to limit the search scope to <emphasis role="bold">BR1</emphasis> and its children, and \r
                                        to expose its holdings.</para>\r
                                </step>\r
                                <step>\r
-                                       <para>Run simple2ZOOM as a daemon, specifying the configuration files and one or more listener addresses that the Z39.50 server will be accessible on. \r
-                                       If you do not specify a port, it will automatically run on port 9999. In the following example, we tell it to listen both to localhost on port 2210, \r
-                                       and on dev.gapines.org on port 210:</para>\r
-                                       <programlisting>\r
-                                        &lt;yazgfs&gt;\r
-                                               &lt;server id="server1"&gt;\r
-                                                       &lt;retrievalinfo&gt;\r
-                                                               &lt;retrieval syntax="xml"/&gt;\r
-                                                               &lt;retrieval syntax="marc21"&gt;\r
-                                                               &lt;backend syntax="xml"&gt;\r
-                                                                       &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
-                                                               &lt;/backend&gt;\r
-                                                               &lt;/retrieval&gt;\r
-                                                       &lt;/retrievalinfo&gt;\r
-                                               &lt;/server&gt;\r
-                                       &lt;/yazgfs&gt;\r
-                                       </programlisting>\r
+                                       <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that the \r
+                                       <systemitem class="protocol">Z39.50</systemitem> server will\r
+                                        be accessible on. If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example, \r
+                                       we tell it to listen both to localhost on port <systemitem>2210</systemitem>, and on <systemitem class="domainname">dev.gapines.org</systemitem> \r
+                                       n port <systemitem>210</systemitem>:</para>\r
+<programlisting>\r
+ &lt;yazgfs&gt;\r
+       &lt;server id="server1"&gt;\r
+               &lt;retrievalinfo&gt;\r
+                       &lt;retrieval syntax="xml"/&gt;\r
+                       &lt;retrieval syntax="marc21"&gt;\r
+                       &lt;backend syntax="xml"&gt;\r
+                               &lt;marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/&gt;\r
+                       &lt;/backend&gt;\r
+                       &lt;/retrieval&gt;\r
+               &lt;/retrievalinfo&gt;\r
+       &lt;/server&gt;\r
+&lt;/yazgfs&gt;\r
+</programlisting>\r
                                </step>\r
                                <step>\r
-                                       <para>Run simple2ZOOM as a daemon, specifying the configuration files and one or more listener addresses that the Z39.50 server will be accessible on. \r
-                                       If you do not specify a port, it will automatically run on port 9999. In the following example, we tell it to listen both to localhost on port 2210, \r
-                                       and on dev.gapines.org on port 210:</para>\r
-                                       <command>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</command>\r
+                                       <para>Run <systemitem class="daemon">simple2ZOOM</systemitem> as a daemon, specifying the configuration files and one or more listener addresses that \r
+                                       the <systemitem class="protocol">Z39.50</systemitem> server will be accessible on. \r
+                                       If you do not specify a port, it will automatically run on port <systemitem>9999</systemitem>. In the following example, we tell it to listen both to localhost on                                              port 2210, and on dev.gapines.org on port <systemitem>210</systemitem>:</para>\r
+                                       <screen><userinput>simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210</userinput></screen>\r
                                </step>                         \r
                        </procedure>\r
-                       <para>To test the Z39.50 server, we can use yaz-client again:</para>\r
-                       <screen>\r
-                       yaz-client\r
-                       Z&gt; open localhost:2210/gapines\r
-                       Connecting...OK.\r
-                       Sent initrequest.\r
-                       Connection accepted by v3 target.\r
-                       ID     : 81/81\r
-                       Name   : Simple2ZOOM Universal Gateway/GFS/YAZ\r
-                       Version: 1.03/1.128/3.0.34\r
-                       Options: search present delSet triggerResourceCtrl scan sort namedResultSets\r
-                       Elapsed: 0.010718\r
-                       Z&gt; format marcxml\r
-                       Z&gt; find <quote>dc.title=zone and dc.author=king</quote>\r
-                       Sent searchRequest.\r
-                       Received SearchResponse.\r
-                       Search was a success.\r
-                       Number of hits: 0, setno 4\r
-                       records returned: 0\r
-                       Elapsed: 0.611432\r
-                       Z&gt; find <quote>dead zone</quote>\r
-                       Sent searchRequest.\r
-                       Received SearchResponse.\r
-                       Search was a success.\r
-                       Number of hits: 4, setno 5\r
-                       records returned: 0\r
-                       Elapsed: 1.555461\r
-                       Z&gt; show 1\r
-                       Sent presentRequest (1+1).\r
-                       Records: 1\r
-                       []Record type: XML\r
-                       &lt;record xmlns:... (rest of record deliberately truncated)\r
-                       </screen>\r
+                       <para>To test the <systemitem class="protocol">Z39.50</systemitem> server, we can use <application>yaz-client</application> again:</para>\r
+<screen>\r
+yaz-client\r
+Z&gt; open localhost:2210/gapines\r
+Connecting...OK.\r
+Sent initrequest.\r
+Connection accepted by v3 target.\r
+ID     : 81/81\r
+Name   : Simple2ZOOM Universal Gateway/GFS/YAZ\r
+Version: 1.03/1.128/3.0.34\r
+Options: search present delSet triggerResourceCtrl scan sort namedResultSets\r
+Elapsed: 0.010718\r
+Z&gt; format marcxml\r
+Z&gt; find <quote>dc.title=zone and dc.author=king</quote>\r
+Sent searchRequest.\r
+Received SearchResponse.\r
+Search was a success.\r
+Number of hits: 0, setno 4\r
+records returned: 0\r
+Elapsed: 0.611432\r
+Z&gt; find <quote>dead zone</quote>\r
+Sent searchRequest.\r
+Received SearchResponse.\r
+Search was a success.\r
+Number of hits: 4, setno 5\r
+records returned: 0\r
+Elapsed: 1.555461\r
+Z&gt; show 1\r
+Sent presentRequest (1+1).\r
+Records: 1\r
+[]Record type: XML\r
+&lt;record xmlns:... (rest of record deliberately truncated)\r
+</screen>\r
        </section>\r
 </chapter>\r
 \r