aboutsummaryrefslogtreecommitdiffhomepage
path: root/man/man8/sisu_faq.8
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2007-09-23 05:16:21 +0100
committerRalph Amissah <ralph@amissah.com>2007-09-23 05:16:21 +0100
commit50d45c6deb0afd2e4222d2e33a45487a9d1fa676 (patch)
tree100c62d678f009139999bf77c26c81653a721eeb /man/man8/sisu_faq.8
parentsisu-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/sisu_faq.8')
-rw-r--r--man/man8/sisu_faq.8404
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 &lt;
+ 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