documentation related to search, needs further review
authorRalph Amissah <ralph@amissah.com>
Tue, 15 Dec 2015 04:09:14 +0000 (23:09 -0500)
committerRalph Amissah <ralph@amissah.com>
Tue, 15 Dec 2015 05:01:37 +0000 (00:01 -0500)
data/doc/sisu/CHANGELOG_v7
data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
man/man1/sisu.1

index 520a2cd62d136839dcdac744f54f4f598df4bb2a..7be988695e586cc1f469d6113c1478ae51f1b7a5 100644 (file)
@@ -29,6 +29,8 @@ Reverse Chronological:
        (revisit tic block markup, improperly impmented)
     *  sisu-mode-autoloads.el, added (see elpa 3.0.3 & Kevin Ryde recent post)
 
+  * documentation related to search, needs further review
+
 * sisu_7.1.5.orig.tar.xz (2015-06-02:22/2)
   http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_7.1.5
 
index 9641bea61ac9dccbf9250c1acb5502190bfff813..6197daf035416dfb1fac76240fa662d21f3990c7 100644 (file)
 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.
@@ -40,7 +64,7 @@ sudo su postgres
 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 SiSUv6a_manual
+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:
index 1969c1a4999980794b9ab9862df11c683e3a1c82..1ae5ca1620a80090fbf8eb955b6a123fd46fdeef 100644 (file)
 1~search_intro SiSU Search - Introduction
 ={ SiSU search }
 
-SiSU output can easily and conveniently be indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier.
-
 Because the document structure of sites created is clearly defined, and the text object citation system is available hypothetically at least, for all forms of output, it is possible to search the sql database, and either read results from that database, or map the results to the html or other output, which has richer text markup.
 
 SiSU can populate a relational sql type database with documents at an object level, including objects numbers that are shared across different output types. Making a document corpus searchable with that degree of granularity. Basically, your match criteria is met by these documents and at these locations within each document, which can be viewed within the database directly or in various output formats.
 
+SiSU can populate an sql database (sqlite3 or postgresql) with documents made up of their objects. It also can generate a cgi search form that can be used to query the database.
+
+In order to use the built in search functionality you would take the following steps.
+
+_* use sisu to populate an sql database with with a sisu markup content
+
+_1* sqlite3 should work out of the box
+
+_1* postgresql may require some initial database configuration
+
+_* provide a way to query the database, which sisu can assist with by
+
+_1* generating a sample ruby cgi search form, required (sisu configuration recommended)
+
+_1* adding a query field for this search form to be added to all html files (sisu configuration required)
index 771d300140e534c956e547318b2da06b2423e7c2..4b4866ec851991ccf2a6a8d76e5ae2a99fbc3842 100644 (file)
 :C~? Search
 
 1~search_sql SQL
-
-2~ populating SQL type databases
 ={ SiSU sql; SiSU search }
 
