From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: 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 --- .../sisu_manual/sisu_faq/plain.txt | 385 +++++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_faq/plain.txt (limited to 'data/doc/manuals_generated/sisu_manual/sisu_faq/plain.txt') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_faq/plain.txt b/data/doc/manuals_generated/sisu_manual/sisu_faq/plain.txt new file mode 100644 index 00000000..67a4d774 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_faq/plain.txt @@ -0,0 +1,385 @@ +SISU - SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS - FAQ - FREQUENTLY ASKED/ANSWERED QUESTIONS, +RALPH AMISSAH +****************************************************************************** + +1. FAQ - FREQUENTLY ASKED/ANSWERED QUESTIONS +-------------------------------------------- + +1.1 WHY ARE URLS PRODUCED WITH THE -V (AND -U) FLAG THAT POINT TO A WEB SERVER +ON PORT 8081? +.............................................................................. + +Try the following rune: + + +* sisu -W + + +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. + + +1.2 I CANNOT FIND MY OUTPUT, WHERE IS IT? +......................................... + +The following should provide help on output paths: + + +* sisu --help env + + +* sisu -V [same as the previous command] + + +* sisu --help directory + + +* sisu --help path + + +* sisu -U [filename] + + +* man sisu + + +1.3 I DO NOT GET ANY PDF OUTPUT, WHY? +..................................... + +*SiSU* produces LaTeX and pdflatex is run against that to generate pdf files. + + +If you use *Debian* the following will install the required dependencies + + +* aptitude install sisu-pdf + + +the following packages are required: tetex-bin, tetex-extra, latex-ucs + + +1.4 WHERE IS THE LATEX (OR SOME OTHER INTERIM) OUTPUT? +...................................................... + +Try adding -M (for maintenance) to your command flags, e.g.: + + +* sisu -HpMv [filename] + + +this should result in the interim processing output being retained, and +information being provided on where to find it. + + +* sisu --help directory + + +* sisu --help path + + +should also provide some relevant information as to where it is placed. + + +1.5 WHY ISN'T SISU MARKUP XML +............................. + +I worked with text and (though I find XML immensely valuable) disliked noise +... better to sidestep the question and say: + + +*SiSU* currently "understands" three XML input representations - or more +accurately, converts from three forms of XML to native *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 *SiSU* VERSION CONVERSION + + + sisu --to-sax [filename/wildcard] + + + sisu --to-dom [filename/wildcard] + + + sisu --to-node [filename/wildcard] + + +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 *SiSU* markup]. + + + sisu --from-xml2sst [filename/wildcard] + + +1.6 LATEX CLAIMS TO BE A DOCUMENT PREPARATION SYSTEM FOR HIGH-QUALITY +TYPESETTING. CAN THE SAME BE SAID ABOUT SISU? +.............................................................................. + +*SiSU* is not really about type-setting. + + +LaTeX is the ultimate computer instruction type-setting language for paper +based publication. + + +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. + + +*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. + + +*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 *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. + + +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. + + +Where there are large document sets, it provides consistency in appearance in +each output format for the documents. + + +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 *SiSU* tries to achieve +this from minimal markup. + + +1.7 HOW DO I CREATE GIN OR GIST INDEX IN POSTGRESQL FOR USE IN SISU +................................................................... + +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: + + +"I have tsearch2 slides which introduces tsearch2 + + + +FTS in PostgreSQL is provided by tsearch2, which should works without any +indices (GiST or GIN) ! Indices provide performance, not functionality. + + +In your example I'd do ( simple way, just for demo): + + +*0.* compile, install tsearch2 and load tsearch2 into your database + + + cd contrib/tsearch2; make&&make&&install&&make installcheck; psql DB < + tsearch2.sql + + +*1.* Add column fts, which holds tsvector + + + alter table documents add column fts tsvector; + + +*2.* Fill fts column + + + update document set fts = to_tsvector(clean); + + +*3.* create index - just for performance ! + + + create index fts_gin_idx on document using gin(fts); + + +*4.* Run vacuum + + + vacuum analyze document; + + +That's all. + + +Now you can search: + + +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; + + +1.8 WHERE IS VERSION 1.0? +......................... + +*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. + + +The feature set for html,[^1] LaTeX/pdf and opendocument is in place. XML, and +plaintext are in order. + + +- [1]: html w3c compliance has been largely met. + +html and LaTeX/pdf may be regarded as reference copy outputs + + +With regard to the populating of sql databases (postgresql and sqlite), there +is a bit to be done. + + +We are still almost there. + + +DOCUMENT INFORMATION (METADATA) +******************************* + +METADATA +-------- + +Document Manifest @ + + + +*Dublin Core* (DC) + + +/DC tags included with this document are provided here./ + + +DC Title: _SiSU - SiSU information Structuring Universe / Structured +information, Serialized Units - FAQ - Frequently Asked/Answered Questions_ + + +DC Creator: _Ralph Amissah_ + + +DC Rights: _Copyright (C) Ralph Amissah 2007, part of SiSU documentation, +License GPL 3_ + + +DC Type: _information_ + + +DC Date created: _2006-09-06_ + + +DC Date available: _2006-09-06_ + + +DC Date issued: _2006-09-06_ + + +DC Date modified: _2007-09-16_ + + +DC Date: _2007-09-16_ + + +*Version Information* + + +Sourcefile: _sisu_faq.sst_ + + +Filetype: _SiSU text 0.57_ + + +Sourcefile Digest, MD5(sisu_faq.sst)= _4ba78b1270b9d994054c1ff06d58765d_ + + +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)= +_20fc43cf3eb6590bc3399a1aef65c5a9_ + + +*Generated* + + +Document (metaverse) last generated: _Sun Sep 23 04:11:02 +0100 2007_ + + +Generated by: _SiSU_ _0.59.0_ of 2007w38/0 (2007-09-23) + + +Ruby version: _ ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]_ + + + +============================================================================== + + title: SiSU - SiSU information Structuring Universe / Structured + information, Serialized Units - FAQ - Frequently Asked/Answered + Questions + + creator: Ralph Amissah + + rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, + License GPL 3 + + type: information + + subject: ebook, epublishing, electronic book, electronic publishing, + electronic document, electronic citation, data structure, + citation systems, search + + date.created: 2006-09-06 + + date.available: 2006-09-06 + + date.issued: 2006-09-06 + + date.modified: 2007-09-16 + + date: 2007-09-16 + + + + + +============================================================================== +nil + +Other versions of this document: +manifest: + http://www.jus.uio.no/sisu/sisu_faq/sisu_manifest.html +html: + http://www.jus.uio.no/sisu/sisu_faq/toc.html +pdf: + http://www.jus.uio.no/sisu/sisu_faq/portrait.pdf + http://www.jus.uio.no/sisu/sisu_faq/landscape.pdf +plaintext (plain text): + http://www.jus.uio.no/sisu/sisu_faq/plain.txt +at: + http://www.jus.uio.no/sisu +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +* Last Generated on: Sun Sep 23 04:11:51 +0100 2007 +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3