path: root/data/doc/sisu/README

SiSU 0.49 2007w08/5 20070223
homepage: http://www.jus.uio.no/sisu

%% 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, ODF:ODT
  (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or
  SQLite) in paragraph sized chunks so that document searches are done at this
  "atomic" level of granularity.
 
  Outputs share a common citation numbering system, and any semantic meta-data
  provided about the document.
 
  SiSU also provides concordance files, document content certificates and
  manifests of generated output.

    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 remaining simple. SiSU implements across document formats a "useful
    common feature set" [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).
 
  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

-----

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

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

%% 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
or the same:
  http://www.jus.uio.no/sisu/sisu_download/download.html#current
  http://www.jus.uio.no/sisu/sisu_download/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
  http://www.jus.uio.no/sisu/sisu_download/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
  http://www.jus.uio.no/sisu/sisu_download/download.html#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.html#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 (prapared with "Rant")
---------------
in the root directory of the unpacked SiSU as root type:
  ruby install

or
  ruby 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 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_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
Depends: ruby (>= 1.8.4), libwebrick-ruby
Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
  tidy, librexml-ruby, zip, unzip, openssl, rsync, openssh-client | lsh-client,
  keychain, hyperestraier, kdissert
Suggests: libfcgi-ruby1.8, rcs | cvs, lv, texinfo, pinfo, rename

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

Package: sisu-pdf
Depends: sisu, tetex-bin | texlive-base-bin, tetex-extra | texlive-latex-extra,
  texlive-latex-extra, latex-ucs
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/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

%% 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

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

See man pages.
  man 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/sisu_markup_samples/dfsg

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

More markup samples are available in the package 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/conf/syntax

usually installed to:

  /usr/share/sisu/conf/syntax

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

License: GPL 2 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