SiSU - Structured information, Serialized Units - a document publishing system

sisu [-mhwpxXv...] [ filename/wildcard ]

A document publishing system, that from a simple single marked-up document, produces a multitude of output formats including: html, latex, pdf, info, and sql output, which can be cross referenced as having the same document structure and text object numbering, "object citation numbering". Features include its' simple syntax; the semantic identification of documents using the Dublin Core; document management; built to be associated with a revision control system; text object numbering for the identification of a texts location in any of the output formats, easy skinning on a site wide, or per document basis, ... for more see man 1 sisu or http://www.jus.uio.no/sisu

SiSU is an alternative way of publishing and managing documents.

Up to date information on SiSU downloads, and their installation should be available from: http://www.jus.uio.no/sisu/sisu_download/download or at: http://www.jus.uio.no/sisu/SiSU/download

There you should find links to the latest source tarball, and instructions on how to install SiSU.

NB. SiSU markup syntax changed in sisu-0.16

Sample marked up documents are are available at /usr/share/sisu-examples/sample/document_samples_sisu_markup or equivalent directory, or online at http://www.jus.uio.no/sisu/sample/markup or in html with syntax highlighting from http://www.jus.uio.no/sisu/sample/syntax

A syntax table is provided at /usr/share/doc/sisu/on_markup.txt or equivalent, and online at http://www.jus.uio.no/sisu/sample/on_markup.txt

man 1 sisu has a syntax table along with processing commands.

SiSU also has an interactive help entered by typing sisu and selecting the subject, or to get help on a subject directly, e.g. sisu help markup or e.g. sisu help headers or e.g. sisu help commands however, the man pages are probably more up to date than the interactive help.

The rest of this note is on post installation setup (it assumes you have sisu-examples installed for which there are instructions on the download page mentioned above).

A. Quick test cd to /usr/share/sisu-examples/sample/document_samples_sisu_markup select a document there and run (for example) sisu -mhwpv gpl2.fsf.sst

that is it information should be provided as to where the generated output was placed.

B. Generate a (local) document from a markup/work directory.

1. Create a directory for sisu marked up documents within your home directory: e.g. ~/sisu_test

2. Select a sample markup file to use from: /usr/share/sisu-examples/sample/document_samples_sisu_markup (created with your installation of the sisu tarball or of sisu-example), or download sample markup files from: http://www.jus.uio.no/sisu/sample/markup and copy a sample markup file into it e.g. gpl2.fsf.sst

Note: you may have several directories for marked up documents

3. Change to your work directory cd ~/sisu_test and run: sisu -mHwapv gpl2.fsf.sst shortcut to same command: sisu -1v gpl2.fsf.sst

You should have the document (without images specific to the document), and the selected verbose output should inform you where the output has been placed.

that is it

C. Generate a (remote) document.

If you are connected to the Net, change to your work directory cd ~/sisu_test and run

sisu -mHwapv http://www.jus.uio.no/sisu/sample/markup/free_culture.lawrence_lessig.sst

This generates the remote document after downloading it and its' associated images,

or again:

sisu -3cv http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst

that is it

Tip: the markup syntax examples may be of interest http://www.jus.uio.no/sisu/sample/

Tip: sisu -U [sisu markup filename] should printout the different possible outputs and where sisu would place them.

Tip: if you want to toggle ansi color add c to your flags.

----------

A note on images

To add the images, within your document markup directory (in our example which we shall use ~/sisu_test ) create a directory,

~/sisu_test/_sisu/image

copy the images from the sub-directory data/sisu-examples/sample/document_samples_sisu_markup/_sisu/image in the directory from which you got your source markup, in this example either, or from: /usr/share/sisu-examples/sample/document_samples_sisu_markup/_sisu/image or online from: http://www.jus.uio.no/sisu/sample/markup/_sisu/image

(copy those images) into ~/sisu_test/_sisu/image

then regenerate the document

sisu -mHwapcv gpl2.fsf.sst

that should be it

