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