From 65477054fd798728bf186aa2938727ddddbe86a5 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 22 May 2007 02:06:46 +0100 Subject: Imported upstream version 0.52.7 --- README | 422 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 422 insertions(+) create mode 100644 README (limited to 'README') 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 + + -- cgit v1.2.3