Merge tag 'sisu_5.3.1' into debian/sid

SiSU 5.3.1

52 files changed, 306 insertions, 64 deletions

diff --git a/data/doc/sisu/markup-samples/sisu_manual/Rakefile b/data/doc/sisu/markup-samples/manual/Rakefile
index 1d9b5414..1d9b5414 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/Rakefile
+++ b/data/doc/sisu/markup-samples/manual/Rakefile
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/GnuDebianLinuxRubyBetterWay.png b/data/doc/sisu/markup-samples/manual/_sisu/image/GnuDebianLinuxRubyBetterWay.png
index ce5b8830..ce5b8830 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/GnuDebianLinuxRubyBetterWay.png
+++ b/data/doc/sisu/markup-samples/manual/_sisu/image/GnuDebianLinuxRubyBetterWay.png
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/ruby_logo.png b/data/doc/sisu/markup-samples/manual/_sisu/image/ruby_logo.png
index 829e2458..829e2458 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/ruby_logo.png
+++ b/data/doc/sisu/markup-samples/manual/_sisu/image/ruby_logo.png
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/sisu.png b/data/doc/sisu/markup-samples/manual/_sisu/image/sisu.png
index b449fa6b..b449fa6b 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/sisu.png
+++ b/data/doc/sisu/markup-samples/manual/_sisu/image/sisu.png
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/tux.png b/data/doc/sisu/markup-samples/manual/_sisu/image/tux.png
index 15fd152b..15fd152b 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/image/tux.png
+++ b/data/doc/sisu/markup-samples/manual/_sisu/image/tux.png
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_fn.yml
index f12e3144..f12e3144 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_fn.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn_monolingual.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_fn_monolingual.yml
index b3c49ca1..b3c49ca1 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_fn_monolingual.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_fn_monolingual.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_ft.yml
index 71faa3e0..71faa3e0 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_ft.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft_monolingual.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_ft_monolingual.yml
index adf144d5..adf144d5 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_ft_monolingual.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_ft_monolingual.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_lng.yml b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml
index ca1cf424..ca1cf424 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/rc/sisurc_by_lng.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/rc/sisurc_by_lng.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/sisu_document_make b/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make
index 72706d10..72706d10 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/sisu_document_make
+++ b/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v5/sisurc.yml b/data/doc/sisu/markup-samples/manual/_sisu/v5/sisurc.yml
index e492f789..e492f789 120000
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v5/sisurc.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/v5/sisurc.yml
diff --git a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v6/sisurc.yml b/data/doc/sisu/markup-samples/manual/_sisu/v6/sisurc.yml
index e492f789..e492f789 120000
--- a/data/doc/sisu/markup-samples/sisu_manual/_sisu/v6/sisurc.yml
+++ b/data/doc/sisu/markup-samples/manual/_sisu/v6/sisurc.yml
diff --git a/data/doc/sisu/markup-samples/manual/en/README.ssm b/data/doc/sisu/markup-samples/manual/en/README.ssm
new file mode 100644
index 00000000..fc67fdb8
--- /dev/null
+++ b/data/doc/sisu/markup-samples/manual/en/README.ssm
@@ -0,0 +1,39 @@
+% SiSU master 5.0
+
+@title: SiSU
+ :subtitle: README
+
+@creator:
+ :author: Amissah, Ralph
+
+@date:
+ :published: 2014-02-02
+ :created: 2014-02-02
+ :available: 2014-02-02
+ :modified: 2014-02-02
+
+@rights:
+ :copyright: Copyright (C) Ralph Amissah 2014
+ :license: GPL 3 (part of SiSU documentation)
+
+@classify:
+ :topic_register: SiSU:manual;electronic documents:SiSU:README
+ :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
+
+:A~ @title
+
+:B~ Introduction
+
+<< sisu_introduction.sst
+
+:B~ Install or Run without Installation
+
+<< sisu_install_run.sst
+
+:B~ Commands
+
+<< sisu_commands.sst
+:B~ Markup
+
+<< sisu_markup.sst
+
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu.ssm b/data/doc/sisu/markup-samples/manual/en/sisu.ssm
index 79703fef..c8260858 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu.ssm
+++ b/data/doc/sisu/markup-samples/manual/en/sisu.ssm
@@ -1,4 +1,4 @@
-% SiSU master 4.0
+% SiSU master 5.0
 
 @title: SiSU
  :subtitle: Manual
