diff options
Diffstat (limited to 'man/man8/sisu_howto.8')
| -rw-r--r-- | man/man8/sisu_howto.8 | 2283 |
1 files changed, 2283 insertions, 0 deletions
diff --git a/man/man8/sisu_howto.8 b/man/man8/sisu_howto.8 new file mode 100644 index 00000000..42bd1caf --- /dev/null +++ b/man/man8/sisu_howto.8 @@ -0,0 +1,2283 @@ +.TH "sisu_howto" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- TECHNICAL, HOWTO, +RALPH AMISSAH +.BR + +.SH +SISU SOME TECHNICAL INFORMATION +.BR + +.SH +HOWTO +.BR + +.SH +1. GETTING HELP +.BR + +.BR +An online manual of sorts should be available at: + +.BR +<http://www.jus.uio.no/sisu_manual/> + +.BR +The manual pages provided with +.B SiSU +are also available online, and there is an interactive help, which is being +superseded by the man page, and possibly some document which contains this +component. + +.SH +1.1 SISU \"MAN\" PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR +man sisu + +.BR +The +.B SiSU +man pages can be viewed online at:[^1] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages <http://www.jus.uio.no/sisu/man/> \ [^2] + +.BR +* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> \ [^3] + +.BR +* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8.html> \ [^4] + +.BR +* sisu_examples.1 <http://www.jus.uio.no/sisu/man/sisu_examples.1.html> \ [^5] + +.BR +* sisu_webrick.1 <http://www.jus.uio.no/sisu/man/sisu_webrick.1.html> \ [^6] + +.SH +1.2 SISU BUILT\-IN HELP + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.SH +1.3 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. + +.BR +In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h +cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all +documents. + +.SH +2. SETUP, INITIALISATION +.BR + +.SH +2.1 INITIALISE OUTPUT DIRECTORY + +.BR +Images, css files for a document directory are copied to their respective +locations in the output directory. + +.BR +while within your document markup/preparation directory, issue the following +command + +.BR + sisu \-CC + +.SH +2.1.1 USE OF SEARCH FUNCTIONALITY, AN EXAMPLE USING SQLITE + +.BR +.B SiSU +can populate PostgreSQL and Sqlite databases and provides a sample search +form for querying these databases. + +.BR +This note provides an example to get you started and will use sqlite + +.BR +It is necessary to: + +.BR +(1) make sure the required dependencies have been installed + +.BR +(2) have a directory with sisu markup samples that is writable + +.BR +(3) use sisu to create a database + +.BR +(4) use sisu tp populate a database + +.BR +(5) use sisu to start the webrick (httpd) server + +.BR +(6) use sisu to create a search form + +.BR +(7) copy the search form to the cgi directory + +.BR +(8) open up the form in your browser + +.BR +(9) query the database using the search form + +.BR +.B (1) make sure the required dependencies have been installed + +.BR +if you use +.B Debian +, the following command will install the required dependencies + +.BR +aptitude install sisu\-sqlite + +.BR +.B (2) have a directory with sisu markup samples that is writable + +.BR +ideally copy the sisu\-examples directory to your home directory (because the +directory in which you run this example should be writable) + +.BR +cp \-rv /usr/share/sisu\-examples/sample/document_samples_sisu_markup ~/. + +.BR +.B (3) use sisu to create an sqlite database + +.BR +within the sisu\-examples directory + +.BR +sisu \-dv createall + +.BR +.B (4) use sisu tp populate a database with some text + +.BR +within the sisu\-examples directory + +.BR +sisu \-div free_*.sst + +.BR +or + +.BR +sisu \-dv import free_*.sst debian_constitution_v1.2.sst +debian_social_contract_v1.1.sst gpl2.fsf.sst + +.BR +.B (5) use sisu to start the webrick (httpd) server (if it has not already +been started): + +.BR +sisu \-W + +.BR +.B (6) use sisu to create a search form (for use with the webrick server, and +your sample documents) + +.BR +within the sisu\-examples directory + +.BR +sisu \-F webrick + +.BR +#here i run into a problem, you are working from a read only #directory..., not +my usual mode of operation, to complete the example #the following is necessary +sudo touch sisu_sqlite.cgi sisu_pgsql.cgi sudo \-P chown $USER sisu_sqlite.cgi +sisu_pgsql.cgi + +.BR +#now this should be possible: sisu \-F webrick + +.BR +.B (7) copy the search form to the cgi directory + +.BR +the string should be provided as output from the previous command + +.BR +sudo cp \-vi +/usr/share/sisu\-examples/sample/document_samples_sisu_markup/sisu_sqlite.cgi +/usr/lib/cgi\-bin + +.BR +sudo chmod \-v 755 /usr/lib/cgi\-bin/sisu_sqlite.cgi + +.BR +.B (8) open up the form in your browser and query it + +.BR +url: + +.BR +<http://localhost:8081/cgi\-bin/sisu_sqlite.cgi> + +.BR +or as instructed by command sisu \-F webrick + +.BR +.B (9) query the database using the search form + +.BR +if there are other options in the dropdown menu select + +.BR +document_samples_sisu_markup + +.BR +and search for some text, e.g.: + +.BR +aim OR project + +.BR +* selecting the +.B index +radio button gives an index of results using the object numbers + +.BR +* selecting the +.B text +radio button gives the content of the matched paragraphs with the match +highlighted + +.BR +.B (10) to start again with a new database + +.BR +to start from scratch you can drop the database with the command + +.BR +sisu \-dv dropall + +.BR +and go to step 3 + +.BR +to get to step 3 in one step with a single command + +.BR +sisu \-dv recreate + +.BR +continue subsequent steps + +.SH +2.2 MISC + +.SH +2.2.1 URL FOR OUTPUT FILES \-U \-U + +.BR + sisu \-uv[and \ other \ flags] \ [filename/wildcard] + +.BR + sisu \-Uv \ [filename/wildcard] + +.SH +2.2.2 TOGGLE SCREEN COLOR + +.BR + sisu \-cv[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.3 VERBOSE MODE + +.BR + sisu \-v[and \ processing \ flags] \ [filename/wildcard] + +.BR + sisu \-V[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.4 QUIET MODE + +.BR + sisu \-q[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.5 MAINTENANCE MODE INTERMEDIATE FILES KEPT \-M + +.BR + sisu \-Mv[and \ other \ flags] \ [filename/wildcard] + +.SH +2.2.6 START THE WEBRICK SERVER + +.BR + sisu \-W + +.SH +2.3 REMOTE PLACEMENT OF OUTPUT + +.BR +configuration is necessary + +.BR +scp + +.BR + sisu \-vr[and \ processing \ flags] \ [filename/wildcard] + +.BR +rsync + +.BR + sisu \-vR[and \ processing \ flags] \ [filename/wildcard] + +.SH +3. CONFIGURATION FILES +.BR + +.BR +Sample provided, on untarring the source tarball: + +.BR + conf/sisu/sisurc.yaml + +.BR +and on installation under: + +.BR + /etc/sisu/sisurc.yaml + +.BR +The following paths are searched: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + ./etc/sisu/sisurc.yaml + +.SH +4. MARKUP +.BR + +.BR +See sample markup provided on + +.BR +<http://www.jus.uio.no/sisu> + +.BR +<http://www.jus.uio.no/sisu_markup> + +.BR +<http://www.jus.uio.no/sisu/SiSU> + +.BR +in particular for each of the document output samples provided, the source +document is provided as well + +.BR +<http://www.jus.uio.no/sisu/SiSU/2#books> + +.BR +on untarring the source tarball: + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +or the same once source is installed (or sisu\-examples) under: + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +Some notes are contained within the man page, +.B man sisu +and within sisu help via the commands +.B sisu help markup +and +.B sisu help headers + +.BR +.B SiSU +is for literary and legal text, also for some social science material. In +particular it does not do formula, and is not particularly suited to technical +documentation. Despite the latter caveat, some notes will be provided here and +added to over time: + +.SH +4.1 HEADERS + +.BR +Headers @headername: provide information related to the document, this may +relate to + +.BR +1. how it is to be processed, such as whether headings are to be numbered, what +skin is to be used and markup instructions, such as the document structure, or +words to be made bold within the document + +.BR +2. semantic information about the document including the dublin core + +.SH +4.2 FONT FACE + +.BR +Defaults are set. You may change the face to: bold, italics, underscore, +strikethrough, ... + +.SH +4.2.1 BOLD + +.BR +\@bold: \ [list \ of \ words \ that \ should \ be \ made \ bold \ within \ +document] + +.BR +.B bold line + +.BR +!_ bold line + +.BR +.B bold word or sentence + +.BR +!{ bold word or sentence }! + +.BR +*{ bold word or sentence }* + +.BR +.B boldword +or +.B boldword + +.BR +*boldword* or !boldword! + +.SH +4.2.2 ITALICS + +.BR +\@italics: \ [list \ of \ words \ that \ should \ be \ italicised \ within \ +document] + +.BR +.I italicise word or sentence + +.BR +/{ italicise word or sentence }/ + +.BR +.I italicisedword + +.BR +/italicisedword/ + +.SH +4.2.3 UNDERSCORE + +.BR +.I underscore word or sentence + +.BR +_{ underscore word or sentence }_ + +.BR +.I underscoreword + +.SH +4.2.4 STRIKETHROUGH + +.BR +<del> strikethrough word or sentence </del> + +.BR +\-{ strikethrough word or sentence }\- + +.BR +<del>strikeword</del> + +.BR +\-strikeword\- + +.SH +4.3 ENDNOTES + +.BR +There are two forms of markup for endnotes, they cannot be mixed within the +same document + +.BR +here[^7] + +.BR +1. preferred endnote markup + +.BR +here~{ this is an endnote }~ + +.BR +2. alternative markup equivalent, kept because it is possible to search and +replace to get markup in existing texts such as Project Gutenberg + +.BR +here~^ + +.BR +^~ this is an endote + +.SH +4.4 LINKS + +.BR +SiSU <http://sisudoc.org> + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +sisu.png 120x39 <http://sisudoc.org> + +.BR +{sisu.png }http://sisudoc.org + +.BR +[ tux.png ] + +.BR +{ tux.png 64x80 }image + +.BR +SiSU <http://sisudoc.org> \ [^8] + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +is equivalent to: + +.BR +{ +.B SiSU +}http://sisudoc.org ~{ <http://sisudoc.org> }~ + +.BR +the same can be done with an image: + +.BR +sisu.png 120x39 \"SiSU\" <http://sisudoc.org> \ [^10] + +.BR +{ sisu.png \" +.B SiSU +\" }http://sisudoc.org + +.SH +4.5 NUMBER TITLES + +.BR +Set with the header @markup: + +.SH +4.6 LINE OPERATIONS + +.BR +Line Operations (marker placed at start of line) + +.BR +!_ bold line + +.BR +.B bold line + +.BR +_1 indent paragraph one level + +.BR + indent paragraph one level + +.BR +_2 indent paragraph two steps + +.BR + indent paragraph two steps + +.BR +_* bullet paragraph + +.BR +* bullet paragraph + +.BR +# number paragraph (see headers for numbering document headings) + +.BR +1. number paragraph (see headers for numbering document headings) + +.BR +_# number paragraph level 2 (see headers for numbering document headings) + +.BR + a. number paragraph level 2 (see headers for numbering document headings) + +.SH +4.7 TABLES + +.BR +Table markup sample + + +table{~h c3; 26; 32; 32; +.P + + +This is a table, column1 +.P +this would become row one of column two +.P +column three of row one is here +.P + + +column one row 2 +.P +column two of row two +.P +column three of row two, and so on +.P + + +column one row three +.P +and so on +.P +here +.P + + +}table +.P + +.BR +Alternative form of table markup + + +.nf + {t\~h} + |Mon|Tue|Wed|Thu|Fri|Sat|Sun + 0 | * | * | * | * | * | * | * + 1 | * | * | * | * | | | + 2 | \- | * | * | * | * | * | + 3 | \- | * | * | * | * | * | * + 4 | \- | | | * | * | * | + 5 | * | * | * | * | * | * | * +.fi + +.SH +4.8 GROUPED TEXT + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +code{ + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +}code + + +A Limerick +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +poem{ +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +}\poem +.P + +.SH +4.9 COMPOSITE DOCUMENT + +.BR +To import another document, the master document or importing document should be +named filename.r3 (r for require) + +.BR +<< { filename.sst } + +.BR +<< { filename.ssi } + +.SH +5. CHANGE APPEARANCE +.BR + +.SH +5.1 SKINS + +.BR +\"Skins\" may be used to change various aspects related to the output documents +appearance, including such things as the url for the home page on which the +material will be published, information on the credit band, and for html +documents colours and icons used in navigation bars. Skins are ruby files which +permit changing of the default values set within the program for +.B SiSU +output. + +.BR +There are a few examples provided, on untarring the source tarball: + +.BR + conf/sisu/skin/doc/ + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +and on installation under: + +.BR + /etc/sisu/skin/doc/ + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +The following paths are searched: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +Skins under the searched paths in a per document directory, a per directory +directory, or a site directory, named: + +.BR +doc \ [may \ be \ specified \ individually \ in \ each \ document] + +.BR +dir \ [used \ if \ identifier \ part \ of \ name \ matches \ markup \ directory +\ name] + +.BR +site + +.BR +It is usual to place all skins in the document directory, with symbolic links +as required from dir or site directories. + +.SH +5.2 CSS + +.BR +The appearance of html and XML related output can be changed for an ouput +collection directory by prepareing and placing a new css file in one of the +sisu css directories searched in the sisu configuration path. These are located +at: + +.BR +_./_sisu/css + +.BR +~/.sisu/css + +.BR +and + +.BR +/etc/sisu/css + +.BR +The contents of the first directory found in the search path are copied to the +corresponding sisu output directory with the commnd: + +.BR +sisu \-CC + +.BR +The +.B SiSU +standard css files for +.B SiSU +output are: + +.BR +dom.css html.css html_tables.css index.css sax.css xhtml.css + +.BR +A document may specify its own/bespoke css file using the css header. + +.BR +\@css: + +.BR +[expand] + +.SH +EXTRACTS FROM THE README +.BR + +.SH +6. README +.BR + +.BR +.B SiSU +0.55 2007w27/6 2007\-07\-07 + +.BR +Homepage: <http://www.jus.uio.no/sisu> + +.BR +.B Description + +.BR +.B SiSU +is lightweight markup based document creation and publishing framework that +is controlled from the command line. Prepare documents for +.B SiSU +using your text editor of choice, then use +.B SiSU +to generate various output document formats. + +.BR +With minimal preparation of a plain\-text (UTF\-8) file using its native +markup\-syntax, +.B 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. + +.BR +Outputs share a common citation numbering system, and any semantic meta\-data +provided about the document. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +.B 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. +.B 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). + +.BR +A vim syntax highlighting file and an ftplugin with folds for sisu markup is +provided. Vim 7 includes syntax highlighting for +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: <http://www.jus.uio.no/sisu> + +.BR +.B 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. + +.BR +.B SiSU +can be used for Internet, Intranet, local filesystem or cd publishing. + +.BR +.B SiSU +can be used directly off the filesystem, or from a database. + +.BR +.B SiSU +\'s scalability, is be dependent on your hardware, and filesystem (in my case +Reiserfs), and/or database Postgresql. + +.BR +Amongst it\'s characteristics are: + +.BR +* simple mnemonoic markup style, + +.BR +* 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, + +.BR +* 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. + +.BR +* it is command line driven, and can be set up on a remote server + +.BR +* Documents are marked up in +.B SiSU +syntax in your favourite editor. +.B 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. + +.BR +Input files should be UTF\-8 + +.BR +Once set up it is simple to use. + +.SH +6.1 ONLINE INFORMATION, PLACES TO LOOK + +.BR +<http://www.jus.uio.no/sisu> + +.BR +Download Sources: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#debian> + +.SH +6.2 INSTALLATION + +.BR +NB. Platform is Unix / Linux. + +.SH +6.2.1 DEBIAN + +.BR +If you use +.B Debian +use the +.B Debian +packages, check the information at: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#debian> + +.BR +(A) +.B SiSU +is available directly off the +.B Debian +archives for Sid and testing. It should necessary only to run as root: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.BR +(B) If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + +.BR + deb <http://www.jus.uio.no/sisu/archive> unstable main non\-free + +.BR + deb\-src <http://www.jus.uio.no/sisu/archive> unstable main non\-free + +.BR +[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] + +.BR +Then as root run: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.SH +6.2.2 RPM + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#rpm> + +.SH +6.2.3 SOURCE PACKAGE .TGZ + +.BR +Otherwise to install +.B SiSU +from source, check information at: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + +.BR +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, + +.BR +.B Ruby +is the essential dependency for the basic operation of +.B SiSU + +.BR +1. Download the latest source (information available) from: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + +.BR +2. Unpack the source + +.BR +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. + +.SH +6.2.4 TO USE SETUP.RB + +.BR +this is a three step process, in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby setup.rb config + +.BR + ruby setup.rb setup + +.BR +as root: + +.BR + ruby setup.rb install + +.BR +further information: + +.BR + <http://i.loveruby.net/en/projects/setup/> + +.BR + <http://i.loveruby.net/en/projects/setup/doc/usage.html> + +.SH +6.2.5 TO USE INSTALL (PRAPARED WITH \"RAKE\") + +.BR +Rake must be installed on your system: + +.BR + <http://rake.rubyforge.org/> + +.BR + <http://rubyforge.org/frs/?group_id=50> + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + rake + +.BR +or + +.BR + rake base + +.BR +This makes use of Rake (by Jim Weirich) and the provided Rakefile + +.BR +For a list of alternative actions you may type: + +.BR + rake help + +.BR + rake \-T + +.SH +6.2.6 TO USE INSTALL (PRAPARED WITH \"RANT\") + +.BR +(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:) + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby ./sisu\-install + +.BR +or + +.BR + ruby ./sisu\-install base + +.BR +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. + +.BR +further information: + +.BR + <http://make.rubyforge.org/> + +.BR + <http://rubyforge.org/frs/?group_id=615> + +.BR +For a list of alternative actions you may type: + +.BR + ruby ./sisu\-install help + +.BR + ruby ./sisu\-install \-T + +.SH +6.3 DEPENDENCIES + +.BR +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 +.B 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. + +.BR +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 +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +). + +.BR +The following is from the debian/control file of sisu\-0.58.2, which amongst +other things provides the dependencies of sisu within +.B Debian +. + + +.nf + 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 +.fi + + +.nf + Source: sisu + Section: text + Priority: optional + Maintainer: Ralph Amissah <ralph@amissah.com> + Build\-Depends: debhelper (>= 5) + Standards\-Version: 3.7.2 + 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, hyperestraier, keychain, librmagick\-ruby, librexml\-ruby, openssl, openssh\-client | lsh\-client, rsync, tidy, vim\-addon\-manager + Suggests: kdissert, lv, rcs | cvs, pinfo, texinfo, trang + 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, 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. + . + Homepage: <http://www.jus.uio.no/sisu> +.fi + + +.nf + Package: sisu\-complete + Architecture: all + Depends: ruby (>= 1.8.2), sisu, sisu\-pdf, sisu\-postgresql, sisu\-sqlite + Recommends: hyperestraier + Description: installs all SiSU related packages + This package installs SiSU and related packages that enable sisu to produce + pdf and to populate postgresql and sqlite databases. + . + SiSU is a lightweight markup based document publishing framework. + . + See sisu for a description of the package. + . + Homepage: <http://www.jus.uio.no/sisu> +.fi + + +.nf + Package: sisu\-pdf + Architecture: all + Depends: sisu, texlive\-latex\-base, texlive\-fonts\-recommended, texlive\-latex\-recommended, texlive\-latex\-extra + #Suggests: evince, xpdf + Description: dependencies to convert SiSU LaTeX output to pdf + This package enables the conversion of SiSU LaTeX output to pdf. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: <http://www.jus.uio.no/sisu> +.fi + + +.nf + Package: sisu\-postgresql + Architecture: all + Depends: sisu, libdbd\-pg\-ruby, libdbi\-ruby, libdbm\-ruby, postgresql + Recommends: libfcgi\-ruby + Suggests: postgresql\-contrib + Description: SiSU dependencies for use with postgresql database + 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. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: <http://www.jus.uio.no/sisu> +.fi + + +.nf + Package: sisu\-sqlite + Architecture: all + Depends: sisu, sqlite, libdbd\-sqlite\-ruby, libdbi\-ruby, libdbm\-ruby + Recommends: libfcgi\-ruby + Description: SiSU dependencies for use with sqlite database + 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. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: <http://www.jus.uio.no/sisu> +.fi + +.SH +6.4 QUICK START + +.BR +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). + +.BR +After installation of sisu\-complete, move to the document samples directory + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +and run + +.BR + sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +or to generate an online document move to a writable directory, as the file +will be downloaded there and e.g. + +.BR +sisu \-3 +<http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst> + +.BR +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 + +.BR +examine source document, vim has syntax support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + <http://www.jus.uio.no/sisu/SiSU/2.html> + +.BR +For help + +.BR + man sisu + +.BR +or + +.BR + sisu \-\-help + +.BR +e.g. + +.BR +for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help env + +.BR +for list of commands and so on + +.BR + sisu \-\-help commands + +.SH +6.5 CONFIGURATION FILES + +.BR +The default configuration/setup is contained within the program and is altered +by configuration settings in +.I etc +[sisu \ version]/sisurc.yml or in ~/.sisu/sisurc.yml + +.BR +* configuration file \- a yaml file + +.BR + /etc/sisu/[sisu \ version]/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR +* directory structure \- setting up of output and working directory. + +.BR +* skins \- changing the appearance of a project, directory or individual +documents within ~/.sisu/skin + +.BR + ~/.sisu/skin/doc contains individual skins, with symbolic links from + +.BR + ~/.sisu/skin/dir if the contents of a directory are to take a particular + document skin. + +.BR +* additional software \- eg. Tex and LaTeX (tetex, tetex\-base, tetex\-extra on +.B Debian +), Postgresql, \ [sqlite], trang, tidy, makeinfo, ... none of which are +required for basic html or XML processing. + +.BR +* if you use Vim as editor there is a syntax highlighter and fold resource +config file for +.B SiSU +. I hope more syntax highlighters follow. + +.BR +There are post installation steps (which are really part of the overall +installation) + +.BR +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). + +.SH +6.6 USE GENERAL OVERVIEW + +.BR +Documents are marked up in +.B SiSU +syntax and kept in an ordinary text editable file, named with the suffix +.sst, or .ssm + +.BR +Marked up +.B SiSU +documents are usually kept in a sub\-directory of your choosing + +.BR +use the interactive help and man pages + +.BR + sisu \-\-help + +.BR + man sisu + +.SH +6.7 HELP + +.BR +interactive help described below, or man page: + +.BR + man sisu + +.BR + man 8 sisu + +.BR +\'man sisu_markup\-samples\' \ [if \ the \ sisu\-markup\-samples \ package \ is +\ also \ installed] + +.BR +Once installed an interactive help is available typing \'sisu\' (without) any +flags, and select an option: + +.BR + sisu + +.BR +alternatively, you could type e.g. + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help env + +.BR + sisu \-\-help headers + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help headings + +.BR +etc. + +.BR +for questions about mappings, output paths etc. + +.BR + sisu \-\-help env + +.BR + sisu \-\-help path + +.BR + sisu \-\-help directory + +.SH +6.8 DIRECTORY STRUCTURE + +.BR +Once installed, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.SH +6.9 CONFIGURATION FILE + +.BR +The defaults can be changed via +.B 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) + +.SH +6.10 MARKUP + +.BR +See man pages. + +.BR + man sisu + +.BR + man 8 sisu + +.BR +Once installed there is some information on +.B SiSU +Markup in its help: + +.BR + sisu \-\-help markup + +.BR +and + +.BR + sisu \-\-help headers + +.BR +Sample marked up document are provided with the download tarball in the +directory: + +.BR + ./data/doc/sisu/sisu_markup_samples/dfsg + +.BR +These are installed on the system usually at: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +More markup samples are available in the package sisu\-markup\-samples + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#sisu\-markup\-samples> + +.BR +Many more are available online off: + +.BR + <http://www.jus.uio.no/sisu/SiSU/2.html> + +.SH +6.11 ADDITIONAL THINGS + +.BR +There is syntax support for some editors provided (together with a README file) +in + +.BR + ./data/sisu/conf/syntax + +.BR +usually installed to: + +.BR + /usr/share/sisu/conf/syntax + +.SH +6.12 LICENSE + +.BR +License: GPL 3 or later see the copyright file in + +.BR + ./data/doc/sisu + +.BR +usually installed to: + +.BR + /usr/share/doc/sisu + +.SH +6.13 SISU STANDARD + +.BR +.B SiSU +uses: + +.BR +* Standard +.B SiSU +markup syntax, + +.BR +* Standard +.B SiSU +meta\-markup syntax, and the + +.BR +* Standard +.B SiSU +object citation numbering and system + +.BR +© Ralph Amissah 1997, current 2006 All Rights Reserved. + +.BR +* however note the License section + +.BR +CHANGELOG + +.BR + ./CHANGELOG + +.BR +and see + +.BR + <http://www.jus.uio.no/sisu/SiSU/changelog.html> + +.BR + <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html> + +.SH +EXTRACTS FROM MAN 8 SISU +.BR + +.SH +7. POST INSTALLATION SETUP +.BR + +.SH +7.1 POST INSTALLATION SETUP \- QUICK START + +.BR +After installation of sisu\-complete, move to the document samples directory, + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +[this \ is \ not \ where \ you \ would \ normally \ work \ but \ provides \ +sample \ documents \ for \ testing, \ you \ may \ prefer \ instead \ to \ copy +\ the \ contents \ of \ that \ directory \ to \ a \ local \ directory \ before +\ proceeding] + +.BR +and in that directory, initialise the output directory with the command + +.BR + sisu \-CC + +.BR +then run: + +.BR + sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +for an overview of your current sisu setup, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.BR +To generate a document from a remote url accessible location move to a writable +directory, (create a work directory and cd into it) as the file will be +downloaded there and e.g. + +.BR + sisu \-1 <http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst> + +.BR + sisu \-3 + <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst> + +.BR +examine source document, vim has syntax highlighting support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + <http://www.jus.uio.no/sisu/SiSU/2.html> + +.BR +it should also be possible to run sisu against sisupods (prepared zip files, +created by running the command sisu \-S \ [filename]), whether stored locally +or remotely. + +.BR + sisu \-3 + <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip> + +.BR +there is a security issue associated with the running of document skins that +are not your own, so these are turned of by default, and the use of the +following command, which switches on the associated skin is not recommended: + +.BR + sisu \-3 \-\-trust + <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip> + +.BR +For help + +.BR + man sisu + +.BR + sisu \-\-help + +.BR + sisu \-\-help env for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help commands for list of commands and so on + +.SH +7.2 DOCUMENT MARKUP DIRECTORY + +.BR +Perhaps the easiest way to begin is to create a directory for sisu marked up +documents within your home directory, and copy the file structure (and document +samples) provided in the document sample directory: + +.BR + mkdir ~/sisu_test + +.BR + cd ~/sisu_test + +.BR + cp \-a /usr/share/doc/sisu/sisu_markup_samples/dfsg/* ~/sisu_test/. + +.BR +.B Tip: +the markup syntax examples may be of interest + +.BR + <http://www.jus.uio.no/sisu/sample/> + +.BR +.B Tip: + +.BR + sisu \-U \ [sisu \ markup \ filename] + +.BR +should printout the different possible outputs and where sisu would place them. + +.BR +.B Tip: +if you want to toggle ansi color add + +.BR + c + +.BR +to your flags. + +.SH +7.2.1 CONFIGURATION FILES + +.BR +.B SiSU +configuration file search path is: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/sisurc.yaml + +.BR +.\\"%% +.B Debian +Installation Note + +.SH +7.2.2 DEBIAN INSTALLATION NOTE + +.BR +It is best you see + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#debian> + +.BR +for up the most up to date information. + +.BR +notes taken from the +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +): + +.BR +Package: sisu + +.BR +.B SiSU +is a lightweight markup based, command line oriented, document structuring, +publishing and search framework for document collections. + +.BR +With minimal preparation of a plain\-text, (UTF\-8) file, using its native +markup syntax in your text editor of choice, +.B SiSU +can generate various document formats (most of which share a common object +numbering system for locating content), including plain text, HTML, XHTML, XML, +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. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +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 +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: <http://www.jus.uio.no/sisu> + +.SH +7.2.3 DOCUMENT RESOURCE CONFIGURATION + +.BR +.B sisu +resource configuration information is obtained from sources (where they +exist): + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/[sisu \ version]/sisurc.yaml + +.BR + sisu program defaults + +.SH +7.2.4 SKINS + +.BR +.B Skins +default document appearance may be modified using skins contained in +sub\-directories located at the following paths: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +more specifically, the following locations (or their /etc/sisu equivalent) +should be used: + +.BR + ~/.sisu/skin/doc + +.BR +skins for individual documents; + +.BR + ~/.sisu/skin/dir + +.BR +skins for directories of matching names; + +.BR + ~/.sisu/skin/site + +.BR +site\-wide skin modifying the site\-wide appearance of documents. + +.BR +Usually all skin files are placed in the document skin directory: + +.BR + ~/.sisu/skin/doc + +.BR +with softlinks being made to the skins contained there from other skin +directories as required. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_howto/sisu_manifest.html> + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Technical, Howto + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_howto.sst + +.BR +Filetype: +.I SiSU text insert 0.57 + +.BR +Sourcefile Digest, MD5(sisu_howto.sst)= +.I 82c606e66689bcb5d190edf8fc7227a0 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:01 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +generated from source using rman + <http://polyglotman.sourceforge.net/rman.html> + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + <http://www.jus.uio.no/sample> +.TP +.BI 2. +<http://www.jus.uio.no/sisu/man/> +.TP +.BI 3. +<http://www.jus.uio.no/sisu/man/sisu.1.html> +.TP +.BI 4. +<http://www.jus.uio.no/sisu/man/sisu.8.html> +.TP +.BI 5. +<http://www.jus.uio.no/sisu/man/sisu_examples.1.html> +.TP +.BI 6. +<http://www.jus.uio.no/sisu/man/sisu_webrick.1.html> +.TP +.BI 7. +this is an endnote +.TP +.BI 8. +<http://sisudoc.org> +.TP +.BI 10. +<http://sisudoc.org> + +.TP +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_howto/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_howto/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_howto/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_howto/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_howto/sisu_howto.1 +.TP +at: <http://www.jus.uio.no/sisu> +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:06 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu |