%% SiSU versions 1 & 2, 2010
Homepage: <http://www.jus.uio.no/sisu>
* README CHANGELOG CHANGELOG_v1 CHANGELOG_v2

Herein (this package) reside SiSU versions 1 and 2.

%% Description
---------------

  SiSU is 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.

  With minimal preparation of a plain-text (UTF-8) file using its native
  markup-syntax, SiSU produces: plain-text, HTML, XHTML, XML, EPUB (v2 only)
  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.

    SiSU takes advantage of well established open standard ways of representing
    text, and provides a bridge to take advantage of the strengths of each,
    while retaining minimal markup requirement. SiSU implements a "useful
    common feature set" across document formats [coming from a humanities, law,
    and possibly social sciences perspective, rather than technical or
    scientific writing] ...  focus is primarily on content and data integrity
    rather than appearance, (though outputs in the various formats are
    respectable).

  Syntax highlighting files for a number of editors are provided.
  A vim syntax highlighting file and an ftplugin with folds for sisu markup is
  provided. Vim 7 includes syntax highlighting for SiSU.

  man pages, and interactive help are provided.

  Dependencies for various features are taken care of in sisu related packages.
  The package sisu-complete installs the whole of SiSU.

  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.

  Homepage: <http://www.jus.uio.no/sisu>

%% Take 2
---------

The ideas behind SiSU evolved working with managing static, published documents
that needed to be citable, ideally searchable and preferably available in
multiple formats over a period of time with a rapidly changing World Wide Web.
Initial experience was in 1993, one issue being that the document content
remained the same, but presentation needed to be updated with changing formats,
html in particular has really changed since then.

So the idea was to provide a minimal markup requirement for documents that
remained the same, and a generator to convert that markup custom producing
various output types. This made it possible to:

* have a marked-up document set and continue improving the presentation, as the
generators code was updated, e.g. update HTML as it evolves, and improve upon
LaTeX driven pdf output

* have available new document formats/ output types as they came to be of
interest, e.g. version 2 includes EPUB

* produce a citation system that is available across different output types,
text based on objects (rather than page numbers), i.e. you can accurately and
reliably cite text within a document regardless of the document format version
that is being looked at

* take advantage of the strengths of disparate technologies representing text,
each output type being custom generated for that format, the object citation
system lends itself as a result is that there is little necessity that one
output type should be based on or related to another, just that the content is
preserved and presented in a way that is well suited to the output type in
question

* produce consistent quality presentation for material, suitable where
substance/content is more important than appearance, there is some sacrifice of
flexibility and no concept of wysiwyg, e.g. there is no attempt to make pdf
output identical to html, rather the system attempts to take advantage of
making the best presentation it can in each output format taking advantage of
the strengths of that format available to it given the minimal markup (sisu
document preparation); the citation system ensures you can pinpoint the same
text 

SiSU works best:

* with published works (e.g. books, articles), static documents the content of
which is changed rarely, and ideally when they do in the form of a new edition.

* for literature and law related content

SiSU uses Unicode, utf-8 where it is available,
-----

SiSU - simple information structuring universe, is a publishing tool, document
generation and management, (and search enabling) tool primarily for literary,
academic and legal published works.

SiSU can be used for Internet, Intranet, local filesystem or cd publishing.

SiSU can be used directly off the filesystem, or from a database.

SiSU's scalability, is be dependent on your hardware, and filesystem and/or
database Postgresql.

Amongst it's characteristics are:

* simple mnemonoic markup style,

* the ability to produce multiple output formats, including html, XML, EPUB,
LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining
document structure - Postgresql and Sqlite,

* that all share a common citation system (a simple idea from which much good),
possibly most exciting, the following: if fed into a relational database (as it
can be automatically), the document set is searchable, with results displayed
at a paragraph level, or the possibility of an indexed display of documents
identifying the paragraph in which the match is found (using the object
citation numbering system) together with a hyperlinked listing for each of each
paragraph in which the match is found. In any event citations using this system
(with or without the relational database) are relevant for all output formats.

* it is command line driven, and can be set up on a remote server

* Documents are marked up in SiSU syntax in your favourite editor. SiSU syntax
may be regarded as a type of smart ascii - which in its basic form is simpler
than the most elementary html. There is currently a syntax highlighter, and
folding for Vim. Syntax highlighters for other editors are welcome.

Input files should be UTF-8

Once set up it is simple to use.

%% Information, places to look
---------------

Within the SiSU tarball:

  ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual

Once installed, directory equivalent to:

  <file:///usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/>

Available man pages are converted back to html using man2html:

  <file:///usr/share/doc/sisu/v2/html/>

  ./data/doc/sisu/v2/html/

%% Online Information, places to look
---------------

  <http://www.jus.uio.no/sisu>