@@ -11,7 +11,7 @@
  :created: 2002-08-28
  :issued: 2002-08-28
  :available: 2002-08-28
- :modified: 2012-10-03
+ :modified: 2014-02-05
 
 @rights:
  :copyright: Copyright (C) Ralph Amissah 2012
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_commands.sst b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
index 2ca43a43..be491bf8 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_commands.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_commands.sst
@@ -1,4 +1,4 @@
-% SiSU 4.0
+% SiSU 5.0
 
 @title: SiSU
  :subtitle: Commands
@@ -11,7 +11,7 @@
  :issued: 2002-08-28
  :available: 2002-08-28
  :published: 2007-09-16
- :modified: 2012-10-03
+ :modified: 2014-02-05
 
 @rights:
  :copyright: Copyright (C) Ralph Amissah 2012
@@ -159,6 +159,9 @@ produces html output, the document in a single file (scroll.html) only. Compare
 !_ --html-seg [filename/wildcard] \\
 produces html output, segmented text with table of contents (toc.html and index.html). Compare --html-scroll and --html
 
+!_ --html-strict [filename/wildcard] \\
+produces html with --strict option. see --strict
+
 !_ -I [filename/wildcard] \\
 see --texinfo
 
@@ -221,6 +224,9 @@ see --exc-*
 !_ -o [filename/wildcard/url] \\
 see --odt
 
+!_ --ocn \\
+see --inc-ocn and --exc-ocn
+
 !_ --odf [filename/wildcard/url] \\
 see --odt
 
@@ -324,6 +330,9 @@ produces a zipped file of the prepared document specified along with associated
 !_ --source [filename/wildcard] \\
 copies sisu markup file to output directory. Alias -s
 
+!_ --strict \\
+together with --html, produces more w3c compliant html, for example not having purely numeric identifiers for text, the location object url#33 becomes url#o33
+
 !_ -T [filename/wildcard (*.termsheet.rb)] \\
 standard form document builder, preprocessing feature
 
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_config.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi
index 3c29f995..3c29f995 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_config.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_config.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_content_directories.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi
index 182b176d..182b176d 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_content_directories.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_content_directories.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_css.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi
index 7ffc654b..7ffc654b 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_css.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_css.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_description.sst b/data/doc/sisu/markup-samples/manual/en/sisu_description.sst
index 9f8fdcd8..128bfe1e 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_description.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_description.sst
@@ -1,4 +1,4 @@
-% SiSU 4.0
+% SiSU 5.0
 
 @title: SiSU - SiSU information Structuring Universe / Structured information, Serialized Units
  :subtitle: Description
@@ -11,7 +11,7 @@
  :issued: 2002-11-12
  :available: 2002-11-12
  :published: 2007-08-30
- :modified: 2012-10-03
+ :modified: 2014-02-05
 
 @rights:
  :copyright: Copyright (C) Ralph Amissah 2007
@@ -29,6 +29,26 @@
 
 2~ Outline
 
