cgi-sample search form; texinfo fix; xml scaffold; help, man pages etc. visited; screen output, color set to true; docbook entries removed

* cgi generated sample search form
  * order results on files of the same title, in multiple files (with
    different filenames)
  * postgresql, character case sensitivity, control, on/off
  * tail decoration, gplv3 & sisu info

* texinfo/info (pinfo) module starts to do something vaguely useful again
  [not a much used module, testing required]

* print XML rendition of document structure to screen -T

* sisurc.yml default, color set to true
  [apologies if this causes anyone any inconvenience, it is configurable in
  sisurc.yml]

* help, man pages, README (man(8) related and env, 'sisu -V')

* docbook entries removed for the present time

* sisu-install (install ruby rant script renamed) and permissions set to
  executable

3 files changed, 171 insertions, 128 deletions

diff --git a/data/doc/sisu/copyright b/data/doc/sisu/copyright
index c15699c4..6b129a77 100644
--- a/data/doc/sisu/copyright
+++ b/data/doc/sisu/copyright
@@ -8,33 +8,31 @@ The original source can always be found at:
 	<http://www.jus.uio.no/sisu/SiSU/download>
 	<http://www.jus.uio.no/sisu/pkg/src>
 
-Copyright (C) 1997, 1998, 1999, 2000, 20001, 2002, 2003, 2004, 2005
-Ralph Amissah
+License: GPL 3 or later:
 
-License: GPL v3 or later
+  SiSU, a framework for document structuring, publishing and search
 
-  GPL3 summary:
+  Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+  2007 Ralph Amissah
 
-  This program is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 3 of the License, or
-  (at your option) any later version.
+  This program is free software: you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the Free
+  Software Foundation, either version 3 of the License, or (at your option)
+  any later version.
 
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+  more details.
 
-  You should have received a copy of the GNU General Public License
-  along with this package; if not, write to the Free Software
-  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-  MA 02110-1301, USA
+  You should have received a copy of the GNU General Public License along with
+  this program. If not, see <http://www.gnu.org/licenses/>.
 
   If you have Internet connection, the latest version of the GPL should be
