documentation related to search, needs further review
[software/sisu] / data / doc / sisu / markup-samples / manual / en / sisu_search_cgi.ssi
1 % SiSU insert 2.0
2
3 @title: SiSU
4 :subtitle: Search
5
6 @creator:
7 :author: Ralph Amissah
8
9 @date:
10 :published: 2007-09-16
11 :created: 2002-08-28
12 :issued: 2002-08-28
13 :available: 2002-08-28
14 :modified: 2011-02-07
15
16 @rights:
17 :copyright: Copyright (C) Ralph Amissah 2007
18 :license: GPL 3 (part of SiSU documentation)
19
20 :A~? @title @creator
21
22 :B~? SiSU Search
23
24 :C~? CGI Search Form
25
26 1~search_cgi CGI Search Form
27 ={ SiSU sql:cgi search form; SiSU search:cgi search form;search form }
28
29 For the search form, which is a single search page
30
31 _* configure the search form
32
33 _* generate the sample search form with the sisu command, (this will be based on the configuration settings and existing found sisu databases)
34
35 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.
36
37 correctly, you may want www-data rather than your username.
38
39 ``` code
40 @user='www-data'
41 ```
42
43 _* check the search form, copy it to the appropriate cgi directory and set the correct permissions
44
45 For a search form to appear on each html page, you need to:
46
47 _* rely on the above mentioned configuration of the search form
48
49 _* configure the html search form to be on
50
51 _* run the html command
52
53 2~ Setup search form
54
55 You will need a web server, httpd with cgi enabled, and a postgresql database to which you are able to create databases.
56
57 Setup postgresql, make sure you are able to create and write to the database, e.g.:
58
59 ``` code
60 sudo su postgres
61 createuser -d -a ralph
62 ```
63
64 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):
65
66 ``` code
67 createdb SiSU.7a.manual
68 ```
69
70 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:
71
72 ``` code
73 sisu --pg --createall -v
74 ```
75
76 You can then start to populate the database, in this example with a single document:
77
78 ``` code
79 sisu --pg --update -v en/sisu_manual.ssm
80 ```
81
82 To create a sample search form, from within the same directory run:
83
84 ``` code
85 sisu --sample-search-form --db-pg
86 ```
87
88 and copy the resulting cgi form to your cgi-bin directory
89
90 A sample setup for nginx is provided that assumes data will be stored under /srv/www and cgi scripts under /srv/cgi
91
92 2~ Search - database frontend sample, utilising database and SiSU features, including object citation numbering (backend currently PostgreSQL) *~search
93
94 {~^ Sample search frontend }http://search.sisudoc.org
95 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. }~
96
97 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.
98
99 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. }~
100
101 % 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].
102
103 !_ sisu -F --webserv-webrick \\
104 builds a cgi web search frontend for the database created
105
106 The following is feedback on the setup on a machine provided by the help command:
107
108 _1 sisu --help sql
109
110 code{
111
112 Postgresql
113 user: ralph
114 current db set: SiSU_sisu
115 port: 5432
116 dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
117
118 sqlite
119 current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
120 dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
121
122 }code
123
124 Note on databases built
125
126 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]
127
128 2~ Search Form
129
130 !_ sisu -F \\
131 generates a sample search form, which must be copied to the web-server cgi directory
132
133 !_ sisu -F --webserv-webrick \\
134 generates a sample search form for use with the webrick server, which must be copied to the web-server cgi directory
135
136 !_ sisu -W \\
137 starts the webrick server which should be available wherever sisu is properly installed
138
139 The generated search form must be copied manually to the webserver directory as instructed