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 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 These are the search keywords requested by the user. :sources 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 ) :relevant-documents 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 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 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 The positioning of the question editing window (if there is one) in machine dependent units. It is of the form (:rect :left :top :right :bottom ) Document-id Structure Definition: -------------------------------- (:document-id :score :start :end :document ) (:fragment either :byte-pos or :line-pos or :para-id ) (:document :headline :doc-id :source :number-of-lines :number-of-bytes :best-line :type :date ) (:doc-id :original-server :original-database :original-local-id :distributor-server :distributor-database :distributor-local-id :copyright-disposition )