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

2 files changed, 104 insertions, 45 deletions

diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index ce47abce..7af13c9d 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -9,14 +9,14 @@
 .\" /[^\\][-']
 .\" :%s/\([^\\]\)\([-']\)/\1\\\2/c
 .\" |sisu.1|@|^|<url:sisu.1>
-.TH "sisu" "1" "June 29, 2007" "version 0.54" "USER COMMANDS and basic Markup"
+.TH "sisu" "1" "July 7, 2007" "version 0.55" "USER COMMANDS and basic Markup"
 .SH "NAME"
 .B SiSU
 \- Structured information, Serialized Units \- a document publishing system
 .SH "SYNOPSIS"
 .B sisu
 .B [
-.I \-AabcDdEeFHhIMmNnopqrRSstUuVvwXxYyZz0\-9
+.I \-AabcDdEeFHhIMmNnopqRrSsTtUuVvwXxYyZz0\-9
 .B ] [
 .I filename/ wildcard
 .B ]
@@ -186,7 +186,9 @@ html, with internal document links that include the document suffix, i.e. whethe
 .BI \-I \ [filename/wildcard]
 produces
 .I texinfo
-file.
+and
+.I info
+file, (view with pinfo).
 .TP
 .BI \-L
 prints license information.
diff --git a/man/man8/sisu.8 b/man/man8/sisu.8
index 005759fa..e3e676ae 100644
--- a/man/man8/sisu.8
+++ b/man/man8/sisu.8
@@ -22,16 +22,16 @@ A 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\'
-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
+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 1 sisu
 or
 .I <http://www.jus.uio.no/sisu>
 .PP
-.B SiSU is an alternative way of publishing and managing documents.
+.B SiSU is a way of preparing, publishing, managing and searching documents.
 .\"%% Installation
 .SH INSTALLATION
 .PP
@@ -46,15 +46,8 @@ how to install SiSU.
 .PP
 Sample marked up documents are are available at
 .I /usr/share/doc/sisu/sisu_markup_samples/dfsg
-or equivalent directory, or online at
-.I <http://www.jus.uio.no/sisu/sample/markup.html>
-or for viewing in html with syntax highlighting from
-.I <http://www.jus.uio.no/sisu/sample/syntax>
-.PP
-A syntax table is provided at
-.I /usr/share/doc/sisu/on_markup.txt
-or equivalent, and online at
-.I <http://www.jus.uio.no/sisu/sample/on_markup.txt>
+or equivalent directory, or online, see
+.I <http://www.jus.uio.no/sisu/SiSU/2.html>
 .PP
 .I man 1 sisu
 has a syntax table along with processing commands.
@@ -75,22 +68,40 @@ The rest of this note is on post installation setup
 .\"%% Post Installation Setup
 .SH Post Installation Setup \- Quick start
 .PP
-After installation of sisu-complete, move to the document samples directory
+
+After installation of sisu\-complete, move to the document samples directory,
 .PP
   cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
 .PP
-and run
+[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]
+.PP
+and in that directory, initialise the output directory with the command
 .PP
-  sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+.I sisu \-CC
+.PP
+then run:
+.PP
+.I sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst
 .PP
 or the same:
 .PP
-  sisu  \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+.I sisu  \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
 .PP
 look at output results, see the "sisu_manifest" page created for the document
 .PP
-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.
+for an overview of your current sisu setup, type:
+.PP
+.I sisu \-\-help env
+.PP
+or
+.PP
+.I sisu \-V
+.PP
+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.
 .PP
 .I sisu \-1 http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst
 .PP
@@ -103,11 +114,15 @@ gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
 additional markup samples in
 .I <http://www.jus.uio.no/sisu/SiSU/2.html>
 .PP
-it should also be possible to run sisu against sisupods (prepared zip files, created by running the command sisu -S [filename]), whether stored locally or remotely.
+it should also be possible to run sisu against sisupods (prepared zip files,
+created by running the command sisu \-S [filename]), whether stored locally or
+remotely.
 .PP
 .I sisu \-3 http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip
 .PP
