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
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)
sisu can be used without a database module
~/.sisu/sisurc.yaml/etc/sisu/[sisu version]/sisurc.yamlsisu 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