documentation, acquiring source & installation, minor

4 files changed, 117 insertions, 28 deletions

diff --git a/README b/README
index 7af7f698..ad3434e7 100644
--- a/README
+++ b/README
@@ -37,15 +37,20 @@ Homepages:
 INSTALL OR RUN WITHOUT INSTALLATION
 ***********************************
 
-SOURCE TARBALL
---------------
+SOURCE TREE
+-----------
 
 RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
 ..........................................................
 
-1. Download the latest source
+Download & unpack the latest source tarball
 
-2. Unpack the source
+or
+
+Git clone the latest source, to clone the latest source without the repo
+history:
+
+git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
 
 Provided you have *Ruby*, *SiSU* can be run without installation straight from
 the source package directory tree. Run ruby against the full path to bin/sisu
@@ -55,14 +60,36 @@ Note however, that additional external package dependencies, such as texlive
 (for pdfs), sqlite3 or postgresql (for search) should you desire to use them
 are not taken care of for you.
 
-GEM INSTALL (WITH RAKE)
-.......................
+GEM INSTALL
+...........
 
 Gem install, you need to:
 
 (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
 the gem
 
+
+----------------------------------------
+
+GEM INSTALL WITH QI (QUICK INSTALL) SCRIPT
+..........................................
+
+(This requires that ruby -thor is installed).
+
+qi (quick install) can go through the steps required to install the gem:
+
+  qi gem --create --build --install --stable
+
+or
+
+  qi gem --create --build --install --unstable
+
+
+----------------------------------------
+
+GEM INSTALL WITH RAKE
+.....................
+
 Provided you have ruby & rake, this can be done with the single command:
 
   rake gem_create_build_install # (to build and install sisu v5 & sisu v6,
@@ -79,7 +106,21 @@ separate gems are made/installed for sisu v5 & sisu v6 contained in source:
 for individual steps (create, build, install) see rake options, rake -T to
 specify sisu version for sisu installed via gem
 
-  gem search sisu
+For a list of alternative actions you may type:
+
+  rake help
+
+  rake -T
+
+Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
+
+
+----------------------------------------
+
+MISC GEM
+........
+
+gem search sisu
 
   sisu _5.6.2_ --version
 
@@ -89,15 +130,21 @@ to uninstall sisu installed via gem
 
   sudo gem uninstall --verbose sisu
 
-For a list of alternative actions you may type:
+DIRECT INSTALLATION WITH QI (QUICK INSTALL) SCRIPT
+..................................................
 
-  rake help
+(This requires that ruby -thor is installed).
 
-  rake -T
+Root will be requested as required:
 
-Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
+  qi setup --bin --lib --conf --data --share --man
+
+or
+
+  qi setup --all
 
-Rant: <http://make.rubyforge.org/> <http://rubyforge.org/frs/?group_id=615>
+You may wish to do a dryrun to see where files would be installed without
+copying them, to do so add the flag --dryrun
 
 INSTALLATION WITH SETUP.RB
 ..........................
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi
index 085229f1..c5f31d2a 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi
@@ -44,13 +44,15 @@ For changelogs see http://www.jus.uio.no/sisu/SiSU/changelog.html
 
 Git repository currently at:
 
-_* git clone git://git.sisudoc.org/git/code/sisu.git
-
-_* git clone _http://git.sisudoc.org/git/code/sisu.git
+_* git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream
 
 _* http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
 
-On using git, see
+To get the most recent source without repo history:
+
+_* git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
+
+On using git, see:
 
 !_ Git documentation:
 {~^ Git User's Manual }http://www.kernel.org/pub/software/scm/git/docs/user-manual.html, {~^ Everyday GIT With 20 Commands Or So }http://www.kernel.org/pub/software/scm/git/docs/everyday.html, {~^ A tutorial introduction to git }http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/tutorial.html, {~^ A tutorial introduction to git: part two }http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/tutorial-2.html
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 08c9ba02..97fdbd28 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
@@ -19,26 +19,46 @@
 
 :A~? SiSU Installation notes
 
-1~source_tarball Source tarball
+1~source_tree Source tree
 
 2~ run off source package directory tree (without installing)
 ={ SiSU program:run off source package directory tree;SiSU:run off source package directory tree }
 
-1. Download the latest source
+Download & unpack the latest source tarball
 
-2. Unpack the source
+or
+
+Git clone the latest source, to clone the latest source without the repo history:
+
+``` code
+git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
+```
 
 Provided you have Ruby, SiSU can be run without installation straight from the source package directory tree. Run ruby against the full path to bin/sisu (in the unzipped source package directory tree)
 
 Note however, that additional external package dependencies, such as texlive (for pdfs), sqlite3 or postgresql (for search) should you desire to use them are not taken care of for you.
 
-2~ Gem install (with rake)
+2~ Gem install
 ={ SiSU program:gem;SiSU:ruby gem }
 
 Gem install, you need to:
 
 (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install the gem
 
+3~ Gem install with qi (quick install) script
+
+(This requires that ruby-thor is installed).
+
+qi (quick install) can go through the steps required to install the gem:
+
+_1 qi gem --create --build --install --stable
+
+or
+
+_1 qi gem --create --build --install --unstable
+
+3~ Gem install with rake
+
 Provided you have ruby & rake, this can be done with the single command:
 
 _1 rake gem_create_build_install # (to build and install sisu v5 & sisu v6, alias gemcbi)
@@ -52,6 +72,16 @@ _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
 
+For a list of alternative actions you may type:
+
+_1 rake help
+
+_1 rake -T
+
+Rake: http://rake.rubyforge.org/ http://rubyforge.org/frs/?group_id=50
+
+3~ misc Gem
+
 gem search sisu
 
 _1 sisu _${sisu_stable}_ --version
@@ -62,15 +92,19 @@ to uninstall sisu installed via gem
 
 _1 sudo gem uninstall --verbose sisu
 
-For a list of alternative actions you may type:
+2~ direct installation with qi (quick install) script
 
-_1 rake help
+(This requires that ruby-thor is installed).
 
-_1 rake -T
+Root will be requested as required:
 
-Rake: http://rake.rubyforge.org/ http://rubyforge.org/frs/?group_id=50
+_1 qi setup --bin --lib --conf --data --share --man
+
+or
+
+_1 qi setup --all
 
-Rant: http://make.rubyforge.org/ http://rubyforge.org/frs/?group_id=615
+You may wish to do a dryrun to see where files would be installed without copying them, to do so add the flag --dryrun
 
 2~ installation with setup.rb
 ={ SiSU program:setup.rb;SiSU:setup.rb }
diff --git a/data/doc/sisu/org/sisu.org b/data/doc/sisu/org/sisu.org
index 3ea2f446..dbf00996 100644
--- a/data/doc/sisu/org/sisu.org
+++ b/data/doc/sisu/org/sisu.org
@@ -12,7 +12,7 @@ the ability to cite text easily across output formats.
 
 documents - structuring, publishing in multiple formats and search
  SiSU is a lightweight markup based, command line oriented, document
- structuring, publishing and search, static content framework for document
+ structuring, publishing and search, static content tool for document
  collections.
  .
  With minimal preparation of a plain-text (UTF-8) file, using sisu markup syntax
@@ -52,7 +52,7 @@ documents - structuring, publishing in multiple formats and search
  te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk)
  .
  SiSU works well under po4a translation management, for which an administrative
- sample Rakefile is provided with sisu_manual under markup-samples.                                           j
+ sample Rakefile is provided with sisu_manual under markup-samples.
 
 ** take two
 
@@ -538,10 +538,16 @@ w3 since October 3 1993
 ** source
 http://git.sisudoc.org/gitweb/
 
+*** sisu
 sisu git repo:
 http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
 
-sisu-markup-samples git repo:
+**** most recent source without repo history
+git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
+**** full clone
+git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream
+
+*** sisu-markup-samples git repo:
 http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary
 
 ** mailing list