|
|
|
|
|
|
|
|
|
|
|
|
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
1. Description
1.1 Outline
1.2 Short summary of features
1.3 How it works
1.4 Simple markup
1.4.1 Sparse markup requirement, try to get the most out of markup
1.4.2 Single markup file provides multiple output formats
1.4.3 Syntax relatively easy to read and remember
1.4.4 Kept simple by having a limited publishing feature set, and features identified as most important, are available across several document types
1.5 Designed with usability in mind
1.6 Code separate from content
1.7 Object citation numbering, a text or object positioning / citation system - "paragraph" (or text object) numbering, that remains same and usable across all output formats by people and machine
1.8 Handling of Dublin Core meta-tags making use of the Resource Description Framework
1.9 Easy directory management
1.10 Document Version Control Information
1.11 Table of contents
1.12 Auto-numbering of headings
1.13 Numbering and cross-hyperlinking of endnotes
1.14 "Skinnable"
1.15 Multiple Outputs
1.15.1 html - several presentations: full length & segmented; css & table based
1.15.2 EPUB
1.15.3 XML
1.15.4 ODT:ODF, Open Document Format - ISO/IEC 26300:2006
1.15.5 PDF - portrait and landscape, (through the generation of LaTeX output which is then transformed to pdf)
1.15.6 Search - loading/populating of relational database while retaining document structure information, object citation numbering and other features (currently PostgreSQL and/or SQLite)
1.15.7 Search - database frontend sample, utilising database and SiSU features, including object citation numbering (backend currently PostgreSQL)
1.15.8 Other forms
1.16 Concordance / Word Map or rudimentary index
1.17 Managed (document) directory, database, or site structure
1.18 Batch processing
1.19 Integration to superior Gnu/Linux and Unix tools
1.19.1 Backup and version control
1.19.2 Editor support
1.20 Modular design, need something new add a module
2. Markup and Output Examples
2.1 Markup examples
2.2 A few book (and other) examples
2.2.1 "Viral Spiral", David Bollier
"The Wealth of Networks", Yochai Benkler
"Two Bits", Christopher Kelty
"Free Culture", Lawrence Lessig
"CONTENT", Cory Doctorow
"Democratizing Innovation", by Eric von Hippel
"Free as in Freedom: Richard Stallman's Crusade for Free Software", by Sam Williams
"Free For All: How Linux and the Free Software Movement Undercut the High Tech Titans", by Peter Wayner
"The Cathedral and the Bazaar", by Eric S. Raymond
"Down and out in the Magic Kingdom", Cory Doctorow
"Little Brother", Cory Doctorow
"For the Win", Cory Doctorow
"Accelerando", Charles Stross
"Tainaron", Leena Krohn
"Sphinx or Robot", Leena Krohn
"War and Peace", Leo Tolstoy, PG Etext 2600
"Don Quixote", Miguel de Cervantes [Saavedra], translated by John Ormsby, PG Etext 996
"Gulliver's Travels", Jonathan Swift, transcribed from the 1892 George Bell and Sons edition by David Price, PG Etext 829
"Alice's Adventures in Wonderland", Lewis Carroll, PG Etext 11
"Through The Looking-Glass", Lewis Carroll, PG Etext 12
"Alice's Adventures in Wonderland" and "Through The Looking-Glass", Lewis Carroll, PG Etexts 11 and 12
"Gnu Public License 2", (GPL 2) Free Software Foundation
"Gnu Public License v3 - Third discussion draft", (GPLv3) Free Software Foundation
"Debian Social Contract"
"Debian Constitution v1.3", (simple/default markup)
"Debian Constitution v1.3", (markup adjusted for output to more closely match the original)
"Debian Constitution v1.2", (simple/default markup)
"Debian Constitution v1.2", (markup adjusted for output to more closely match the original)
"A Uniform Sales Terminology", Vikki Rogers and Albert Kritzer
"The Autonomous Contract" 1997 - markup sample
"The Autonomous Contract Revisited" - markup sample
"United Nations Convention on Contracts for the International Sale of Goods"
/PECL/ the "Principles of European Contract Law"
2.3 SQL - PostgreSQL, SQLite
2.4 Lex Mercatoria as an example
2.5 For good measure the markup for a document with lots of (simple) tables
2.6 And a link to the output of a reported case
3. A Checklist of Output Features
4. Introduction to SiSU Markup 114
4.1 Summary
4.2 Markup Examples
4.2.1 Online
4.2.2 Installed
5. Markup of Headers
5.1 Sample Header
5.2 Available Headers
6. Markup of Substantive Text
6.1 Heading Levels
6.2 Font Attributes
6.3 Indentation and bullets
6.4 Footnotes / Endnotes
6.5 Links
6.5.1 Naked URLs within text, dealing with urls
6.5.2 Linking Text
6.5.3 Linking Images
6.6 Grouped Text
6.6.1 Tables
6.6.2 Poem
6.6.3 Group
6.6.4 Code
6.7 Book index
7. Composite documents markup
Markup Syntax History
8. Notes related to Files-types and Markup Syntax
9. Commands Summary
9.1 Description
9.2 Document Processing Command Flags
10. command line modifiers
11. database commands
12. Shortcuts, Shorthand for multiple flags
12.1 Command Line with Flags - Batch Processing
Technical Information
13. Technical notes
13.1 See abandoned U.S. Provisional Patent Application
14. Diagram / Chart
14.1 The Chart
14.2 I/O
14.3 The Program
14.4 Software utilised
14.4.1 SiSU
14.4.2 SiSU Modules
15. SiSU development environment and technologies of interest, including data formats
15.1 Development environment, Debian
15.2 Programming language, Ruby
15.3 SGML & XML Family
15.3.1 SGML
15.3.2 XML Family
15.4 TeX Family
15.5 Pdf
15.6 Relational Databases, SQL
15.7 Other Databases
15.8 Text Search
15.9 Character Encoding, Unicode
15.10 Information Visualization
15.11 Metadata - semantic
15.12 Syndication, Web feed formats
15.13 Other
15.14 Editors
15.15 Version Control
15.16 Licenses
A Summary of notable events
16. A history of SiSU and its outputs including search
A Chronological history of developments on SiSU
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
January
February
March
April
June
July
August
September
November
December
2004
January
February
March
April
May
June
July
August
September
October
November
December
2005
January
February
March
April
May
June
July
August
September
October
November
December
2006
January
February
March
April
May
June
July
August
September
October
November
December
2007
January
February
March
April
May
June
July
August
September
November
December
2008
January
February
April
June
September
October
November
December
2009
January
December
2010
March
2010
March
FAQ, Howto, Installation, etc.
HowTo
17. Getting Help
17.1 SiSU "man" pages
17.2 SiSU built-in help
17.3 Command Line with Flags - Batch Processing
18. Setup, initialisation
18.1 initialise output directory
18.1.1 Use of search functionality, an example using sqlite
18.2 misc
18.2.1 url for output files -u -U
18.2.2 toggle screen color
18.2.3 verbose mode
18.2.4 quiet mode
18.2.5 maintenance mode intermediate files kept -M
18.2.6 start the webrick server
18.3 remote placement of output
19. Configuration Files
20. Markup
20.1 Headers
20.2 Font Face
20.2.1 Bold
20.2.2 Italics
20.2.3 Underscore
20.2.4 Strikethrough
20.3 Endnotes
20.4 Links
20.5 Number Titles
20.6 Line operations
20.7 Tables
20.8 Grouped Text
20.9 Composite Document
21. Change Appearance
21.1 Skins
21.2 CSS
Extracts from the README
22. README
22.1 Online Information, places to look
22.2 Installation
22.2.1 Debian
22.2.2 RPM
22.2.3 Source package .tgz
22.2.4 to use setup.rb
22.2.5 to use install (prapared with "Rake")
22.2.6 to use install (prapared with "Rant")
22.3 Dependencies
22.4 Quick start
22.5 Configuration files
22.6 Use General Overview
22.7 Help
22.8 Directory Structure
22.9 Configuration File
22.10 Markup
22.11 Additional Things
22.12 License
22.13 SiSU Standard
Extracts from man 8 sisu
23. Post Installation Setup
23.1 Post Installation Setup - Quick start
23.2 Document markup directory
23.2.1 Configuration files
23.2.2 Debian INSTALLATION Note
23.2.3 Document Resource Configuration
23.2.4 Skins
24. FAQ - Frequently Asked/Answered Questions
24.1 Why are urls produced with the -v (and -u) flag that point to a web server on port 8081 ?
24.2 I cannot find my output, where is it?
24.3 I do not get any pdf output, why?
24.4 Where is the latex (or some other interim) output?
24.5 Why isn't SiSU markup XML
24.6 LaTeX claims to be a document preparation system for high-quality typesetting. Can the same be said about SiSU?
24.7 Can the SiSU markup be used to prepare for a LaTex automatic building of an index to the work?
24.8 Can the conversion from SiSU to LaTeX be modified if we have special needs for the LaTeX, or do we need to modify the LaTeX manually?
24.9 How do I create GIN or GiST index in Postgresql for use in SiSU
24.10 Are there some examples of using Ferret Search with a SiSU repository?
Have you had any reports of building SiSU from tar on Mac OS 10.4?
24.12 Where is version 1?
24.13 What is the difference between version 1 and 2?
Installation
25. Installation
25.1 Debian
25.2 Other Unix / Linux
25.2.1 source tarball
26. SiSU Components, Dependencies and Notes
26.1 sisu
26.2 sisu-complete
26.3 sisu-examples
26.4 sisu-pdf
26.5 sisu-postgresql
26.6 sisu-remote
26.7 sisu-sqlite
27. Quickstart - Getting Started Howto
27.1 Installation
27.1.1 Debian Installation
27.1.2 RPM Installation
27.1.3 Installation from source
27.2 Testing SiSU, generating output
27.2.1 basic text, plaintext, html, XML, ODF, EPUB
27.2.2 LaTeX / pdf
27.2.3 relational database - postgresql, sqlite
27.3 Getting Help
27.3.1 The man pages
27.3.2 Built in help
27.3.3 The home page
27.4 Markup Samples
28. SiSU Components, Dependencies and Notes
29. Breakage and Fixes
31st October 2006 - SiSU < 0.48.3 break against Ruby > 1.8.5-3, break on cyclic include; Fixed SiSU: >=0.48.3 (see notes)
21st September 2005 - Avoid ruby-1.8.3 (2005-09-21) and (2005-10-12), Ruby Segfaults; Fixed: later versions of Ruby (see notes)
License, Standard
30. License
31. Things SiSU Standard
Download information
Download information
32. Download SiSU - Linux/Unix
SiSU Current Version - Linux/Unix
Source (tarball tar.gz)
Git (source control management)
Debian
RPM
Changelog - sisu
33. SiSU Version Manifest / changelog
Current version
3.0
Previous versions
2.7
2.6
2.5
2.4
2.3
2.2
2.1
2.0
1.0
0.71
0.70
0.69
0.68
0.67
0.66
0.65
0.64
0.63
0.62
0.61
0.60
0.59
0.58
0.57
0.56
0.55
0.54
0.53
0.52
0.51
0.50
0.49
0.48
0.47
0.46
0.45
0.44
0.43
0.42
0.41
0.40
0.39
0.38
0.37
0.36
0.35
0.34
0.33
0.32
0.31
0.30
0.29
0.28
0.27
0.26
0.25
0.24
0.23
0.22
0.21
0.20
0.18
0.16
0.14
0.12
0.10
0.8
0.6
0.4
0.2
0.1
Release
Changelog - sisu-markup-samples
34. Version Manifest / changelog - SiSU Markup Samples
Current version
2.0
1.1
1.0
Method for providing digital documents including a common citation structure
[SiSU Provisional Patent Application of 2004 based on much older idea and work on SiSU, Abandoned]
The 'Invention' described (and diagrams) by Ralph Amissah.
Provisional patent application text prepared by Stephan Filipek of Winston & Strawn LLP
35. 1. Background
36. 2. Definitions
37. 3. Brief Descriptions of the Drawings
38. 4. Detailed Description of the Preferred Embodiments
39. 5. Document Processing, examples of subsequent steps
40. 6. Advantages of the Invention
41. 7. THE CLAIMS
Post Filing Appendix
42. Post Filing Appendix: Reasons for Abandonment of Patent Process Claim
Endnotes
Endnotes
Metadata
SiSU Metadata, document information
Manifest
SiSU Manifest, alternative outputs etc.
SiSU - SiSU information Structuring Universe - Structured information, Serialized Units,
Structured information, Serialized Units
Installation
27.1 Installation
27.1.1 Debian Installation
27.1.2 RPM Installation
27.1.3 Installation from source
27.2 Testing SiSU, generating output
27.2.1 basic text, plaintext, html, XML, ODF, EPUB
27.2.2 LaTeX / pdf
27.2.3 relational database - postgresql, sqlite
27.3 Getting Help
27.3.1 The man pages
27.3.2 Built in help
27.3.3 The home page
27.4 Markup Samples
Installation is currently most straightforward and tested on the Debian platform, as there are packages for the installation of sisu and all requirements for what it does.
SiSU is available directly from the Debian Sid and testing archives (and possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly:
aptitude update
aptitude install sisu-complete
The following /etc/apt/sources.list setting permits the download of additional markup samples:
#/etc/apt/sources.list
deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib
The aptitude commands become:
aptitude update
aptitude install sisu-complete sisu-markup-samples
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
#/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
repeat the aptitude commands
aptitude update
aptitude install sisu-complete sisu-markup-samples
Note however that it is not necessary to install sisu-complete if not all components of sisu are to be used. Installing just the package sisu will provide basic functionality.
RPMs are provided though untested, they are prepared by running alien against the source package, and against the debs.
They may be downloaded from:
as root type:
rpm -i [rpm package name]
To install SiSU from source check information at:
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:
For basic use SiSU is only dependent on the programming language in which it is written Ruby, and SiSU will be able to generate html, EPUB, various XMLs, including ODF (and will also produce LaTeX). Dependencies required for further actions, though it relies on the installation of additional dependencies which the source tarball does not take care of, for things like using a database (postgresql or sqlite) 958 or converting LaTeX to pdf.
setup.rb
This is a standard ruby installer, using setup.rb is a three step process. In the root directory of the unpacked SiSU as root type:
ruby setup.rb config
ruby setup.rb setup
#[and as root:]
ruby setup.rb install
further information on setup.rb is available from:
"install"
The "install" file provided is an installer prepared using "rant". In the root directory of the unpacked SiSU as root type:
ruby install base
or for a more complete installation:
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 on "rant" is available from:
For a list of alternative actions you may type:
ruby install help
ruby install -T
To check which version of sisu is installed:
sisu -v
Depending on your mode of installation one or a number of markup sample files may be found either in the directory:
...
or
...
change directory to the appropriate one:
cd /usr/share/doc/sisu/markup-samples/samples
Having moved to the directory that contains the markup samples (see instructions above if necessary), choose a file and run sisu against it
sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text
Assuming a LaTeX engine such as tetex or texlive is installed with the required modules (done automatically on selection of sisu-pdf in Debian)
Having moved to the directory that contains the markup samples (see instructions above if necessary), choose a file and run sisu against it
sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst
sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
should generate most available output formats: html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text and pdf
Relational databases need some setting up - you must have permission to create the database and write to it when you run sisu.
Assuming you have the database installed and the requisite permissions
sisu --sqlite --recreate
sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
sisu --pgsql --recreate
sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
Type:
man sisu
The man pages are also available online, though not always kept as up to date as within the package itself:
sisu --help
sisu --help --env
sisu --help --commands
sisu --help --markup
A number of markup samples (along with output) are available off:
Additional markup samples are packaged separately in the file:
***
On Debian they are available in non-free 962 to include them it is necessary to include non-free in your /etc/apt/source.list or obtain them from the sisu home site.
958. There is nothing to stop MySQL support being added in future.
959. ‹http://www.jus.uio.no/sisu/man/sisu.1.html›
960. ‹http://www.jus.uio.no/sisu/man/sisu.8.html›
961. ‹http://www.jus.uio.no/sisu/man›
962. the Debian Free Software guidelines require that everything distributed within Debian can be changed - and the documents are authors' works that while freely distributable are not freely changeable.
