homepage: http://www.jus.uio.no/sisu

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

SiSU - simple information structuring universe, is a publishing tool, document
generation and management, (and search enabling) tool primarily for literary, 
academic and legal 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 (in my
case Reiserfs), and/or database Postgresql.

Amongst it's characteristics are: 

* simple mnemonoic markup style,

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

* 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 in
which the match is found 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, and run
using a term or from a windows box using putty.

* 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.

It currently works on ascii, but should be possible to port to Unicode (UTF-8)
in future.

Little time has been spent so far on installation/setup.

Once set up it is simple to use.

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

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

Download Sources:
  http://www.jus.uio.no/sisu/SiSU/download#current
  http://www.jus.uio.no/sisu/SiSU/download#debian
or the same:
  http://www.jus.uio.no/sisu/sisu_download/download#current
  http://www.jus.uio.no/sisu/sisu_download/download#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/download#debian
  http://www.jus.uio.no/sisu/SiSU/download#debian

1. Add the following line to your /etc/apt/sources.list

   deb http://www.jus.uio.no/sisu/pkg ./deb/

2.  apt-get sisu sisu-examples

3. read the manual pages as needed:
     'man 8 sisu' 
     'man sisu_examples' [if the sisu-examples package is also installed]
     'man sisu'

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

two alternative modes of installation from source are provided, 
setup.rb (by Minero Aoki) and a rant(by Stefan Lang) built install file,
in either case: the first steps are the same, download and unpack the 
source file:

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

2. Unpack the source

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 (Rant)
---------------
in the root directory of the unpacked SiSU as root type:

   ruby install

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 install help
  ruby 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_examples' may also be of
interest if the sisu-examples package has also been installed.

Further note
---------------

The following is taken from the Debian control file and gives an idea of
additional packages that SiSU can make use of if available, (the
use/requirement of some of wich are interdependent for specific actions by
SiSU):

Depends: ${misc:Depends}, ruby (>=1.8.2)

Recommends: tetex-bin, tetex-extra, latex-ucs, postgresql (>=8.0.0), sqlite,
libdbi-ruby, libdbm-ruby, libdbd-pg-ruby, libsqlite, libdbd-sqlite-ruby,
librmagick-ruby, trang, tidy, libtidy, librexml-ruby, sisu-examples,
vim-ruby|vim-full|vim-gtk|vim-gnome, sisu-vim, zip, unzip

Suggests: makeinfo, pgaccess, texinfo, pinfo, libfcgi-ruby1.8, libdbd-pgsql,
libdbd-sqlite, rsync, openssl, openssh-client|openssh-client, keychain,
rcs|cvs, evince, lv

%% Setup/configure
---------------

Most of the installation should be taken care of by the Rant install, which if
run in full will also test run the generation of the first document.

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

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

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

* 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 .s3

Marked up SiSU documents are usually kept in a sub-directory of your choosing
(within ~/)

sisu -C in your marked up document directory, should do some auto-configuring
provided you have the right permissions for the output directories.

use the interactive help

%% External Programs

SiSU makes use of the following programs for the following purposes

Linux/Unix platform

Ruby > 1.8 required

general

  * wc (word count) [recommended] is used so as not to create wordmaps, indexes
  on files that are over 200,000 words, takes a bit long, but more importantly
  resulting output of indexed words becomes so large as to freeze browser.

html

no external programs

XML

  no external programs to generate

  external programs to check XML is well formed:

  * tidy [recommended] is used when SiSU is run in verbose mode to check that
  XML output is well formed and without errors

  * rexml (ruby xml parser) [recommended - should be part of ruby distribution]
  is used in verbose mode, to read in document headers and write them to screen
  in verbose mode (double check that output document is well formed)

latex/pdf 

  * pdflatex [required for pdfs] is used to produce pdf output from latex
  written by SiSU

Database [not required as sisu will work off file system, however provides
wonderful possibilities]

  * postgresql used as database

  * sqlite used as database [however this module is for the time being not
  functional]

  * (dbi which is part of the Ruby distribution)

other

  * spell uses aspell or ispell, default currently aspell


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

interactive help described below, or man page:

  man sisu

 man 8 sisu
 'man sisu_examples' [if the sisu-examples 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 headers
  sisu help markup
  sisu help headings
  etc.

for questions about output paths 
  sisu help path
  sisu help directory

%% Directory Structure
---------------

You are probably better off reading the man pages.

SiSU needs to know where the files it produces are to be written, I write
directly to the web server directory, which on Debian is /var/www

SiSU is writes its output (html/xml/pdf etc.) to a directory, in my case to a
sub-directory in /var/www that takes its name from the directory used for file
markup, eg. if i markup text in ~/sisu the output directory would be
/var/www/sisu in which a sub-directory will be created named after the document
being processed. The default for this is:
 /var/www
(for which check permissions) and in its absence [not tested]:
  ~/sisu_output

SiSU also writes intermediate files to a processing directory. Amongst other
tools used LaTeX requires this.
The default for this is:
  ~/sisu_processing

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

The defaults can be changed via SiSU's configure file sisurc.yaml which the
program expects to find in ~/.sisu

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

You are probably better off reading the man pages.
  man sisu

There is a bit about SiSU Markup in the file:
  SiSU_MARKUP.txt

Alternatively 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/sisu/sample/document_samples_sisu_markup

These are installed on the system usually at:
  /usr/share/sisu/sample/document_samples_sisu_markup

To find out where during the installation run:
  rant system
  (and examine the section on directories)

Online sample markup is provided at:
  http://www.jus.uio.no/sisu/SiSU/2#markup

And a general markup table at:
  http://www.jus.uio.no/sisu/sisu_markup_table/markup

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

Vim Syntax Hi-lighter

Vim Folds

%% Currently Unmaintained Modules
---------------

Sqlite
Lout

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

 * License: GPL 2 or later

  GPL2 summary:

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License
    http://www.gnu.org/copyleft/gpl.html
  as published by the Free Software Foundation;
    http://www.gnu.org/fsf/fsf.html
  either version 2 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.

  You should have received a copy of the GNU General Public License along
  with this program; if not, write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA  

  If you have Internet connection, the latest version of the GPL should be
  available at these locations:
    http://www.fsf.org/licenses/gpl.html
    http://www.gnu.org/copyleft/gpl.html
    http://www.jus.uio.no/sisu/gpl2.fsf

* see also the "SiSU Standard" section

* Ralph Amissah mailto:ralph@amissah.com
  Ralph Amissah mailto:amissah@gmail.com

%% 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 2005.
All Rights Reserved.

* however note the License section


