SiSU

git

[ document manifest ]

<< previous toc next >>

SiSU - Manual,
Ralph Amissah

What is SiSU?

Introduction - What is SiSU?

How does sisu work?

Summary of features

Help

SiSU Manual
SiSU man pages
SiSU built-in interactive help, [discontinued]

Commands Summary

Description
Document Processing Command Flags

command line modifiers

database commands

Command Line with Flags - Batch Processing

Introduction to SiSU Markup  3 

Summary
Markup Rules, document structure and metadata requirements
Markup Examples
Online
Installed

Markup of Headers

Sample Header
Available Headers

Markup of Substantive Text

Heading Levels
Font Attributes
Indentation and bullets
Hanging Indents
Footnotes / Endnotes
Links
Naked URLs within text, dealing with urls
Linking Text
Linking Images
Link shortcut for multiple versions of a sisu document in the same directory tree
Grouped Text / blocked text
blocked text curly brace syntax
blocked text tic syntax
Tables
Poem
Group
Code
Additional breaks - linebreaks within objects, column and page-breaks
line-breaks
page breaks
Bibliography / References
a markup tagged metadata bibliography section
Tagging citations for inclusion in the Bibliography
Glossary
Book index

Composite documents markup

Substitutions

SiSU filetypes

.sst .ssm .ssi marked up plain text
sisu text - regular files (.sst)
sisu master files (.ssm)
sisu insert files (.ssi)
sisupod, zipped binary container (sisupod.zip, .ssp)

Configuration

Configuration files
config.yml
sisu_document_make

CSS - Cascading Style Sheets (for html, XHTML and XML)

Organising Content - Directory Structure and Mapping

Document Source Directory
General Directories
Document Output Directory Structures
Output Directory Root
Alternative Output Structures
By Language
By Filetype
By Filename
Remote Directories
Sisupod

Homepages

Home page and other custom built pages in a sub-directory

Markup and Output Examples

Markup examples
SiSU Markup Samples

SiSU Search - Introduction

SQL

populating SQL type databases

Postgresql

Name
Description
Synopsis
Commands
create and destroy database
import and remove documents

Sqlite

Name
Description
Synopsis
Commands
create and destroy database
import and remove documents

CGI Search Form

Setup search form
Search - database frontend sample, utilising database and SiSU features, including object citation numbering (backend currently PostgreSQL)
Search Form

sisu_webrick

Name
Synopsis
Description
Summary of man page
Document processing command flags

Remote Source Documents

Remote Document Output

Remote Output

commands
configuration

Remote Servers

Download information

Download SiSU - Linux/Unix

SiSU Current Version - Linux/Unix
Source (tarball tar.gz)
Git (source control management)
Debian
RPM

Source tree

run off source package directory tree (without installing)
Gem install
Gem install with qi (quick install) script
Gem install with rake
misc Gem
direct installation with qi (quick install) script
installation with setup.rb

Unix/Linux Distribution

Debian

Dependencies

Quickstart - Getting Started Howto

Installation
Debian Installation
RPM Installation
Installation from source
Testing SiSU, generating output
basic text, plaintext, html, XML, ODF, EPUB
LaTeX / pdf
relational database - postgresql, sqlite
Getting Help
The man pages
Built in help
The home page
Markup Samples

HowTo

Getting Help

SiSU "man" pages

Setup, initialisation

initialise output directory
Use of search functionality, an example using sqlite
misc
url for output files -u -U
toggle screen color
verbose mode
quiet mode
maintenance mode intermediate files kept -M
start the webrick server
remote placement of output

Configuration Files

Markup

Headers
Font Face
Bold
Italics
Underscore
Strikethrough
Endnotes
Links
Number Titles
Line operations
Tables
Grouped Text
Composite Document

Change Appearance

Skins
CSS

Extracts from the README

README

Online Information, places to look
Installation
Debian
RPM
Source package .tgz
to use setup.rb
to use install (prapared with "Rake")
to use install (prapared with "Rant")
Dependencies
Quick start
Configuration files
Use General Overview
Help
Directory Structure
Configuration File
Markup
Additional Things
License
SiSU Standard

Extracts from man 8 sisu

Post Installation Setup

Post Installation Setup - Quick start
Document markup directory
Configuration files
Debian INSTALLATION Note
Document Resource Configuration

FAQ - Frequently Asked/Answered Questions

Why are urls produced with the -v (and -u) flag that point to a web server on port 8081 ?
I cannot find my output, where is it?
I do not get any pdf output, why?
Where is the latex (or some other interim) output?
Why isn't SiSU markup XML
LaTeX claims to be a document preparation system for high-quality typesetting. Can the same be said about SiSU?
Can the SiSU markup be used to prepare for a LaTex automatic building of an index to the work?
Can the conversion from SiSU to LaTeX be modified if we have special needs for the LaTeX, or do we need to modify the LaTeX manually?
How do I create GIN or GiST index in Postgresql for use in SiSU
Are there some examples of using Ferret Search with a SiSU repository?
Have you had any reports of building SiSU from tar on Mac OS 10.4?
Where is version 1?
What is the difference between version 1 and 2?

Who might be interested in the SiSU feature set?

Work Needed

Wishlist

Editor Files, Syntax Highlighting

Help Sources

man pages
sisu generated output - links to html
www.sisudoc.org
man2html
locally installed
www.jus.uio.no/sisu

