CGI parameters to Omega
=======================

In addition to the parameters listed here, all other parameters are
retained. Arbitrary CGI parameters may be read with the $cgi{PARAM}
and $cgilist{PARAM} OmegaScript commands.

Note that all CGI parameters are modified by Omega before they become
part of $cgilist{} - see the section at the end for details.

Main query parameters
---------------------

DB
	database name (give multiple values to search over several
	databases) each DB value may be a list of database names
	separated by "/".

xDB
	database(s) used for last query (separated by / if appropriate).
	If the database(s) used change then relevance judgements are
	discarded and the first page of matches is shown.

DEFAULTOP
	default operator - values recognised "AND", "and", "OR", "or".
	Default: OR.  If you want to implement "match all words", set
	DEFAULTOP=AND.

P
	probabilistic query (may occur multiple times).

xP
	terms from previous probabilistic query - used to decide if
	this is a fresh query (in which case relevance judgements are
	discarded and the first page of matches is shown), an extended query
	(in which case the first page of matches is shown), or an unchanged
	query.

ADD
	if present, any X parameters are added to the probabilistic
	query (used for topterms support when javascript isn't
	supported or is disabled).

X
	topterms to add to query.

R
	relevant document(s) (multiple values separated by ".")

MORELIKE
	value is a document id to return similar pages to, or a term name
	(which will be looked up and the document id of the first document it
	indexes will be used - this allows a MORELIKE query based on the
	unique id from an external database)

RAWSEARCH
	when set to non-zero value, this prevents TOPDOC being snapped to a
	multiple of HITSPERPAGE.  Normally we snap TOPDOC like this so that
	things work nicely if HITSPERPAGE is in a picker or on radio buttons.
	If we're postprocessing the output of omega and want variable sized
	pages, this is unhelpful.  (Alternative deprecated spelling is
	RAW_SEARCH).

MINHITS
	can be set to look for more matches than would otherwise be looked for
	to you can be sure how many more consecutive pages will definitely be
	needed to show results.  By default omega asks for one hit more than
	the last one displayed on this page (so we know for sure if there is a
	next page or not).  If MINHITS is set, we ask for at least MINHITS
	matches from the start of the current page - you can think of MINHITS
	as defaulting to (HITSPERPAGE + 1).  (Alternative deprecated spelling
	is MIN_HITS).

Filtering parameters
--------------------

B
	general boolean filter terms.  See overview.txt for details of how
	multiple B parameters are handled.

COLLAPSE
	value number to use for removing duplicate documents.
	Additional documents in the mset with the same value will be
	removed from the mset. $value{$cgi{COLLAPSE}} can be used to
	access the actual value for each hit.

SPAN
	filter on this number of days up to END (if set), or after
	START (if set), or before today's date (otherwise).
	
START
	start of date range, in the format YYYYMMDD (defaults to 1st January
	1970).

END
	end of date range, in the format YYYYMMDD (defaults to today's date).

	The old deprecated names are DATE1 (START), DATE2 (END), and
	DAYSMINUS (SPAN) which for now are checked if the new variables
	aren't present.  The semantics of DAYSMINUS are slightly different
	- DAYSMINUS is always days before DATE1 or now (whereas SPAN is
	days after START, before END, or before today's date).

xFILTERS
	used to spot when the filters have changed from the previous search.
	Set this to $html{$filters} in your query template ($filters is a
	compact serialisation of the currently set B filters, date-range
	filters, COLLAPSE, and DEFAULTOP).

THRESHOLD
	apply a percentage cut-off at the value given by this parameter
	(clipped to the range 0-100).

Reordering parameters
---------------------

SORT
	reorder results by this value number (greater values are better).
	The comparison used is a string compare.

SORTREVERSE
	if non-zero, reverse the sort order so that lower values are better.

Display parameters and navigation
---------------------------------

FMT
	name of page format to use (a-z only).

HITSPERPAGE
	hits per page (integer) - clipped to range 10-1000.

TOPDOC
	first document to display (snapped to multiple of HITSPERPAGE
	if RAWSEARCH is not set)

If a parameter named '<' or '>' exists, Omega will go to the previous
or next results page (based on the value of TOPDOC), respectively. If
not, and a parameter named '[' or '#' exists, it will jump to the page
number given by that parameter (trailing junk after the number is
ignored). (See the section below on modification of CGI parameters to
see how this works.)

This means that <input type='image' .../> forms buttons can have names
of the form '[ 3 ]', which looks nice in lynx, for tooltips, and so
on. For text-only links, you really need to write out the entire GET
parameters and use a normal anchor.

Match Bias Functor
------------------

Note: this is a temporary bodge to allow experimentation with
Xapian::BiasFunctor.

bias_weight
	if set, enable the Xapian::BiasFunctor with max_weight "bias_weight".

bias_halflife
	optionally set the halflife of the bias (default is 2 days).  Has no
	effect unless bias_weight is also set.

Modification of CGI parameters
------------------------------

For an image button, two CGI parameters are passed from the HTML
client, of the form "PARAM.x" and "PARAM.y" (the x and y coordinates
within the image that were clicked).

The PARAM part of the parameters are taken from the value attribute of
the <input> element that specified that image button in the HTML
page. We regularly use image buttons to provide pretty navigation
within search results (they are part of a form because it is easier to
treat more or less all of Omega as a single form, rather than
generating very long GET requests for every button on the results
page), so Omega does some mangling of these parameters:

 * PARAM.y is silently dropped
 * PARAM.x is truncated to PARAM
 * if PARAM contains a space (the CGI parameter name, not the value):
    * the value becomes everything after the first space; the
      original value is dropped. (eg: [ 2 ].x=NNN becomes [=2 ])

   otherwise:
    * if PARAM is entirely numeric, the name becomes '#' and the value
      becomes PARAM. (eg: 2.x=NNN becomes #=2)
    * if PARAM is not entirely numeric, the value is copied from PARAM
      (eg: >.x=NNN becomes >=>)

Then, for ALL CGI parameters, the name is truncated at the first
space. So [ page two ]=2 becomes [=2.
