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?

Download information

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

Installation

Installation is currently most straightforward and tested on the Debian platform, as there are packages for the installation of sisu and all requirements for what it does.

Debian Installation

SiSU is available directly from the Debian Sid and testing archives (and possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly:

  aptitude update
  aptitude install sisu-complete

The following /etc/apt/sources.list setting permits the download of additional markup samples:

#/etc/apt/sources.list

  deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
  deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib

The aptitude commands become:

  aptitude update
  aptitude install sisu-complete sisu-markup-samples

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

#/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

repeat the aptitude commands

  aptitude update
  aptitude install sisu-complete sisu-markup-samples

Note however that it is not necessary to install sisu -complete if not all components of sisu are to be used. Installing just the package sisu will provide basic functionality.

RPM Installation

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

as root type:

rpm -i [rpm package name]

Installation from source

To install SiSU from source check information at:

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

Two alternative modes of installation from source are provided, setup.rb (by Minero Aoki) and a rant(by Stefan Lang) built install file, in either case: the first steps are the same, download and unpack the source file:

For basic use SiSU is only dependent on the programming language in which it is written Ruby, and SiSU will be able to generate html, EPUB, various XMLs, including ODF (and will also produce LaTeX) . Dependencies required for further actions, though it relies on the installation of additional dependencies which the source tarball does not take care of, for things like using a database (postgresql or sqlite)   40  or converting LaTeX to pdf.

setup.rb

This is a standard ruby installer, using setup.rb is a three step process. In the root directory of the unpacked SiSU as root type:

    ruby setup.rb config
    ruby setup.rb setup
    #[and as root:]
    ruby setup.rb install

further information on setup.rb is available from:

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

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

"install"

The "install" file provided is an installer prepared using "rant". In the root directory of the unpacked SiSU as root type:

ruby install base

or for a more complete installation:

ruby install

or

ruby 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 on "rant" is available from:

http://make.rubyforge.org/

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

For a list of alternative actions you may type:

ruby install help

ruby install -T

Testing SiSU, generating output

To check which version of sisu is installed:

sisu -v

Depending on your mode of installation one or a number of markup sample files may be found either in the directory:

...

or

...

change directory to the appropriate one:

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

basic text, plaintext, html, XML, ODF, EPUB

Having moved to the directory that contains the markup samples (see instructions above if necessary), choose a file and run sisu against it

sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst

this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text

LaTeX / pdf

Assuming a LaTeX engine such as tetex or texlive is installed with the required modules (done automatically on selection of sisu -pdf in Debian)

Having moved to the directory that contains the markup samples (see instructions above if necessary), choose a file and run sisu against it

sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst

sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

should generate most available output formats: html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text and pdf

relational database - postgresql, sqlite

Relational databases need some setting up - you must have permission to create the database and write to it when you run sisu.

Assuming you have the database installed and the requisite permissions

sisu --sqlite --recreate

sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst

sisu --pgsql --recreate

sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst

Getting Help

The man pages

Type:

man sisu

The man pages are also available online, though not always kept as up to date as within the package itself:

Built in help

sisu --help

sisu --help --env

sisu --help --commands

sisu --help --markup

The home page

http://www.sisudoc.org/

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

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

Markup Samples

A number of markup samples (along with output) are available off:

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

Additional markup samples are packaged separately in the file:

***

On Debian they are available in non-free  44  to include them it is necessary to include non-free in your /etc/apt/source.list or obtain them from the sisu home site.


 40. There is nothing to stop MySQL support being added in future.

 41.http://www.jus.uio.no/sisu/man/sisu.1.html

 42.http://www.jus.uio.no/sisu/man/sisu.8.html

 43.http://www.jus.uio.no/sisu/man

 44. the Debian Free Software guidelines require that everything distributed within Debian can be changed - and the documents are authors' works that while freely distributable are not freely changeable.


[ document manifest ]

<< previous toc next >>