diff options
Diffstat (limited to 'man/man8/sisu_faq.8')
| -rw-r--r-- | man/man8/sisu_faq.8 | 404 |
1 files changed, 404 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 |