diff options
| author | Ralph Amissah <ralph@amissah.com> | 2007-09-23 05:16:21 +0100 |
|---|---|---|
| committer | Ralph Amissah <ralph@amissah.com> | 2007-09-23 05:16:21 +0100 |
| commit | 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 (patch) | |
| tree | 100c62d678f009139999bf77c26c81653a721eeb /man/man8 | |
| parent | sisu-0.58.3 + md5s (diff) | |
primarily todo with sisu documentation, changelog reproduced below:
* start documenting sisu using sisu
* sisu markup source files in
data/doc/sisu/sisu_markup_samples/sisu_manual/
/usr/share/doc/sisu/sisu_markup_samples/sisu_manual/
* default output [sisu -3] in
data/doc/manuals_generated/sisu_manual/
/usr/share/doc/manuals_generated/sisu_manual/
(adds substantially to the size of sisu package!)
* help related edits
* manpage, work on ability to generate manpages, improved
* param, exclude footnote mark count when occurs within code block
* plaintext changes made
* shared_txt, line wrap visited
* file:// link option introduced (in addition to existing https?:// and
ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and
hub]
* minor adjustments
* html url match refinement
* css added tiny_center
* plaintext
* endnotes fix
* footnote adjustment to make more easily distinguishable from substantive
text
* flag -a only [flags -A -e -E dropped]
controlled by modifiers --unix/msdos --footnote/endnote
* defaults, homepage
* renamed homepage (instead of index) implications for modifying skins,
which need likewise to have any homepage entry renamed
* added link to sisu_manual in homepage
* css the css for the default homepage is renamed homepage.css (instead of
index.css) [consider removing this and relying on html.css]
* ruby version < ruby1.9
* place stop on installation and working with for now [ruby String.strip
broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux],
2007-09-18:38/2]
* debian/control restrict use to ruby > 1.8.4 and ruby < 1.9
* debian
* debian/control restrict use to ruby > 1.8.4 and ruby < 1.9
* sisu-doc new sub-package for sisu documentation
debian/control and sisu-doc.install
Diffstat (limited to 'man/man8')
| -rw-r--r-- | man/man8/sisu_faq.8 | 404 | ||||
| -rw-r--r-- | man/man8/sisu_howto.8 | 2283 | ||||
| -rw-r--r-- | man/man8/sisu_quickstart.8 | 517 | ||||
| -rw-r--r-- | man/man8/sisu_remote.8 | 251 | ||||
| -rw-r--r-- | man/man8/sisu_search.8 | 639 | ||||
| -rw-r--r-- | man/man8/sisu_syntax_highlighting.8 | 307 |
6 files changed, 4401 insertions, 0 deletions
diff --git a/man/man8/sisu_faq.8 b/man/man8/sisu_faq.8 new file mode 100644 index 00000000..3146086c --- /dev/null +++ b/man/man8/sisu_faq.8 @@ -0,0 +1,404 @@ +.TH "sisu_faq" "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 \- FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS, +RALPH AMISSAH +.BR + +.SH +1. FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS +.BR + +.SH +1.1 WHY ARE URLS PRODUCED WITH THE \-V (AND \-U) FLAG THAT POINT TO A WEB +SERVER ON PORT 8081? + +.BR +Try the following rune: + +.BR +* sisu \-W + +.BR +This should start the ruby webserver. It should be done after having produced +some output as it scans the output directory for what to serve. + +.SH +1.2 I CANNOT FIND MY OUTPUT, WHERE IS IT? + +.BR +The following should provide help on output paths: + +.BR +* sisu \-\-help env + +.BR +* sisu \-V \ [same \ as \ the \ previous \ command] + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +* sisu \-U \ [filename] + +.BR +* man sisu + +.SH +1.3 I DO NOT GET ANY PDF OUTPUT, WHY? + +.BR +.B SiSU +produces LaTeX and pdflatex is run against that to generate pdf files. + +.BR +If you use +.B Debian +the following will install the required dependencies + +.BR +* aptitude install sisu\-pdf + +.BR +the following packages are required: tetex\-bin, tetex\-extra, latex\-ucs + +.SH +1.4 WHERE IS THE LATEX (OR SOME OTHER INTERIM) OUTPUT? + +.BR +Try adding \-M (for maintenance) to your command flags, e.g.: + +.BR +* sisu \-HpMv \ [filename] + +.BR +this should result in the interim processing output being retained, and +information being provided on where to find it. + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +should also provide some relevant information as to where it is placed. + +.SH +1.5 WHY ISN\'T SISU MARKUP XML + +.BR +I worked with text and (though I find XML immensely valuable) disliked noise +... better to sidestep the question and say: + +.BR +.B SiSU +currently \"understands\" three XML input representations \- or more +accurately, converts from three forms of XML to native +.B SiSU +markup for processing. The three types correspond to SAX (structure +described), DOM (structure embedded, whole document must be read before +structure is correctly discernable) and node based (a tree) forms of XML +document structure representation. Problem is I use them very seldom and check +that all is as it should be with them seldom, so I would not be surprised if +something breaks there, but as far as I know they are working. I will check and +add an XML markup help page before the next release. There already is a bit of +information in the man page under the title +.B SiSU +VERSION CONVERSION + +.BR + sisu \-\-to\-sax \ [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] + +.BR +The XML should be well formed... must check, but lacks sensible headers. +Suggestions welcome as to what to make of them. \ [For \ the \ present \ time \ +I \ am \ satisfied \ that \ I \ can \ convert \ (both \ ways) \ between \ 3 \ +forms \ of \ XML \ representation \ and +.B \ SiSU +\ markup]. + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard] + +.SH +1.6 LATEX CLAIMS TO BE A DOCUMENT PREPARATION SYSTEM FOR HIGH\-QUALITY +TYPESETTING. CAN THE SAME BE SAID ABOUT SISU? + +.BR +.B SiSU +is not really about type\-setting. + +.BR +LaTeX is the ultimate computer instruction type\-setting language for paper +based publication. + +.BR +LaTeX is able to control just about everything that happens on page and pixel, +position letters kerning, space variation between characters, words, paragraphs +etc. formula. + +.BR +.B SiSU +is not really about type\-setting at all. It is about a lightweight markup +instruction that provides enough information for an abstraction of the +documents structure and objects, from which different forms of representation +of the document can be generated. + +.BR +.B SiSU +with very little markup instruction is able to produce relatively high +quality pdf by virtue of being able to generate usable default LaTeX; it +produces \"quality\" html by generating the html directly; likewise it +populates an SQL database in a useful way with the document in object sized +chunks and its meta\-data. But +.B SiSU +works on an abstraction of the document\'s structure and content and custom +builds suitable uniform output. The html for browser viewing and pdf for paper +viewing/publishing are rather different things with different needs for layout +\- as indeed is what is needed to store information in a database in searchable +objects. + +.BR +The pdfs or html produced for example by open office based on open document +format and other office/word processor suits usually attempt to have similar +looking outputs \- your document rendered in html looks much the same, or in +pdf... sisu is less this way, it seeks to have a starting point with as little +information about appearance as possible, and to come up with the best possible +appearance for each output that can be derived based on this minimal +information. + +.BR +Where there are large document sets, it provides consistency in appearance in +each output format for the documents. + +.BR +The excuse for going this way is, it is a waste of time to think much about +appearance when working on substantive content, it is the substantive content +that is relevant, not the way it looks beyond the basic informational tags \- +and yet you want to be able to take advantage of as many useful different ways +of representing documents as are available, and for various types of output to +to be/look as good as it can for each medium/format in which it is presented, +(with different mediums having different focuses) and +.B SiSU +tries to achieve this from minimal markup. + +.SH +1.7 HOW DO I CREATE GIN OR GIST INDEX IN POSTGRESQL FOR USE IN SISU + +.BR +This at present needs to be done \"manually\" and it is probably necessary to +alter the sample search form. The following is a helpful response from one of +the contributors of GiN to Postgresql Oleg Bartunov 2006\-12\-06: + +.BR +\"I have tsearch2 slides which introduces tsearch2 +<http://www.sai.msu.su/~megera/wiki/tsearch2slides> + +.BR +FTS in PostgreSQL is provided by tsearch2, which should works without any +indices (GiST or GIN) ! Indices provide performance, not functionality. + +.BR +In your example I\'d do ( simple way, just for demo): + +.BR +.B 0. +compile, install tsearch2 and load tsearch2 into your database + +.BR + cd contrib/tsearch2; make&&make&&install&&make installcheck; psql DB < + tsearch2.sql + +.BR +.B 1. +Add column fts, which holds tsvector + +.BR + alter table documents add column fts tsvector; + +.BR +.B 2. +Fill fts column + +.BR + update document set fts = to_tsvector(clean); + +.BR +.B 3. +create index \- just for performance ! + +.BR + create index fts_gin_idx on document using gin(fts); + +.BR +.B 4. +Run vacuum + +.BR + vacuum analyze document; + +.BR +That\'s all. + +.BR +Now you can search: + +.BR +select lid, metadata_tid, rank_cd(fts, q,2)as rank from document, +plainto_tsquery(\'markup syntax\') q where q @@ fts order by rank desc limit +10; + +.SH +1.8 WHERE IS VERSION 1.0? + +.BR +.B SiSU +works pretty well as it is supposed to. Version 1.0 will have the current +markup, and directory structure. At this point it is largely a matter of choice +as to when the name change is made. + +.BR +The feature set for html,[^1] LaTeX/pdf and opendocument is in place. XML, and +plaintext are in order. + +.BR +html and LaTeX/pdf may be regarded as reference copy outputs + +.BR +With regard to the populating of sql databases (postgresql and sqlite), there +is a bit to be done. + +.BR +We are still almost there. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_faq/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 \- FAQ \- Frequently Asked/Answered Questions + +.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 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_faq.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_faq.sst)= +.I 4ba78b1270b9d994054c1ff06d58765d + +.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. +html w3c compliance has been largely met. + +.TP +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_faq/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_faq/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_faq/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_faq/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_faq/sisu_faq.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:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu 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 diff --git a/man/man8/sisu_quickstart.8 b/man/man8/sisu_quickstart.8 new file mode 100644 index 00000000..e13f84e4 --- /dev/null +++ b/man/man8/sisu_quickstart.8 @@ -0,0 +1,517 @@ +.TH "sisu_quickstart" "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 \- QUICKSTART, INSTALLATION AND USE, +RALPH AMISSAH +.BR + +.SH +QUICKSTART \- SISU INSTALLATION AND USE +.BR + +.SH +1. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +1.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +1.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/etc/apt/sources.list + deb http://ftp.fi.debian.org/debian/ unstable main non\-free contrib + deb\-src http://ftp.fi.debian.org/debian/ unstable main non\-free contrib + d +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +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 + + +.nf + #/etc/apt/sources.list + deb http://www.jus.uio.no/sisu/archive unstable main non\-free + deb\-src http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +Note however that it is not necessary to install sisu\-complete if not all +components of sisu are to be used. Installing just the package sisu will +provide basic functionality. + +.SH +1.1.2 RPM INSTALLATION + +.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> + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +1.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + <http://www.jus.uio.no/sisu/SiSU/download.html#current> + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +Two alternative modes of installation from source are provided, setup.rb (by +Minero Aoki) and a rant(by Stefan Lang) built install file, in either case: the +first steps are the same, download and unpack the source file: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B SiSU +will be able to generate html, various XMLs, including ODF (and will also +produce LaTeX). Dependencies required for further actions, though it relies on +the installation of additional dependencies which the source tarball does not +take care of, for things like using a database (postgresql or sqlite)[^1] or +converting LaTeX to pdf. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + <http://i.loveruby.net/en/projects/setup/> + +.BR + <http://i.loveruby.net/en/projects/setup/doc/usage.html> + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby 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 on \"rant\" is available from: + +.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 install help + +.BR + ruby install \-T + +.SH +1.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +1.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +1.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +should generate most available output formats: html including a concordance +file, opendocument text format, plaintext, XHTML and various forms of XML, and +OpenDocument text and pdf + +.SH +1.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +1.3 GETTING HELP + +.SH +1.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1> \ [^2] + +.BR +* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8> \ [^3] + +.BR +* man directory <http://www.jus.uio.no/sisu/man> \ [^4] + +.SH +1.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +1.3.3 THE HOME PAGE + +.BR +<http://www.jus.uio.no/sisu> + +.BR +<http://www.jus.uio.no/sisu/SiSU> + +.SH +1.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR +<http://www.jus.uio.no/sisu/SiSU/2.html> + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^5] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_quickstart/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 \- Quickstart, installation and use + +.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 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_quickstart.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_quickstart.sst)= +.I 05a047fd659fbbeaa3cdb982b5911bcd + +.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:00 +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. +There is nothing to stop MySQL support being added in future. +.TP +.BI 2. +<http://www.jus.uio.no/sisu/man/sisu.1> +.TP +.BI 3. +<http://www.jus.uio.no/sisu/man/sisu.8> +.TP +.BI 4. +<http://www.jus.uio.no/sisu/man> +.TP +.BI 5. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. + +.TP +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_quickstart/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_quickstart/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_quickstart/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_quickstart/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_quickstart/sisu_quickstart.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 diff --git a/man/man8/sisu_remote.8 b/man/man8/sisu_remote.8 new file mode 100644 index 00000000..9da648f2 --- /dev/null +++ b/man/man8/sisu_remote.8 @@ -0,0 +1,251 @@ +.TH "sisu_remote" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- REMOTE OPERATIONS \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU REMOTE OPERATIONS +.BR + +.SH +1. REMOTE SOURCE DOCUMENTS +.BR + +.BR +.B SiSU +processing instructions can be run against remote source documents by +providing the url of the documents against which the processing instructions +are to be carried out. The remote +.B SiSU +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp + +.BR +.B .sst / .ssm \- sisu text files + +.BR +.B SiSU +can be run against source text files on a remote machine, provide the +processing instruction and the url. The source file and any associated parts +(such as images) will be downloaded and generated locally. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ .sst \ or \ .ssm \ file] +.fi + +.BR +Any of the source documents in the sisu examples page can be used in this way, +see <http://www.jus.uio.no/sisu/SiSU/2.html> and use the url for the desired +document. + +.BR +NOTE: to set up a remote machine to serve +.B SiSU +documents in this way, images should be in the directory relative to the +document source ../_sisu/image + +.BR +.B sisupod \- zipped sisu files + +.BR +A sisupod is the zipped content of a sisu marked up text or texts and any other +associated parts to the document such as images. + +.BR +.B SiSU +can be run against a sisupod on a (local or) remote machine, provide the +processing instruction and the url, the sisupod will be downloaded and the +documents it contains generated locally. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ sisupod.zip \ or \ .ssp \ file] +.fi + +.BR +Any of the source documents in the sisu examples page can be used in this way, +see <http://www.jus.uio.no/sisu/SiSU/2.html> and use the url for the desired +document. + +.SH +REMOTE DOCUMENT OUTPUT +.BR + +.SH +2. REMOTE OUTPUT +.BR + +.BR +Once properly configured +.B SiSU +output can be automatically posted once generated to a designated remote +machine using either rsync, or scp. + +.BR +In order to do this some ssh authentication agent and keychain or similar tool +will need to be configured. Once that is done the placement on a remote host +can be done seamlessly with the \-r (for scp) or \-R (for rsync) flag, which +may be used in conjunction with other processing flags, e.g. + + +.nf + sisu \-3R sisu_remote.sst +.fi + +.SH +2.1 COMMANDS + +.TP +.B \ \-R \ \ [filename/wildcard] +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Note the behavior of rsync +different if \-R is used with other flags from if used alone. Alone the rsync +\-\-delete parameter is sent, useful for cleaning the remote directory (when +\-R is used together with other flags, it is not). Also see \-r + +.TP +.B \ \-r \ \ [filename/wildcard] +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your \"keys\" and ssh agent in place. Also see \-R + +.SH +2.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +3. REMOTE SERVERS +.BR + +.BR +As +.B SiSU +is generally operated using the command line, and works within a Unix type +environment, +.B SiSU +the program and all documents can just as easily be on a remote server, to +which you are logged on using a terminal, and commands and operations would be +pretty much the same as they would be on your local machine. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_remote/sisu_manifest.html> + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Remote Operations \ [0.58] + +.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\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_remote.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_remote.sst)= +.I 5fe0c81eddcd7e3e18608b8e48b3ccad + +.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:02 +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 +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_remote/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_remote/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_remote/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_remote/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_remote/sisu_remote.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:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/man/man8/sisu_search.8 b/man/man8/sisu_search.8 new file mode 100644 index 00000000..039f6e7c --- /dev/null +++ b/man/man8/sisu_search.8 @@ -0,0 +1,639 @@ +.TH "sisu_search" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +1. SISU SEARCH \- INTRODUCTION +.BR + +.BR +.B SiSU +output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + +.BR +Because the document structure of sites created is clearly defined, and the +text object citation system is available hypothetically at least, for all forms +of output, it is possible to search the sql database, and either read results +from that database, or just as simply map the results to the html output, which +has richer text markup. + +.BR +In addition to this +.B SiSU +has the ability to populate a relational sql type database with documents at +an object level, with objects numbers that are shared across different output +types, which make them searchable with that degree of granularity. Basically, +your match criteria is met by these documents and at these locations within +each document, which can be viewed within the database directly or in various +output formats. + +.SH +2. SQL +.BR + +.SH +2.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^1] and/or +SQLite[^2] database together with information related to document structure. + +.BR +This is one of the more interesting output forms, as all the structural data of +the documents are retained (though can be ignored by the user of the database +should they so choose). All site texts/documents are (currently) streamed to +four tables: + +.BR + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + +.BR + * another the substantive texts by individual \"paragraph\" (or object) \- + along with structural information, each paragraph being identifiable by its + paragraph number (if it has one which almost all of them do), and the + substantive text of each paragraph quite naturally being searchable (both in + formatted and clean text versions for searching); and + +.BR + * a third containing endnotes cross\-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + +.BR + * a fourth table with a one to one relation with the headers table contains + full text versions of output, eg. pdf, html, xml, and ascii. + +.BR +There is of course the possibility to add further structures. + +.BR +At this level +.B SiSU +loads a relational database with documents chunked into objects, their +smallest logical structurally constituent parts, as text objects, with their +object citation number and all other structural information needed to construct +the document. Text is stored (at this text object level) with and without +elementary markup tagging, the stripped version being so as to facilitate ease +of searching. + +.BR +Being able to search a relational database at an object level with the +.B SiSU +citation system is an effective way of locating content generated by +.B SiSU +. As individual text objects of a document stored (and indexed) together with +object numbers, and all versions of the document have the same numbering, +complex searches can be tailored to return just the locations of the search +results relevant for all available output formats, with live links to the +precise locations in the database or in html/xml documents; or, the structural +information provided makes it possible to search the full contents of the +database and have headings in which search content appears, or to search only +headings etc. (as the Dublin Core is incorporated it is easy to make use of +that as well). + +.SH +3. POSTGRESQL +.BR + +.SH +3.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +3.2 DESCRIPTION + +.BR +Information related to using postgresql with sisu (and related to the +sisu_postgresql dependency package, which is a dummy package to install +dependencies needed for +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +3.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +3.4 COMMANDS + +.BR +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql, +alternatively \-\-sqlite or \-\-pgsql may be used + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +3.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-pgsql \ \-\-createall +\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in +\ existing \ (postgresql) \ database \ (a \ database \ should \ be \ created \ +manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \ +requested) \ (rb.dbi) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ sisu \ \-D \ \-\-Dropall +\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \ +and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \ +given \ directory \ (and \ directories \ of \ the \ same \ name). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +3.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ sisu \ \-D \ \-\-import \ \-v \ \ [filename/wildcard] +populates database with the contents of the file. Imports documents(s) +specified to a postgresql database (at an object level). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +4. SQLITE +.BR + +.SH +4.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +4.2 DESCRIPTION + +.BR +Information related to using sqlite with sisu (and related to the sisu_sqlite +dependency package, which is a dummy package to install dependencies needed for +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +4.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +4.4 COMMANDS + +.BR +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +\-d (lowercase) denotes sqlite and \-D (uppercase) denotes postgresql, +alternatively \-\-sqlite or \-\-pgsql may be used + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +4.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-sqlite \ \-\-createall +\ initial \ step, \ creates \ required \ relations \ (tables, \ indexes) \ in +\ existing \ (sqlite) \ database \ (a \ database \ should \ be \ created \ +manually \ and \ given \ the \ same \ name \ as \ working \ directory, \ as \ +requested) \ (rb.dbi) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ sisu \ \-d \ \-\-dropall +\ destroys \ database \ (including \ all \ its \ content)! \ kills \ data \ +and \ drops \ tables, \ indexes \ and \ database \ associated \ with \ a \ +given \ directory \ (and \ directories \ of \ the \ same \ name). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +4.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ sisu \ \-d \ \-\-import \ \-v \ \ [filename/wildcard] +populates database with the contents of the file. Imports documents(s) +specified to an sqlite database (at an object level). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +5. INTRODUCTION +.BR + +.SH +5.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend <http://search.sisudoc.org> \ [^3] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^4] + +.BR +.B SiSU +can provide information on which documents are matched and at what locations +within each document the matches are found. These results are relevant across +all outputs using object citation numbering, which includes html, XML, LaTeX, +PDF and indeed the SQL database. You can then refer to one of the other outputs +or in the SQL database expand the text within the matched objects (paragraphs) +in the documents matched. + +.BR +Note you may set results either for documents matched and object number +locations within each matched document meeting the search criteria; or display +the names of the documents matched along with the objects (paragraphs) that +meet the search criteria.[^5] + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created +\ + +.BR +The following is feedback on the setup on a machine provided by the help +command: + +.BR + sisu \-\-help sql + + +.nf + Postgresql + user: ralph + current db set: SiSU_sisu + port: 5432 + dbi connect: DBI:Pg:database=SiSU_sisu;port=5432 + sqlite + current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db + dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db +.fi + +.BR +Note on databases built + +.BR +By default, \ [unless \ otherwise \ specified] databases are built on a +directory basis, from collections of documents within that directory. The name +of the directory you choose to work from is used as the database name, i.e. if +you are working in a directory called /home/ralph/ebook the database SiSU_ebook +is used. \ [otherwise \ a \ manual \ mapping \ for \ the \ collection \ is \ +necessary] + +.SH +5.2 SEARCH FORM + +.TP +.B \ sisu \ \-F +\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \ +the \ web\-server \ cgi \ directory \ + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ generates \ a \ sample \ search \ form \ for \ use \ with \ the \ webrick \ +server, \ which \ must \ be \ copied \ to \ the \ web\-server \ cgi \ directory +\ + +.TP +.B \ sisu \ \-Fv +\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \ +hyperestraier \ + +.TP +.B \ sisu \ \-W +\ starts \ the \ webrick \ server \ which \ should \ be \ available \ +wherever \ sisu \ is \ properly \ installed \ + +.BR +The generated search form must be copied manually to the webserver directory as +instructed + +.SH +6. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + <http://hyperestraier.sourceforge.net/> + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.BR +on sisu_hyperestraier: + +.BR + man sisu_hyperestraier + +.BR + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + +.BR +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + +.BR +(A) to generate the index within the webserver directory to be indexed: + +.BR + estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index] + +.BR +the following are examples that will need to be tailored according to your +needs: + +.BR + cd /home/ralph/sisu_www + +.BR + estcmd gather \-sd casket /home/ralph/sisu_www + +.BR +you may use the \'find\' command together with \'egrep\' to limit indexing to +particular document collection directories within the web server directory: + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \- + +.BR +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + +.BR +As sisu duplicates output in multiple file formats, it it is probably +preferable to limit the estraier index to html output, and as it may also be +desirable to exclude files \'plain.txt\', \'toc.html\' and +\'concordance.html\', as these duplicate information held in other html output +e.g. + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v + \'(doc|concordance).html$\' |estcmd gather \-sd casket \- + +.BR +from your current document preparation/markup directory, you would construct a +rune along the following lines: + +.BR + find /home/ralph/sisu_www \-type f | egrep \'/home/ralph/sisu_www/([specify \ + first \ directory \ for \ inclusion]|[specify \ second \ directory \ for \ + inclusion]|[another \ directory \ for \ inclusion? \ ...])/.+?.html$\' | + egrep \-v \'(doc|concordance).html$\' |estcmd gather \-sd + /home/ralph/sisu_www/casket \- + +.BR +(B) to set up the search form + +.BR +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + +.BR + sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin + +.BR + sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi + +.BR + sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin + +.BR + \ [see \ estraier \ documentation \ for \ paths] + +.BR +(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and +\'replace:\': + +.BR + indexname: /home/ralph/sisu_www/casket + +.BR + replace: ^file:///home/ralph/sisu_www{{!}}http://localhost + +.BR + replace: /index.html?${{!}}/ + +.BR +(C) to test using webrick, start webrick: + +.BR + sisu \-W + +.BR +and try open the url: <http://localhost:8081/cgi\-bin/estseek.cgi> + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_search/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 \- Search \ [0.58] + +.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\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_search._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_search._sst)= +.I 52c1d6d3c3082e6b236c65debc733a05 + +.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:04 +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. +<http://www.postgresql.org/> + <http://advocacy.postgresql.org/> + <http://en.wikipedia.org/wiki/Postgresql> +.TP +.BI 2. +<http://www.hwaci.com/sw/sqlite/> + <http://en.wikipedia.org/wiki/Sqlite> +.TP +.BI 3. +<http://search.sisudoc.org> +.TP +.BI 4. +(which could be extended further with current back-end). As regards scaling +of the database, it is as scalable as the database (here Postgresql) and +hardware allow. +.TP +.BI 5. +of this feature when demonstrated to an IBM software innovations evaluator in +2004 he said to paraphrase: this could be of interest to us. We have large +document management systems, you can search hundreds of thousands of documents +and we can tell you which documents meet your search criteria, but there is no +way we can tell you without opening each document where within each your +matches are found. + +.TP +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_search/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_search/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_search/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_search/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_search/sisu_search.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:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/man/man8/sisu_syntax_highlighting.8 b/man/man8/sisu_syntax_highlighting.8 new file mode 100644 index 00000000..b2f85d85 --- /dev/null +++ b/man/man8/sisu_syntax_highlighting.8 @@ -0,0 +1,307 @@ +.TH "sisu_syntax_highlighting" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- SYNTAX HIGHLIGHTING \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SYNTAX HIGHLIGHTING +.BR + +.SH +1. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + ./data/sisu/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/conf/editor\-syntax\-etc + +.BR +contains rudimentary sisu syntax highlighting files for: + +.BR +* (g)vim <http://www.vim.org> + +.BR + package: sisu\-vim + +.BR +status: largely done + +.BR + there is a vim syntax highlighting and folds component + +.BR +* gedit <http://www.gnome.org/projects/gedit> + +.BR +* gobby <http://gobby.0x539.de/> + +.BR + file: sisu.lang + +.BR +place in: + +.BR + /usr/share/gtksourceview\-1.0/language\-specs + +.BR +or + +.BR + ~/.gnome2/gtksourceview\-1.0/language\-specs + +.BR + status: very basic syntax highlighting + +.BR + comments: this editor features display line wrap and is used by Goby! + +.BR +* nano <http://www.nano\-editor.org> + +.BR + file: nanorc + +.BR +save as: + +.BR + ~/.nanorc + +.BR + status: basic syntax highlighting + +.BR + comments: assumes dark background; no display line\-wrap; does line breaks + +.BR +* diakonos (an editor written in ruby) <http://purepistos.net/diakonos> + +.BR +file: diakonos.conf + +.BR +save as: + +.BR + ~/.diakonos/diakonos.conf + +.BR +includes: + +.BR + status: basic syntax highlighting + +.BR +comments: assumes dark background; no display line\-wrap + +.BR +* kate & kwrite <http://kate.kde.org> + +.BR + file: sisu.xml + +.BR + place in: + +.BR + /usr/share/apps/katepart/syntax + +.BR + or + +.BR + ~/.kde/share/apps/katepart/syntax + +.BR + \ [settings::configure \ kate::{highlighting,filetypes}] + +.BR + \ [tools::highlighting::{markup,scripts}:: +.B \ SiSU +] + +.BR +* nedit <http://www.nedit.org> + +.BR + file: sisu_nedit.pats + +.BR + nedit \-import sisu_nedit.pats + +.BR + status: a very clumsy first attempt \ [not \ really \ done] + +.BR + comments: this editor features display line wrap + +.BR +* emacs <http://www.gnu.org/software/emacs/emacs.html> + +.BR + files: sisu\-mode.el + +.BR + to file ~/.emacs add the following 2 lines: + +.BR + (add\-to\-list \'load\-path \"/usr/share/sisu\-examples/config/syntax_hi\") + +.BR + (require \'sisu\-mode.el) + +.BR + \ [not \ done \ / \ not \ yet \ included] + +.BR +* vim & gvim <http://www.vim.org> + +.BR + files: + +.BR + package is the most comprehensive sisu syntax highlighting and editor + environment provided to date (is for vim/ gvim, and is separate from the + contents of this directory) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ SiSU +\ parses \ files \ with \ long \ lines \ or \ line \ breaks, \ but, \ display +\ linewrap \ (without \ line\-breaks) \ is \ a \ convenient \ editor \ feature +\ to \ have \ for \ sisu \ markup] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ +<http://www.jus.uio.no/sisu/sisu_manual/sisu_syntax_highlighting/sisu_manifest.html> + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Syntax Highlighting \ [0.58] + +.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_syntax_highlighting.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_syntax_highlighting.sst)= +.I 1dfe1975df71459c3f56c3fd13c5789c + +.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:02 +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 +Other versions of this document: +.TP +manifest: <http://www.jus.uio.no/sisu/sisu_syntax_highlighting/sisu_manifest.html> +.TP +html: <http://www.jus.uio.no/sisu/sisu_syntax_highlighting/toc.html> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_syntax_highlighting/portrait.pdf> +.TP +pdf: <http://www.jus.uio.no/sisu/sisu_syntax_highlighting/landscape.pdf> +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_syntax_highlighting/sisu_syntax_highlighting.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:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu |