Do some clean up of development files. Adjust converting script to
[working/Evergreen.git] / 1.6 / development / supercat.xml
1 <?xml version="1.0" encoding="utf-8"?>\r
2 <chapter xml:id="supercat" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
4         <info>\r
5                 <title>SuperCat</title>\r
6         </info>\r
7         <para>SuperCat allows Evergreen record and information retrieval from a web browser using a based on a number of open web standards and formats. The following record types are supported:</para>\r
8         <itemizedlist>\r
9                 <listitem>isbn</listitem>\r
10                 <listitem>metarecord</listitem>\r
11                 <listitem>record</listitem>\r
12         </itemizedlist>\r
13         <simplesect>\r
14                 <title>Return a list of ISBNs for related records</title>\r
15                 <para>Similar to the OCLC xISBN service, Evergreen can return a list of related records based on its oISBN algorithm:</para>\r
16                 <para><uri>http://&lt;hostname&gt;/opac/extras/osibn/&lt;ISBN&gt;</uri></para>\r
17                 <para>For example, <uri>http://dev.gapines.org/opac/extras/oisbn/0439136350</uri> returns:</para>\r
18 <screen>\r
19 &lt;idlist metarecord="302670"&gt;\r
20 &lt;isbn record="250060"&gt;0790783525&lt;/isbn&gt;\r
21 &lt;isbn record="20717"&gt;0736691316&lt;/isbn&gt;\r
22 &lt;isbn record="250045"&gt;0790783517&lt;/isbn&gt;\r
23 &lt;isbn record="199060"&gt;9500421151&lt;/isbn&gt;\r
24 &lt;isbn record="250061"&gt;0790783495&lt;/isbn&gt;\r
25 &lt;isbn record="154477"&gt;0807286028&lt;/isbn&gt;\r
26 &lt;isbn record="227297"&gt;1594130027&lt;/isbn&gt;\r
27 &lt;isbn record="26682"&gt;0786222743&lt;/isbn&gt;\r
28 &lt;isbn record="17179"&gt;0807282316&lt;/isbn&gt;\r
29 &lt;isbn record="34885"&gt;0807282316&lt;/isbn&gt;\r
30 &lt;isbn record="118019"&gt;8478885196&lt;/isbn&gt;\r
31 &lt;isbn record="1231"&gt;0738301477&lt;/isbn&gt;\r
32 &lt;/idlist&gt;\r
33 </screen>\r
34          </simplesect>\r
35          <simplesect>\r
36                 <title>Return records</title>\r
37                 <para>SuperCat can return records and metarecords in many different formats (see <xref linkend='supportedsupercatformats' /></para>\r
38                 <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/retrieve/&lt;format&gt;/&lt;record-type&gt;/&lt;bib-ID&gt;</uri></para>\r
39                 <para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/retrieve/mods/record/555</uri> returns:</para>\r
40 <screen>\r
41 &lt;mods:modsCollection version="3.0"&gt;\r
42         &lt;mods:mods xsi:schemaLocation="http://www.loc.gov/mods/ http://www.loc.gov/standards/mods/mods.xsd"&gt;\r
43                 &lt;titleInfo&gt;\r
44                         &lt;title&gt;More Brer Rabbit stories /&lt;/title&gt;\r
45                 &lt;/titleInfo&gt;\r
46                 &lt;typeOfResource&gt;text&lt;/typeOfResource&gt;\r
47                 &lt;originInfo&gt;\r
48                         &lt;place&gt;\r
49                                 &lt;code authority="marc"&gt;xx&lt;/c0de&gt;\r
50                         &lt;/place&gt;\r
51                         &lt;publisher&gt;Award Publications&lt;/publisher&gt;\r
52                         &lt;dateIssued&gt;c1982, 1983&lt;/dateIssued&gt;\r
53                         &lt;dateIssued encoding="marc" point="start"&gt;1983&lt;/dateIssued&gt;\r
54                         &lt;dateIssued encoding="marc" point="end"&gt;1982&lt;/dateIssued&gt;\r
55                         &lt;issuance&gt;monographic&lt;/issuance&gt;\r
56                         &lt;/originInfo&gt;\r
57                 &lt;language authority="iso639-2b"&gt;eng&lt;/language&gt;\r
58                 &lt;physicalDescription&gt;\r
59                         &lt;form authority="marcform"&gt;print&lt;/form&gt;\r
60                         &lt;extent&gt;unp. : col. ill.&lt;/extent&gt;\r
61                 &lt;/physicalDescription&gt;\r
62                 &lt;note type="statement of responsibility"&gt;ill. by Rene Cloke.&lt;/note&gt;\r
63                 &lt;subject authority="lcsh"&gt;\r
64                         &lt;topic&gt;Animals&lt;/topic&gt;\r
65                         &lt;topic&gt;Fiction&lt;/topic&gt;\r
66                 &lt;/subject&gt;\r
67                 &lt;subject authority="lcsh"&gt;\r
68                         &lt;topic&gt;Fables&lt;/topic&gt;\r
69                 &lt;/subject&gt;\r
70                 &lt;recordInfo&gt;\r
71                         &lt;recordContentSource&gt;(BRO)&lt;/recordContentSource&gt;\r
72                         &lt;recordCreationDate encoding="marc"&gt;930903&lt;/recordCreationDate&gt;\r
73                         &lt;recordChangeDate encoding="iso8601"&gt;19990703024637.0&lt;/recordChangeDate&gt;\r
74                         &lt;recordIdentifier&gt;PIN60000007 &lt;/recordIdentifier&gt;\r
75                 &lt;/recordInfo&gt;\r
76         &lt;/mods:mods&gt;\r
77 &lt;/mods:modsCollection&gt;\r
78 </screen>\r
79          </simplesect>\r
80          <simplesect>\r
81                 <title>Return a feed of recently edited or created records</title>\r
82                 <para>SuperCat can return feeds of recently edited or created authority and bibliographic records:</para>\r
83                 <para><uri>http://&lt;hostname&gt;/opac/extras/feed/freshmeat/&lt;feed-type&gt;/[authority|biblio]/[import|edit]/&lt;limit&gt;/&lt;date&gt;</uri></para>\r
84                 <para>The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.</para>\r
85                 <para>If you do not supply a limit, then up to 10 records will be returned.</para>      \r
86                 <para>Feed-type can be one of atom, html, htmlholdings, marcxml, mods, mods3, or rss2.</para>           \r
87                 <para><uri>For example, http://dev.gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01</uri></para>\r
88         </simplesect>\r
89          <simplesect>\r
90                 <title>Browse records</title>\r
91                 <para>SuperCat can browse records in HTML and XML formats:</para>\r
92                 <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/browse/&lt;format&gt;/call_number/&lt;org_unit&gt;/&lt;call_number&gt;</uri></para>\r
93                 <para>For example, <uri>http://dev.gapines.org/opac/extras/browse/xml/call_number/-/GV</uri> returns:</para>\r
94 <screen>\r
95 &lt;hold:volumes xmlns:hold='http://open-ils.org/spec/holdings/v1'&gt;\r
96         &lt;hold:volume id="tag:open-ils.org,2008:asset-call_number/130607" lib="FRRLS-FA" label="GUTCHEON BETH"&gt;\r
97                 &lt;act:owning_lib id="tag:open-ils.org,2008:actor-org_unit/111" name="Fayette County Public Library"/&gt;\r
98                 &lt;record xsi:schemaLocation="http://www.loc.gov/MARC21/slim http://www.loc.gov/ \r
99                         standards/marcxml/schema/MARC21slim.xsd"\r
100                         id="tag:open-ils.org,2008:biblio-record_entry/21669/FRRLS-FA"&gt;\r
101                         &lt;leader&gt;09319pam a2200961 a 4500&lt;/leader&gt;\r
102                         &lt;controlfield tag="001"/&gt;\r
103                         &lt;controlfield tag="005"&gt;20000302124754.0&lt;/controlfield&gt;\r
104                         &lt;controlfield tag="008"&gt;990817s2000    nyu           000 1 eng  &lt;/controlfield&gt;\r
105                         &lt;datafield tag="010" ind1=" " ind2=" "&gt;\r
106                                 &lt;subfield code="a"&gt;   99045936&lt;/subfield&gt;\r
107                         &lt;/datafield&gt;\r
108                         ..\r
109                 &lt;/record&gt;\r
110                 &lt;record&gt;\r
111                         ..\r
112                 &lt;/record&gt;\r
113         &lt;/hold:volume&gt;\r
114 &lt;/hold:volumes&gt;   \r
115 </screen>\r
116         </simplesect>\r
117          <simplesect xml:id="supportedsupercatformats">\r
118                 <title>Supported formats</title>\r
119                 <para>SuperCat maintains a list of supported formats for records and metarecords:</para>\r
120                 <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/formats/&lt;record-type&gt;</uri></para>\r
121                 <para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/formats/record</uri> returns:</para>\r
122 <screen>\r
123 &lt;formats&gt;\r
124 \r
125   &lt;format&gt;\r
126     &lt;name&gt;opac&lt;/name&gt;\r
127     &lt;type&gt;text/html&lt;/type&gt;\r
128   &lt;/format&gt;\r
129 \r
130   &lt;format&gt;\r
131     &lt;name&gt;htmlholdings&lt;/name&gt;\r
132     &lt;type&gt;text/html&lt;/type&gt;\r
133   &lt;/format&gt;\r
134  \r
135   &lt;format&gt;\r
136     &lt;name&gt;html&lt;/name&gt;\r
137     &lt;type&gt;text/html&lt;/type&gt;\r
138   &lt;/format&gt;\r
139  \r
140   &lt;format&gt;\r
141     &lt;name&gt;htmlholdings-full&lt;/name&gt;\r
142     &lt;type&gt;text/html&lt;/type&gt;\r
143   &lt;/format&gt;\r
144  \r
145   &lt;format&gt;\r
146     &lt;name&gt;html-full&lt;/name&gt;\r
147     &lt;type&gt;text/html&lt;/type&gt;\r
148   &lt;/format&gt;\r
149  \r
150   &lt;format&gt;\r
151     &lt;name&gt;marcxml&lt;/name&gt;\r
152     &lt;type&gt;application/xml&lt;/type&gt;\r
153     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
154     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
155  \r
156     &lt;schema_location&gt;\r
157     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
158     &lt;/schema_location&gt;\r
159   &lt;/format&gt;\r
160  \r
161   &lt;format&gt;\r
162     &lt;name&gt;marcxml-full&lt;/name&gt;\r
163     &lt;type&gt;application/xml&lt;/type&gt;\r
164     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
165     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
166  \r
167     &lt;schema_location&gt;\r
168     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
169     &lt;/schema_location&gt;\r
170   &lt;/format&gt;\r
171  \r
172   &lt;format&gt;\r
173     &lt;name&gt;rss2&lt;/name&gt;\r
174     &lt;type&gt;application/xml&lt;/type&gt;\r
175   &lt;/format&gt;\r
176  \r
177   &lt;format&gt;\r
178     &lt;name&gt;rss2-full&lt;/name&gt;\r
179     &lt;type&gt;application/xml&lt;/type&gt;\r
180   &lt;/format&gt;\r
181  \r
182   &lt;format&gt;\r
183     &lt;name&gt;rdf_dc&lt;/name&gt;\r
184     &lt;type&gt;application/xml&lt;/type&gt;\r
185     &lt;namespace_uri&gt;http://purl.org/dc/elements/1.1/&lt;/namespace_uri&gt;\r
186     &lt;schema_location&gt;http://purl.org/dc/elements/1.1/&lt;/schema_location&gt;\r
187   &lt;/format&gt;\r
188  \r
189   &lt;format&gt;\r
190     &lt;name&gt;oai_dc&lt;/name&gt;\r
191     &lt;type&gt;application/xml&lt;/type&gt;\r
192     &lt;namespace_uri&gt;http://www.openarchives.org/OAI/2.0/oai_dc/&lt;/namespace_uri&gt;\r
193     &lt;schema_location&gt;http://www.openarchives.org/OAI/2.0/oai_dc.xsd&lt;/schema_location&gt;\r
194   &lt;/format&gt;\r
195  \r
196   &lt;format&gt;\r
197     &lt;name&gt;srw_dc&lt;/name&gt;\r
198     &lt;type&gt;application/xml&lt;/type&gt;\r
199     &lt;namespace_uri&gt;info:srw/schema/1/dc-schema&lt;/namespace_uri&gt;\r
200  \r
201     &lt;schema_location&gt;\r
202     http://www.loc.gov/z3950/agency/zing/srw/dc-schema.xsd\r
203     &lt;/schema_location&gt;\r
204   &lt;/format&gt;\r
205  \r
206   &lt;format&gt;\r
207     &lt;name&gt;mods32&lt;/name&gt;\r
208     &lt;type&gt;application/xml&lt;/type&gt;\r
209     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
210     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
211     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-2.xsd&lt;/schema_location&gt;\r
212   &lt;/format&gt;\r
213  \r
214   &lt;format&gt;\r
215     &lt;name&gt;mods3&lt;/name&gt;\r
216     &lt;type&gt;application/xml&lt;/type&gt;\r
217     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
218     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
219     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
220   &lt;/format&gt;\r
221  \r
222   &lt;format&gt;\r
223     &lt;name&gt;mods3-full&lt;/name&gt;\r
224     &lt;type&gt;application/xml&lt;/type&gt;\r
225     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
226     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
227     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
228   &lt;/format&gt;\r
229  \r
230   &lt;format&gt;\r
231     &lt;name&gt;mods&lt;/name&gt;\r
232     &lt;type&gt;application/xml&lt;/type&gt;\r
233     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
234     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
235     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
236   &lt;/format&gt;\r
237  \r
238   &lt;format&gt;\r
239     &lt;name&gt;mods-full&lt;/name&gt;\r
240     &lt;type&gt;application/xml&lt;/type&gt;\r
241     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
242     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
243     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
244   &lt;/format&gt;\r
245  \r
246   &lt;format&gt;\r
247     &lt;name&gt;atom&lt;/name&gt;\r
248     &lt;type&gt;application/xml&lt;/type&gt;\r
249     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
250     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
251   &lt;/format&gt;\r
252  \r
253   &lt;format&gt;\r
254     &lt;name&gt;atom-full&lt;/name&gt;\r
255     &lt;type&gt;application/xml&lt;/type&gt;\r
256     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
257     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
258   &lt;/format&gt;\r
259 &lt;/formats&gt;\r
260 </screen>\r
261         </simplesect>\r
262         <simplesect>\r
263                 <title>Adding new SuperCat formats</title>      \r
264                 <para>SuperCat web services are based on the OpenSRF service, <systemitem class="service">>open-ils.supercat</systemitem>.</para> \r
265                 <para>Developers are able to add new formats by adding the <emphasis>xsl</emphasis> \r
266                 stylesheet for the format in the directory<filename class="directory">/openils/var/web/opac/extras/xsl/</filename>, and by adding the feed references to the perl modules \r
267                 <filename>openils/lib/perl5/OpenILS/WWW/SuperCat/feed.pm</filename> and <filename>openils/lib/perl5/OpenILS/WWW/SuperCat.pm</filename>. An Evergreen restart is \r
268                 required for the new format to be activated.</para>\r
269                 <tip><para>Use an existing xsl stylesheet and perm module entry as a guide for your new format.</para></tip>\r
270         </simplesect>\r
271 </chapter>\r
272 \r