documentation, minor updatesisu_5.3.3

11 files changed, 85 insertions, 35 deletions

diff --git a/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml
index 4ab568ca..9b60f8c9 100644
--- a/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml
@@ -15,8 +15,9 @@
 #  #all:           'image'
 #% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name)
 webserv:
-  url_root:     'http://www.sisudoc.org' #url to document root, without dir stub
-#  path:         '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
+# url_root:     'http://www.sisudoc.org' #url to document root, without dir stub
+  url_root:     'http://192.168.1.108' #url to document root, without dir stub
+  path:         '/srv/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
 #  images:       '_sisu/image'
 #  man:          'man'
 #  cgi:          '/usr/local/lib/sisu-cgi'
@@ -130,6 +131,15 @@ program_set:
 #    flag:            true
 ##    action:          http://localhost:8081/cgi-bin/sisu_pgsql.cgi
 #    action:          http://search.sisudoc.org
-#    db:              sisu
+#    db:              manual
 #    title:           sample search form
 #promo:               sisu_search_libre, sisu_icon, sisu, open_society, fsf, ruby
+
+search:
+  sisu:
+    flag:            true
+    action:          http://192.168.1.108/cgi/sisu_search.cgi
+#   action:          http://192.168.1.108/cgi-bin/sisu_pgsql.cgi
+#    action:          http://search.sisudoc.org
+    db:              manual
+    title:           sample search form
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst
index 4a23bdfe..afba3e48 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst
@@ -41,7 +41,7 @@ If SiSU is installed on your system usual man commands should be available, try:
 
 man sisu
 
