Complete scan documentation.

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 8658115..00e5aca 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.14 2005-12-13 11:26:19 mike Exp $
+# $Id: ZOOM.pod,v 1.15 2005-12-13 12:32:15 mike Exp $
 
 use strict;
 use warnings;
@@ -247,27 +247,9 @@ Objects of the Connection, ResultSet, ScanSet and Package classes
 carry with them a set of named options which affect their behaviour in
 certain ways.  See the ZOOM-C options documentation for details:
 
-=over 4
-
-=item *
-
 Connection options are listed at
 http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
 
-=item *
-
-ScanSet options are listed at
-http://indexdata.com/yaz/doc/zoom.scan.tkl
-I<### move this observation down to the appropriate place>
-
-=item *
-
-Package options are listed at
-http://indexdata.com/yaz/doc/zoom.ext.html
-I<### move this observation down to the appropriate place>
-
-=back
-
 These options are set and fetched using the C<option()> method, which
 may be called with either one or two arguments.  In the two-argument
 form, the option named by the first argument is set to the value of
@@ -424,7 +406,7 @@ http://zoom.z3950.org/api/zoom-current.html#3.4
 
 =head4 option()
 
- $conn->option(elementSetName => "f");
+ $rs->option(elementSetName => "f");
 
 Allows options to be set into, and read from a ResultSet, just like
 the Connection class's C<option()> method.  There is no
@@ -439,7 +421,7 @@ http://indexdata.com/yaz/doc/zoom.resultsets.tkl
 
 Returns the number of records in the result set.
 
-=head4 record(), record_immediate()
+=head4 record() / record_immediate()
 
  $rec = $rs->record(0);
  $rec2 = $rs->record_immediate(0);
@@ -726,25 +708,60 @@ http://zoom.z3950.org/api/zoom-current.html#3.6
 
  print "Found ", $ss->size(), " terms\n";
 
-Returns the number of terms in the scan set.
-### describe option that affects this.
+Returns the number of terms in the scan set.  In general, this will be
+the scan-set size requested by the C<number> option in the Connection
+on which the scan was performed [default 10], but it may be fewer if
+the scan is close to the end of the index.
 
 =head4 term() / display_term()
 
-I<###>
+ $ss = $conn->scan('@attr 1=1004 whatever');
+ ($term, $occurrences) = $ss->term(0);
+ ($displayTerm, $occurrences2) = $ss->display_term(0);
+ assert($occurrences == $occurrences2);
+ if (user_likes_the_look_of($displayTerm)) {
+     $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
+     assert($rs->size() == $occurrences);
+ }
+
+These methods return the scanned terms themselves.  C<term()> returns
+the term is a form suitable for submitting as part of a query, whereas
+C<display_term()> returns it in a form suitable for displaying to a
+user.  Both versions also return the number of occurrences of the term
+in the index, i.e. the number of hits that will be found if the term
+is subsequently used in a query.
+
+In most cases, the term and display term will be identical; however,
+they may be different in cases where punctuation or case is
+normalised, or where identifiers rather than the original document
+terms are indexed.
 
 =head4 option()
 
-I<###>
+ print "scan status is ", $ss->option("scanStatus");
+
+Allows options to be set into, and read from a ScanSet, just like
+the Connection class's C<option()> method.  There is no
+C<option_binary()> method for ScanSet objects.
+
+ScanSet options are also described, though not particularly
+informatively, at
+http://indexdata.com/yaz/doc/zoom.scan.tkl
 
 =head4 destroy()
 
-I<###>
+ $ss->destroy()
+
+Destroys a ScanSet object, freeing its resources.  It is an error to
+reuse a ScanSet that has been C<destroy()>ed.
 
 =head2 ZOOM::Package
 
 I<###>
 
+Package options are listed at
+http://indexdata.com/yaz/doc/zoom.ext.html
+
 =head2 ZOOM::Query
 
 I<###>