-there is a security issue associated with the running of document skins that are not your own, so these are turned of by default, and the use of the following command, which switches on the associated skin is not recommended:
+there is a security issue associated with the running of document skins that
+are not your own, so these are turned of by default, and the use of the
+following command, which switches on the associated skin is not recommended:
 .PP
 .I sisu \-3 \-\-trust http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip
 .PP
@@ -174,43 +189,83 @@ SiSU):
 .PP
 Package: sisu
 .PP
-Depends: ruby (>= 1.8.4), libwebrick-ruby
+Depends: ruby (>= 1.8.2), libwebrick\-ruby, unzip, zip
 .PP
-Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
-  tidy, librexml-ruby, zip, unzip, openssl, rsync, openssh-client \| lsh-client,
-  keychain, hyperestraier, kdissert
+Conflicts: vim\-sisu, sisu\-vim, sisu\-remote
 .PP
-Suggests: libfcgi-ruby1.8, rcs \| cvs, lv, texinfo, pinfo, rename
+Replaces: vim\-sisu, sisu\-vim
 .PP
-Package: sisu-complete
+Recommends: 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
 .PP
-Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
+Package: sisu\-complete
+.PP
+Depends: ruby (>= 1.8.2), sisu, sisu\-pdf, sisu\-postgresql, sisu\-sqlite
 .PP
 Recommends: hyperestraier
 .PP
-Package: sisu-pdf
+Package: sisu\-pdf
 .PP
-Depends: sisu, tetex-bin \| texlive-base-bin, tetex-extra \| texlive-latex-extra,
-  texlive-latex-extra, latex-ucs
+Depends: sisu, texlive\-latex\-base, texlive\-fonts\-recommended,
+texlive\-latex\-recommended, texlive\-latex\-extra
 .PP
 Suggests: evince, xpdf
 .PP
-Package: sisu-postgresql
+Package: sisu\-postgresql
 .PP
-Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby
+Depends: sisu, libdbd\-pg\-ruby, libdbi\-ruby, libdbm\-ruby, postgresql
 .PP
-Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1
+Recommends: libfcgi\-ruby
 .PP
-Package: sisu-sqlite
+Package: sisu\-sqlite
 .PP
-Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
+Depends: sisu, sqlite, libdbd\-sqlite\-ruby, libdbi\-ruby, libdbm\-ruby
 .PP
-Suggests: libdbd-sqlite
+Recommends: libfcgi\-ruby
 .PP
-Package: sisu-markup-samples
+Package: sisu\-markup\-samples
 .PP
 Depends: sisu
 .PP
+.SH Package Description
+.B sisu
+.PP
+Description: documents \- structuring, publishing in multiple formats and search
+.PP
+SiSU is a lightweight markup based, command line oriented, document
+structuring, publishing and search framework for document collections.
+.PP
+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.
+.PP
+SiSU also provides concordance files, document content certificates and
+manifests of generated output.
+.PP
+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.
+.PP
+man pages, and interactive help are provided.
+.PP
+Dependencies for various features are taken care of in sisu related packages.
+The package sisu\-complete installs the whole of SiSU.
+.PP
+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.
+.PP
+Homepage: <http://www.jus.uio.no/sisu>
 .fi
 .\"%% Configuration Files
 .SH DOCUMENT RESOURCE CONFIGURATION
@@ -235,7 +290,8 @@ sub\-directories located at the following paths:
 .I /etc/sisu/skin
 .fi
 .PP
-more specifically, the following locations (or their /etc/sisu equivalent) should be used:
+more specifically, the following locations (or their /etc/sisu equivalent)
+should be used:
 .PP
 .I ~/.sisu/skin/doc
 skins for individual documents;
@@ -249,7 +305,8 @@ modifying the site\-wide appearance of documents.
 .PP
 Usually all skin files are placed in the document skin directory:
 .I ~/.sisu/skin/doc
-with softlinks being made to the skins contained there from other skin directories as required.
+with softlinks being made to the skins contained there from other skin
+directories as required.
 .\"%% Further Information
 .SH FURTHER INFORMATION
 .PP