diff options
Diffstat (limited to 'data/doc/sisu/README')
| -rw-r--r-- | data/doc/sisu/README | 561 |
1 files changed, 0 insertions, 561 deletions
diff --git a/data/doc/sisu/README b/data/doc/sisu/README deleted file mode 100644 index 0c021ee5..00000000 --- a/data/doc/sisu/README +++ /dev/null @@ -1,561 +0,0 @@ -%% SiSU versions 1 & 2, 2010 -Homepage: <http://www.jus.uio.no/sisu> -* README CHANGELOG v1/CHANGELOG v2/CHANGELOG - -Herein (this package) reside SiSU versions 1 and 2. - -%% 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, EPUB (v2 only) - ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL - or SQLite) with text objects, roughly, paragraph sized chunks so that - document searches are done at this level of granularity. - - Outputs share a common citation numbering system, associated with text - objects and any semantic meta-data provided about the document. - - SiSU also provides concordance files, document content certificates and - manifests of generated output. Book indexes may be made. - - 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 retaining minimal markup requirement. SiSU implements a "useful - common feature set" across document formats [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). - - Syntax highlighting files for a number of editors are provided. - 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> - -%% Take 2 ---------- - -The ideas behind SiSU evolved working with managing static, published documents -that needed to be citable, ideally searchable and preferably available in -multiple formats over a period of time with a rapidly changing World Wide Web. -Initial experience was in 1993, one issue being that the document content -remained the same, but presentation needed to be updated with changing formats, -html in particular has really changed since then. - -So the idea was to provide a minimal markup requirement for documents that -remained the same, and a generator to convert that markup custom producing -various output types. This made it possible to: - -* have a marked-up document set and continue improving the presentation, as the -generators code was updated, e.g. update HTML as it evolves, and improve upon -LaTeX driven pdf output - -* have available new document formats/ output types as they came to be of -interest, e.g. version 2 includes EPUB - -* produce a citation system that is available across different output types, -text based on objects (rather than page numbers), i.e. you can accurately and -reliably cite text within a document regardless of the document format version -that is being looked at - -* take advantage of the strengths of disparate technologies representing text, -each output type being custom generated for that format, the object citation -system lends itself as a result is that there is little necessity that one -output type should be based on or related to another, just that the content is -preserved and presented in a way that is well suited to the output type in -question - -* produce consistent quality presentation for material, suitable where -substance/content is more important than appearance, there is some sacrifice of -flexibility and no concept of wysiwyg, e.g. there is no attempt to make pdf -output identical to html, rather the system attempts to take advantage of -making the best presentation it can in each output format taking advantage of -the strengths of that format available to it given the minimal markup (sisu -document preparation); the citation system ensures you can pinpoint the same -text - -SiSU works best: - -* with published works (e.g. books, articles), static documents the content of -which is changed rarely, and ideally when they do in the form of a new edition. - -* for literature and law related content - -SiSU uses Unicode, utf-8 where it is available, ------ - -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. - -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 and/or -database Postgresql. - -Amongst it's characteristics are: - -* simple mnemonoic markup style, - -* the ability to produce multiple output formats, including html, XML, EPUB, -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 -identifying the paragraph in which the match is found (using the object -citation numbering system) 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. - -%% Information, places to look ---------------- - -Within the SiSU tarball: - - ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual - -Once installed, directory equivalent to: - - <file:///usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/> - -Available man pages are converted back to html using man2html: - - <file:///usr/share/doc/sisu/v2/html/> - - ./data/doc/sisu/v2/html/ - -%% 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> - -%% 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> - -(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> - -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, - -Ruby is the essential dependency for the basic operation of SiSU - -1. Download the latest source (information available) from: - <http://www.jus.uio.no/sisu/SiSU/download.html#current> - -2. Unpack the source - -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. - -%% 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 "Rake") ---------------- -Rake must be installed on your system: - <http://rake.rubyforge.org/> - <http://rubyforge.org/frs/?group_id=50> - -in the root directory of the unpacked SiSU as root type: - rake - -or - rake base - -This makes use of Rake (by Jim Weirich) and the provided Rakefile - -For a list of alternative actions you may type: - rake help - rake -T - -%% to use install (prapared with "Rant") ---------------- -(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:) - -in the root directory of the unpacked SiSU as root type: - ruby ./sisu-install - -or - ruby ./sisu-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 ./sisu-install help - ruby ./sisu-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 -Architecture: all -Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip -Conflicts: vim-sisu, sisu-vim, sisu-remote -Replaces: vim-sisu, sisu-vim -Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang, -tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain, -hyperestraier, kdissert, vim-addon-manager -Suggests: rcs | cvs, lv, texinfo, pinfo - -Package: sisu-complete -Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite -Recommends: hyperestraier - -Package: sisu-pdf -Architecture: all -Depends: sisu, texlive-latex-base, texlive-fonts-recommended, -texlive-latex-recommended, texlive-latex-extra -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/v2/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 -or - sisu -V - -%% 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 (searched in that -order, stopping on the first one found) - -%% Markup ---------------- - -See man pages. - man sisu - - man 8 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/v2/sisu_markup_samples/dfsg - -These are installed on the system usually at: - /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg - -More markup samples are available in the package sisu-markup-samples - <http://www.jus.uio.no/sisu/SiSU/download.html#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/v2/conf/editor-syntax-etc - -usually installed to: - - /usr/share/sisu/v2/conf/editor-syntax-etc - -v1, v2 Changes ---------------- - -See changelogs - -From a developer's perspective the substantive change between the two versions -is to the middle layer, (the document abstraction, the intermediate document -representation used in processing). Version 1 uses strings and relies on -regular expressions to identify document objects, while Version 2 uses ruby -objects. The version 1 approach whilst programming language neutral offers less -control, and leads to complicated code; version 2 approach takes advantage of -features within the ruby language suited to what the application does. -Development is curently on version 2, version 1 is likely to remain for some -time as a reference implementation. - -%% v1, v2 Compatibility Notes ---------------- - -Versions 1 and 2 are not quite compatible, version 1 and version 2 will run -against each other's documents but document metadata, and processing -instructions may be lost. - -On the input side, version 1 and 2 headers are different, version 2 headers -have been tidied, see document markup samples provided - -On the output side, the sql databases produced if search is to be implemented -are not the same and a database must be generated for each version, most other -differences should be relatively cosmetic. - -%% License ---------------- - -License: GPL 3 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 - -CHANGELOG - ./CHANGELOG -and see - <http://www.jus.uio.no/sisu/SiSU/changelog.html> - <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html> |