From 50d45c6deb0afd2e4222d2e33a45487a9d1fa676 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 23 Sep 2007 05:16:21 +0100 Subject: primarily todo with sisu documentation, changelog reproduced below: * start documenting sisu using sisu * sisu markup source files in data/doc/sisu/sisu_markup_samples/sisu_manual/ /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/ * default output [sisu -3] in data/doc/manuals_generated/sisu_manual/ /usr/share/doc/manuals_generated/sisu_manual/ (adds substantially to the size of sisu package!) * help related edits * manpage, work on ability to generate manpages, improved * param, exclude footnote mark count when occurs within code block * plaintext changes made * shared_txt, line wrap visited * file:// link option introduced (in addition to existing https?:// and ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and hub] * minor adjustments * html url match refinement * css added tiny_center * plaintext * endnotes fix * footnote adjustment to make more easily distinguishable from substantive text * flag -a only [flags -A -e -E dropped] controlled by modifiers --unix/msdos --footnote/endnote * defaults, homepage * renamed homepage (instead of index) implications for modifying skins, which need likewise to have any homepage entry renamed * added link to sisu_manual in homepage * css the css for the default homepage is renamed homepage.css (instead of index.css) [consider removing this and relying on html.css] * ruby version < ruby1.9 * place stop on installation and working with for now [ruby String.strip broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux], 2007-09-18:38/2] * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * debian * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9 * sisu-doc new sub-package for sisu documentation debian/control and sisu-doc.install --- data/doc/manuals_generated/sisu_manual/man/sisu.1 | 5042 ++++++++++++++++++++ .../sisu_manual/man/sisu_commands.1 | 575 +++ .../sisu_manual/man/sisu_complete.1 | 181 + .../sisu_manual/man/sisu_complete.7 | 181 + .../sisu_manual/man/sisu_configuration.1 | 368 ++ .../manuals_generated/sisu_manual/man/sisu_faq.1 | 404 ++ .../manuals_generated/sisu_manual/man/sisu_faq.8 | 404 ++ .../sisu_manual/man/sisu_filetypes.1 | 387 ++ .../manuals_generated/sisu_manual/man/sisu_help.1 | 318 ++ .../sisu_manual/man/sisu_help_sources.1 | 729 +++ .../manuals_generated/sisu_manual/man/sisu_howto.1 | 2283 +++++++++ .../manuals_generated/sisu_manual/man/sisu_howto.8 | 2283 +++++++++ .../sisu_manual/man/sisu_introduction.1 | 504 ++ .../sisu_manual/man/sisu_markup.1 | 1532 ++++++ .../sisu_manual/man/sisu_output_overview.1 | 164 + .../manuals_generated/sisu_manual/man/sisu_pdf.1 | 216 + .../manuals_generated/sisu_manual/man/sisu_pdf.7 | 216 + .../sisu_manual/man/sisu_postgresql.1 | 223 + .../sisu_manual/man/sisu_postgresql.7 | 223 + .../sisu_manual/man/sisu_quickstart.1 | 517 ++ .../sisu_manual/man/sisu_quickstart.8 | 517 ++ .../sisu_manual/man/sisu_remote.1 | 251 + .../sisu_manual/man/sisu_remote.8 | 251 + .../sisu_manual/man/sisu_search.1 | 639 +++ .../sisu_manual/man/sisu_search.8 | 639 +++ .../manuals_generated/sisu_manual/man/sisu_skin.1 | 222 + .../sisu_manual/man/sisu_sqlite.1 | 222 + .../sisu_manual/man/sisu_sqlite.7 | 222 + .../sisu_manual/man/sisu_syntax_highlighting.1 | 307 ++ .../sisu_manual/man/sisu_syntax_highlighting.8 | 307 ++ .../manuals_generated/sisu_manual/man/sisu_vim.1 | 196 + .../manuals_generated/sisu_manual/man/sisu_vim.7 | 196 + .../sisu_manual/man/sisu_webrick.1 | 218 + 33 files changed, 20937 insertions(+) create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_commands.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_complete.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_complete.7 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_configuration.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_faq.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_faq.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_help.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_help_sources.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_howto.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_howto.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_introduction.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_markup.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_output_overview.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_pdf.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_pdf.7 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.7 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_remote.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_remote.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_search.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_search.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_skin.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.7 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.8 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_vim.1 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_vim.7 create mode 100644 data/doc/manuals_generated/sisu_manual/man/sisu_webrick.1 (limited to 'data/doc/manuals_generated/sisu_manual/man') diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu.1 b/data/doc/manuals_generated/sisu_manual/man/sisu.1 new file mode 100644 index 00000000..8da9be45 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu.1 @@ -0,0 +1,5042 @@ +.TH "sisu" "1" "2007-08-30" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- MANUAL \ [0.58], +RALPH AMISSAH +.BR + +.SH +WHAT IS SISU? +.BR + +.SH +1. INTRODUCTION \- WHAT IS SISU? +.BR + +.BR +.B SiSU +is a system for document markup, publishing (in multiple open standard +formats) and search + +.BR +.B 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. + +.BR +.B 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. + +.BR +.B SiSU +both defines a markup syntax and provides an engine that produces open +standards format outputs from documents prepared with +.B 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 +.B 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. +.B 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. + +.BR +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 +.B SiSU +markup applied to a document, +.B 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. + +.BR +In preparing a +.B 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. + +.BR +.B 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 +.B 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. + +.BR +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. +.B SiSU +provides the flexibility of outputing documents in multiple non\-proprietary +open formats including html, pdf[^7] and the ISO standard ODF.[^8] Whilst +.B 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 +.B SiSU +can be migrated to other document formats. Further security is provided by +the fact that the software itself, +.B 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. +.B 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). + +.BR +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. + +.BR +.B 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 +.B SiSU +offers great possibilities. + +.BR +.B SiSU +is primarily for published works, which can take advantage of the citation +system to reliably reference its documents. +.B 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 +.B SiSU +. + +.BR + + +.SH +2. HOW DOES SISU WORK? +.BR + +.BR +.B 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. +.B 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). + +.SH +3. SUMMARY OF FEATURES +.BR + +.BR +* 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. + +.BR +* 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]. + +.BR +* 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. +.B 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) + +.BR +* 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: + +.BR + * html \- both as a single scrollable text and a segmented document + +.BR + * xhtml + +.BR + * XML \- both in sax and dom style xml structures for further development as + required + +.BR + * ODF \- open document format, the iso standard for document storage + +.BR + * LaTeX \- used to generate pdf + +.BR + * pdf (via LaTeX) + +.BR + * sql \- population of an sql database, (at the same object level that is + used to cite text within a document) + +.BR +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)) + +.BR +* 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. + +.BR +* 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]. + +.BR +* 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 + +.BR +* SQL search aside, documents are generated as required and static once +generated. + +.BR +* 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) + +.BR +* document source (plaintext utf\-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + +.BR +* 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 + +.BR +* generated document outputs may automatically be posted to remote sites. + +.BR +* for basic document generation, the only software dependency is +.B 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. + +.BR +* as a developers tool it is flexible and extensible + +.BR +Syntax highlighting for +.B SiSU +markup is available for a number of text editors. + +.BR +.B 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 + +.BR +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)... + +.BR +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. + +.SH +4. HELP +.BR + +.SH +4.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +and (from +.B SiSU +0.59 onwards) installed locally at: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +or equivalent directory + +.BR +Within the +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.SH +4.2 SISU MAN PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR + man sisu + +.BR + man sisu_markup + +.BR + man sisu_commands + +.BR +Most +.B 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 +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.BR +Once installed, directory equivalent to: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +Available man pages are converted back to html using man2html: + +.BR + /usr/share/doc/sisu/html/ + +.BR + ./data/doc/sisu/html/ + +.BR +The +.B SiSU +man pages can be viewed online at:[^9] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^10] + +.BR +* sisu.1 \ [^11] + +.BR +* sisu.8 \ [^12] + +.BR +* sisu_examples.1 \ [^13] + +.BR +* sisu_webrick.1 \ [^14] + +.SH +4.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +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. + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR +Apart from real\-time information on your current configuration the +.B 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). + +.BR +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. + +.SH +4.4 HELP SOURCES + +.BR +For lists of alternative help sources, see: + +.BR +.B man page + +.BR + man sisu_help_sources + +.BR +.B man2html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR +.B sisu generated html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources/index.html + +.BR + + +.BR + + +.SH +5. COMMANDS SUMMARY +.BR + +.SH +5.1 SYNOPSIS + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.BR +sisu \ [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] \ [ \ filename/ \ +wildcard \ ] + +.BR +sisu \ [ \ \-Ddcv \ ] \ [ \ instruction \ ] + +.BR +sisu \ [ \ \-CcFLSVvW \ ] + +.BR +Note: commands should be issued from within the directory that contains the +marked up files, cd to markup directory. + +.SH +5.2 DESCRIPTION + +.BR +.B SiSU +.B 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: + +.SH +5.3 DOCUMENT PROCESSING COMMAND FLAGS + +.TP +.B \ \-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) + +.TP +.B \ \-b \ \ [filename/wildcard] +produces xhtml/XML output for browser viewing (sax parsing). + +.TP +.B \ \-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. + +.TP +.B \ \-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. \ + +.TP +.B \ \-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). + +.TP +.B \ \-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. + +.TP +.B \ \-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. + +.TP +.B \ \-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 + +.TP +.B \ \-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]. + +.TP +.B \ \-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]. + +.TP +.B \ \-I \ \ [filename/wildcard] +produces texinfo and info file, (view with pinfo). + +.TP +.B \ \-L +\ prints \ license \ information. \ + +.TP +.B \ \-M \ \ [filename/wildcard/url] +maintenance mode files created for processing preserved and their locations +indicated. (also see \-V) + +.TP +.B \ \-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 + +.TP +.B \ \-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. + +.TP +.B \ \-n \ \ [filename/wildcard/url] +skip meta\-markup (building of \"metaverse\"), this skips the equivalent of +\-m which is otherwise assumed by most processing flags. + +.TP +.B \ \-o \ \ [filename/wildcard/url] +output basic document in opendocument file format (opendocument.odt). + +.TP +.B \ \-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). + +.TP +.B \ \-q \ \ [filename/wildcard] +quiet less output to screen. + +.TP +.B \ \-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 + +.TP +.B \ \-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 + +.TP +.B \ \-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). + +.TP +.B \ \-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. +.B 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]. + +.TP +.B \ \-s \ \ [filename/wildcard] +copies sisu markup file to output directory. + +.TP +.B \ \-t \ \ [filename/wildcard \ (*.termsheet.rb)] +standard form document builder, preprocessing feature + +.TP +.B \ \-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 + +.TP +.B \ \-u \ \ [filename/wildcard] +provides url mapping of output files for the flags requested for processing, +also see \-U + +.TP +.B \ \-V +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ and \ environment \ information \ (sisu \ \-\-help \ env) \ + +.TP +.B \ \-V \ \ [filename/wildcard] +even more verbose than the \-v flag. (also see \-M) + +.TP +.B \ \-v +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ information \ + +.TP +.B \ \-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 + +.TP +.B \ \-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 \ ]. + +.TP +.B \ \-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) + +.TP +.B \ \-X \ \ [filename/wildcard] +produces XML output with deep document structure, in the nature of dom. + +.TP +.B \ \-x \ \ [filename/wildcard] +produces XML output shallow structure (sax parsing). + +.TP +.B \ \-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]) + +.TP +.B \ \-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. + +.TP +.B \ \-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. + +.TP +.B \ \-z \ \ [filename/wildcard] +produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \ +being] + +.SH +6. COMMAND LINE MODIFIERS +.BR + +.TP +.B \ \-\-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. + +.TP +.B \ \-\-no\-annotate +\ strips \ output \ text \ of \ editor \ endnotes[^*1] denoted by asterisk or +dagger/plus sign + +.TP +.B \ \-\-no\-asterisk +\ strips \ output \ text \ of \ editor \ endnotes[^*2] denoted by asterisk +sign + +.TP +.B \ \-\-no\-dagger +\ strips \ output \ text \ of \ editor \ endnotes[^+1] denoted by dagger/plus +sign + +.SH +7. DATABASE COMMANDS +.BR + +.BR +dbi \- database interface + +.BR +\-D or \-\-pgsql set for postgresql \-d or \-\-sqlite default set for sqlite +\-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)] + +.TP +.B \ \-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. + +.TP +.B \ \-Dv \ \-\-import +\ \ [filename/wildcard] imports data specified to postgresql db (rb.dbi) \ [ +\ \-dv \ \-\-import \ sqlite \ equivalent] + +.TP +.B \ \-Dv \ \-\-update +\ \ [filename/wildcard] updates/imports specified data to postgresql db +(rb.dbi) \ [ \ \-dv \ \-\-update \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-remove +\ \ [filename/wildcard] removes specified data to postgresql db (rb.dbi) \ [ +\ \-d \ \-\-remove \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-dropall +\ kills \ data\" \ and \ drops \ (postgresql \ or \ sqlite) \ db, \ tables \ +& \ indexes \ \ [ \ \-d \ \-\-dropall \ sqlite \ equivalent] + +.BR +The v in e.g. \-Dv is for verbose output. + +.SH +8. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +.BR + +.TP +.B \ \-\-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. + +.TP +.B \ \-0 \ to \ \-5 \ \ [filename \ or \ wildcard] +Default shorthand mappings (note that the defaults can be changed/configured +in the sisurc.yml file): + +.TP +.B \ \-0 +\ \-mNhwpAobxXyYv \ \ [this \ is \ the \ default \ action \ run \ when \ no \ +options \ are \ give, \ i.e. \ on \ \'sisu \ \ [filename]\'] + +.TP +.B \ \-1 +\ \-mNHwpy \ + +.TP +.B \ \-2 +\ \-mNHwpaoy \ + +.TP +.B \ \-3 +\ \-mNhwpAobxXyY \ + +.TP +.B \ \-4 +\ \-mNhwpAobxXDyY \ \-\-import \ + +.TP +.B \ \-5 +\ \-mNhwpAobxXDyY \ \-\-update \ + +.BR +add \-v for verbose mode and \-c for color, e.g. sisu \-2vc \ [filename \ or \ +wildcard] + +.BR +consider \-u for appended url info or \-v for verbose output + +.SH +8.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +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. + +.BR +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. + +.SH +9. INTRODUCTION TO SISU MARKUP[^15] +.BR + +.SH +9.1 SUMMARY + +.BR +.B SiSU +source documents are plaintext (UTF\-8)[^16] files + +.BR +All paragraphs are separated by an empty line. + +.BR +Markup is comprised of: + +.BR +* 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) + +.BR +* 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: + +.BR + * heading levels defines document structure + +.BR + * text basic attributes, italics, bold etc. + +.BR + * grouped text (objects), which are to be treated differently, such as code + blocks or poems. + +.BR + * footnotes/endnotes + +.BR + * linked text and images + +.BR + * paragraph actions, such as indent, bulleted, numbered\-lists, etc. + +.BR +Some interactive help on markup is available, by typing sisu and selecting +markup or sisu \-\-help markup + +.SH +9.2 MARKUP EXAMPLES + +.SH +9.2.1 ONLINE + +.BR +Online markup examples are available together with the respective outputs +produced from or from + + +.BR +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + + +.BR +Some example marked up files are available as html with syntax highlighting for +viewing: + +.BR +an alternative presentation of markup syntax: + + +.SH +9.2.2 INSTALLED + +.BR +With +.B 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 + +.SH +10. MARKUP OF HEADERS +.BR + +.BR +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. + +.BR +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: + + +.nf + % this would be a comment +.fi + +.SH +10.1 SAMPLE HEADER + +.BR +This current document has a header similar to this one (without the comments): + + +.nf + % 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 +.fi + +.SH +10.2 AVAILABLE HEADERS + +.BR +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 + +.BR +.B @indentifier: +information or instructions + +.BR +where the \"identifier\" is a tag recognised by the program, and the +\"information\" or \"instructions\" belong to the tag/indentifier specified + +.BR +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. + +.BR +This is a sample header + +.BR +.B % SiSU 0.38 +\ [declared \ file\-type \ identifier \ with \ markup \ version] + +.BR +.B @title: +\ [title \ text] This is the title of the document and used as such, this +header is the only one that is +.I mandatory + +.BR +.B @subtitle: +The Subtitle if any + +.BR +.B @creator: +\ [or \ @author:] Name of Author + +.BR +.B @subject: +(whatever your subject) + +.BR +.B @description: + +.BR +.B @publisher: + +.BR +.B @contributor: + +.BR +.B @translator: +\ [or \ @translated_by:] + +.BR +.B @illustrator: +\ [or \ @illustrated_by:] + +.BR +.B @prepared_by: +\ [or \ @digitized_by:] + +.BR +.B @date: 2000\-08\-27 +\ [ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid: +\ @date.modified: \ ] + +.BR +.B @type: article + +.BR +.B @format: + +.BR +.B @identifier: + +.BR +.B @source: + +.BR +.B @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.] + +.BR +[@language.original: \ original \ language \ in \ which \ the \ work \ was \ +published] + +.BR +.B @papersize: +(A4|US_letter|book_B5|book_A5|US_legal) + +.BR +.B @relation: + +.BR +.B @coverage: + +.BR +.B @rights: +Copyright (c) Name of Right Holder, all rights reserved, or as granted: +public domain, copyleft, creative commons variant, etc. + +.BR +.B @owner: + +.BR +.B @keywords: +text document generation processing management latex pdf structured xml +citation \ [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds, +\ and \ in \ sql \ searches] + +.BR +.B @abstract: +\ [paper \ abstract, \ placed \ after \ table \ of \ contents] + +.BR +.B @comment: +\ [...] + +.BR +.B @catalogue: +loc=[Library \ of \ Congress \ classification]; dewey=[Dewey \ +classification]; isbn=[ISBN]; pg=[Project \ Gutenberg \ text \ number] + +.BR +.B @classify_loc: +\ [Library \ of \ Congress \ classification] + +.BR +.B @classify_dewey: +\ [Dewey \ classification] + +.BR +.B @classify_isbn: +\ [ISBN] + +.BR +.B @classify_pg: +\ [Project \ Gutenberg \ text \ number] + +.BR +.B @prefix: +\ [prefix \ is \ placed \ just \ after \ table \ of \ contents] + +.BR +.B @prefix_a: +\ [prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \ +implemented] + +.BR +.B @prefix_b: + +.BR +.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 \ ] + +.BR +.B @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:) + +.BR +.B @level: +newpage=3; breakpage=4 +\ [paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \ +is \ optional \ eg. \ in \ newpage] + +.BR +.B @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] + +.BR +.B @bold: +\ [regular \ expression \ of \ words/phrases \ to \ be \ made \ bold] + +.BR +.B @italics: +\ [regular \ expression \ of \ words/phrases \ to \ italicise] + +.BR +.B @vocabulary: +name of taxonomy/vocabulary/wordlist to use against document + +.BR +.B @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. + +.BR +.B @links: +{ +.B SiSU +}http://www.jus.uio.no/sisu/; +{ FSF }http://www.fsf.org + +.BR +.B @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] + +.SH +11. MARKUP OF SUBSTANTIVE TEXT +.BR + +.SH +11.1 HEADING LEVELS + +.BR +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) + +.BR +.B :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 + +.BR +.B :B~ \ [heading \ text] +Second level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B :C~ \ [heading \ text] +Third level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B 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 + +.BR +.B 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. + +.BR +.B 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 + + +.nf + 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) +.fi + +.SH +11.2 FONT ATTRIBUTES + +.BR +.B markup example: + + +.nf + 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}\- +.fi + +.BR +.B resulting output: + +.BR +normal text emphasis +.B bold text +.I underscore +.I italics +citation ^superscript^ \ [subscript] inserted text +strikethrough + +.BR +normal text + +.BR +emphasis + +.BR +.B bold text + +.BR +.I underscore + +.BR +.I italics + +.BR +citation + +.BR +^superscript^ + +.BR +[subscript] + +.BR +inserted text + +.BR +strikethrough + +.SH +11.3 INDENTATION AND BULLETS + +.BR +.B markup example: + + +.nf + ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps +.fi + +.BR +.B resulting output: + +.BR +ordinary paragraph + +.BR + indent paragraph one step + +.BR + indent paragraph two steps + +.BR + indent paragraph nine steps + +.BR +.B markup example: + + +.nf + * bullet text + _1* bullet text, first indent + _2* bullet text, two step indent +.fi + +.BR +.B resulting output: + +.BR +* bullet text + +.BR + * bullet text, first indent + +.BR + * bullet text, two step indent + +.BR +Numbered List (not to be confused with headings/titles, (document structure)) + +.BR +.B markup example: + + +.nf + # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. +.fi + +.SH +11.4 FOOTNOTES / ENDNOTES + +.BR +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. + +.BR +.B markup example: + + +.nf + ~{ a footnote or endnote }~ +.fi + +.BR +.B resulting output: + +.BR +[^17] + +.BR +.B markup example: + + +.nf + normal text~{ self contained endnote marker & endnote in one }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text[^18] continues + +.BR +.B markup example: + + +.nf + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*] continues + +.BR +normal text \ [^**] continues + +.BR +.B markup example: + + +.nf + normal text ~[* \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues + normal text ~[+ \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*3] continues + +.BR +normal text \ [^+2] continues + +.BR +.B Alternative endnote pair notation for footnotes/endnotes: + + +.nf +.nf + % note the endnote marker \"~^\" + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs +.fi + +.BR +the standard and pair notation cannot be mixed in the same document + +.SH +11.5 LINKS + +.SH +11.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS + +.BR +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). + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues +.fi + +.BR +.B resulting output: + +.BR +normal text continues + +.BR +An escaped url without decoration + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +.B resulting output: + +.BR +normal text http://www.jus.uio.no/sisu continues + +.BR +deb http://www.jus.uio.no/sisu/archive unstable main non\-free + +.BR +where a code block is used there is neither decoration nor hyperlinking, code +blocks are discussed later in this document + +.BR +.B resulting output: + + +.nf + 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 +.fi + +.BR +To link text or an image to a url the markup is as follows + +.BR +.B markup example: + + +.nf + about { SiSU }http://url.org markup +.fi + +.SH +11.5.2 LINKING TEXT + +.BR +.B resulting output: + +.BR +about SiSU markup + +.BR +A shortcut notation is available so the url link may also be provided +automatically as a footnote + +.BR +.B markup example: + + +.nf + about {~^ SiSU }http://url.org markup +.fi + +.BR +.B resulting output: + +.BR +about SiSU \ [^19] markup + +.SH +11.5.3 LINKING IMAGES + +.BR +.B markup example: + + +.nf + [ tux.png ] + % various url linked images + [ tux.png ] + [ GnuDebianLinuxRubyBetterWay.png ] + {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ +.fi + +.BR +.B resulting output: + +.BR +[ tux.png ] + +.BR +tux.png 64x80 \"Gnu/Linux \- a better way\" + +.BR +[ \ ruby_logo \ (png \ missing) \ ] \ [^20] + +.BR +GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian +and Ruby\" + +.BR +.B linked url footnote shortcut + + +.nf + {~^ \ [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 +.fi + + +.nf + text marker *~name +.fi + +.BR +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. + +.SH +11.6 GROUPED TEXT + +.SH +11.6.1 TABLES + +.BR +Tables may be prepared in two either of two forms + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +a second form may be easier to work with in cases where there is not much +information in each column + +.BR +.B markup example: +[^21] + + +.nf + !_ 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. +.fi + +.BR +.B resulting output: + +.BR +.B Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +* Contributed at least ten times; ** at least 5 times in last month; *** more +than 100 times in last month. + +.SH +11.6.2 POEM + +.BR +.B basic markup: + + +.nf + poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. +.fi + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +11.6.3 GROUP + +.BR +.B basic markup: + + +.nf + group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. +.fi + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +11.6.4 CODE + +.BR +Code tags are used to escape regular sisu markup, and have been used +extensively within this document to provide examples of +.B 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. + +.BR +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] + +.BR +.B use of code tags instead of poem compared, resulting output: + + +.nf + \'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.\"\' +.fi + +.SH +12. COMPOSITE DOCUMENTS MARKUP +.BR + +.BR +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 +.B .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 +.B .sst +regular markup file, or +.B .ssi +(insert/information) A secondary file of the composite document is built +prior to processing with the same prefix and the suffix +.B ._sst + +.BR +basic markup for importing a document into a master document + + +.nf + << |filename1.sst|@|^| + << |filename2.ssi|@|^| +.fi + +.BR +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. + + +.nf + r{filename} + {filename.ssi}require + << {filename.ssi} + % using textlink alternatives + |filename.ssi|@|^|require + << |filename.ssi|@|^| + % using thlnk alternatives + require + << +.fi + +.SH +MARKUP SYNTAX HISTORY +.BR + +.SH +13. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +.BR + +.BR +0.38 is substantially current, depreciated 0.16 supported, though file names +were changed at 0.37 + +.BR +.B 0.52 +(2007w14/6) declared document type identifier at start of text/document: + +.BR + .B SiSU +0.52 + +.BR +or, backward compatible using the comment marker: + +.BR + % +.B SiSU +0.38 + +.BR +variations include \' +.B SiSU +(text|master|insert) \ [version]\' and \'sisu\-[version]\' + +.BR +.B 0.51 +(2007w13/6) skins changed (simplified), markup unchanged + +.BR +.B 0.42 +(2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author + +.BR +.B 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) + +.BR +.B 0.37 +(2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged + +.BR +.B 0.35 +(2005w52/3) sisupod, zipped content file introduced + +.BR +.B 0.23 +(2005w36/2) utf\-8 for markup file + +.BR +.B 0.22 +(2005w35/3) image dimensions may be omitted if rmagick is available to be +relied upon + +.BR +.B 0.20.4 +(2005w33/4) header 0~links + +.BR +.B 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 + +.SH +14. SISU FILETYPES +.BR + +.BR +.B SiSU +has plaintext and binary filetypes, and can process either type of document. + +.SH +14.1 .SST .SSM .SSI MARKED UP PLAIN TEXT + +.BR +.B SiSU +documents are prepared as plain\-text (utf\-8) files with +.B SiSU +markup. They may make reference to and contain images (for example), which +are stored in the directory beneath them _sisu/image. +.B 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. + +.BR +.B 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. + +.BR +.B SiSU +source markup can be shared with the command: + +.BR + sisu \-s \ [filename] + +.SH +14.1.1 SISU TEXT \- REGULAR FILES (.SST) + +.BR +The most common form of document in +.B SiSU +, see the section on +.B SiSU +markup. + +.BR + + +.BR + + +.SH +14.1.2 SISU MASTER FILES (.SSM) + +.BR +Composite documents which incorporate other +.B SiSU +documents which may be either regular +.B SiSU +text .sst which may be generated independently, or inserts prepared solely +for the purpose of being incorporated into one or more master documents. + +.BR +The mechanism by which master files incorporate other documents is described as +one of the headings under under +.B SiSU +markup in the +.B SiSU +manual. + +.BR +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. + +.BR +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst \ [^22] + +.BR + + +.BR + + +.SH +14.1.3 SISU INSERT FILES (.SSI) + +.BR +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular +.B SiSU +text files except they are ignored by the +.B 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. + +.SH +14.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) + +.BR +A sisupod is a zipped +.B SiSU +text file or set of +.B SiSU +text files and any associated images that they contain (this will be extended +to include sound and multimedia\-files) + +.BR +.B 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. + +.BR +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 +.B SiSU +documents. + +.BR +The command to create a sisupod is: + +.BR + sisu \-S \ [filename] + +.BR +Alternatively, make a pod of the contents of a whole directory: + +.BR + sisu \-S + +.BR +.B 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. + +.BR + + +.BR + + +.SH +15. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +.BR + +.SH +15.1 ALTERNATIVE XML + +.BR +.B 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. + +.BR +.B convert from sst to simple xml representations (sax, dom and node): + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +.B convert to sst from any sisu xml representation (sax, dom and node): + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.1 XML SAX REPRESENTATION + +.BR +To convert from sst to simple xml (sax) representation: + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.2 XML DOM REPRESENTATION + +.BR +To convert from sst to simple xml (dom) representation: + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +15.1.3 XML NODE REPRESENTATION + +.BR +To convert from sst to simple xml (node) representation: + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +16. CONFIGURATION +.BR + +.SH +16.1 DETERMINING THE CURRENT CONFIGURATION + +.BR +Information on the current configuration of +.B SiSU +should be available with the help command: + +.BR + sisu \-v + +.BR +which is an alias for: + +.BR + sisu \-\-help env + +.BR +Either of these should be executed from within a directory that contains sisu +markup source documents. + +.SH +16.2 CONFIGURATION FILES (CONFIG.YML) + +.BR +.B 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. + +.BR +The +.B SiSU +configuration file is a yaml file, which means indentation is significant. + +.BR +.B SiSU +resource configuration is determined by looking at the following files if +they exist: + +.BR + ./_sisu/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR + /etc/sisu/sisurc.yml + +.BR +The search is in the order listed, and the first one found is used. + +.BR +In the absence of instructions in any of these it falls back to the internal +program defaults. + +.BR +Configuration determines the output and processing directories and the database +access details. + +.BR +If +.B SiSU +is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +.SH +17. SKINS +.BR + +.BR +Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following locations: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +.B Within the skin directory +are the following the default sub\-directories for document skins: + +.BR + ./skin/doc + +.BR + ./skin/dir + +.BR + ./skin/site + +.BR +A skin is placed in the appropriate directory and the file named skin_[name].rb + +.BR +The skin itself is a ruby file which modifies the default appearances set in +the program. + +.SH +17.1 DOCUMENT SKIN + +.BR +Documents take on a document skin, if the header of the document specifies a +skin to be used. + + +.nf + @skin: skin_united_nations +.fi + +.SH +17.2 DIRECTORY SKIN + +.BR +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). + +.BR +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. + +.SH +17.3 SITE SKIN + +.BR +A site skin, modifies the program default skin. + +.SH +17.4 SAMPLE SKINS + +.BR +With +.B SiSU +installed sample skins may be found in: + +.BR + /etc/sisu/skin/doc and + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + +.BR +(or equivalent directory) and if sisu\-markup\-samples is installed also under: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/non\-free/_sisu/skin/doc + +.BR +Samples of list.yml and promo.yml (which are used to create the right column +list) may be found in: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent + directory) + +.SH +18. CSS \- CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +.BR + +.BR +CSS files to modify the appearance of +.B 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. + +.BR +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. + +.BR +HTML: html.css + +.BR +XML DOM: dom.css + +.BR +XML SAX: sax.css + +.BR +XHTML: xhtml.css + +.BR +The default homepage may use homepage.css or html.css + +.BR +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] + +.SH +19. ORGANISING CONTENT +.BR + +.SH +19.1 DIRECTORY STRUCTURE AND MAPPING + +.BR +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) + +.BR +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. + +.SH +19.2 ORGANISING CONTENT + +.SH +20. HOMEPAGES +.BR + +.BR +.B SiSU +is about the ability to auto\-generate documents. Home pages are regarded as +custom built items, and are not created by +.B SiSU +. More accurately, +.B 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: + +.BR +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) + +.BR +2. through providing what you want as the home page in a skin, + +.BR +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. + +.SH +20.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY + +.BR +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: + +.BR + sisu \-CC + +.SH +20.2 HOME PAGE WITHIN A SKIN + +.BR +Skins are described in a separate section, but basically are a file written in +the programming language +.B 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. + +.BR +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 + + +.nf + 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 +.fi + +.SH +21. MARKUP AND OUTPUT EXAMPLES +.BR + +.SH +21.1 MARKUP EXAMPLES + +.BR +Current markup examples and document output samples are provided at + + +.BR +Some markup with syntax highlighting may be found under + but is not as up to date. + +.BR +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. + +.SH +22. SISU SEARCH \- INTRODUCTION +.BR + +.BR +.B SiSU +output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + +.BR +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. + +.BR +In addition to this +.B 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. + +.SH +23. SQL +.BR + +.SH +23.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^24] and/or +SQLite[^25] database together with information related to document structure. + +.BR +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: + +.BR + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + +.BR + * 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 + +.BR + * a third containing endnotes cross\-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + +.BR + * 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. + +.BR +There is of course the possibility to add further structures. + +.BR +At this level +.B 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. + +.BR +Being able to search a relational database at an object level with the +.B SiSU +citation system is an effective way of locating content generated by +.B 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). + +.SH +24. POSTGRESQL +.BR + +.SH +24.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +24.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +24.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +24.4 COMMANDS + +.BR +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 + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +24.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +24.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +25. SQLITE +.BR + +.SH +25.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +25.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +25.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +25.4 COMMANDS + +.BR +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 + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +25.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +25.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +26. INTRODUCTION +.BR + +.SH +26.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend \ [^26] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^27] + +.BR +.B 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. + +.BR +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.[^28] + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created +\ + +.BR +The following is feedback on the setup on a machine provided by the help +command: + +.BR + sisu \-\-help sql + + +.nf + 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 +.fi + +.BR +Note on databases built + +.BR +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] + +.SH +26.2 SEARCH FORM + +.TP +.B \ sisu \ \-F +\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \ +the \ web\-server \ cgi \ directory \ + +.TP +.B \ 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 +\ + +.TP +.B \ sisu \ \-Fv +\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \ +hyperestraier \ + +.TP +.B \ sisu \ \-W +\ starts \ the \ webrick \ server \ which \ should \ be \ available \ +wherever \ sisu \ is \ properly \ installed \ + +.BR +The generated search form must be copied manually to the webserver directory as +instructed + +.SH +27. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.BR +on sisu_hyperestraier: + +.BR + man sisu_hyperestraier + +.BR + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + +.BR +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + +.BR +(A) to generate the index within the webserver directory to be indexed: + +.BR + estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index] + +.BR +the following are examples that will need to be tailored according to your +needs: + +.BR + cd /home/ralph/sisu_www + +.BR + estcmd gather \-sd casket /home/ralph/sisu_www + +.BR +you may use the \'find\' command together with \'egrep\' to limit indexing to +particular document collection directories within the web server directory: + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \- + +.BR +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + +.BR +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. + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v + \'(doc|concordance).html$\' |estcmd gather \-sd casket \- + +.BR +from your current document preparation/markup directory, you would construct a +rune along the following lines: + +.BR + 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 \- + +.BR +(B) to set up the search form + +.BR +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + +.BR + sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin + +.BR + sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi + +.BR + sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin + +.BR + \ [see \ estraier \ documentation \ for \ paths] + +.BR +(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and +\'replace:\': + +.BR + indexname: /home/ralph/sisu_www/casket + +.BR + replace: ^file:///home/ralph/sisu_www{{!}}http://localhost + +.BR + replace: /index.html?${{!}}/ + +.BR +(C) to test using webrick, start webrick: + +.BR + sisu \-W + +.BR +and try open the url: + +.SH +28. SISU_WEBRICK +.BR + +.SH +28.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.SH +28.2 SYNOPSIS + +.BR +sisu_webrick \ [port] + +.BR +or + +.BR +sisu \-W \ [port] + +.SH +28.3 DESCRIPTION + +.BR +sisu_webrick is part of +.B SiSU +(man sisu) sisu_webrick starts +.B Ruby +\'s Webrick web\-server and points it to the directories to which +.B SiSU +output is written, providing a list of these directories (assuming +.B SiSU +is in use and they exist). + +.BR +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). + +.SH +28.4 SUMMARY OF MAN PAGE + +.BR +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] + +.BR +where no port is given and settings are unchanged the default port is 8081 + +.SH +28.5 DOCUMENT PROCESSING COMMAND FLAGS + +.BR +sisu \-W \ [port] starts +.B Ruby +Webrick web\-server, serving +.B 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 + +.SH +28.6 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR +or man sisu + +.SH +28.7 AUTHOR + +.BR +Ralph Amissah or + +.SH +28.8 SEE ALSO + +.BR + sisu(1) + +.BR + sisu_vim(7) + +.BR + sisu(8) + +.SH +29. REMOTE SOURCE DOCUMENTS +.BR + +.BR +.B 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 +.B SiSU +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp + +.BR +.B .sst / .ssm \- sisu text files + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ .sst \ or \ .ssm \ file] +.fi + +.BR +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. + +.BR +NOTE: to set up a remote machine to serve +.B SiSU +documents in this way, images should be in the directory relative to the +document source ../_sisu/image + +.BR +.B sisupod \- zipped sisu files + +.BR +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. + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ sisupod.zip \ or \ .ssp \ file] +.fi + +.BR +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. + +.SH +REMOTE DOCUMENT OUTPUT +.BR + +.SH +30. REMOTE OUTPUT +.BR + +.BR +Once properly configured +.B SiSU +output can be automatically posted once generated to a designated remote +machine using either rsync, or scp. + +.BR +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. + + +.nf + sisu \-3R sisu_remote.sst +.fi + +.SH +30.1 COMMANDS + +.TP +.B \ \-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 + +.TP +.B \ \-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 + +.SH +30.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +31. REMOTE SERVERS +.BR + +.BR +As +.B SiSU +is generally operated using the command line, and works within a Unix type +environment, +.B 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. + +.SH +32. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +32.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +32.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/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 +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + + +.nf + #/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 +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +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. + +.SH +32.1.2 RPM INSTALLATION + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +32.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +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: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B 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)[^29] or +converting LaTeX to pdf. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + + +.BR + + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby install base + +.BR +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. + +.BR +Further information on \"rant\" is available from: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby install help + +.BR + ruby install \-T + +.SH +32.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +32.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +32.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +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 + +.SH +32.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +32.3 GETTING HELP + +.SH +32.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 \ [^30] + +.BR +* sisu.8 \ [^31] + +.BR +* man directory \ [^32] + +.SH +32.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +32.3.3 THE HOME PAGE + +.BR + + +.BR + + +.SH +32.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR + + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^33] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +33. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + ./data/sisu/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/conf/editor\-syntax\-etc + +.BR +contains rudimentary sisu syntax highlighting files for: + +.BR +* (g)vim + +.BR + package: sisu\-vim + +.BR +status: largely done + +.BR + there is a vim syntax highlighting and folds component + +.BR +* gedit + +.BR +* gobby + +.BR + file: sisu.lang + +.BR +place in: + +.BR + /usr/share/gtksourceview\-1.0/language\-specs + +.BR +or + +.BR + ~/.gnome2/gtksourceview\-1.0/language\-specs + +.BR + status: very basic syntax highlighting + +.BR + comments: this editor features display line wrap and is used by Goby! + +.BR +* nano + +.BR + file: nanorc + +.BR +save as: + +.BR + ~/.nanorc + +.BR + status: basic syntax highlighting + +.BR + comments: assumes dark background; no display line\-wrap; does line breaks + +.BR +* diakonos (an editor written in ruby) + +.BR +file: diakonos.conf + +.BR +save as: + +.BR + ~/.diakonos/diakonos.conf + +.BR +includes: + +.BR + status: basic syntax highlighting + +.BR +comments: assumes dark background; no display line\-wrap + +.BR +* kate & kwrite + +.BR + file: sisu.xml + +.BR + place in: + +.BR + /usr/share/apps/katepart/syntax + +.BR + or + +.BR + ~/.kde/share/apps/katepart/syntax + +.BR + \ [settings::configure \ kate::{highlighting,filetypes}] + +.BR + \ [tools::highlighting::{markup,scripts}:: +.B \ SiSU +] + +.BR +* nedit + +.BR + file: sisu_nedit.pats + +.BR + nedit \-import sisu_nedit.pats + +.BR + status: a very clumsy first attempt \ [not \ really \ done] + +.BR + comments: this editor features display line wrap + +.BR +* emacs + +.BR + files: sisu\-mode.el + +.BR + to file ~/.emacs add the following 2 lines: + +.BR + (add\-to\-list \'load\-path \"/usr/share/sisu\-examples/config/syntax_hi\") + +.BR + (require \'sisu\-mode.el) + +.BR + \ [not \ done \ / \ not \ yet \ included] + +.BR +* vim & gvim + +.BR + files: + +.BR + 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) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ 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] + +.SH +34. HELP SOURCES +.BR + +.BR +For a summary of alternative ways to get help on +.B SiSU +try one of the following: + +.BR +.B man page + +.BR + man sisu_help + +.BR +.B man2html + +.BR + + +.BR + + +.BR +.B sisu generated output \- links to html + +.BR + + +.BR + + +.BR + + +.BR +.B help sources lists + +.BR +Alternative sources for this help sources page listed here: + +.BR + man sisu_help_sources + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.1 MAN PAGES + +.SH +34.1.1 MAN + +.BR + man sisu + +.BR + man sisu_commands + +.BR + man 7 sisu_complete + +.BR + man sisu_configuration + +.BR + man 8 sisu_faq + +.BR + man sisu_filetypes + +.BR + man sisu_help + +.BR + man sisu_help_sources + +.BR + man 8 sisu_howto + +.BR + man sisu_introduction + +.BR + man sisu_markup + +.BR + man sisu_output_overview + +.BR + man 7 sisu_pdf + +.BR + man 7 sisu_postgresql + +.BR + man 8 sisu_quickstart + +.BR + man 8 sisu_remote + +.BR + man 8 sisu_search + +.BR + man sisu_skin + +.BR + man 7 sisu_sqlite + +.BR + man 8 sisu_syntax_highlighting + +.BR + man 7 sisu_vim + +.BR + man sisu_webrick + +.SH +34.2 SISU GENERATED OUTPUT \- LINKS TO HTML + +.BR +Note +.B SiSU +documentation is prepared in +.B 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[^34] + +.SH +34.2.1 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/sisu_manual/sisu/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_description/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_search/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html + +.SH +34.2.2 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.3 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.4 MAN2HTML + +.SH +34.2.5 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/html/sisu.1.html + +.BR + /usr/share/doc/sisu/html/sisu_commands.1.html + +.BR + /usr/share/doc/sisu/html/sisu_complete.7.html + +.BR + /usr/share/doc/sisu/html/sisu_configuration.1.html + +.BR + /usr/share/doc/sisu/html/sisu_faq.8.html + +.BR + /usr/share/doc/sisu/html/sisu_help.1.html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources.1.html + +.BR + /usr/share/doc/sisu/html/sisu_howto.8.html + +.BR + /usr/share/doc/sisu/html/sisu_markup.1.html + +.BR + /usr/share/doc/sisu/html/sisu_pdf.7.html + +.BR + /usr/share/doc/sisu/html/sisu_postgresql.7.html + +.BR + /usr/share/doc/sisu/html/sisu_quickstart.8.html + +.BR + /usr/share/doc/sisu/html/sisu_remote.8.html + +.BR + /usr/share/doc/sisu/html/sisu_search.8.html + +.BR + /usr/share/doc/sisu/html/sisu_skin.1.html + +.BR + /usr/share/doc/sisu/html/sisu_sqlite.7.html + +.BR + /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html + +.BR + /usr/share/doc/sisu/html/sisu_vim.7.html + +.BR + /usr/share/doc/sisu/html/sisu_webrick.1.html + +.SH +34.2.6 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +34.2.7 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Manual \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-08\-30 + +.BR +DC Date: +.I 2007\-08\-30 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu._sst)= +.I 850b4b4b2da877667488ddfa325b6581 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:41 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +\" +.B SiSU +information Structuring Universe\" or \"Structured information, Serialized +Units\". + also chosen for the meaning of the Finnish term "sisu". +.TP +.BI 2. +Unix command line oriented +.TP +.BI 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. +.TP +.BI 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. +.TP +.BI 5. +the different heading levels +.TP +.BI 6. +units of text, primarily paragraphs and headings, also any tables, poems, +code-blocks +.TP +.BI 7. +Specification submitted by Adobe to ISO to become a full open ISO +specification + +.TP +.BI 8. +ISO/IEC 26300:2006 +.TP +.BI 9. +generated from source using rman + + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + +.TP +.BI 10. + +.TP +.BI 11. + +.TP +.BI 12. + +.TP +.BI 13. + +.TP +.BI 14. + +.TP +.BI *1. +square brackets +.TP +.BI *2. +square brackets +.TP +.BI +1. +square brackets +.TP +.BI 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. +.TP +.BI 16. +files should be prepared using UTF-8 character encoding +.TP +.BI 17. +a footnote or endnote +.TP +.BI 18. +self contained endnote marker & endnote in one +.TP +.BI *. +unnumbered asterisk footnote/endnote, insert multiple asterisks if required +.TP +.BI **. +another unnumbered asterisk footnote/endnote +.TP +.BI *3. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI +2. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI 19. + +.TP +.BI 20. + +.TP +.BI 21. +Table from the Wealth of Networks by Yochai Benkler + +.TP +.BI 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. +.TP +.BI 23. +.B 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. +.TP +.BI 24. + + + +.TP +.BI 25. + + +.TP +.BI 26. + +.TP +.BI 27. +(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. +.TP +.BI 28. +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. +.TP +.BI 29. +There is nothing to stop MySQL support being added in future. +.TP +.BI 30. + +.TP +.BI 31. + +.TP +.BI 32. + +.TP +.BI 33. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. +.TP +.BI 34. +named index.html or more extensively through sisu_manifest.html + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu/sisu.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:48 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_commands.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_commands.1 new file mode 100644 index 00000000..46e217ec --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_commands.1 @@ -0,0 +1,575 @@ +.TH "sisu_commands" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- COMMANDS \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU COMMANDS +.BR + +.SH +1. COMMANDS SUMMARY +.BR + +.SH +1.1 SYNOPSIS + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.BR +sisu \ [ \ \-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9 \ ] \ [ \ filename/ \ +wildcard \ ] + +.BR +sisu \ [ \ \-Ddcv \ ] \ [ \ instruction \ ] + +.BR +sisu \ [ \ \-CcFLSVvW \ ] + +.BR +Note: commands should be issued from within the directory that contains the +marked up files, cd to markup directory. + +.SH +1.2 DESCRIPTION + +.BR +.B SiSU +.B 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: + +.SH +1.3 DOCUMENT PROCESSING COMMAND FLAGS + +.TP +.B \ \-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) + +.TP +.B \ \-b \ \ [filename/wildcard] +produces xhtml/XML output for browser viewing (sax parsing). + +.TP +.B \ \-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. + +.TP +.B \ \-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. \ + +.TP +.B \ \-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). + +.TP +.B \ \-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. + +.TP +.B \ \-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. + +.TP +.B \ \-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 + +.TP +.B \ \-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]. + +.TP +.B \ \-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]. + +.TP +.B \ \-I \ \ [filename/wildcard] +produces texinfo and info file, (view with pinfo). + +.TP +.B \ \-L +\ prints \ license \ information. \ + +.TP +.B \ \-M \ \ [filename/wildcard/url] +maintenance mode files created for processing preserved and their locations +indicated. (also see \-V) + +.TP +.B \ \-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 + +.TP +.B \ \-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. + +.TP +.B \ \-n \ \ [filename/wildcard/url] +skip meta\-markup (building of \"metaverse\"), this skips the equivalent of +\-m which is otherwise assumed by most processing flags. + +.TP +.B \ \-o \ \ [filename/wildcard/url] +output basic document in opendocument file format (opendocument.odt). + +.TP +.B \ \-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). + +.TP +.B \ \-q \ \ [filename/wildcard] +quiet less output to screen. + +.TP +.B \ \-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 + +.TP +.B \ \-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 + +.TP +.B \ \-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). + +.TP +.B \ \-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. +.B 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]. + +.TP +.B \ \-s \ \ [filename/wildcard] +copies sisu markup file to output directory. + +.TP +.B \ \-t \ \ [filename/wildcard \ (*.termsheet.rb)] +standard form document builder, preprocessing feature + +.TP +.B \ \-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 + +.TP +.B \ \-u \ \ [filename/wildcard] +provides url mapping of output files for the flags requested for processing, +also see \-U + +.TP +.B \ \-V +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ and \ environment \ information \ (sisu \ \-\-help \ env) \ + +.TP +.B \ \-V \ \ [filename/wildcard] +even more verbose than the \-v flag. (also see \-M) + +.TP +.B \ \-v +\ on \ its \ own, \ provides +.B \ SiSU +\ version \ information \ + +.TP +.B \ \-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 + +.TP +.B \ \-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 \ ]. + +.TP +.B \ \-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) + +.TP +.B \ \-X \ \ [filename/wildcard] +produces XML output with deep document structure, in the nature of dom. + +.TP +.B \ \-x \ \ [filename/wildcard] +produces XML output shallow structure (sax parsing). + +.TP +.B \ \-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]) + +.TP +.B \ \-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. + +.TP +.B \ \-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. + +.TP +.B \ \-z \ \ [filename/wildcard] +produces php (zend) \ [this \ feature \ is \ disabled \ for \ the \ time \ +being] + +.SH +2. COMMAND LINE MODIFIERS +.BR + +.TP +.B \ \-\-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. + +.TP +.B \ \-\-no\-annotate +\ strips \ output \ text \ of \ editor \ endnotes[^*1] denoted by asterisk or +dagger/plus sign + +.TP +.B \ \-\-no\-asterisk +\ strips \ output \ text \ of \ editor \ endnotes[^*2] denoted by asterisk +sign + +.TP +.B \ \-\-no\-dagger +\ strips \ output \ text \ of \ editor \ endnotes[^+1] denoted by dagger/plus +sign + +.SH +3. DATABASE COMMANDS +.BR + +.BR +dbi \- database interface + +.BR +\-D or \-\-pgsql set for postgresql \-d or \-\-sqlite default set for sqlite +\-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)] + +.TP +.B \ \-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. + +.TP +.B \ \-Dv \ \-\-import +\ \ [filename/wildcard] imports data specified to postgresql db (rb.dbi) \ [ +\ \-dv \ \-\-import \ sqlite \ equivalent] + +.TP +.B \ \-Dv \ \-\-update +\ \ [filename/wildcard] updates/imports specified data to postgresql db +(rb.dbi) \ [ \ \-dv \ \-\-update \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-remove +\ \ [filename/wildcard] removes specified data to postgresql db (rb.dbi) \ [ +\ \-d \ \-\-remove \ sqlite \ equivalent] + +.TP +.B \ \-D \ \-\-dropall +\ kills \ data\" \ and \ drops \ (postgresql \ or \ sqlite) \ db, \ tables \ +& \ indexes \ \ [ \ \-d \ \-\-dropall \ sqlite \ equivalent] + +.BR +The v in e.g. \-Dv is for verbose output. + +.SH +4. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS +.BR + +.TP +.B \ \-\-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. + +.TP +.B \ \-0 \ to \ \-5 \ \ [filename \ or \ wildcard] +Default shorthand mappings (note that the defaults can be changed/configured +in the sisurc.yml file): + +.TP +.B \ \-0 +\ \-mNhwpAobxXyYv \ \ [this \ is \ the \ default \ action \ run \ when \ no \ +options \ are \ give, \ i.e. \ on \ \'sisu \ \ [filename]\'] + +.TP +.B \ \-1 +\ \-mNHwpy \ + +.TP +.B \ \-2 +\ \-mNHwpaoy \ + +.TP +.B \ \-3 +\ \-mNhwpAobxXyY \ + +.TP +.B \ \-4 +\ \-mNhwpAobxXDyY \ \-\-import \ + +.TP +.B \ \-5 +\ \-mNhwpAobxXDyY \ \-\-update \ + +.BR +add \-v for verbose mode and \-c for color, e.g. sisu \-2vc \ [filename \ or \ +wildcard] + +.BR +consider \-u for appended url info or \-v for verbose output + +.SH +4.0.1 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +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. + +.BR +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. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Commands \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_commands.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_commands.sst)= +.I 8101d9e72f3de2510ef887202f8db3f9 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:43 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI *1. +square brackets +.TP +.BI *2. +square brackets +.TP +.BI +1. +square brackets + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_commands/sisu_commands.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_complete.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_complete.1 new file mode 100644 index 00000000..e68acc46 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_complete.1 @@ -0,0 +1,181 @@ +.TH "sisu_complete" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- COMPLETE PACKAGE \ [0.58], +RALPH AMISSAH +.BR + +.SH +1. SISU_COMPLETE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +complete dependency package + +.SH +1.2 SYNOPSIS + +.BR +.B Debian +dummy package installs the whole of +.B SiSU +, excluding sisu\-examples. + +.BR +sisu\-complete together with sisu\-examples is the whole of +.B SiSU + +.SH +1.3 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR + + +.BR + + +.SH +1.4 AUTHOR + +.BR +Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com + +.SH +1.5 SEE + +.BR +sisu(1) + +.SH +1.6 ALSO SEE + +.BR +sisu_webrick(1), sisu_pdf(7) sisu_sqlite(7) sisu_postgresql(7) sisu_vim(7) +sisu_termsheet(1) + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Complete Package \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_complete.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_complete.sst)= +.I 42003f9cf59fd7e4ddffae864e2c4179 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:47 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_complete/sisu_complete.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_complete.7 b/data/doc/manuals_generated/sisu_manual/man/sisu_complete.7 new file mode 100644 index 00000000..3e3294b7 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_complete.7 @@ -0,0 +1,181 @@ +.TH "sisu_complete" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- COMPLETE PACKAGE \ [0.58], +RALPH AMISSAH +.BR + +.SH +1. SISU_COMPLETE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +complete dependency package + +.SH +1.2 SYNOPSIS + +.BR +.B Debian +dummy package installs the whole of +.B SiSU +, excluding sisu\-examples. + +.BR +sisu\-complete together with sisu\-examples is the whole of +.B SiSU + +.SH +1.3 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR + + +.BR + + +.SH +1.4 AUTHOR + +.BR +Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com + +.SH +1.5 SEE + +.BR +sisu(1) + +.SH +1.6 ALSO SEE + +.BR +sisu_webrick(1), sisu_pdf(7) sisu_sqlite(7) sisu_postgresql(7) sisu_vim(7) +sisu_termsheet(1) + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Complete Package \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_complete.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_complete.sst)= +.I 42003f9cf59fd7e4ddffae864e2c4179 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:02 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_complete/sisu_complete.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_configuration.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_configuration.1 new file mode 100644 index 00000000..a844f465 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_configuration.1 @@ -0,0 +1,368 @@ +.TH "sisu_configuration" "1" "2007-08-30" "0.59.0" "SiSU" +.SH +SISU \- CONFIGURATION \ [0.58], +RALPH AMISSAH +.BR + +.SH +CONFIGURATION OF ENVIRONMENT +.BR + +.SH +1. CONFIGURATION +.BR + +.SH +1.1 DETERMINING THE CURRENT CONFIGURATION + +.BR +Information on the current configuration of +.B SiSU +should be available with the help command: + +.BR + sisu \-v + +.BR +which is an alias for: + +.BR + sisu \-\-help env + +.BR +Either of these should be executed from within a directory that contains sisu +markup source documents. + +.SH +1.2 CONFIGURATION FILES (CONFIG.YML) + +.BR +.B 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. + +.BR +The +.B SiSU +configuration file is a yaml file, which means indentation is significant. + +.BR +.B SiSU +resource configuration is determined by looking at the following files if +they exist: + +.BR + ./_sisu/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR + /etc/sisu/sisurc.yml + +.BR +The search is in the order listed, and the first one found is used. + +.BR +In the absence of instructions in any of these it falls back to the internal +program defaults. + +.BR +Configuration determines the output and processing directories and the database +access details. + +.BR +If +.B SiSU +is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +.SH +CONFIGURATION OF DOCUMENTS +.BR + +.SH +2. SKINS +.BR + +.BR +Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following locations: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +.B Within the skin directory +are the following the default sub\-directories for document skins: + +.BR + ./skin/doc + +.BR + ./skin/dir + +.BR + ./skin/site + +.BR +A skin is placed in the appropriate directory and the file named skin_[name].rb + +.BR +The skin itself is a ruby file which modifies the default appearances set in +the program. + +.SH +2.1 DOCUMENT SKIN + +.BR +Documents take on a document skin, if the header of the document specifies a +skin to be used. + + +.nf + @skin: skin_united_nations +.fi + +.SH +2.2 DIRECTORY SKIN + +.BR +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). + +.BR +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. + +.SH +2.3 SITE SKIN + +.BR +A site skin, modifies the program default skin. + +.SH +2.4 SAMPLE SKINS + +.BR +With +.B SiSU +installed sample skins may be found in: + +.BR + /etc/sisu/skin/doc and + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + +.BR +(or equivalent directory) and if sisu\-markup\-samples is installed also under: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/non\-free/_sisu/skin/doc + +.BR +Samples of list.yml and promo.yml (which are used to create the right column +list) may be found in: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent + directory) + +.SH +3. HOMEPAGES +.BR + +.BR +.B SiSU +is about the ability to auto\-generate documents. Home pages are regarded as +custom built items, and are not created by +.B SiSU +. More accurately, +.B 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: + +.BR +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) + +.BR +2. through providing what you want as the home page in a skin, + +.BR +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. + +.SH +3.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB\-DIRECTORY + +.BR +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: + +.BR + sisu \-CC + +.SH +3.2 HOME PAGE WITHIN A SKIN + +.BR +Skins are described in a separate section, but basically are a file written in +the programming language +.B 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. + +.BR +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 + + +.nf + 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 +.fi + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Configuration \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Ralph Amissah + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2007\-08\-28 + +.BR +DC Date modified: +.I 2007\-08\-30 + +.BR +DC Date: +.I 2007\-08\-30 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_configuration._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_configuration._sst)= +.I 2a18ae8bbfec534c6e064d666ffbe20d + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:46 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_configuration/sisu_configuration.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_faq.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_faq.1 new file mode 100644 index 00000000..613a3e43 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_faq.1 @@ -0,0 +1,404 @@ +.TH "sisu_faq" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS, +RALPH AMISSAH +.BR + +.SH +1. FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS +.BR + +.SH +1.1 WHY ARE URLS PRODUCED WITH THE \-V (AND \-U) FLAG THAT POINT TO A WEB +SERVER ON PORT 8081? + +.BR +Try the following rune: + +.BR +* sisu \-W + +.BR +This should start the ruby webserver. It should be done after having produced +some output as it scans the output directory for what to serve. + +.SH +1.2 I CANNOT FIND MY OUTPUT, WHERE IS IT? + +.BR +The following should provide help on output paths: + +.BR +* sisu \-\-help env + +.BR +* sisu \-V \ [same \ as \ the \ previous \ command] + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +* sisu \-U \ [filename] + +.BR +* man sisu + +.SH +1.3 I DO NOT GET ANY PDF OUTPUT, WHY? + +.BR +.B SiSU +produces LaTeX and pdflatex is run against that to generate pdf files. + +.BR +If you use +.B Debian +the following will install the required dependencies + +.BR +* aptitude install sisu\-pdf + +.BR +the following packages are required: tetex\-bin, tetex\-extra, latex\-ucs + +.SH +1.4 WHERE IS THE LATEX (OR SOME OTHER INTERIM) OUTPUT? + +.BR +Try adding \-M (for maintenance) to your command flags, e.g.: + +.BR +* sisu \-HpMv \ [filename] + +.BR +this should result in the interim processing output being retained, and +information being provided on where to find it. + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +should also provide some relevant information as to where it is placed. + +.SH +1.5 WHY ISN\'T SISU MARKUP XML + +.BR +I worked with text and (though I find XML immensely valuable) disliked noise +... better to sidestep the question and say: + +.BR +.B SiSU +currently \"understands\" three XML input representations \- or more +accurately, converts from three forms of XML to native +.B SiSU +markup for processing. The three types correspond to SAX (structure +described), DOM (structure embedded, whole document must be read before +structure is correctly discernable) and node based (a tree) forms of XML +document structure representation. Problem is I use them very seldom and check +that all is as it should be with them seldom, so I would not be surprised if +something breaks there, but as far as I know they are working. I will check and +add an XML markup help page before the next release. There already is a bit of +information in the man page under the title +.B SiSU +VERSION CONVERSION + +.BR + sisu \-\-to\-sax \ [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] + +.BR +The XML should be well formed... must check, but lacks sensible headers. +Suggestions welcome as to what to make of them. \ [For \ the \ present \ time \ +I \ am \ satisfied \ that \ I \ can \ convert \ (both \ ways) \ between \ 3 \ +forms \ of \ XML \ representation \ and +.B \ SiSU +\ markup]. + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard] + +.SH +1.6 LATEX CLAIMS TO BE A DOCUMENT PREPARATION SYSTEM FOR HIGH\-QUALITY +TYPESETTING. CAN THE SAME BE SAID ABOUT SISU? + +.BR +.B SiSU +is not really about type\-setting. + +.BR +LaTeX is the ultimate computer instruction type\-setting language for paper +based publication. + +.BR +LaTeX is able to control just about everything that happens on page and pixel, +position letters kerning, space variation between characters, words, paragraphs +etc. formula. + +.BR +.B SiSU +is not really about type\-setting at all. It is about a lightweight markup +instruction that provides enough information for an abstraction of the +documents structure and objects, from which different forms of representation +of the document can be generated. + +.BR +.B SiSU +with very little markup instruction is able to produce relatively high +quality pdf by virtue of being able to generate usable default LaTeX; it +produces \"quality\" html by generating the html directly; likewise it +populates an SQL database in a useful way with the document in object sized +chunks and its meta\-data. But +.B SiSU +works on an abstraction of the document\'s structure and content and custom +builds suitable uniform output. The html for browser viewing and pdf for paper +viewing/publishing are rather different things with different needs for layout +\- as indeed is what is needed to store information in a database in searchable +objects. + +.BR +The pdfs or html produced for example by open office based on open document +format and other office/word processor suits usually attempt to have similar +looking outputs \- your document rendered in html looks much the same, or in +pdf... sisu is less this way, it seeks to have a starting point with as little +information about appearance as possible, and to come up with the best possible +appearance for each output that can be derived based on this minimal +information. + +.BR +Where there are large document sets, it provides consistency in appearance in +each output format for the documents. + +.BR +The excuse for going this way is, it is a waste of time to think much about +appearance when working on substantive content, it is the substantive content +that is relevant, not the way it looks beyond the basic informational tags \- +and yet you want to be able to take advantage of as many useful different ways +of representing documents as are available, and for various types of output to +to be/look as good as it can for each medium/format in which it is presented, +(with different mediums having different focuses) and +.B SiSU +tries to achieve this from minimal markup. + +.SH +1.7 HOW DO I CREATE GIN OR GIST INDEX IN POSTGRESQL FOR USE IN SISU + +.BR +This at present needs to be done \"manually\" and it is probably necessary to +alter the sample search form. The following is a helpful response from one of +the contributors of GiN to Postgresql Oleg Bartunov 2006\-12\-06: + +.BR +\"I have tsearch2 slides which introduces tsearch2 + + +.BR +FTS in PostgreSQL is provided by tsearch2, which should works without any +indices (GiST or GIN) ! Indices provide performance, not functionality. + +.BR +In your example I\'d do ( simple way, just for demo): + +.BR +.B 0. +compile, install tsearch2 and load tsearch2 into your database + +.BR + cd contrib/tsearch2; make&&make&&install&&make installcheck; psql DB < + tsearch2.sql + +.BR +.B 1. +Add column fts, which holds tsvector + +.BR + alter table documents add column fts tsvector; + +.BR +.B 2. +Fill fts column + +.BR + update document set fts = to_tsvector(clean); + +.BR +.B 3. +create index \- just for performance ! + +.BR + create index fts_gin_idx on document using gin(fts); + +.BR +.B 4. +Run vacuum + +.BR + vacuum analyze document; + +.BR +That\'s all. + +.BR +Now you can search: + +.BR +select lid, metadata_tid, rank_cd(fts, q,2)as rank from document, +plainto_tsquery(\'markup syntax\') q where q @@ fts order by rank desc limit +10; + +.SH +1.8 WHERE IS VERSION 1.0? + +.BR +.B SiSU +works pretty well as it is supposed to. Version 1.0 will have the current +markup, and directory structure. At this point it is largely a matter of choice +as to when the name change is made. + +.BR +The feature set for html,[^1] LaTeX/pdf and opendocument is in place. XML, and +plaintext are in order. + +.BR +html and LaTeX/pdf may be regarded as reference copy outputs + +.BR +With regard to the populating of sql databases (postgresql and sqlite), there +is a bit to be done. + +.BR +We are still almost there. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- FAQ \- Frequently Asked/Answered Questions + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_faq.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_faq.sst)= +.I 4ba78b1270b9d994054c1ff06d58765d + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:46 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +html w3c compliance has been largely met. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_faq/sisu_faq.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_faq.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_faq.8 new file mode 100644 index 00000000..3146086c --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_faq.8 @@ -0,0 +1,404 @@ +.TH "sisu_faq" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS, +RALPH AMISSAH +.BR + +.SH +1. FAQ \- FREQUENTLY ASKED/ANSWERED QUESTIONS +.BR + +.SH +1.1 WHY ARE URLS PRODUCED WITH THE \-V (AND \-U) FLAG THAT POINT TO A WEB +SERVER ON PORT 8081? + +.BR +Try the following rune: + +.BR +* sisu \-W + +.BR +This should start the ruby webserver. It should be done after having produced +some output as it scans the output directory for what to serve. + +.SH +1.2 I CANNOT FIND MY OUTPUT, WHERE IS IT? + +.BR +The following should provide help on output paths: + +.BR +* sisu \-\-help env + +.BR +* sisu \-V \ [same \ as \ the \ previous \ command] + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +* sisu \-U \ [filename] + +.BR +* man sisu + +.SH +1.3 I DO NOT GET ANY PDF OUTPUT, WHY? + +.BR +.B SiSU +produces LaTeX and pdflatex is run against that to generate pdf files. + +.BR +If you use +.B Debian +the following will install the required dependencies + +.BR +* aptitude install sisu\-pdf + +.BR +the following packages are required: tetex\-bin, tetex\-extra, latex\-ucs + +.SH +1.4 WHERE IS THE LATEX (OR SOME OTHER INTERIM) OUTPUT? + +.BR +Try adding \-M (for maintenance) to your command flags, e.g.: + +.BR +* sisu \-HpMv \ [filename] + +.BR +this should result in the interim processing output being retained, and +information being provided on where to find it. + +.BR +* sisu \-\-help directory + +.BR +* sisu \-\-help path + +.BR +should also provide some relevant information as to where it is placed. + +.SH +1.5 WHY ISN\'T SISU MARKUP XML + +.BR +I worked with text and (though I find XML immensely valuable) disliked noise +... better to sidestep the question and say: + +.BR +.B SiSU +currently \"understands\" three XML input representations \- or more +accurately, converts from three forms of XML to native +.B SiSU +markup for processing. The three types correspond to SAX (structure +described), DOM (structure embedded, whole document must be read before +structure is correctly discernable) and node based (a tree) forms of XML +document structure representation. Problem is I use them very seldom and check +that all is as it should be with them seldom, so I would not be surprised if +something breaks there, but as far as I know they are working. I will check and +add an XML markup help page before the next release. There already is a bit of +information in the man page under the title +.B SiSU +VERSION CONVERSION + +.BR + sisu \-\-to\-sax \ [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] + +.BR +The XML should be well formed... must check, but lacks sensible headers. +Suggestions welcome as to what to make of them. \ [For \ the \ present \ time \ +I \ am \ satisfied \ that \ I \ can \ convert \ (both \ ways) \ between \ 3 \ +forms \ of \ XML \ representation \ and +.B \ SiSU +\ markup]. + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard] + +.SH +1.6 LATEX CLAIMS TO BE A DOCUMENT PREPARATION SYSTEM FOR HIGH\-QUALITY +TYPESETTING. CAN THE SAME BE SAID ABOUT SISU? + +.BR +.B SiSU +is not really about type\-setting. + +.BR +LaTeX is the ultimate computer instruction type\-setting language for paper +based publication. + +.BR +LaTeX is able to control just about everything that happens on page and pixel, +position letters kerning, space variation between characters, words, paragraphs +etc. formula. + +.BR +.B SiSU +is not really about type\-setting at all. It is about a lightweight markup +instruction that provides enough information for an abstraction of the +documents structure and objects, from which different forms of representation +of the document can be generated. + +.BR +.B SiSU +with very little markup instruction is able to produce relatively high +quality pdf by virtue of being able to generate usable default LaTeX; it +produces \"quality\" html by generating the html directly; likewise it +populates an SQL database in a useful way with the document in object sized +chunks and its meta\-data. But +.B SiSU +works on an abstraction of the document\'s structure and content and custom +builds suitable uniform output. The html for browser viewing and pdf for paper +viewing/publishing are rather different things with different needs for layout +\- as indeed is what is needed to store information in a database in searchable +objects. + +.BR +The pdfs or html produced for example by open office based on open document +format and other office/word processor suits usually attempt to have similar +looking outputs \- your document rendered in html looks much the same, or in +pdf... sisu is less this way, it seeks to have a starting point with as little +information about appearance as possible, and to come up with the best possible +appearance for each output that can be derived based on this minimal +information. + +.BR +Where there are large document sets, it provides consistency in appearance in +each output format for the documents. + +.BR +The excuse for going this way is, it is a waste of time to think much about +appearance when working on substantive content, it is the substantive content +that is relevant, not the way it looks beyond the basic informational tags \- +and yet you want to be able to take advantage of as many useful different ways +of representing documents as are available, and for various types of output to +to be/look as good as it can for each medium/format in which it is presented, +(with different mediums having different focuses) and +.B SiSU +tries to achieve this from minimal markup. + +.SH +1.7 HOW DO I CREATE GIN OR GIST INDEX IN POSTGRESQL FOR USE IN SISU + +.BR +This at present needs to be done \"manually\" and it is probably necessary to +alter the sample search form. The following is a helpful response from one of +the contributors of GiN to Postgresql Oleg Bartunov 2006\-12\-06: + +.BR +\"I have tsearch2 slides which introduces tsearch2 + + +.BR +FTS in PostgreSQL is provided by tsearch2, which should works without any +indices (GiST or GIN) ! Indices provide performance, not functionality. + +.BR +In your example I\'d do ( simple way, just for demo): + +.BR +.B 0. +compile, install tsearch2 and load tsearch2 into your database + +.BR + cd contrib/tsearch2; make&&make&&install&&make installcheck; psql DB < + tsearch2.sql + +.BR +.B 1. +Add column fts, which holds tsvector + +.BR + alter table documents add column fts tsvector; + +.BR +.B 2. +Fill fts column + +.BR + update document set fts = to_tsvector(clean); + +.BR +.B 3. +create index \- just for performance ! + +.BR + create index fts_gin_idx on document using gin(fts); + +.BR +.B 4. +Run vacuum + +.BR + vacuum analyze document; + +.BR +That\'s all. + +.BR +Now you can search: + +.BR +select lid, metadata_tid, rank_cd(fts, q,2)as rank from document, +plainto_tsquery(\'markup syntax\') q where q @@ fts order by rank desc limit +10; + +.SH +1.8 WHERE IS VERSION 1.0? + +.BR +.B SiSU +works pretty well as it is supposed to. Version 1.0 will have the current +markup, and directory structure. At this point it is largely a matter of choice +as to when the name change is made. + +.BR +The feature set for html,[^1] LaTeX/pdf and opendocument is in place. XML, and +plaintext are in order. + +.BR +html and LaTeX/pdf may be regarded as reference copy outputs + +.BR +With regard to the populating of sql databases (postgresql and sqlite), there +is a bit to be done. + +.BR +We are still almost there. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- FAQ \- Frequently Asked/Answered Questions + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_faq.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_faq.sst)= +.I 4ba78b1270b9d994054c1ff06d58765d + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:01 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +html w3c compliance has been largely met. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_faq/sisu_faq.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 new file mode 100644 index 00000000..d556f763 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_filetypes.1 @@ -0,0 +1,387 @@ +.TH "sisu_filetypes" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- FILETYPES \ [0.58], +RALPH AMISSAH +.BR + +.SH +1. SISU FILETYPES +.BR + +.BR +.B SiSU +has plaintext and binary filetypes, and can process either type of document. + +.SH +1.1 .SST .SSM .SSI MARKED UP PLAIN TEXT + +.BR +.B SiSU +documents are prepared as plain\-text (utf\-8) files with +.B SiSU +markup. They may make reference to and contain images (for example), which +are stored in the directory beneath them _sisu/image. +.B 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. + +.BR +.B 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. + +.BR +.B SiSU +source markup can be shared with the command: + +.BR + sisu \-s \ [filename] + +.SH +1.1.1 SISU TEXT \- REGULAR FILES (.SST) + +.BR +The most common form of document in +.B SiSU +, see the section on +.B SiSU +markup. + +.BR + + +.BR + + +.SH +1.1.2 SISU MASTER FILES (.SSM) + +.BR +Composite documents which incorporate other +.B SiSU +documents which may be either regular +.B SiSU +text .sst which may be generated independently, or inserts prepared solely +for the purpose of being incorporated into one or more master documents. + +.BR +The mechanism by which master files incorporate other documents is described as +one of the headings under under +.B SiSU +markup in the +.B SiSU +manual. + +.BR +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. + +.BR +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst \ [^1] + +.BR + + +.BR + + +.SH +1.1.3 SISU INSERT FILES (.SSI) + +.BR +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular +.B SiSU +text files except they are ignored by the +.B 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. + +.SH +1.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) + +.BR +A sisupod is a zipped +.B SiSU +text file or set of +.B SiSU +text files and any associated images that they contain (this will be extended +to include sound and multimedia\-files) + +.BR +.B 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. + +.BR +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 +.B SiSU +documents. + +.BR +The command to create a sisupod is: + +.BR + sisu \-S \ [filename] + +.BR +Alternatively, make a pod of the contents of a whole directory: + +.BR + sisu \-S + +.BR +.B 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. + +.BR + + +.BR + + +.SH +2. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +.BR + +.SH +2.1 ALTERNATIVE XML + +.BR +.B 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. + +.BR +.B convert from sst to simple xml representations (sax, dom and node): + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +.B convert to sst from any sisu xml representation (sax, dom and node): + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +2.1.1 XML SAX REPRESENTATION + +.BR +To convert from sst to simple xml (sax) representation: + +.BR + sisu \-\-to\-sax \ [filename/wildcard] or sisu \-\-to\-sxs \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +2.1.2 XML DOM REPRESENTATION + +.BR +To convert from sst to simple xml (dom) representation: + +.BR + sisu \-\-to\-dom \ [filename/wildcard] or sisu \-\-to\-sxd \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +2.1.3 XML NODE REPRESENTATION + +.BR +To convert from sst to simple xml (node) representation: + +.BR + sisu \-\-to\-node \ [filename/wildcard] or sisu \-\-to\-sxn \ + [filename/wildcard] + +.BR +To convert from any sisu xml representation back to sst + +.BR + sisu \-\-from\-xml2sst \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.BR +or the same: + +.BR + sisu \-\-from\-sxml \ [filename/wildcard \ \ [.sxs.xml,.sxd.xml,sxn.xml]] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Filetypes \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_filetypes.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_filetypes.sst)= +.I c0fc6ab6516fe919f331fd8517c9f7a6 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:44 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +.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. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_filetypes/sisu_filetypes.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_help.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_help.1 new file mode 100644 index 00000000..7322b381 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_help.1 @@ -0,0 +1,318 @@ +.TH "sisu_help" "1" "2007-08-30" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- MANUAL \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU HELP +.BR + +.SH +1. HELP +.BR + +.SH +1.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +and (from +.B SiSU +0.59 onwards) installed locally at: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +or equivalent directory + +.BR +Within the +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.SH +1.2 SISU MAN PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR + man sisu + +.BR + man sisu_markup + +.BR + man sisu_commands + +.BR +Most +.B 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 +.B SiSU +tarball at: + +.BR + ./data/doc/sisu/sisu_manual/ + +.BR +Once installed, directory equivalent to: + +.BR + /usr/share/doc/sisu/sisu_manual/ + +.BR +Available man pages are converted back to html using man2html: + +.BR + /usr/share/doc/sisu/html/ + +.BR + ./data/doc/sisu/html/ + +.BR +The +.B SiSU +man pages can be viewed online at:[^1] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^2] + +.BR +* sisu.1 \ [^3] + +.BR +* sisu.8 \ [^4] + +.BR +* sisu_examples.1 \ [^5] + +.BR +* sisu_webrick.1 \ [^6] + +.SH +1.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +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. + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR +Apart from real\-time information on your current configuration the +.B 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). + +.BR +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. + +.SH +1.4 HELP SOURCES + +.BR +For lists of alternative help sources, see: + +.BR +.B man page + +.BR + man sisu_help_sources + +.BR +.B man2html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR +.B sisu generated html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources/index.html + +.BR + + +.BR + + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Manual \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-08\-30 + +.BR +DC Date: +.I 2007\-08\-30 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_help.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_help.sst)= +.I 387208846e53080b55b39cf92b70aaa9 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:42 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +generated from source using rman + + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + +.TP +.BI 2. + +.TP +.BI 3. + +.TP +.BI 4. + +.TP +.BI 5. + +.TP +.BI 6. + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_help/sisu_help.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:49 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_help_sources.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_help_sources.1 new file mode 100644 index 00000000..5d85e009 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_help_sources.1 @@ -0,0 +1,729 @@ +.TH "sisu_help_sources" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- REFERENCES, +RALPH AMISSAH +.BR + +.SH +SISU HELP SOURCES +.BR + +.SH +1. HELP SOURCES +.BR + +.BR +For a summary of alternative ways to get help on +.B SiSU +try one of the following: + +.BR +.B man page + +.BR + man sisu_help + +.BR +.B man2html + +.BR + + +.BR + + +.BR +.B sisu generated output \- links to html + +.BR + + +.BR + + +.BR + + +.BR +.B help sources lists + +.BR +Alternative sources for this help sources page listed here: + +.BR + man sisu_help_sources + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +1.1 MAN PAGES + +.SH +1.1.1 MAN + +.BR + man sisu + +.BR + man sisu_commands + +.BR + man 7 sisu_complete + +.BR + man sisu_configuration + +.BR + man 8 sisu_faq + +.BR + man sisu_filetypes + +.BR + man sisu_help + +.BR + man sisu_help_sources + +.BR + man 8 sisu_howto + +.BR + man sisu_introduction + +.BR + man sisu_markup + +.BR + man sisu_output_overview + +.BR + man 7 sisu_pdf + +.BR + man 7 sisu_postgresql + +.BR + man 8 sisu_quickstart + +.BR + man 8 sisu_remote + +.BR + man 8 sisu_search + +.BR + man sisu_skin + +.BR + man 7 sisu_sqlite + +.BR + man 8 sisu_syntax_highlighting + +.BR + man 7 sisu_vim + +.BR + man sisu_webrick + +.SH +1.2 SISU GENERATED OUTPUT \- LINKS TO HTML + +.BR +Note +.B SiSU +documentation is prepared in +.B 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[^1] + +.SH +1.2.1 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/sisu_manual/sisu/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_commands/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_complete/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_configuration/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_description/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_examples/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_faq/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_filetypes/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_howto/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_introduction/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_manual/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_markup/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_output_overview/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_pdf/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_postgresql/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_quickstart/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_remote/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_search/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_skin/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_sqlite/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_vim/index.html + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_webrick/index.html + +.SH +1.2.2 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +1.2.3 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +1.2.4 MAN2HTML + +.SH +1.2.5 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/html/sisu.1.html + +.BR + /usr/share/doc/sisu/html/sisu_commands.1.html + +.BR + /usr/share/doc/sisu/html/sisu_complete.7.html + +.BR + /usr/share/doc/sisu/html/sisu_configuration.1.html + +.BR + /usr/share/doc/sisu/html/sisu_faq.8.html + +.BR + /usr/share/doc/sisu/html/sisu_help.1.html + +.BR + /usr/share/doc/sisu/html/sisu_help_sources.1.html + +.BR + /usr/share/doc/sisu/html/sisu_howto.8.html + +.BR + /usr/share/doc/sisu/html/sisu_markup.1.html + +.BR + /usr/share/doc/sisu/html/sisu_pdf.7.html + +.BR + /usr/share/doc/sisu/html/sisu_postgresql.7.html + +.BR + /usr/share/doc/sisu/html/sisu_quickstart.8.html + +.BR + /usr/share/doc/sisu/html/sisu_remote.8.html + +.BR + /usr/share/doc/sisu/html/sisu_search.8.html + +.BR + /usr/share/doc/sisu/html/sisu_skin.1.html + +.BR + /usr/share/doc/sisu/html/sisu_sqlite.7.html + +.BR + /usr/share/doc/sisu/html/sisu_syntax_highlighting.8.html + +.BR + /usr/share/doc/sisu/html/sisu_vim.7.html + +.BR + /usr/share/doc/sisu/html/sisu_webrick.1.html + +.SH +1.2.6 WWW.SISUDOC.ORG + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +1.2.7 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- References + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_help_sources.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_help_sources.sst)= +.I ff6812b3008391d7a20d777bbbeb3ec1 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:42 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +named index.html or more extensively through sisu_manifest.html + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_help_sources/sisu_help_sources.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_howto.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_howto.1 new file mode 100644 index 00000000..681193fb --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_howto.1 @@ -0,0 +1,2283 @@ +.TH "sisu_howto" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- TECHNICAL, HOWTO, +RALPH AMISSAH +.BR + +.SH +SISU SOME TECHNICAL INFORMATION +.BR + +.SH +HOWTO +.BR + +.SH +1. GETTING HELP +.BR + +.BR +An online manual of sorts should be available at: + +.BR + + +.BR +The manual pages provided with +.B 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. + +.SH +1.1 SISU \"MAN\" PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR +man sisu + +.BR +The +.B SiSU +man pages can be viewed online at:[^1] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^2] + +.BR +* sisu.1 \ [^3] + +.BR +* sisu.8 \ [^4] + +.BR +* sisu_examples.1 \ [^5] + +.BR +* sisu_webrick.1 \ [^6] + +.SH +1.2 SISU BUILT\-IN HELP + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.SH +1.3 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. + +.BR +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. + +.SH +2. SETUP, INITIALISATION +.BR + +.SH +2.1 INITIALISE OUTPUT DIRECTORY + +.BR +Images, css files for a document directory are copied to their respective +locations in the output directory. + +.BR +while within your document markup/preparation directory, issue the following +command + +.BR + sisu \-CC + +.SH +2.1.1 USE OF SEARCH FUNCTIONALITY, AN EXAMPLE USING SQLITE + +.BR +.B SiSU +can populate PostgreSQL and Sqlite databases and provides a sample search +form for querying these databases. + +.BR +This note provides an example to get you started and will use sqlite + +.BR +It is necessary to: + +.BR +(1) make sure the required dependencies have been installed + +.BR +(2) have a directory with sisu markup samples that is writable + +.BR +(3) use sisu to create a database + +.BR +(4) use sisu tp populate a database + +.BR +(5) use sisu to start the webrick (httpd) server + +.BR +(6) use sisu to create a search form + +.BR +(7) copy the search form to the cgi directory + +.BR +(8) open up the form in your browser + +.BR +(9) query the database using the search form + +.BR +.B (1) make sure the required dependencies have been installed + +.BR +if you use +.B Debian +, the following command will install the required dependencies + +.BR +aptitude install sisu\-sqlite + +.BR +.B (2) have a directory with sisu markup samples that is writable + +.BR +ideally copy the sisu\-examples directory to your home directory (because the +directory in which you run this example should be writable) + +.BR +cp \-rv /usr/share/sisu\-examples/sample/document_samples_sisu_markup ~/. + +.BR +.B (3) use sisu to create an sqlite database + +.BR +within the sisu\-examples directory + +.BR +sisu \-dv createall + +.BR +.B (4) use sisu tp populate a database with some text + +.BR +within the sisu\-examples directory + +.BR +sisu \-div free_*.sst + +.BR +or + +.BR +sisu \-dv import free_*.sst debian_constitution_v1.2.sst +debian_social_contract_v1.1.sst gpl2.fsf.sst + +.BR +.B (5) use sisu to start the webrick (httpd) server (if it has not already +been started): + +.BR +sisu \-W + +.BR +.B (6) use sisu to create a search form (for use with the webrick server, and +your sample documents) + +.BR +within the sisu\-examples directory + +.BR +sisu \-F webrick + +.BR +#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 + +.BR +#now this should be possible: sisu \-F webrick + +.BR +.B (7) copy the search form to the cgi directory + +.BR +the string should be provided as output from the previous command + +.BR +sudo cp \-vi +/usr/share/sisu\-examples/sample/document_samples_sisu_markup/sisu_sqlite.cgi +/usr/lib/cgi\-bin + +.BR +sudo chmod \-v 755 /usr/lib/cgi\-bin/sisu_sqlite.cgi + +.BR +.B (8) open up the form in your browser and query it + +.BR +url: + +.BR + + +.BR +or as instructed by command sisu \-F webrick + +.BR +.B (9) query the database using the search form + +.BR +if there are other options in the dropdown menu select + +.BR +document_samples_sisu_markup + +.BR +and search for some text, e.g.: + +.BR +aim OR project + +.BR +* selecting the +.B index +radio button gives an index of results using the object numbers + +.BR +* selecting the +.B text +radio button gives the content of the matched paragraphs with the match +highlighted + +.BR +.B (10) to start again with a new database + +.BR +to start from scratch you can drop the database with the command + +.BR +sisu \-dv dropall + +.BR +and go to step 3 + +.BR +to get to step 3 in one step with a single command + +.BR +sisu \-dv recreate + +.BR +continue subsequent steps + +.SH +2.2 MISC + +.SH +2.2.1 URL FOR OUTPUT FILES \-U \-U + +.BR + sisu \-uv[and \ other \ flags] \ [filename/wildcard] + +.BR + sisu \-Uv \ [filename/wildcard] + +.SH +2.2.2 TOGGLE SCREEN COLOR + +.BR + sisu \-cv[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.3 VERBOSE MODE + +.BR + sisu \-v[and \ processing \ flags] \ [filename/wildcard] + +.BR + sisu \-V[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.4 QUIET MODE + +.BR + sisu \-q[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.5 MAINTENANCE MODE INTERMEDIATE FILES KEPT \-M + +.BR + sisu \-Mv[and \ other \ flags] \ [filename/wildcard] + +.SH +2.2.6 START THE WEBRICK SERVER + +.BR + sisu \-W + +.SH +2.3 REMOTE PLACEMENT OF OUTPUT + +.BR +configuration is necessary + +.BR +scp + +.BR + sisu \-vr[and \ processing \ flags] \ [filename/wildcard] + +.BR +rsync + +.BR + sisu \-vR[and \ processing \ flags] \ [filename/wildcard] + +.SH +3. CONFIGURATION FILES +.BR + +.BR +Sample provided, on untarring the source tarball: + +.BR + conf/sisu/sisurc.yaml + +.BR +and on installation under: + +.BR + /etc/sisu/sisurc.yaml + +.BR +The following paths are searched: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + ./etc/sisu/sisurc.yaml + +.SH +4. MARKUP +.BR + +.BR +See sample markup provided on + +.BR + + +.BR + + +.BR + + +.BR +in particular for each of the document output samples provided, the source +document is provided as well + +.BR + + +.BR +on untarring the source tarball: + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +or the same once source is installed (or sisu\-examples) under: + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +Some notes are contained within the man page, +.B man sisu +and within sisu help via the commands +.B sisu help markup +and +.B sisu help headers + +.BR +.B 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: + +.SH +4.1 HEADERS + +.BR +Headers @headername: provide information related to the document, this may +relate to + +.BR +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 + +.BR +2. semantic information about the document including the dublin core + +.SH +4.2 FONT FACE + +.BR +Defaults are set. You may change the face to: bold, italics, underscore, +strikethrough, ... + +.SH +4.2.1 BOLD + +.BR +\@bold: \ [list \ of \ words \ that \ should \ be \ made \ bold \ within \ +document] + +.BR +.B bold line + +.BR +!_ bold line + +.BR +.B bold word or sentence + +.BR +!{ bold word or sentence }! + +.BR +*{ bold word or sentence }* + +.BR +.B boldword +or +.B boldword + +.BR +*boldword* or !boldword! + +.SH +4.2.2 ITALICS + +.BR +\@italics: \ [list \ of \ words \ that \ should \ be \ italicised \ within \ +document] + +.BR +.I italicise word or sentence + +.BR +/{ italicise word or sentence }/ + +.BR +.I italicisedword + +.BR +/italicisedword/ + +.SH +4.2.3 UNDERSCORE + +.BR +.I underscore word or sentence + +.BR +_{ underscore word or sentence }_ + +.BR +.I underscoreword + +.SH +4.2.4 STRIKETHROUGH + +.BR + strikethrough word or sentence + +.BR +\-{ strikethrough word or sentence }\- + +.BR +strikeword + +.BR +\-strikeword\- + +.SH +4.3 ENDNOTES + +.BR +There are two forms of markup for endnotes, they cannot be mixed within the +same document + +.BR +here[^7] + +.BR +1. preferred endnote markup + +.BR +here~{ this is an endnote }~ + +.BR +2. alternative markup equivalent, kept because it is possible to search and +replace to get markup in existing texts such as Project Gutenberg + +.BR +here~^ + +.BR +^~ this is an endote + +.SH +4.4 LINKS + +.BR +SiSU + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +sisu.png 120x39 + +.BR +{sisu.png }http://sisudoc.org + +.BR +[ tux.png ] + +.BR +{ tux.png 64x80 }image + +.BR +SiSU \ [^8] + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +is equivalent to: + +.BR +{ +.B SiSU +}http://sisudoc.org ~{ }~ + +.BR +the same can be done with an image: + +.BR +sisu.png 120x39 \"SiSU\" \ [^10] + +.BR +{ sisu.png \" +.B SiSU +\" }http://sisudoc.org + +.SH +4.5 NUMBER TITLES + +.BR +Set with the header @markup: + +.SH +4.6 LINE OPERATIONS + +.BR +Line Operations (marker placed at start of line) + +.BR +!_ bold line + +.BR +.B bold line + +.BR +_1 indent paragraph one level + +.BR + indent paragraph one level + +.BR +_2 indent paragraph two steps + +.BR + indent paragraph two steps + +.BR +_* bullet paragraph + +.BR +* bullet paragraph + +.BR +# number paragraph (see headers for numbering document headings) + +.BR +1. number paragraph (see headers for numbering document headings) + +.BR +_# number paragraph level 2 (see headers for numbering document headings) + +.BR + a. number paragraph level 2 (see headers for numbering document headings) + +.SH +4.7 TABLES + +.BR +Table markup sample + + +table{~h c3; 26; 32; 32; +.P + + +This is a table, column1 +.P +this would become row one of column two +.P +column three of row one is here +.P + + +column one row 2 +.P +column two of row two +.P +column three of row two, and so on +.P + + +column one row three +.P +and so on +.P +here +.P + + +}table +.P + +.BR +Alternative form of table markup + + +.nf + {t\~h} + |Mon|Tue|Wed|Thu|Fri|Sat|Sun + 0 | * | * | * | * | * | * | * + 1 | * | * | * | * | | | + 2 | \- | * | * | * | * | * | + 3 | \- | * | * | * | * | * | * + 4 | \- | | | * | * | * | + 5 | * | * | * | * | * | * | * +.fi + +.SH +4.8 GROUPED TEXT + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +code{ + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +}code + + +A Limerick +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +poem{ +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +}\poem +.P + +.SH +4.9 COMPOSITE DOCUMENT + +.BR +To import another document, the master document or importing document should be +named filename.r3 (r for require) + +.BR +<< { filename.sst } + +.BR +<< { filename.ssi } + +.SH +5. CHANGE APPEARANCE +.BR + +.SH +5.1 SKINS + +.BR +\"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 +.B SiSU +output. + +.BR +There are a few examples provided, on untarring the source tarball: + +.BR + conf/sisu/skin/doc/ + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +and on installation under: + +.BR + /etc/sisu/skin/doc/ + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +The following paths are searched: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +Skins under the searched paths in a per document directory, a per directory +directory, or a site directory, named: + +.BR +doc \ [may \ be \ specified \ individually \ in \ each \ document] + +.BR +dir \ [used \ if \ identifier \ part \ of \ name \ matches \ markup \ directory +\ name] + +.BR +site + +.BR +It is usual to place all skins in the document directory, with symbolic links +as required from dir or site directories. + +.SH +5.2 CSS + +.BR +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: + +.BR +_./_sisu/css + +.BR +~/.sisu/css + +.BR +and + +.BR +/etc/sisu/css + +.BR +The contents of the first directory found in the search path are copied to the +corresponding sisu output directory with the commnd: + +.BR +sisu \-CC + +.BR +The +.B SiSU +standard css files for +.B SiSU +output are: + +.BR +dom.css html.css html_tables.css index.css sax.css xhtml.css + +.BR +A document may specify its own/bespoke css file using the css header. + +.BR +\@css: + +.BR +[expand] + +.SH +EXTRACTS FROM THE README +.BR + +.SH +6. README +.BR + +.BR +.B SiSU +0.55 2007w27/6 2007\-07\-07 + +.BR +Homepage: + +.BR +.B Description + +.BR +.B SiSU +is lightweight markup based document creation and publishing framework that +is controlled from the command line. Prepare documents for +.B SiSU +using your text editor of choice, then use +.B SiSU +to generate various output document formats. + +.BR +With minimal preparation of a plain\-text (UTF\-8) file using its native +markup\-syntax, +.B 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. + +.BR +Outputs share a common citation numbering system, and any semantic meta\-data +provided about the document. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +.B 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. +.B 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). + +.BR +A vim syntax highlighting file and an ftplugin with folds for sisu markup is +provided. Vim 7 includes syntax highlighting for +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: + +.BR +.B 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. + +.BR +.B SiSU +can be used for Internet, Intranet, local filesystem or cd publishing. + +.BR +.B SiSU +can be used directly off the filesystem, or from a database. + +.BR +.B SiSU +\'s scalability, is be dependent on your hardware, and filesystem (in my case +Reiserfs), and/or database Postgresql. + +.BR +Amongst it\'s characteristics are: + +.BR +* simple mnemonoic markup style, + +.BR +* 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, + +.BR +* 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. + +.BR +* it is command line driven, and can be set up on a remote server + +.BR +* Documents are marked up in +.B SiSU +syntax in your favourite editor. +.B 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. + +.BR +Input files should be UTF\-8 + +.BR +Once set up it is simple to use. + +.SH +6.1 ONLINE INFORMATION, PLACES TO LOOK + +.BR + + +.BR +Download Sources: + +.BR + + +.BR + + +.SH +6.2 INSTALLATION + +.BR +NB. Platform is Unix / Linux. + +.SH +6.2.1 DEBIAN + +.BR +If you use +.B Debian +use the +.B Debian +packages, check the information at: + +.BR + + +.BR +(A) +.B SiSU +is available directly off the +.B Debian +archives for Sid and testing. It should necessary only to run as root: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.BR +(B) If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + +.BR + deb unstable main non\-free + +.BR + deb\-src unstable main non\-free + +.BR +[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] + +.BR +Then as root run: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.SH +6.2.2 RPM + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.SH +6.2.3 SOURCE PACKAGE .TGZ + +.BR +Otherwise to install +.B SiSU +from source, check information at: + +.BR + + +.BR +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, + +.BR +.B Ruby +is the essential dependency for the basic operation of +.B SiSU + +.BR +1. Download the latest source (information available) from: + +.BR + + +.BR +2. Unpack the source + +.BR +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. + +.SH +6.2.4 TO USE SETUP.RB + +.BR +this is a three step process, in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby setup.rb config + +.BR + ruby setup.rb setup + +.BR +as root: + +.BR + ruby setup.rb install + +.BR +further information: + +.BR + + +.BR + + +.SH +6.2.5 TO USE INSTALL (PRAPARED WITH \"RAKE\") + +.BR +Rake must be installed on your system: + +.BR + + +.BR + + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + rake + +.BR +or + +.BR + rake base + +.BR +This makes use of Rake (by Jim Weirich) and the provided Rakefile + +.BR +For a list of alternative actions you may type: + +.BR + rake help + +.BR + rake \-T + +.SH +6.2.6 TO USE INSTALL (PRAPARED WITH \"RANT\") + +.BR +(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:) + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby ./sisu\-install + +.BR +or + +.BR + ruby ./sisu\-install base + +.BR +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. + +.BR +further information: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby ./sisu\-install help + +.BR + ruby ./sisu\-install \-T + +.SH +6.3 DEPENDENCIES + +.BR +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 +.B 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. + +.BR +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 +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +). + +.BR +The following is from the debian/control file of sisu\-0.58.2, which amongst +other things provides the dependencies of sisu within +.B Debian +. + + +.nf + 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 +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + +.SH +6.4 QUICK START + +.BR +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). + +.BR +After installation of sisu\-complete, move to the document samples directory + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +and run + +.BR + sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +or to generate an online document move to a writable directory, as the file +will be downloaded there and e.g. + +.BR +sisu \-3 + + +.BR +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 + +.BR +examine source document, vim has syntax support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + + +.BR +For help + +.BR + man sisu + +.BR +or + +.BR + sisu \-\-help + +.BR +e.g. + +.BR +for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help env + +.BR +for list of commands and so on + +.BR + sisu \-\-help commands + +.SH +6.5 CONFIGURATION FILES + +.BR +The default configuration/setup is contained within the program and is altered +by configuration settings in +.I etc +[sisu \ version]/sisurc.yml or in ~/.sisu/sisurc.yml + +.BR +* configuration file \- a yaml file + +.BR + /etc/sisu/[sisu \ version]/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR +* directory structure \- setting up of output and working directory. + +.BR +* skins \- changing the appearance of a project, directory or individual +documents within ~/.sisu/skin + +.BR + ~/.sisu/skin/doc contains individual skins, with symbolic links from + +.BR + ~/.sisu/skin/dir if the contents of a directory are to take a particular + document skin. + +.BR +* additional software \- eg. Tex and LaTeX (tetex, tetex\-base, tetex\-extra on +.B Debian +), Postgresql, \ [sqlite], trang, tidy, makeinfo, ... none of which are +required for basic html or XML processing. + +.BR +* if you use Vim as editor there is a syntax highlighter and fold resource +config file for +.B SiSU +. I hope more syntax highlighters follow. + +.BR +There are post installation steps (which are really part of the overall +installation) + +.BR +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). + +.SH +6.6 USE GENERAL OVERVIEW + +.BR +Documents are marked up in +.B SiSU +syntax and kept in an ordinary text editable file, named with the suffix +.sst, or .ssm + +.BR +Marked up +.B SiSU +documents are usually kept in a sub\-directory of your choosing + +.BR +use the interactive help and man pages + +.BR + sisu \-\-help + +.BR + man sisu + +.SH +6.7 HELP + +.BR +interactive help described below, or man page: + +.BR + man sisu + +.BR + man 8 sisu + +.BR +\'man sisu_markup\-samples\' \ [if \ the \ sisu\-markup\-samples \ package \ is +\ also \ installed] + +.BR +Once installed an interactive help is available typing \'sisu\' (without) any +flags, and select an option: + +.BR + sisu + +.BR +alternatively, you could type e.g. + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help env + +.BR + sisu \-\-help headers + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help headings + +.BR +etc. + +.BR +for questions about mappings, output paths etc. + +.BR + sisu \-\-help env + +.BR + sisu \-\-help path + +.BR + sisu \-\-help directory + +.SH +6.8 DIRECTORY STRUCTURE + +.BR +Once installed, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.SH +6.9 CONFIGURATION FILE + +.BR +The defaults can be changed via +.B 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) + +.SH +6.10 MARKUP + +.BR +See man pages. + +.BR + man sisu + +.BR + man 8 sisu + +.BR +Once installed there is some information on +.B SiSU +Markup in its help: + +.BR + sisu \-\-help markup + +.BR +and + +.BR + sisu \-\-help headers + +.BR +Sample marked up document are provided with the download tarball in the +directory: + +.BR + ./data/doc/sisu/sisu_markup_samples/dfsg + +.BR +These are installed on the system usually at: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +More markup samples are available in the package sisu\-markup\-samples + +.BR + + +.BR +Many more are available online off: + +.BR + + +.SH +6.11 ADDITIONAL THINGS + +.BR +There is syntax support for some editors provided (together with a README file) +in + +.BR + ./data/sisu/conf/syntax + +.BR +usually installed to: + +.BR + /usr/share/sisu/conf/syntax + +.SH +6.12 LICENSE + +.BR +License: GPL 3 or later see the copyright file in + +.BR + ./data/doc/sisu + +.BR +usually installed to: + +.BR + /usr/share/doc/sisu + +.SH +6.13 SISU STANDARD + +.BR +.B SiSU +uses: + +.BR +* Standard +.B SiSU +markup syntax, + +.BR +* Standard +.B SiSU +meta\-markup syntax, and the + +.BR +* Standard +.B SiSU +object citation numbering and system + +.BR +© Ralph Amissah 1997, current 2006 All Rights Reserved. + +.BR +* however note the License section + +.BR +CHANGELOG + +.BR + ./CHANGELOG + +.BR +and see + +.BR + + +.BR + + +.SH +EXTRACTS FROM MAN 8 SISU +.BR + +.SH +7. POST INSTALLATION SETUP +.BR + +.SH +7.1 POST INSTALLATION SETUP \- QUICK START + +.BR +After installation of sisu\-complete, move to the document samples directory, + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +[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] + +.BR +and in that directory, initialise the output directory with the command + +.BR + sisu \-CC + +.BR +then run: + +.BR + sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +for an overview of your current sisu setup, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.BR +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. + +.BR + sisu \-1 + +.BR + sisu \-3 + + +.BR +examine source document, vim has syntax highlighting support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + + +.BR +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. + +.BR + sisu \-3 + + +.BR +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: + +.BR + sisu \-3 \-\-trust + + +.BR +For help + +.BR + man sisu + +.BR + sisu \-\-help + +.BR + sisu \-\-help env for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help commands for list of commands and so on + +.SH +7.2 DOCUMENT MARKUP DIRECTORY + +.BR +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: + +.BR + mkdir ~/sisu_test + +.BR + cd ~/sisu_test + +.BR + cp \-a /usr/share/doc/sisu/sisu_markup_samples/dfsg/* ~/sisu_test/. + +.BR +.B Tip: +the markup syntax examples may be of interest + +.BR + + +.BR +.B Tip: + +.BR + sisu \-U \ [sisu \ markup \ filename] + +.BR +should printout the different possible outputs and where sisu would place them. + +.BR +.B Tip: +if you want to toggle ansi color add + +.BR + c + +.BR +to your flags. + +.SH +7.2.1 CONFIGURATION FILES + +.BR +.B SiSU +configuration file search path is: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/sisurc.yaml + +.BR +.\\"%% +.B Debian +Installation Note + +.SH +7.2.2 DEBIAN INSTALLATION NOTE + +.BR +It is best you see + +.BR + + +.BR +for up the most up to date information. + +.BR +notes taken from the +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +): + +.BR +Package: sisu + +.BR +.B SiSU +is a lightweight markup based, command line oriented, document structuring, +publishing and search framework for document collections. + +.BR +With minimal preparation of a plain\-text, (UTF\-8) file, using its native +markup syntax in your text editor of choice, +.B 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. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +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 +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: + +.SH +7.2.3 DOCUMENT RESOURCE CONFIGURATION + +.BR +.B sisu +resource configuration information is obtained from sources (where they +exist): + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/[sisu \ version]/sisurc.yaml + +.BR + sisu program defaults + +.SH +7.2.4 SKINS + +.BR +.B Skins +default document appearance may be modified using skins contained in +sub\-directories located at the following paths: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +more specifically, the following locations (or their /etc/sisu equivalent) +should be used: + +.BR + ~/.sisu/skin/doc + +.BR +skins for individual documents; + +.BR + ~/.sisu/skin/dir + +.BR +skins for directories of matching names; + +.BR + ~/.sisu/skin/site + +.BR +site\-wide skin modifying the site\-wide appearance of documents. + +.BR +Usually all skin files are placed in the document skin directory: + +.BR + ~/.sisu/skin/doc + +.BR +with softlinks being made to the skins contained there from other skin +directories as required. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Technical, Howto + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_howto.sst + +.BR +Filetype: +.I SiSU text insert 0.57 + +.BR +Sourcefile Digest, MD5(sisu_howto.sst)= +.I 82c606e66689bcb5d190edf8fc7227a0 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:45 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +generated from source using rman + + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + +.TP +.BI 2. + +.TP +.BI 3. + +.TP +.BI 4. + +.TP +.BI 5. + +.TP +.BI 6. + +.TP +.BI 7. +this is an endnote +.TP +.BI 8. + +.TP +.BI 10. + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_howto/sisu_howto.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_howto.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_howto.8 new file mode 100644 index 00000000..42bd1caf --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_howto.8 @@ -0,0 +1,2283 @@ +.TH "sisu_howto" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- TECHNICAL, HOWTO, +RALPH AMISSAH +.BR + +.SH +SISU SOME TECHNICAL INFORMATION +.BR + +.SH +HOWTO +.BR + +.SH +1. GETTING HELP +.BR + +.BR +An online manual of sorts should be available at: + +.BR + + +.BR +The manual pages provided with +.B 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. + +.SH +1.1 SISU \"MAN\" PAGES + +.BR +If +.B SiSU +is installed on your system usual man commands should be available, try: + +.BR +man sisu + +.BR +The +.B SiSU +man pages can be viewed online at:[^1] + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages \ [^2] + +.BR +* sisu.1 \ [^3] + +.BR +* sisu.8 \ [^4] + +.BR +* sisu_examples.1 \ [^5] + +.BR +* sisu_webrick.1 \ [^6] + +.SH +1.2 SISU BUILT\-IN HELP + +.BR + sisu \-\-help + +.BR + sisu \-\-help \ [subject] + +.BR + sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V \ [same \ as \ above \ command] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.SH +1.3 COMMAND LINE WITH FLAGS \- BATCH PROCESSING + +.BR +Running sisu (alone without any flags, filenames or wildcards) brings up the +interactive help, as does any sisu command that is not recognised. + +.BR +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. + +.SH +2. SETUP, INITIALISATION +.BR + +.SH +2.1 INITIALISE OUTPUT DIRECTORY + +.BR +Images, css files for a document directory are copied to their respective +locations in the output directory. + +.BR +while within your document markup/preparation directory, issue the following +command + +.BR + sisu \-CC + +.SH +2.1.1 USE OF SEARCH FUNCTIONALITY, AN EXAMPLE USING SQLITE + +.BR +.B SiSU +can populate PostgreSQL and Sqlite databases and provides a sample search +form for querying these databases. + +.BR +This note provides an example to get you started and will use sqlite + +.BR +It is necessary to: + +.BR +(1) make sure the required dependencies have been installed + +.BR +(2) have a directory with sisu markup samples that is writable + +.BR +(3) use sisu to create a database + +.BR +(4) use sisu tp populate a database + +.BR +(5) use sisu to start the webrick (httpd) server + +.BR +(6) use sisu to create a search form + +.BR +(7) copy the search form to the cgi directory + +.BR +(8) open up the form in your browser + +.BR +(9) query the database using the search form + +.BR +.B (1) make sure the required dependencies have been installed + +.BR +if you use +.B Debian +, the following command will install the required dependencies + +.BR +aptitude install sisu\-sqlite + +.BR +.B (2) have a directory with sisu markup samples that is writable + +.BR +ideally copy the sisu\-examples directory to your home directory (because the +directory in which you run this example should be writable) + +.BR +cp \-rv /usr/share/sisu\-examples/sample/document_samples_sisu_markup ~/. + +.BR +.B (3) use sisu to create an sqlite database + +.BR +within the sisu\-examples directory + +.BR +sisu \-dv createall + +.BR +.B (4) use sisu tp populate a database with some text + +.BR +within the sisu\-examples directory + +.BR +sisu \-div free_*.sst + +.BR +or + +.BR +sisu \-dv import free_*.sst debian_constitution_v1.2.sst +debian_social_contract_v1.1.sst gpl2.fsf.sst + +.BR +.B (5) use sisu to start the webrick (httpd) server (if it has not already +been started): + +.BR +sisu \-W + +.BR +.B (6) use sisu to create a search form (for use with the webrick server, and +your sample documents) + +.BR +within the sisu\-examples directory + +.BR +sisu \-F webrick + +.BR +#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 + +.BR +#now this should be possible: sisu \-F webrick + +.BR +.B (7) copy the search form to the cgi directory + +.BR +the string should be provided as output from the previous command + +.BR +sudo cp \-vi +/usr/share/sisu\-examples/sample/document_samples_sisu_markup/sisu_sqlite.cgi +/usr/lib/cgi\-bin + +.BR +sudo chmod \-v 755 /usr/lib/cgi\-bin/sisu_sqlite.cgi + +.BR +.B (8) open up the form in your browser and query it + +.BR +url: + +.BR + + +.BR +or as instructed by command sisu \-F webrick + +.BR +.B (9) query the database using the search form + +.BR +if there are other options in the dropdown menu select + +.BR +document_samples_sisu_markup + +.BR +and search for some text, e.g.: + +.BR +aim OR project + +.BR +* selecting the +.B index +radio button gives an index of results using the object numbers + +.BR +* selecting the +.B text +radio button gives the content of the matched paragraphs with the match +highlighted + +.BR +.B (10) to start again with a new database + +.BR +to start from scratch you can drop the database with the command + +.BR +sisu \-dv dropall + +.BR +and go to step 3 + +.BR +to get to step 3 in one step with a single command + +.BR +sisu \-dv recreate + +.BR +continue subsequent steps + +.SH +2.2 MISC + +.SH +2.2.1 URL FOR OUTPUT FILES \-U \-U + +.BR + sisu \-uv[and \ other \ flags] \ [filename/wildcard] + +.BR + sisu \-Uv \ [filename/wildcard] + +.SH +2.2.2 TOGGLE SCREEN COLOR + +.BR + sisu \-cv[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.3 VERBOSE MODE + +.BR + sisu \-v[and \ processing \ flags] \ [filename/wildcard] + +.BR + sisu \-V[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.4 QUIET MODE + +.BR + sisu \-q[and \ processing \ flags] \ [filename/wildcard] + +.SH +2.2.5 MAINTENANCE MODE INTERMEDIATE FILES KEPT \-M + +.BR + sisu \-Mv[and \ other \ flags] \ [filename/wildcard] + +.SH +2.2.6 START THE WEBRICK SERVER + +.BR + sisu \-W + +.SH +2.3 REMOTE PLACEMENT OF OUTPUT + +.BR +configuration is necessary + +.BR +scp + +.BR + sisu \-vr[and \ processing \ flags] \ [filename/wildcard] + +.BR +rsync + +.BR + sisu \-vR[and \ processing \ flags] \ [filename/wildcard] + +.SH +3. CONFIGURATION FILES +.BR + +.BR +Sample provided, on untarring the source tarball: + +.BR + conf/sisu/sisurc.yaml + +.BR +and on installation under: + +.BR + /etc/sisu/sisurc.yaml + +.BR +The following paths are searched: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + ./etc/sisu/sisurc.yaml + +.SH +4. MARKUP +.BR + +.BR +See sample markup provided on + +.BR + + +.BR + + +.BR + + +.BR +in particular for each of the document output samples provided, the source +document is provided as well + +.BR + + +.BR +on untarring the source tarball: + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +or the same once source is installed (or sisu\-examples) under: + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/ + +.BR +Some notes are contained within the man page, +.B man sisu +and within sisu help via the commands +.B sisu help markup +and +.B sisu help headers + +.BR +.B 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: + +.SH +4.1 HEADERS + +.BR +Headers @headername: provide information related to the document, this may +relate to + +.BR +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 + +.BR +2. semantic information about the document including the dublin core + +.SH +4.2 FONT FACE + +.BR +Defaults are set. You may change the face to: bold, italics, underscore, +strikethrough, ... + +.SH +4.2.1 BOLD + +.BR +\@bold: \ [list \ of \ words \ that \ should \ be \ made \ bold \ within \ +document] + +.BR +.B bold line + +.BR +!_ bold line + +.BR +.B bold word or sentence + +.BR +!{ bold word or sentence }! + +.BR +*{ bold word or sentence }* + +.BR +.B boldword +or +.B boldword + +.BR +*boldword* or !boldword! + +.SH +4.2.2 ITALICS + +.BR +\@italics: \ [list \ of \ words \ that \ should \ be \ italicised \ within \ +document] + +.BR +.I italicise word or sentence + +.BR +/{ italicise word or sentence }/ + +.BR +.I italicisedword + +.BR +/italicisedword/ + +.SH +4.2.3 UNDERSCORE + +.BR +.I underscore word or sentence + +.BR +_{ underscore word or sentence }_ + +.BR +.I underscoreword + +.SH +4.2.4 STRIKETHROUGH + +.BR + strikethrough word or sentence + +.BR +\-{ strikethrough word or sentence }\- + +.BR +strikeword + +.BR +\-strikeword\- + +.SH +4.3 ENDNOTES + +.BR +There are two forms of markup for endnotes, they cannot be mixed within the +same document + +.BR +here[^7] + +.BR +1. preferred endnote markup + +.BR +here~{ this is an endnote }~ + +.BR +2. alternative markup equivalent, kept because it is possible to search and +replace to get markup in existing texts such as Project Gutenberg + +.BR +here~^ + +.BR +^~ this is an endote + +.SH +4.4 LINKS + +.BR +SiSU + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +sisu.png 120x39 + +.BR +{sisu.png }http://sisudoc.org + +.BR +[ tux.png ] + +.BR +{ tux.png 64x80 }image + +.BR +SiSU \ [^8] + +.BR +{ +.B SiSU +}http://sisudoc.org + +.BR +is equivalent to: + +.BR +{ +.B SiSU +}http://sisudoc.org ~{ }~ + +.BR +the same can be done with an image: + +.BR +sisu.png 120x39 \"SiSU\" \ [^10] + +.BR +{ sisu.png \" +.B SiSU +\" }http://sisudoc.org + +.SH +4.5 NUMBER TITLES + +.BR +Set with the header @markup: + +.SH +4.6 LINE OPERATIONS + +.BR +Line Operations (marker placed at start of line) + +.BR +!_ bold line + +.BR +.B bold line + +.BR +_1 indent paragraph one level + +.BR + indent paragraph one level + +.BR +_2 indent paragraph two steps + +.BR + indent paragraph two steps + +.BR +_* bullet paragraph + +.BR +* bullet paragraph + +.BR +# number paragraph (see headers for numbering document headings) + +.BR +1. number paragraph (see headers for numbering document headings) + +.BR +_# number paragraph level 2 (see headers for numbering document headings) + +.BR + a. number paragraph level 2 (see headers for numbering document headings) + +.SH +4.7 TABLES + +.BR +Table markup sample + + +table{~h c3; 26; 32; 32; +.P + + +This is a table, column1 +.P +this would become row one of column two +.P +column three of row one is here +.P + + +column one row 2 +.P +column two of row two +.P +column three of row two, and so on +.P + + +column one row three +.P +and so on +.P +here +.P + + +}table +.P + +.BR +Alternative form of table markup + + +.nf + {t\~h} + |Mon|Tue|Wed|Thu|Fri|Sat|Sun + 0 | * | * | * | * | * | * | * + 1 | * | * | * | * | | | + 2 | \- | * | * | * | * | * | + 3 | \- | * | * | * | * | * | * + 4 | \- | | | * | * | * | + 5 | * | * | * | * | * | * | * +.fi + +.SH +4.8 GROUPED TEXT + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +code{ + + +.nf + 5.times { puts \'Ruby\' } +.fi + +.BR +}code + + +A Limerick +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +poem{ +.P + + +There was a young lady from Clyde, +.P +who ate a green apple and died, +.P +but the apple fermented inside the lamented, +.P +and made cider inside her inside. +.P + + +}\poem +.P + +.SH +4.9 COMPOSITE DOCUMENT + +.BR +To import another document, the master document or importing document should be +named filename.r3 (r for require) + +.BR +<< { filename.sst } + +.BR +<< { filename.ssi } + +.SH +5. CHANGE APPEARANCE +.BR + +.SH +5.1 SKINS + +.BR +\"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 +.B SiSU +output. + +.BR +There are a few examples provided, on untarring the source tarball: + +.BR + conf/sisu/skin/doc/ + +.BR + data/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +and on installation under: + +.BR + /etc/sisu/skin/doc/ + +.BR + /usr/share/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc + +.BR +The following paths are searched: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +Skins under the searched paths in a per document directory, a per directory +directory, or a site directory, named: + +.BR +doc \ [may \ be \ specified \ individually \ in \ each \ document] + +.BR +dir \ [used \ if \ identifier \ part \ of \ name \ matches \ markup \ directory +\ name] + +.BR +site + +.BR +It is usual to place all skins in the document directory, with symbolic links +as required from dir or site directories. + +.SH +5.2 CSS + +.BR +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: + +.BR +_./_sisu/css + +.BR +~/.sisu/css + +.BR +and + +.BR +/etc/sisu/css + +.BR +The contents of the first directory found in the search path are copied to the +corresponding sisu output directory with the commnd: + +.BR +sisu \-CC + +.BR +The +.B SiSU +standard css files for +.B SiSU +output are: + +.BR +dom.css html.css html_tables.css index.css sax.css xhtml.css + +.BR +A document may specify its own/bespoke css file using the css header. + +.BR +\@css: + +.BR +[expand] + +.SH +EXTRACTS FROM THE README +.BR + +.SH +6. README +.BR + +.BR +.B SiSU +0.55 2007w27/6 2007\-07\-07 + +.BR +Homepage: + +.BR +.B Description + +.BR +.B SiSU +is lightweight markup based document creation and publishing framework that +is controlled from the command line. Prepare documents for +.B SiSU +using your text editor of choice, then use +.B SiSU +to generate various output document formats. + +.BR +With minimal preparation of a plain\-text (UTF\-8) file using its native +markup\-syntax, +.B 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. + +.BR +Outputs share a common citation numbering system, and any semantic meta\-data +provided about the document. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +.B 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. +.B 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). + +.BR +A vim syntax highlighting file and an ftplugin with folds for sisu markup is +provided. Vim 7 includes syntax highlighting for +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: + +.BR +.B 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. + +.BR +.B SiSU +can be used for Internet, Intranet, local filesystem or cd publishing. + +.BR +.B SiSU +can be used directly off the filesystem, or from a database. + +.BR +.B SiSU +\'s scalability, is be dependent on your hardware, and filesystem (in my case +Reiserfs), and/or database Postgresql. + +.BR +Amongst it\'s characteristics are: + +.BR +* simple mnemonoic markup style, + +.BR +* 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, + +.BR +* 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. + +.BR +* it is command line driven, and can be set up on a remote server + +.BR +* Documents are marked up in +.B SiSU +syntax in your favourite editor. +.B 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. + +.BR +Input files should be UTF\-8 + +.BR +Once set up it is simple to use. + +.SH +6.1 ONLINE INFORMATION, PLACES TO LOOK + +.BR + + +.BR +Download Sources: + +.BR + + +.BR + + +.SH +6.2 INSTALLATION + +.BR +NB. Platform is Unix / Linux. + +.SH +6.2.1 DEBIAN + +.BR +If you use +.B Debian +use the +.B Debian +packages, check the information at: + +.BR + + +.BR +(A) +.B SiSU +is available directly off the +.B Debian +archives for Sid and testing. It should necessary only to run as root: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.BR +(B) If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + +.BR + deb unstable main non\-free + +.BR + deb\-src unstable main non\-free + +.BR +[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] + +.BR +Then as root run: + +.BR + aptitude update + +.BR + aptitude install sisu\-complete + +.SH +6.2.2 RPM + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.SH +6.2.3 SOURCE PACKAGE .TGZ + +.BR +Otherwise to install +.B SiSU +from source, check information at: + +.BR + + +.BR +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, + +.BR +.B Ruby +is the essential dependency for the basic operation of +.B SiSU + +.BR +1. Download the latest source (information available) from: + +.BR + + +.BR +2. Unpack the source + +.BR +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. + +.SH +6.2.4 TO USE SETUP.RB + +.BR +this is a three step process, in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby setup.rb config + +.BR + ruby setup.rb setup + +.BR +as root: + +.BR + ruby setup.rb install + +.BR +further information: + +.BR + + +.BR + + +.SH +6.2.5 TO USE INSTALL (PRAPARED WITH \"RAKE\") + +.BR +Rake must be installed on your system: + +.BR + + +.BR + + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + rake + +.BR +or + +.BR + rake base + +.BR +This makes use of Rake (by Jim Weirich) and the provided Rakefile + +.BR +For a list of alternative actions you may type: + +.BR + rake help + +.BR + rake \-T + +.SH +6.2.6 TO USE INSTALL (PRAPARED WITH \"RANT\") + +.BR +(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:) + +.BR +in the root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby ./sisu\-install + +.BR +or + +.BR + ruby ./sisu\-install base + +.BR +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. + +.BR +further information: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby ./sisu\-install help + +.BR + ruby ./sisu\-install \-T + +.SH +6.3 DEPENDENCIES + +.BR +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 +.B 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. + +.BR +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 +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +). + +.BR +The following is from the debian/control file of sisu\-0.58.2, which amongst +other things provides the dependencies of sisu within +.B Debian +. + + +.nf + 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 +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + + +.nf + 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: +.fi + +.SH +6.4 QUICK START + +.BR +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). + +.BR +After installation of sisu\-complete, move to the document samples directory + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +and run + +.BR + sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +or to generate an online document move to a writable directory, as the file +will be downloaded there and e.g. + +.BR +sisu \-3 + + +.BR +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 + +.BR +examine source document, vim has syntax support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + + +.BR +For help + +.BR + man sisu + +.BR +or + +.BR + sisu \-\-help + +.BR +e.g. + +.BR +for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help env + +.BR +for list of commands and so on + +.BR + sisu \-\-help commands + +.SH +6.5 CONFIGURATION FILES + +.BR +The default configuration/setup is contained within the program and is altered +by configuration settings in +.I etc +[sisu \ version]/sisurc.yml or in ~/.sisu/sisurc.yml + +.BR +* configuration file \- a yaml file + +.BR + /etc/sisu/[sisu \ version]/sisurc.yml + +.BR + ~/.sisu/sisurc.yml + +.BR +* directory structure \- setting up of output and working directory. + +.BR +* skins \- changing the appearance of a project, directory or individual +documents within ~/.sisu/skin + +.BR + ~/.sisu/skin/doc contains individual skins, with symbolic links from + +.BR + ~/.sisu/skin/dir if the contents of a directory are to take a particular + document skin. + +.BR +* additional software \- eg. Tex and LaTeX (tetex, tetex\-base, tetex\-extra on +.B Debian +), Postgresql, \ [sqlite], trang, tidy, makeinfo, ... none of which are +required for basic html or XML processing. + +.BR +* if you use Vim as editor there is a syntax highlighter and fold resource +config file for +.B SiSU +. I hope more syntax highlighters follow. + +.BR +There are post installation steps (which are really part of the overall +installation) + +.BR +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). + +.SH +6.6 USE GENERAL OVERVIEW + +.BR +Documents are marked up in +.B SiSU +syntax and kept in an ordinary text editable file, named with the suffix +.sst, or .ssm + +.BR +Marked up +.B SiSU +documents are usually kept in a sub\-directory of your choosing + +.BR +use the interactive help and man pages + +.BR + sisu \-\-help + +.BR + man sisu + +.SH +6.7 HELP + +.BR +interactive help described below, or man page: + +.BR + man sisu + +.BR + man 8 sisu + +.BR +\'man sisu_markup\-samples\' \ [if \ the \ sisu\-markup\-samples \ package \ is +\ also \ installed] + +.BR +Once installed an interactive help is available typing \'sisu\' (without) any +flags, and select an option: + +.BR + sisu + +.BR +alternatively, you could type e.g. + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help env + +.BR + sisu \-\-help headers + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help headings + +.BR +etc. + +.BR +for questions about mappings, output paths etc. + +.BR + sisu \-\-help env + +.BR + sisu \-\-help path + +.BR + sisu \-\-help directory + +.SH +6.8 DIRECTORY STRUCTURE + +.BR +Once installed, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.SH +6.9 CONFIGURATION FILE + +.BR +The defaults can be changed via +.B 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) + +.SH +6.10 MARKUP + +.BR +See man pages. + +.BR + man sisu + +.BR + man 8 sisu + +.BR +Once installed there is some information on +.B SiSU +Markup in its help: + +.BR + sisu \-\-help markup + +.BR +and + +.BR + sisu \-\-help headers + +.BR +Sample marked up document are provided with the download tarball in the +directory: + +.BR + ./data/doc/sisu/sisu_markup_samples/dfsg + +.BR +These are installed on the system usually at: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +More markup samples are available in the package sisu\-markup\-samples + +.BR + + +.BR +Many more are available online off: + +.BR + + +.SH +6.11 ADDITIONAL THINGS + +.BR +There is syntax support for some editors provided (together with a README file) +in + +.BR + ./data/sisu/conf/syntax + +.BR +usually installed to: + +.BR + /usr/share/sisu/conf/syntax + +.SH +6.12 LICENSE + +.BR +License: GPL 3 or later see the copyright file in + +.BR + ./data/doc/sisu + +.BR +usually installed to: + +.BR + /usr/share/doc/sisu + +.SH +6.13 SISU STANDARD + +.BR +.B SiSU +uses: + +.BR +* Standard +.B SiSU +markup syntax, + +.BR +* Standard +.B SiSU +meta\-markup syntax, and the + +.BR +* Standard +.B SiSU +object citation numbering and system + +.BR +© Ralph Amissah 1997, current 2006 All Rights Reserved. + +.BR +* however note the License section + +.BR +CHANGELOG + +.BR + ./CHANGELOG + +.BR +and see + +.BR + + +.BR + + +.SH +EXTRACTS FROM MAN 8 SISU +.BR + +.SH +7. POST INSTALLATION SETUP +.BR + +.SH +7.1 POST INSTALLATION SETUP \- QUICK START + +.BR +After installation of sisu\-complete, move to the document samples directory, + +.BR + cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.BR +[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] + +.BR +and in that directory, initialise the output directory with the command + +.BR + sisu \-CC + +.BR +then run: + +.BR + sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +or the same: + +.BR + sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +look at output results, see the \"sisu_manifest\" page created for the document + +.BR +for an overview of your current sisu setup, type: + +.BR + sisu \-\-help env + +.BR +or + +.BR + sisu \-V + +.BR +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. + +.BR + sisu \-1 + +.BR + sisu \-3 + + +.BR +examine source document, vim has syntax highlighting support + +.BR +gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +additional markup samples in + +.BR + + +.BR +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. + +.BR + sisu \-3 + + +.BR +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: + +.BR + sisu \-3 \-\-trust + + +.BR +For help + +.BR + man sisu + +.BR + sisu \-\-help + +.BR + sisu \-\-help env for the way sisu \"sees/maps\" your system + +.BR + sisu \-\-help commands for list of commands and so on + +.SH +7.2 DOCUMENT MARKUP DIRECTORY + +.BR +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: + +.BR + mkdir ~/sisu_test + +.BR + cd ~/sisu_test + +.BR + cp \-a /usr/share/doc/sisu/sisu_markup_samples/dfsg/* ~/sisu_test/. + +.BR +.B Tip: +the markup syntax examples may be of interest + +.BR + + +.BR +.B Tip: + +.BR + sisu \-U \ [sisu \ markup \ filename] + +.BR +should printout the different possible outputs and where sisu would place them. + +.BR +.B Tip: +if you want to toggle ansi color add + +.BR + c + +.BR +to your flags. + +.SH +7.2.1 CONFIGURATION FILES + +.BR +.B SiSU +configuration file search path is: + +.BR + ./_sisu/sisurc.yaml + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/sisurc.yaml + +.BR +.\\"%% +.B Debian +Installation Note + +.SH +7.2.2 DEBIAN INSTALLATION NOTE + +.BR +It is best you see + +.BR + + +.BR +for up the most up to date information. + +.BR +notes taken from the +.B Debian +control file (end edited), gives an idea of additional packages that +.B SiSU +can make use of if available, (the use/requirement of some of which are +interdependent for specific actions by +.B SiSU +): + +.BR +Package: sisu + +.BR +.B SiSU +is a lightweight markup based, command line oriented, document structuring, +publishing and search framework for document collections. + +.BR +With minimal preparation of a plain\-text, (UTF\-8) file, using its native +markup syntax in your text editor of choice, +.B 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. + +.BR +.B SiSU +also provides concordance files, document content certificates and manifests +of generated output. + +.BR +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 +.B SiSU +. + +.BR +man pages, and interactive help are provided. + +.BR +Dependencies for various features are taken care of in sisu related packages. +The package sisu\-complete installs the whole of +.B SiSU +. + +.BR +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. + +.BR +Homepage: + +.SH +7.2.3 DOCUMENT RESOURCE CONFIGURATION + +.BR +.B sisu +resource configuration information is obtained from sources (where they +exist): + +.BR + ~/.sisu/sisurc.yaml + +.BR + /etc/sisu/[sisu \ version]/sisurc.yaml + +.BR + sisu program defaults + +.SH +7.2.4 SKINS + +.BR +.B Skins +default document appearance may be modified using skins contained in +sub\-directories located at the following paths: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +more specifically, the following locations (or their /etc/sisu equivalent) +should be used: + +.BR + ~/.sisu/skin/doc + +.BR +skins for individual documents; + +.BR + ~/.sisu/skin/dir + +.BR +skins for directories of matching names; + +.BR + ~/.sisu/skin/site + +.BR +site\-wide skin modifying the site\-wide appearance of documents. + +.BR +Usually all skin files are placed in the document skin directory: + +.BR + ~/.sisu/skin/doc + +.BR +with softlinks being made to the skins contained there from other skin +directories as required. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Technical, Howto + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_howto.sst + +.BR +Filetype: +.I SiSU text insert 0.57 + +.BR +Sourcefile Digest, MD5(sisu_howto.sst)= +.I 82c606e66689bcb5d190edf8fc7227a0 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:01 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +generated from source using rman + + With regard to +.B SiSU +man pages the formatting generated for markup syntax is not quite right, for +that you might prefer the links under: + +.TP +.BI 2. + +.TP +.BI 3. + +.TP +.BI 4. + +.TP +.BI 5. + +.TP +.BI 6. + +.TP +.BI 7. +this is an endnote +.TP +.BI 8. + +.TP +.BI 10. + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_howto/sisu_howto.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:06 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_introduction.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_introduction.1 new file mode 100644 index 00000000..22e04ea0 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_introduction.1 @@ -0,0 +1,504 @@ +.TH "sisu_introduction" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- COMMANDS \ [0.58], +RALPH AMISSAH +.BR + +.SH +WHAT IS SISU? +.BR + +.SH +DESCRIPTION +.BR + +.SH +1. INTRODUCTION \- WHAT IS SISU? +.BR + +.BR +.B SiSU +is a system for document markup, publishing (in multiple open standard +formats) and search + +.BR +.B 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. + +.BR +.B 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. + +.BR +.B SiSU +both defines a markup syntax and provides an engine that produces open +standards format outputs from documents prepared with +.B 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 +.B 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. +.B 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. + +.BR +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 +.B SiSU +markup applied to a document, +.B 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. + +.BR +In preparing a +.B 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. + +.BR +.B 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 +.B 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. + +.BR +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. +.B SiSU +provides the flexibility of outputing documents in multiple non\-proprietary +open formats including html, pdf[^7] and the ISO standard ODF.[^8] Whilst +.B 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 +.B SiSU +can be migrated to other document formats. Further security is provided by +the fact that the software itself, +.B 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. +.B 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). + +.BR +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. + +.BR +.B 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 +.B SiSU +offers great possibilities. + +.BR +.B SiSU +is primarily for published works, which can take advantage of the citation +system to reliably reference its documents. +.B 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 +.B SiSU +. + +.BR + + +.SH +2. HOW DOES SISU WORK? +.BR + +.BR +.B 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. +.B 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). + +.SH +3. SUMMARY OF FEATURES +.BR + +.BR +* 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. + +.BR +* 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]. + +.BR +* 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. +.B 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) + +.BR +* 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: + +.BR + * html \- both as a single scrollable text and a segmented document + +.BR + * xhtml + +.BR + * XML \- both in sax and dom style xml structures for further development as + required + +.BR + * ODF \- open document format, the iso standard for document storage + +.BR + * LaTeX \- used to generate pdf + +.BR + * pdf (via LaTeX) + +.BR + * sql \- population of an sql database, (at the same object level that is + used to cite text within a document) + +.BR +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)) + +.BR +* 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. + +.BR +* 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]. + +.BR +* 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 + +.BR +* SQL search aside, documents are generated as required and static once +generated. + +.BR +* 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) + +.BR +* document source (plaintext utf\-8) if shared on the net may be used as input +and processed locally to produce the different document outputs + +.BR +* 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 + +.BR +* generated document outputs may automatically be posted to remote sites. + +.BR +* for basic document generation, the only software dependency is +.B 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. + +.BR +* as a developers tool it is flexible and extensible + +.BR +Syntax highlighting for +.B SiSU +markup is available for a number of text editors. + +.BR +.B 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 + +.BR +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)... + +.BR +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. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Commands \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_introduction.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_introduction.sst)= +.I b2a6da5bd22fa1eaa92a08d81f11d1c7 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:42 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +\" +.B SiSU +information Structuring Universe\" or \"Structured information, Serialized +Units\". + also chosen for the meaning of the Finnish term "sisu". +.TP +.BI 2. +Unix command line oriented +.TP +.BI 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. +.TP +.BI 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. +.TP +.BI 5. +the different heading levels +.TP +.BI 6. +units of text, primarily paragraphs and headings, also any tables, poems, +code-blocks +.TP +.BI 7. +Specification submitted by Adobe to ISO to become a full open ISO +specification + +.TP +.BI 8. +ISO/IEC 26300:2006 + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_introduction/sisu_introduction.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:49 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_markup.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_markup.1 new file mode 100644 index 00000000..bac7ed4d --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_markup.1 @@ -0,0 +1,1532 @@ +.TH "sisu_markup" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- MARKUP \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU MARKUP +.BR + +.SH +1. INTRODUCTION TO SISU MARKUP[^1] +.BR + +.SH +1.1 SUMMARY + +.BR +.B SiSU +source documents are plaintext (UTF\-8)[^2] files + +.BR +All paragraphs are separated by an empty line. + +.BR +Markup is comprised of: + +.BR +* 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) + +.BR +* 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: + +.BR + * heading levels defines document structure + +.BR + * text basic attributes, italics, bold etc. + +.BR + * grouped text (objects), which are to be treated differently, such as code + blocks or poems. + +.BR + * footnotes/endnotes + +.BR + * linked text and images + +.BR + * paragraph actions, such as indent, bulleted, numbered\-lists, etc. + +.BR +Some interactive help on markup is available, by typing sisu and selecting +markup or sisu \-\-help markup + +.SH +1.2 MARKUP EXAMPLES + +.SH +1.2.1 ONLINE + +.BR +Online markup examples are available together with the respective outputs +produced from or from + + +.BR +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + + +.BR +Some example marked up files are available as html with syntax highlighting for +viewing: + +.BR +an alternative presentation of markup syntax: + + +.SH +1.2.2 INSTALLED + +.BR +With +.B 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 + +.SH +2. MARKUP OF HEADERS +.BR + +.BR +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. + +.BR +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: + + +.nf + % this would be a comment +.fi + +.SH +2.1 SAMPLE HEADER + +.BR +This current document has a header similar to this one (without the comments): + + +.nf + % 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 +.fi + +.SH +2.2 AVAILABLE HEADERS + +.BR +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 + +.BR +.B @indentifier: +information or instructions + +.BR +where the \"identifier\" is a tag recognised by the program, and the +\"information\" or \"instructions\" belong to the tag/indentifier specified + +.BR +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. + +.BR +This is a sample header + +.BR +.B % SiSU 0.38 +\ [declared \ file\-type \ identifier \ with \ markup \ version] + +.BR +.B @title: +\ [title \ text] This is the title of the document and used as such, this +header is the only one that is +.I mandatory + +.BR +.B @subtitle: +The Subtitle if any + +.BR +.B @creator: +\ [or \ @author:] Name of Author + +.BR +.B @subject: +(whatever your subject) + +.BR +.B @description: + +.BR +.B @publisher: + +.BR +.B @contributor: + +.BR +.B @translator: +\ [or \ @translated_by:] + +.BR +.B @illustrator: +\ [or \ @illustrated_by:] + +.BR +.B @prepared_by: +\ [or \ @digitized_by:] + +.BR +.B @date: 2000\-08\-27 +\ [ \ also \ @date.created: \ @date.issued: \ @date.available: \ @date.valid: +\ @date.modified: \ ] + +.BR +.B @type: article + +.BR +.B @format: + +.BR +.B @identifier: + +.BR +.B @source: + +.BR +.B @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.] + +.BR +[@language.original: \ original \ language \ in \ which \ the \ work \ was \ +published] + +.BR +.B @papersize: +(A4|US_letter|book_B5|book_A5|US_legal) + +.BR +.B @relation: + +.BR +.B @coverage: + +.BR +.B @rights: +Copyright (c) Name of Right Holder, all rights reserved, or as granted: +public domain, copyleft, creative commons variant, etc. + +.BR +.B @owner: + +.BR +.B @keywords: +text document generation processing management latex pdf structured xml +citation \ [your \ keywords \ here, \ used \ for \ example \ by \ rss \ feeds, +\ and \ in \ sql \ searches] + +.BR +.B @abstract: +\ [paper \ abstract, \ placed \ after \ table \ of \ contents] + +.BR +.B @comment: +\ [...] + +.BR +.B @catalogue: +loc=[Library \ of \ Congress \ classification]; dewey=[Dewey \ +classification]; isbn=[ISBN]; pg=[Project \ Gutenberg \ text \ number] + +.BR +.B @classify_loc: +\ [Library \ of \ Congress \ classification] + +.BR +.B @classify_dewey: +\ [Dewey \ classification] + +.BR +.B @classify_isbn: +\ [ISBN] + +.BR +.B @classify_pg: +\ [Project \ Gutenberg \ text \ number] + +.BR +.B @prefix: +\ [prefix \ is \ placed \ just \ after \ table \ of \ contents] + +.BR +.B @prefix_a: +\ [prefix \ is \ placed \ just \ before \ table \ of \ contents \ \- \ not \ +implemented] + +.BR +.B @prefix_b: + +.BR +.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 \ ] + +.BR +.B @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:) + +.BR +.B @level: +newpage=3; breakpage=4 +\ [paragraph \ level, \ used \ by \ latex \ to \ breakpages, \ the \ page \ +is \ optional \ eg. \ in \ newpage] + +.BR +.B @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] + +.BR +.B @bold: +\ [regular \ expression \ of \ words/phrases \ to \ be \ made \ bold] + +.BR +.B @italics: +\ [regular \ expression \ of \ words/phrases \ to \ italicise] + +.BR +.B @vocabulary: +name of taxonomy/vocabulary/wordlist to use against document + +.BR +.B @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. + +.BR +.B @links: +{ +.B SiSU +}http://www.jus.uio.no/sisu/; +{ FSF }http://www.fsf.org + +.BR +.B @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] + +.SH +3. MARKUP OF SUBSTANTIVE TEXT +.BR + +.SH +3.1 HEADING LEVELS + +.BR +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) + +.BR +.B :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 + +.BR +.B :B~ \ [heading \ text] +Second level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B :C~ \ [heading \ text] +Third level heading \ [this \ is \ a \ heading \ level \ divider] + +.BR +.B 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 + +.BR +.B 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. + +.BR +.B 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 + + +.nf + 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) +.fi + +.SH +3.2 FONT ATTRIBUTES + +.BR +.B markup example: + + +.nf + 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}\- +.fi + +.BR +.B resulting output: + +.BR +normal text emphasis +.B bold text +.I underscore +.I italics +citation ^superscript^ \ [subscript] inserted text +strikethrough + +.BR +normal text + +.BR +emphasis + +.BR +.B bold text + +.BR +.I underscore + +.BR +.I italics + +.BR +citation + +.BR +^superscript^ + +.BR +[subscript] + +.BR +inserted text + +.BR +strikethrough + +.SH +3.3 INDENTATION AND BULLETS + +.BR +.B markup example: + + +.nf + ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps +.fi + +.BR +.B resulting output: + +.BR +ordinary paragraph + +.BR + indent paragraph one step + +.BR + indent paragraph two steps + +.BR + indent paragraph nine steps + +.BR +.B markup example: + + +.nf + * bullet text + _1* bullet text, first indent + _2* bullet text, two step indent +.fi + +.BR +.B resulting output: + +.BR +* bullet text + +.BR + * bullet text, first indent + +.BR + * bullet text, two step indent + +.BR +Numbered List (not to be confused with headings/titles, (document structure)) + +.BR +.B markup example: + + +.nf + # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. +.fi + +.SH +3.4 FOOTNOTES / ENDNOTES + +.BR +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. + +.BR +.B markup example: + + +.nf + ~{ a footnote or endnote }~ +.fi + +.BR +.B resulting output: + +.BR +[^3] + +.BR +.B markup example: + + +.nf + normal text~{ self contained endnote marker & endnote in one }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text[^4] continues + +.BR +.B markup example: + + +.nf + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*] continues + +.BR +normal text \ [^**] continues + +.BR +.B markup example: + + +.nf + normal text ~[* \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues + normal text ~[+ \ editors \ notes, \ numbered \ asterisk \ footnote/endnote \ series \ ]~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text \ [^*1] continues + +.BR +normal text \ [^+1] continues + +.BR +.B Alternative endnote pair notation for footnotes/endnotes: + + +.nf +.nf + % note the endnote marker \"~^\" + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs +.fi + +.BR +the standard and pair notation cannot be mixed in the same document + +.SH +3.5 LINKS + +.SH +3.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS + +.BR +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). + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues +.fi + +.BR +.B resulting output: + +.BR +normal text continues + +.BR +An escaped url without decoration + +.BR +.B markup example: + + +.nf + normal text http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non\-free +.fi + +.BR +.B resulting output: + +.BR +normal text http://www.jus.uio.no/sisu continues + +.BR +deb http://www.jus.uio.no/sisu/archive unstable main non\-free + +.BR +where a code block is used there is neither decoration nor hyperlinking, code +blocks are discussed later in this document + +.BR +.B resulting output: + + +.nf + 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 +.fi + +.BR +To link text or an image to a url the markup is as follows + +.BR +.B markup example: + + +.nf + about { SiSU }http://url.org markup +.fi + +.SH +3.5.2 LINKING TEXT + +.BR +.B resulting output: + +.BR +about SiSU markup + +.BR +A shortcut notation is available so the url link may also be provided +automatically as a footnote + +.BR +.B markup example: + + +.nf + about {~^ SiSU }http://url.org markup +.fi + +.BR +.B resulting output: + +.BR +about SiSU \ [^5] markup + +.SH +3.5.3 LINKING IMAGES + +.BR +.B markup example: + + +.nf + [ tux.png ] + % various url linked images + [ tux.png ] + [ GnuDebianLinuxRubyBetterWay.png ] + {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ +.fi + +.BR +.B resulting output: + +.BR +[ tux.png ] + +.BR +tux.png 64x80 \"Gnu/Linux \- a better way\" + +.BR +[ \ ruby_logo \ (png \ missing) \ ] \ [^6] + +.BR +GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian +and Ruby\" + +.BR +.B linked url footnote shortcut + + +.nf + {~^ \ [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 +.fi + + +.nf + text marker *~name +.fi + +.BR +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. + +.SH +3.6 GROUPED TEXT + +.SH +3.6.1 TABLES + +.BR +Tables may be prepared in two either of two forms + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +a second form may be easier to work with in cases where there is not much +information in each column + +.BR +.B markup example: +[^7] + + +.nf + !_ 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. +.fi + +.BR +.B resulting output: + +.BR +.B Table 3.1: Contributors to Wikipedia, January 2001 \- June 2005 + + \ [table \ omitted, \ see \ other \ document \ formats] + +.BR +* Contributed at least ten times; ** at least 5 times in last month; *** more +than 100 times in last month. + +.SH +3.6.2 POEM + +.BR +.B basic markup: + + +.nf + poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. +.fi + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +3.6.3 GROUP + +.BR +.B basic markup: + + +.nf + group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. +.fi + +.BR +.B markup example: + + +.nf + 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 +.fi + +.BR +.B resulting output: + + + \'Fury said to a +.P + mouse, That he +.P + met in the +.P + house, +.P + \"Let us +.P + both go to +.P + law: I will +.P + prosecute +.P + YOU. \-\-Come, +.P + I\'ll take no +.P + denial; We +.P + must have a +.P + trial: For +.P + really this +.P + morning I\'ve +.P + nothing +.P + to do.\" +.P + Said the +.P + mouse to the +.P + cur, \"Such +.P + a trial, +.P + dear Sir, +.P + With +.P + no jury +.P + or judge, +.P + would be +.P + wasting +.P + our +.P + breath.\" +.P + \"I\'ll be +.P + judge, I\'ll +.P + be jury,\" +.P + Said +.P + cunning +.P + old Fury: +.P + \"I\'ll +.P + try the +.P + whole +.P + cause, +.P + and +.P + condemn +.P + you +.P + to +.P + death.\"\' +.P + +.SH +3.6.4 CODE + +.BR +Code tags are used to escape regular sisu markup, and have been used +extensively within this document to provide examples of +.B 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. + +.BR +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] + +.BR +.B use of code tags instead of poem compared, resulting output: + + +.nf + \'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.\"\' +.fi + +.SH +4. COMPOSITE DOCUMENTS MARKUP +.BR + +.BR +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 +.B .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 +.B .sst +regular markup file, or +.B .ssi +(insert/information) A secondary file of the composite document is built +prior to processing with the same prefix and the suffix +.B ._sst + +.BR +basic markup for importing a document into a master document + + +.nf + << |filename1.sst|@|^| + << |filename2.ssi|@|^| +.fi + +.BR +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. + + +.nf + r{filename} + {filename.ssi}require + << {filename.ssi} + % using textlink alternatives + |filename.ssi|@|^|require + << |filename.ssi|@|^| + % using thlnk alternatives + require + << +.fi + +.SH +MARKUP SYNTAX HISTORY +.BR + +.SH +5. NOTES RELATED TO FILES\-TYPES AND MARKUP SYNTAX +.BR + +.BR +0.38 is substantially current, depreciated 0.16 supported, though file names +were changed at 0.37 + +.BR +.B 0.52 +(2007w14/6) declared document type identifier at start of text/document: + +.BR + .B SiSU +0.52 + +.BR +or, backward compatible using the comment marker: + +.BR + % +.B SiSU +0.38 + +.BR +variations include \' +.B SiSU +(text|master|insert) \ [version]\' and \'sisu\-[version]\' + +.BR +.B 0.51 +(2007w13/6) skins changed (simplified), markup unchanged + +.BR +.B 0.42 +(2006w27/4) * (asterisk) type endnotes, used e.g. in relation to author + +.BR +.B 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) + +.BR +.B 0.37 +(2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged + +.BR +.B 0.35 +(2005w52/3) sisupod, zipped content file introduced + +.BR +.B 0.23 +(2005w36/2) utf\-8 for markup file + +.BR +.B 0.22 +(2005w35/3) image dimensions may be omitted if rmagick is available to be +relied upon + +.BR +.B 0.20.4 +(2005w33/4) header 0~links + +.BR +.B 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 + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Markup \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_markup.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_markup.sst)= +.I 643738c4b96d001d107e3ea72ba17a97 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:43 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +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. +.TP +.BI 2. +files should be prepared using UTF-8 character encoding +.TP +.BI 3. +a footnote or endnote +.TP +.BI 4. +self contained endnote marker & endnote in one +.TP +.BI *. +unnumbered asterisk footnote/endnote, insert multiple asterisks if required +.TP +.BI **. +another unnumbered asterisk footnote/endnote +.TP +.BI *1. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI +1. +editors notes, numbered asterisk footnote/endnote series +.TP +.BI 5. + +.TP +.BI 6. + +.TP +.BI 7. +Table from the Wealth of Networks by Yochai Benkler + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_markup/sisu_markup.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_output_overview.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_output_overview.1 new file mode 100644 index 00000000..36b3fc97 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_output_overview.1 @@ -0,0 +1,164 @@ +.TH "sisu_output_overview" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- SISU OVERVIEW OF STATUS OF FEATURES AVAILABLE IN VARIOUS +OUTPUTS, +RALPH AMISSAH +.BR + +.SH +SISU OVERVIEW OF STATUS OF FEATURES AVAILABLE IN VARIOUS OUTPUTS +.BR + +.SH +1. A CHECKLIST OF OUTPUT FEATURES +.BR + +.BR +This table gives an indication of the features that are available for various +forms of output of +.B SiSU +. \ [^1] + + \ [table \ omitted, \ see \ other \ document \ formats] + + + Done +.P + * yes/done +.P + . partial +.P + \- not available/appropriate +.P + Not Done +.P + T task todo +.P + t lesser task/todo +.P + not done +.P + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- SiSU overview of status of features available in various +outputs + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2005\-10\-31 + +.BR +DC Date available: +.I 2006\-10\-31 + +.BR +DC Date issued: +.I 2006\-10\-31 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_output_overview.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_output_overview.sst)= +.I a97ac8856d180e9c4074ba83ef15bcfa + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:44 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +updated for sisu-0.36.6 on 2006-01-23 + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_output_overview/sisu_output_overview.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.1 new file mode 100644 index 00000000..d31641bd --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.1 @@ -0,0 +1,216 @@ +.TH "sisu_pdf" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU SQLITE +.BR + +.SH +1. SQLITE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +1.2 DESCRIPTION + +.BR +Information creating pdf output with sisu (and related to the sisu_pdf +dependency package, which is a dummy package to install dependencies needed for +.B SiSU +to generate pdfs (primarily related to LaTeX), sisu_pdf being part of +.B SiSU +\- man sisu). + +.BR +.B SiSU +generates LaTeX which is converted by LaTeX tools to pdf. + +.SH +1.3 SYNOPSIS + +.BR + sisu \-pv \ [filename/wildcard] + +.SH +1.4 COMMANDS + +.TP +.B \ sisu \ \-pv \ \ [filename/wildcard] +creates two pdf documents: vertical (portrait.pdf) and; horizontal +(landscape.pdf). +.B SiSU +generates LaTeX output which is converted to pdf if the appropriate LaTeX +dependencies are met on the system. + +.TP +.B \ sisu \ \-pv \ \-\-papersize\-a4 \ \ [filename/wildcard] +overrides the default papersize set to A4. Preset alternative sizes include: +\'A4\', U.S. \'letter\' and \'legal\' and book sizes \'A5\' and \'B5\' (system +defaults to A4). + +.SH +1.5 SETTING PAPER SIZE + +.BR +The paper\-size may be set to any of the following sizes: \'A4\', U.S. +\'letter\' and \'legal\' and book sizes: \'A5\' and \'B5\' + +.BR +1. The preset default if not otherwise given in the configuration file or +elsewhere is A4. + +.BR +2. The default paper size may be set in the configuration file sisurc.yml. See +sisu_configuration: + + +.nf + #% papersize, (LaTeX/pdf) current values A4, US_letter, book_b5, book_a5, US_legal + default: + papersize: \'A4\' +.fi + +.BR +3. Paper size may be set in a document header: + + +.nf + @papersize: (A4|US_letter|book_B5|book_A5|US_legal) +.fi + +.BR +4. or provided with additional command line parameter, e.g. + +.BR + sisu \-pv \-\-papersize\-a4 \ [filename/wildcard] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_pdf.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_pdf.sst)= +.I 161d3f57a0c3b9e816474243229cb423 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:48 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_pdf/sisu_pdf.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:52 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.7 b/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.7 new file mode 100644 index 00000000..00ca7889 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_pdf.7 @@ -0,0 +1,216 @@ +.TH "sisu_pdf" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU SQLITE +.BR + +.SH +1. SQLITE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +1.2 DESCRIPTION + +.BR +Information creating pdf output with sisu (and related to the sisu_pdf +dependency package, which is a dummy package to install dependencies needed for +.B SiSU +to generate pdfs (primarily related to LaTeX), sisu_pdf being part of +.B SiSU +\- man sisu). + +.BR +.B SiSU +generates LaTeX which is converted by LaTeX tools to pdf. + +.SH +1.3 SYNOPSIS + +.BR + sisu \-pv \ [filename/wildcard] + +.SH +1.4 COMMANDS + +.TP +.B \ sisu \ \-pv \ \ [filename/wildcard] +creates two pdf documents: vertical (portrait.pdf) and; horizontal +(landscape.pdf). +.B SiSU +generates LaTeX output which is converted to pdf if the appropriate LaTeX +dependencies are met on the system. + +.TP +.B \ sisu \ \-pv \ \-\-papersize\-a4 \ \ [filename/wildcard] +overrides the default papersize set to A4. Preset alternative sizes include: +\'A4\', U.S. \'letter\' and \'legal\' and book sizes \'A5\' and \'B5\' (system +defaults to A4). + +.SH +1.5 SETTING PAPER SIZE + +.BR +The paper\-size may be set to any of the following sizes: \'A4\', U.S. +\'letter\' and \'legal\' and book sizes: \'A5\' and \'B5\' + +.BR +1. The preset default if not otherwise given in the configuration file or +elsewhere is A4. + +.BR +2. The default paper size may be set in the configuration file sisurc.yml. See +sisu_configuration: + + +.nf + #% papersize, (LaTeX/pdf) current values A4, US_letter, book_b5, book_a5, US_legal + default: + papersize: \'A4\' +.fi + +.BR +3. Paper size may be set in a document header: + + +.nf + @papersize: (A4|US_letter|book_B5|book_A5|US_legal) +.fi + +.BR +4. or provided with additional command line parameter, e.g. + +.BR + sisu \-pv \-\-papersize\-a4 \ [filename/wildcard] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_pdf.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_pdf.sst)= +.I 161d3f57a0c3b9e816474243229cb423 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:03 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_pdf/sisu_pdf.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.1 new file mode 100644 index 00000000..5d5b68cd --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.1 @@ -0,0 +1,223 @@ +.TH "sisu_postgresql" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU POSTGRESQL +.BR + +.SH +1. POSTGRESQL +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +1.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +1.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +1.4 COMMANDS + +.BR +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 + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +1.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +1.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_postgresql.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_postgresql.sst)= +.I b81ba44e7946dfaf03d26f0dc5d749ab + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:47 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_postgresql/sisu_postgresql.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.7 b/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.7 new file mode 100644 index 00000000..4a550af0 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_postgresql.7 @@ -0,0 +1,223 @@ +.TH "sisu_postgresql" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU POSTGRESQL +.BR + +.SH +1. POSTGRESQL +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +1.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +1.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +1.4 COMMANDS + +.BR +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 + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +1.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +1.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_postgresql.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_postgresql.sst)= +.I b81ba44e7946dfaf03d26f0dc5d749ab + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:03 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_postgresql/sisu_postgresql.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.1 new file mode 100644 index 00000000..42df7771 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.1 @@ -0,0 +1,517 @@ +.TH "sisu_quickstart" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- QUICKSTART, INSTALLATION AND USE, +RALPH AMISSAH +.BR + +.SH +QUICKSTART \- SISU INSTALLATION AND USE +.BR + +.SH +1. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +1.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +1.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/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 +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + + +.nf + #/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 +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +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. + +.SH +1.1.2 RPM INSTALLATION + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +1.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +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: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B 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)[^1] or +converting LaTeX to pdf. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + + +.BR + + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby install base + +.BR +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. + +.BR +Further information on \"rant\" is available from: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby install help + +.BR + ruby install \-T + +.SH +1.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +1.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +1.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +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 + +.SH +1.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +1.3 GETTING HELP + +.SH +1.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 \ [^2] + +.BR +* sisu.8 \ [^3] + +.BR +* man directory \ [^4] + +.SH +1.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +1.3.3 THE HOME PAGE + +.BR + + +.BR + + +.SH +1.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR + + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^5] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Quickstart, installation and use + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_quickstart.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_quickstart.sst)= +.I 05a047fd659fbbeaa3cdb982b5911bcd + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:45 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +There is nothing to stop MySQL support being added in future. +.TP +.BI 2. + +.TP +.BI 3. + +.TP +.BI 4. + +.TP +.BI 5. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_quickstart/sisu_quickstart.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.8 new file mode 100644 index 00000000..e13f84e4 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_quickstart.8 @@ -0,0 +1,517 @@ +.TH "sisu_quickstart" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION, +SERIALIZED UNITS \- QUICKSTART, INSTALLATION AND USE, +RALPH AMISSAH +.BR + +.SH +QUICKSTART \- SISU INSTALLATION AND USE +.BR + +.SH +1. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +1.1 INSTALLATION + +.BR +Installation is currently most straightforward and tested on the +.B Debian +platform, as there are packages for the installation of sisu and all +requirements for what it does. + +.SH +1.1.1 DEBIAN INSTALLATION + +.BR +.B SiSU +is available directly from the +.B Debian +Sid and testing archives (and possibly Ubuntu), assuming your +/etc/apt/sources.list is set accordingly: + + +.nf + aptitude update + aptitude install sisu\-complete +.fi + +.BR +The following /etc/apt/sources.list setting permits the download of additional +markup samples: + + +.nf + #/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 +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +If there are newer versions of +.B SiSU +upstream of the +.B Debian +archives, they will be available by adding the following to your +/etc/apt/sources.list + + +.nf + #/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 +.fi + +.BR +repeat the aptitude commands + + +.nf + aptitude update + aptitude install sisu\-complete sisu\-markup\-samples +.fi + +.BR +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. + +.SH +1.1.2 RPM INSTALLATION + +.BR +RPMs are provided though untested, they are prepared by running alien against +the source package, and against the debs. + +.BR +They may be downloaded from: + +.BR + + +.BR +as root type: + +.BR + rpm \-i \ [rpm \ package \ name] + +.SH +1.1.3 INSTALLATION FROM SOURCE + +.BR +To install +.B SiSU +from source check information at: + +.BR + + +.BR +* download the source package + +.BR +* Unpack the source + +.BR +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: + +.BR +For basic use +.B SiSU +is only dependent on the programming language in which it is written +.B Ruby +, and +.B 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)[^1] or +converting LaTeX to pdf. + +.BR +.B setup.rb + +.BR +This is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked +.B SiSU +as root type: + + +.nf + ruby setup.rb config + ruby setup.rb setup + #[and \ as \ root:] + ruby setup.rb install +.fi + +.BR +further information on setup.rb is available from: + +.BR + + +.BR + + +.BR +.B \"install\" + +.BR +The \"install\" file provided is an installer prepared using \"rant\". In the +root directory of the unpacked +.B SiSU +as root type: + +.BR + ruby install base + +.BR +or for a more complete installation: + +.BR + ruby install + +.BR +or + +.BR + ruby install base + +.BR +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. + +.BR +Further information on \"rant\" is available from: + +.BR + + +.BR + + +.BR +For a list of alternative actions you may type: + +.BR + ruby install help + +.BR + ruby install \-T + +.SH +1.2 TESTING SISU, GENERATING OUTPUT + +.BR +To check which version of sisu is installed: + +.BR +sisu \-v + +.BR +Depending on your mode of installation one or a number of markup sample files +may be found either in the directory: + +.BR +... + +.BR +or + +.BR +... + +.BR +change directory to the appropriate one: + +.BR +cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +.SH +1.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +this will generate html including a concordance file, opendocument text format, +plaintext, XHTML and various forms of XML, and OpenDocument text + +.SH +1.2.2 LATEX / PDF + +.BR +Assuming a LaTeX engine such as tetex or texlive is installed with the required +modules (done automatically on selection of sisu\-pdf in +.B Debian +) + +.BR +Having moved to the directory that contains the markup samples (see +instructions above if necessary), choose a file and run sisu against it + +.BR +sisu \-pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +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 + +.SH +1.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE + +.BR +Relational databases need some setting up \- you must have permission to create +the database and write to it when you run sisu. + +.BR +Assuming you have the database installed and the requisite permissions + +.BR +sisu \-\-sqlite \-\-recreate + +.BR +sisu \-\-sqlite \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.BR +sisu \-\-pgsql \-\-recreate + +.BR +sisu \-\-pgsql \-v \-\-import +free_as_in_freedom.rms_and_free_software.sam_williams.sst + +.SH +1.3 GETTING HELP + +.SH +1.3.1 THE MAN PAGES + +.BR +Type: + +.BR + man sisu + +.BR +The man pages are also available online, though not always kept as up to date +as within the package itself: + +.BR +* sisu.1 \ [^2] + +.BR +* sisu.8 \ [^3] + +.BR +* man directory \ [^4] + +.SH +1.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +1.3.3 THE HOME PAGE + +.BR + + +.BR + + +.SH +1.4 MARKUP SAMPLES + +.BR +A number of markup samples (along with output) are available off: + +.BR + + +.BR +Additional markup samples are packaged separately in the file: + +.BR +.B * + +.BR +On +.B Debian +they are available in non\-free[^5] to include them it is necessary to +include non\-free in your /etc/apt/source.list or obtain them from the sisu +home site. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe / Structured information, +Serialized Units \- Quickstart, installation and use + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2006\-09\-06 + +.BR +DC Date available: +.I 2006\-09\-06 + +.BR +DC Date issued: +.I 2006\-09\-06 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_quickstart.sst + +.BR +Filetype: +.I SiSU text 0.57 + +.BR +Sourcefile Digest, MD5(sisu_quickstart.sst)= +.I 05a047fd659fbbeaa3cdb982b5911bcd + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:00 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. +There is nothing to stop MySQL support being added in future. +.TP +.BI 2. + +.TP +.BI 3. + +.TP +.BI 4. + +.TP +.BI 5. +the +.B Debian +Free Software guidelines require that everything distributed within +.B Debian +can be changed - and the documents are authors\' works that while freely +distributable are not freely changeable. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_quickstart/sisu_quickstart.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:06 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_remote.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_remote.1 new file mode 100644 index 00000000..078bec7a --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_remote.1 @@ -0,0 +1,251 @@ +.TH "sisu_remote" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- REMOTE OPERATIONS \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU REMOTE OPERATIONS +.BR + +.SH +1. REMOTE SOURCE DOCUMENTS +.BR + +.BR +.B 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 +.B SiSU +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp + +.BR +.B .sst / .ssm \- sisu text files + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ .sst \ or \ .ssm \ file] +.fi + +.BR +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. + +.BR +NOTE: to set up a remote machine to serve +.B SiSU +documents in this way, images should be in the directory relative to the +document source ../_sisu/image + +.BR +.B sisupod \- zipped sisu files + +.BR +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. + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ sisupod.zip \ or \ .ssp \ file] +.fi + +.BR +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. + +.SH +REMOTE DOCUMENT OUTPUT +.BR + +.SH +2. REMOTE OUTPUT +.BR + +.BR +Once properly configured +.B SiSU +output can be automatically posted once generated to a designated remote +machine using either rsync, or scp. + +.BR +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. + + +.nf + sisu \-3R sisu_remote.sst +.fi + +.SH +2.1 COMMANDS + +.TP +.B \ \-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 + +.TP +.B \ \-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 + +.SH +2.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +3. REMOTE SERVERS +.BR + +.BR +As +.B SiSU +is generally operated using the command line, and works within a Unix type +environment, +.B 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. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Remote Operations \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_remote.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_remote.sst)= +.I 5fe0c81eddcd7e3e18608b8e48b3ccad + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:47 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_remote/sisu_remote.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_remote.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_remote.8 new file mode 100644 index 00000000..9da648f2 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_remote.8 @@ -0,0 +1,251 @@ +.TH "sisu_remote" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- REMOTE OPERATIONS \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU REMOTE OPERATIONS +.BR + +.SH +1. REMOTE SOURCE DOCUMENTS +.BR + +.BR +.B 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 +.B SiSU +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp + +.BR +.B .sst / .ssm \- sisu text files + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ .sst \ or \ .ssm \ file] +.fi + +.BR +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. + +.BR +NOTE: to set up a remote machine to serve +.B SiSU +documents in this way, images should be in the directory relative to the +document source ../_sisu/image + +.BR +.B sisupod \- zipped sisu files + +.BR +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. + +.BR +.B 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. + + +.nf + sisu \-3 http://[provide \ url \ to \ valid \ sisupod.zip \ or \ .ssp \ file] +.fi + +.BR +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. + +.SH +REMOTE DOCUMENT OUTPUT +.BR + +.SH +2. REMOTE OUTPUT +.BR + +.BR +Once properly configured +.B SiSU +output can be automatically posted once generated to a designated remote +machine using either rsync, or scp. + +.BR +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. + + +.nf + sisu \-3R sisu_remote.sst +.fi + +.SH +2.1 COMMANDS + +.TP +.B \ \-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 + +.TP +.B \ \-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 + +.SH +2.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +3. REMOTE SERVERS +.BR + +.BR +As +.B SiSU +is generally operated using the command line, and works within a Unix type +environment, +.B 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. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Remote Operations \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_remote.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_remote.sst)= +.I 5fe0c81eddcd7e3e18608b8e48b3ccad + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:02 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_remote/sisu_remote.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_search.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_search.1 new file mode 100644 index 00000000..a052ee34 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_search.1 @@ -0,0 +1,639 @@ +.TH "sisu_search" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +1. SISU SEARCH \- INTRODUCTION +.BR + +.BR +.B SiSU +output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + +.BR +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. + +.BR +In addition to this +.B 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. + +.SH +2. SQL +.BR + +.SH +2.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^1] and/or +SQLite[^2] database together with information related to document structure. + +.BR +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: + +.BR + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + +.BR + * 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 + +.BR + * a third containing endnotes cross\-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + +.BR + * 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. + +.BR +There is of course the possibility to add further structures. + +.BR +At this level +.B 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. + +.BR +Being able to search a relational database at an object level with the +.B SiSU +citation system is an effective way of locating content generated by +.B 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). + +.SH +3. POSTGRESQL +.BR + +.SH +3.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +3.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +3.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +3.4 COMMANDS + +.BR +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 + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +3.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +3.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +4. SQLITE +.BR + +.SH +4.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +4.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +4.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +4.4 COMMANDS + +.BR +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 + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +4.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +4.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +5. INTRODUCTION +.BR + +.SH +5.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend \ [^3] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^4] + +.BR +.B 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. + +.BR +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.[^5] + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created +\ + +.BR +The following is feedback on the setup on a machine provided by the help +command: + +.BR + sisu \-\-help sql + + +.nf + 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 +.fi + +.BR +Note on databases built + +.BR +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] + +.SH +5.2 SEARCH FORM + +.TP +.B \ sisu \ \-F +\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \ +the \ web\-server \ cgi \ directory \ + +.TP +.B \ 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 +\ + +.TP +.B \ sisu \ \-Fv +\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \ +hyperestraier \ + +.TP +.B \ sisu \ \-W +\ starts \ the \ webrick \ server \ which \ should \ be \ available \ +wherever \ sisu \ is \ properly \ installed \ + +.BR +The generated search form must be copied manually to the webserver directory as +instructed + +.SH +6. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.BR +on sisu_hyperestraier: + +.BR + man sisu_hyperestraier + +.BR + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + +.BR +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + +.BR +(A) to generate the index within the webserver directory to be indexed: + +.BR + estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index] + +.BR +the following are examples that will need to be tailored according to your +needs: + +.BR + cd /home/ralph/sisu_www + +.BR + estcmd gather \-sd casket /home/ralph/sisu_www + +.BR +you may use the \'find\' command together with \'egrep\' to limit indexing to +particular document collection directories within the web server directory: + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \- + +.BR +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + +.BR +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. + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v + \'(doc|concordance).html$\' |estcmd gather \-sd casket \- + +.BR +from your current document preparation/markup directory, you would construct a +rune along the following lines: + +.BR + 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 \- + +.BR +(B) to set up the search form + +.BR +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + +.BR + sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin + +.BR + sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi + +.BR + sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin + +.BR + \ [see \ estraier \ documentation \ for \ paths] + +.BR +(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and +\'replace:\': + +.BR + indexname: /home/ralph/sisu_www/casket + +.BR + replace: ^file:///home/ralph/sisu_www{{!}}http://localhost + +.BR + replace: /index.html?${{!}}/ + +.BR +(C) to test using webrick, start webrick: + +.BR + sisu \-W + +.BR +and try open the url: + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_search._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_search._sst)= +.I 52c1d6d3c3082e6b236c65debc733a05 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:48 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. + + + +.TP +.BI 2. + + +.TP +.BI 3. + +.TP +.BI 4. +(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. +.TP +.BI 5. +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. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_search/sisu_search.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:52 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_search.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_search.8 new file mode 100644 index 00000000..039f6e7c --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_search.8 @@ -0,0 +1,639 @@ +.TH "sisu_search" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +1. SISU SEARCH \- INTRODUCTION +.BR + +.BR +.B SiSU +output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. + +.BR +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. + +.BR +In addition to this +.B 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. + +.SH +2. SQL +.BR + +.SH +2.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^1] and/or +SQLite[^2] database together with information related to document structure. + +.BR +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: + +.BR + * one containing semantic (and other) headers, including, title, author, + subject, (the Dublin Core...); + +.BR + * 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 + +.BR + * a third containing endnotes cross\-referenced back to the paragraph from + which they are referenced (both in formatted and clean text versions for + searching). + +.BR + * 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. + +.BR +There is of course the possibility to add further structures. + +.BR +At this level +.B 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. + +.BR +Being able to search a relational database at an object level with the +.B SiSU +citation system is an effective way of locating content generated by +.B 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). + +.SH +3. POSTGRESQL +.BR + +.SH +3.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +3.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate a postgresql database, this being part of +.B SiSU +\- man sisu). + +.SH +3.3 SYNOPSIS + +.BR + sisu \-D \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] \ [filename/wildcard \ if \ required] + +.SH +3.4 COMMANDS + +.BR +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 + +.BR +.B \-D or \-\-pgsql +may be used interchangeably. + +.SH +3.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-D \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-D \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-D \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +3.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-D \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-D \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from postgresql database. + +.SH +4. SQLITE +.BR + +.SH +4.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +4.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +4.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +4.4 COMMANDS + +.BR +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 + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +4.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +4.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +5. INTRODUCTION +.BR + +.SH +5.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend \ [^3] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^4] + +.BR +.B 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. + +.BR +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.[^5] + +.TP +.B \ sisu \ \-F \ \-\-webserv\-webrick +\ builds \ a \ cgi \ web \ search \ frontend \ for \ the \ database \ created +\ + +.BR +The following is feedback on the setup on a machine provided by the help +command: + +.BR + sisu \-\-help sql + + +.nf + 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 +.fi + +.BR +Note on databases built + +.BR +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] + +.SH +5.2 SEARCH FORM + +.TP +.B \ sisu \ \-F +\ generates \ a \ sample \ search \ form, \ which \ must \ be \ copied \ to \ +the \ web\-server \ cgi \ directory \ + +.TP +.B \ 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 +\ + +.TP +.B \ sisu \ \-Fv +\ as \ above, \ and \ provides \ some \ information \ on \ setting \ up \ +hyperestraier \ + +.TP +.B \ sisu \ \-W +\ starts \ the \ webrick \ server \ which \ should \ be \ available \ +wherever \ sisu \ is \ properly \ installed \ + +.BR +The generated search form must be copied manually to the webserver directory as +instructed + +.SH +6. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.BR +on sisu_hyperestraier: + +.BR + man sisu_hyperestraier + +.BR + /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html + +.BR +NOTE: the examples that follow assume that sisu output is placed in the +directory /home/ralph/sisu_www + +.BR +(A) to generate the index within the webserver directory to be indexed: + +.BR + estcmd gather \-sd \ [index \ name] \ [directory \ path \ to \ index] + +.BR +the following are examples that will need to be tailored according to your +needs: + +.BR + cd /home/ralph/sisu_www + +.BR + estcmd gather \-sd casket /home/ralph/sisu_www + +.BR +you may use the \'find\' command together with \'egrep\' to limit indexing to +particular document collection directories within the web server directory: + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/home/ralph/sisu_www/sisu/.+?.html$\' |estcmd gather \-sd casket \- + +.BR +Check which directories in the webserver/output directory (~/sisu_www or +elsewhere depending on configuration) you wish to include in the search index. + +.BR +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. + +.BR + find /home/ralph/sisu_www \-type f | egrep + \'/sisu_www/(sisu|bookmarks)/.+?.html$\' | egrep \-v + \'(doc|concordance).html$\' |estcmd gather \-sd casket \- + +.BR +from your current document preparation/markup directory, you would construct a +rune along the following lines: + +.BR + 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 \- + +.BR +(B) to set up the search form + +.BR +(i) copy estseek.cgi to your cgi directory and set file permissions to 755: + +.BR + sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin + +.BR + sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi + +.BR + sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin + +.BR + \ [see \ estraier \ documentation \ for \ paths] + +.BR +(ii) edit estseek.conf, with attention to the lines starting \'indexname:\' and +\'replace:\': + +.BR + indexname: /home/ralph/sisu_www/casket + +.BR + replace: ^file:///home/ralph/sisu_www{{!}}http://localhost + +.BR + replace: /index.html?${{!}}/ + +.BR +(C) to test using webrick, start webrick: + +.BR + sisu \-W + +.BR +and try open the url: + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_search._sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_search._sst)= +.I 52c1d6d3c3082e6b236c65debc733a05 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:04 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + +.TP +.BI 1. + + + +.TP +.BI 2. + + +.TP +.BI 3. + +.TP +.BI 4. +(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. +.TP +.BI 5. +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. + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_search/sisu_search.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_skin.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_skin.1 new file mode 100644 index 00000000..f502adae --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_skin.1 @@ -0,0 +1,222 @@ +.TH "sisu_skin" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- SKINS \ [0.58], +RALPH AMISSAH +.BR + +.SH +DOCUMENT SKINS \- CONFIGURATION +.BR + +.SH +1. SKINS +.BR + +.BR +Skins modify the default appearance of document output on a document, +directory, or site wide basis. Skins are looked for in the following locations: + +.BR + ./_sisu/skin + +.BR + ~/.sisu/skin + +.BR + /etc/sisu/skin + +.BR +.B Within the skin directory +are the following the default sub\-directories for document skins: + +.BR + ./skin/doc + +.BR + ./skin/dir + +.BR + ./skin/site + +.BR +A skin is placed in the appropriate directory and the file named skin_[name].rb + +.BR +The skin itself is a ruby file which modifies the default appearances set in +the program. + +.SH +1.1 DOCUMENT SKIN + +.BR +Documents take on a document skin, if the header of the document specifies a +skin to be used. + + +.nf + @skin: skin_united_nations +.fi + +.SH +1.2 DIRECTORY SKIN + +.BR +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). + +.BR +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. + +.SH +1.3 SITE SKIN + +.BR +A site skin, modifies the program default skin. + +.SH +1.4 SAMPLE SKINS + +.BR +With +.B SiSU +installed sample skins may be found in: + +.BR + /etc/sisu/skin/doc and + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/doc + +.BR +(or equivalent directory) and if sisu\-markup\-samples is installed also under: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/non\-free/_sisu/skin/doc + +.BR +Samples of list.yml and promo.yml (which are used to create the right column +list) may be found in: + +.BR + /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent + directory) + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Skins \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_skin.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_skin.sst)= +.I 3686b1b7864132c8d6ab3b0398d6e2ae + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:44 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_skin/sisu_skin.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.1 new file mode 100644 index 00000000..721c22c0 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.1 @@ -0,0 +1,222 @@ +.TH "sisu_sqlite" "1" "2007-09-16" "0.59.0" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU SQLITE +.BR + +.SH +1. SQLITE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +1.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +1.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +1.4 COMMANDS + +.BR +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 + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +1.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +1.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_sqlite.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_sqlite.sst)= +.I 61ba58f6a2f5cc9651b985a8eabb96e9 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:47 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_sqlite/sisu_sqlite.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.7 b/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.7 new file mode 100644 index 00000000..fa162cc3 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_sqlite.7 @@ -0,0 +1,222 @@ +.TH "sisu_sqlite" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe" +.SH +SISU \- SISU INFORMATION STRUCTURING UNIVERSE \- SEARCH \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SEARCH +.BR + +.SH +SISU SQLITE +.BR + +.SH +1. SQLITE +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +1.2 DESCRIPTION + +.BR +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 +.B SiSU +to populate an sqlite database, this being part of +.B SiSU +\- man sisu). + +.SH +1.3 SYNOPSIS + +.BR + sisu \-d \ [instruction] \ [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] \ [filename/wildcard \ if \ + required] + +.SH +1.4 COMMANDS + +.BR +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 + +.BR +.B \-d or \-\-sqlite +may be used interchangeably. + +.SH +1.4.1 CREATE AND DESTROY DATABASE + +.TP +.B \ \-\-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) \ + +.TP +.B \ sisu \ \-d \ \-\-createdb +\ creates \ database \ where \ no \ database \ existed \ before \ + +.TP +.B \ sisu \ \-d \ \-\-create +\ creates \ database \ tables \ where \ no \ database \ tables \ existed \ +before \ + +.TP +.B \ 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). \ + +.TP +.B \ sisu \ \-d \ \-\-recreate +\ destroys \ existing \ database \ and \ builds \ a \ new \ empty \ database +\ structure \ + +.SH +1.4.2 IMPORT AND REMOVE DOCUMENTS + +.TP +.B \ 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). + +.TP +.B \ sisu \ \-d \ \-\-update \ \-v \ \ [filename/wildcard] +updates file contents in database + +.TP +.B \ sisu \ \-d \ \-\-remove \ \-v \ \ [filename/wildcard] +removes specified document from sqlite database. + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- SiSU information Structuring Universe \- Search \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2002\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_sqlite.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_sqlite.sst)= +.I 61ba58f6a2f5cc9651b985a8eabb96e9 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:03 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_sqlite/sisu_sqlite.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.1 new file mode 100644 index 00000000..47625086 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.1 @@ -0,0 +1,307 @@ +.TH "sisu_syntax_highlighting" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- SYNTAX HIGHLIGHTING \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SYNTAX HIGHLIGHTING +.BR + +.SH +1. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + ./data/sisu/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/conf/editor\-syntax\-etc + +.BR +contains rudimentary sisu syntax highlighting files for: + +.BR +* (g)vim + +.BR + package: sisu\-vim + +.BR +status: largely done + +.BR + there is a vim syntax highlighting and folds component + +.BR +* gedit + +.BR +* gobby + +.BR + file: sisu.lang + +.BR +place in: + +.BR + /usr/share/gtksourceview\-1.0/language\-specs + +.BR +or + +.BR + ~/.gnome2/gtksourceview\-1.0/language\-specs + +.BR + status: very basic syntax highlighting + +.BR + comments: this editor features display line wrap and is used by Goby! + +.BR +* nano + +.BR + file: nanorc + +.BR +save as: + +.BR + ~/.nanorc + +.BR + status: basic syntax highlighting + +.BR + comments: assumes dark background; no display line\-wrap; does line breaks + +.BR +* diakonos (an editor written in ruby) + +.BR +file: diakonos.conf + +.BR +save as: + +.BR + ~/.diakonos/diakonos.conf + +.BR +includes: + +.BR + status: basic syntax highlighting + +.BR +comments: assumes dark background; no display line\-wrap + +.BR +* kate & kwrite + +.BR + file: sisu.xml + +.BR + place in: + +.BR + /usr/share/apps/katepart/syntax + +.BR + or + +.BR + ~/.kde/share/apps/katepart/syntax + +.BR + \ [settings::configure \ kate::{highlighting,filetypes}] + +.BR + \ [tools::highlighting::{markup,scripts}:: +.B \ SiSU +] + +.BR +* nedit + +.BR + file: sisu_nedit.pats + +.BR + nedit \-import sisu_nedit.pats + +.BR + status: a very clumsy first attempt \ [not \ really \ done] + +.BR + comments: this editor features display line wrap + +.BR +* emacs + +.BR + files: sisu\-mode.el + +.BR + to file ~/.emacs add the following 2 lines: + +.BR + (add\-to\-list \'load\-path \"/usr/share/sisu\-examples/config/syntax_hi\") + +.BR + (require \'sisu\-mode.el) + +.BR + \ [not \ done \ / \ not \ yet \ included] + +.BR +* vim & gvim + +.BR + files: + +.BR + 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) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ 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] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Syntax Highlighting \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_syntax_highlighting.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_syntax_highlighting.sst)= +.I 1dfe1975df71459c3f56c3fd13c5789c + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:46 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_syntax_highlighting/sisu_syntax_highlighting.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:51 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.8 b/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.8 new file mode 100644 index 00000000..b2f85d85 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_syntax_highlighting.8 @@ -0,0 +1,307 @@ +.TH "sisu_syntax_highlighting" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- SYNTAX HIGHLIGHTING \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU SYNTAX HIGHLIGHTING +.BR + +.SH +1. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + ./data/sisu/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/conf/editor\-syntax\-etc + +.BR +contains rudimentary sisu syntax highlighting files for: + +.BR +* (g)vim + +.BR + package: sisu\-vim + +.BR +status: largely done + +.BR + there is a vim syntax highlighting and folds component + +.BR +* gedit + +.BR +* gobby + +.BR + file: sisu.lang + +.BR +place in: + +.BR + /usr/share/gtksourceview\-1.0/language\-specs + +.BR +or + +.BR + ~/.gnome2/gtksourceview\-1.0/language\-specs + +.BR + status: very basic syntax highlighting + +.BR + comments: this editor features display line wrap and is used by Goby! + +.BR +* nano + +.BR + file: nanorc + +.BR +save as: + +.BR + ~/.nanorc + +.BR + status: basic syntax highlighting + +.BR + comments: assumes dark background; no display line\-wrap; does line breaks + +.BR +* diakonos (an editor written in ruby) + +.BR +file: diakonos.conf + +.BR +save as: + +.BR + ~/.diakonos/diakonos.conf + +.BR +includes: + +.BR + status: basic syntax highlighting + +.BR +comments: assumes dark background; no display line\-wrap + +.BR +* kate & kwrite + +.BR + file: sisu.xml + +.BR + place in: + +.BR + /usr/share/apps/katepart/syntax + +.BR + or + +.BR + ~/.kde/share/apps/katepart/syntax + +.BR + \ [settings::configure \ kate::{highlighting,filetypes}] + +.BR + \ [tools::highlighting::{markup,scripts}:: +.B \ SiSU +] + +.BR +* nedit + +.BR + file: sisu_nedit.pats + +.BR + nedit \-import sisu_nedit.pats + +.BR + status: a very clumsy first attempt \ [not \ really \ done] + +.BR + comments: this editor features display line wrap + +.BR +* emacs + +.BR + files: sisu\-mode.el + +.BR + to file ~/.emacs add the following 2 lines: + +.BR + (add\-to\-list \'load\-path \"/usr/share/sisu\-examples/config/syntax_hi\") + +.BR + (require \'sisu\-mode.el) + +.BR + \ [not \ done \ / \ not \ yet \ included] + +.BR +* vim & gvim + +.BR + files: + +.BR + 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) + +.BR + status: this includes: syntax highlighting; vim folds; some error checking + +.BR + comments: this editor features display line wrap + +.BR +NOTE: + +.BR +[ +.B \ 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] + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Syntax Highlighting \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_syntax_highlighting.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_syntax_highlighting.sst)= +.I 1dfe1975df71459c3f56c3fd13c5789c + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:02 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_syntax_highlighting/sisu_syntax_highlighting.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_vim.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_vim.1 new file mode 100644 index 00000000..61538145 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_vim.1 @@ -0,0 +1,196 @@ +.TH "sisu_vim" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- VIM, +RALPH AMISSAH +.BR + +.SH +SISU VIM +.BR + +.SH +1. SISU VIM +.BR + +.BR +.B Synopsis + +.BR +.B SiSU +has syntax highlighting for a number of editors including vim which are +documented under: + +.BR + man sisu_syntax_highlighting + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + +.BR + + +.BR + + +.BR +.B SiSU +also provides an ftplugin to provide vim folds for +.B SiSU +markup, and to set some defaults for +.B SiSU +markup in installed by sisu. + +.BR +Vim 7 includes sisu markup syntax highlighting. + +.BR +Vim related files are included in: /usr/share/sisu/conf/editor\-syntax\-etc/vim +(including the syntax highlighter which may be used for earlier versions of +Vim). + +.BR +sisu\-vim actions are activated on files with the suffix .sst .ssm .ssi .\-sst +._sst (and the same with a further .meta extension) + + +.nf + F activate folds on headings matched in a document + (also provides folds when sourced on a ruby program file), + also :F + S search and replace down + G search and replace globally within file + X ruby regex global search and replace within file + C set color scheme to slate which is provided +.fi + +.BR +FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR + + +.BR +or man sisu + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Vim + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_vim.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_vim.sst)= +.I a3db74eebef04815aa234d3c3b17f375 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:48 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_vim/sisu_vim.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:52 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_vim.7 b/data/doc/manuals_generated/sisu_manual/man/sisu_vim.7 new file mode 100644 index 00000000..65d97d53 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_vim.7 @@ -0,0 +1,196 @@ +.TH "sisu_vim" "1" "2007-09-16" "0.58.3" "SiSU" +.SH +SISU \- VIM, +RALPH AMISSAH +.BR + +.SH +SISU VIM +.BR + +.SH +1. SISU VIM +.BR + +.BR +.B Synopsis + +.BR +.B SiSU +has syntax highlighting for a number of editors including vim which are +documented under: + +.BR + man sisu_syntax_highlighting + +.BR + /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html + +.BR + + +.BR + + +.BR +.B SiSU +also provides an ftplugin to provide vim folds for +.B SiSU +markup, and to set some defaults for +.B SiSU +markup in installed by sisu. + +.BR +Vim 7 includes sisu markup syntax highlighting. + +.BR +Vim related files are included in: /usr/share/sisu/conf/editor\-syntax\-etc/vim +(including the syntax highlighter which may be used for earlier versions of +Vim). + +.BR +sisu\-vim actions are activated on files with the suffix .sst .ssm .ssi .\-sst +._sst (and the same with a further .meta extension) + + +.nf + F activate folds on headings matched in a document + (also provides folds when sourced on a ruby program file), + also :F + S search and replace down + G search and replace globally within file + X ruby regex global search and replace within file + C set color scheme to slate which is provided +.fi + +.BR +FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR + + +.BR +or man sisu + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- Vim + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-11\-12 + +.BR +DC Date issued: +.I 2002\-11\-12 + +.BR +DC Date available: +.I 2002\-11\-12 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_vim.sst + +.BR +Filetype: +.I SiSU text insert 0.58 + +.BR +Sourcefile Digest, MD5(sisu_vim.sst)= +.I a3db74eebef04815aa234d3c3b17f375 + +.BR +Skin_Digest: +MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)= +.I 20fc43cf3eb6590bc3399a1aef65c5a9 + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 01:14:04 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.58.3 +of 2007w36/4 (2007\-09\-06) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_vim/sisu_vim.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 01:14:07 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu diff --git a/data/doc/manuals_generated/sisu_manual/man/sisu_webrick.1 b/data/doc/manuals_generated/sisu_manual/man/sisu_webrick.1 new file mode 100644 index 00000000..285a35f1 --- /dev/null +++ b/data/doc/manuals_generated/sisu_manual/man/sisu_webrick.1 @@ -0,0 +1,218 @@ +.TH "sisu_webrick" "1" "2007-09-16" "0.59.0" "SiSU" +.SH +SISU \- SISU_WEBRICK \ [0.58], +RALPH AMISSAH +.BR + +.SH +SISU WEBRICK +.BR + +.SH +1. SISU_WEBRICK +.BR + +.SH +1.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.SH +1.2 SYNOPSIS + +.BR +sisu_webrick \ [port] + +.BR +or + +.BR +sisu \-W \ [port] + +.SH +1.3 DESCRIPTION + +.BR +sisu_webrick is part of +.B SiSU +(man sisu) sisu_webrick starts +.B Ruby +\'s Webrick web\-server and points it to the directories to which +.B SiSU +output is written, providing a list of these directories (assuming +.B SiSU +is in use and they exist). + +.BR +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). + +.SH +1.4 SUMMARY OF MAN PAGE + +.BR +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] + +.BR +where no port is given and settings are unchanged the default port is 8081 + +.SH +1.5 DOCUMENT PROCESSING COMMAND FLAGS + +.BR +sisu \-W \ [port] starts +.B Ruby +Webrick web\-server, serving +.B 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 + +.SH +1.6 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR +or man sisu + +.SH +1.7 AUTHOR + +.BR +Ralph Amissah or + +.SH +1.8 SEE ALSO + +.BR + sisu(1) + +.BR + sisu_vim(7) + +.BR + sisu(8) + +.SH +DOCUMENT INFORMATION (METADATA) +.BR + +.SH +METADATA +.BR + +.BR +Document Manifest @ + + +.BR +.B Dublin Core +(DC) + +.BR +.I DC tags included with this document are provided here. + +.BR +DC Title: +.I SiSU \- sisu_webrick \ [0.58] + +.BR +DC Creator: +.I Ralph Amissah + +.BR +DC Rights: +.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL +3 + +.BR +DC Type: +.I information + +.BR +DC Date created: +.I 2002\-08\-28 + +.BR +DC Date issued: +.I 2002\-08\-28 + +.BR +DC Date available: +.I 2007\-08\-28 + +.BR +DC Date modified: +.I 2007\-09\-16 + +.BR +DC Date: +.I 2007\-09\-16 + +.BR +.B Version Information + +.BR +Sourcefile: +.I sisu_webrick.sst + +.BR +Filetype: +.I SiSU text 0.58 + +.BR +Sourcefile Digest, MD5(sisu_webrick.sst)= +.I d288c50a18a6d7464fdb3413479b8b98 + +.BR +Skin_Digest: MD5(/etc/sisu/skin/doc/skin_sisu.rb)= +.I c4b3c21ba1ed0d491bfe14cd0fcd075e + +.BR +.B Generated + +.BR +Document (metaverse) last generated: +.I Sun Sep 23 04:13:44 +0100 2007 + +.BR +Generated by: +.I SiSU +.I 0.59.0 +of 2007w38/0 (2007\-09\-23) + +.BR +Ruby version: +.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux] + + +.TP +Other versions of this document: +.TP +manifest: +.TP +html: +.TP +pdf: +.TP +pdf: +." .TP +." manpage: http://www.jus.uio.no/sisu/sisu_webrick/sisu_webrick.1 +.TP +at: +.TP +.TP +* Generated by: SiSU 0.59.0 of 2007w38/0 (2007-09-23) +.TP +* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux] +.TP +* Last Generated on: Sun Sep 23 04:13:50 +0100 2007 +.TP +* SiSU http://www.jus.uio.no/sisu -- cgit v1.2.3