+SiSU is a framework for document structuring, publishing (in multiple open standard formats) and search, comprising of: (a) a lightweight document structure and presentation markup syntax; and (b) an accompanying engine for generating standard document format outputs from documents prepared in sisu markup syntax, which is able to produce multiple standard outputs (including the population of sql databases) that (can) share a common numbering system for the citation of text within a document.
+
+SiSU is developed under an open source, software libre license (GPLv3). Its use case for development is work with medium to large document sets and cope with evolving document formats/ representation technologies. Documents are prepared once, and generated as need be to update the technical presentation or add additional output formats. Various output formats (including search related output) share a common mechanism for cross-output-format citation.
+
+SiSU both defines a markup syntax and provides an engine that produces open standards format outputs from documents prepared with SiSU markup. From a single lightly prepared document sisu custom builds several standard output formats which share a common (text object) numbering system for citation of content within a document (that also has implications for search). The sisu engine works with an abstraction of the document's structure and content from which it is possible to generate different forms of representation of the document. Significantly SiSU markup is more sparse than html and outputs which include HTML, EPUB, ODT (Open Document Format text), LaTeX, landscape and portrait PDF, all of which can be added to and updated. SiSU is also able to populate SQL type databases at an object level, which means that searches can be made with that degree of granularity.
+
+Source document preparation and output generation is a two step process: (i) document source is prepared, that is, marked up in sisu markup syntax and (ii) the desired output subsequently generated by running the sisu engine against document source. Output representations if updated (in the sisu engine) can be generated by re-running the engine against the prepared source. Using SiSU markup applied to a document, SiSU custom builds (to take advantage of the strengths of different ways of representing documents) various standard open output formats including plain text, HTML, XHTML, XML, EPUB, ODT, LaTeX or PDF files, and populate an SQL database with objects~{ objects include: headings, paragraphs, verse, tables, images, but not footnotes/endnotes which are numbered separately and tied to the object from which they are referenced. }~ (equating generally to paragraph-sized chunks) so searches may be performed and matches returned with that degree of granularity ( e.g. your search criteria is met by these documents and at these locations within each document). Document output formats share a common object numbering system for locating content. This 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.
+
+In preparing a SiSU document you optionally provide semantic information related to the document in a document header, and in marking up the substantive text provide information on the structure of the document, primarily indicating heading levels and footnotes. You also provide information on basic text attributes where used. The rest is automatic, sisu from this information custom builds~{ i.e. the HTML, PDF, EPUB, ODT outputs are each built individually and optimised for that form of presentation, rather than for example the html being a saved version of the odf, or the pdf being a saved version of the html. }~ the different forms of output requested.
+
+SiSU works with an abstraction of the document based on its structure which is comprised of its headings~{ the different heading levels }~ and objects~{ units of text, primarily paragraphs and headings, also any tables, poems, code-blocks }~, which enables SiSU to represent the document in many different ways, and to take advantage of the strengths of different ways of presenting documents. The objects are numbered, and these numbers can be used to provide a common basis for citing material within a document across the different output format types. This is significant as page numbers are not well suited to the digital age, in web publishing, changing a browser's default font or using a different browser can mean that text will appear on a different page; and publishing in different formats, html, landscape and portrait pdf etc. again page numbers are not useful to cite text. Dealing with documents at an object level together with object numbering also has implications for search that SiSU is able to take advantage of.
+
+One of the challenges of maintaining documents is to keep them in a format that allows use of them independently of proprietary platforms. Consider issues related to dealing with legacy proprietary formats today and what guarantee you have that old proprietary formats will remain (or can be read without proprietary software/equipment) in 15 years time, or the way the way in which html has evolved over its relatively short span of existence. SiSU provides the flexibility of producing documents in multiple non-proprietary open formats including HTML, EPUB,~{ An open standard format for e-books }~ ODT,~{ Open Document Format (ODF) text }~ PDF~{ Specification submitted by Adobe to ISO to become a full open ISO specification \\ http://www.linux-watch.com/news/NS7542722606.html }~ ODF,~{ ISO standard ISO/IEC 26300:2006 }~. Whilst SiSU relies on software, the markup is uncomplicated and minimalistic which guarantees that future engines can be written to run against it. It is also easily converted to other formats, which means documents prepared in SiSU can be migrated to other document formats. Further security is provided by the fact that the software itself, SiSU is available under GPLv3 a licence that guarantees that the source code will always be open, and free as in libre, which means that that code base can be used, updated and further developed as required under the terms of its license. Another challenge is to keep up with a moving target. SiSU permits new forms of output to be added as they become important, (Open Document Format text was added in 2006 when it became an ISO standard for office applications and the archival of documents), EPUB was introduced in 2009; and allows the technical representations existing output to be updated (HTML has evolved and the related module has been updated repeatedly over the years, presumably when the World Wide Web Consortium (w3c) finalises HTML 5 which is currently under development, the HTML module will again be updated allowing all existing documents to be regenerated as HTML 5).
+
+SiSU also provides other features such as concordance files and document content certificates, and the working against an abstraction of document structure has further possibilities for the research and development of other document representations, the availability of objects is useful for example for topic maps and thesauri, together with the flexibility of SiSU offers great possibilities.
+
+SiSU is primarily for published works, which can take advantage of the citation system to reliably reference its documents. SiSU works well in a complementary manner with such collaborative technologies as Wikis, which can take advantage of and be used to discuss the substance of content prepared in SiSU.
+
+% SiSU is a way of preparing, publishing, managing and searching documents.
+
 SiSU is a flexible document preparation, generation publishing and search system.~{ This information was first placed on the web 12 November 2002; with predating material taken from http://www.jus.uio.no/lm/lm.information/toc.html part of a site started and developed since 1993. See document metadata section http://www.jus.uio.no/sisu/SiSU/metadata.html or manifest page http://www.jus.uio.no/sisu/SiSU/sisu_manifest.html for information on this version. Dates related to the development of SiSU may be tracked in the http://www.jus.uio.no/sisu/SiSU/changelog.html or the Git repository http://git.sisudoc.org/?p=code/sisu.git;a=summary some of the more significant events may be contained within the Chronology section of this document http://www.jus.uio.no/sisu/sisu_chronology }~
 
 SiSU ("SiSU information Structuring Universe" or "Structured information, Serialized Units"),~{ also chosen for the meaning of the Finnish term "sisu". }~ is a Unix command line oriented framework for document structuring, publishing and search. Featuring minimalistic markup, multiple standard outputs, a common citation system, and granular search.
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_download.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi
index 96c97985..96c97985 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_download.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_examples.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi
index cf9df9d5..cf9df9d5 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_examples.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_examples.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_faq.sst b/data/doc/sisu/markup-samples/manual/en/sisu_faq.sst
index 966cea5f..966cea5f 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_faq.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_faq.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_filetypes.sst b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst
index d36acac0..d36acac0 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_filetypes.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_filetypes.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_help.sst b/data/doc/sisu/markup-samples/manual/en/sisu_help.sst
index 69535085..69535085 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_help.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_help.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_help_sources.sst b/data/doc/sisu/markup-samples/manual/en/sisu_help_sources.sst
index bee5ed78..bee5ed78 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_help_sources.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_help_sources.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_homepages.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi
index 3d8d95d5..3d8d95d5 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_homepages.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_homepages.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_how.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi
index 3372bcd4..3372bcd4 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_how.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_how.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_howto.sst b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst
index 4a23bdfe..4a23bdfe 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_howto.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_howto.sst
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
new file mode 100644
index 00000000..dfd56ec8
--- /dev/null
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst
@@ -0,0 +1,186 @@
+% SiSU insert 5.0
+
+@title: SiSU
+ :subtitle: Installation
+
+@creator:
+ :author: Amissah, Ralph
+
+@date:
+ :published: 2007-09-16
+ :created: 2002-11-12
+ :issued: 2002-11-12
+ :available: 2002-11-12
+ :modified: 2014-02-05
+
+@rights:
+ :copyright: Copyright (C) Ralph Amissah 2007
+ :license: GPL 3 (part of SiSU documentation)
+
+:A~? SiSU Installation notes
+
+1~source_tarball Source tarball
+
+2~ run off source package directory tree (without installing)
+
+1. Download the latest source (information available) from: http://www.jus.uio.no/sisu/SiSU/download.html#current
+
+2. Unpack the source
+
+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)
+
+Gem install, you need to:
+
+(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install the gem
+
+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)
+
+separate gems are made/installed for sisu v5 & sisu v6 contained in source:
+
+_1 rake gem_create_build_install_stable # (to build and install sisu v5, alias gem5cbi)
+
+_1 rake gem_create_build_install_unstable # (to build and install sisu v6, alias gem6cbi)
+
+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
+
+_1 sisu _6.0.0_ --version
+
+to uninstall sisu installed via gem
+
+_1 sudo gem uninstall --verbose sisu
+
+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
+
+Rant: http://make.rubyforge.org/ http://rubyforge.org/frs/?group_id=615
+
+2~ installation with setup.rb
+
+It should also be possible to install sisu using setup.rb
+
+this is a three step process, in the root directory of the unpacked SiSU as root type:
+
+``` code
+ruby setup.rb config
+ruby setup.rb setup
+#[as root:]
+ruby setup.rb install
+```
+
+further information: \\
+http://i.loveruby.net/en/projects/setup/ \\
+http://i.loveruby.net/en/projects/setup/doc/usage.html
+
+_1 ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
+
+1~distribution_install Unix/Linux Distribution
+
+A distribution install should take care of the dependencies of sisu for producing various outputs.
+
+2~ Debian
+
+SiSU is available off the Debian archives. It should necessary only to run as root, Using apt-get:
+
+code{
+
+  apt-get update
+
+  apt get install sisu-complete
+
+}code
+
+(all sisu dependencies should be taken care of)
+
+If there are newer versions of SiSU upstream, they will be available by
+adding the following to your sources list /etc/apt/sources.list *~sources.list
+
+code{
+
+#/etc/apt/sources.list
+
+deb http://www.jus.uio.no/sisu/archive unstable main non-free
+deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+
+}code
+
+The non-free section is for sisu markup samples provided, which contain authored works the substantive text of which cannot be changed, and which as a result do not meet the debian free software guidelines.
+
+SiSU is developed on Debian, and packages are available for Debian that take care of the dependencies encountered on installation.
+
+The package is divided into the following components:
+
+_1 *sisu*, the base code, (the main package on which the others depend), without any dependencies other than ruby (and for convenience the ruby webrick web server), this generates a number of types of output on its own, other packages provide additional functionality, and have their dependencies
+
+_1 *sisu-complete*, a dummy package that installs the whole of greater sisu as described below, apart from sisu-examples
+
+_1 *sisu-pdf*, dependencies used by sisu to produce pdf from LaTeX generated
+
+_1 *sisu-postgresql*, dependencies used by sisu to populate postgresql database (further configuration is necessary)
+
+_1 *sisu-sqlite*, dependencies used by sisu to populate sqlite database
+
+_1 *sisu-markup-samples*, sisu markup samples and other miscellany (under Debian Free Software Guidelines non-free)
+
+SiSU is available off { Debian Unstable and Testing }http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu ~{ http://packages.qa.debian.org/s/sisu.html }~ install it using apt-get, aptitude or alternative Debian install tools. *~apt-get
+
+1~dependencies Dependencies
+
+Here is a list of sisu's current dependencies,~{from the Debian control file}~ which depend on such factors as whether you want to generate pdf, whether you will be using SiSU with or without a database, ...). sisu_markup-samples may also be of interest.
+
+``` code
+Package: sisu
+Depends: ruby | ruby-interpreter, openssl, rsync, unzip, zip
+Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick |
+graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
+ruby-rmagick, tidy, tree, vim-addon-manager
+Suggests: lv, calibre, pinfo, poedit, texinfo, trang
+```
+
+``` code
+Package: sisu-complete
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
+${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
+${source:Version})
+Description-en: installs all SiSU related packages
+```
+
+``` code
+Package: sisu-pdf
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
+texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
+texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
+texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
+Suggests: evince | pdf-viewer
+```
+
+``` code
+Package: sisu-postgresql
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
+ruby-dbd-pg, ruby-dbi, ruby-fcgi
+Suggests: postgresql-contrib
+```
+
+``` code
+Package: sisu-sqlite
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
+ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
+```
+
+``` code
+Package: sisu-markup-samples
+Depends: sisu
+```
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_installation.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi
index f908bb6e..f908bb6e 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_installation.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_installation.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_interesting_to_whom.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_interesting_to_whom.ssi
index 750c46ea..750c46ea 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_interesting_to_whom.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_interesting_to_whom.ssi
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst b/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst
new file mode 100644
index 00000000..1fc14d9a
--- /dev/null
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_introduction.sst
@@ -0,0 +1,43 @@
+% SiSU 5.0
+
+@title: SiSU
+ :subtitle: Introduction
+
+@creator:
+ :author: Amissah, Ralph
+
+@date:
+ :published: 2007-09-16
+ :created: 2002-08-28
+ :issued: 2002-08-28
+ :available: 2002-08-28
+ :modified: 2014-02-05
+
+@rights:
+ :copyright: Copyright (C) Ralph Amissah 2011
+ :license: GPL 3 (part of SiSU documentation)
+
+@classify:
+ :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
+
+:A~? @title @creator
+
+:B~? What is SiSU?
+
+1~sisu_intro Introduction - What is SiSU?
+
+SiSU is a lightweight markup based document creation and publishing framework that is controlled from the command line. Prepare documents for SiSU using your text editor of choice, then use SiSU to generate various output document formats.
+
+From a single lightly prepared document (plain-text UTF-8) sisu custom builds several standard output formats which share a common (text object) numbering system for citation of content within a document (that also has implications for search). The sisu engine works with an abstraction of the document's structure and content from which it is possible to generate different forms of representation of the document. SiSU produces: plain-text, HTML, XHTML, XML, EPUB, ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or SQLite) with text objects, roughly, paragraph sized chunks so that document searches are done at this level of granularity.
+
+Outputs share a common citation numbering system, associated with text objects and any semantic meta-data provided about the document.
+
+SiSU also provides concordance files, document content certificates and manifests of generated output. Book indexes may be made.
+
+Some document markup samples are provided in the package sisu-markup-samples.
+
+``` group
+Homepages:
+* http://www.sisudoc.org/
+* http://www.jus.uio.no/sisu
+```
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_manual.ssm b/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm
index 90e8a323..46d80198 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_manual.ssm
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_manual.ssm
@@ -1,4 +1,4 @@
-% SiSU master 4.0
+% SiSU master 5.0
 
 @title: SiSU
  :subtitle: Manual
@@ -11,7 +11,7 @@
  :created: 2002-08-28
  :issued: 2002-08-28
  :available: 2002-08-28
- :modified: 2012-10-03
+ :modified: 2014-02-05
 
 @rights:
  :copyright: Copyright (C) Ralph Amissah 2007
@@ -77,7 +77,7 @@
 
 << sisu_download.ssi
 
-<< sisu_installation.ssi
+<< sisu_install_run.sst
 
 << sisu_quickstart.sst
 
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
index 69293637..69293637 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_markup.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_markup_syntax_history.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup_syntax_history.sst
index c6da0a14..c6da0a14 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_markup_syntax_history.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup_syntax_history.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_output_overview.sst b/data/doc/sisu/markup-samples/manual/en/sisu_output_overview.sst
index 332f4aae..332f4aae 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_output_overview.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_output_overview.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_postgresql.sst b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst
index 574e307c..574e307c 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_postgresql.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_postgresql.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_quickstart.sst b/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst
index ae95f528..ae95f528 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_quickstart.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_quickstart.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_remote.sst b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst
index 959fbcf6..959fbcf6 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_remote.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_remote.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search.ssm b/data/doc/sisu/markup-samples/manual/en/sisu_search.ssm
index 9c40a8bf..9c40a8bf 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search.ssm
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search.ssm
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search_cgi.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
index 03eef9ff..03eef9ff 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search_cgi.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_cgi.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search_intro.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
index d5da379f..d5da379f 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_search_intro.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_search_intro.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_short_feature_summary.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi
index 294644af..294644af 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_short_feature_summary.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_short_feature_summary.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_sql.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
index 6e54275b..6e54275b 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_sql.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_sql.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_sqlite.sst b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst
index a73ae16c..a73ae16c 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_sqlite.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_sqlite.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_synopsis.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_synopsis.ssi
index 98e5d4f3..98e5d4f3 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_synopsis.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_synopsis.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_syntax_highlighting.sst b/data/doc/sisu/markup-samples/manual/en/sisu_syntax_highlighting.sst
index ef881aae..ef881aae 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_syntax_highlighting.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_syntax_highlighting.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_webrick.sst b/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst
index 6e56e53a..6e56e53a 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_webrick.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_webrick.sst
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_work_needed_and_wishlist.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_work_needed_and_wishlist.ssi
index 20e774ac..20e774ac 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_work_needed_and_wishlist.ssi
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_work_needed_and_wishlist.ssi
diff --git a/data/doc/sisu/markup-samples/sisu_manual/translation_languages b/data/doc/sisu/markup-samples/manual/translation_languages
index d84a94e8..d84a94e8 100644
--- a/data/doc/sisu/markup-samples/sisu_manual/translation_languages
+++ b/data/doc/sisu/markup-samples/manual/translation_languages
diff --git a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_introduction.sst b/data/doc/sisu/markup-samples/sisu_manual/en/sisu_introduction.sst
deleted file mode 100644
index 8978ace6..00000000
--- a/data/doc/sisu/markup-samples/sisu_manual/en/sisu_introduction.sst
+++ /dev/null
@@ -1,55 +0,0 @@
-% SiSU 4.0
-
-@title: SiSU
- :subtitle: Introduction
-
-@creator:
- :author: Amissah, Ralph
-
-@date:
- :published: 2007-09-16
- :created: 2002-08-28
- :issued: 2002-08-28
- :available: 2002-08-28
- :modified: 2012-10-03
-
-@rights:
- :copyright: Copyright (C) Ralph Amissah 2011
- :license: GPL 3 (part of SiSU documentation)
-
-@classify:
- :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
-
-:A~? @title @creator
-
-:B~? What is SiSU?
-
-:C~? Description
-
-1~sisu_intro Introduction - What is SiSU?
-
-SiSU is a framework for document structuring, publishing (in multiple open standard formats) and search, comprising of: (a) a lightweight document structure and presentation markup syntax; and (b) an accompanying engine for generating standard document format outputs from documents prepared in sisu markup syntax, which is able to produce multiple standard outputs (including the population of sql databases) that (can) share a common numbering system for the citation of text within a document.
-
-SiSU is developed under an open source, software libre license (GPLv3). Its use case for development is work with medium to large document sets and cope with evolving document formats/ representation technologies. Documents are prepared once, and generated as need be to update the technical presentation or add additional output formats. Various output formats (including search related output) share a common mechanism for cross-output-format citation.
-
-SiSU both defines a markup syntax and provides an engine that produces open standards format outputs from documents prepared with SiSU markup. From a single lightly prepared document sisu custom builds several standard output formats which share a common (text object) numbering system for citation of content within a document (that also has implications for search). The sisu engine works with an abstraction of the document's structure and content from which it is possible to generate different forms of representation of the document. Significantly SiSU markup is more sparse than html and outputs which include HTML, EPUB, ODT (Open Document Format text), LaTeX, landscape and portrait PDF, all of which can be added to and updated. SiSU is also able to populate SQL type databases at an object level, which means that searches can be made with that degree of granularity.
-
-Source document preparation and output generation is a two step process: (i) document source is prepared, that is, marked up in sisu markup syntax and (ii) the desired output subsequently generated by running the sisu engine against document source. Output representations if updated (in the sisu engine) can be generated by re-running the engine against the prepared source. Using SiSU markup applied to a document, SiSU custom builds (to take advantage of the strengths of different ways of representing documents) various standard open output formats including plain text, HTML, XHTML, XML, EPUB, ODT, LaTeX or PDF files, and populate an SQL database with objects~{ objects include: headings, paragraphs, verse, tables, images, but not footnotes/endnotes which are numbered separately and tied to the object from which they are referenced. }~ (equating generally to paragraph-sized chunks) so searches may be performed and matches returned with that degree of granularity ( e.g. your search criteria is met by these documents and at these locations within each document). Document output formats share a common object numbering system for locating content. This 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.
-
-In preparing a SiSU document you optionally provide semantic information related to the document in a document header, and in marking up the substantive text provide information on the structure of the document, primarily indicating heading levels and footnotes. You also provide information on basic text attributes where used. The rest is automatic, sisu from this information custom builds~{ i.e. the HTML, PDF, EPUB, ODT outputs are each built individually and optimised for that form of presentation, rather than for example the html being a saved version of the odf, or the pdf being a saved version of the html. }~ the different forms of output requested.
-
-SiSU works with an abstraction of the document based on its structure which is comprised of its headings~{ the different heading levels }~ and objects~{ units of text, primarily paragraphs and headings, also any tables, poems, code-blocks }~, which enables SiSU to represent the document in many different ways, and to take advantage of the strengths of different ways of presenting documents. The objects are numbered, and these numbers can be used to provide a common basis for citing material within a document across the different output format types. This is significant as page numbers are not well suited to the digital age, in web publishing, changing a browser's default font or using a different browser can mean that text will appear on a different page; and publishing in different formats, html, landscape and portrait pdf etc. again page numbers are not useful to cite text. Dealing with documents at an object level together with object numbering also has implications for search that SiSU is able to take advantage of.
-
-One of the challenges of maintaining documents is to keep them in a format that allows use of them independently of proprietary platforms. Consider issues related to dealing with legacy proprietary formats today and what guarantee you have that old proprietary formats will remain (or can be read without proprietary software/equipment) in 15 years time, or the way the way in which html has evolved over its relatively short span of existence. SiSU provides the flexibility of producing documents in multiple non-proprietary open formats including HTML, EPUB,~{ An open standard format for e-books }~ ODT,~{ Open Document Format (ODF) text }~ PDF~{ Specification submitted by Adobe to ISO to become a full open ISO specification <br> http://www.linux-watch.com/news/NS7542722606.html }~ ODF,~{ ISO standard ISO/IEC 26300:2006 }~. Whilst SiSU relies on software, the markup is uncomplicated and minimalistic which guarantees that future engines can be written to run against it. It is also easily converted to other formats, which means documents prepared in SiSU can be migrated to other document formats. Further security is provided by the fact that the software itself, SiSU is available under GPLv3 a licence that guarantees that the source code will always be open, and free as in libre, which means that that code base can be used, updated and further developed as required under the terms of its license. Another challenge is to keep up with a moving target. SiSU permits new forms of output to be added as they become important, (Open Document Format text was added in 2006 when it became an ISO standard for office applications and the archival of documents), EPUB was introduced in 2009; and allows the technical representations existing output to be updated (HTML has evolved and the related module has been updated repeatedly over the years, presumably when the World Wide Web Consortium (w3c) finalises HTML 5 which is currently under development, the HTML module will again be updated allowing all existing documents to be regenerated as HTML 5).
-
-The document formats are written to the file-system and available for indexing by independent indexing tools, whether off the web like Google and Yahoo or on the site like Lucene and Hyperestraier.
-
-SiSU also provides other features such as concordance files and document content certificates, and the working against an abstraction of document structure has further possibilities for the research and development of other document representations, the availability of objects is useful for example for topic maps and thesauri, together with the flexibility of SiSU offers great possibilities.
-
-SiSU is primarily for published works, which can take advantage of the citation system to reliably reference its documents. SiSU works well in a complementary manner with such collaborative technologies as Wikis, which can take advantage of and be used to discuss the substance of content prepared in SiSU.
-
-http://www.sisudoc.org/
-
-http://www.jus.uio.no/sisu
-
-% SiSU is a way of preparing, publishing, managing and searching documents.