Note: for local documents, SiSU will look for generic images, images associated with all documents, (such as navigation buttons) in /usr/share/sisu-examples/sample/_sisu/image (or it's equivalent). It expects to find all images that are specific to documents contained in the markup work directory, in a sub-directory within it called ./_sisu/image

----------

A more comprehensive test

sisu -mHwabpxXv gpl2.fsf.sst

which should be the same as

sisu -3v gpl2.fsf.sst

add c to toggle screen colour.

----------

SiSU setup for postgresql and sqlite is configured in ~/.sisu/sisurc.yaml

a sample of this file is provided with the examples provided at (or equivalent): /etc/sisu/sisurc.yaml the section to take note of in this regard is to be found in that yaml file under db:

[more extensive notes to be included later]

It is best you see http://www.jus.uio.no/sisu/SiSU/download#debian for up the most up to date information.

The following command should include the external packages used by SiSU:

required ruby (>=1.8.2)

recommends tetex-bin, tetex-extra, latex-ucs, postgresql (>=8.0.0), libdbi-ruby, libdbm-ruby, libdbd-pg-ruby, libsqlite, libdbd-sqlite-ruby, librmagick-ruby, trang, tidy, libtidy, librexml-ruby, sisu-examples, vim-ruby, sisu-vim

suggested makeinfo, pgaccess, texinfo, pinfo, libcgi_ruby, libfcgi-ruby1.8, libdbd-pgsql, libdbd-sqlite, openssl, openssh-client|openssh-client, rcs|cvs

A rough breakdown of additional additional packages and libraries

ruby is required, sisu is written in ruby and needs it to run

sisu-examples provides examples of various things including sisu markup which are usually placed under the tree /usr/share/sisu-examples it has its own man page, "man sisu_examples" and include document markup samples; vim syntax highlighting and folds; a sample cgi frontend to database.

sisu-vim provides vim syntax highlighting for the sisu markup, man page under "man sisu_vim"

sisu-webrick is installed with sisu runs the ruby webserver webrick, this has a man page "man sisu_webrick" -W

The following output require nothing, and should work out of the box: plaintext -a -e, html -H -h, xhtml -b, xml -x -X, [php -z], latex -p, wordmap -w however the latex output in particular is used to generate pdf which has several other requirements listed below, and some of the other libraries can take advantage of additional packages.

xhtml and xml output -b -x -X will use the following if available: tidy, libtidy to check that the output is well formed with the -v flag, and librexml-ruby , for an additional check that the output is readable with the -V flag

The metaverse, the first step in processing -m which produces an initial markup step, will make use if available of: librmagick-ruby to determine image dimensions, if they are not provided in the markup, and, if instructed to in the document it will make use of any rcs or cvs document version information provided in it using the Id tag

Pdf output -p (and latex though it can be generated without as it is used to produce the pdf), require tetex-bin, tetex-extra, (for " pdfetex " aka. pdflatex) latex-ucs, (to do utf-8 ) and if a document contains images requires the image dimension information which must either be provided (manually so to speak) as part of the document markup, or extracted (autmatically) during the "metaverse" step using librmagick-ruby

if sisu output is to be streamed into a database -D or -d then either postgresql (>=8.0.0), libdbi-ruby, libdbm-ruby, libdbd-pg-ruby or libsqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby

The cgi generator -S used to create a sample database front end cgi search form assumes the availability of libcgi_ruby, libfcgi-ruby1.8

The texinfo output -I makes use of makeinfo, texinfo and is best viewed with pinfo

Remote placement of sisu output -r makes use of openssh-client|openssh-client, and key management client such as keychain

SiSU has several modules that can be used independently of each other, or together (you could just use SiSU to generate html). SiSU can be used either off the file system or with a relational database, or both.

Once a document is marked up all possibilities are available, provided external programs where required are present on the system. External programs can be installed later to make these possibilities available at a subsequent date.

Ruby > 1.8.2 required

[ no external programs required ]

[ no external programs required ]

[ no external programs required, tidy and rexml recommended, check that documents are well formed ]

[ no external programs required, tidy and rexml recommended, check that documents are 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)

[ no external programs required ] SiSU generates LaTeX, however to produce pdfs from the LaTeX produced you require tetex-base, tetex-extra and latex-ucs to interpret LaTeX generated and utf-8 and produce pdf

[ requires pdflatex and ucs ] conversion from LaTeX to pdf file. For this you require tetex-bin, tex base package tetex-extra which includes pdflatex and latex-ucs for utf-8 also image dimensions must either be provided in document markup, or extracted using librmagick-ruby

[ requires makeinfo, texinfo ]

[ no external programs required, word count recommended ] 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. tetex base and tetex extra required to interpret LaTeX generated

[ requires postgresql (>=8.0.0), libdbi-ruby, libdbm-ruby, libdbd-pg-ruby ]

[ requires libsqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby ]

sisu can be used without a database module

rcs or cvs recommended for document versioning, RCS or CVS provide version control and version stamps for documents. The versioning history can be incorporated into output. If used properly you can track which version of a document you are looking at.

[ word count, recommended ] 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.

sisu resource configuration information is obtained from sources (where they exist):

~/.sisu/sisurc.yaml
/etc/sisu/[sisu version]/sisurc.yaml
sisu program defaults

Skins

default document appearance may be modified using skins contained in sub-directories located at the following paths:

~/.sisu/skin
/etc/sisu/[sisu version]/skin

more specifically, the following locations (or their /etc/sisu equivalent) should be used:

~/.sisu/skin/doc skins for individual documents;

~/.sisu/skin/dir skins for directories of matching names;

~/.sisu/skin/site site-wide skin modifying the site-wide appearance of documents.

Usually all skin files are placed in the document skin directory: ~/.sisu/skin/doc with softlinks being made to the skins contained there from other skin directories as required.

For more information on SiSU see: http://www.jus.uio.no/sisu

or man sisu

Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com

sisu(1), sisu_examples(1), sisu_webrick(1), sisu_pdf(1) sisu_sqlite(1) sisu_postgresql(1) sisu_makeinfo(1) sisu_termsheet(1), sisu_vim(1)