SiSU - Manual,
Ralph Amissah

  1

What is SiSU?

  2

Extracts from the README

  1714

42. README

42. README

  1715

SiSU 0.55 2007w27/6 2007-07-07

  1716

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

  1717

Description

  1718

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.

  1719

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.

  1720

Outputs share a common citation numbering system, and any semantic meta-data provided about the document.

  1721

SiSU also provides concordance files, document content certificates and manifests of generated output.

  1722

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

  1723

A vim syntax highlighting file and an ftplugin with folds for sisu markup is provided. Vim 7 includes syntax highlighting for SiSU.

  1724

man pages, and interactive help are provided.

  1725

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

  1726

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.

  1727

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

  1728

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.

  1729

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

  1730

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

  1731

SiSU's scalability, is be dependent on your hardware, and filesystem (in my case Reiserfs), and/or database Postgresql.

  1732

Amongst it's characteristics are:

  1733

  1734

  1735

  1736

  1737

  1738

Input files should be UTF-8

  1739

Once set up it is simple to use.

  1740

42.1 Online Information, places to look

  1741

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

  1742

Download Sources:

  1743

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

  1744

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

  1745

42.2 Installation

  1746

NB. Platform is Unix / Linux.

  1747

42.2.1 Debian

  1748

If you use Debian use the Debian packages, check the information at:

  1749

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

  1750

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

  1751

aptitude update

  1752

aptitude install sisu-complete

  1753