-SiSU feeds sisu markupd documents into sql type databases PostgreSQL~{ http://www.postgresql.org/ \\ http://advocacy.postgresql.org/ \\ http://en.wikipedia.org/wiki/Postgresql }~ and/or SQLite~{ http://www.hwaci.com/sw/sqlite/ \\ http://en.wikipedia.org/wiki/Sqlite }~ database together with information related to document structure.
+2~ Populate the database
+={ SiSU search:populate database }
+
+TO populate the sql database, run sisu against a sisu markup file with one of the following sets of flags
+
+``` code
+sisu --sqlite filename.sst
+```
+
+creates an sqlite3 database containing searchable content of just the sisu markup document selected
+
+``` code
+sisu --sqlite --update filename.sst
+```
+
+creates an sqlite3 database containing searchable content of marked up document(s) selected by the user from a common directory
+
+``` code
+sisu --pg --update filename.sst
+```
+
+fills a postgresql database with searchable content of marked up document(s) selected by the user from a common directory
+
+For postgresql the first time the command is run in a given directory the user will be prompted to create the requisite database, at the time of writing the prompt sisu provides is as follows:
+
+``` code
+no connection with pg database established, you may need to run:
+    createdb "SiSU.7a.current"
+  after that don't forget to run:
+    sisu --pg --createall
+  before attempting to populate the database
+```
+
+The named database that sisu expects to find must exist and if necessary be created using postgresql tools. If the database exist but the database tables do not, sisu will attempt to create the tables it needs, the equivalent of the requested #{sisu --pg --createall}# command.
+
+Once this is done, the sql database is populated and ready to be queried.
+
+2~ SQL type databases
+
+SiSU feeds sisu markup documents into sql type databases PostgreSQL~{ http://www.postgresql.org/ \\ http://advocacy.postgresql.org/ \\ http://en.wikipedia.org/wiki/Postgresql }~ and/or SQLite~{ http://www.hwaci.com/sw/sqlite/ \\ http://en.wikipedia.org/wiki/Sqlite }~ database together with information related to document structure.
 
 This is one of the more interesting output forms, as all the structural data of the documents are retained (though can be ignored by the user of the database should they so choose). All site texts/documents are (currently) streamed to four tables:
 
index ca46ef99202fbd65f6e1fe161f3fefe22c8c0230..8f1b1d91d3ba304e69911c23783d159259c1c009 100644 (file)
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2015-05-21" "7.1.3" "SiSU"
+.TH "sisu" "1" "2014-02-05" "7.1.5" "SiSU"
 .br
 .SH NAME
 .br
@@ -3417,12 +3417,6 @@ viral_spiral.david_bollier.sst
 .SH SISU SEARCH - INTRODUCTION
 
 
-.BR
-
-.B SiSU
-output can easily and conveniently be indexed by a number of standalone
-indexing tools, such as Lucene, Hyperestraier.
-
 .BR
 Because the document structure of sites created is clearly defined, and the
 text
@@ -3440,15 +3434,98 @@ a document corpus searchable with that degree of granularity. Basically, your
 match criteria is met by these documents and at these locations within each
 document, which can be viewed within the database directly or in various output
 formats.
+
+.BR
+
+.B SiSU
+can populate an sql database (sqlite3 or postgresql) with documents made up of
+their objects. It also can generate a cgi search form that can be used to query
+the database.
+
+.BR
+In order to use the built in search functionality you would take the following
+steps.
+
+.BR
+* use sisu to populate an sql database with with a sisu markup content
+
+.BR
+  * sqlite3 should work out of the box
+
+.BR
+  * postgresql may require some initial database configuration
+
+.BR
+* provide a way to query the database, which sisu can assist with by
+
+.BR
+  * generating a sample ruby cgi search form, required (sisu configuration
+  recommended)
+
+.BR
+  * adding a query field for this search form to be added to all html files
+  (sisu configuration required)
 .SH SQL
 
-.SH POPULATING SQL TYPE DATABASES
+.SH POPULATE THE DATABASE
+
+
+.BR
+TO populate the sql database, run sisu against a sisu markup file with one of
+the following sets of flags
+.nf
+sisu --sqlite filename.sst
+.fi
+
+
+.BR
+creates an sqlite3 database containing searchable content of just the sisu
+markup document selected
+.nf
+sisu --sqlite --update filename.sst
+.fi
+
+
+.BR
+creates an sqlite3 database containing searchable content of marked up
+document(s) selected by the user from a common directory
+.nf
+sisu --pg --update filename.sst
+.fi
+
+
+.BR
+fills a postgresql database with searchable content of marked up document(s)
+selected by the user from a common directory
+
+.BR
+For postgresql the first time the command is run in a given directory the user
+will be prompted to create the requisite database, at the time of writing the
+prompt sisu provides is as follows:
+.nf
+no connection with pg database established, you may need to run:
+    createdb "SiSU.7a.current"
+  after that don't forget to run:
+    sisu --pg --createall
+  before attempting to populate the database
+.fi
+
+
+.BR
+The named database that sisu expects to find must exist and if necessary be
+created using postgresql tools. If the database exist but the database tables
+do not, sisu will attempt to create the tables it needs, the equivalent of the
+requested sisu --pg --createall command.
+
+.BR
+Once this is done, the sql database is populated and ready to be queried.
+.SH SQL TYPE DATABASES
 
 
 .BR
 
 .B SiSU
-feeds sisu markupd documents into sql type databases
+feeds sisu markup documents into sql type databases
 .I PostgreSQL
 [^14] and/or
 .I SQLite
@@ -3661,6 +3738,44 @@ updates file contents in database
 removes specified document from sqlite database.
 .SH CGI SEARCH FORM
 
+
+.BR
+For the search form, which is a single search page
+
+.BR
+* configure the search form
+
+.BR
+* generate the sample search form with the sisu command, (this will be based on
+the configuration settings and existing found sisu databases)
+
+.BR
+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.
+
+.BR
+correctly, you may want www-data rather than your username.
+.nf
+@user='www-data'
+.fi
+
+
+.BR
+* check the search form, copy it to the appropriate cgi directory and set the
+correct permissions
+
+.BR
+For a search form to appear on each html page, you need to:
+
+.BR
+* rely on the above mentioned configuration of the search form
+
+.BR
+* configure the html search form to be on
+
+.BR
+* run the html command
 .SH SETUP SEARCH FORM
 
 
@@ -3682,7 +3797,7 @@ 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):
 .nf
-createdb SiSUv6a_manual
+createdb SiSU.7a.manual
 .fi