-  available from these locations:
-    <http://www.fsf.org/licenses/gpl.html>
-    <http://www.gnu.org/copyleft/gpl.html>
-    <http://www.jus.uio.no/sisu/gpl3.fsf>
+  available at these locations:
+  <http://www.fsf.org/licenses/gpl.html>
+  <http://www.gnu.org/copyleft/gpl.html>
+  <http://www.jus.uio.no/sisu/gpl.fsf>
 
   On Debian systems, the complete text of the GNU General
   Public License can be found in `/usr/share/common-licenses/GPL'.
@@ -42,7 +40,7 @@ License: GPL v3 or later
   The Free Software Foundation:
     <http://www.fsf.org/>
 
-For installation purposes the SiSU tarball includes
+For installation purposes the SiSU tarball includes:
 
 setup.rb by Minero Aoki
 
@@ -52,9 +50,9 @@ Hompepage:
 License:
   LGPL
 
-and 
+and
 
-install, an installer generated by
+sisu-install, an installer generated by
 Rant which is by Stefan Lang
 
 Homepage:
@@ -64,4 +62,4 @@ License:
   LGPL
 
 NB: Rant is not included in the SiSU tarball, and is not itself required for
-    the Rant generated install file to work
+    the Rant generated install file to work, (ruby will suffice)
diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html
index 61d0ab0d..968f8eb1 100644
--- a/data/doc/sisu/html/sisu.1.html
+++ b/data/doc/sisu/html/sisu.1.html
@@ -12,7 +12,7 @@
 <b>SiSU</b> - Structured information, Serialized Units - a document
 publishing system 
 <h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
-<b>sisu</b> <b>[</b> <i>-AabcDdEeFHhIMmNnopqrRSstUuVvwXxYyZz0-9</i>
+<b>sisu</b> <b>[</b> <i>-AabcDdEeFHhIMmNnopqRrSsTtUuVvwXxYyZz0-9</i>
 <b>] [</b> <i>filename/</i> wildcard <b>]</b> <p>
 <b>sisu</b> <b>[</b> <i>-Ddcv</i> <b>] [</b> <i>instruction</i> <b>]</b> <p>
 <b>sisu</b> <b>[</b> <i>-CcFLSVvW</i>
@@ -130,37 +130,37 @@ most web servers). [behaviour switched after 0.35 see -H]. </dd>
 
 <dt><b>-I</b><i>&nbsp;[filename/wildcard]</i>
 </dt>
-<dd>produces <i>texinfo</i> file. </dd>
+<dd>produces <i>texinfo</i> and <i>info</i> file, (view with pinfo). </dd>
 
 <dt><b>-L</b> </dt>
-<dd>prints license information. </dd>
+<dd>prints license information.
+</dd>
+
+<dt><b>-M</b><i>&nbsp;[filename/wildcard/url]</i> </dt>
+<dd><i>maintenance</i> mode files created for processing
+preserved and their locations indicated. (also see -V) </dd>
+
+<dt><b>-m</b><i>&nbsp;[filename/wildcard/url]</i>
+</dt>
+<dd>assumed for most other flags, creates new meta-markup file, (the <i>metaverse</i>
+) that is used in all subsequent processing of other output. This step is
+assumed for most processing flags. To skip it see <i>-n</i> </dd>
+
+<dt><b>-N</b><i>&nbsp;[filename/wildcard/url]</i>
+</dt>
+<dd>document <i>digest</i> or <i>document</i> content certificate ( <i>DCC</i> ) as <i>md5</i> digest tree
+of the document: the digest for the document, and digests for each object
+contained within the document (together with information on software versions
+that produced it)  (digest.txt). <i>-NV</i> for verbose digest output to screen. </dd>
+
+<dt><b>-n</b><i>&nbsp;[filename/wildcard/url]</i>
+</dt>
+<dd>skip meta-markup (building of "metaverse"), this skips the equivalent of
+<i>-m</i> which is otherwise assumed by most processing flags. </dd>
 
-<dt><b>-M</b><i>&nbsp;[filename/wildcard/url]</i>
+<dt><b>-o</b><i>&nbsp;[filename/wildcard/url]</i>
 </dt>
-<dd><i>maintenance</i> mode files created for processing preserved and their locations
-indicated. (also see -V) </dd>
-
-<dt><b>-m</b><i>&nbsp;[filename/wildcard/url]</i> </dt>
-<dd>assumed for most other
-flags, creates new meta-markup file, (the <i>metaverse</i> ) that is used in all
-subsequent processing of other output. This step is assumed for most processing
-flags. To skip it see <i>-n</i> </dd>
-
-<dt><b>-N</b><i>&nbsp;[filename/wildcard/url]</i> </dt>
-<dd>document <i>digest</i> or <i>document</i>
-content certificate ( <i>DCC</i> ) as <i>md5</i> digest tree of the document: the digest
-for the document, and digests for each object contained within the document
-(together with information on software versions that produced it)  (digest.txt).
-<i>-NV</i> for verbose digest output to screen. </dd>
-
-<dt><b>-n</b><i>&nbsp;[filename/wildcard/url]</i> </dt>
-<dd>skip meta-markup
-(building of "metaverse"), this skips the equivalent of <i>-m</i> which is otherwise
-assumed by most processing flags. </dd>
-
-<dt><b>-o</b><i>&nbsp;[filename/wildcard/url]</i> </dt>
-<dd>output basic
-document in <i>opendocument</i> file format (opendocument.odt). </dd>
+<dd>output basic document in <i>opendocument</i> file format (opendocument.odt). </dd>
 
 <dt><b>-p</b><i>&nbsp;[filename/wildcard]</i>
 </dt>
@@ -1161,7 +1161,7 @@ set up, and first time must be run without other flags ie sisu <i>-mrv</i> [file
 <b>sisu</b> <i>-mhwprv</i> example_file.sst other_example_file.sst <p>
 to process a remote sisu
 marked up file (html,pdf,concordance), provide the url(s) (works for text
-only files, will be downloaded and processed locally): <b>sisu</b> <i>-mhwpv</i> <a href='http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst'>http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst</a>
+only files, will be downloaded and processed locally): <b>sisu</b> <i>-mhwpv</i> <a href='http://www.jus.uio.no/sisu/sample/markup/gpl3.fsf.sst'>http://www.jus.uio.no/sisu/sample/markup/gpl3.fsf.sst</a>
 
 http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst <p>
 one file is local
diff --git a/data/doc/sisu/html/sisu.8.html b/data/doc/sisu/html/sisu.8.html
index b79b71b1..c6134b33 100644
--- a/data/doc/sisu/html/sisu.8.html
+++ b/data/doc/sisu/html/sisu.8.html
@@ -19,65 +19,72 @@ document publishing system, that from a simple single marked-up document,
 produces a multitude of output formats including: html, latex, pdf, info,
 and sql output, which can be cross referenced as having the same document
 structure and text object numbering, "object citation numbering". Features
-include its&rsquo; simple syntax; the semantic identification of documents using
-the Dublin Core; document management; built to be associated with a revision
-control system; text object numbering for the identification of a texts
-location in any of the output formats, easy skinning on a site wide, or
-per document basis, ... for more see <i>man</i> 1 sisu or <i>&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+include its&rsquo; simple syntax; the semantic tagging of documents; document
+management; built to be associated with a revision control system; text
+object numbering for the identification of a texts location in any of the
+output formats, easy skinning on a site wide, or per document basis; granular
+search; a degree of future proofing ... for more see <i>man</i> 1 sisu or <i>&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
 &gt;</i>
 <p>
-<b>SiSU is an alternative way of publishing and managing documents.</b>  
+<b>SiSU is a way of preparing, publishing, managing and searching documents.</b>
+ 
 <h2><a name='sect3' href='#toc3'>Installation</a></h2>
 <p>
-Up
-to date information on SiSU downloads, and their installation should be
-available from: <i>&lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html'>http://www.jus.uio.no/sisu/SiSU/download.html</a>
-&gt;</i> or at: <i>&lt;<a href='http://www.jus.uio.no/sisu/sisu_download/download.html'>http://www.jus.uio.no/sisu/sisu_download/download.html</a>
+Up to date information on SiSU downloads, and their installation
+should be available from: <i>&lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html'>http://www.jus.uio.no/sisu/SiSU/download.html</a>
+&gt;</i> or
+at: <i>&lt;<a href='http://www.jus.uio.no/sisu/sisu_download/download.html'>http://www.jus.uio.no/sisu/sisu_download/download.html</a>
+&gt;</i> <p>
+There you should
+find links to the latest source tarball, and instructions on how to install
+SiSU. <p>
+Sample marked up documents are are available at <i>/usr/share/doc/sisu/sisu_markup_samples/dfsg</i>
+or equivalent directory, or online, see <i>&lt;<a href='http://www.jus.uio.no/sisu/SiSU/2.html'>http://www.jus.uio.no/sisu/SiSU/2.html</a>
 &gt;</i>
 <p>
-There you should find links to the latest source tarball, and instructions
-on how to install SiSU. <p>
-Sample marked up documents are are available at
-<i>/usr/share/doc/sisu/sisu_markup_samples/dfsg</i> or equivalent directory, or
-online at <i>&lt;<a href='http://www.jus.uio.no/sisu/sample/markup.html'>http://www.jus.uio.no/sisu/sample/markup.html</a>
-&gt;</i> or for viewing in html
-with syntax highlighting from <i>&lt;<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a>
-&gt;</i> <p>
-A syntax
-table is provided at <i>/usr/share/doc/sisu/on_markup.txt</i> or equivalent, and
-online at <i>&lt;<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a>
-&gt;</i> <p>
-<i>man</i> 1 sisu has a
-syntax table along with processing commands. <p>
-SiSU also provides some help
-via the command: <i>sisu</i> --help and selecting an appropriate subject, e.g. <p>
-<i>sisu</i>
---help commands <p>
+<i>man</i> 1 sisu has a syntax table along with processing commands. <p>
+SiSU also
+provides some help via the command: <i>sisu</i> --help and selecting an appropriate
+subject, e.g. <p>
+<i>sisu</i> --help commands <p>
 <i>sisu</i> --help markup <p>
 <i>sisu</i> --help headers <p>
-<i>sisu</i> --help env <p>
-The rest
-of this note is on post installation setup  
-<h2><a name='sect4' href='#toc4'>Post Installation Setup - Quick
-start</a></h2>
-<p>
-After installation of sisu-complete, move to the document samples directory
+<i>sisu</i>
+--help env <p>
+The rest of this note is on post installation setup  
+<h2><a name='sect4' href='#toc4'>Post Installation
+Setup - Quick start</a></h2>
 <p>
+
+<p> After installation of sisu-complete, move to the document
+samples directory, <p>
   cd /usr/share/doc/sisu/sisu_markup_samples/dfsg<br>
  <p>
-and run <p>
-  sisu -1 free_as_in_freedom.rms_and_free_software.sam_williams.sst<br>
- <p>
+[this is not where you would normally work but provides sample documents
+for testing, you may prefer instead to copy the contents of that directory
+to a local directory before proceeding] <p>
+and in that directory, initialise
+the output directory with the command <p>
+<i>sisu</i> -CC <p>
+then run: <p>
+<i>sisu</i> -1 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+<p>
 or the same: <p>
-  sisu  -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst<br>
- <p>
+<i>sisu</i>  -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+<p>
 look at output results, see the "sisu_manifest" page created for the document
 <p>
-To generate an online document move to a writable directory, (create a
-work directory and cd into it) as the file will be downloaded there and
-e.g. <p>
+for an overview of your current sisu setup, type: <p>
+<i>sisu</i> --help env <p>
+or <p>
+<i>sisu</i>
+-V <p>
+To generate a document from a remote url accessible location  move to
+a writable directory, (create a work directory and cd into it) as the file
+will be downloaded there and e.g. <p>
 <i>sisu</i> -1 <a href='http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst'>http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst</a>
- <p>
+
+<p>
 <i>sisu</i> -3 <a href='http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst'>http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst</a>
 
 <p>
@@ -140,39 +147,76 @@ gives an idea of additional packages that SiSU can make use of if available,
 (the use/requirement of some of which are interdependent for specific actions
 by SiSU): <p>
 Package: sisu <p>
-Depends: ruby (&gt;= 1.8.4), libwebrick-ruby <p>
+Depends: ruby (&gt;= 1.8.2), libwebrick-ruby, unzip, zip
+<p>
+Conflicts: vim-sisu, sisu-vim, sisu-remote <p>
+Replaces: vim-sisu, sisu-vim <p>
 Recommends:
-sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,   tidy, librexml-ruby,
-zip, unzip, openssl, rsync, openssh-client  lsh-client,<br>
-   keychain, hyperestraier, kdissert<br>
- <p>
-Suggests: libfcgi-ruby1.8, rcs  cvs, lv, texinfo, pinfo, rename <p>
-Package:
-sisu-complete <p>
-Depends: ruby (&gt;= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
+sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang, tidy, librexml-ruby,
+openssl, rsync, openssh-client  lsh-client, keychain, hyperestraier, kdissert
+Suggests: rcs  cvs, lv, texinfo, pinfo <p>
+Package: sisu-complete <p>
+Depends: ruby
+(&gt;= 1.8.2), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite <p>
+Recommends: hyperestraier
 <p>
-Recommends: hyperestraier <p>
 Package: sisu-pdf <p>
-Depends: sisu, tetex-bin  texlive-base-bin,
-tetex-extra  texlive-latex-extra,   texlive-latex-extra, latex-ucs<br>
- <p>
+Depends: sisu, texlive-latex-base, texlive-fonts-recommended,
+texlive-latex-recommended, texlive-latex-extra <p>
 Suggests: evince, xpdf <p>
-Package: sisu-postgresql <p>
-Depends: sisu, postgresql-8.1,
-libdbi-ruby, libdbm-ruby, libdbd-pg-ruby <p>
-Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1
+Package:
+sisu-postgresql <p>
+Depends: sisu, libdbd-pg-ruby, libdbi-ruby, libdbm-ruby, postgresql
 <p>
+Recommends: libfcgi-ruby <p>
 Package: sisu-sqlite <p>
-Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
+Depends: sisu, sqlite, libdbd-sqlite-ruby,
+libdbi-ruby, libdbm-ruby <p>
+Recommends: libfcgi-ruby <p>
+Package: sisu-markup-samples
 <p>
-Suggests: libdbd-sqlite <p>
-Package: sisu-markup-samples <p>
 Depends: sisu <p>
+
+<h2><a name='sect6' href='#toc6'>Package Description</a></h2>
+<b>sisu</b> <p>
+Description: documents - structuring,
+publishing in multiple formats and search <p>
+SiSU is a lightweight markup
+based, command line oriented, document structuring, publishing and search
+framework for document collections. <p>
+With minimal preparation of a plain-text,
+(UTF-8) file, using its native markup syntax in your text editor of choice,
+SiSU can generate various document formats (most of which share a common
+object numbering system for locating content), including plain text, HTML,
+XHTML, XML, OpenDocument text (ODF:ODT), LaTeX, PDF files, and populate
+an SQL database with objects (roughly paragraph-sized chunks) so searches
+may be performed and matches returned with that degree of granularity:
+your search criteria is met by these documents and at these locations within
+each document. Object numbering is particularly suitable for "published"
+works (finalized texts as opposed to works that are frequently changed
+or updated) for which it provides a fixed means of reference of content.
+Document outputs also share semantic meta-data provided. <p>
+SiSU also provides
+concordance files, document content certificates and manifests of generated
+output. <p>
+A vim syntax highlighting file and an ftplugin with folds for sisu
+markup is provided, as are syntax highlighting files for kate, kwrite,
+gedit and diakonos. Vim 7 includes syntax highlighting for SiSU. <p>
+man pages,
+and interactive help are provided. <p>
+Dependencies for various features are
+taken care of in sisu related packages. The package sisu-complete installs
+the whole of SiSU. <p>
+Additional document markup samples are provided in the
+package sisu-markup-samples which is found in the non-free archive the licenses
+for the substantive content of the marked up documents provided is that
+provided by the author or original publisher. <p>
+Homepage: &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
 </pre> 
-<h2><a name='sect6' href='#toc6'>Document
-Resource Configuration</a></h2>
-<b>sisu</b> resource configuration information is obtained
-from sources (where they exist):  <br>
+<h2><a name='sect7' href='#toc7'>Document Resource Configuration</a></h2>
+<b>sisu</b> resource configuration information
+is obtained from sources (where they exist):  <br>
 <pre>~/.sisu/sisurc.yaml/etc/sisu/[sisu version]/sisurc.yamlsisu program defaults</pre><p>
 
 <b>Skins</b> <p>
@@ -190,16 +234,16 @@ of documents. <p>
 Usually all skin files are placed in the document skin directory:
 <i>~/.sisu/skin/doc</i> with softlinks being made to the skins contained there
 from other skin directories as required.  
-<h2><a name='sect7' href='#toc7'>Further Information</a></h2>
+<h2><a name='sect8' href='#toc8'>Further Information</a></h2>
 <p>
 For more information
 on <i>SiSU</i> see: <i>&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
 &gt;</i> <p>
 or <i>man</i> sisu  
-<h2><a name='sect8' href='#toc8'>Author</a></h2>
+<h2><a name='sect9' href='#toc9'>Author</a></h2>
 Ralph Amissah <i>&lt;ralph@amissah.com&gt;</i>
 or <i>&lt;ralph.amissah@gmail.com&gt;</i> 
-<h2><a name='sect9' href='#toc9'>See Also</a></h2>
+<h2><a name='sect10' href='#toc10'>See Also</a></h2>
 <a href='http:~/bin/man2html?sisu:1'><b>sisu(1)</a>
 ,</b> <a href='http:~/bin/man2html?sisu_examples:1'><b>sisu_examples(1)</a>
 ,</b> <a href='http:~/bin/man2html?sisu_webrick:1'><b>sisu_webrick(1)</a>
@@ -219,10 +263,11 @@ or <i>&lt;ralph.amissah@gmail.com&gt;</i>
 <li><a name='toc3' href='#sect3'>Installation</a></li>
 <li><a name='toc4' href='#sect4'>Post Installation Setup - Quick start</a></li>
 <li><a name='toc5' href='#sect5'>Debian INSTALLATION Note</a></li>
-<li><a name='toc6' href='#sect6'>Document Resource Configuration</a></li>
-<li><a name='toc7' href='#sect7'>Further Information</a></li>
-<li><a name='toc8' href='#sect8'>Author</a></li>
-<li><a name='toc9' href='#sect9'>See Also</a></li>
+<li><a name='toc6' href='#sect6'>Package Description</a></li>
+<li><a name='toc7' href='#sect7'>Document Resource Configuration</a></li>
+<li><a name='toc8' href='#sect8'>Further Information</a></li>
+<li><a name='toc9' href='#sect9'>Author</a></li>
+<li><a name='toc10' href='#sect10'>See Also</a></li>
 </ul>
 </body>
 </html>