"sisu_faq"("1") manual page

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 --- data/doc/sisu/html/sisu_faq.8.html | 275 +++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 data/doc/sisu/html/sisu_faq.8.html (limited to 'data/doc/sisu/html/sisu_faq.8.html') diff --git a/data/doc/sisu/html/sisu_faq.8.html b/data/doc/sisu/html/sisu_faq.8.html new file mode 100644 index 00000000..d480b195 --- /dev/null +++ b/data/doc/sisu/html/sisu_faq.8.html @@ -0,0 +1,275 @@ + + + + + +"sisu_faq"("1") manual page + + +Table of Contents

+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 +

SiSU currently +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 Structured +information, Serialized Units" I am satisfied that I can convert (both + ways) between 3 Structured information, Serialized Units" 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 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 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 <http://www.sai.msu.su/~megera/wiki/tsearch2slides +> + +

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. +

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 @ <http://www.jus.uio.no/sisu/sisu_manual/sisu_faq/sisu_manifest.html +> + +

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 01:14:01 +0100 2007 +

Generated by: SiSU 0.58.3 of +2007w36/4 (2007-09-06) +

Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) + [i486-linux] +

html w3c compliance has been largely met. +
+ +
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 + +> +
+
+ +
pdf: <http://www.jus.uio.no/sisu/sisu_faq/landscape.pdf + +>
+

+ +
at: <http://www.jus.uio.no/sisu + +> +
+
+ +
* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06)
+
+ +
* Ruby version: ruby +1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
+
+ +
* Last Generated on: Sun Sep 23 +01:14:07 +0100 2007
+
+ +
* SiSU http://www.jus.uio.no/sisu +
+
+ +
+ + -- cgit v1.2.3