Add documentation about facets

[yaz-moved-to-github.git] / doc / tools.xml

diff --git a/doc/tools.xml b/doc/tools.xml
index 9ebc4dd..2d9b62b 100644 (file)
--- a/doc/tools.xml
+++ b/doc/tools.xml
@@ -1020,8 +1020,7 @@ struct ccl_rpn_node *ccl_find_str(CCL_bibset bibset, const char *str,
       </listitem>
       <listitem>
        <para>
-        The parser converts CQL to
-        <ulink url="&url.xcql;">XCQL</ulink>.
+        The parser converts CQL to XCQL.
         XCQL is an XML representation of CQL.
         XCQL is part of the SRU specification. However, since SRU
         supports CQL only, we don't expect XCQL to be widely used.
@@ -1235,8 +1234,8 @@ int cql_transform_buf(cql_transform_t ct,
       If conversion failed, <function>cql_transform_buf</function>
       returns a non-zero SRU error code; otherwise zero is returned
       (conversion successful).  The meanings of the numeric error
-      codes are listed in the SRU specifications at
-      <ulink url="&url.sru.diagnostics.list;"/>
+      codes are listed in the SRU specification somewhere (no
+      direct link anymore).
      </para>
      <para>
       If conversion fails, more information can be obtained by calling
@@ -2006,6 +2005,7 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
     #define YAZ_MARC_XCHANGE   5
     #define YAZ_MARC_CHECK     6
     #define YAZ_MARC_TURBOMARC 7
+    #define YAZ_MARC_JSON      8
 
     /* supply iconv handle for character set conversion .. */
     void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
@@ -2099,6 +2099,15 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>YAZ_MARC_JSON</term>
+      <listitem>
+       <para>
+        <ulink url="&url.marc_in_json;">MARC-in_JSON</ulink> format.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </para>
    <para>
@@ -2329,8 +2338,9 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
            <listitem>
             <para>
              Format of input. Supported values are
-            <literal>marc</literal> (for ISO2709); and <literal>xml</literal>
-             for MARCXML/MarcXchange.
+             <literal>marc</literal> (for ISO2709), <literal>xml</literal>
+             (MARCXML/MarcXchange) and <literal>json</literal>
+             (<ulink url="&url.marc_in_json;">MARC-in_JSON</ulink>).
             </para>
            </listitem>
           </varlistentry>
@@ -2339,10 +2349,12 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
            <listitem>
             <para>
              Format of output. Supported values are
-            <literal>line</literal> (MARC line format);
-            <literal>marcxml</literal> (for MARCXML),
-            <literal>marc</literal> (ISO2709),
-            <literal>marcxhcange</literal> (for MarcXchange).
+             <literal>line</literal> (MARC line format);
+             <literal>marcxml</literal> (for MARCXML),
+             <literal>marc</literal> (ISO2709),
+             <literal>marcxhcange</literal> (for MarcXchange),
+             or <literal>json</literal>
+             (<ulink url="&url.marc_in_json;">MARC-in_JSON </ulink>).
             </para>
            </listitem>
           </varlistentry>
@@ -2511,7 +2523,7 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
     </para>
    </sect2>
   </sect1>
-  <sect1><title>Sorting</title>
+  <sect1 id="sorting"><title>Sorting</title>
    <para>
     This chapter describes sorting and how it is supported in YAZ.
     Sorting applies to a result-set.
@@ -2585,6 +2597,83 @@ int cql_transform_rpn2cql_wrbuf(cql_transform_t ct,
     </para>
    </sect2>
   </sect1>
+  <sect1 id="facets"><title>Facets</title>
+  <para>
+   YAZ supports facets for in Solr, SRU 2.0 and Z39.50 protocols.
+  </para>
+  <para>
+   Like Type-1/RPN, YAZ supports a string notation for specifying
+   facets. For the API this is performed by
+   <function>yaz_pqf_parse_facet_list</function>.
+  </para>
+  <para>
+   For ZOOM C the facets are given by option "facets"
+   For yaz-client it is used for the facets command.
+  </para>
+  <para>
+   The grammar of this specification is as follows:
+   <literallayout>
+   facet-spec ::= facet-list
+
+   facet-list ::= facet-list ',' attr-spec | attr-spec
+
+   attr-spec ::= attr-spec '@attr' string | '@attr' string
+
+   </literallayout>
+    The notation is inspired by PQF. The string following '@attr'
+    may not include blanks and is of the form
+    <replaceable>type</replaceable><literal>=</literal><replaceable>value</replaceable>,
+    where <replaceable>type</replaceable> is an integer and
+    <replaceable>value</replaceable> is a string or an integer.
+  </para>
+  <para>
+   The Facets specification is not Bib-1. The following types apply:
+  </para>
+   <table id="facet.attributes">
+     <title>Facet attributes</title>
+       <tgroup cols="2">
+        <colspec colwidth="2*" colname="type"></colspec>
+        <colspec colwidth="9*" colname="description"></colspec>
+        <thead>
+         <row>
+          <entry>Type</entry>
+          <entry>Description</entry>
+         </row>
+        </thead>
+        <tbody>
+         <row>
+          <entry>1</entry>
+          <entry>
+            Field-name. This is often a string, eg "Author", "Year", etc.
+          </entry>
+         </row>
+
+         <row>
+          <entry>2</entry>
+          <entry>
+            Sort order. Value should be an integer.
+            Value 0: count descending (frequency). Value 1: alpha ascending.
+          </entry>
+         </row>
+
+         <row>
+          <entry>3</entry>
+          <entry>
+            Number of terms requested.
+          </entry>
+         </row>
+
+         <row>
+          <entry>4</entry>
+          <entry>
+            Start offset.
+          </entry>
+         </row>
+
+         </tbody>
+         </tgroup>
+       </table>
+  </sect1>
  </chapter>
 
  <!-- Keep this comment at the end of the file