Using search front-ends
=======================


Doing search
------------

Open your prefered frontend in Web browser:
http://your.web.server/path/to/search.cgi
or
http://your.web.server/path/to/search.php3
or
http://your.web.server/path/to/search.pl


To find something just type words you want to find and press SUBMIT button.
For example, "mysql odbc". You should not use quotes " in query,
they are written here only to divide a query from other text. UdmSearch
will find all documents that contain word "mysql" and/or word "odbc". 
Best documents having bigger weights will be displayed first.


Search parameters
-----------------

UdmSearch frontends support the following parameters given in CGI query 
string. You may use them in HTML form on search page.

q	text parameter with search query
ps	page size, number of search results displayed on one page,
	20 by default. Maximum page size is 100. This value does
	not allow to pass very big page sizes to avoid server overload
	and might be changed with MAX_PS definition in search.c.
np	page number, 0 by default (first page)
m	search mode. Currently "all" and "any" values are supported.
o	search result type. 0 by default. You may describe several template 
	sections for every part, for example "res". This allows to choose
	for example "Long" or "Short" search result output types. Up to 100
	different formats are allowed in the same template.
t	tag limit. Limits search through only documents with given tag.
	This parameter has the same effect with -t indexer option
cat	Category limit. Take a look into "categories.txt" for datails.
ul	URL limit, URL substring to limit search through subsection
	of database. It supports SQL % and _  LIKE wildcards. 
	This parameter has the same effect with -u indexer option.
	By default search.cgi inserts % signs before and after "ul" value.
	It allows to write URL substring in HTML from to limit search,
	for example <OPTION VALUE="/manual/"> instead of VALUE="%/manual/%".
	You may specify --disable-auto-wildcard to configure script
	at installation time to disallow automatic addition of % signs.

	Disabling automatic addition sometimes allow to make search faster.
	For example, specifying whole begining of URL
	<OPTION VALUE="http://www.somewhere.com/manual/%"> allows most 
	of SQL servers to use indexes when executing the query with given 
	value in LIKE expression.


Using different templates
-------------------------

It is often required to use several templates with the same
search.cgi. There are actually several ways to do it. They 
are given here in the order how search.cgi detects template
name. 

1. search.cgi checks environment variable UDMSEARCH_TEMPLATE. So you
can put a path to desired search template into this variable. 

2. search.cgi also supports Apache internal redirect. It checks
REDIRECT_STATUS and REDIRECT_URL environment variables. To activate 
this way of template usage you may add these lines in Apache srm.conf: 

AddType text/html .zhtml
AddHandler zhtml .zhtml
Action zhtml /cgi-bin/search.cgi

Put search.cgi into your /cgi-bin/ directory. Then put HTML template into
your site directory structure under any name with .zthml extension, for
example template.zhtml. Now you may open search page:
http://www.site.com/path/to/template.zhtml You may use any
unused extention insteat of .zthml of course. 

3. If the above two ways fail, search.cgi opens a template which has
the same name with the script being executed using SCRIPT_NAME environment
variable. search.cgi will open a template ETC/search.htm, search1.cgi will
open ETC/search1.htm and so on, where ETC is UdmSearch /etc directory
(usually /usr/local/udmsearch/etc). So, you can use the same search.cgi with
different templates without having to recompile it. Just create
one or several hard or symbolic links for search.cgi or copy it and put
correspondent search templates into /etc directory of UdmSearch installation.



Advanced search with PHP
------------------------
If you want more advanced results and use PHP you can use query language. 
search.cgi does not have advanced search yet. It is on TODO list.
PHP frontend support is currently inmplemented for MySQL, PostgreSQL and 
Oracle databases.


search.php3 understands next boolean operators:

& - logical AND.
For example, "mysql & odbc". UdmSearch will find any URLs that 
contain both "mysql" and "odbc".

| - logical OR. For example "mysql|odbc". It's just the same that "mysql odbc".
Space " " is equal for "|". UdmSearch will find any URLs, that contain
word "mysql" or word "odbc".

~ - logical NOT. For example "mysql & ~odbc". 
UdmSearch will find urls that contain word "mysql" and do not contain
word "odbc" at the same time. Note that ~ just excludes given word from results.
Query "~odbc" will find nothing! UdmSearch compose WHERE condition in
mysql query using all of the words in search query (to make search very quick):
.... WHERE word in ('all','of','the','words','have','been','typed')

() - group command to compose more complex queries.
For example "(mysql | msql) & ~postgres".
Query language is simple and powerful at the same time. Just consider 
query as usual logical expression.