(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

  1754

deb <http://www.jus.uio.no/sisu/archive> unstable main non-free

  1755

deb-src <http://www.jus.uio.no/sisu/archive> unstable main non-free

  1756

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

  1757

Then as root run:

  1758

aptitude update

  1759

aptitude install sisu-complete

  1760

42.2.2 RPM

  1761

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

  1762

They may be downloaded from:

  1763

<http://www.jus.uio.no/sisu/SiSU/download.html#rpm>

  1764

42.2.3 Source package .tgz

  1765

Otherwise to install SiSU from source, check information at:

  1766

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

  1767

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,

  1768

Ruby is the essential dependency for the basic operation of SiSU

  1769

1. Download the latest source (information available) from:

  1770

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

  1771

2. Unpack the source

  1772

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.

  1773

42.2.4 to use setup.rb

  1774

this is a three step process, in the root directory of the unpacked SiSU as root type:

  1775

ruby setup.rb config

  1776

ruby setup.rb setup

  1777

as root:

  1778

ruby setup.rb install

  1779

further information:

  1780

<http://i.loveruby.net/en/projects/setup/>

  1781

<http://i.loveruby.net/en/projects/setup/doc/usage.html>

  1782

42.2.5 to use install (prapared with "Rake")

  1783

Rake must be installed on your system:

  1784

<http://rake.rubyforge.org/>

  1785

<http://rubyforge.org/frs/?group_id=50>

  1786

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

  1787

rake

  1788

or

  1789

rake base

  1790

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

  1791

For a list of alternative actions you may type:

  1792

rake help

  1793

rake -T

  1794

42.2.6 to use install (prapared with "Rant")

  1795

(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:)

  1796

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

  1797

ruby ./sisu-install

  1798

or

  1799

ruby ./sisu-install base

  1800

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.

  1801

further information:

  1802

<http://make.rubyforge.org/>

  1803

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

  1804

For a list of alternative actions you may type:

  1805

ruby ./sisu-install help

  1806

ruby ./sisu-install -T

  1807

42.3 Dependencies

  1808

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.

  1809

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

  1810

The following is from the debian/control file of sisu-0.58.2, which amongst other things provides the dependencies of sisu within Debian.

  1811

  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

  1812

  Source: sisu
  Section: text
  Priority: optional
  Maintainer: Ralph Amissah <ralph@amissah.com>
  Build-Depends: debhelper (>= 5)
  Standards-Version: 3.7.2

  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, hyperestraier, keychain, librmagick-ruby, librexml-ruby, openssl, openssh-client | lsh-client, rsync, tidy, vim-addon-manager
  Suggests: kdissert, lv, rcs | cvs, pinfo, texinfo, trang
  Description: documents - structuring, publishing in multiple formats and search
   SiSU is a lightweight markup based, command line oriented, document
   structuring, publishing and search framework for document collections.
   .
   With minimal preparation of a plain-text, (UTF-8) file, using its native
   markup syntax in your text editor of choice, SiSU can generate various
   document formats (most of which share a common object numbering system for
   locating content), including plain text, HTML, XHTML, XML, OpenDocument text
   (ODF:ODT), LaTeX, PDF files, and populate an SQL database with objects
   (roughly paragraph-sized chunks) so searches may be performed and matches
   returned with that degree of granularity: your search criteria is met by these
   documents and at these locations within each document. Object numbering 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. Document outputs also share semantic meta-data
   provided.
   .
   SiSU also provides concordance files, document content certificates and
   manifests of generated output.
   .
   A vim syntax highlighting file and an ftplugin with folds for sisu markup is
   provided, as are syntax highlighting files for kate, kwrite, gedit and
   diakonos. 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>

  1813

  Package: sisu-complete
  Architecture: all
  Depends: ruby (>= 1.8.2), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
  Recommends: hyperestraier
  Description: installs all SiSU related packages
   This package installs SiSU and related packages that enable sisu to produce
   pdf and to populate postgresql and sqlite databases.
   .
   SiSU is a lightweight markup based document publishing framework.
   .
   See sisu for a description of the package.
   .
    Homepage: <http://www.jus.uio.no/sisu>

  1814

  Package: sisu-pdf
  Architecture: all
  Depends: sisu, texlive-latex-base, texlive-fonts-recommended, texlive-latex-recommended, texlive-latex-extra
  #Suggests: evince, xpdf
  Description: dependencies to convert SiSU LaTeX output to pdf
   This package enables the conversion of SiSU LaTeX output to pdf.
   .
   SiSU is a lightweight markup based document publishing framework.
   .
    Homepage: <http://www.jus.uio.no/sisu>

  1815

  Package: sisu-postgresql
  Architecture: all
  Depends: sisu, libdbd-pg-ruby, libdbi-ruby, libdbm-ruby, postgresql
  Recommends: libfcgi-ruby
  Suggests: postgresql-contrib
  Description: SiSU dependencies for use with postgresql database
   This package enables SiSU to populate a postgresql database. This is done at
   an object/paragraph level, making granular searches of documents possible.
   .
   This relational database feature of SiSU is not required but provides
   interesting possibilities, including that of granular searches of documents
   for matching units of text, primarily paragraphs that can be displayed or
   identified by object citation number, from which an index of documents
   matched and each matched paragraph within them can be displayed.
   .
   SiSU is a lightweight markup based document publishing framework.
   .
    Homepage: <http://www.jus.uio.no/sisu>

  1816

  Package: sisu-sqlite
  Architecture: all
  Depends: sisu, sqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby
  Recommends: libfcgi-ruby
  Description: SiSU dependencies for use with sqlite database
   This package enables SiSU to populate an sqlite database. This is done at an
   object/paragraph level, making granular searches of documents possible.
   .
   This relational database feature of SiSU is not required but provides
   interesting possibilities, including that of granular searches of documents
   for matching units of text, primarily paragraphs that can be displayed or
   identified by object citation number, from which an index of documents
   matched and each matched paragraph within them can be displayed.
   .
   SiSU is a lightweight markup based document publishing framework.
   .
    Homepage: <http://www.jus.uio.no/sisu>

  1817

42.4 Quick start

  1818

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

  1819

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

  1820

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

  1821

and run

  1822

sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

  1823

or the same:

  1824

sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst

  1825

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

  1826

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

  1827

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

  1828

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

  1829

examine source document, vim has syntax support

  1830

gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst

  1831

additional markup samples in

  1832

<http://www.jus.uio.no/sisu/SiSU/2.html>

  1833

For help

  1834

man sisu

  1835

or

  1836

sisu --help

  1837

e.g.

  1838

for the way sisu "sees/maps" your system

  1839

sisu --help env

  1840

for list of commands and so on

  1841

sisu --help commands

  1842

42.5 Configuration files

  1843

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

  1844

  1845

/etc/sisu/[sisu version]/sisurc.yml

  1846

~/.sisu/sisurc.yml

  1847

  1848

* skins - changing the appearance of a project, directory or individual documents within ~/.sisu/skin

  1849

~/.sisu/skin/doc contains individual skins, with symbolic links from

  1850

~/.sisu/skin/dir if the contents of a directory are to take a particular document skin.

  1851

  1852

  1853

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

  1854

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

  1855

42.6 Use General Overview

  1856

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

  1857

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

  1858

use the interactive help and man pages

  1859

sisu --help

  1860

man sisu

  1861

42.7 Help

  1862

interactive help described below, or man page:

  1863

man sisu

  1864

man 8 sisu

  1865

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

  1866

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

  1867

sisu

  1868

alternatively, you could type e.g.

  1869

sisu --help commands

  1870

sisu --help env

  1871

sisu --help headers

  1872

sisu --help markup

  1873

sisu --help headings

  1874

etc.

  1875

for questions about mappings, output paths etc.

  1876

sisu --help env

  1877

sisu --help path

  1878

sisu --help directory

  1879

42.8 Directory Structure

  1880

Once installed, type:

  1881

sisu --help env

  1882

or

  1883

sisu -V

  1884

42.9 Configuration File

  1885

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)

  1886

