SiSU -->

SiSU

Manual

Ralph Amissah

copy @ SiSU

1

2

1715

42. README

1716

42.1 Online Information, places to look

42.2 Installation

42.2.1 Debian

42.2.2 RPM

42.2.3 Source package .tgz

42.2.4 to use setup.rb

42.2.5 to use install (prapared with "Rake")

42.2.6 to use install (prapared with "Rant")

42.3 Dependencies

42.4 Quick start

42.5 Configuration files

42.6 Use General Overview

42.7 Help

42.8 Directory Structure

42.9 Configuration File

42.10 Markup

42.11 Additional Things

42.12 License

42.13 SiSU Standard

SiSU 0.55 2007w27/6 2007-07-07

1717

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

1718

Description

1719

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.

1720

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.

1721

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

1722

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

1723

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

1724

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

1725

man pages, and interactive help are provided.

1726

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

1727

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.

1728

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

1729

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.

1730

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

1731

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

1732

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

1733

Amongst it's characteristics are:

1734

simple mnemonoic markup style,

1735

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,

1736

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.

1737

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

1738

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.

1739

Input files should be UTF-8

1740

Once set up it is simple to use.

1741

42.1 Online Information, places to look

1742

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

1743

Download Sources:

1744

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

1745

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

1746

42.2 Installation

1747

NB. Platform is Unix / Linux.

1748

1749

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

1750

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

1751

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

1752

aptitude update

1753

aptitude install sisu-complete

1754

(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

1755

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

1756

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

1757

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

1758

Then as root run:

1759

aptitude update

1760

aptitude install sisu-complete

1761

1762

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

1763

They may be downloaded from:

1764

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

1765

42.2.3 Source package .tgz

1766

Otherwise to install SiSU from source, check information at:

1767

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

1768

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,

1769

Ruby is the essential dependency for the basic operation of SiSU

1770

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

1771

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

1772

2. Unpack the source

1773

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.

1774

42.2.4 to use setup.rb

1775

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

1776

ruby setup.rb config

1777

ruby setup.rb setup

1778

1779

ruby setup.rb install

1780

further information:

1781

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

1782

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

1783

42.2.5 to use install (prapared with "Rake")

1784

Rake must be installed on your system:

1785

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

1786

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

1787

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

1788

1789

1790

1791

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

1792

For a list of alternative actions you may type:

1793

1794

1795

42.2.6 to use install (prapared with "Rant")

1796

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

1797

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

1798

ruby ./sisu-install

1799

1800

ruby ./sisu-install base

1801

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.

1802

further information:

1803

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

1804

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

1805

For a list of alternative actions you may type:

1806

ruby ./sisu-install help

1807

ruby ./sisu-install -T

1808

42.3 Dependencies

1809

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.

1810

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

1811

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

1812

  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

1813

  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), ruby (<< 1.9), libwebrick-ruby, unzip, zip
  Conflicts: vim-sisu, sisu-vim, sisu-remote
  Replaces: vim-sisu, sisu-vim
  Recommends: sisu-doc, 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>

1814

  Package: sisu-complete
  Architecture: all
  Depends: ruby (>= 1.8.2), ruby (<< 1.9), sisu, sisu-doc, 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 structuring, publishing and search
   framework for document collections.
   .
   See sisu for a description of the package.
   .
    Homepage: <http://www.jus.uio.no/sisu>

1815

  Package: sisu-doc
  Architecture: all
  Depends: sisu
  Recommends: sisu-pdf, sisu-postgresql, sisu-sqlite
  Description: sisu manual and other documentation for sisu
   Multiple file formats generated output of sisu documentation generated from
   sisu markup source documents included in the main package
   .
   SiSU is a lightweight markup based document structuring, publishing and search
   framework for document collections.
   .
    Homepage: <http://www.jus.uio.no/sisu>

1816

  Package: sisu-pdf
  Architecture: all
  Depends: sisu, texlive-latex-base, texlive-fonts-recommended, texlive-latex-recommended, texlive-latex-extra
  Recommends: sisu-doc
  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 structuring, publishing and search
   framework for document collections.
   .
    Homepage: <http://www.jus.uio.no/sisu>

1817

  Package: sisu-postgresql
  Architecture: all
  Depends: sisu, libdbd-pg-ruby, libdbi-ruby, libdbm-ruby, postgresql
  Recommends: sisu-doc, 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 structuring, publishing and search
   framework for document collections.
   .
    Homepage: <http://www.jus.uio.no/sisu>

1818

  Package: sisu-sqlite
  Architecture: all
  Depends: sisu, sqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby
  Recommends: sisu-doc, 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 structuring, publishing and search
   framework for document collections.
   .
    Homepage: <http://www.jus.uio.no/sisu>

1819

42.4 Quick start

1820

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

1821

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

1822

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

1823

1824

sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

1825

1826

sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst

1827

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

1828

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

1829

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

1830

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

1831

examine source document, vim has syntax support

1832

gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst

1833

additional markup samples in

1834

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

1835

1836

1837

1838

1839

1840

for the way sisu "sees/maps" your system

1841

sisu --help env

1842

for list of commands and so on

1843

sisu --help commands

1844

42.5 Configuration files

1845

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

1846

configuration file - a yaml file

1847

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

1848

~/.sisu/sisurc.yml

1849

directory structure - setting up of output and working directory.

1850

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

1851

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

1852

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

1853

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.

1854

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

1855

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

1856

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

1857

42.6 Use General Overview

1858

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

1859

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

1860

use the interactive help and man pages

1861

1862

1863

1864

interactive help described below, or man page:

1865

1866

1867

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

1868

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

1869

1870

alternatively, you could type e.g.

1871

sisu --help commands

1872

sisu --help env

1873

sisu --help headers

1874

sisu --help markup

1875

sisu --help headings

1876

1877

for questions about mappings, output paths etc.

1878

sisu --help env

1879

sisu --help path

1880

sisu --help directory

1881

42.8 Directory Structure

1882

Once installed, type:

1883

sisu --help env

1884

1885

1886

42.9 Configuration File

1887

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)

1888

1889

1890

1891

1892

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

1893

sisu --help markup

1894

1895

sisu --help headers

1896

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

1897

./data/doc/sisu/sisu_markup_samples/dfsg

1898

These are installed on the system usually at:

1899

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

1900

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

1901

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

1902

Many more are available online off:

1903

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

1904

42.11 Additional Things

1905

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

1906

./data/sisu/conf/syntax

1907

usually installed to:

1908

/usr/share/sisu/conf/syntax

1909

1910

License: GPL 3 or later see the copyright file in

1911

./data/doc/sisu

1912

usually installed to:

1913

/usr/share/doc/sisu

1914

42.13 SiSU Standard

1915

1916

Standard SiSU markup syntax,

1917

Standard SiSU meta-markup syntax, and the

1918

Standard SiSU object citation numbering and system

1919

© Ralph Amissah 1997, current 2006 All Rights Reserved.

1920

however note the License section

1921

1922

1923

1924

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

1925

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

1926

SiSU -->


	Output generated by SiSU 0.59.1 2007-09-25 (2007w39/2) 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!

SiSU manual

SiSU introduction

SiSU configuration

SiSU help sources

What does SiSU do? Summary

SiSU Book Samples and Markup Examples

Wikipedia entry

Ruby Application Archive