Download Sources:
  <http://www.jus.uio.no/sisu/SiSU/download.html#current>
  <http://www.jus.uio.no/sisu/SiSU/download.html#debian>

%% Installation
---------------
NB. Platform is Unix / Linux.

%% Debian
---------------
If you use Debian use the Debian packages,
check the information at:
  <http://www.jus.uio.no/sisu/SiSU/download.html#debian>

(A) SiSU is available directly off the Debian archives for Sid and testing. It
should necessary only to run as root:

  aptitude update
  aptitude install sisu-complete

(B) If there are newer versions of SiSU upstream of the Debian archives, they
will be available by adding the following to your /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

   [the non-free line is for document markup
   samples, for which the substantive text is
   provided under the author or original
   publisher's license and which in most cases will
   not be debian free software guideline compliant]

Then as root run:
  aptitude update
  aptitude install sisu-complete

%% RPM
---------------
RPMs are provided though untested, they are prepared by running alien against the
source package, and against the debs.

They may be downloaded from:
  <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>

%% Source package .tgz
---------------
Otherwise to install SiSU from source, check information at:
  <http://www.jus.uio.no/sisu/SiSU/download.html#current>

alternative modes of installation from source are provided,
setup.rb (by Minero Aoki),
rake (by Jim Weirich) built install file,
rant (by Stefan Lang) built install file,

Ruby is the essential dependency for the basic operation of SiSU

1. Download the latest source (information available) from:
  <http://www.jus.uio.no/sisu/SiSU/download.html#current>

2. Unpack the source

Note however, that additional external package dependencies,
such as texlive or postgresql should you desire to use it
are not taken care of for you.

%% to use setup.rb
---------------
this is a three step process,
in the root directory of the unpacked SiSU as root type:

    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>

%% to use install (prapared with "Rake")
---------------
Rake must be installed on your system:
  <http://rake.rubyforge.org/>
  <http://rubyforge.org/frs/?group_id=50>

in the root directory of the unpacked SiSU as root type:
  rake

or
  rake base

This makes use of Rake (by Jim Weirich) and the provided Rakefile

For a list of alternative actions you may type:
  rake help
  rake -T

%% to use install (prapared with "Rant")
---------------
(you may use the instructions above for rake substituting rant if rant is
installed on your system, or you may use an independent installer created using
rant as follows:)

in the root directory of the unpacked SiSU as root type:
  ruby ./sisu-install

or
  ruby ./sisu-install base

This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been
configured to do post installation setup setup configuration and generation of
first test file. Note however, that additional external package dependencies,
such as tetex-extra are not taken care of for you.

  further information:
    <http://make.rubyforge.org/>
    <http://rubyforge.org/frs/?group_id=615>

For a list of alternative actions you may type:
  ruby ./sisu-install help
  ruby ./sisu-install -T

Dependencies
--------------
Once installed see 'man 8 sisu' for some information on additional programs
that sisu makes use of, and that you may need or wish to install. (this will
depend on such factors as whether you want to generate pdf, whether you will be
using SiSU with or without a database, ...) 'man sisu_markup-samples' may also be of
interest if the sisu-markup-samples package has also been installed.

The information in man 8 may not be most up to date, and it is possible that
more useful information can be gleaned from the following notes taken from the
Debian control file (end edited), 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):

Package: sisu
Architecture: all
Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip
Conflicts: vim-sisu, sisu-vim, sisu-remote
Replaces: vim-sisu, sisu-vim
Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain,
hyperestraier, kdissert, vim-addon-manager
Suggests: rcs | cvs, lv, texinfo, pinfo

Package: sisu-complete
Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
Recommends: hyperestraier

Package: sisu-pdf
Architecture: all
Depends: sisu, texlive-latex-base, texlive-fonts-recommended,
texlive-latex-recommended, texlive-latex-extra
Suggests: evince, xpdf

Package: sisu-postgresql
Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby
Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1

Package: sisu-sqlite
Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
Suggests: libdbd-sqlite

Package: sisu-markup-samples
Depends: sisu

%% Quick start
---------------
Most of the installation should be taken care of by the aptitude or rant
install. (The rant install if run in full will also test run the generation of
the first document).

After installation of sisu-complete, move to the document samples directory

  cd /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg

and run

  sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

[or the same:
  sisu  -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
]

look at output results, see the "sisu_manifest" page created for the document

or to generate an online document move to a writable directory, as the file
will be downloaded there and e.g.

sisu -3 http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst

the database stuff is extra perhaps, the latex stuff could be considered extra
perhaps but neither needs to be installed for most of sisu output to work

examine source document, vim has syntax support

gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst

additional markup samples in
<http://www.jus.uio.no/sisu/SiSU/2.html>

