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

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