42.10 Markup

  1887

See man pages.

  1888

man sisu

  1889

man 8 sisu

  1890

Once installed there is some information on SiSU Markup in its help:

  1891

sisu --help markup

  1892

and

  1893

sisu --help headers

  1894

Sample marked up document are provided with the download tarball in the directory:

  1895

./data/doc/sisu/sisu_markup_samples/dfsg

  1896

These are installed on the system usually at:

  1897

/usr/share/doc/sisu/sisu_markup_samples/dfsg

  1898

More markup samples are available in the package sisu-markup-samples

  1899

<http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples>

  1900

Many more are available online off:

  1901

<http://www.jus.uio.no/sisu/SiSU/2.html>

  1902

42.11 Additional Things

  1903

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

  1904

./data/sisu/conf/syntax

  1905

usually installed to:

  1906

/usr/share/sisu/conf/syntax

  1907

42.12 License

  1908

License: GPL 3 or later see the copyright file in

  1909

./data/doc/sisu

  1910

usually installed to:

  1911

/usr/share/doc/sisu

  1912

42.13 SiSU Standard

  1913

SiSU uses:

  1914

  1915

  1916

  1917

© Ralph Amissah 1997, current 2006 All Rights Reserved.

  1918

  1919

CHANGELOG

  1920

./CHANGELOG

  1921

and see

  1922

<http://www.jus.uio.no/sisu/SiSU/changelog.html>

  1923

<http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>

  1924

Output generated by SiSU 0.59.0 2007-09-23 (2007w38/0)
SiSU Copyright ^© Ralph Amissah 1997, current 2007. All Rights Reserved.
SiSU is software for document structuring, publishing and search,
www.jus.uio.no/sisu and www.sisudoc.org
w3 since October 3 1993 ralph@amissah.com

SiSU using:
Standard SiSU markup syntax,
Standard SiSU meta-markup syntax, and the
Standard SiSU object citation numbering and system, (object/text positioning system)
Copyright ^© Ralph Amissah 1997, current 2007. All Rights Reserved.

SiSU is released under GPLv3 or later, <http://www.gnu.org/licenses/gpl.html>

SiSU, developed using Ruby on Debian/Gnu/Linux software infrastructure, with the usual GPL (or OSS) suspects.
Better - "performance, reliability, scalability, security & total cost of ownership" [not to mention flexibility & choice] use of and adherence to open standards (where practical and fair) and it is software libre.
Get With the Future Way Better!