%% SiSU versions 1 & 2, 2010 Homepage: <http://www.jus.uio.no/sisu> * README CHANGELOG CHANGELOG_v1 CHANGELOG_v2 Herein (this package) reside SiSU versions 1 and 2. %% 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, XML, EPUB (v2 only) ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or SQLite) with text objects, roughly, paragraph sized chunks so that document searches are done at this level of granularity. Outputs share a common citation numbering system, associated with text objects and any semantic meta-data provided about the document. SiSU also provides concordance files, document content certificates and manifests of generated output. Book indexes may be made. 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 retaining minimal markup requirement. SiSU implements a "useful common feature set" across document formats [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). Syntax highlighting files for a number of editors are provided. 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.jus.uio.no/sisu> %% Take 2 --------- The ideas behind SiSU evolved working with managing static, published documents that needed to be citable, ideally searchable and preferably available in multiple formats over a period of time with a rapidly changing World Wide Web. Initial experience was in 1993, one issue being that the document content remained the same, but presentation needed to be updated with changing formats, html in particular has really changed since then. So the idea was to provide a minimal markup requirement for documents that remained the same, and a generator to convert that markup custom producing various output types. This made it possible to: * have a marked-up document set and continue improving the presentation, as the generators code was updated, e.g. update HTML as it evolves, and improve upon LaTeX driven pdf output * have available new document formats/ output types as they came to be of interest, e.g. version 2 includes EPUB * produce a citation system that is available across different output types, text based on objects (rather than page numbers), i.e. you can accurately and reliably cite text within a document regardless of the document format version that is being looked at * take advantage of the strengths of disparate technologies representing text, each output type being custom generated for that format, the object citation system lends itself as a result is that there is little necessity that one output type should be based on or related to another, just that the content is preserved and presented in a way that is well suited to the output type in question * produce consistent quality presentation for material, suitable where substance/content is more important than appearance, there is some sacrifice of flexibility and no concept of wysiwyg, e.g. there is no attempt to make pdf output identical to html, rather the system attempts to take advantage of making the best presentation it can in each output format taking advantage of the strengths of that format available to it given the minimal markup (sisu document preparation); the citation system ensures you can pinpoint the same text SiSU works best: * with published works (e.g. books, articles), static documents the content of which is changed rarely, and ideally when they do in the form of a new edition. * for literature and law related content SiSU uses Unicode, utf-8 where it is available, ----- 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 be dependent on your hardware, and filesystem and/or database Postgresql. Amongst it's characteristics are: * simple mnemonoic markup style, * the ability to produce multiple output formats, including html, XML, EPUB, LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining document structure - Postgresql and Sqlite, * 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 identifying the paragraph in which the match is found (using the object citation numbering system) 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. * it is command line driven, and can be set up on a remote server * 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. Input files should be UTF-8 Once set up it is simple to use. %% Information, places to look --------------- Within the SiSU tarball: ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual Once installed, directory equivalent to: <file:///usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/> Available man pages are converted back to html using man2html: <file:///usr/share/doc/sisu/v2/html/> ./data/doc/sisu/v2/html/ %% Online Information, places to look --------------- <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): 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 %% 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/v2/sisu_markup_samples/dfsg 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/free_culture.lawrence_lessig/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/2.html> For help man sisu or sisu --help e.g. sisu --help env for the way sisu "sees/maps" your system sisu --help commands for list of commands and so on %% 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 * configuration file - a yaml file /etc/sisu/[sisu version]/sisurc.yml ~/.sisu/sisurc.yml * directory structure - setting up of output and working directory. * skins - changing the appearance of a project, directory or individual documents within ~/.sisu/skin ~/.sisu/skin/doc contains individual skins, with symbolic links from ~/.sisu/skin/dir if the contents of a directory are to take a particular document skin. * 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. * if you use Vim as editor there is a syntax highlighter and fold resource config file for SiSU. I hope more syntax highlighters follow. 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/v2/sisu_markup_samples/dfsg These are installed on the system usually at: /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg More markup samples are available in the package sisu-markup-samples <http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples> Many more are available online off: <http://www.jus.uio.no/sisu/SiSU/2.html> %% Additional Things --------------- There is syntax support for some editors provided (together with a README file) in ./data/sisu/v2/conf/editor-syntax-etc usually installed to: /usr/share/sisu/v2/conf/editor-syntax-etc v1, v2 Changes --------------- See changelogs From a developer's perspective the substantive change between the two versions is to the middle layer, (the document abstraction, the intermediate document representation used in processing). Version 1 uses strings and relies on regular expressions to identify document objects, while Version 2 uses ruby objects. The version 1 approach whilst programming language neutral offers less control, and leads to complicated code; version 2 approach takes advantage of features within the ruby language suited to what the application does. Development is curently on version 2, version 1 is likely to remain for some time as a reference implementation. %% v1, v2 Compatibility Notes --------------- Versions 1 and 2 are not quite compatible, version 1 and version 2 will run against each other's documents but document metadata, and processing instructions may be lost. On the input side, version 1 and 2 headers are different, version 2 headers have been tidied, see document markup samples provided On the output side, the sql databases produced if search is to be implemented are not the same and a database must be generated for each version, most other differences should be relatively cosmetic. %% 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: * Standard SiSU markup syntax, * Standard SiSU meta-markup syntax, and the * Standard SiSU object citation numbering and system © Ralph Amissah 1997, current 2006. All Rights Reserved. * however note the License section CHANGELOG ./CHANGELOG and see <http://www.jus.uio.no/sisu/SiSU/changelog.html> <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>