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_manual/plain.txt | 9580 ++++++++++++++++++++ 1 file changed, 9580 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/sisu_manual/plain.txt (limited to 'data/doc/manuals_generated/sisu_manual/sisu_manual/plain.txt') diff --git a/data/doc/manuals_generated/sisu_manual/sisu_manual/plain.txt b/data/doc/manuals_generated/sisu_manual/sisu_manual/plain.txt new file mode 100644 index 00000000..2bec8e15 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/sisu_manual/plain.txt @@ -0,0 +1,9580 @@ +SISU - SISU INFORMATION STRUCTURING UNIVERSE - MANUAL [0.58], +RALPH AMISSAH +**************************************************************************** + +WHAT IS SISU? +============= + +1. INTRODUCTION - WHAT IS SISU? +------------------------------- + +*SiSU* is a system for document markup, publishing (in multiple open standard +formats) and search + + +*SiSU*[^1] is a[^2] framework for document structuring, publishing and search, +comprising of (a) a lightweight document structure and presentation markup +syntax and (b) an accompanying engine for generating standard document format +outputs from documents prepared in sisu markup syntax, which is able to produce +multiple standard outputs that (can) share a common numbering system for the +citation of text within a document. + + +- [1]: "*SiSU* information Structuring Universe" or "Structured information, + Serialized Units". + +- also chosen for the meaning of the Finnish term "sisu". + +- [2]: Unix command line oriented + +*SiSU* is developed under an open source, software libre license (GPL3). It has +been developed in the context of coping with large document sets with evolving +markup related technologies, for which you want multiple output formats, a +common mechanism for cross-output-format citation, and search. + + +*SiSU* both defines a markup syntax and provides an engine that produces open +standards format outputs from documents prepared with *SiSU* markup. From a +single lightly prepared document sisu custom builds several standard output +formats which share a common (text object) numbering system for citation of +content within a document (that also has implications for search). The sisu +engine works with an abstraction of the document's structure and content from +which it is possible to generate different forms of representation of the +document. Significantly *SiSU* markup is more sparse than html and outputs +which include html, LaTeX, landscape and portrait pdfs, Open Document Format +(ODF), all of which can be added to and updated. *SiSU* is also able to +populate SQL type databases at an object level, which means that searches can +be made with that degree of granularity. Results of objects (primarily +paragraphs and headings) can be viewed directly in the database, or just the +object numbers shown - your search criteria is met in these documents and at +these locations within each document. + + +Source document preparation and output generation is a two step process: (i) +document source is prepared, that is, marked up in sisu markup syntax and (ii) +the desired output subsequently generated by running the sisu engine against +document source. Output representations if updated (in the sisu engine) can be +generated by re-running the engine against the prepared source. Using *SiSU* +markup applied to a document, *SiSU* custom builds various standard open output +formats including plain text, HTML, XHTML, XML, OpenDocument, LaTeX or PDF +files, and populate an SQL database with objects[^3] (equating generally to +paragraph-sized chunks) so searches may be performed and matches returned with +that degree of granularity ( e.g. your search criteria is met by these +documents and at these locations within each document). Document output formats +share a common object numbering system for locating content. This is +particularly suitable for "published" works (finalized texts as opposed to +works that are frequently changed or updated) for which it provides a fixed +means of reference of content. + + +- [3]: objects include: headings, paragraphs, verse, tables, images, but not + footnotes/endnotes which are numbered separately and tied to the object from + which they are referenced. + +In preparing a *SiSU* document you optionally provide semantic information +related to the document in a document header, and in marking up the substantive +text provide information on the structure of the document, primarily indicating +heading levels and footnotes. You also provide information on basic text +attributes where used. The rest is automatic, sisu from this information custom +builds[^4] the different forms of output requested. + + +- [4]: i.e. the html, pdf, odf outputs are each built individually and optimised + for that form of presentation, rather than for example the html being a saved + version of the odf, or the pdf being a saved version of the html. + +*SiSU* works with an abstraction of the document based on its structure which +is comprised of its frame[^5] and the objects[^6] it contains, which enables +*SiSU* to represent the document in many different ways, and to take advantage +of the strengths of different ways of presenting documents. The objects are +numbered, and these numbers can be used to provide a common base for citing +material within a document across the different output format types. This is +significant as page numbers are not suited to the digital age, in web +publishing, changing a browser's default font or using a different browser +means that text appears on different pages; and in publishing in different +formats, html, landscape and portrait pdf etc. again page numbers are of no use +to cite text in a manner that is relevant against the different output types. +Dealing with documents at an object level together with object numbering also +has implications for search. + + +- [5]: the different heading levels + +- [6]: units of text, primarily paragraphs and headings, also any tables, poems, + code-blocks + +One of the challenges of maintaining documents is to keep them in a format that +would allow users to use them without depending on a proprietary software +popular at the time. Consider the ease of dealing with legacy proprietary +formats today and what guarantee you have that old proprietary formats will +remain (or can be read without proprietary software/equipment) in 15 years +time, or the way the way in which html has evolved over its relatively short +span of existence. *SiSU* provides the flexibility of outputing documents in +multiple non-proprietary open formats including html, pdf[^7] and the ISO +standard ODF.[^8] Whilst *SiSU* relies on software, the markup is uncomplicated +and minimalistic which guarantees that future engines can be written to run +against it. It is also easily converted to other formats, which means documents +prepared in *SiSU* can be migrated to other document formats. Further security +is provided by the fact that the software itself, *SiSU* is available under +GPL3 a licence that guarantees that the source code will always be open, and +free as in libre which means that that code base can be used updated and +further developed as required under the terms of its license. Another challenge +is to keep up with a moving target. *SiSU* permits new forms of output to be +added as they become important, (Open Document Format text was added in 2006), +and existing output to be updated (html has evolved and the related module has +been updated repeatedly over the years, presumably when the World Wide Web +Consortium (w3c) finalises html 5 which is currently under development, the +html module will again be updated allowing all existing documents to be +regenerated as html 5). + + +- [7]: Specification submitted by Adobe to ISO to become a full open ISO + specification + +- + +- [8]: ISO/IEC 26300:2006 + +The document formats are written to the file-system and available for indexing +by independent indexing tools, whether off the web like Google and Yahoo or on +the site like Lucene and Hyperestraier. + + +*SiSU* also provides other features such as concordance files and document +content certificates, and the working against an abstraction of document +structure has further possibilities for the research and development of other +document representations, the availability of objects is useful for example for +topic maps and the commercial law thesaurus by Vikki Rogers and Al Krtizer, +together with the flexibility of *SiSU* offers great possibilities. + + +*SiSU* is primarily for published works, which can take advantage of the +citation system to reliably reference its documents. *SiSU* works well in a +complementary manner with such collaborative technologies as Wikis, which can +take advantage of and be used to discuss the substance of content prepared in +*SiSU*. + + + + + +2. HOW DOES SISU WORK? +---------------------- + +*SiSU* markup is fairly minimalistic, it consists of: a (largely optional) +document header, made up of information about the document (such as when it was +published, who authored it, and granting what rights) and any processing +instructions; and markup within the substantive text of the document, which is +related to document structure and typeface. *SiSU* must be able to discern the +structure of a document, (text headings and their levels in relation to each +other), either from information provided in the document header or from markup +within the text (or from a combination of both). Processing is done against an +abstraction of the document comprising of information on the document's +structure and its objects,[2] which the program serializes (providing the +object numbers) and which are assigned hash sum values based on their content. +This abstraction of information about document structure, objects, (and hash +sums), provides considerable flexibility in representing documents different +ways and for different purposes (e.g. search, document layout, publishing, +content certification, concordance etc.), and makes it possible to take +advantage of some of the strengths of established ways of representing +documents, (or indeed to create new ones). + + +3. SUMMARY OF FEATURES +---------------------- + +* sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a +single UTF-8 file using a minimalistic mnemonic syntax. Typical literature, +documents like "War and Peace" require almost no markup, and most of the +headers are optional. + + +* markup is easily readable/parsable by the human eye, (basic markup is simpler +and more sparse than the most basic HTML), [this may also be converted to XML +representations of the same input/source document]. + + +* markup defines document structure (this may be done once in a header +pattern-match description, or for heading levels individually); basic text +attributes (bold, italics, underscore, strike-through etc.) as required; and +semantic information related to the document (header information, extended +beyond the Dublin core and easily further extended as required); the headers +may also contain processing instructions. *SiSU* markup is primarily an +abstraction of document structure and document metadata to permit taking +advantage of the basic strengths of existing alternative practical standard +ways of representing documents [be that browser viewing, paper publication, sql +search etc.] (html, xml, odf, latex, pdf, sql) + + +* for output produces reasonably elegant output of established industry and +institutionally accepted open standard formats.[3] takes advantage of the +different strengths of various standard formats for representing documents, +amongst the output formats currently supported are: + + + * html - both as a single scrollable text and a segmented document + + + * xhtml + + + * XML - both in sax and dom style xml structures for further development as + required + + + * ODF - open document format, the iso standard for document storage + + + * LaTeX - used to generate pdf + + + * pdf (via LaTeX) + + + * sql - population of an sql database, (at the same object level that is used + to cite text within a document) + + +Also produces: concordance files; document content certificates (md5 or sha256 +digests of headings, paragraphs, images etc.) and html manifests (and sitemaps +of content). (b) takes advantage of the strengths implicit in these very +different output types, (e.g. PDFs produced using typesetting of LaTeX, +databases populated with documents at an individual object/paragraph level, +making possible granular search (and related possibilities)) + + +* ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important to +academics generally and to lawyers) as page numbers are meaningless across +browsers and formats. sisu seeks to provide a common way of pinpoint the text +within a document, (which can be utilized for citation and by search engines). +The outputs share a common numbering system that is meaningful (to man and +machine) across all digital outputs whether paper, screen, or database +oriented, (pdf, HTML, xml, sqlite, postgresql), this numbering system can be +used to reference content. + + +* Granular search within documents. SQL databases are populated at an object +level (roughly headings, paragraphs, verse, tables) and become searchable with +that degree of granularity, the output information provides the +object/paragraph numbers which are relevant across all generated outputs; it is +also possible to look at just the matching paragraphs of the documents in the +database; [output indexing also work well with search indexing tools like +hyperestraier]. + + +* long term maintainability of document collections in a world of changing +formats, having a very sparsely marked-up source document base. there is a +considerable degree of future-proofing, output representations are +"upgradeable", and new document formats may be added. e.g. addition of odf +(open document text) module in 2006 and in future html5 output sometime in +future, without modification of existing prepared texts + + +* SQL search aside, documents are generated as required and static once +generated. + + +* documents produced are static files, and may be batch processed, this needs +to be done only once but may be repeated for various reasons as desired +(updated content, addition of new output formats, updated technology document +presentations/representations) + + +* document source (plaintext utf-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + + +* document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) and +images and sent as a zip file called a sisupod, if shared on the net these too +may be processed locally to produce the desired document outputs + + +* generated document outputs may automatically be posted to remote sites. + + +* for basic document generation, the only software dependency is *Ruby*, and a +few standard Unix tools (this covers plaintext, HTML, XML, ODF, LaTeX). To use +a database you of course need that, and to convert the LaTeX generated to pdf, +a latex processor like tetex or texlive. + + +* as a developers tool it is flexible and extensible + + +Syntax highlighting for *SiSU* markup is available for a number of text +editors. + + +*SiSU* is less about document layout than about finding a way with little +markup to be able to construct an abstract representation of a document that +makes it possible to produce multiple representations of it which may be rather +different from each other and used for different purposes, whether layout and +publishing, or search of content + + +i.e. to be able to take advantage from this minimal preparation starting point +of some of the strengths of rather different established ways of representing +documents for different purposes, whether for search (relational database, or +indexed flat files generated for that purpose whether of complete documents, or +say of files made up of objects), online viewing (e.g. html, xml, pdf), or +paper publication (e.g. pdf)... + + +the solution arrived at is by extracting structural information about the +document (about headings within the document) and by tracking objects (which +are serialized and also given hash values) in the manner described. It makes +possible representations that are quite different from those offered at +present. For example objects could be saved individually and identified by +their hashes, with an index of how the objects relate to each other to form a +document. + + +4. HELP +------- + +4.1 SISU MANUAL +............... + +The most up to date information on sisu should be contained in the sisu_manual, +available at: + + + + + +and (from *SiSU* 0.59 onwards) installed locally at: + + + /usr/share/doc/sisu/sisu_manual/ + + +or equivalent directory + + +Within the *SiSU* tarball at: + + + ./data/doc/sisu/sisu_manual/ + + +4.2 SISU MAN PAGES +.................. + +If *SiSU* is installed on your system usual man commands should be available, +try: + + + man sisu + + + man sisu_markup + + + man sisu_commands + + +Most *SiSU* man pages are generated directly from sisu documents that are used +to prepare the sisu manual, the sources files for which are located within the +*SiSU* tarball at: + + + ./data/doc/sisu/sisu_manual/ + + +Once installed, directory equivalent to: + + + /usr/share/doc/sisu/sisu_manual/ + + +Available man pages are converted back to html using man2html: + + + /usr/share/doc/sisu/html/ + + + ./data/doc/sisu/html/ + + +The *SiSU* man pages can be viewed online at:[^9] + + +- [9]: generated from source using rman + +- + +- With regard to *SiSU* man pages the formatting generated for markup syntax is + not quite right, for that you might prefer the links under: + +- + +An online version of the sisu man page is available here: + + +* various sisu man pages [link:] [^10] + + +- [10]: + +* sisu.1 [link:] [^11] + + +- [11]: + +* sisu.8 [link:] [^12] + + +- [12]: + +* sisu_examples.1 [link:] +[^13] + + +- [13]: + +* sisu_webrick.1 [link:] +[^14] + + +- [14]: + +4.3 SISU BUILT-IN INTERACTIVE HELP +.................................. + +This is particularly useful when current installation information is obtained +as the interactive help is able to provide information on your sisu +configuration and setup. + + + sisu --help + + + sisu --help [subject] + + + sisu --help env [for feedback on the way your system is setup with regard + to sisu] + + + sisu -V [same as above command] + + + sisu --help commands + + + sisu --help markup + + +Apart from real-time information on your current configuration the *SiSU* +manual and man pages are likely to contain more up-to-date information than the +sisu interactive help (for example on commands and markup). + + +NOTE: Running the command sisu (alone without any flags, filenames or +wildcards) brings up the interactive help, as does any sisu command that is not +recognised. Enter to escape. + + +4.4 HELP SOURCES +................ + +For lists of alternative help sources, see: + + +*man page* + + + man sisu_help_sources + + +*man2html* + + + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + + +*sisu generated html* + + + /usr/share/doc/sisu/html/sisu_help_sources/index.html + + + + + + + + +5. COMMANDS SUMMARY +------------------- + +5.1 SYNOPSIS +............ + +*SiSU* - Structured information, Serialized Units - a document publishing +system + + +sisu [ -abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9 ] [ filename/ wildcard ] + + +sisu [ -Ddcv ] [ instruction ] + + +sisu [ -CcFLSVvW ] + + +Note: commands should be issued from within the directory that contains the +marked up files, cd to markup directory. + + +5.2 DESCRIPTION +............... + +*SiSU* *SiSU* is a document publishing system, that from a simple single +marked-up document, produces multiple of output formats including: plaintext, +html, LaTeX, pdf, xhtml, XML, info, and SQL (PostgreSQL and SQLite), which +share numbered text objects ("object citation numbering") and the same document +structure information. For more see: + + +5.3 DOCUMENT PROCESSING COMMAND FLAGS +..................................... + +*-a [filename/wildcard] * +produces plaintext with Unix linefeeds and without markup, (object numbers +are omitted), has footnotes at end of each paragraph that contains them [ -A +for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options +include: --endnotes for endnotes --footnotes for footnotes at the end of each +paragraph --unix for unix linefeed (default) --msdos for msdos linefeed) + + +*-b [filename/wildcard] * +produces xhtml/XML output for browser viewing (sax parsing). + + +*-C [--init-site] * +configure/initialise shared output directory files initialize shared output +directory (config files such as css and dtd files are not updated if they +already exist unless modifier is used). -C --init-site configure/initialise +site more extensive than -C on its own, shared output directory files/force +update, existing shared output config files such as css and dtd files are +updated if this modifier is used. + + +*-CC * +configure/initialise shared output directory files initialize shared output +directory (config files such as css and dtd files are not updated if they +already exist unless modifier is used). The equivalent of: -C --init-site +configure/initialise site, more extensive than -C on its own, shared output +directory files/force update, existing shared output config files such as css +and dtd files are updated if -CC is used. + + +*-c [filename/wildcard] * +screen toggle ansi screen colour on or off depending on default set (unless +-c flag is used: if sisurc colour default is set to 'true', output to screen +will be with colour, if sisurc colour default is set to 'false' or is undefined +screen output will be without colour). + + +*-D [instruction] [filename] * +database postgresql ( --pgsql may be used instead) possible instructions, +include: --createdb; --create; --dropall; --import [filename]; --update +[filename]; --remove [filename]; see database section below. + + +*-d [--db-[database type (sqlite|pg)]] --[instruction] [filename] * +database type default set to sqlite, (for which --sqlite may be used instead) +or to specify another database --db-[pgsql, sqlite] (however see -D) possible +instructions include: --createdb; --create; --dropall; --import [filename]; +--update [filename]; --remove [filename]; see database section below. + + +*-F [--webserv=webrick] * +generate examples of (naive) cgi search form for sqlite and pgsql depends on +your already having used sisu to populate an sqlite and/or pgsql database, (the +sqlite version scans the output directories for existing sisu_sqlite databases, +so it is first necessary to create them, before generating the search form) see +-d -D and the database section below. If the optional parameter +--webserv=webrick is passed, the cgi examples created will be set up to use the +default port set for use by the webrick server, (otherwise the port is left +blank and the system setting used, usually 80). The samples are dumped in the +present work directory which must be writable, (with screen instructions given +that they be copied to the cgi-bin directory). -Fv (in addition to the above) +provides some information on setting up hyperestraier for sisu + + +*-H [filename/wildcard] * +produces html without link suffixes (.html .pdf etc.) ("Hide"). Requires an +appropriately configured web server. [behaviour switched after 0.35 see -h]. + + +*-h [filename/wildcard] * +produces html (with hardlinks i.e. with name suffixes in links/local urls). +html, with internal document links that include the document suffix, i.e. +whether it is .html or .pdf (required for browsing directly off a file system, +and works with most web servers). [behaviour switched after 0.35 see -H]. + + +*-I [filename/wildcard] * +produces texinfo and info file, (view with pinfo). + + +*-L * +prints license information. + + +*-M [filename/wildcard/url] * +maintenance mode files created for processing preserved and their locations +indicated. (also see -V) + + +*-m [filename/wildcard/url] * +assumed for most other flags, creates new meta-markup file, (the metaverse ) +that is used in all subsequent processing of other output. This step is assumed +for most processing flags. To skip it see -n + + +*-N [filename/wildcard/url] * +document digest or document content certificate ( DCC ) as md5 digest tree of +the document: the digest for the document, and digests for each object +contained within the document (together with information on software versions +that produced it) (digest.txt). -NV for verbose digest output to screen. + + +*-n [filename/wildcard/url] * +skip meta-markup (building of "metaverse"), this skips the equivalent of -m +which is otherwise assumed by most processing flags. + + +*-o [filename/wildcard/url] * +output basic document in opendocument file format (opendocument.odt). + + +*-p [filename/wildcard] * +produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper size is set +in config file, or document header, or provided with additional command line +parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and +'legal' and book sizes 'A5' and 'B5' (system defaults to A4). + + +*-q [filename/wildcard] * +quiet less output to screen. + + +*-R [filename/wildcard] * +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Note the behavior of rsync +different if -R is used with other flags from if used alone. Alone the rsync +--delete parameter is sent, useful for cleaning the remote directory (when -R +is used together with other flags, it is not). Also see -r + + +*-r [filename/wildcard] * +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Also see -R + + +*-S * +produces a sisupod a zipped sisu directory of markup files including sisu +markup source files and the directories local configuration file, images and +skins. Note: this only includes the configuration files or skins contained in +./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option +is tested only with zsh). + + +*-S [filename/wildcard] * +produces a zipped file of the prepared document specified along with +associated images, by default named sisupod.zip they may alternatively be named +with the filename extension .ssp This provides a quick way of gathering the +relevant parts of a sisu document which can then for example be emailed. A +sisupod includes sisu markup source file, (along with associated documents if a +master file, or available in multilingual versions), together with related +images and skin. *SiSU* commands can be run directly against a sisupod +contained in a local directory, or provided as a url on a remote site. As there +is a security issue with skins provided by other users, they are not applied +unless the flag --trust or --trusted is added to the command instruction, it is +recommended that file that are not your own are treated as untrusted. The +directory structure of the unzipped file is understood by sisu, and sisu +commands can be run within it. Note: if you wish to send multiple files, it +quickly becomes more space efficient to zip the sisu markup directory, rather +than the individual files for sending). See the -S option without +[filename/wildcard]. + + +*-s [filename/wildcard] * +copies sisu markup file to output directory. + + +*-t [filename/wildcard (*.termsheet.rb)] * +standard form document builder, preprocessing feature + + +*-U [filename/wildcard] * +prints url output list/map for the available processing flags options and +resulting files that could be requested, (can be used to get a list of +processing options in relation to a file, together with information on the +output that would be produced), -u provides url output mapping for those flags +requested for processing. The default assumes sisu_webrick is running and +provides webrick url mappings where appropriate, but these can be switched to +file system paths in sisurc.yml + + +*-u [filename/wildcard] * +provides url mapping of output files for the flags requested for processing, +also see -U + + +*-V * +on its own, provides *SiSU* version and environment information (sisu --help +env) + + +*-V [filename/wildcard] * +even more verbose than the -v flag. (also see -M) + + +*-v * +on its own, provides *SiSU* version information + + +*-v [filename/wildcard] * +provides verbose output of what is being built, where it is being built (and +error messages if any), as with -u flag provides a url mapping of files created +for each of the processing flag requests. See also -V + + +*-W * +starts ruby's webrick webserver points at sisu output directories, the +default port is set to 8081 and can be changed in the resource configuration +files. [tip: the webrick server requires link suffixes, so html output should +be created using the -h option rather than -H; also, note -F webrick ]. + + +*-w [filename/wildcard] * +produces concordance (wordmap) a rudimentary index of all the words in a +document. (Concordance files are not generated for documents of over 260,000 +words unless this limit is increased in the file sisurc.yml) + + +*-X [filename/wildcard] * +produces XML output with deep document structure, in the nature of dom. + + +*-x [filename/wildcard] * +produces XML output shallow structure (sax parsing). + + +*-Y [filename/wildcard] * +produces a short sitemap entry for the document, based on html output and the +sisu_manifest. --sitemaps generates/updates the sitemap index of existing +sitemaps. (Experimental, [g,y,m announcement this week]) + + +*-y [filename/wildcard] * +produces an html summary of output generated (hyperlinked to content) and +document specific metadata (sisu_manifest.html). This step is assumed for most +processing flags. + + +*-Z [filename/wildcard] * +Zap, if used with other processing flags deletes output files of the type +about to be processed, prior to processing. If -Z is used as the lone +processing related flag (or in conjunction with a combination of -[mMvVq]), +will remove the related document output directory. + + +*-z [filename/wildcard] * +produces php (zend) [this feature is disabled for the time being] + + +6. COMMAND LINE MODIFIERS +------------------------- + +*--no-ocn * +[with -h -H or -p] switches off object citation numbering. Produce output +without identifying numbers in margins of html or LaTeX/pdf output. + + +*--no-annotate * +strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus +sign + + +- [*1]: square brackets + +*--no-asterisk * +strips output text of editor endnotes[^*2] denoted by asterisk sign + + +- [*2]: square brackets + +*--no-dagger * +strips output text of editor endnotes[^+1] denoted by dagger/plus sign + + +- [+1]: square brackets + +7. DATABASE COMMANDS +-------------------- + +dbi - database interface + + +-D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is +modifiable with --db=[database type (pgsql or sqlite)] + + +*-Dv --createall * +initial step, creates required relations (tables, indexes) in existing +postgresql database (a database should be created manually and given the same +name as working directory, as requested) (rb.dbi) [ -dv --createall sqlite +equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at +the present time for postgresql it may be necessary to manually create the +database. The command would be 'createdb [database name]' where database name +would be SiSU_[present working directory name (without path)]. Please use only +alphanumerics and underscores. + + +*-Dv --import * +[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ -dv +--import sqlite equivalent] + + +*-Dv --update * +[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) +[ -dv --update sqlite equivalent] + + +*-D --remove * +[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ -d +--remove sqlite equivalent] + + +*-D --dropall * +kills data" and drops (postgresql or sqlite) db, tables & indexes [ -d +--dropall sqlite equivalent] + + +The v in e.g. -Dv is for verbose output. + + +8. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +------------------------------------------ + +*--update [filename/wildcard] * +Checks existing file output and runs the flags required to update this +output. This means that if only html and pdf output was requested on previous +runs, only the -hp files will be applied, and only these will be generated this +time, together with the summary. This can be very convenient, if you offer +different outputs of different files, and just want to do the same again. + + +*-0 to -5 [filename or wildcard] * +Default shorthand mappings (note that the defaults can be changed/configured +in the sisurc.yml file): + + +*-0 * +-mNhwpAobxXyYv [this is the default action run when no options are give, i.e. +on 'sisu [filename]'] + + +*-1 * +-mNHwpy + + +*-2 * +-mNHwpaoy + + +*-3 * +-mNhwpAobxXyY + + +*-4 * +-mNhwpAobxXDyY --import + + +*-5 * +-mNhwpAobxXDyY --update + + +add -v for verbose mode and -c for color, e.g. sisu -2vc [filename or wildcard] + + +consider -u for appended url info or -v for verbose output + + +8.0.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +................................................ + +In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst" +or "sisu -h *.{sst,ssm}" to produce html version of all documents. + + +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. Enter to +escape. + + +9. INTRODUCTION TO SISU MARKUP[^15] +----------------------------------- + +- [15]: From sometime after SiSU 0.58 it should be possible to describe SiSU markup + using SiSU, which though not an original design goal is useful. + +9.1 SUMMARY +........... + +*SiSU* source documents are plaintext (UTF-8)[^16] files + + +- [16]: files should be prepared using UTF-8 character encoding + +All paragraphs are separated by an empty line. + + +Markup is comprised of: + + +* at the top of a document, the document header made up of semantic meta-data +about the document and if desired additional processing instructions (such an +instruction to automatically number headings from a particular level down) + + +* followed by the prepared substantive text of which the most important single +characteristic is the markup of different heading levels, which define the +primary outline of the document structure. Markup of substantive text includes: + + + * heading levels defines document structure + + + * text basic attributes, italics, bold etc. + + + * grouped text (objects), which are to be treated differently, such as code + blocks or poems. + + + * footnotes/endnotes + + + * linked text and images + + + * paragraph actions, such as indent, bulleted, numbered-lists, etc. + + +Some interactive help on markup is available, by typing sisu and selecting +markup or sisu --help markup + + +9.2 MARKUP EXAMPLES +................... + +9.2.1 ONLINE +............ + +Online markup examples are available together with the respective outputs +produced from or from + + + +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + + + +Some example marked up files are available as html with syntax highlighting for +viewing: + + +an alternative presentation of markup syntax: + + + +9.2.2 INSTALLED +............... + +With *SiSU* installed sample skins may be found in: +/usr/share/doc/sisu/sisu_markup_samples/dfsg (or equivalent directory) and if +sisu-markup-samples is installed also under: +/usr/share/doc/sisu/sisu_markup_samples/non-free + + +10. MARKUP OF HEADERS +--------------------- + +Headers consist of semantic meta-data about a document, which can be used by +any output module of the program; and may in addition include extra processing +instructions. + + +Note: the first line of a document may include information on the markup +version used in the form of a comment. Comments are a percentage mark at the +start of a paragraph (and as the first character in a line of text) followed by +a space and the comment: + + + + % this would be a comment + +10.1 SAMPLE HEADER +.................. + +This current document has a header similar to this one (without the comments): + + + + % SiSU 0.57 + @title: SiSU + @subtitle: Markup [0.58] + @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: 2002-08-28 + @date.issued: 2002-08-28 + @date.available: 2002-08-28 + @date.modified: 2007-09-16 + @date: 2007-09-16 + @level: new=C; break=1; num_top=1 + % comment: in this @level header num_top=1 starts automatic heading numbering at heading level 1 (numbering continues 3 levels down); the new and break instructions are used by the LaTeX/pdf and odf output to determine where to put page breaks (that are not used by html output or say sql database population). + @skin: skin_sisu_manual + % skins modify the appearance of a document and are placed in a sub-directory under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single documents that request them, all documents in a directory, or be site-wide. (A document is affected by a single skin) + @bold: /Gnu|Debian|Ruby|SiSU/ + @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ + { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/2.html + { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU + { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/ + { SiSU @ Ruby Application Archive }http://raa.ruby-lang.org/project/sisu/ + { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html + { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html + { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html + +10.2 AVAILABLE HEADERS +...................... + +Header tags appear at the beginning of a document and provide meta information +on the document (such as the Dublin Core), or information as to how the +document as a whole is to be processed. All header instructions take either the +form @headername: or 0~headername. All Dublin Core meta tags are available + + +*@indentifier:* information or instructions + + +where the "identifier" is a tag recognised by the program, and the +"information" or "instructions" belong to the tag/indentifier specified + + +Note: a header where used should only be used once; all headers apart from +@title: are optional; the @structure: header is used to describe document +structure, and can be useful to know. + + +This is a sample header + + +*% SiSU 0.38* [declared file-type identifier with markup version] + + +*@title:* [title text] This is the title of the document and used as such, this +header is the only one that is _mandatory_ + + +*@subtitle:* The Subtitle if any + + +*@creator:* [or @author:] Name of Author + + +*@subject:* (whatever your subject) + + +*@description:* + + +*@publisher:* + + +*@contributor:* + + +*@translator:* [or @translated_by:] + + +*@illustrator:* [or @illustrated_by:] + + +*@prepared_by:* [or @digitized_by:] + + +*@date: 2000-08-27* [ also @date.created: @date.issued: @date.available: +@date.valid: @date.modified: ] + + +*@type: article* + + +*@format:* + + +*@identifier:* + + +*@source:* + + +*@language:* [or @language.document:] [country code for language if available, +or language, English, en is the default setting] (en - English, fr - French, de +- German, it - Italian, es - Spanish, pt - Portuguese, sv - Swedish, da - +Danish, fi - Finnish, no - Norwegian, is - Icelandic, nl - Dutch, et - +Estonian, hu - Hungarian, pl - Polish, ro - Romanian, ru - Russian, el - Greek, +uk - Ukranian, tr - Turkish, sk - Slovak, sl - Slovenian, hr - Croatian, cs - +Czech, bg - Bul garian ) [however, encodings are not available for all of the +languages listed.] + + +[@language.original: original language in which the work was published] + + +*@papersize:* (A4|US_letter|book_B5|book_A5|US_legal) + + +*@relation:* + + +*@coverage:* + + +*@rights:* Copyright (c) Name of Right Holder, all rights reserved, or as +granted: public domain, copyleft, creative commons variant, etc. + + +*@owner:* + + +*@keywords:* text document generation processing management latex pdf +structured xml citation [your keywords here, used for example by rss feeds, and +in sql searches] + + +*@abstract:* [paper abstract, placed after table of contents] + + +*@comment:* [...] + + +*@catalogue:* loc=[Library of Congress classification]; dewey=[Dewey +classification]; isbn=[ISBN]; pg=[Project Gutenberg text number] + + +*@classify_loc:* [Library of Congress classification] + + +*@classify_dewey:* [Dewey classification] + + +*@classify_isbn:* [ISBN] + + +*@classify_pg:* [Project Gutenberg text number] + + +*@prefix:* [prefix is placed just after table of contents] + + +*@prefix_a:* [prefix is placed just before table of contents - not implemented] + + +*@prefix_b:* + + +*@rcs:* $Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ [used by rcs +or cvs to embed version (revision control) information into document, rcs or +cvs can usefully provide a history of updates to a document ] + + +*@structure:* PART; CHAPTER; SECTION; ARTICLE; none; none; +optional, document structure can be defined by words to match or regular +expression (the regular expression is assumed to start at the beginning of a +line of text i.e. ^) default markers :A~ to :C~ and 1~ to 6~ can be used within +text instead, without this header tag, and may be used to supplement the +instructions provided in this header tag if provided (@structure: is a synonym +for @toc:) + + +*@level:* newpage=3; breakpage=4 +[paragraph level, used by latex to breakpages, the page is optional eg. in +newpage] + + +*@markup:* information on the markup used, e.g. new=1,2,3; break=4; num_top=4 +[or newpage=1,2,3; breakpage=4; num_top=4] newpage and breakpage, heading +level, used by LaTeX to breakpages. breakpage: starts on a new page in single +column text and on a new column in double column text; newpage: starts on a new +page for both single and double column texts. +num_top=4 [auto-number document, starting at level 4. the default is to +provide 3 levels, as in 1 level 4, 1.1 level 5, 1.1.1 level 6, markup to be +merged within level] +num_extract [take numbering of headings provided (manually in marked up +source document), and use for numbering of segments. Available where a clear +numbering structure is provided within document, without the repetition of a +number in a header.] [In 0.38 notation, you would map to the equivalent levels, +the examples provided would map to the following new=A,B,C; break=1; num_top=1 +[or newpage=A,B,C; breakpage=1; num_top=1] see headings] + + +*@bold:* [regular expression of words/phrases to be made bold] + + +*@italics:* [regular expression of words/phrases to italicise] + + +*@vocabulary:* name of taxonomy/vocabulary/wordlist to use against document + + +*@skin:* skin_doc_[name_of_desired_document_skin] +skins change default settings related to the appearance of documents +generated, such as the urls of the home site, and the icon/logo for the +document or site. + + +*@links:* { *SiSU* }http://www.jus.uio.no/sisu/; +{ FSF }http://www.fsf.org + + +*@promo:* sisu, ruby, search_libre_docs, open_society +[places content in right pane in html, makes use of list.yml and promo.yml, +commented out sample in document sample: +free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst] + + +11. MARKUP OF SUBSTANTIVE TEXT +------------------------------ + +11.1 HEADING LEVELS +................... + +Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section +headings, followed by other heading levels, and 1 -6 being headings followed by +substantive text or sub-headings. :A~ usually the title :A~? conditional level +1 heading (used where a stand-alone document may be imported into another) + + +*:A~ [heading text]* Top level heading [this usually has similar content to the +title @title: ] NOTE: the heading levels described here are in 0.38 notation, +see heading + + +*:B~ [heading text]* Second level heading [this is a heading level divider] + + +*:C~ [heading text]* Third level heading [this is a heading level divider] + + +*1~ [heading text]* Top level heading preceding substantive text of document or +sub-heading 2, the heading level that would normally be marked 1. or 2. or 3. +etc. in a document, and the level on which sisu by default would break html +output into named segments, names are provided automatically if none are given +(a number), otherwise takes the form 1~my_filename_for_this_segment + + +*2~ [heading text]* Second level heading preceding substantive text of document +or sub-heading 3, the heading level that would normally be marked 1.1 or 1.2 or +1.3 or 2.1 etc. in a document. + + +*3~ [heading text]* Third level heading preceding substantive text of document, +that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a +document + + + + 1~filename level 1 heading, + % the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made) + +11.2 FONT ATTRIBUTES +.................... + +*markup example:* + + + + normal text !{emphasis}! *{bold text}* _{underscore}_ /{italics}/ "{citation}" ^{superscript}^ ,{subscript}, +{inserted text}+ + normal text + !{emphasis}! + *{bold text}* + _{underscore} + /{italics}/ + "{citation}" + ^{superscript}^ + ,{subscript}, + +{inserted text}+ + -{strikethrough}- + +*resulting output:* + + +normal text emphasis *bold text* _underscore_ /italics/ +citation ^superscript^ [subscript] inserted text +strikethrough + + +normal text + + +emphasis + + +*bold text* + + +_underscore_ + + +/italics/ + + +citation + + +^superscript^ + + +[subscript] + + +inserted text + + +strikethrough + + +11.3 INDENTATION AND BULLETS +............................ + +*markup example:* + + + + ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps + +*resulting output:* + + +ordinary paragraph + + + indent paragraph one step + + + indent paragraph two steps + + + indent paragraph nine steps + + +*markup example:* + + + + * bullet text + _1* bullet text, first indent + _2* bullet text, two step indent + +*resulting output:* + + +* bullet text + + + * bullet text, first indent + + + * bullet text, two step indent + + +Numbered List (not to be confused with headings/titles, (document structure)) + + +*markup example:* + + + + # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. + +11.4 FOOTNOTES / ENDNOTES +......................... + +Footnotes and endnotes not distinguished in markup. They are automatically +numbered. Depending on the output file format (html, odf, pdf etc.), the +document output selected will have either footnotes or endnotes. + + +*markup example:* + + + + ~{ a footnote or endnote }~ + +*resulting output:* + + +[^17] + + +- [17]: a footnote or endnote + +*markup example:* + + + + normal text~{ self contained endnote marker & endnote in one }~ continues + +*resulting output:* + + +normal text[^18] continues + + +- [18]: self contained endnote marker & endnote in one + +*markup example:* + + + + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues + +*resulting output:* + + +normal text [^*] continues + + +- [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required + +normal text [^**] continues + + +- [**]: another unnumbered asterisk footnote/endnote + +*markup example:* + + + + normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues + normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues + +*resulting output:* + + +normal text [^*3] continues + + +- [*3]: editors notes, numbered asterisk footnote/endnote series + +normal text [^+2] continues + + +- [+2]: editors notes, numbered asterisk footnote/endnote series + +*Alternative endnote pair notation for footnotes/endnotes:* + + + + % note the endnote marker "~^" + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs + +the standard and pair notation cannot be mixed in the same document + + +11.5 LINKS +.......... + +11.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +................................................ + +urls are found within text and marked up automatically. A url within text is +automatically hyperlinked to itself and by default decorated with angled +braces, unless they are contained within a code block (in which case they are +passed as normal text), or escaped by a preceding underscore (in which case the +decoration is omitted). + + +*markup example:* + + + + normal text http://www.jus.uio.no/sisu continues + +*resulting output:* + + +normal text continues + + +An escaped url without decoration + + +*markup example:* + + + + normal text http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non-free + +*resulting output:* + + +normal text http://www.jus.uio.no/sisu continues + + +deb http://www.jus.uio.no/sisu/archive unstable main non-free + + +where a code block is used there is neither decoration nor hyperlinking, code +blocks are discussed later in this document + + +*resulting output:* + + + + deb http://www.jus.uio.no/sisu/archive unstable main non-free + deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +To link text or an image to a url the markup is as follows + + +*markup example:* + + + + about { SiSU }http://url.org markup + +11.5.2 LINKING TEXT +................... + +*resulting output:* + + +about SiSU [link:] markup + + +A shortcut notation is available so the url link may also be provided +automatically as a footnote + + +*markup example:* + + + + about {~^ SiSU }http://url.org markup + +*resulting output:* + + +about SiSU [link:] [^19] markup + + +- [19]: + +11.5.3 LINKING IMAGES +..................... + +*markup example:* + + + + [ tux.png ] + % various url linked images + [ tux.png ] + [ GnuDebianLinuxRubyBetterWay.png ] + {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ + +*resulting output:* + + +tux.png 64x80 [link:] image + + +tux.png 64x80 "Gnu/Linux - a better way" [link:] + + +[ ruby_logo (png missing) ] [^20] + + +- [20]: + +GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian +and Ruby" [link:] + + +*linked url footnote shortcut* + + + + {~^ [text to link] }http://url.org + % maps to: { [text to link] }http://url.org ~{ http://url.org }~ + % which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink + + + text marker *~name + +note at a heading level the same is automatically achieved by providing names +to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of +auto-heading numbering, without further intervention. + + +11.6 GROUPED TEXT +................. + +11.6.1 TABLES +............. + +Tables may be prepared in two either of two forms + + +*markup example:* + + + + table{ c3; 40; 30; 30; + This is a table + this would become column two of row one + column three of row one is here + And here begins another row + column two of row two + column three of row two, and so on + }table + +*resulting output:* + + + +[table omitted, see other document formats] + +a second form may be easier to work with in cases where there is not much +information in each column + + +*markup example:*[^21] + + +- [21]: Table from the Wealth of Networks by Yochai Benkler + +- + + + !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005 + {table~h 24; 12; 12; 12; 12; 12; 12;} + |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006 + Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721 + Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945 + Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016 + No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 + No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 + \* Contributed at least ten times; \** at least 5 times in last month; \*\** more than 100 times in last month. + +*resulting output:* + + +*Table 3.1: Contributors to Wikipedia, January 2001 - June 2005* + + + +[table omitted, see other document formats] + +* Contributed at least ten times; ** at least 5 times in last month; *** more +than 100 times in last month. + + +11.6.2 POEM +........... + +*basic markup:* + + + + poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. + +*markup example:* + + + + poem{ + 'Fury said to a + mouse, That he + met in the + house, + "Let us + both go to + law: I will + prosecute + YOU. --Come, + I'll take no + denial; We + must have a + trial: For + really this + morning I've + nothing + to do." + Said the + mouse to the + cur, "Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath." + "I'll be + judge, I'll + be jury," + Said + cunning + old Fury: + "I'll + try the + whole + cause, + and + condemn + you + to + death."' + }poem + +*resulting output:* + + + + 'Fury said to a + mouse, That he + met in the + house, + "Let us + both go to + law: I will + prosecute + YOU. --Come, + I'll take no + denial; We + must have a + trial: For + really this + morning I've + nothing + to do." + Said the + mouse to the + cur, "Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath." + "I'll be + judge, I'll + be jury," + Said + cunning + old Fury: + "I'll + try the + whole + cause, + and + condemn + you + to + death."' + +11.6.3 GROUP +............ + +*basic markup:* + + + + group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. + +*markup example:* + + + + group{ + 'Fury said to a + mouse, That he + met in the + house, + "Let us + both go to + law: I will + prosecute + YOU. --Come, + I'll take no + denial; We + must have a + trial: For + really this + morning I've + nothing + to do." + Said the + mouse to the + cur, "Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath." + "I'll be + judge, I'll + be jury," + Said + cunning + old Fury: + "I'll + try the + whole + cause, + and + condemn + you + to + death."' + }group + +*resulting output:* + + + + 'Fury said to a + mouse, That he + met in the + house, + "Let us + both go to + law: I will + prosecute + YOU. --Come, + I'll take no + denial; We + must have a + trial: For + really this + morning I've + nothing + to do." + Said the + mouse to the + cur, "Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath." + "I'll be + judge, I'll + be jury," + Said + cunning + old Fury: + "I'll + try the + whole + cause, + and + condemn + you + to + death."' + +11.6.4 CODE +........... + +Code tags are used to escape regular sisu markup, and have been used +extensively within this document to provide examples of *SiSU* markup. You +cannot however use code tags to escape code tags. They are however used in the +same way as group or poem tags. + + +A code-block is treated as an object and given a single object number. [an +option to number each line of code may be considered at some later time] + + +*use of code tags instead of poem compared, resulting output:* + + + + 'Fury said to a + mouse, That he + met in the + house, + "Let us + both go to + law: I will + prosecute + YOU. --Come, + I'll take no + denial; We + must have a + trial: For + really this + morning I've + nothing + to do." + Said the + mouse to the + cur, "Such + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath." + "I'll be + judge, I'll + be jury," + Said + cunning + old Fury: + "I'll + try the + whole + cause, + and + condemn + you + to + death."' + +12. COMPOSITE DOCUMENTS MARKUP +------------------------------ + +It is possible to build a document by creating a master document that requires +other documents. The documents required may be complete documents that could be +generated independently, or they could be markup snippets, prepared so as to be +easily available to be placed within another text. If the calling document is a +master document (built from other documents), it should be named with the +suffix *.ssm* Within this document you would provide information on the other +documents that should be included within the text. These may be other documents +that would be processed in a regular way, or markup bits prepared only for +inclusion within a master document *.sst* regular markup file, or *.ssi* +(insert/information) A secondary file of the composite document is built prior +to processing with the same prefix and the suffix *._sst* + + +basic markup for importing a document into a master document + + + + << |filename1.sst|@|^| + << |filename2.ssi|@|^| + +The form described above should be relied on. Within the Vim editor it results +in the text thus linked becoming hyperlinked to the document it is calling in +which is convenient for editing. Alternative markup for importation of +documents under consideration, and occasionally supported have been. + + + + r{filename} + {filename.ssi}require + << {filename.ssi} + % using textlink alternatives + |filename.ssi|@|^|require + << |filename.ssi|@|^| + % using thlnk alternatives + require + << + +MARKUP SYNTAX HISTORY +===================== + +13. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX +-------------------------------------------------- + +0.38 is substantially current, depreciated 0.16 supported, though file names +were changed at 0.37 + + +*0.52* (2007w14/6) declared document type identifier at start of text/document: + + + *SiSU* 0.52 + + +or, backward compatible using the comment marker: + + + % *SiSU* 0.38 + + +variations include '*SiSU* (text|master|insert) [version]' and 'sisu-[version]' + + +*0.51* (2007w13/6) skins changed (simplified), markup unchanged + + +*0.42* (2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author + + +*0.38* (2006w15/7) introduced new/alternative notation for headers, e.g. +@title: (instead of 0~title), and accompanying document structure markup, +:A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6) + + +*0.37* (2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged + + +*0.35* (2005w52/3) sisupod, zipped content file introduced + + +*0.23* (2005w36/2) utf-8 for markup file + + +*0.22* (2005w35/3) image dimensions may be omitted if rmagick is available to +be relied upon + + +*0.20.4* (2005w33/4) header 0~links + + +*0.16* (2005w25/2) substantial changes introduced to make markup cleaner, +header 0~title type, and headings [1-6]~ introduced, also percentage sign (%) +at start of a text line as comment marker + + +14. SISU FILETYPES +------------------ + +*SiSU* has plaintext and binary filetypes, and can process either type of +document. + + +14.1 .SST .SSM .SSI MARKED UP PLAIN TEXT +........................................ + +*SiSU* documents are prepared as plain-text (utf-8) files with *SiSU* markup. +They may make reference to and contain images (for example), which are stored +in the directory beneath them _sisu/image. *SiSU* plaintext markup files are of +three types that may be distinguished by the file extension used: regular text +.sst; master documents, composite documents that incorporate other text, which +can be any regular text or text insert; and inserts the contents of which are +like regular text except these are marked .ssi and are not processed. + + +*SiSU* processing can be done directly against a sisu documents; which may be +located locally or on a remote server for which a url is provided. + + +*SiSU* source markup can be shared with the command: + + + sisu -s [filename] + + +14.1.1 SISU TEXT - REGULAR FILES (.SST) +....................................... + +The most common form of document in *SiSU*, see the section on *SiSU* markup. + + + + + + + + +14.1.2 SISU MASTER FILES (.SSM) +............................... + +Composite documents which incorporate other *SiSU* documents which may be +either regular *SiSU* text .sst which may be generated independently, or +inserts prepared solely for the purpose of being incorporated into one or more +master documents. + + +The mechanism by which master files incorporate other documents is described as +one of the headings under under *SiSU* markup in the *SiSU* manual. + + +Note: Master documents may be prepared in a similar way to regular documents, +and processing will occur normally if a .sst file is renamed .ssm without +requiring any other documents; the .ssm marker flags that the document may +contain other documents. + + +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst [^22] + + +- [22]: .ssc (for composite) is under consideration but ._sst makes clear that this + is not a regular file to be worked on, and thus less likely that people will + have "accidents", working on a .ssc file that is overwritten by subsequent + processing. It may be however that when the resulting file is shared .ssc is + an appropriate suffix to use. + + + + + + + +14.1.3 SISU INSERT FILES (.SSI) +............................... + +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular *SiSU* text files +except they are ignored by the *SiSU* processor. Making a file a .ssi file is a +quick and convenient way of flagging that it is not intended that the file +should be processed on its own. + + +14.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) +......................................................... + +A sisupod is a zipped *SiSU* text file or set of *SiSU* text files and any +associated images that they contain (this will be extended to include sound and +multimedia-files) + + +*SiSU* plaintext files rely on a recognised directory structure to find +contents such as images associated with documents, but all images for example +for all documents contained in a directory are located in the sub-directory +_sisu/image. Without the ability to create a sisupod it can be inconvenient to +manually identify all other files associated with a document. A sisupod +automatically bundles all associated files with the document that is turned +into a pod. + + +The structure of the sisupod is such that it may for example contain a single +document and its associated images; a master document and its associated +documents and anything else; or the zipped contents of a whole directory of +prepared *SiSU* documents. + + +The command to create a sisupod is: + + + sisu -S [filename] + + +Alternatively, make a pod of the contents of a whole directory: + + + sisu -S + + +*SiSU* processing can be done directly against a sisupod; which may be located +locally or on a remote server for which a url is provided. + + + + + + + + +15. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +-------------------------------------------------- + +15.1 ALTERNATIVE XML +.................... + +*SiSU* offers alternative XML input representations of documents as a proof of +concept, experimental feature. They are however not strictly maintained, and +incomplete and should be handled with care. + + +*convert from sst to simple xml representations (sax, dom and node):* + + + sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard] + + + sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard] + + + sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard] + + +*convert to sst from any sisu xml representation (sax, dom and node):* + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +15.1.1 XML SAX REPRESENTATION +............................. + +To convert from sst to simple xml (sax) representation: + + + sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +15.1.2 XML DOM REPRESENTATION +............................. + +To convert from sst to simple xml (dom) representation: + + + sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +15.1.3 XML NODE REPRESENTATION +.............................. + +To convert from sst to simple xml (node) representation: + + + sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard] + + +To convert from any sisu xml representation back to sst + + + sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +or the same: + + + sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]] + + +16. CONFIGURATION +----------------- + +16.1 DETERMINING THE CURRENT CONFIGURATION +.......................................... + +Information on the current configuration of *SiSU* should be available with the +help command: + + + sisu -v + + +which is an alias for: + + + sisu --help env + + +Either of these should be executed from within a directory that contains sisu +markup source documents. + + +16.2 CONFIGURATION FILES (CONFIG.YML) +..................................... + +*SiSU* configration parameters are adjusted in the configuration file, which +can be used to override the defaults set. This includes such things as which +directory interim processing should be done in and where the generated output +should be placed. + + +The *SiSU* configuration file is a yaml file, which means indentation is +significant. + + +*SiSU* resource configuration is determined by looking at the following files +if they exist: + + + ./_sisu/sisurc.yml + + + ~/.sisu/sisurc.yml + + + /etc/sisu/sisurc.yml + + +The search is in the order listed, and the first one found is used. + + +In the absence of instructions in any of these it falls back to the internal +program defaults. + + +Configuration determines the output and processing directories and the database +access details. + + +If *SiSU* is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml + + +17. SKINS +--------- + +Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following locations: + + + ./_sisu/skin + + + ~/.sisu/skin + + + /etc/sisu/skin + + +*Within the skin directory* are the following the default sub-directories for +document skins: + + + ./skin/doc + + + ./skin/dir + + + ./skin/site + + +A skin is placed in the appropriate directory and the file named skin_[name].rb + + +The skin itself is a ruby file which modifies the default appearances set in +the program. + + +17.1 DOCUMENT SKIN +.................. + +Documents take on a document skin, if the header of the document specifies a +skin to be used. + + + + @skin: skin_united_nations + +17.2 DIRECTORY SKIN +................... + +A directory may be mapped on to a particular skin, so all documents within that +directory take on a particular appearance. If a skin exists in the skin/dir +with the same name as the document directory, it will automatically be used for +each of the documents in that directory, (except where a document specifies the +use of another skin, in the skin/doc directory). + + +A personal habit is to place all skins within the doc directory, and symbolic +links as needed from the site, or dir directories as required. + + +17.3 SITE SKIN +.............. + +A site skin, modifies the program default skin. + + +17.4 SAMPLE SKINS +................. + +With *SiSU* installed sample skins may be found in: + + + /etc/sisu/skin/doc and + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + + +(or equivalent directory) and if sisu-markup-samples is installed also under: + + + /usr/share/doc/sisu/sisu_markup_samples/non-free/_sisu/skin/doc + + +Samples of list.yml and promo.yml (which are used to create the right column +list) may be found in: + + + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent + directory) + + +18. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +---------------------------------------------------------- + +CSS files to modify the appearance of *SiSU* html, XHTML or XML may be placed +in the configuration directory: ./_sisu/css; ~/.sisu/css or; /etc/sisu/css and +these will be copied to the output directories with the command sisu -CC. + + +The basic CSS file for html output is html.css, placing a file of that name in +directory _sisu/css or equivalent will result in the default file of that name +being overwritten. + + +HTML: html.css + + +XML DOM: dom.css + + +XML SAX: sax.css + + +XHTML: xhtml.css + + +The default homepage may use homepage.css or html.css + + +Under consideration is to permit the placement of a CSS file with a different +name in directory _sisu/css directory or equivalent, and change the default CSS +file that is looked for in a skin.[^23] + + +- [23]: *SiSU* has worked this way in the past, though this was dropped as it was + thought the complexity outweighed the flexibility, however, the balance was + rather fine and this behaviour could be reinstated. + +19. ORGANISING CONTENT +---------------------- + +19.1 DIRECTORY STRUCTURE AND MAPPING +.................................... + +The output directory root can be set in the sisurc.yml file. Under the root, +subdirectories are made for each directory in which a document set resides. If +you have a directory named poems or conventions, that directory will be created +under the output directory root and the output for all documents contained in +the directory of a particular name will be generated to subdirectories beneath +that directory (poem or conventions). A document will be placed in a +subdirectory of the same name as the document with the filetype identifier +stripped (.sst .ssm) + + +The last part of a directory path, representing the sub-directory in which a +document set resides, is the directory name that will be used for the output +directory. This has implications for the organisation of document collections +as it could make sense to place documents of a particular subject, or type +within a directory identifying them. This grouping as suggested could be by +subject (sales_law, english_literature); or just as conveniently by some other +classification (X University). The mapping means it is also possible to place +in the same output directory documents that are for organisational purposes +kept separately, for example documents on a given subject of two different +institutions may be kept in two different directories of the same name, under a +directory named after each institution, and these would be output to the same +output directory. Skins could be associated with each institution on a +directory basis and resulting documents will take on the appropriate different +appearance. + + +19.2 ORGANISING CONTENT +....................... + +20. HOMEPAGES +------------- + +*SiSU* is about the ability to auto-generate documents. Home pages are regarded +as custom built items, and are not created by *SiSU*. More accurately, *SiSU* +has a default home page, which will not be appropriate for use with other +sites, and the means to provide your own home page instead in one of two ways +as part of a site's configuration, these being: + + +1. through placing your home page and other custom built documents in the +subdirectory _sisu/home/ (this probably being the easier and more convenient +option) + + +2. through providing what you want as the home page in a skin, + + +Document sets are contained in directories, usually organised by site or +subject. Each directory can/should have its own homepage. See the section on +directory structure and organisation of content. + + +20.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY +.............................................................. + +Custom built pages, including the home page index.html may be placed within the +configuration directory _sisu/home/ in any of the locations that is searched +for the configuration directory, namely ./_sisu; ~/_sisu; /etc/sisu From there +they are copied to the root of the output directory with the command: + + + sisu -CC + + +20.2 HOME PAGE WITHIN A SKIN +............................ + +Skins are described in a separate section, but basically are a file written in +the programming language *Ruby* that may be provided to change the defaults +that are provided with sisu with respect to individual documents, a directories +contents or for a site. + + +If you wish to provide a homepage within a skin the skin should be in the +directory _sisu/skin/dir and have the name of the directory for which it is to +become the home page. Documents in the directory commercial_law would have the +homepage modified in skin_commercial law.rb; or the directory poems in +skin_poems.rb + + + + class Home + def homepage + # place the html content of your homepage here, this will become index.html + < + + +

this is my new homepage.

+ + + HOME + end + end + +21. MARKUP AND OUTPUT EXAMPLES +------------------------------ + +21.1 MARKUP EXAMPLES +.................... + +Current markup examples and document output samples are provided at + + + +Some markup with syntax highlighting may be found under + but is not as up to date. + + +For some documents hardly any markup at all is required at all, other than a +header, and an indication that the levels to be taken into account by the +program in generating its output are. + + +21.2 A FEW BOOK (AND OTHER) EXAMPLES +.................................... + +aukio.png 397x340 "Aukio, by Leena Krohn" [link:] + [^24] + + +- [24]: Reproduced with the kind permission of author and artist Leena Krohn, + "Aukio" is from the work /"Sphinx or Robot"/ + which is + included as a book example in this section, together with another of the + author's works, /"Tainaron"/ + + +/"THE WEALTH OF NETWORKS"/, YOCHAI BENKLER +.......................................... + +"The Wealth of Networks", Yochai Benkler [link:] + + + + document manifest [link:] + + [^25] + + +- [25]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"FREE CULTURE"/, LAWRENCE LESSIG +................................. + +"Free Culture", Lawrence Lessig [link:] + + + + document manifest [link:] + + [^26] + + +- [26]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"FREE AS IN FREEDOM: RICHARD STALLMAN'S CRUSADE FOR FREE SOFTWARE"/, BY SAM +WILLIAMS +.............................................................................. + +"Free as in Freedom: Richard Stallman's Crusade for Free Software", by Sam +Williams [link:] + + + + document manifest [link:] + + [^27] + + +- [27]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"FREE FOR ALL: HOW LINUX AND THE FREE SOFTWARE MOVEMENT UNDERCUT THE HIGH TECH +TITANS"/, BY PETER WAYNER +.............................................................................. + +"Free For All: How Linux and the Free Software Movement Undercut the High Tech +Titans", by Peter Wayner [link:] + + + + document manifest [link:] + + [^28] + + +- [28]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"THE CATHEDRAL AND THE BAZAAR"/, BY ERIC S. RAYMOND +.................................................... + +"The Cathedral and the Bazaar", by Eric S. Raymond [link:] + + + + document manifest [link:] + + [^29] + + +- [29]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"ACCELERANDO"/, CHARLES STROSS +............................... + +"Accelerando", Charles Stross [link:] + + + + document manifest [link:] + + [^30] + + +- [30]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"TAINARON"/, LEENA KROHN +......................... + +"Tainaron", Leena Krohn [link:] + + + + document manifest [link:] + + [^31] + + +- [31]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"SPHINX OR ROBOT"/, LEENA KROHN +................................ + +i_sor.png 294x59 "Sphinx or Robot by Leena Krohn" [link:] + + + +"Sphinx or Robot", Leena Krohn [link:] + + + + document manifest [link:] + + [^32] + + +- [32]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"WAR AND PEACE"/, LEO TOLSTOY, PG ETEXT 2600 +............................................. + +"War and Peace", Leo Tolstoy [link:] + +[^33] + + +- [33]: + +- The ascii text was taken from Project Gutenberg. The markup transforms + required are trivial. Of interest, in this instance I am saved by having + alternative syntaxes/(structural modes) for marking up endnotes... as it was + possible to do a simple search and replace to make the Project Gutenberg ascii + presentation suitable for *SiSU*, using the older endnote markup style. This + example instructs the program to use regular expressions, in this example the + words: none; none; BOOK|FIRST|SECOND; CHAPTER; occurring at the beginning of a + line, to identify what should be treated as different levels of heading in a + document (and used to make the table of contents). Note that there was _very + little markup required_ after the document headers and Project Gutenberg legal + notices. As I presume the legal notices are similar in Project Gutenberg + documents, (and I could not bear to think of preparing the same legal notices + twice), I moved those to the "skin" for the Project, and these are now + represented in the markup by <:insert1> and <:insert2> and the + legal notices are available for similar insertion into the next Project + Gutenberg text prepared for *SiSU*, should there be one. + +- I did a stylesheet/skin for the Gutenberg Project, ... I may have to remove. + The markup transforms required are trivial. Of interest, in this instance I am + saved by having alternative syntaxes/(structural modes) for marking up + endnotes... as it is possible to do a simple search and replace to make + Project Gutenberg ascii presentations suitable for *SiSU* using the older + endnote markup style. There is _very little markup required_ after the + document headers and Project Gutenberg legal notices. As I presume the legal + notices are similar in Project Gutenberg documents, (and I could not bear to + think of preparing the same legal notices twice), I moved those to the "skin" + for the Project, and these are now represented in the markup by the + <:insert1> and <:insert2> markers and the legal notices are + available for similar insertion into the next Project Gutenberg text prepared + for *SiSU*, should there be one. + + document manifest [link:] + + [^34] + + +- [34]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DON QUIXOTE"/, MIGUEL DE CERVANTES [SAAVEDRA], TRANSLATED BY JOHN ORMSBY, PG +ETEXT 996 +.............................................................................. + +"Don Quixote", Miguel de Cervantes [Saavedra] [link:] + + + + document manifest [link:] + + [^35] + + +- [35]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"GULLIVER'S TRAVELS"/, JONATHAN SWIFT, TRANSCRIBED FROM THE 1892 GEORGE BELL +AND SONS EDITION BY DAVID PRICE, PG ETEXT 829 +.............................................................................. + +"Gulliver's Travels", Jonathan Swift [link:] + + + + document manifest [link:] + + [^36] + + +- [36]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"ALICE'S ADVENTURES IN WONDERLAND"/, LEWIS CARROLL, PG ETEXT 11 +................................................................ + +"Alice's Adventures in Wonderland", Lewis Carroll [link:] + + + + document manifest [link:] + + [^37] + + +- [37]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"THROUGH THE LOOKING-GLASS"/, LEWIS CARROLL, PG ETEXT 12 +......................................................... + +"Through The Looking-Glass", Lewis Carroll [link:] + + + + document manifest [link:] + + [^38] + + +- [38]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"ALICE'S ADVENTURES IN WONDERLAND"/ AND /"THROUGH THE LOOKING-GLASS"/, LEWIS +CARROLL, PG ETEXTS 11 AND 12 +.............................................................................. + +"Alice's Adventures in Wonderland" and "Through The Looking-Glass", Lewis +Carroll [link:] + + + + document manifest [link:] + + [^39] + + +- [39]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"GNU PUBLIC LICENSE 2"/, (GPL 2) FREE SOFTWARE FOUNDATION +.......................................................... + +"Gnu Public License 2", (GPL 2) Free Software Foundation [link:] + + + + document manifest [link:] + [^40] + + +- [40]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + xml, dom [link:] + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"GNU PUBLIC LICENSE V3 - THIRD DISCUSSION DRAFT"/, (GPLV3) FREE SOFTWARE +FOUNDATION +.............................................................................. + +"Gnu Public License 3 - Third discussion draft", (GPL v3 draft3) Free Software +Foundation [link:] + + + + document manifest [link:] + + [^41] + + +- [41]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DEBIAN SOCIAL CONTRACT"/ +.......................... + +"Debian Social Contract" [link:] + + + + document manifest [link:] + + [^42] + + +- [42]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DEBIAN CONSTITUTION V1.3"/, (SIMPLE/DEFAULT MARKUP) +..................................................... + +"Debian Constitution v1.3" [link:] + + + + document manifest [link:] + + [^43] + + +- [43]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DEBIAN CONSTITUTION V1.3"/, (MARKUP ADJUSTED FOR OUTPUT TO MORE CLOSELY MATCH +THE ORIGINAL) +.............................................................................. + +"Debian Constitution v1.3", (markup adjusted for output to more closely match +the original) [link:] + + + + document manifest [link:] + + [^44] + + +- [44]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DEBIAN CONSTITUTION V1.2"/, (SIMPLE/DEFAULT MARKUP) +..................................................... + +"Debian Constitution v1.2 (more translations)" [link:] + + + + document manifest [link:] + + [^45] + + +- [45]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"DEBIAN CONSTITUTION V1.2"/, (MARKUP ADJUSTED FOR OUTPUT TO MORE CLOSELY MATCH +THE ORIGINAL) +.............................................................................. + +"Debian Constitution (more translations)", (markup adjusted for output to more +closely match the original) [link:] + + + + document manifest [link:] + + [^46] + + +- [46]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"A UNIFORM SALES TERMINOLOGY"/, VIKKI ROGERS AND ALBERT KRITZER +................................................................ + +"A Uniform Sales Terminology", Vikki Rogers and Albert Kritzer [link:] + + + + document manifest [link:] + + [^47] + + +- [47]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"THE AUTONOMOUS CONTRACT" 1997 / - MARKUP SAMPLE +................................................. + +"The Autonomous Contract" 1997 - markup sample [link:] + + + + document manifest [link:] + + [^48] + + +- [48]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"THE AUTONOMOUS CONTRACT REVISITED"/ - MARKUP SAMPLE +..................................................... + +"The Autonomous Contract Revisited" - markup sample [link:] + [^49] + + +- [49]: + +- alternative markup variations revolving around endnotes + +- (i) as above, markup with embedded endnotes, and header list of words/phrases + to emphasise + +- + +- + +- (ii) Again markup with embedded endnotes, but font faces changed within + paragraphs rather than in header as in i + +- + +- + +- (iii) Markup with endnote placemarks within paragraphs, the endnotes following + the paragraph that contains them + + +- + +- (iv) Another alternative is to place the marked up endnotes sequentially and + at the end of the text. This also works. The paragraph variant iii is perhaps + easier to visually check should there be missing endnotes; but this variant iv + may better suit the conversion of alternatively pre-prepared documents. + + document manifest [link:] + + [^50] + + +- [50]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/"UNITED NATIONS CONVENTION ON CONTRACTS FOR THE INTERNATIONAL SALE OF GOODS"/ +.............................................................................. + +"United Nations Convention on Contracts for the International Sale of Goods" +[link:] + +[^51] + + +- [51]: + +- This example instructs the program to use regular expressions, in this example + the words: Part, Chapter, Section, Article occurring at the beginning of a + line, to identify what should be treated as different levels of heading in a + document (and used to make the table of contents). + +- This example instructs the program to use regular expressions, in this example + the words: Part, Chapter, Section, Article occurring at the beginning of a + line, to identify what should be treated as different levels of heading in a + document (and used to make the table of contents). + + document manifest [link:] + + [^52] + + +- [52]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +/PECL/ THE "PRINCIPLES OF EUROPEAN CONTRACT LAW" +................................................ + +"Principles of European Contract Law" [link:] + + + + document manifest [link:] + + [^53] + + +- [53]: + + html, segmented text [link:] + + + + html, scroll, document in one [link:] + + + + pdf, landscape [link:] + + + + pdf, portrait [link:] + + + + open document [link:] + + + + xhtml scroll [link:] + + + + xml, sax [link:] + + + + xml, dom [link:] + + + + plain text utf-8 [link:] + + + + concordance [link:] + + + + dcc, document content certificate (digests) [link:] + + + + markup source text [link:] + + + + zipped markup source pod [link:] + + + +21.3 SQL - POSTGRESQL, SQLITE +............................. + +A Sample search form is available at + + +A few canned searches, showing object numbers. Search for: + + + English documents matching Linux OR Debian [link:] + + + + GPL OR Richard Stallman [link:] + + + + invention OR innovation in English language [link:] + + + + copyright in English language documents [link:] + + + +Note that the searches done in this form are case sensitive. + + +Expand those same searches, showing the matching text in each document: + + + English documents matching Linux OR Debian [link:] + + + + GPL OR Richard Stallman [link:] + + + + invention OR innovation in English language [link:] + + + + copyright in English language documents [link:] + + + +Note you may set results either for documents matched and object number +locations within each matched document meeting the search criteria; or display +the names of the documents matched along with the objects (paragraphs) that +meet the search criteria.[^54] + + +- [54]: of this feature when demonstrated to an IBM software innovations evaluator + in 2004 he said to paraphrase: this could be of interest to us. We have large + document management systems, you can search hundreds of thousands of documents + and we can tell you which documents meet your search criteria, but there is no + way we can tell you without opening each document where within each your + matches are found. + +21.4 LEX MERCATORIA AS AN EXAMPLE +................................. + +There is quite a bit to peruse if you explore the site Lex Mercatoria: + + + [^55] + + +- [55]: + +or perhaps: + + + [^56] + + +- [56]: + +21.5 FOR GOOD MEASURE THE MARKUP FOR A DOCUMENT WITH LOTS OF (SIMPLE) TABLES +............................................................................ + +*SiSU* is not optimised for table making, but does handle simple tables. + + +* SiSU marked up file with tables [link:] + +[^57] + + +- [57]: + +- + +* Output of table file example [link:] + [^58] + + +- [58]: + +21.6 AND A LINK TO THE OUTPUT OF A REPORTED CASE +................................................ + + + + +22. A CHECKLIST OF OUTPUT FEATURES +---------------------------------- + +This table gives an indication of the features that are available for various +forms of output of *SiSU*. [^59] + + +- [59]: updated for sisu-0.36.6 on 2006-01-23 + + +[table omitted, see other document formats] + + + Done + * yes/done + . partial + - not available/appropriate + Not Done + T task todo + t lesser task/todo + not done + +23. SISU SEARCH - INTRODUCTION +------------------------------ + +*SiSU* output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + + +Because the document structure of sites created is clearly defined, and the +text object citation system is available hypothetically at least, for all forms +of output, it is possible to search the sql database, and either read results +from that database, or just as simply map the results to the html output, which +has richer text markup. + + +In addition to this *SiSU* has the ability to populate a relational sql type +database with documents at an object level, with objects numbers that are +shared across different output types, which make them searchable with that +degree of granularity. Basically, your match criteria is met by these documents +and at these locations within each document, which can be viewed within the +database directly or in various output formats. + + +24. SQL +------- + +24.1 POPULATING SQL TYPE DATABASES +.................................. + +*SiSU* feeds sisu markupd documents into sql type databases PostgreSQL[^60] +and/or SQLite[^61] database together with information related to document +structure. + + +- [60]: + +- + +- + +- [61]: + +- + +This is one of the more interesting output forms, as all the structural data of +the documents are retained (though can be ignored by the user of the database +should they so choose). All site texts/documents are (currently) streamed to +four tables: + + + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + + + * another the substantive texts by individual "paragraph" (or object) - along + with structural information, each paragraph being identifiable by its + paragraph number (if it has one which almost all of them do), and the + substantive text of each paragraph quite naturally being searchable (both in + formatted and clean text versions for searching); and + + + * a third containing endnotes cross-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + + + * a fourth table with a one to one relation with the headers table contains + full text versions of output, eg. pdf, html, xml, and ascii. + + +There is of course the possibility to add further structures. + + +At this level *SiSU* loads a relational database with documents chunked into +objects, their smallest logical structurally constituent parts, as text +objects, with their object citation number and all other structural information +needed to construct the document. Text is stored (at this text object level) +with and without elementary markup tagging, the stripped version being so as to +facilitate ease of searching. + + +Being able to search a relational database at an object level with the *SiSU* +citation system is an effective way of locating content generated by *SiSU*. As +individual text objects of a document stored (and indexed) together with object +numbers, and all versions of the document have the same numbering, complex +searches can be tailored to return just the locations of the search results +relevant for all available output formats, with live links to the precise +locations in the database or in html/xml documents; or, the structural +information provided makes it possible to search the full contents of the +database and have headings in which search content appears, or to search only +headings etc. (as the Dublin Core is incorporated it is easy to make use of +that as well). + + +25. POSTGRESQL +-------------- + +25.1 NAME +......... + +*SiSU* - Structured information, Serialized Units - a document publishing +system, postgresql dependency package + + +25.2 DESCRIPTION +................ + +Information related to using postgresql with sisu (and related to the +sisu_postgresql dependency package, which is a dummy package to install +dependencies needed for *SiSU* to populate a postgresql database, this being +part of *SiSU* - man sisu). + + +25.3 SYNOPSIS +............. + + sisu -D [instruction] [filename/wildcard if required] + + + sisu -D --pg --[instruction] [filename/wildcard if required] + + +25.4 COMMANDS +............. + +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +-d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql, +alternatively --sqlite or --pgsql may be used + + +*-D or --pgsql* may be used interchangeably. + + +25.4.1 CREATE AND DESTROY DATABASE +.................................. + +*--pgsql --createall* +initial step, creates required relations (tables, indexes) in existing +(postgresql) database (a database should be created manually and given the same +name as working directory, as requested) (rb.dbi) + + +*sisu -D --createdb* +creates database where no database existed before + + +*sisu -D --create* +creates database tables where no database tables existed before + + +*sisu -D --Dropall* +destroys database (including all its content)! kills data and drops tables, +indexes and database associated with a given directory (and directories of the +same name). + + +*sisu -D --recreate* +destroys existing database and builds a new empty database structure + + +25.4.2 IMPORT AND REMOVE DOCUMENTS +.................................. + +*sisu -D --import -v [filename/wildcard]* +populates database with the contents of the file. Imports documents(s) +specified to a postgresql database (at an object level). + + +*sisu -D --update -v [filename/wildcard]* +updates file contents in database + + +*sisu -D --remove -v [filename/wildcard]* +removes specified document from postgresql database. + + +26. SQLITE +---------- + +26.1 NAME +......... + +*SiSU* - Structured information, Serialized Units - a document publishing +system. + + +26.2 DESCRIPTION +................ + +Information related to using sqlite with sisu (and related to the sisu_sqlite +dependency package, which is a dummy package to install dependencies needed for +*SiSU* to populate an sqlite database, this being part of *SiSU* - man sisu). + + +26.3 SYNOPSIS +............. + + sisu -d [instruction] [filename/wildcard if required] + + + sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required] + + +26.4 COMMANDS +............. + +Mappings to two databases are provided by default, postgresql and sqlite, the +same commands are used within sisu to construct and populate databases however +-d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql, +alternatively --sqlite or --pgsql may be used + + +*-d or --sqlite* may be used interchangeably. + + +26.4.1 CREATE AND DESTROY DATABASE +.................................. + +*--sqlite --createall* +initial step, creates required relations (tables, indexes) in existing +(sqlite) database (a database should be created manually and given the same +name as working directory, as requested) (rb.dbi) + + +*sisu -d --createdb* +creates database where no database existed before + + +*sisu -d --create* +creates database tables where no database tables existed before + + +*sisu -d --dropall* +destroys database (including all its content)! kills data and drops tables, +indexes and database associated with a given directory (and directories of the +same name). + + +*sisu -d --recreate* +destroys existing database and builds a new empty database structure + + +26.4.2 IMPORT AND REMOVE DOCUMENTS +.................................. + +*sisu -d --import -v [filename/wildcard]* +populates database with the contents of the file. Imports documents(s) +specified to an sqlite database (at an object level). + + +*sisu -d --update -v [filename/wildcard]* +updates file contents in database + + +*sisu -d --remove -v [filename/wildcard]* +removes specified document from sqlite database. + + +27. INTRODUCTION +---------------- + +27.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) +.............................................................................. + +Sample search frontend [link:] [^62] A small +database and sample query front-end (search from) that makes use of the +citation system, _object citation numbering_ to demonstrates +functionality.[^63] + + +- [62]: + +- [63]: (which could be extended further with current back-end). As regards scaling + of the database, it is as scalable as the database (here Postgresql) and + hardware allow. + +*SiSU* can provide information on which documents are matched and at what +locations within each document the matches are found. These results are +relevant across all outputs using object citation numbering, which includes +html, XML, LaTeX, PDF and indeed the SQL database. You can then refer to one of +the other outputs or in the SQL database expand the text within the matched +objects (paragraphs) in the documents matched. + + +Note you may set results either for documents matched and object number +locations within each matched document meeting the search criteria; or display +the names of the documents matched along with the objects (paragraphs) that +meet the search criteria.[^64] + + +- [64]: of this feature when demonstrated to an IBM software innovations evaluator + in 2004 he said to paraphrase: this could be of interest to us. We have large + document management systems, you can search hundreds of thousands of documents + and we can tell you which documents meet your search criteria, but there is no + way we can tell you without opening each document where within each your + matches are found. + +*sisu -F --webserv-webrick* +builds a cgi web search frontend for the database created + + +The following is feedback on the setup on a machine provided by the help +command: + + + sisu --help sql + + + + Postgresql + user: ralph + current db set: SiSU_sisu + port: 5432 + dbi connect: DBI:Pg:database=SiSU_sisu;port=5432 + sqlite + current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db + dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db + +Note on databases built + + +By default, [unless otherwise specified] databases are built on a directory +basis, from collections of documents within that directory. The name of the +directory you choose to work from is used as the database name, i.e. if you are +working in a directory called /home/ralph/ebook the database SiSU_ebook is +used. [otherwise a manual mapping for the collection is necessary] + + +27.2 SEARCH FORM +................ + +*sisu -F* +generates a sample search form, which must be copied to the web-server cgi +directory + + +*sisu -F --webserv-webrick* +generates a sample search form for use with the webrick server, which must be +copied to the web-server cgi directory + + +*sisu -Fv* +as above, and provides some information on setting up hyperestraier + + +*sisu -W* +starts the webrick server which should be available wherever sisu is properly +installed + + +The generated search form must be copied manually to the webserver directory as +instructed + + +28. HYPERESTRAIER +----------------- + +See the documentation for hyperestraier: + + + + + + /usr/share/doc/hyperestraier/index.html + + + man estcmd + + +on sisu_hyperestraier: + + + man sisu_hyperestraier + + + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + + +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + + +(A) to generate the index within the webserver directory to be indexed: + + + estcmd gather -sd [index name] [directory path to index] + + +the following are examples that will need to be tailored according to your +needs: + + + cd /home/ralph/sisu_www + + + estcmd gather -sd casket /home/ralph/sisu_www + + +you may use the 'find' command together with 'egrep' to limit indexing to +particular document collection directories within the web server directory: + + + find /home/ralph/sisu_www -type f | egrep + '/home/ralph/sisu_www/sisu/.+?.html$' |estcmd gather -sd casket - + + +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + + +As sisu duplicates output in multiple file formats, it it is probably +preferable to limit the estraier index to html output, and as it may also be +desirable to exclude files 'plain.txt', 'toc.html' and 'concordance.html', as +these duplicate information held in other html output e.g. + + + find /home/ralph/sisu_www -type f | egrep + '/sisu_www/(sisu|bookmarks)/.+?.html$' | egrep -v '(doc|concordance).html$' + |estcmd gather -sd casket - + + +from your current document preparation/markup directory, you would construct a +rune along the following lines: + + + find /home/ralph/sisu_www -type f | egrep '/home/ralph/sisu_www/([specify + first directory for inclusion]|[specify second directory for + inclusion]|[another directory for inclusion? ...])/.+?.html$' | egrep -v + '(doc|concordance).html$' |estcmd gather -sd /home/ralph/sisu_www/casket - + + +(B) to set up the search form + + +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + + + sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin + + + sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi + + + sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin + + + [see estraier documentation for paths] + + +(ii) edit estseek.conf, with attention to the lines starting 'indexname:' and +'replace:': + + + indexname: /home/ralph/sisu_www/casket + + + replace: ^file:///home/ralph/sisu_www{!} [link:] http://localhost + + + replace: /index.html?${{!}}/ + + +(C) to test using webrick, start webrick: + + + sisu -W + + +and try open the url: + + +29. SISU_WEBRICK +---------------- + +29.1 NAME +......... + +*SiSU* - Structured information, Serialized Units - a document publishing +system + + +29.2 SYNOPSIS +............. + +sisu_webrick [port] + + +or + + +sisu -W [port] + + +29.3 DESCRIPTION +................ + +sisu_webrick is part of *SiSU* (man sisu) sisu_webrick starts *Ruby*'s Webrick +web-server and points it to the directories to which *SiSU* output is written, +providing a list of these directories (assuming *SiSU* is in use and they +exist). + + +The default port for sisu_webrick is set to 8081, this may be modified in the +yaml file: ~/.sisu/sisurc.yml a sample of which is provided as +/etc/sisu/sisurc.yml (or in the equivalent directory on your system). + + +29.4 SUMMARY OF MAN PAGE +........................ + +sisu_webrick, may be started on it's own with the command: sisu_webrick [port] +or using the sisu command with the -W flag: sisu -W [port] + + +where no port is given and settings are unchanged the default port is 8081 + + +29.5 DOCUMENT PROCESSING COMMAND FLAGS +...................................... + +sisu -W [port] starts *Ruby* Webrick web-server, serving *SiSU* output +directories, on the port provided, or if no port is provided and the defaults +have not been changed in ~/.sisu/sisurc.yaml then on port 8081 + + +29.6 FURTHER INFORMATION +........................ + +For more information on *SiSU* see: + + +or man sisu + + +29.7 AUTHOR +........... + +Ralph Amissah or + + +29.8 SEE ALSO +............. + + sisu(1) + + + sisu_vim(7) + + + sisu(8) + + +30. REMOTE SOURCE DOCUMENTS +--------------------------- + +*SiSU* processing instructions can be run against remote source documents by +providing the url of the documents against which the processing instructions +are to be carried out. The remote *SiSU* documents can either be sisu marked up +files in plaintext .sst or .ssm or; zipped sisu files, sisupod.zip or +filename.ssp + + +*.sst / .ssm - sisu text files* + + +*SiSU* can be run against source text files on a remote machine, provide the +processing instruction and the url. The source file and any associated parts +(such as images) will be downloaded and generated locally. + + + + sisu -3 http://[provide url to valid .sst or .ssm file] + +Any of the source documents in the sisu examples page can be used in this way, +see and use the url for the desired +document. + + +NOTE: to set up a remote machine to serve *SiSU* documents in this way, images +should be in the directory relative to the document source ../_sisu/image + + +*sisupod - zipped sisu files* + + +A sisupod is the zipped content of a sisu marked up text or texts and any other +associated parts to the document such as images. + + +*SiSU* can be run against a sisupod on a (local or) remote machine, provide the +processing instruction and the url, the sisupod will be downloaded and the +documents it contains generated locally. + + + + sisu -3 http://[provide url to valid sisupod.zip or .ssp file] + +Any of the source documents in the sisu examples page can be used in this way, +see and use the url for the desired +document. + + +REMOTE DOCUMENT OUTPUT +====================== + +31. REMOTE OUTPUT +----------------- + +Once properly configured *SiSU* output can be automatically posted once +generated to a designated remote machine using either rsync, or scp. + + +In order to do this some ssh authentication agent and keychain or similar tool +will need to be configured. Once that is done the placement on a remote host +can be done seamlessly with the -r (for scp) or -R (for rsync) flag, which may +be used in conjunction with other processing flags, e.g. + + + + sisu -3R sisu_remote.sst + +31.1 COMMANDS +............. + +*-R [filename/wildcard] * +copies sisu output files to remote host using rsync. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Note the behavior of rsync +different if -R is used with other flags from if used alone. Alone the rsync +--delete parameter is sent, useful for cleaning the remote directory (when -R +is used together with other flags, it is not). Also see -r + + +*-r [filename/wildcard] * +copies sisu output files to remote host using scp. This requires that +sisurc.yml has been provided with information on hostname and username, and +that you have your "keys" and ssh agent in place. Also see -R + + +31.2 CONFIGURATION +.................. + +[expand on the setting up of an ssh-agent / keychain] + + +32. REMOTE SERVERS +------------------ + +As *SiSU* is generally operated using the command line, and works within a Unix +type environment, *SiSU* the program and all documents can just as easily be on +a remote server, to which you are logged on using a terminal, and commands and +operations would be pretty much the same as they would be on your local +machine. + + +33. DOWNLOAD SISU - LINUX/UNIX +------------------------------ + +SISU CURRENT VERSION - LINUX/UNIX +................................. + +SOURCE (TARBALL TAR.GZ) +....................... + +Download the latest version of *SiSU* (and *SiSU* markup samples):[^65] + + +- [65]: Breakage and Fixes Report + +- + +* sisu_0.58.3.orig.tar.gz (of 2007-09-05:36/3) [link:] + +[^66] + + +- [66]: + +- e9a20a06ffee8d633b8ce525017d89ba 1278987 + + cgi generated sample search form + + + order results on files of the same title, in multiple files (with different + filenames) + + + postgresql, character case sensitivity, control, on/off + + + tail decoration, gplv3 & sisu info + + + texinfo/info (pinfo) module starts to do something vaguely useful again [not + a much used module, testing required] + + + print XML rendition of document structure to screen -T + + + help on environment visited, sisu -V + + + sisurc.yml default, color set to true [apologies if this causes anyone any + inconvenience, it is configurable in sisurc.yml] + + + help and man pages, some work man(8) related + + + sisu-install (install ruby rant script renamed) and permissions set to + executable + + +* sisu-markup-samples_1.0.8.orig.tar.gz (of 2007-08-19:33/7 ) [link:] + +[^67] + + +- [67]: + +- 04ae2812617a4689666600a0fb32301f 3438571 + +For installation notes see + + +For changelogs see + + +tulva.png 425x339 "Tulva, by Leena Krohn" [link:] + [^68] + + +- [68]: Reproduced with the kind permission of author and artist Leena Krohn, + Tulva is from the work Sphinx or Robot + other works + available online include Tainaron + , these two works can be + found in the book sample section + + +GIT (SOURCE CONTROL MANAGEMENT) +............................... + +Git repository currently at: + + +* git clone git://sisudoc.org/git/sisu/ + + +* + + +DEBIAN +...... + +This section contains information on the latest *SiSU* release. For +installation notes see + + + +*SiSU* is updated fairly regularly in *Debian* testing and unstable, and should +be available therefrom. + + +To add this archive, should you still choose to do so, add the following lines +to your /etc/apt/sources.list + + + + deb http://www.jus.uio.no/sisu/archive unstable main non-free + deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +*Source* + + +* sisu_0.58.3.orig.tar.gz [link:] + +[^69] + + +- [69]: + +* sisu_0.58.3-1.diff.gz [link:] + +[^70] + + +- [70]: + +* sisu_0.58.3-1.dsc [link:] + [^71] + + +- [71]: + +- b8330f8b97a15e6eaecba8f2616acb10 606 sisu_0.58.3-1.dsc + +*Debs* + + +* sisu_0.58.3-1_all.deb [link:] + +[^72] + + +- [72]: + +- sisu, the base code, (the main package on which the others depend), without + any dependencies other than ruby (and for convenience the ruby webrick web + server), this generates a number of types of output on its own, other packages + provide additional functionality, and have their dependencies + +- Depends: ruby (>=1.8.2), libwebrick-ruby + +- Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, sisu-examples, vim-sisu, + librmagick-ruby, trang, tidy, libtidy, librexml-ruby, zip, unzip, openssl + +* sisu-complete_0.58.3-1_all.deb [link:] + +[^73] + + +- [73]: + +- a package that pulls in other packages to build the whole of sisu (excluding + sisu-examples) + +- Depends: ruby (>=1.8.2), sisu, sisu-pdf, sisu-postgresql, sisu-remote, + sisu-sqlite, vim-sisu + +- Recommends: sisu-examples + +* sisu-pdf_0.58.3-1_all.deb [link:] + +[^74] + + +- [74]: + +- dependencies used by sisu to produce pdf from LaTeX generated + +- Depends: sisu, tetex-bin, tetex-extra, latex-ucs + +- Suggests: evince, xpdf + +* sisu-postgresql_0.58.3-1_all.deb [link:] + +[^75] + + +- [75]: + +- dependencies used by sisu to populate postgresql database (further + configuration is necessary) + +- Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby + +- Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1 + +* sisu-sqlite_0.58.3-1_all.deb [link:] + +[^76] + + +- [76]: + +- dependencies used by sisu to populate sqlite database + +- Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby + +- Suggests: libdbd-sqlite + +For changelogs see: + + + + + + + + +*non-free* + + +Book markup samples have been moved to non-free as the substantive text of the +documents are available under the author or original publisher's license, and +usually do not comply with the *Debian* Free Software Guidelines. + + +* sisu-markup-samples_1.0.8-1_all.deb [link:] + +[^77] + + +- [77]: + +- marked up documents and other examples related to sisu, a larger package + containing a number of texts + +- Depends: sisu + +* sisu-markup-samples_1.0.8-1.dsc [link:] + +[^78] + + +- [78]: + +- ca03c11467097d6049c43c54d0961ef5 606 sisu-markup-samples_1.0.8-1.dsc + +For changelogs see: + + + + + + + + +RPM +... + +The RPM is generated from the source file using Alien.[^79] Dependencies are +not handled, not even that of the essential *Ruby*. + + +- [79]: + +* sisu_0.58.3.orig-1-2.noarch.rpm [link:] + [^80] + + +- [80]: + +- 31f5cd3e0e577b418e7c98492f71f0af + +- untested, created using: alien -r sisu_0.58.3.orig.tar.gz + +* sisu-0.58.3-2.noarch.rpm [link:] + [^81] + + +- [81]: + +- 8b6858f0117351ce441e8559bf5308be + +- untested, created using: alien -r sisu_0.58.3-1_all.deb + +* sisu-markup-samples_1.0.8.orig-2.noarch.rpm [link:] + +[^82] + + +- [82]: + +- 15eed830b4d004f011bafe831bb816da + +- untested, created using alien + +sudo rpm -i [package name] + + +INSTALLATION +============ + +34. INSTALLATION +---------------- + +See the download pages [link:] [^83] +for information related to installation. + + +- [83]: + +- + +34.1 DEBIAN +........... + +*SiSU* is developed on *Debian*, and packages are available for *Debian* that +take care of the dependencies encountered on installation. + + +The package is divided into the following components: + + + *sisu*, the base code, (the main package on which the others depend), without + any dependencies other than ruby (and for convenience the ruby webrick web + server), this generates a number of types of output on its own, other + packages provide additional functionality, and have their dependencies + + + *sisu-complete*, a dummy package that installs the whole of greater sisu as + described below, apart from sisu-examples + + + *sisu-pdf*, dependencies used by sisu to produce pdf from LaTeX generated + + + *sisu-postgresql*, dependencies used by sisu to populate postgresql database + (further configuration is necessary) + + + *sisu-remote*, dependencies used to place sisu output on a remote server + (further configuration is necessary) + + + *sisu-sqlite*, dependencies used by sisu to populate sqlite database + + + *sisu-markup-samples*, sisu markup samples and other miscellany (under + *Debian* Free Software Guidelines non-free) + + +*SiSU* is available off Debian Unstable and Testing [link:] + +[^84] install it using apt-get, aptitude or alternative *Debian* install tools. +*SiSU* is currently comprised of eight packages. + + +- [84]: + +Initial packaging is done here and to get the latest version of *SiSU* +available you may add the following line(s) to your sources list: + + + + #/etc/apt/sources.list + deb http://www.jus.uio.no/sisu/archive unstable main non-free + deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +The non-free section is for sisu markup samples provided, which contain +authored works the substantive text of which cannot be changed, and which as a +result do not meet the debian free software guidelines. + + +On *Debian* there is little more to know beyond how to install software on +*Debian* using apt, aptitude or synaptic. + + + + #Using aptitude: + aptitude update + aptitude install sisu-complete sisu-markup-samples + + + Using apt-get + apt-get update + apt get install sisu-complete sisu-examples + +34.2 OTHER UNIX / LINUX +....................... + +A source tarball or an rpms built using alien are available, (however +dependencies have not been tested). *SiSU* is first packaged and tested with +dependency handling for *Debian*. [^85] Information on dependencies configured +for *Debian* is provided as this may be of assistance. + + +- [85]: Notes on dependencies are provided in the section that follows + +34.2.1 SOURCE TARBALL +..................... + +*installation with provided install script* + + +To install *SiSU*, in the root directory of the unpacked *SiSU* _as root +type_:[^86] + + +- [86]: This makes use of rant and the provided Rantfile. Note however, that + additional external package dependencies, such as tetex-extra are not taken + care of for you. + + ruby install + + +Once installed see man 8 sisu for information on additional programs that sisu +makes use of. + + +Further notes on install script. + + +The install script is prepared using Rant, and a Rantfile is provided,~87 a +Rantfile has been configured to do post installation setup +<1bede24251bacbf84169330dc9850c56>}~ with more comprehensive install options, +and post install and setup configuration and generation of first test file, if +you have installed Stefan Lang's { Rant [link:] +[^88] installed. While in the package directory, type: rant help, or rant -T, +or to install *SiSU* _as root_, type: + + +- [88]: http://make.rubyforge.org/ + +- + +*install* is an install script prepared using Stefan Lang's Rant [link:] + [^89] It should work whether you have previously +installed Rant or not. It has fairly comprehensive install options, and can do +some post install and setup configuration and generation of first test file. +For options type: + + +- [89]: http://make.rubyforge.org/ + +- + + ruby install -T + + +To install as root type: + + + ruby install + + +For a minimal install type: + + + ruby install base + + +*installation with setup.rb* + + +setup.rb [link:] [^90] is provided +the package and will install *SiSU*[^91] installation is a 3 step process[^92] +the following string assumes you are in the package directory and that you have +root as sudo: + + +- [90]: + +- [91]: Minero Aoki + +- + +- [92]: Installation instructions + +- + + ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install + + +*installation of rpm* + + +The RPM is generated from the source file using Alien.[^93] Dependencies are +not handled, not even that of the essential *Ruby*. + + +- [93]: + +35. SISU COMPONENTS, DEPENDENCIES AND NOTES +------------------------------------------- + +The dependency lists are from the *Debian* control file for *SiSU* version +0.36, and may assist in building *SiSU* on other distributions. + + +35.1 SISU +......... + +* the base code, (the main package on which the others depend), without any +dependencies other than ruby (and for convenience the ruby webrick web server), +this generates a number of types of output on its own, other packages provide +additional functionality, and have their dependencies + + +*Depends:* on ruby (>=1.8.2), libwebrick-ruby + + +*Recommends:* sisu-pdf, sisu-sqlite, sisu-postgresql, sisu-examples, +librmagick-ruby, trang, tidy, libtidy, librexml-ruby, zip, unzip, openssl + + +initialise directory + + + sisu -CC + + +html + + + sisu -hv [filename/wildcard] + + + sisu -Hv [filename/wildcard] + + +LaTeX (but sisu-pdf dependencies required to convert that to pdf) + + + sisu -pv [filename/wildcard] + + +plain text Unix with footnotes + + + sisu -av [filename/wildcard] + + +plain text Dos with footnotes + + + sisu -Av [filename/wildcard] + + +plain text Unix with endnotes + + + sisu -ev [filename/wildcard] + + +plain text Dos with endnotes + + + sisu -Ev [filename/wildcard] + + +openoffice odt + + + sisu -ov [filename/wildcard] + + +xhtml + + + sisu -bv [filename/wildcard] + + +XML SAX + + + sisu -xv [filename/wildcard] + + +XML DOM + + + sisu -Xv [filename/wildcard] + + +wordmap (a rudimentary index of content) + + + sisu -wv [filename/wildcard] + + +document content certificate + + + sisu -Nv [filename/wildcard] + + +placement of sourcefile in output directory + + + sisu -sv [filename/wildcard] + + +creation of source tarball with images, and placement of source tarball in +ouput directory + + + sisu -Sv [filename/wildcard] + + +manifest of output produced (polls output directory and provides links to +existing output) + + + sisu -yv [filename/wildcard] + + +url for output files -u -U + + + sisu -uv[and other flags] [filename/wildcard] + + + sisu -Uv [filename/wildcard] + + +toggle screen colour + + + sisu -cv[and processing flags] [filename/wildcard] + + +verbose mode + + + sisu -v[and processing flags] [filename/wildcard] + + + sisu -V[and processing flags] [filename/wildcard] + + +quiet mode + + + sisu -q[and processing flags] [filename/wildcard] + + +maintenance mode, intermediate files kept -M + + + sisu -Mv[and other flags] [filename/wildcard] + + +[the -v is for verbose] + + +start the webrick server + + + sisu -W + + +35.2 SISU-COMPLETE +.................. + +* a dummy package that installs the whole *SiSU*, apart from sisu-examples + + +*Depends:* ruby (>=1.8.2), sisu, sisu-pdf, sisu-postgresql, sisu-remote, +sisu-sqlite + + +*Recommends:* sisu-examples + + +35.3 SISU-EXAMPLES +.................. + +* installs sisu markup samples and other miscelleny + + +*Depends:* sisu + + +35.4 SISU-PDF +............. + +* dependencies used by sisu to produce pdf from LaTeX generated + + +*Depends:* sisu, tetex-bin, tetex-extra, latex-ucs + + +*Suggests:* evince, xpdf + + +converts sisu LaTeX produced to pdf + + + sisu -pv [filename/wildcard] + + +[the -v is for verbose] + + +35.5 SISU-POSTGRESQL +.................... + +* dependencies used by sisu to populate postgresql database (further +configuration is necessary) + + +*Depends:* sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby + + +*Suggests:* pgaccess, libdbd-pgsql, postgresql-contrib-8.1 + + +installs dependencies for sisu to work with and populate postgresql database + + +create database + + + sisu -Dv createall + + +drop database + + + sisu -Dv dropall + + +import content + + + sisu -Div [filename/wildcard] + + + sisu -Dv import [filename/wildcard] + + +update content + + + sisu -Duv [filename/wildcard] + + + sisu -Dv update [filename/wildcard] + + +[the -v is for verbose] + + +The following are available without installation of the sisu-postgresql +component, but are of interest in this context + + +generate a sample database query form for use with webserver on port 80 + + + sisu -F + + +or for use with webrick server + + + sisu -F webrick + + +to start webrick server + + + sisu -W + + +35.6 SISU-REMOTE +................ + +* dependencies used to place sisu output on a remote server (further +configuration is necessary) + + +scp + + + sisu -vr[and processing flags] [filename/wildcard] + + +rsync + + + sisu -vR[and processing flags] [filename/wildcard] + + +[the -v is for verbose] + + +*Depends:* sisu, rsync, openssh-client|lsh-client, keychain + + +35.7 SISU-SQLITE +................ + +* dependencies used by sisu to populate sqlite database + + +*Depends:* sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby + + +*Suggests:* libdbd-sqlite + + +installs dependencies for sisu to work with and populate sqlite database + + +create database + + + sisu -dv createall + + +drop database + + + sisu -dv dropall + + +update content + + + sisu -div [filename/wildcard] + + + sisu -dv import [filename/wildcard] + + +update content + + + sisu -duv [filename/wildcard] + + + sisu -dv update [filename/wildcard] + + +[the -v is for verbose] + + +The following are available without installation of the sisu-sqlite component, +but are of interest in this context + + +generate a sample database query form for use with webserver on port 80 + + + sisu -F + + +or for use with webrick server + + + sisu -F webrick + + +to start webrick server + + + sisu -W + + +36. QUICKSTART - GETTING STARTED HOWTO +-------------------------------------- + +36.1 INSTALLATION +................. + +Installation is currently most straightforward and tested on the *Debian* +platform, as there are packages for the installation of sisu and all +requirements for what it does. + + +36.1.1 DEBIAN INSTALLATION +.......................... + +*SiSU* is available directly from the *Debian* Sid and testing archives (and +possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: + + + + aptitude update + aptitude install sisu-complete + +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + + + #/etc/apt/sources.list + deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib + deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib + d + +The aptitude commands become: + + + + aptitude update + aptitude install sisu-complete sisu-markup-samples + +If there are newer versions of *SiSU* upstream of the *Debian* archives, they +will be available by adding the following to your /etc/apt/sources.list + + + + #/etc/apt/sources.list + deb http://www.jus.uio.no/sisu/archive unstable main non-free + deb-src http://www.jus.uio.no/sisu/archive unstable main non-free + +repeat the aptitude commands + + + + aptitude update + aptitude install sisu-complete sisu-markup-samples + +Note however that it is not necessary to install sisu-complete if not all +components of sisu are to be used. Installing just the package sisu will +provide basic functionality. + + +36.1.2 RPM INSTALLATION +....................... + +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + + +They may be downloaded from: + + + + + +as root type: + + + rpm -i [rpm package name] + + +36.1.3 INSTALLATION FROM SOURCE +............................... + +To install *SiSU* from source check information at: + + + + + +* download the source package + + +* Unpack the source + + +Two alternative modes of installation from source are provided, setup.rb (by +Minero Aoki) and a rant(by Stefan Lang) built install file, in either case: the +first steps are the same, download and unpack the source file: + + +For basic use *SiSU* is only dependent on the programming language in which it +is written *Ruby*, and *SiSU* will be able to generate html, various XMLs, +including ODF (and will also produce LaTeX). Dependencies required for further +actions, though it relies on the installation of additional dependencies which +the source tarball does not take care of, for things like using a database +(postgresql or sqlite)[^94] or converting LaTeX to pdf. + + +- [94]: There is nothing to stop MySQL support being added in future. + +*setup.rb* + + +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked *SiSU* as root type: + + + + ruby setup.rb config + ruby setup.rb setup + #[and as root:] + ruby setup.rb install + +further information on setup.rb is available from: + + + + + + + + +*"install"* + + +The "install" file provided is an installer prepared using "rant". In the root +directory of the unpacked *SiSU* as root type: + + + ruby install base + + +or for a more complete installation: + + + ruby install + + +or + + + ruby install base + + +This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been +configured to do post installation setup setup configuration and generation of +first test file. Note however, that additional external package dependencies, +such as tetex-extra are not taken care of for you. + + +Further information on "rant" is available from: + + + + + + + + +For a list of alternative actions you may type: + + + ruby install help + + + ruby install -T + + +36.2 TESTING SISU, GENERATING OUTPUT +.................................... + +To check which version of sisu is installed: + + +sisu -v + + +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + + +... + + +or + + +... + + +change directory to the appropriate one: + + +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + + +36.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF +............................................ + +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + +sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + + +36.2.2 LATEX / PDF +.................. + +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu-pdf in *Debian*) + + +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + + +sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +should generate most available output formats: html including a concordance +file, opendocument text format, plaintext, XHTML and various forms of XML, and +OpenDocument text and pdf + + +36.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE +............................................... + +Relational databases need some setting up - you must have permission to create +the database and write to it when you run sisu. + + +Assuming you have the database installed and the requisite permissions + + +sisu --sqlite --recreate + + +sisu --sqlite -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +sisu --pgsql --recreate + + +sisu --pgsql -v --import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +36.3 GETTING HELP +................. + +36.3.1 THE MAN PAGES +.................... + +Type: + + + man sisu + + +The man pages are also available online, though not always kept as up to date +as within the package itself: + + +* sisu.1 [link:] [^95] + + +- [95]: + +* sisu.8 [link:] [^96] + + +- [96]: + +* man directory [link:] [^97] + + +- [97]: + +36.3.2 BUILT IN HELP +.................... + +sisu --help + + +sisu --help --env + + +sisu --help --commands + + +sisu --help --markup + + +36.3.3 THE HOME PAGE +.................... + + + + + + + +36.4 MARKUP SAMPLES +................... + +A number of markup samples (along with output) are available off: + + + + + +Additional markup samples are packaged separately in the file: + + +*** + + +On *Debian* they are available in non-free[^98] to include them it is necessary +to include non-free in your /etc/apt/source.list or obtain them from the sisu +home site. + + +- [98]: the *Debian* Free Software guidelines require that everything distributed + within *Debian* can be changed - and the documents are authors' works that + while freely distributable are not freely changeable. + +HOWTO +===== + +37. GETTING HELP +---------------- + +An online manual of sorts should be available at: + + + + + +The manual pages provided with *SiSU* are also available online, and there is +an interactive help, which is being superseded by the man page, and possibly +some document which contains this component. + + +37.1 SISU "MAN" PAGES +..................... + +If *SiSU* is installed on your system usual man commands should be available, +try: + + +man sisu + + +The *SiSU* man pages can be viewed online at:[^99] + + +- [99]: generated from source using rman + +- + +- With regard to *SiSU* man pages the formatting generated for markup syntax is + not quite right, for that you might prefer the links under: + +- + +An online version of the sisu man page is available here: + + +* various sisu man pages [link:] [^100] + + +- [100]: + +* sisu.1 [link:] [^101] + + +- [101]: + +* sisu.8 [link:] [^102] + + +- [102]: + +* sisu_examples.1 [link:] +[^103] + + +- [103]: + +* sisu_webrick.1 [link:] +[^104] + + +- [104]: + +37.2 SISU BUILT-IN HELP +....................... + + sisu --help + + + sisu --help [subject] + + + sisu --help env [for feedback on the way your system is setup with regard + to sisu] + + + sisu -V [same as above command] + + + sisu --help commands + + + sisu --help markup + + +37.3 COMMAND LINE WITH FLAGS - BATCH PROCESSING +............................................... + +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. + + +In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst" +or "sisu -h *.{sst,ssm}" to produce html version of all documents. + + +38. SETUP, INITIALISATION +------------------------- + +38.1 INITIALISE OUTPUT DIRECTORY +................................ + +Images, css files for a document directory are copied to their respective +locations in the output directory. + + +while within your document markup/preparation directory, issue the following +command + + + sisu -CC + + +38.1.1 USE OF SEARCH FUNCTIONALITY, AN EXAMPLE USING SQLITE +........................................................... + +*SiSU* can populate PostgreSQL and Sqlite databases and provides a sample +search form for querying these databases. + + +This note provides an example to get you started and will use sqlite + + +It is necessary to: + + +(1) make sure the required dependencies have been installed + + +(2) have a directory with sisu markup samples that is writable + + +(3) use sisu to create a database + + +(4) use sisu tp populate a database + + +(5) use sisu to start the webrick (httpd) server + + +(6) use sisu to create a search form + + +(7) copy the search form to the cgi directory + + +(8) open up the form in your browser + + +(9) query the database using the search form + + +*(1) make sure the required dependencies have been installed* + + +if you use *Debian*, the following command will install the required +dependencies + + +aptitude install sisu-sqlite + + +*(2) have a directory with sisu markup samples that is writable* + + +ideally copy the sisu-examples directory to your home directory (because the +directory in which you run this example should be writable) + + +cp -rv /usr/share/sisu-examples/sample/document_samples_sisu_markup ~/. + + +*(3) use sisu to create an sqlite database* + + +within the sisu-examples directory + + +sisu -dv createall + + +*(4) use sisu tp populate a database with some text* + + +within the sisu-examples directory + + +sisu -div free_*.sst + + +or + + +sisu -dv import free_*.sst debian_constitution_v1.2.sst +debian_social_contract_v1.1.sst gpl2.fsf.sst + + +*(5) use sisu to start the webrick (httpd) server (if it has not already been +started):* + + +sisu -W + + +*(6) use sisu to create a search form (for use with the webrick server, and +your sample documents)* + + +within the sisu-examples directory + + +sisu -F webrick + + +#here i run into a problem, you are working from a read only #directory..., not +my usual mode of operation, to complete the example #the following is necessary +sudo touch sisu_sqlite.cgi sisu_pgsql.cgi sudo -P chown $USER sisu_sqlite.cgi +sisu_pgsql.cgi + + +#now this should be possible: sisu -F webrick + + +*(7) copy the search form to the cgi directory* + + +the string should be provided as output from the previous command + + +sudo cp -vi +/usr/share/sisu-examples/sample/document_samples_sisu_markup/sisu_sqlite.cgi +/usr/lib/cgi-bin + + +sudo chmod -v 755 /usr/lib/cgi-bin/sisu_sqlite.cgi + + +*(8) open up the form in your browser and query it* + + +url: + + + + + +or as instructed by command sisu -F webrick + + +*(9) query the database using the search form* + + +if there are other options in the dropdown menu select + + +document_samples_sisu_markup + + +and search for some text, e.g.: + + +aim OR project + + +* selecting the *index* radio button gives an index of results using the object +numbers + + +* selecting the *text* radio button gives the content of the matched paragraphs +with the match highlighted + + +*(10) to start again with a new database* + + +to start from scratch you can drop the database with the command + + +sisu -dv dropall + + +and go to step 3 + + +to get to step 3 in one step with a single command + + +sisu -dv recreate + + +continue subsequent steps + + +38.2 MISC +......... + +38.2.1 URL FOR OUTPUT FILES -U -U +................................. + + sisu -uv[and other flags] [filename/wildcard] + + + sisu -Uv [filename/wildcard] + + +38.2.2 TOGGLE SCREEN COLOR +.......................... + + sisu -cv[and processing flags] [filename/wildcard] + + +38.2.3 VERBOSE MODE +................... + + sisu -v[and processing flags] [filename/wildcard] + + + sisu -V[and processing flags] [filename/wildcard] + + +38.2.4 QUIET MODE +................. + + sisu -q[and processing flags] [filename/wildcard] + + +38.2.5 MAINTENANCE MODE INTERMEDIATE FILES KEPT -M +.................................................. + + sisu -Mv[and other flags] [filename/wildcard] + + +38.2.6 START THE WEBRICK SERVER +............................... + + sisu -W + + +38.3 REMOTE PLACEMENT OF OUTPUT +............................... + +configuration is necessary + + +scp + + + sisu -vr[and processing flags] [filename/wildcard] + + +rsync + + + sisu -vR[and processing flags] [filename/wildcard] + + +39. CONFIGURATION FILES +----------------------- + +Sample provided, on untarring the source tarball: + + + conf/sisu/sisurc.yaml + + +and on installation under: + + + /etc/sisu/sisurc.yaml + + +The following paths are searched: + + + ./_sisu/sisurc.yaml + + + ~/.sisu/sisurc.yaml + + + ./etc/sisu/sisurc.yaml + + +40. MARKUP +---------- + +See sample markup provided on + + + + + + + + + + + +in particular for each of the document output samples provided, the source +document is provided as well + + + + + +on untarring the source tarball: + + + data/sisu-examples/sample/document_samples_sisu_markup/ + + +or the same once source is installed (or sisu-examples) under: + + + /usr/share/sisu-examples/sample/document_samples_sisu_markup/ + + +Some notes are contained within the man page, *man sisu* and within sisu help +via the commands *sisu help markup* and *sisu help headers* + + +*SiSU* is for literary and legal text, also for some social science material. +In particular it does not do formula, and is not particularly suited to +technical documentation. Despite the latter caveat, some notes will be provided +here and added to over time: + + +40.1 HEADERS +............ + +Headers @headername: provide information related to the document, this may +relate to + + +1. how it is to be processed, such as whether headings are to be numbered, what +skin is to be used and markup instructions, such as the document structure, or +words to be made bold within the document + + +2. semantic information about the document including the dublin core + + +40.2 FONT FACE +.............. + +Defaults are set. You may change the face to: bold, italics, underscore, +strikethrough, ... + + +40.2.1 BOLD +........... + +\@bold: [list of words that should be made bold within document] + + +*bold line* + + +!_ bold line + + +* bold word or sentence * + + +!{ bold word or sentence }! + + +*{ bold word or sentence }* + + +*boldword* or *boldword* + + +*boldword* or !boldword! + + +40.2.2 ITALICS +.............. + +\@italics: [list of words that should be italicised within document] + + +/ italicise word or sentence / + + +/{ italicise word or sentence }/ + + +/italicisedword/ + + +/italicisedword/ + + +40.2.3 UNDERSCORE +................. + +_ underscore word or sentence _ + + +_{ underscore word or sentence }_ + + +_underscoreword_ + + +40.2.4 STRIKETHROUGH +.................... + + strikethrough word or sentence + + +-{ strikethrough word or sentence }- + + +strikeword + + +-strikeword- + + +40.3 ENDNOTES +............. + +There are two forms of markup for endnotes, they cannot be mixed within the +same document + + +here[^105] + + +- [105]: this is an endnote + +1. preferred endnote markup + + +here~{ this is an endnote }~ + + +2. alternative markup equivalent, kept because it is possible to search and +replace to get markup in existing texts such as Project Gutenberg + + +here~^ + + +^~ this is an endote + + +40.4 LINKS +.......... + +SiSU [link:] + + +{ *SiSU* }http://sisudoc.org + + +sisu.png 120x39 [link:] + + +{sisu.png }http://sisudoc.org + + +tux.png 64x80 [link:] image + + +{ tux.png 64x80 }image + + +SiSU [link:] [^106] + + +- [106]: + +{ *SiSU* }http://sisudoc.org + + +is equivalent to: + + +{ *SiSU* }http://sisudoc.org ~{ }~ + + +the same can be done with an image: + + +sisu.png 120x39 "SiSU" [link:] [^108] + + +- [108]: + +{ sisu.png "*SiSU*" }http://sisudoc.org + + +40.5 NUMBER TITLES +.................. + +Set with the header @markup: + + +40.6 LINE OPERATIONS +.................... + +Line Operations (marker placed at start of line) + + +!_ bold line + + +*bold line* + + +_1 indent paragraph one level + + + indent paragraph one level + + +_2 indent paragraph two steps + + + indent paragraph two steps + + +_* bullet paragraph + + +* bullet paragraph + + +# number paragraph (see headers for numbering document headings) + + +1. number paragraph (see headers for numbering document headings) + + +_# number paragraph level 2 (see headers for numbering document headings) + + + a. number paragraph level 2 (see headers for numbering document headings) + + +40.7 TABLES +........... + +Table markup sample + + + +table{~h c3; 26; 32; 32; + + +This is a table, column1 +this would become row one of column two +column three of row one is here + + +column one row 2 +column two of row two +column three of row two, and so on + + +column one row three +and so on +here + + +}table + +Alternative form of table markup + + + + {t\~h} + |Mon|Tue|Wed|Thu|Fri|Sat|Sun + 0 | * | * | * | * | * | * | * + 1 | * | * | * | * | | | + 2 | - | * | * | * | * | * | + 3 | - | * | * | * | * | * | * + 4 | - | | | * | * | * | + 5 | * | * | * | * | * | * | * + +40.8 GROUPED TEXT +................. + + + 5.times { puts 'Ruby' } + +code{ + + + + 5.times { puts 'Ruby' } + +}code + + + +A Limerick + + +There was a young lady from Clyde, +who ate a green apple and died, +but the apple fermented inside the lamented, +and made cider inside her inside. + + +poem{ + + +There was a young lady from Clyde, +who ate a green apple and died, +but the apple fermented inside the lamented, +and made cider inside her inside. + + +}\poem + +40.9 COMPOSITE DOCUMENT +....................... + +To import another document, the master document or importing document should be +named filename.r3 (r for require) + + +<< { filename.sst } + + +<< { filename.ssi } + + +41. CHANGE APPEARANCE +--------------------- + +41.1 SKINS +.......... + +"Skins" may be used to change various aspects related to the output documents +appearance, including such things as the url for the home page on which the +material will be published, information on the credit band, and for html +documents colours and icons used in navigation bars. Skins are ruby files which +permit changing of the default values set within the program for *SiSU* output. + + +There are a few examples provided, on untarring the source tarball: + + + conf/sisu/skin/doc/ + + + data/sisu-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + + +and on installation under: + + + /etc/sisu/skin/doc/ + + + /usr/share/sisu-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + + +The following paths are searched: + + + ./_sisu/skin + + + ~/.sisu/skin + + + /etc/sisu/skin + + +Skins under the searched paths in a per document directory, a per directory +directory, or a site directory, named: + + +doc [may be specified individually in each document] + + +dir [used if identifier part of name matches markup directory name] + + +site + + +It is usual to place all skins in the document directory, with symbolic links +as required from dir or site directories. + + +41.2 CSS +........ + +The appearance of html and XML related output can be changed for an ouput +collection directory by prepareing and placing a new css file in one of the +sisu css directories searched in the sisu configuration path. These are located +at: + + +_./_sisu/css + + +~/.sisu/css + + +and + + +/etc/sisu/css + + +The contents of the first directory found in the search path are copied to the +corresponding sisu output directory with the commnd: + + +sisu -CC + + +The *SiSU* standard css files for *SiSU* output are: + + +dom.css html.css html_tables.css index.css sax.css xhtml.css + + +A document may specify its own/bespoke css file using the css header. + + +\@css: + + +[expand] + + +EXTRACTS FROM THE README +======================== + +42. README +---------- + +*SiSU* 0.55 2007w27/6 2007-07-07 + + +Homepage: + + +*Description* + + +*SiSU* is lightweight markup based document creation and publishing framework +that is controlled from the command line. Prepare documents for *SiSU* using +your text editor of choice, then use *SiSU* to generate various output document +formats. + + +With minimal preparation of a plain-text (UTF-8) file using its native +markup-syntax, *SiSU* produces: plain-text, HTML, XHTML, XML, ODF:ODT +(Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL or +SQLite) in paragraph sized chunks so that document searches are done at this +"atomic" level of granularity. + + +Outputs share a common citation numbering system, and any semantic meta-data +provided about the document. + + +*SiSU* also provides concordance files, document content certificates and +manifests of generated output. + + +*SiSU* takes advantage of well established open standard ways of representing +text, and provides a bridge to take advantage of the strengths of each, while +remaining simple. *SiSU* implements across document formats a "useful common +feature set" [coming from a humanities, law, and possibly social sciences +perspective, rather than technical or scientific writing] ... focus is +primarily on content and data integrity rather than appearance, (though outputs +in the various formats are respectable). + + +A vim syntax highlighting file and an ftplugin with folds for sisu markup is +provided. Vim 7 includes syntax highlighting for *SiSU*. + + +man pages, and interactive help are provided. + + +Dependencies for various features are taken care of in sisu related packages. +The package sisu-complete installs the whole of *SiSU*. + + +Additional document markup samples are provided in the package +sisu-markup-samples which is found in the non-free archive the licenses for the +substantive content of the marked up documents provided is that provided by the +author or original publisher. + + +Homepage: + + +*SiSU* - simple information structuring universe, is a publishing tool, +document generation and management, (and search enabling) tool primarily for +literary, academic and legal published works. + + +*SiSU* can be used for Internet, Intranet, local filesystem or cd publishing. + + +*SiSU* can be used directly off the filesystem, or from a database. + + +*SiSU*'s scalability, is be dependent on your hardware, and filesystem (in my +case Reiserfs), and/or database Postgresql. + + +Amongst it's characteristics are: + + +* simple mnemonoic markup style, + + +* the ability to produce multiple output formats, including html, structured +XML, LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining +document structure - Postgresql and Sqlite, + + +* that all share a common citation system (a simple idea from which much good), +possibly most exciting, the following: if fed into a relational database (as it +can be automatically), the document set is searchable, with results displayed +at a paragraph level, or the possibility of an indexed display of documents in +which the match is found together with a hyperlinked listing for each of each +paragraph in which the match is found. In any event citations using this system +(with or without the relational database) are relevant for all output formats. + + +* it is command line driven, and can be set up on a remote server + + +* Documents are marked up in *SiSU* syntax in your favourite editor. *SiSU* +syntax may be regarded as a type of smart ascii - which in its basic form is +simpler than the most elementary html. There is currently a syntax highlighter, +and folding for Vim. Syntax highlighters for other editors are welcome. + + +Input files should be UTF-8 + + +Once set up it is simple to use. + + +42.1 ONLINE INFORMATION, PLACES TO LOOK +....................................... + + + + +Download Sources: + + + + + + + + +42.2 INSTALLATION +................. + +NB. Platform is Unix / Linux. + + +42.2.1 DEBIAN +............. + +If you use *Debian* use the *Debian* packages, check the information at: + + + + + +(A) *SiSU* is available directly off the *Debian* archives for Sid and testing. +It should necessary only to run as root: + + + aptitude update + + + aptitude install sisu-complete + + +(B) If there are newer versions of *SiSU* upstream of the *Debian* archives, +they will be available by adding the following to your /etc/apt/sources.list + + + deb unstable main non-free + + + deb-src unstable main non-free + + +[the non-free line is for document markup samples, for which the substantive +text is provided under the author or original publisher's license and which in +most cases will not be debian free software guideline compliant] + + +Then as root run: + + + aptitude update + + + aptitude install sisu-complete + + +42.2.2 RPM +.......... + +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + + +They may be downloaded from: + + + + + +42.2.3 SOURCE PACKAGE .TGZ +.......................... + +Otherwise to install *SiSU* from source, check information at: + + + + + +alternative modes of installation from source are provided, setup.rb (by Minero +Aoki), rake (by Jim Weirich) built install file, rant (by Stefan Lang) built +install file, + + +*Ruby* is the essential dependency for the basic operation of *SiSU* + + +1. Download the latest source (information available) from: + + + + + +2. Unpack the source + + +Note however, that additional external package dependencies, such as texlive or +postgresql should you desire to use it are not taken care of for you. + + +42.2.4 TO USE SETUP.RB +...................... + +this is a three step process, in the root directory of the unpacked *SiSU* as +root type: + + + ruby setup.rb config + + + ruby setup.rb setup + + +as root: + + + ruby setup.rb install + + +further information: + + + + + + + + +42.2.5 TO USE INSTALL (PRAPARED WITH "RAKE") +............................................ + +Rake must be installed on your system: + + + + + + + + +in the root directory of the unpacked *SiSU* as root type: + + + rake + + +or + + + rake base + + +This makes use of Rake (by Jim Weirich) and the provided Rakefile + + +For a list of alternative actions you may type: + + + rake help + + + rake -T + + +42.2.6 TO USE INSTALL (PRAPARED WITH "RANT") +............................................ + +(you may use the instructions above for rake substituting rant if rant is +installed on your system, or you may use an independent installer created using +rant as follows:) + + +in the root directory of the unpacked *SiSU* as root type: + + + ruby ./sisu-install + + +or + + + ruby ./sisu-install base + + +This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been +configured to do post installation setup setup configuration and generation of +first test file. Note however, that additional external package dependencies, +such as tetex-extra are not taken care of for you. + + +further information: + + + + + + + + +For a list of alternative actions you may type: + + + ruby ./sisu-install help + + + ruby ./sisu-install -T + + +42.3 DEPENDENCIES +................. + +Once installed see 'man 8 sisu' for some information on additional programs +that sisu makes use of, and that you may need or wish to install. (this will +depend on such factors as whether you want to generate pdf, whether you will be +using *SiSU* with or without a database, ...) 'man sisu_markup-samples' may +also be of interest if the sisu-markup-samples package has also been installed. + + +The information in man 8 may not be most up to date, and it is possible that +more useful information can be gleaned from the following notes taken from the +*Debian* control file (end edited), gives an idea of additional packages that +*SiSU* can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by *SiSU*). + + +The following is from the debian/control file of sisu-0.58.2, which amongst +other things provides the dependencies of sisu within *Debian*. + + + + Package: sisu + Architecture: all + Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip + Conflicts: vim-sisu, sisu-vim, sisu-remote + Replaces: vim-sisu, sisu-vim + Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang, + tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain, + hyperestraier, kdissert, vim-addon-manager + Suggests: rcs | cvs, lv, texinfo, pinfo + Package: sisu-complete + Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite + Recommends: hyperestraier + Package: sisu-pdf + Architecture: all + Depends: sisu, texlive-latex-base, texlive-fonts-recommended, + texlive-latex-recommended, texlive-latex-extra + Suggests: evince, xpdf + Package: sisu-postgresql + Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby + Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1 + Package: sisu-sqlite + Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby + Suggests: libdbd-sqlite + Package: sisu-markup-samples + Depends: sisu + + + Source: sisu + Section: text + Priority: optional + Maintainer: Ralph Amissah + Build-Depends: debhelper (>= 5) + Standards-Version: 3.7.2 + Package: sisu + Architecture: all + Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip + Conflicts: vim-sisu, sisu-vim, sisu-remote + Replaces: vim-sisu, sisu-vim + Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, hyperestraier, keychain, librmagick-ruby, librexml-ruby, openssl, openssh-client | lsh-client, rsync, tidy, vim-addon-manager + Suggests: kdissert, lv, rcs | cvs, pinfo, texinfo, trang + Description: documents - structuring, publishing in multiple formats and search + SiSU is a lightweight markup based, command line oriented, document + structuring, publishing and search framework for document collections. + . + With minimal preparation of a plain-text, (UTF-8) file, using its native + markup syntax in your text editor of choice, SiSU can generate various + document formats (most of which share a common object numbering system for + locating content), including plain text, HTML, XHTML, XML, OpenDocument text + (ODF:ODT), LaTeX, PDF files, and populate an SQL database with objects + (roughly paragraph-sized chunks) so searches may be performed and matches + returned with that degree of granularity: your search criteria is met by these + documents and at these locations within each document. Object numbering is + particularly suitable for "published" works (finalized texts as opposed to + works that are frequently changed or updated) for which it provides a fixed + means of reference of content. Document outputs also share semantic meta-data + provided. + . + SiSU also provides concordance files, document content certificates and + manifests of generated output. + . + A vim syntax highlighting file and an ftplugin with folds for sisu markup is + provided, as are syntax highlighting files for kate, kwrite, gedit and + diakonos. Vim 7 includes syntax highlighting for SiSU. + . + man pages, and interactive help are provided. + . + Dependencies for various features are taken care of in sisu related packages. + The package sisu-complete installs the whole of SiSU. + . + Additional document markup samples are provided in the package + sisu-markup-samples which is found in the non-free archive the licenses for + the substantive content of the marked up documents provided is that provided + by the author or original publisher. + . + Homepage: + + + Package: sisu-complete + Architecture: all + Depends: ruby (>= 1.8.2), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite + Recommends: hyperestraier + Description: installs all SiSU related packages + This package installs SiSU and related packages that enable sisu to produce + pdf and to populate postgresql and sqlite databases. + . + SiSU is a lightweight markup based document publishing framework. + . + See sisu for a description of the package. + . + Homepage: + + + Package: sisu-pdf + Architecture: all + Depends: sisu, texlive-latex-base, texlive-fonts-recommended, texlive-latex-recommended, texlive-latex-extra + #Suggests: evince, xpdf + Description: dependencies to convert SiSU LaTeX output to pdf + This package enables the conversion of SiSU LaTeX output to pdf. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: + + + Package: sisu-postgresql + Architecture: all + Depends: sisu, libdbd-pg-ruby, libdbi-ruby, libdbm-ruby, postgresql + Recommends: libfcgi-ruby + Suggests: postgresql-contrib + Description: SiSU dependencies for use with postgresql database + This package enables SiSU to populate a postgresql database. This is done at + an object/paragraph level, making granular searches of documents possible. + . + This relational database feature of SiSU is not required but provides + interesting possibilities, including that of granular searches of documents + for matching units of text, primarily paragraphs that can be displayed or + identified by object citation number, from which an index of documents + matched and each matched paragraph within them can be displayed. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: + + + Package: sisu-sqlite + Architecture: all + Depends: sisu, sqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby + Recommends: libfcgi-ruby + Description: SiSU dependencies for use with sqlite database + This package enables SiSU to populate an sqlite database. This is done at an + object/paragraph level, making granular searches of documents possible. + . + This relational database feature of SiSU is not required but provides + interesting possibilities, including that of granular searches of documents + for matching units of text, primarily paragraphs that can be displayed or + identified by object citation number, from which an index of documents + matched and each matched paragraph within them can be displayed. + . + SiSU is a lightweight markup based document publishing framework. + . + Homepage: + +42.4 QUICK START +................ + +Most of the installation should be taken care of by the aptitude or rant +install. (The rant install if run in full will also test run the generation of +the first document). + + +After installation of sisu-complete, move to the document samples directory + + + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + + +and run + + + sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +or the same: + + + sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +look at output results, see the "sisu_manifest" page created for the document + + +or to generate an online document move to a writable directory, as the file +will be downloaded there and e.g. + + +sisu -3 + + + +the database stuff is extra perhaps, the latex stuff could be considered extra +perhaps but neither needs to be installed for most of sisu output to work + + +examine source document, vim has syntax support + + +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +additional markup samples in + + + + + +For help + + + man sisu + + +or + + + sisu --help + + +e.g. + + +for the way sisu "sees/maps" your system + + + sisu --help env + + +for list of commands and so on + + + sisu --help commands + + +42.5 CONFIGURATION FILES +........................ + +The default configuration/setup is contained within the program and is altered +by configuration settings in /etc/[sisu version]/sisurc.yml or in +~/.sisu/sisurc.yml + + +* configuration file - a yaml file + + + /etc/sisu/[sisu version]/sisurc.yml + + + ~/.sisu/sisurc.yml + + +* directory structure - setting up of output and working directory. + + +* skins - changing the appearance of a project, directory or individual +documents within ~/.sisu/skin + + + ~/.sisu/skin/doc contains individual skins, with symbolic links from + + + ~/.sisu/skin/dir if the contents of a directory are to take a particular + document skin. + + +* additional software - eg. Tex and LaTeX (tetex, tetex-base, tetex-extra on +*Debian*), Postgresql, [sqlite], trang, tidy, makeinfo, ... none of which are +required for basic html or XML processing. + + +* if you use Vim as editor there is a syntax highlighter and fold resource +config file for *SiSU*. I hope more syntax highlighters follow. + + +There are post installation steps (which are really part of the overall +installation) + + +sisu -C in your marked up document directory, should do some auto-configuring +provided you have the right permissions for the output directories. (and +provided the output directories have already been specified if you are not +using the defaults). + + +42.6 USE GENERAL OVERVIEW +......................... + +Documents are marked up in *SiSU* syntax and kept in an ordinary text editable +file, named with the suffix .sst, or .ssm + + +Marked up *SiSU* documents are usually kept in a sub-directory of your choosing + + +use the interactive help and man pages + + + sisu --help + + + man sisu + + +42.7 HELP +......... + +interactive help described below, or man page: + + + man sisu + + + man 8 sisu + + +'man sisu_markup-samples' [if the sisu-markup-samples package is also +installed] + + +Once installed an interactive help is available typing 'sisu' (without) any +flags, and select an option: + + + sisu + + +alternatively, you could type e.g. + + + sisu --help commands + + + sisu --help env + + + sisu --help headers + + + sisu --help markup + + + sisu --help headings + + +etc. + + +for questions about mappings, output paths etc. + + + sisu --help env + + + sisu --help path + + + sisu --help directory + + +42.8 DIRECTORY STRUCTURE +........................ + +Once installed, type: + + + sisu --help env + + +or + + + sisu -V + + +42.9 CONFIGURATION FILE +....................... + +The defaults can be changed via *SiSU*'s configure file sisurc.yml which the +program expects to find in ./_sisu ~/.sisu or /etc/sisu (searched in that +order, stopping on the first one found) + + +42.10 MARKUP +............ + +See man pages. + + + man sisu + + + man 8 sisu + + +Once installed there is some information on *SiSU* Markup in its help: + + + sisu --help markup + + +and + + + sisu --help headers + + +Sample marked up document are provided with the download tarball in the +directory: + + + ./data/doc/sisu/sisu_markup_samples/dfsg + + +These are installed on the system usually at: + + + /usr/share/doc/sisu/sisu_markup_samples/dfsg + + +More markup samples are available in the package sisu-markup-samples + + + + + +Many more are available online off: + + + + + +42.11 ADDITIONAL THINGS +....................... + +There is syntax support for some editors provided (together with a README file) +in + + + ./data/sisu/conf/syntax + + +usually installed to: + + + /usr/share/sisu/conf/syntax + + +42.12 LICENSE +............. + +License: GPL 3 or later see the copyright file in + + + ./data/doc/sisu + + +usually installed to: + + + /usr/share/doc/sisu + + +42.13 SISU STANDARD +................... + +*SiSU* uses: + + +* Standard *SiSU* markup syntax, + + +* Standard *SiSU* meta-markup syntax, and the + + +* Standard *SiSU* object citation numbering and system + + +© Ralph Amissah 1997, current 2006 All Rights Reserved. + + +* however note the License section + + +CHANGELOG + + + ./CHANGELOG + + +and see + + + + + + + + +EXTRACTS FROM MAN 8 SISU +======================== + +43. POST INSTALLATION SETUP +--------------------------- + +43.1 POST INSTALLATION SETUP - QUICK START +.......................................... + +After installation of sisu-complete, move to the document samples directory, + + + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + + +[this is not where you would normally work but provides sample documents for +testing, you may prefer instead to copy the contents of that directory to a +local directory before proceeding] + + +and in that directory, initialise the output directory with the command + + + sisu -CC + + +then run: + + + sisu -1 free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +or the same: + + + sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +look at output results, see the "sisu_manifest" page created for the document + + +for an overview of your current sisu setup, type: + + + sisu --help env + + +or + + + sisu -V + + +To generate a document from a remote url accessible location move to a writable +directory, (create a work directory and cd into it) as the file will be +downloaded there and e.g. + + + sisu -1 + + + sisu -3 + + + +examine source document, vim has syntax highlighting support + + +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + + +additional markup samples in + + + + + +it should also be possible to run sisu against sisupods (prepared zip files, +created by running the command sisu -S [filename]), whether stored locally or +remotely. + + + sisu -3 + + +there is a security issue associated with the running of document skins that +are not your own, so these are turned of by default, and the use of the +following command, which switches on the associated skin is not recommended: + + + sisu -3 --trust + + + +For help + + + man sisu + + + sisu --help + + + sisu --help env for the way sisu "sees/maps" your system + + + sisu --help commands for list of commands and so on + + +43.2 DOCUMENT MARKUP DIRECTORY +.............................. + +Perhaps the easiest way to begin is to create a directory for sisu marked up +documents within your home directory, and copy the file structure (and document +samples) provided in the document sample directory: + + + mkdir ~/sisu_test + + + cd ~/sisu_test + + + cp -a /usr/share/doc/sisu/sisu_markup_samples/dfsg/* ~/sisu_test/. + + +*Tip:* the markup syntax examples may be of interest + + + + + +*Tip:* + + + sisu -U [sisu markup filename] + + +should printout the different possible outputs and where sisu would place them. + + +*Tip:* if you want to toggle ansi color add + + + c + + +to your flags. + + +43.2.1 CONFIGURATION FILES +.......................... + +*SiSU* configuration file search path is: + + + ./_sisu/sisurc.yaml + + + ~/.sisu/sisurc.yaml + + + /etc/sisu/sisurc.yaml + + +.\"%% *Debian* Installation Note + + +43.2.2 DEBIAN INSTALLATION NOTE +............................... + +It is best you see + + + + + +for up the most up to date information. + + +notes taken from the *Debian* control file (end edited), gives an idea of +additional packages that *SiSU* can make use of if available, (the +use/requirement of some of which are interdependent for specific actions by +*SiSU*): + + +Package: sisu + + +*SiSU* is a lightweight markup based, command line oriented, document +structuring, publishing and search framework for document collections. + + +With minimal preparation of a plain-text, (UTF-8) file, using its native markup +syntax in your text editor of choice, *SiSU* can generate various document +formats (most of which share a common object numbering system for locating +content), including plain text, HTML, XHTML, XML, OpenDocument text (ODF:ODT), +LaTeX, PDF files, and populate an SQL database with objects (roughly +paragraph-sized chunks) so searches may be performed and matches returned with +that degree of granularity: your search criteria is met by these documents and +at these locations within each document. Object numbering is particularly +suitable for "published" works (finalized texts as opposed to works that are +frequently changed or updated) for which it provides a fixed means of reference +of content. Document outputs also share semantic meta-data provided. + + +*SiSU* also provides concordance files, document content certificates and +manifests of generated output. + + +A vim syntax highlighting file and an ftplugin with folds for sisu markup is +provided, as are syntax highlighting files for kate, kwrite, gedit and +diakonos. Vim 7 includes syntax highlighting for *SiSU*. + + +man pages, and interactive help are provided. + + +Dependencies for various features are taken care of in sisu related packages. +The package sisu-complete installs the whole of *SiSU*. + + +Additional document markup samples are provided in the package +sisu-markup-samples which is found in the non-free archive the licenses for the +substantive content of the marked up documents provided is that provided by the +author or original publisher. + + +Homepage: + + +43.2.3 DOCUMENT RESOURCE CONFIGURATION +...................................... + +*sisu* resource configuration information is obtained from sources (where they +exist): + + + ~/.sisu/sisurc.yaml + + + /etc/sisu/[sisu version]/sisurc.yaml + + + sisu program defaults + + +43.2.4 SKINS +............ + +*Skins* default document appearance may be modified using skins contained in +sub-directories located at the following paths: + + + ./_sisu/skin + + + ~/.sisu/skin + + + /etc/sisu/skin + + +more specifically, the following locations (or their /etc/sisu equivalent) +should be used: + + + ~/.sisu/skin/doc + + +skins for individual documents; + + + ~/.sisu/skin/dir + + +skins for directories of matching names; + + + ~/.sisu/skin/site + + +site-wide skin modifying the site-wide appearance of documents. + + +Usually all skin files are placed in the document skin directory: + + + ~/.sisu/skin/doc + + +with softlinks being made to the skins contained there from other skin +directories as required. + + +44. FAQ - FREQUENTLY ASKED/ANSWERED QUESTIONS +--------------------------------------------- + +44.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. + + +44.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 + + +44.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 + + +44.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. + + +44.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] + + +44.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. + + +44.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; + + +44.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,[^110] LaTeX/pdf and opendocument is in place. XML, +and plaintext are in order. + + +- [110]: 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. + + +45. EDITOR FILES, SYNTAX HIGHLIGHTING +------------------------------------- + +The directory: + + + ./data/sisu/conf/editor-syntax-etc/ + + + /usr/share/sisu/conf/editor-syntax-etc + + +contains rudimentary sisu syntax highlighting files for: + + +* (g)vim + + + package: sisu-vim + + +status: largely done + + + there is a vim syntax highlighting and folds component + + +* gedit + + +* gobby + + + file: sisu.lang + + +place in: + + + /usr/share/gtksourceview-1.0/language-specs + + +or + + + ~/.gnome2/gtksourceview-1.0/language-specs + + + status: very basic syntax highlighting + + + comments: this editor features display line wrap and is used by Goby! + + +* nano + + + file: nanorc + + +save as: + + + ~/.nanorc + + + status: basic syntax highlighting + + + comments: assumes dark background; no display line-wrap; does line breaks + + +* diakonos (an editor written in ruby) + + +file: diakonos.conf + + +save as: + + + ~/.diakonos/diakonos.conf + + +includes: + + + status: basic syntax highlighting + + +comments: assumes dark background; no display line-wrap + + +* kate & kwrite + + + file: sisu.xml + + + place in: + + + /usr/share/apps/katepart/syntax + + + or + + + ~/.kde/share/apps/katepart/syntax + + + [settings::configure kate::{highlighting,filetypes}] + + + [tools::highlighting::{markup,scripts}::*SiSU*] + + +* nedit + + + file: sisu_nedit.pats + + + nedit -import sisu_nedit.pats + + + status: a very clumsy first attempt [not really done] + + + comments: this editor features display line wrap + + +* emacs + + + files: sisu-mode.el + + + to file ~/.emacs add the following 2 lines: + + + (add-to-list 'load-path "/usr/share/sisu-examples/config/syntax_hi") + + + (require 'sisu-mode.el) + + + [not done / not yet included] + + +* vim & gvim + + + files: + + + package is the most comprehensive sisu syntax highlighting and editor + environment provided to date (is for vim/ gvim, and is separate from the + contents of this directory) + + + status: this includes: syntax highlighting; vim folds; some error checking + + + comments: this editor features display line wrap + + +NOTE: + + +[*SiSU* parses files with long lines or line breaks, but, display linewrap +(without line-breaks) is a convenient editor feature to have for sisu markup] + + +46. HELP SOURCES +---------------- + +For a summary of alternative ways to get help on *SiSU* try one of the +following: + + +*man page* + + + man sisu_help + + +*man2html* + + + + + + + + +*sisu generated output - links to html* + + + + + + + + + + + +*help sources lists* + + +Alternative sources for this help sources page listed here: + + + man sisu_help_sources + + + + + + + + + + + + + + +46.1 MAN PAGES +.............. + +46.1.1 MAN +.......... + + man sisu + + + man sisu_commands + + + man 7 sisu_complete + + + man sisu_configuration + + + man 8 sisu_faq + + + man sisu_filetypes + + + man sisu_help + + + man sisu_help_sources + + + man 8 sisu_howto + + + man sisu_introduction + + + man sisu_markup + + + man sisu_output_overview + + + man 7 sisu_pdf + + + man 7 sisu_postgresql + + + man 8 sisu_quickstart + + + man 8 sisu_remote + + + man 8 sisu_search + + + man sisu_skin + + + man 7 sisu_sqlite + + + man 8 sisu_syntax_highlighting + + + man 7 sisu_vim + + + man sisu_webrick + + +46.2 SISU GENERATED OUTPUT - LINKS TO HTML +.......................................... + +Note *SiSU* documentation is prepared in *SiSU* and output is available in +multiple formats including amongst others html, pdf, and odf which may be also +be accessed via the html pages[^111] + + +- [111]: named index.html or more extensively through sisu_manifest.html + +46.2.1 LOCALLY INSTALLED +........................ + + + + + + + + + + + /usr/share/doc/sisu/sisu_manual/sisu/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_description/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_help/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_search/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + + + /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html + + +46.2.2 WWW.SISUDOC.ORG +...................... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +46.2.3 WWW.JUS.UIO.NO/SISU +.......................... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +46.2.4 MAN2HTML +............... + +46.2.5 LOCALLY INSTALLED +........................ + + + + + + + + + + + /usr/share/doc/sisu/html/sisu.1.html + + + /usr/share/doc/sisu/html/sisu_commands.1.html + + + /usr/share/doc/sisu/html/sisu_complete.7.html + + + /usr/share/doc/sisu/html/sisu_configuration.1.html + + + /usr/share/doc/sisu/html/sisu_faq.8.html + + + /usr/share/doc/sisu/html/sisu_help.1.html + + + /usr/share/doc/sisu/html/sisu_help_sources.1.html + + + /usr/share/doc/sisu/html/sisu_howto.8.html + + + /usr/share/doc/sisu/html/sisu_markup.1.html + + + /usr/share/doc/sisu/html/sisu_pdf.7.html + + + /usr/share/doc/sisu/html/sisu_postgresql.7.html + + + /usr/share/doc/sisu/html/sisu_quickstart.8.html + + + /usr/share/doc/sisu/html/sisu_remote.8.html + + + /usr/share/doc/sisu/html/sisu_search.8.html + + + /usr/share/doc/sisu/html/sisu_skin.1.html + + + /usr/share/doc/sisu/html/sisu_sqlite.7.html + + + /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html + + + /usr/share/doc/sisu/html/sisu_vim.7.html + + + /usr/share/doc/sisu/html/sisu_webrick.1.html + + +46.2.6 WWW.SISUDOC.ORG +...................... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +46.2.7 WWW.JUS.UIO.NO/SISU +.......................... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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 - Manual [0.58]_ + + +DC Creator: _Ralph Amissah_ + + +DC Rights: _Copyright (C) Ralph Amissah 2007, part of SiSU documentation, +License GPL 3_ + + +DC Type: _information_ + + +DC Date created: _2002-08-28_ + + +DC Date issued: _2002-08-28_ + + +DC Date available: _2002-08-28_ + + +DC Date modified: _2007-08-30_ + + +DC Date: _2007-08-30_ + + +*Version Information* + + +Sourcefile: _sisu_manual._sst_ + + +Filetype: _SiSU text insert 0.58_ + + +Sourcefile Digest, MD5(sisu_manual._sst)= _1f10457d4314dc96550b6c8ded413878_ + + +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:10:57 +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 - Manual [0.58] + + 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: 2002-08-28 + + date.issued: 2002-08-28 + + date.available: 2002-08-28 + + date.modified: 2007-08-30 + + date: 2007-08-30 + + + + + +============================================================================== +nil + +Other versions of this document: +manifest: + http://www.jus.uio.no/sisu/sisu_manual/sisu_manifest.html +html: + http://www.jus.uio.no/sisu/sisu_manual/toc.html +pdf: + http://www.jus.uio.no/sisu/sisu_manual/portrait.pdf + http://www.jus.uio.no/sisu/sisu_manual/landscape.pdf +plaintext (plain text): + http://www.jus.uio.no/sisu/sisu_manual/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:47 +0100 2007 +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3