% SiSU insert 2.0

@title: SiSU
 :subtitle: Search

@creator:
 :author: Ralph Amissah

@date:
 :published: 2007-09-16
 :created: 2002-08-28
 :issued: 2002-08-28
 :available: 2002-08-28
 :modified: 2011-02-07

@rights:
 :copyright: Copyright (C) Ralph Amissah 2007
 :license: GPL 3 (part of SiSU documentation)

:A~? @title @creator

:B~? SiSU Search

:C~? CGI Search Form

1~search_cgi CGI Search Form
={ SiSU sql:cgi search form; SiSU search:cgi search form;search form }

For the search form, which is a single search page

_* configure the search form

_* generate the sample search form with the sisu command, (this will be based on the configuration settings and existing found sisu databases)

For postgresql web content you may need to edit the search cgi script. Two things to look out for are that the user is set as needed, and that the any different databases that you wish to be able to query are listed.

correctly, you may want www-data rather than your username.

``` code
@user='www-data'
```

_* check the search form, copy it to the appropriate cgi directory and set the correct permissions

For a search form to appear on each html page, you need to:

_* rely on the above mentioned configuration of the search form

_* configure the html search form to be on

_* run the html command

2~ Setup search form

You will need a web server, httpd with cgi enabled, and a postgresql database to which you are able to create databases.

Setup postgresql, make sure you are able to create and write to the database, e.g.:

``` code
sudo su postgres
  createuser -d -a ralph
```

You then need to create the database that sisu will use, for sisu manual in the directory manual/en for example, (when you try to populate a database that does not exist sisu prompts as to whether it exists):

``` code
createdb SiSU.7a.manual
```

SiSU is then able to create the required tables that allow you to populate the database with documents in the directory for which it has been created:

``` code
sisu --pg --createall -v
```

You can then start to populate the database, in this example with a single document:

``` code
sisu --pg --update -v en/sisu_manual.ssm
```

To create a sample search form, from within the same directory run:

``` code
sisu --sample-search-form --db-pg
```

and copy the resulting cgi form to your cgi-bin directory

A sample setup for nginx is provided that assumes data will be stored under /srv/www and cgi scripts under /srv/cgi

2~ Search - database frontend sample, utilising database and SiSU features, including object citation numbering (backend currently PostgreSQL) *~search

{~^ Sample search frontend }http://search.sisudoc.org
A small database and sample query front-end (search from) that makes use of the citation system, _{object citation numbering}_ to demonstrates functionality.~{ (which could be extended further with current back-end). As regards scaling of the database, it is as scalable as the database (here Postgresql) and hardware allow. }~

SiSU can provide information on which documents are matched and at what locations within each document the matches are found. These results are relevant across all outputs using object citation numbering, which includes html, XML, EPUB, LaTeX, PDF and indeed the SQL database. You can then refer to one of the other outputs or in the SQL database expand the text within the matched objects (paragraphs) in the documents matched.

Note you may set results either for documents matched and object number locations within each matched document meeting the search criteria; or display the names of the documents matched along with the objects (paragraphs) that meet the search criteria.~{ of this feature when demonstrated to an IBM software innovations evaluator in 2004 he said to paraphrase: this could be of interest to us. We have large document management systems, you can search hundreds of thousands of documents and we can tell you which documents meet your search criteria, but there is no way we can tell you without opening each document where within each your matches are found. }~

% Several options for output - select database to search, show results in index view (links to locations within text), show results with text, echo search in form, show what was searched, create and show a "canned url" for search, show available search fields. Also shows counters number of documents in which found and number of locations within documents where found. [could consider sorting by document with most occurrences of the search result].

!_ sisu -F --webserv-webrick \\
builds a cgi web search frontend for the database created

The following is feedback on the setup on a machine provided by the help command:

_1 sisu --help sql

code{

Postgresql
  user:             ralph
  current db set:   SiSU_sisu
  port:             5432
  dbi connect:      DBI:Pg:database=SiSU_sisu;port=5432

sqlite
  current db set:   /home/ralph/sisu_www/sisu/sisu_sqlite.db
  dbi connect       DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db

}code

Note on databases built

By default, [unless otherwise specified] databases are built on a directory basis, from collections of documents within that directory. The name of the directory you choose to work from is used as the database name, i.e. if you are working in a directory called /home/ralph/ebook the database SiSU_ebook is used. [otherwise a manual mapping for the collection is necessary]

2~ Search Form

!_ sisu -F \\
generates a sample search form, which must be copied to the web-server cgi directory

!_ sisu -F --webserv-webrick \\
generates a sample search form for use with the webrick server, which must be copied to the web-server cgi directory

!_ sisu -W \\
starts the webrick server which should be available wherever sisu is properly installed

The generated search form must be copied manually to the webserver directory as instructed