For help
 man sisu

or
 sisu --help

e.g.
sisu --help env
for the way sisu "sees/maps" your system
sisu --help commands
for list of commands and so on

%% Configuration files
---------------

The default configuration/setup is contained within the program and is altered
by configuration settings in /etc/[sisu version]/sisurc.yml
or in ~/.sisu/sisurc.yml

* configuration file - a yaml file
  /etc/sisu/[sisu version]/sisurc.yml
  ~/.sisu/sisurc.yml

* directory structure - setting up of output and working directory.

* skins - changing the appearance of a project, directory or individual
documents within ~/.sisu/skin
  ~/.sisu/skin/doc contains individual skins, with symbolic links from
  ~/.sisu/skin/dir if the contents of a directory are to take a particular
  document skin.

* additional software - eg. Tex and LaTeX (tetex, tetex-base, tetex-extra on
Debian), Postgresql, [sqlite], trang, tidy, makeinfo,  ... none of which are
required for basic html or XML processing.

* if you use Vim as editor there is a syntax highlighter and fold resource
config file for SiSU. I hope more syntax highlighters follow.

There are post installation steps (which are really part of the overall
installation)

sisu -C in your marked up document directory, should do some auto-configuring
provided you have the right permissions for the output directories. (and
provided the output directories have already been specified if you are not
using the defaults).

%% Use General Overview
---------------
Documents are marked up in SiSU syntax and kept in an ordinary text editable
file, named with the suffix .sst, or .ssm

Marked up SiSU documents are usually kept in a sub-directory of your choosing

use the interactive help and man pages
  sisu --help
  man sisu

%% Help
---------------

interactive help described below, or man page:

  man sisu

  man 8 sisu
 'man sisu_markup-samples' [if the sisu-markup-samples package is also installed]

Once installed an interactive help is available typing 'sisu' (without) any
flags, and select an option:

  sisu

alternatively, you could type e.g.
  sisu --help commands
  sisu --help env
  sisu --help headers
  sisu --help markup
  sisu --help headings
  etc.

for questions about mappings, output paths etc.
  sisu --help env
  sisu --help path
  sisu --help directory

%% Directory Structure
---------------
Once installed, type:
  sisu --help env
or
  sisu -V

%% Configuration File
---------------

The defaults can be changed via SiSU's configure file sisurc.yml which the
program expects to find in ./_sisu ~/.sisu or /etc/sisu (searched in that
order, stopping on the first one found)

%% Markup
---------------

See man pages.
  man sisu

  man 8 sisu

Once installed there is some information on SiSU Markup in its help:
  sisu --help markup
and
  sisu --help headers

Sample marked up document are provided with the download tarball in the
directory:
  ./data/doc/sisu/v2/sisu_markup_samples/dfsg

These are installed on the system usually at:
  /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg

More markup samples are available in the package sisu-markup-samples
  <http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples>

Many more are available online off:
  <http://www.jus.uio.no/sisu/SiSU/2.html>

%% Additional Things
---------------

There is syntax support for some editors provided (together with a README file) in

  ./data/sisu/v2/conf/editor-syntax-etc

usually installed to:

  /usr/share/sisu/v2/conf/editor-syntax-etc

v1, v2 Changes
---------------

See changelogs

From a developer's perspective the substantive change between the two versions
is to the middle layer, (the document abstraction, the intermediate document
representation used in processing).  Version 1 uses strings and relies on
regular expressions to identify document objects, while Version 2 uses ruby
objects. The version 1 approach whilst programming language neutral offers less
control, and leads to complicated code; version 2 approach takes advantage of
features within the ruby language suited to what the application does.
Development is curently on version 2, version 1 is likely to remain for some
time as a reference implementation.

%% v1, v2 Compatibility Notes
---------------

Versions 1 and 2 are not quite compatible, version 1 and version 2 will run
against each other's documents but document metadata, and processing
instructions may be lost.

On the input side, version 1 and 2 headers are different, version 2 headers
have been tidied, see document markup samples provided

On the output side, the sql databases produced if search is to be implemented
are not the same and a database must be generated for each version, most other
differences should be relatively cosmetic.

%% License
---------------

License: GPL 3 or later see the copyright file in

  ./data/doc/sisu

usually installed to:

  /usr/share/doc/sisu

%% SiSU Standard
-----------------

SiSU uses:

*  Standard SiSU markup syntax,
*  Standard SiSU meta-markup syntax, and the
*  Standard SiSU object citation numbering and system

© Ralph Amissah 1997, current 2006.
All Rights Reserved.

* however note the License section

CHANGELOG
  ./CHANGELOG
and see
  <http://www.jus.uio.no/sisu/SiSU/changelog.html>
  <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>