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/scroll.xhtml | 547 +++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_faq/scroll.xhtml (limited to 'data/doc/manuals_generated/sisu_manual/sisu_faq/scroll.xhtml') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_faq/scroll.xhtml b/data/doc/manuals_generated/sisu_manual/sisu_faq/scroll.xhtml new file mode 100644 index 00000000..2612ae21 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_faq/scroll.xhtml @@ -0,0 +1,547 @@ + + + + + + + + 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 + +
+ + + + + SiSU - SiSU information Structuring Universe / Structured information, +Serialized Units - FAQ - Frequently Asked/Answered Questions,
+Ralph Amissah + + 1 + + + + 1. FAQ - Frequently Asked/Answered Questions + + 2 + + + + 1.1 Why are urls produced with the -v (and -u) flag that point to a web +server on port 8081? + + 3 + + + + Try the following rune: + + 4 + + + + sisu -W + + 5 + + + + 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. + + 6 + + + + 1.2 I cannot find my output, where is it? + + 7 + + + + The following should provide help on output paths: + + 8 + + + + sisu --help env + + 9 + + + + sisu -V [same as the previous command] + + 10 + + + + sisu --help directory + + 11 + + + + sisu --help path + + 12 + + + + sisu -U [filename] + + 13 + + + + man sisu + + 14 + + + + 1.3 I do not get any pdf output, why? + + 15 + + + + SiSU produces LaTeX and pdflatex is run against that to generate +pdf files. + + 16 + + + + If you use Debian the following will install the required +dependencies + + 17 + + + + aptitude install sisu-pdf + + 18 + + + + the following packages are required: tetex-bin, tetex-extra, latex-ucs + + 19 + + + + 1.4 Where is the latex (or some other interim) output? + + 20 + + + + Try adding -M (for maintenance) to your command flags, e.g.: + + 21 + + + + sisu -HpMv [filename] + + 22 + + + + this should result in the interim processing output being retained, and +information being provided on where to find it. + + 23 + + + + sisu --help directory + + 24 + + + + sisu --help path + + 25 + + + + should also provide some relevant information as to where it is placed. + + 26 + + + + 1.5 Why isn't SiSU markup XML + + 27 + + + + I worked with text and (though I find XML immensely valuable) disliked +noise ... better to sidestep the question and say: + + 28 + + + + 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 + + 29 + + + + sisu --to-sax [filename/wildcard] + + 30 + + + + sisu --to-dom [filename/wildcard] + + 31 + + + + sisu --to-node [filename/wildcard] + + 32 + + + + 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]. + + 33 + + + + sisu --from-xml2sst [filename/wildcard] + + 34 + + + + 1.6 LaTeX claims to be a document preparation system for high-quality +typesetting. Can the same be said about SiSU? + + 35 + + + + SiSU is not really about type-setting. + + 36 + + + + LaTeX is the ultimate computer instruction type-setting language for +paper based publication. + + 37 + + + + 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. + + 38 + + + + 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. + + 39 + + + + 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. + + 40 + + + + 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. + + 41 + + + + Where there are large document sets, it provides consistency in +appearance in each output format for the documents. + + 42 + + + + 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. + + 43 + + + + 1.7 How do I create GIN or GiST index in Postgresql for use in SiSU + + 44 + + + + 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: + + 45 + + + + "I have tsearch2 slides which introduces tsearch2 <http://www.sai.msu.su/~megera/wiki/tsearch2slides> + + 46 + + + + FTS in PostgreSQL is provided by tsearch2, which should works without +any indices (GiST or GIN) ! Indices provide performance, not +functionality. + + 47 + + + + In your example I'd do ( simple way, just for demo): + + 48 + + + + 0. compile, install tsearch2 and load tsearch2 into your +database + + 49 + + + + cd contrib/tsearch2; +make&&make&&install&&make installcheck; psql DB +< tsearch2.sql + + 50 + + + + 1. Add column fts, which holds tsvector + + 51 + + + + alter table documents add column fts tsvector; + + 52 + + + + 2. Fill fts column + + 53 + + + + update document set fts = to_tsvector(clean); + + 54 + + + + 3. create index - just for performance ! + + 55 + + + + create index fts_gin_idx on document using gin(fts); + + 56 + + + + 4. Run vacuum + + 57 + + + + vacuum analyze document; + + 58 + + + + That's all. + + 59 + + + + Now you can search: + + 60 + + + + 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; + + 61 + + + + 1.8 Where is version 1.0? + + 62 + + + + 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. + + 63 + + + + 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. + + 64 + + + + html and LaTeX/pdf may be regarded as reference copy outputs + + 65 + + + + With regard to the populating of sql databases (postgresql and sqlite), +there is a bit to be done. + + 66 + + + + We are still almost there. + + 67 + + + + Endnotes + + 0 + + + -- cgit v1.2.3