Endnotes

Endnotes

Index

Index

Metadata

SiSU Metadata, document information

SiSU - Manual,
Ralph Amissah

What is SiSU?

Extracts from the README

README

Online Information, places to look
Installation
Debian
RPM
Source package .tgz
to use setup.rb
to use install (prapared with "Rake")
to use install (prapared with "Rant")
Dependencies
Quick start
Configuration files
Use General Overview
Help
Directory Structure
Configuration File
Markup
Additional Things
License
SiSU Standard

SiSU 0.55 2007w27/6 2007-07-07

Homepage: ‹http://www.sisudoc.org

old 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, EPUB, 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.sisudoc.org

old 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 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 dependent on your hardware, and filesystem, and/or database Postgresql.

Amongst it's characteristics are:

Input files should be UTF-8

Once set up it is simple to use.

Online Information, places to look

http://www.sisudoc.org

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

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

Source: sisu
Section: text
Priority: optional
Maintainer: SiSU Project <sisu@lists.sisudoc.org>
Uploaders: Ralph Amissah <ralph@amissah.com>
Build-Depends: debhelper (>= 8)
Standards-Version: 3.9.1
Homepage: http://www.sisudoc.org/
Vcs-Browser: http://git.sisudoc.org/gitweb/?p=code/sisu.git
Vcs-Git: git://git.sisudoc.org/git/code/sisu.git
XS-Dm-Upload-Allowed: yes

Package: sisu
Architecture: all
Depends: ${misc:Depends}, ruby (>= 1.8.2), libwebrick-ruby, rsync, unzip, zip
Recommends:
sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick, keychain, librmagick-ruby,
librexml-ruby, openssl, openssh-client | lsh-client, tidy, vim-addon-manager
Suggests: lv, calibre, pinfo, texinfo, trang
Conflicts: sisu-markup-samples (<= 1.0.11)
Replaces: sisu-markup-samples (<= 1.0.11)
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, EPUB, 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.

Package: sisu-complete
Architecture: all
Depends:
${misc:Depends}, ruby (>= 1.8.2), sisu (= ${source:Version}),

sisu-pdf (= ${source:Version}), sisu-postgresql (= ${source:Version}),

sisu-sqlite (= ${source:Version})
Description: installs all SiSU related packages
SiSU is a lightweight markup based document structuring, publishing and search
framework for document collections.
.
This package installs SiSU and related packages that enable sisu to produce
pdf and to populate PostgreSQL and sqlite databases.
.
See sisu for a description of the package.

Package: sisu-pdf
Architecture: all
Depends:
${misc:Depends}, sisu, texlive-latex-base, texlive-fonts-recommended,
texlive-latex-recommended, texlive-latex-extra, texlive-xetex, lmodern,
ttf-liberation
Suggests: evince | pdf-viewer
Description: dependencies to convert SiSU LaTeX output to pdf
SiSU is a lightweight markup based document structuring, publishing and search
framework for document collections.
.
This package enables the conversion of SiSU LaTeX output to pdf.

Package: sisu-pdf
Architecture: all
Depends:
${misc:Depends}, sisu, texlive-latex-base, texlive-fonts-recommended,
texlive-latex-recommended, texlive-latex-extra, texlive-xetex, lmodern,
ttf-liberation
Suggests: evince | pdf-viewer
Description: dependencies to convert SiSU LaTeX output to pdf
SiSU is a lightweight markup based document structuring, publishing and search
framework for document collections.
.
This package enables the conversion of SiSU LaTeX output to pdf.

Package: sisu-postgresql
Architecture: all
Depends:
${misc:Depends}, sisu, libdbd-pg-ruby, libdbd-pg-ruby1.8, libdbi-ruby,
libdbi-ruby1.8, libdbm-ruby, postgresql, libfcgi-ruby1.8 | libfcgi-ruby1.9.1
Suggests: postgresql-contrib
Description: SiSU dependencies for use with PostgreSQL database
SiSU is a lightweight markup based document structuring, publishing and search
framework for document collections.
.
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.

Package: sisu-sqlite
Architecture: all
Depends:
${misc:Depends}, sisu, sqlite3, libsqlite3-ruby, libdbd-sqlite3-ruby,
libdbd-sqlite3-ruby1.8, libdbi-ruby, libdbi-ruby1.8, libdbm-ruby,
libfcgi-ruby1.8 | libfcgi-ruby1.9.1
Description: SiSU dependencies for use with SQLite database
SiSU is a lightweight markup based document structuring, publishing and search
framework for document collections.
.
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.

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/markup-samples/samples

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/src/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/examples.html

For help

man sisu

or

sisu --help

e.g.

for the way sisu "sees/maps" your system

sisu --help env

for list of commands and so on

sisu --help commands

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

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

~/.sisu/sisurc.yml

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/markup-samples/

These are installed on the system usually at:

/usr/share/doc/sisu/markup-samples/

More markup samples are available in the package sisu -markup-samples, which if installed should be available at:

/usr/share/doc/sisu/markup-samples-non-free/

Many more are available online off:

http://www.jus.uio.no/sisu/SiSU/examples.html

Additional Things

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

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

usually installed to:

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

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:

© Ralph Amissah 1997, current 2006 All Rights Reserved.

CHANGELOG

./CHANGELOG

and see

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

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


[ document manifest ]

<< previous toc next >>