Imported upstream version 0.52.7upstream/0.52.7sisu_0.52.7

1 files changed, 422 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 00000000..a688fcb5
--- /dev/null
+++ b/README
@@ -0,0 +1,422 @@
+SiSU 0.49 2007w08/5 20070223
+homepage: http://www.jus.uio.no/sisu
+
+%% 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, 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.
+ 
+  Outputs share a common citation numbering system, and any semantic meta-data
+  provided about the document.
+ 
+  SiSU also provides concordance files, document content certificates and
+  manifests of generated output.
+
+    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).
+ 
+  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
+
+-----
+
+SiSU - simple information structuring universe, is a publishing tool, document
+generation and management, (and search enabling) tool primarily for literary, 
+academic and legal 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 (in my
+case Reiserfs), and/or database Postgresql.
+
+Amongst it's characteristics are: 
+
+* simple mnemonoic markup style,
+
+* 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,
+
+* 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.
+
+* 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.
+
+%% 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
+or the same:
+  http://www.jus.uio.no/sisu/sisu_download/download.html#current
+  http://www.jus.uio.no/sisu/sisu_download/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
+  http://www.jus.uio.no/sisu/sisu_download/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
+  http://www.jus.uio.no/sisu/sisu_download/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:
+
+1. Download the latest source (information available) from:
+  http://www.jus.uio.no/sisu/SiSU/download.html#current
+
+2. Unpack the source
+
+%% 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 "Rant")
+---------------
+in the root directory of the unpacked SiSU as root type:
+  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:
+    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
+
+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
+Depends: ruby (>= 1.8.4), libwebrick-ruby
+Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
+  tidy, librexml-ruby, zip, unzip, openssl, rsync, openssh-client | lsh-client,
+  keychain, hyperestraier, kdissert
+Suggests: libfcgi-ruby1.8, rcs | cvs, lv, texinfo, pinfo, rename
+
+Package: sisu-complete
+Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
+Recommends: hyperestraier
+
+Package: sisu-pdf
+Depends: sisu, tetex-bin | texlive-base-bin, tetex-extra | texlive-latex-extra,
+  texlive-latex-extra, latex-ucs
+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/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
+
+%% 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
+
+%% Markup
+---------------
+
+See man pages.
+  man 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/sisu_markup_samples/dfsg
+
+These are installed on the system usually at:
+  /usr/share/doc/sisu/sisu_markup_samples/dfsg
+
+More markup samples are available in the package 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/conf/syntax
+
+usually installed to:
+
+  /usr/share/sisu/conf/syntax
+
+%% License
+---------------
+
+License: GPL 2 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
+
+