Question Description Structures

                       Harry Morris morris@think.com
		    Jonathan Goldman jonathan@think.com
				  3/2/91


A "question description structure" is used by a client of the WAIS system
to pose a query to a WAIS server.  This document describes a text encoding
of the question description structure.  This specification is compatible
with the clients that are given out with the WAIS release (version 8 and
higher).  Example C code to read and write these structures is available
free of charge from the authors.

Note that WAIS end users should never see this structure, since a typical
user will use the questions created by a client, and interact with them
through a client user interface.

Philosophy: -----------

Questions are the basic way a user interacts with a WAIS server.  We have
found it useful to store the current state of a particular interaction
(hereafter referred to simply as the question), so that it may be used
later, either by the user explicitly, or by a smart client to submit
requests to the server automatically.

The other fields are strictly optional.  Clients may choose to let the user
store additional parameters in questions (eg. how to display the question).
While not all clients may want or need all the optional fields, it is in
everyone's best interest to have any particular function expressed in a
single format that all can share.  The optional fields presented here are
ones we have found useful.  If you have suggestions for fields that should
be added to the specification, please contact the authors.

Clients and servers should always be prepared to ignore the non-required
fields.

Question structure have four basic parts:

1.  The search words upon which the question is based
2.  The sources to search
3.  Some documents that might be similar to the desired results.
4.  The resulting documents as returned from the sources.
5.  Optional fields

An example of a question structure:

(:question 
 :version  1 
 :seed-words "how do I use the wais system?"
 :relevant-documents (  ) 
 :sources 
 ( (:source-id 
    :filename "wais-docs" ) 
   (:source-id
    :filename "CMNS")
 ) 
 :result-documents  (  ) 
) 

The first symbol in the structure must be :question, as this identifies the
structure.  The rest of the symbols may appear in any order.  They are:


Syntax:
------

See the syntax discussion in source.txt


Fields:
------

:version <integer>  
The number is the major version number of the question structure format.
The current version is 2.  This must be the first slot.

:seed-words <string>
These are the search keywords requested by the user.

:sources  <list>
A (possibly empty) list of source-id structures.  Source-ids identify the
sources which the question will use.  They point to a file containing a
source structure (see source.txt).  They are defined as:

	(:source-id
	 	:filename <string>
	)

:relevant-documents <list>
A (possibly empty) list of document-id structures.  They are documents
which the user has selected as "relevant" to the query.  Some servers can
use the information contained in relevant documents to drastically improve
search performance.  They are defined below.

:result-documents <list>
Another (possibly empty) list of document-id structures.  These constitute
the answers provided to the question by the server(s) it refers to.

:sort-results-by <sort-type>
A hint to the client as to how to sort the result documents for display.
Sort-type is one of

	:score 
	:date
	:source - alphabetically

:window-geometry  <rect>
The positioning of the question editing window (if there is one) in machine
dependent units.  It is of the form
	
	(:rect  
		:left	<integer>
		:top  	<integer>  
		:right  <integer>  
		:bottom <integer>
		) 


Document-id Structure Definition:
--------------------------------


(:document-id
	:score			<integer>
	:start			<fragment>
	:end			<fragment>
	:document 		<document>
	)

(:fragment
	either
	:byte-pos		<integer>
	or
	:line-pos		<integer>
	or
	:para-id		<integer>
	)

(:document
	:headline 		<string>
	:doc-id 		<doc-id>
	:source 		<source-id>
	:number-of-lines 	<integer>
	:number-of-bytes 	<integer>
	:best-line 		<integer>
	:type 			<string>
	:date 			<string>
	)

(:doc-id
	:original-server	<any>
	:original-database	<any>
	:original-local-id 	<any>
	:distributor-server	<any>
	:distributor-database	<any>
	:distributor-local-id 	<any>
	:copyright-disposition  <number> 
	)