1427

42. README

1428

SiSU 0.55 2007w27/6 2007-07-07

1429

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

1430

old homepage: ‹http://www.jus.uio.no/sisu›

1431

Description

1432

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.

1433

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.

1434

Outputs share a common citation numbering system, and any semantic meta-data provided about the document.

1435

SiSU also provides concordance files, document content certificates and manifests of generated output.

1436

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

1437

A vim syntax highlighting file and an ftplugin with folds for sisu markup is provided. Vim 7 includes syntax highlighting for SiSU.

1438

man pages, and interactive help are provided.

1439

Dependencies for various features are taken care of in sisu related packages. The package sisu-complete installs the whole of SiSU.

1440

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.

1441

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

1442

old homepage: ‹http://www.jus.uio.no/sisu›

1443

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.

1444

SiSU can be used for Internet, Intranet, local filesystem or cd publishing.

1445

SiSU can be used directly off the filesystem, or from a database.

1446

SiSU' s scalability, is be dependent on your hardware, and filesystem (in my case Reiserfs), and/or database Postgresql.

1447

Amongst it's characteristics are:

1448

simple mnemonoic markup style,

1449

the ability to produce multiple output formats, including html, structured XML, LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining document structure - Postgresql and Sqlite,

1450

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 in which the match is found 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.

1451

it is command line driven, and can be set up on a remote server

1452

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.

1453

Input files should be UTF-8

1454

Once set up it is simple to use.

1455

42.1 Online Information, places to look

1456

‹http://www.sisudoc.org›

1457

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

1458

Download Sources:

1459

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

1460

‹http://www.jus.uio.no/sisu/SiSU/download.html#debian›

1461

42.2 Installation

1462

NB. Platform is Unix / Linux.

1463

42.2.1 Debian

1464

If you use Debian use the Debian packages, check the information at:

1465

‹http://www.jus.uio.no/sisu/SiSU/download.html#debian›

1466

(A) SiSU is available directly off the Debian archives for Sid and testing. It should necessary only to run as root:

1467

aptitude update

1468

aptitude install sisu-complete

1469

