diff options
Diffstat (limited to 'man/man8/sisu_howto.8')
| -rw-r--r-- | man/man8/sisu_howto.8 | 2301 |
1 files changed, 0 insertions, 2301 deletions
diff --git a/man/man8/sisu_howto.8 b/man/man8/sisu_howto.8 deleted file mode 100644 index 7717fd7d..00000000 --- a/man/man8/sisu_howto.8 +++ /dev/null @@ -1,2301 +0,0 @@ -.TH "sisu_howto" "1" "2007-09-16" "0.59.1" "SiSU" -.SH -SISU \- 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), ruby (<< 1.9), libwebrick\-ruby, unzip, zip - Conflicts: vim\-sisu, sisu\-vim, sisu\-remote - Replaces: vim\-sisu, sisu\-vim - Recommends: sisu\-doc, 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), ruby (<< 1.9), sisu, sisu\-doc, 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 structuring, publishing and search - framework for document collections. - \. - See sisu for a description of the package. - \. - Homepage: <http://www.jus.uio.no/sisu> -.fi - - -.nf - Package: sisu\-doc - Architecture: all - Depends: sisu - Recommends: sisu\-pdf, sisu\-postgresql, sisu\-sqlite - Description: sisu manual and other documentation for sisu - Multiple file formats generated output of sisu documentation generated from - sisu markup source documents included in the main package - \. - SiSU is a lightweight markup based document structuring, publishing and search - framework for document collections. - \. - 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 - Recommends: sisu\-doc - 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 structuring, publishing and search - framework for document collections. - \. - 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: sisu\-doc, 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 structuring, publishing and search - framework for document collections. - \. - 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: sisu\-doc, 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 structuring, publishing and search - framework for document collections. - \. - 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 \- 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 c0491e0093434f4d962ce3b59e4985ca - -.BR -Skin_Digest: -MD5(/home/ralph/grotto/theatre/dbld/builds/sisu/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 Tue Sep 25 02:54:45 +0100 2007 - -.BR -Generated by: -.I SiSU -.I 0.59.1 -of 2007w39/2 (2007\-09\-25) - -.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.59.1 of 2007w39/2 (2007-09-25) -.TP -* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] -.TP -* Last Generated on: Tue Sep 25 02:54:51 +0100 2007 -.TP -* SiSU http://www.jus.uio.no/sisu |