-The SiSU man pages can be viewed online at:~{ generated from source using rman<br> http://polyglotman.sourceforge.net/rman.html <br>With regard to SiSU man pages the formatting generated for markup syntax is not quite right, for that you might prefer the links under:<br> http://www.jus.uio.no/sample }~
+The SiSU man pages can be viewed online at:~{ generated from source using rman \\ http://polyglotman.sourceforge.net/rman.html \\With regard to SiSU man pages the formatting generated for markup syntax is not quite right, for that you might prefer the links under: \\ http://www.jus.uio.no/sample }~
 
 An online version of the sisu man page is available here:
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst
index dfd56ec8..cadcde61 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst
@@ -50,9 +50,11 @@ _1 rake gem_create_build_install_unstable # (to build and install sisu v6, alias
 for individual steps (create, build, install) see rake options, rake -T
 to specify sisu version for sisu installed via gem
 
-_1 sisu _5.3.0_ --version
+gem search sisu
 
-_1 sisu _6.0.0_ --version
+_1 sisu _5.3.3_ --version
+
+_1 sisu _6.0.3_ --version
 
 to uninstall sisu installed via gem
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi
index f908bb6e..0c48c229 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi
@@ -98,9 +98,9 @@ Once installed see man 8 sisu for information on additional programs that sisu m
 
 Further notes on install script.
 
-The install script is prepared using Rant, and a Rantfile *~rant is provided,~{ a Rantfile has been configured to do post installation setup }~ with more comprehensive install options, and post install and setup configuration and generation of first test file, if you have installed Stefan Lang's {~^ Rant }http://make.rubyforge.org/ ~{ http://make.rubyforge.org/ <br> http://rubyforge.org/frs/?group_id=615 }~ installed. While in the package directory, type: rant help, or rant -T, or to install SiSU _{as root}_, type:
+The install script is prepared using Rant, and a Rantfile *~rant is provided,~{ a Rantfile has been configured to do post installation setup }~ with more comprehensive install options, and post install and setup configuration and generation of first test file, if you have installed Stefan Lang's {~^ Rant }http://make.rubyforge.org/ ~{ http://make.rubyforge.org/ \\ http://rubyforge.org/frs/?group_id=615 }~ installed. While in the package directory, type: rant help, or rant -T, or to install SiSU _{as root}_, type:
 
-*install* is an install script prepared using Stefan Lang's {~^ Rant }http://make.rubyforge.org/ ~{ http://make.rubyforge.org/ <br> http://rubyforge.org/frs/?group_id=615 }~ It should work whether you have previously installed Rant or not. It has fairly comprehensive install options, and can do some post install and setup configuration and generation of first test file. For options type:
+*install* is an install script prepared using Stefan Lang's {~^ Rant }http://make.rubyforge.org/ ~{ http://make.rubyforge.org/ \\ http://rubyforge.org/frs/?group_id=615 }~ It should work whether you have previously installed Rant or not. It has fairly comprehensive install options, and can do some post install and setup configuration and generation of first test file. For options type:
 
 _1 ruby install -T
 
@@ -114,7 +114,7 @@ _1 ruby install base
 
 !_ installation with setup.rb
 
-{~^ setup.rb }http://i.loveruby.net/en/projects/setup/ is provided the package and will install SiSU~{ Minero Aoki<br> http://i.loveruby.net/en/projects/setup/doc/ }~ installation is a 3 step process~{ Installation instructions<br> http://i.loveruby.net/en/projects/setup/doc/usage.html }~ the following string assumes you are in the package directory and that you have root as sudo:
+{~^ setup.rb }http://i.loveruby.net/en/projects/setup/ is provided the package and will install SiSU~{ Minero Aoki \\ http://i.loveruby.net/en/projects/setup/doc/ }~ installation is a 3 step process~{ Installation instructions \\ http://i.loveruby.net/en/projects/setup/doc/usage.html }~ the following string assumes you are in the package directory and that you have root as sudo:
 
 _1 ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
index 69293637..fbd6d1f4 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
@@ -744,7 +744,7 @@ column three of row two, and so on
 
 a second form may be easier to work with in cases where there is not much information in each column
 
-*{markup example:}*~{ Table from the Wealth of Networks by Yochai Benkler<br> http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler }~
+*{markup example:}*~{ Table from the Wealth of Networks by Yochai Benkler \\ http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler }~
 
 code{
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst
index 574e307c..e5b0c4cb 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst
@@ -54,29 +54,29 @@ may be used interchangeably.
 
 3~ create and destroy database
 
-!_ --pgsql --createall<br>
+!_ --pgsql --createall \\
 initial step, creates required relations (tables, indexes) in existing (postgresql) database (a database should be created manually and given the same name as working directory, as requested) (rb.dbi)
 
-!_ sisu -D --createdb<br>
+!_ sisu -D --createdb \\
 creates database where no database existed before
 
-!_ sisu -D --create<br>
+!_ sisu -D --create \\
 creates database tables where no database tables existed before
 
-!_ sisu -D --Dropall<br>
+!_ sisu -D --Dropall \\
 destroys database (including all its content)! kills data and drops tables, indexes and database associated with a given directory (and directories of the same name).
 
-!_ sisu -D --recreate<br>
+!_ sisu -D --recreate \\
 destroys existing database and builds a new empty database structure
 
 3~ import and remove documents
 
-!_ sisu -D --import -v [filename/wildcard]<br>
+!_ sisu -D --import -v [filename/wildcard] \\
 populates database with the contents of the file. Imports documents(s) specified to a postgresql database (at an object level).
 
-!_ sisu -D --update -v [filename/wildcard]<br>
+!_ sisu -D --update -v [filename/wildcard] \\
 updates file contents in database
 
-!_ sisu -D --remove -v [filename/wildcard]<br>
+!_ sisu -D --remove -v [filename/wildcard] \\
 removes specified document from postgresql database.
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst
index 959fbcf6..54ea9a7b 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst
@@ -73,10 +73,10 @@ sisu -3R sisu_remote.sst
 
 2~ commands
 
-!_ -R [filename/wildcard] <br>
+!_ -R [filename/wildcard] \\
 copies sisu output files to remote host using rsync. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Note the behavior of rsync different if -R is used with other flags from if used alone. Alone the rsync --delete parameter is sent, useful for cleaning the remote directory (when -R is used together with other flags, it is not). Also see -r
 
-!_ -r [filename/wildcard] <br>
+!_ -r [filename/wildcard] \\
 copies sisu output files to remote host using scp. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Also see -R
 
 2~ configuration
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
index 03eef9ff..4e833b9b 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
@@ -25,6 +25,44 @@
 
 1~search_cgi Introduction
 
+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 SiSUv6a_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
@@ -36,7 +74,7 @@ Note you may set results either for documents matched and object number location
 
 % 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<br>
+!_ 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:
@@ -63,13 +101,13 @@ By default, [unless otherwise specified] databases are built on a directory basi
 
 2~ Search Form
 
-!_ sisu -F<br>
+!_ sisu -F \\
 generates a sample search form, which must be copied to the web-server cgi directory
 
-!_ sisu -F --webserv-webrick<br>
+!_ 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<br>
+!_ 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
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
index d5da379f..386b8175 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
@@ -25,7 +25,7 @@
 
 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 just as simply map the results to the html output, which has richer text markup.
+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.
 
-In addition to this SiSU has the ability to populate a relational sql type database with documents at an object level, with objects numbers that are shared across different output types, which make them 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 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.
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
index 6e54275b..f24fe2a9 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
@@ -30,7 +30,7 @@
 
 2~ populating SQL type databases
 
-SiSU feeds sisu markupd documents into sql type databases PostgreSQL~{ http://www.postgresql.org/ <br> http://advocacy.postgresql.org/ <br> http://en.wikipedia.org/wiki/Postgresql }~ and/or SQLite~{ http://www.hwaci.com/sw/sqlite/ <br> http://en.wikipedia.org/wiki/Sqlite }~ database together with information related to document structure.
+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.
 
 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:
 
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst
index a73ae16c..2c43aa92 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst
@@ -55,28 +55,28 @@ may be used interchangeably.
 
 3~ create and destroy database
 
-!_ --sqlite --createall<br>
+!_ --sqlite --createall \\
 initial step, creates required relations (tables, indexes) in existing (sqlite) database (a database should be created manually and given the same name as working directory, as requested) (rb.dbi)
 
-!_ sisu -d --createdb<br>
+!_ sisu -d --createdb \\
 creates database where no database existed before
 
-!_ sisu -d --create<br>
+!_ sisu -d --create \\
 creates database tables where no database tables existed before
 
-!_ sisu -d --dropall<br>
+!_ sisu -d --dropall \\
 destroys database (including all its content)! kills data and drops tables, indexes and database associated with a given directory (and directories of the same name).
 
-!_ sisu -d --recreate<br>
+!_ sisu -d --recreate \\
 destroys existing database and builds a new empty database structure
 
 3~ import and remove documents
 
-!_ sisu -d --import -v [filename/wildcard]<br>
+!_ sisu -d --import -v [filename/wildcard] \\
 populates database with the contents of the file. Imports documents(s) specified to an sqlite database (at an object level).
 
-!_ sisu -d --update -v [filename/wildcard]<br>
+!_ sisu -d --update -v [filename/wildcard] \\
 updates file contents in database
 
-!_ sisu -d --remove -v [filename/wildcard]<br>
+!_ sisu -d --remove -v [filename/wildcard] \\
 removes specified document from sqlite database.