2441

22. README

2442

SiSU 0.55 2007w27/6 2007-07-07

2443

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

2444

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

2445

Description

2446

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.

2447

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.

2448

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

2449

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

2450

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

2451

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

2452

man pages, and interactive help are provided.

2453

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

2454

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.

2455

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

2456

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

2457

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.

2458

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

2459

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

2460

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

2461

Amongst it's characteristics are:

2462

simple mnemonoic markup style,

2463

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,

2464

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.

2465

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

2466

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.

2467

Input files should be UTF-8

2468

Once set up it is simple to use.

2469

22.1 Online Information, places to look

2470

‹http://www.sisudoc.org›

2471

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

2472

Download Sources:

2473

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

2474

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

2475

22.2 Installation

2476

NB. Platform is Unix / Linux.

2477

22.2.1 Debian

2478

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

2479

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

2480

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

2481

aptitude update

2482

aptitude install sisu-complete

2483

(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

2484

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

2485

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

2486

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

2487

Then as root run:

2488

aptitude update

2489

aptitude install sisu-complete

2490

22.2.2 RPM

2491

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

2492

They may be downloaded from:

2493

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

2494

22.2.3 Source package .tgz

2495

Otherwise to install SiSU from source, check information at:

2496

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

2497

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,

2498

Ruby is the essential dependency for the basic operation of SiSU

2499

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

2500

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

2501

2. Unpack the source

2502

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.

2503

22.2.4 to use setup.rb

2504

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

2505

ruby setup.rb config

2506

ruby setup.rb setup

2507

as root:

2508

ruby setup.rb install

2509

further information:

2510

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

2511

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

2512

22.2.5 to use install (prapared with "Rake")

2513

Rake must be installed on your system:

2514

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

2515

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

2516

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

2517

rake

2518

or

2519

rake base

2520

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

2521

For a list of alternative actions you may type:

2522

rake help

2523

rake -T

2524

22.2.6 to use install (prapared with "Rant")

2525

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

2526

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

2527

ruby ./sisu-install

2528

or

2529

ruby ./sisu-install base

2530

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.

2531

further information:

2532

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

2533

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

2534

For a list of alternative actions you may type:

2535

ruby ./sisu-install help

2536

ruby ./sisu-install -T

2537

22.3 Dependencies

2538

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.

2539

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

2540

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

2541

  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

2542

  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.

2543

  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.

2544

  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.

2545

  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.

2546

  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.

2547

  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.

2548

22.4 Quick start

2549

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

2550

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

2551

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

2552

and run

2553

sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

2554

or the same:

2555

sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst

2556

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

2557

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

2558

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

2559

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

2560

examine source document, vim has syntax support

2561

gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst

2562

additional markup samples in

2563

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

2564

For help

2565

man sisu

2566

or

2567

sisu --help

2568

e.g.

2569

for the way sisu "sees/maps" your system

2570

sisu --help env

2571

for list of commands and so on

2572

sisu --help commands

2573

22.5 Configuration files

2574

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

2575

configuration file - a yaml file

2576

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

2577

~/.sisu/sisurc.yml

2578

directory structure - setting up of output and working directory.

2579

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

2580

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

2581

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

2582

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.

2583

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

2584

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

2585

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

2586

22.6 Use General Overview

2587

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

2588

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

2589

use the interactive help and man pages

2590

sisu --help

2591

man sisu

2592

22.7 Help

2593

interactive help described below, or man page:

2594

man sisu

2595

man 8 sisu

2596

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

2597

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

2598

sisu

2599

alternatively, you could type e.g.

2600

sisu --help commands

2601

sisu --help env

2602

sisu --help headers

2603

sisu --help markup

2604

sisu --help headings

2605

etc.

2606

for questions about mappings, output paths etc.

2607

sisu --help env

2608

sisu --help path

2609

sisu --help directory

2610

22.8 Directory Structure

2611

Once installed, type:

2612

sisu --help env

2613

or

2614

sisu -V

2615

22.9 Configuration File

2616

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)

2617

22.10 Markup

2618

See man pages.

2619

man sisu

2620

man 8 sisu

2621

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

2622

sisu --help markup

2623

and

2624

sisu --help headers

2625

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

2626

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

2627

These are installed on the system usually at:

2628

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

2629

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

2630

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

2631

Many more are available online off:

2632

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

2633

22.11 Additional Things

2634

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

2635

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

2636

usually installed to:

2637

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

2638

22.12 License

2639

License: GPL 3 or later see the copyright file in

2640

./data/doc/sisu

2641

usually installed to:

2642

/usr/share/doc/sisu

2643

22.13 SiSU Standard

2644

SiSU uses:

2645

Standard SiSU markup syntax,

2646

Standard SiSU meta-markup syntax, and the

2647

Standard SiSU object citation numbering and system

2648

2649

however note the License section

2650

CHANGELOG

2651

./CHANGELOG

2652

and see

2653

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

2654

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

SiSU - SiSU information Structuring Universe - Structured information, Serialized Units,Ralph Amissah

Structured information, Serialized Units

SiSU - from less markup than the most elementary equivalent html, you can have more

Markup Syntax History

Technical Information

A Summary of notable events

A Chronological history of developments on SiSU

SiSU - SiSU information Structuring Universe - Structured information, Serialized Units,
Ralph Amissah