(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

1470

deb ‹http://www.jus.uio.no/sisu/archive› unstable main non-free

1471

deb-src ‹http://www.jus.uio.no/sisu/archive› unstable main non-free

1472

[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]

1473

Then as root run:

1474

aptitude update

1475

aptitude install sisu-complete

1476

42.2.2 RPM

1477

RPMs are provided though untested, they are prepared by running alien against the source package, and against the debs.

1478

They may be downloaded from:

1479

‹http://www.jus.uio.no/sisu/SiSU/download.html#rpm›

1480

42.2.3 Source package .tgz

1481

Otherwise to install SiSU from source, check information at:

1482

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

1483

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,

1484

Ruby is the essential dependency for the basic operation of SiSU

1485

1. Download the latest source (information available) from:

1486

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

1487

2. Unpack the source

1488

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.

1489

42.2.4 to use setup.rb

1490

this is a three step process, in the root directory of the unpacked SiSU as root type:

1491

ruby setup.rb config

1492

ruby setup.rb setup

1493

as root:

1494

ruby setup.rb install

1495

further information:

1496

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

1497

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

1498

42.2.5 to use install (prapared with "Rake")

1499

Rake must be installed on your system:

1500

‹http://rake.rubyforge.org/›

1501

‹http://rubyforge.org/frs/?group_id=50›

1502

in the root directory of the unpacked SiSU as root type:

1503

rake

1504

or

1505

rake base

1506

This makes use of Rake (by Jim Weirich) and the provided Rakefile

1507

For a list of alternative actions you may type:

1508

rake help

1509

rake -T

1510

42.2.6 to use install (prapared with "Rant")

1511

(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:)

1512

in the root directory of the unpacked SiSU as root type:

1513

ruby ./sisu-install

1514

or

1515

ruby ./sisu-install base

1516

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.

1517

further information:

1518

‹http://make.rubyforge.org/›

1519

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

1520

For a list of alternative actions you may type:

1521

ruby ./sisu-install help

1522

ruby ./sisu-install -T

1523

42.3 Dependencies

1524

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.

1525

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

1526

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

1527

  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/?p=code/sisu.git
  Vcs-Git: git://git.sisudoc.org/git/code/sisu.git
  XS-Dm-Upload-Allowed: yes

1528

  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.

1529

  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.

1530

  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.

1531

  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.

1532

  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.

1533

  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.

1534

42.4 Quick start

1535

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

1536

After installation of sisu-complete, move to the document samples directory

1537

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

1538

and run

1539

sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

1540

or the same:

1541

sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst

1542

look at output results, see the "sisu_manifest" page created for the document

1543

or to generate an online document move to a writable directory, as the file will be downloaded there and e.g.

1544

sisu -3 ‹http://www.jus.uio.no/sisu/src/free_culture.lawrence_lessig.sst›

1545

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

1546

examine source document, vim has syntax support

1547

gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst

1548

additional markup samples in

1549

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

1550

For help

1551

man sisu

1552

or

1553

sisu --help

1554

e.g.

1555

for the way sisu "sees/maps" your system

1556

sisu --help env

1557

for list of commands and so on

1558

sisu --help commands

1559

42.5 Configuration files

1560

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

1561

configuration file - a yaml file

1562

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

1563

~/.sisu/sisurc.yml

1564

directory structure - setting up of output and working directory.

1565

* skins - changing the appearance of a project, directory or individual documents within ~/.sisu/skin

1566

~/.sisu/skin/doc contains individual skins, with symbolic links from

1567

~/.sisu/skin/dir if the contents of a directory are to take a particular document skin.

1568

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.

1569

if you use Vim as editor there is a syntax highlighter and fold resource config file for SiSU. I hope more syntax highlighters follow.

1570

There are post installation steps (which are really part of the overall installation)

1571

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

1572

42.6 Use General Overview

1573

Documents are marked up in SiSU syntax and kept in an ordinary text editable file, named with the suffix .sst, or .ssm

1574

Marked up SiSU documents are usually kept in a sub-directory of your choosing

1575

use the interactive help and man pages

1576

sisu --help

1577

man sisu

1578

42.7 Help

1579

interactive help described below, or man page:

1580

man sisu

1581

man 8 sisu

1582

'man sisu_markup-samples' [if the sisu-markup-samples package is also installed]

1583

Once installed an interactive help is available typing 'sisu' (without) any flags, and select an option:

1584

sisu

1585

alternatively, you could type e.g.

1586

sisu --help commands

1587

sisu --help env

1588

sisu --help headers

1589

sisu --help markup

1590

sisu --help headings

1591

etc.

1592

for questions about mappings, output paths etc.

1593

sisu --help env

1594

sisu --help path

1595

sisu --help directory

1596

42.8 Directory Structure

1597

Once installed, type:

1598

sisu --help env

1599

or

1600

sisu -V

1601

42.9 Configuration File

1602

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)

1603

42.10 Markup

1604

See man pages.

1605

man sisu

1606

man 8 sisu

1607

Once installed there is some information on SiSU Markup in its help:

1608

sisu --help markup

1609

and

1610

sisu --help headers

1611

Sample marked up document are provided with the download tarball in the directory:

1612

./data/doc/sisu/markup-samples/

1613

These are installed on the system usually at:

1614

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

1615

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

1616

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

1617

Many more are available online off:

1618

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

1619

42.11 Additional Things

1620

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

1621

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

1622

usually installed to:

1623

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

1624

42.12 License

1625

License: GPL 3 or later see the copyright file in

1626

./data/doc/sisu

1627

usually installed to:

1628

/usr/share/doc/sisu

1629

42.13 SiSU Standard

1630

SiSU uses:

1631

Standard SiSU markup syntax,

1632

Standard SiSU meta-markup syntax, and the

1633

Standard SiSU object citation numbering and system

1634

1635

however note the License section

1636

CHANGELOG

1637

./CHANGELOG

1638

and see

1639

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

1640

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

SiSU - Manual,Ralph Amissah

What is SiSU?

Markup Syntax History

Remote Document Output

Download information

SiSU - Manual,
Ralph Amissah