From b571083d97d62e381d9b0cccd41889cfc95256a4 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Mon, 7 Feb 2011 11:53:21 -0500 Subject: documentation & man pages, add sisu3, sisu-po and touches --- man/man1/sisu-concordance.1 | 4 + man/man1/sisu-epub.1 | 4 + man/man1/sisu-git.1 | 2 + man/man1/sisu-harvest.1 | 4 + man/man1/sisu-html.1 | 4 + man/man1/sisu-odf.1 | 4 + man/man1/sisu-pdf.1 | 4 + man/man1/sisu-pg.1 | 4 + man/man1/sisu-po.1 | 42 + man/man1/sisu-sqlite.1 | 4 + man/man1/sisu-txt.1 | 4 + man/man1/sisu3.1 | 4806 +++++++++++++++++++++++++++++++++++++++++++ 12 files changed, 4886 insertions(+) create mode 100644 man/man1/sisu-po.1 create mode 100644 man/man1/sisu3.1 (limited to 'man/man1') diff --git a/man/man1/sisu-concordance.1 b/man/man1/sisu-concordance.1 index da2cdb7a..d21c7a02 100644 --- a/man/man1/sisu-concordance.1 +++ b/man/man1/sisu-concordance.1 @@ -16,6 +16,8 @@ The \fBsisu\-concordance\fR command is an alias for \fBsisu \-\-concordance\fR ( .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-concordance\fR command is an alias for \fBsisu \-\-concordance\fR ( .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-epub.1 b/man/man1/sisu-epub.1 index 8036b214..216ff352 100644 --- a/man/man1/sisu-epub.1 +++ b/man/man1/sisu-epub.1 @@ -16,6 +16,8 @@ The \fBsisu\-epub\fR command is an alias for \fBsisu \-\-epub\fR (or \fBsisu \-e .br \fIsisu\-concordance\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-epub\fR command is an alias for \fBsisu \-\-epub\fR (or \fBsisu \-e .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-git.1 b/man/man1/sisu-git.1 index 9401c70d..21907f17 100644 --- a/man/man1/sisu-git.1 +++ b/man/man1/sisu-git.1 @@ -26,6 +26,8 @@ The \fBsisu\-git\fR command is an alias for \fBsisu \-\-git\fR (or \fBsisu \-g\f .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-harvest.1 b/man/man1/sisu-harvest.1 index 3f450986..6a521cee 100644 --- a/man/man1/sisu-harvest.1 +++ b/man/man1/sisu-harvest.1 @@ -18,6 +18,8 @@ The \fBsisu\-harvest\fR command is an alias for \fBsisu \-\-harvest\fR which bas .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-html\fR(1), .br \fIsisu\-pdf\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-harvest\fR command is an alias for \fBsisu \-\-harvest\fR which bas .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-html.1 b/man/man1/sisu-html.1 index 8af826cc..9226016d 100644 --- a/man/man1/sisu-html.1 +++ b/man/man1/sisu-html.1 @@ -18,6 +18,8 @@ The \fBsisu\-html\fR command is an alias for \fBsisu \-\-html\fR (or \fBsisu \-h .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-pdf\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-html\fR command is an alias for \fBsisu \-\-html\fR (or \fBsisu \-h .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-odf.1 b/man/man1/sisu-odf.1 index 7e12508c..6573f7c8 100644 --- a/man/man1/sisu-odf.1 +++ b/man/man1/sisu-odf.1 @@ -18,6 +18,8 @@ The \fBsisu\-odf\fR command is an alias for \fBsisu \-\-odt\fR (or \fBsisu \-o\f .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-odf\fR command is an alias for \fBsisu \-\-odt\fR (or \fBsisu \-o\f .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-pdf.1 b/man/man1/sisu-pdf.1 index 20782f75..65309edb 100644 --- a/man/man1/sisu-pdf.1 +++ b/man/man1/sisu-pdf.1 @@ -18,6 +18,8 @@ The \fBsisu\-pdf\fR command is an alias for \fBsisu \-\-pdf\fR (or \fBsisu \-p\f .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -26,6 +28,8 @@ The \fBsisu\-pdf\fR command is an alias for \fBsisu \-\-pdf\fR (or \fBsisu \-p\f .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1), .br \fIsisu\-txt\fR(1). diff --git a/man/man1/sisu-pg.1 b/man/man1/sisu-pg.1 index d94d4b0c..4df0d792 100644 --- a/man/man1/sisu-pg.1 +++ b/man/man1/sisu-pg.1 @@ -18,12 +18,16 @@ The \fBsisu\-pq\fR command is an alias for \fBsisu \-\-pg\fR (or \fBsisu \-D\fR) .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), .br \fIsisu\-pdf\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-odf\fR(1), .br \fIsisu\-sqlite\fR(1), diff --git a/man/man1/sisu-po.1 b/man/man1/sisu-po.1 new file mode 100644 index 00000000..dc0460bf --- /dev/null +++ b/man/man1/sisu-po.1 @@ -0,0 +1,42 @@ +.TH SISU\-ODF 1 2011\-02\-07 3.0.0 SiSU + +.SH NAME +\fBSiSU\fR \- Structured information, Serialized Units \- a document publishing system + +.SH SYNOPSIS +\fBsisu\-odf\fR \fIsisu_document.sst\fR | \fIsisu_document.ssm\fR + +.SH DESCRIPTION +\fBSiSU\fR is a lightweight markup based document structuring, publishing and search framework for document collections. +.PP +The \fBsisu\-po\fR command is an alias for \fBsisu \-\-po4a\fR (or \fBsisu \-o\fR) which provided two sisu markup files of the same document in different languages produces .pot and .po output of a SiSU markup file. Experimental, and under development. + +.SH SEE ALSO +\fIsisu\fR(1), +.br +\fIsisu\-concordance\fR(1), +.br +\fIsisu\-epub\fR(1), +.br +\fIsisu\-git\fR(1), +.br +\fIsisu\-harvest\fR(1), +.br +\fIsisu\-html\fR(1), +.br +\fIsisu\-odf\fR(1), +.br +\fIsisu\-pdf\fR(1), +.br +\fIsisu\-pg\fR(1), +.br +\fIsisu\-sqlite\fR(1), +.br +\fIsisu\-txt\fR(1). + +.SH HOMEPAGE +More information about \fBSiSU\fR can be found at <\fIhttp://www.jus.uio.no/sisu/\fR>. + +.SH AUTHOR +\fBSiSU\fR was written by Ralph Amissah <\fIralph@amissah.com\fR>. + diff --git a/man/man1/sisu-sqlite.1 b/man/man1/sisu-sqlite.1 index f808aaa9..2916cd8a 100644 --- a/man/man1/sisu-sqlite.1 +++ b/man/man1/sisu-sqlite.1 @@ -18,6 +18,8 @@ The \fBsisu\-sqlite\fR command is an alias for \fBsisu \-\-sqlite\fR (or \fBsisu .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -28,6 +30,8 @@ The \fBsisu\-sqlite\fR command is an alias for \fBsisu \-\-sqlite\fR (or \fBsisu .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-txt\fR(1). .SH HOMEPAGE diff --git a/man/man1/sisu-txt.1 b/man/man1/sisu-txt.1 index 51cedf4c..79c36daf 100644 --- a/man/man1/sisu-txt.1 +++ b/man/man1/sisu-txt.1 @@ -18,6 +18,8 @@ The \fBsisu\-txt\fR command is an alias for \fBsisu \-\-txt\fR (or \fBsisu \-t\f .br \fIsisu\-epub\fR(1), .br +\fIsisu\-git\fR(1), +.br \fIsisu\-harvest\fR(1), .br \fIsisu\-html\fR(1), @@ -28,6 +30,8 @@ The \fBsisu\-txt\fR command is an alias for \fBsisu \-\-txt\fR (or \fBsisu \-t\f .br \fIsisu\-pg\fR(1), .br +\fIsisu\-po\fR(1), +.br \fIsisu\-sqlite\fR(1). .SH HOMEPAGE diff --git a/man/man1/sisu3.1 b/man/man1/sisu3.1 new file mode 100644 index 00000000..96b69e36 --- /dev/null +++ b/man/man1/sisu3.1 @@ -0,0 +1,4806 @@ +.TH "sisu" "1" "2011-02-07" "3.0.0" "SiSU" +.SH NAME +sisu \- documents: markup, structuring, publishing in multiple standard formats, and search +.SH SYNOPSIS +sisu [\-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] [filename/wildcard] + +.BR +sisu [\-P] [language_directory/filename language_directory] + +.BR +sisu [\-Ddcv] [instruction] [filename/wildcard] + +.BR +sisu [\-CcFLSVvW] + +.BR +sisu \-\-v2 [operations] + +.BR +sisu \-\-v1 [operations] +.SH +SISU \- MANUAL, +RALPH AMISSAH +.BR + +.SH +WHAT IS SISU? +.BR + +.SH +1. INTRODUCTION \- WHAT IS SISU? +.BR + +.BR +.B SiSU +is a framework for document structuring, publishing (in multiple open +standard formats) 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 (including +the population of sql databases) 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). Its use +case for development is work with medium to large document sets and cope with +evolving document formats/ representation technologies. Documents are prepared +once, and generated as need be to update the technical presentation or add +additional output formats. Various output formats (including search related +output) share a common mechanism for cross\-output\-format citation. + +.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, EPUB, 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. + +.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 (to take advantage of the strengths of different ways of +representing documents) various standard open output formats including plain +text, HTML, XHTML, XML, EPUB, OpenDocument, LaTeX or PDF files, and populate an +SQL database with objects[^1] (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[^2] +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 headings[^3] and objects[^4], 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 basis for citing +material within a document across the different output format types. This is +significant as page numbers are not well suited to the digital age, in web +publishing, changing a browser's default font or using a different browser can +mean that text will appear on a different page; and publishing in different +formats, html, landscape and portrait pdf etc. again page numbers are not +useful to cite text. Dealing with documents at an object level together with +object numbering also has implications for search that +.B SiSU +is able to take advantage of. + +.BR +One of the challenges of maintaining documents is to keep them in a format that +allows use of them independently of proprietary platforms. Consider issues +related to 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 producing documents in multiple non\-proprietary +open formats including html, pdf[^5] ODF,[^6] and EPUB.[^7] 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 when it became an ISO standard for +office applications and the archival of documents), EPUB was introduced in +2009; and allows the technical representations 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 thesauri, 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. COMMANDS SUMMARY +.BR + +.SH +2.1 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, +xhtml, XML, epub, odt (odf text), LaTeX, pdf, info, and SQL (PostgreSQL and +SQLite), which share numbered text objects ("object citation numbering") and +the same document structure information. For more see: + + +.SH +2.2 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] +see \-\-xhtml + +.TP +.B \-\-color\-toggle [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). Alias \-c + +.TP +.B \-\-concordance [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). Alias \-w + +.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] +see \-\-color\-toggle + +.TP +.B \-\-dal [filename/wildcard/url] +assumed for most other flags, creates new intermediate files for processing +(document abstraction) that is used in all subsequent processing of other +output. This step is assumed for most processing flags. To skip it see \-n. +Alias \-m + +.TP +.B \-\-delete [filename/wildcard] +see \-\-zap + +.TP +.B \-D [instruction] [filename] +see \-\-pg + +.TP +.B \-d [\-\-db\-[database \ type \ (sqlite|pg)]] \-\-[instruction] [filename] +see \-\-sqlite + +.TP +.B \-\-epub [filename/wildcard] +produces an epub document, [sisu \ version \ 2 \ only] (filename.epub). Alias +\-e + +.TP +.B \-e [filename/wildcard] +see \-\-epub + +.TP +.B \-F [\-\-webserv=webrick] +see \-\-sample\-search\-form + +.TP +.B \-\-git [filename/wildcard] +produces or updates markup source file structure in a git repo (experimental +and subject to change). Alias \-g + +.TP +.B \-g [filename/wildcard] +see \-\-git + +.TP +.B \-\-harvest *.ss[tm] +makes two lists of sisu output based on the sisu markup documents in a +directory: list of author and authors works (year and titles), and; list by +topic with titles and author. Makes use of header metadata fields (author, +title, date, topic_register). Can be used with maintenance (\-M) and remote +placement (\-R) flags. + +.TP +.B \-\-help [topic] +provides help on the selected topic, where topics (keywords) include: list, +(com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers, +headings, endnotes, tables, example, customise, skin, (dir)ectories, path, +(lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql, +features, license + +.TP +.B \-\-html [filename/wildcard] +produces html output, segmented text with table of contents (toc.html and +index.html) and the document in a single file (scroll.html). Alias \-h + +.TP +.B \-h [filename/wildcard] +see \-\-html + +.TP +.B \-I [filename/wildcard] +see \-\-texinfo + +.TP +.B \-i [filename/wildcard] +see \-\-manpage + +.TP +.B \-L +prints license information. + +.TP +.B \-\-machine [filename/wildcard/url] +see \-\-dal (document abstraction level/layer) + +.TP +.B \-\-maintenance [filename/wildcard/url] +maintenance mode files created for processing preserved and their locations +indicated. (also see \-V). Alias \-M + +.TP +.B \-\-manpage [filename/wildcard] +produces man page of file, not suitable for all outputs. Alias \-i + +.TP +.B \-M [filename/wildcard/url] +see \-\-maintenance + +.TP +.B \-m [filename/wildcard/url] +see \-\-dal (document abstraction level/layer) + +.TP +.B \-\-no\-ocn +[with \ \-\-html \ \-\-pdf \ or \ \-\-epub] switches off object citation +numbering. Produce output without identifying numbers in margins of html or +LaTeX/pdf output. + +.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 the creation of intermediate processing files (document abstraction) if +they already exist, this skips the equivalent of \-m which is otherwise assumed +by most processing flags. + +.TP +.B \-\-odf [filename/wildcard/url] +see \-\-odt + +.TP +.B \-\-odt [filename/wildcard/url] +output basic document in opendocument file format (opendocument.odt). Alias +\-o + +.TP +.B \-o [filename/wildcard/url] +see \-\-odt + +.TP +.B \-\-pdf [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). Alias \-p + +.TP +.B \-\-pg [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. Alias +\-D + +.TP +.B \-\-po [language_directory/filename language_directory] +see \-\-po4a + +.TP +.B \-\-po4a [language_directory/filename language_directory] +produces .pot and po files for the file in the languages specified by the +language directory. SiSU markup is placed in subdirectories named with the +language code, e.g. en/ fr/ es/. The sisu config file must set the output +directory structure to multilingual. v3, experimental + +.TP +.B \-P [language_directory/filename language_directory] +see \-\-po4a + +.TP +.B \-p [filename/wildcard] +see \-\-pdf + +.TP +.B \-\-quiet [filename/wildcard] +quiet less output to screen. + +.TP +.B \-q [filename/wildcard] +see \-\-quiet + +.TP +.B \-\-rsync [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 \-\-scp. Alias \-R + +.TP +.B \-R [filename/wildcard] +see \-\-rsync + +.TP +.B \-r [filename/wildcard] +see \-\-scp + +.TP +.B \-\-sample\-search\-form [\-\-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. Alias \-F + +.TP +.B \-\-scp [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 \-\-rsync. Alias \-r + +.TP +.B \-\-sqlite \-\-[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. Alias \-d + +.TP +.B \-\-sisupod +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). Alias \-S + +.TP +.B \-\-sisupod [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]. +Alias \-S + +.TP +.B \-\-source [filename/wildcard] +copies sisu markup file to output directory. Alias \-s + +.TP +.B \-S +see \-\-sisupod + +.TP +.B \-S [filename/wildcard] +see \-\-sisupod + +.TP +.B \-s [filename/wildcard] +see \-\-source + +.TP +.B \-\-texinfo [filename/wildcard] +produces texinfo and info file, (view with pinfo). Alias \-I + +.TP +.B \-\-txt [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). Alias \-t + +.TP +.B \-T [filename/wildcard \ (*.termsheet.rb)] +standard form document builder, preprocessing feature + +.TP +.B \-t [filename/wildcard] +see \-\-txt + +.TP +.B \-\-urls [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. Alias \-U + +.TP +.B \-U [filename/wildcard] +see \-\-urls + +.TP +.B \-u [filename/wildcard] +provides url mapping of output files for the flags requested for processing, +also see \-U + +.TP +.B \-\-v1 [filename/wildcard] +invokes the sisu v1 document parser/generator. For use with sisu v1 markup +documents. (Markup conversion to v2 involves the modification of document +headers) + +.TP +.B \-\-v2 [filename/wildcard] +invokes the sisu v2 document parser/generator. This is the default and is +normally omitted. + +.TP +.B \-\-verbose [filename/wildcard] +provides verbose output of what is being generated, where output is placed +(and error messages if any), as with \-u flag provides a url mapping of files +created for each of the processing flag requests. Alias \-v + +.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. + +.TP +.B \-v +on its own, provides +.B SiSU +version information + +.TP +.B \-v [filename/wildcard] +see \-\-verbose + +.TP +.B \-\-webrick +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 \ ]. Alias \-W + +.TP +.B \-W +see \-\-webrick + +.TP +.B \-\-wordmap [filename/wildcard] +see \-\-concordance + +.TP +.B \-w [filename/wildcard] +see \-\-concordance + +.TP +.B \-\-xhtml [filename/wildcard] +produces xhtml/XML output for browser viewing (sax parsing). Alias \-b + +.TP +.B \-\-xml\-dom [filename/wildcard] +produces XML output with deep document structure, in the nature of dom. Alias +\-X + +.TP +.B \-\-xml\-sax [filename/wildcard] +produces XML output shallow structure (sax parsing). Alias \-x + +.TP +.B \-X [filename/wildcard] +see \-\-xml\-dom + +.TP +.B \-x [filename/wildcard] +see \-\-xml\-sax + +.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 \-\-zap [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. Alias \-Z + +.TP +.B \-Z [filename/wildcard] +see \-\-zap + +.SH +3. COMMAND LINE MODIFIERS +.BR + +.TP +.B \-\-no\-ocn +[with \ \-\-html \ \-\-pdf \ or \ \-\-epub] 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 +4. 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 \-\-pg \-v \-\-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 \-\-pg \-v \-\-import +[filename/wildcard] imports data specified to postgresql db (rb.dbi) [ \ \-dv +\ \-\-import \ sqlite \ equivalent] + +.TP +.B \-\-pg \-v \-\-update +[filename/wildcard] updates/imports specified data to postgresql db (rb.dbi) +[ \ \-dv \ \-\-update \ sqlite \ equivalent] + +.TP +.B \-\-pg \-\-remove +[filename/wildcard] removes specified data to postgresql db (rb.dbi) [ \ \-d +\ \-\-remove \ sqlite \ equivalent] + +.TP +.B \-\-pg \-\-dropall +kills data" and drops (postgresql or sqlite) db, tables & indexes [ \ \-d \ +\-\-dropall \ sqlite \ equivalent] + +.BR +The \-v is for verbose output. + +.SH +5. 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 +\-mhewpy + +.TP +.B \-2 +\-mhewpaoy + +.TP +.B \-3 +\-mhewpAobxXyY + +.TP +.B \-4 +\-mhewpAobxXDyY \-\-import + +.TP +.B \-5 +\-mhewpAobxXDyY \-\-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 +5.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 +6. HELP +.BR + +.SH +6.1 SISU MANUAL + +.BR +The most up to date information on sisu should be contained in the sisu_manual, +available at: + +.BR + + +.BR +The manual can be generated from source, found respectively, either within the +.B SiSU +tarball or installed locally at: + +.BR + ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/ + +.BR + /usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/ + +.BR +move to the respective directory and type e.g.: + +.BR + sisu sisu_manual.ssm + +.SH +6.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/v2/sisu_markup_samples/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/v2/html/ + +.BR + ./data/doc/sisu/v2/html/ + +.BR +An online version of the sisu man page is available here: + +.BR +* various sisu man pages [^8] + +.BR +* sisu.1 [^9] + +.SH +6.3 SISU BUILT\-IN INTERACTIVE HELP + +.BR +This is particularly useful for getting the current sisu setup/environment +information: + +.BR + sisu \-\-help + +.BR + sisu \-\-help [subject] + +.BR + sisu \-\-help commands + +.BR + sisu \-\-help markup + +.BR + sisu \-\-help env [for \ feedback \ on \ the \ way \ your \ system \ is \ + setup \ with \ regard \ to \ sisu] + +.BR + sisu \-V [environment \ information, \ same \ as \ above \ command] + +.BR + sisu (on its own provides version and some help information) + +.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 +6.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/v2/html/sisu.1.html + +.BR + + +.SH +7. INTRODUCTION TO SISU MARKUP[^10] +.BR + +.SH +7.1 SUMMARY + +.BR +.B SiSU +source documents are plaintext (UTF\-8)[^11] 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 + +.BR +To check the markup in a file: + +.BR + sisu \-\-identify [filename].sst + +.BR +For brief descriptive summary of markup history + +.BR + sisu \-\-query\-history + +.BR +or if for a particular version: + +.BR + sisu \-\-query\-0.38 + +.SH +7.2 MARKUP EXAMPLES + +.SH +7.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 +7.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 +8. MARKUP OF HEADERS +.BR + +.BR +Headers contain either: semantic meta\-data about a document, which can be used +by any output module of the program, or; 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 +8.1 SAMPLE HEADER + +.BR +This current document is loaded by a master document that has a header similar +to this one: + + +.nf + % SiSU master 2.0 + @title: SiSU + :subtitle: Manual + @creator: :author: Amissah, Ralph + @rights: Copyright (C) Ralph Amissah 2007, License GPL 3 + @classify: + :type: information + :topic_register: SiSU:manual;electronic documents:SiSU:manual + :subject: ebook, epublishing, electronic book, electronic publishing, + electronic document, electronic citation, data structure, + citation systems, search + % used_by: manual + @date: :published: 2008\-05\-22 + :created: 2002\-08\-28 + :issued: 2002\-08\-28 + :available: 2002\-08\-28 + :modified: 2010\-03\-03 + @make: :num_top: 1 + :breaks: new=C; break=1 + :skin: skin_sisu_manual + :bold: /Gnu|Debian|Ruby|SiSU/ + :manpage: name=sisu \- documents: markup, structuring, publishing + in multiple standard formats, and search; + synopsis=sisu \ [\-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0\-9] \ [filename/wildcard \ ] + . sisu \ [\-Ddcv] \ [instruction] + . sisu \ [\-CcFLSVvW] + . sisu \-\-v2 \ [operations] + . sisu \-\-v1 \ [operations] + @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/ + { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.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 + { SiSU help }http://www.jus.uio.no/sisu/sisu_manual/sisu_help/ + { SiSU help sources }http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/ +.fi + +.SH +8.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 + + +.nf + % SiSU 2.0 \ [declared \ file\-type \ identifier \ with \ markup \ version] +.fi + +.nf + @title: \ [title \ text] \ [this \ header \ is \ the \ only \ one \ that \ is \ mandatory] + :subtitle: \ [subtitle \ if \ any] + :language: English +.fi + +.nf + @creator: :author: \ [Lastname, \ First \ names] + :illustrator: \ [Lastname, \ First \ names] + :translator: \ [Lastname, \ First \ names] + :prepared_by: \ [Lastname, \ First \ names] +.fi + +.nf + @date: :published: \ [year \ or \ yyyy\-mm\-dd] + :created: \ [year \ or \ yyyy\-mm\-dd] + :issued: \ [year \ or \ yyyy\-mm\-dd] + :available: \ [year \ or \ yyyy\-mm\-dd] + :modified: \ [year \ or \ yyyy\-mm\-dd] + :valid: \ [year \ or \ yyyy\-mm\-dd] + :added_to_site: \ [year \ or \ yyyy\-mm\-dd] + :translated: \ [year \ or \ yyyy\-mm\-dd] +.fi + +.nf + @rights: :copyright: Copyright (C) \ [Year \ and \ Holder] + :license: \ [Use \ License \ granted] + :text: \ [Year \ and \ Holder] + :translation: \ [Name, \ Year] + :illustrations: \ [Name, \ Year] +.fi + +.nf + @classify: + :topic_register: SiSU:markup sample:book;book:novel:fantasy + :type: + :subject: + :description: + :keywords: + :abstract: + :isbn: \ [ISBN] + :loc: \ [Library \ of \ Congress \ classification] + :dewey: \ [Dewey \ classification + :pg: \ [Project \ Gutenberg \ text \ number] +.fi + +.nf + @links: { SiSU }http://www.jus.uio.no/sisu/ + { FSF }http://www.fsf.org +.fi + +.nf + @make: + :skin: skin_name + [skins change default settings related to the appearance of documents generated] + :num_top: 1 + :headings: \ [text \ to \ match \ for \ each \ level + (e.g. PART; Chapter; Section; Article; + or another: none; BOOK|FIRST|SECOND; none; CHAPTER;) + :breaks: new=:C; break=1 + :promo: sisu, ruby, sisu_search_libre, open_society + :bold: [regular expression of words/phrases to be made bold] + :italics: \ [regular \ expression \ of \ words/phrases \ to \ italicise] +.fi + +.nf + @original: :language: \ [language] +.fi + +.nf + @notes: :comment: + :prefix: \ [prefix \ is \ placed \ just \ after \ table \ of \ contents] +.fi + +.SH +9. MARKUP OF SUBSTANTIVE TEXT +.BR + +.SH +9.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 +9.2 FONT ATTRIBUTES + +.BR +.B markup example: + + +.nf + normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}", + ^{superscript}^, ,{subscript},, +{inserted text}+, \-{strikethrough}\- #{monospace}# +.BR + normal text +.BR + !{emphasis}! +.BR + *{bold text}* +.BR + _{underscore}_ +.BR + /{italics}/ +.BR + "{citation}" +.BR + ^{superscript}^ +.BR + ,{subscript}, +.BR + +{inserted text}+ +.BR + \-{strikethrough}\- +.BR + #{monospace}# +.fi + +.BR +.B resulting output: + +.BR +normal text +.B emphasis +.B bold text +.I underscore +.I italics +"citation" ^superscript^ [subscript] ++inserted text++ \-\-strikethrough\-\- monospace + +.BR +normal text + +.BR +.B emphasis +[note: \ can \ be \ configured \ to \ be \ represented \ by \ bold, \ italics +\ or \ underscore] + +.BR +.B bold text + +.BR +.I italics + +.BR +.I underscore + +.BR +"citation" + +.BR +^superscript^ + +.BR +[subscript] + +.BR +++inserted text++ + +.BR +\-\-strikethrough\-\- + +.BR +monospace + +.SH +9.3 INDENTATION AND BULLETS + +.BR +.B markup example: + + +.nf + ordinary paragraph +.BR + _1 indent paragraph one step +.BR + _2 indent paragraph two steps +.BR + _9 indent paragraph nine steps +.fi + + +.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 +.BR + _1* bullet text, first indent +.BR + _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. +.BR + _# numbered list numbered list indented a., b., c., d., etc. +.fi + +.SH +9.4 FOOTNOTES / ENDNOTES + +.BR +Footnotes and endnotes not distinguished in markup. They are automatically +numbered. Depending on the output file format (html, EPUB, 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 +[^12] + +.BR +.B markup example: + + +.nf + normal text~{ self contained endnote marker & endnote in one }~ continues +.fi + +.BR +.B resulting output: + +.BR +normal text[^13] continues + +.BR +.B markup example: + + +.nf + normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues +.BR + 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 +.BR + 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 + % note the endnote marker \"~^\" +.BR + normal text~^ continues +.BR + ^~ 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 +9.5 LINKS + +.SH +9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS + +.BR +urls found within text are 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 +.BR + 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 +9.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 +abou tSiSU [^14] markup + +.SH +9.5.3 LINKING IMAGES + +.BR +.B markup example: + + +.nf + { tux.png 64x80 }image +.BR + % various url linked images +.BR + {tux.png 64x80 \"a better way\" }http://www.jus.uio.no/sisu/ +.BR +.BR + {GnuDebianLinuxRubyBetterWay.png 100x101 \"Way Better \- with Gnu/Linux, Debian and Ruby\" }http://www.jus.uio.no/sisu/ +.BR +.BR + {~^ ruby_logo.png \"Ruby\" }http://www.ruby\-lang.org/en/ +.BR +.BR +.fi + +.BR +.B resulting output: + +.BR +[ tux.png ] + +.BR +tux.png 64x80 \"Gnu/Linux \- a better way\" + +.BR +[ \ ruby_logo \ (png \ missing) \ ] [^15] + +.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 +9.6 GROUPED TEXT + +.SH +9.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: +[^16] + + +.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 +9.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 +.BR + mouse, That he +.BR + met in the +.BR + house, +.BR + \"Let us +.BR + both go to +.BR + law: I will +.BR + prosecute +.BR + YOU. \-\-Come, +.BR + I\'ll take no +.BR + denial; We +.BR + must have a +.BR + trial: For +.BR + really this +.BR + morning I\'ve +.BR + nothing +.BR + to do.\" +.BR + Said the +.BR + mouse to the +.BR + cur, \"Such +.BR + a trial, +.BR + dear Sir, +.BR + With +.BR + no jury +.BR + or judge, +.BR + would be +.BR + wasting +.BR + our +.BR + breath.\" +.BR + \"I\'ll be +.BR + judge, I\'ll +.BR + be jury,\" +.BR + Said +.BR + cunning +.BR + old Fury: +.BR + \"I\'ll +.BR + try the +.BR + whole +.BR + cause, +.BR + and +.BR + condemn +.BR + you +.BR + to +.BR + death.\"\' +.BR + +.SH +9.6.3 GROUP + +.BR +.B basic markup: + + +.nf + group{ +.BR + Your grouped text here +.BR + }group +.BR + A group is treated as an object and given a single object number. +.fi + +.BR +.B markup example: + + +.nf + group{ +.BR + \'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 +.BR + mouse, That he +.BR + met in the +.BR + house, +.BR + \"Let us +.BR + both go to +.BR + law: I will +.BR + prosecute +.BR + YOU. \-\-Come, +.BR + I\'ll take no +.BR + denial; We +.BR + must have a +.BR + trial: For +.BR + really this +.BR + morning I\'ve +.BR + nothing +.BR + to do.\" +.BR + Said the +.BR + mouse to the +.BR + cur, \"Such +.BR + a trial, +.BR + dear Sir, +.BR + With +.BR + no jury +.BR + or judge, +.BR + would be +.BR + wasting +.BR + our +.BR + breath.\" +.BR + \"I\'ll be +.BR + judge, I\'ll +.BR + be jury,\" +.BR + Said +.BR + cunning +.BR + old Fury: +.BR + \"I\'ll +.BR + try the +.BR + whole +.BR + cause, +.BR + and +.BR + condemn +.BR + you +.BR + to +.BR + death.\"\' +.BR + +.SH +9.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 +9.7 BOOK INDEX + +.BR +To make an index append to paragraph the book index term relates to it, using +an equal sign and curly braces. + +.BR +Currently two levels are provided, a main term and if needed a sub\-term. +Sub\-terms are separated from the main term by a colon. + + +.nf + Paragraph containing main term and sub\-term. + ={Main term:sub\-term} +.fi + +.BR +The index syntax starts on a new line, but there should not be an empty line +between paragraph and index markup. + +.BR +The structure of the resulting index would be: + + +.nf + Main term, 1 + sub\-term, 1 +.fi + +.BR +Several terms may relate to a paragraph, they are separated by a semicolon. If +the term refers to more than one paragraph, indicate the number of paragraphs. + + +.nf + Paragraph containing main term, second term and sub\-term. + ={first term; second term: sub\-term} +.fi + +.BR +The structure of the resulting index would be: + + +.nf + First term, 1, + Second term, 1, + sub\-term, 1 +.fi + +.BR +If multiple sub\-terms appear under one paragraph, they are separated under the +main term heading from each other by a pipe symbol. + + +.nf + Paragraph containing main term, second term and sub\-term. + ={Main term:sub\-term+1|second sub\-term + A paragraph that continues discussion of the first sub\-term +.fi + +.BR +The plus one in the example provided indicates the first sub\-term spans one +additional paragraph. The logical structure of the resulting index would be: + + +.nf + Main term, 1, + sub\-term, 1\-3, + second sub\-term, 1, +.fi + +.SH +10. 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 + << filename.ssi + <<{filename.ssi} + % using textlink alternatives + << |filename.ssi|@|^| +.fi + +.SH +MARKUP SYNTAX HISTORY +.BR + +.SH +11. 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 +* sisu \-\-query=[sisu \ version \ [0.38] or \'history] + +.BR +provides a short history of changes to +.B SiSU +markup + +.BR +.B 0.57 +(2007w34/4) +.B SiSU +0.57 is the same as 0.42 with the introduction of some a shortcut to use the +headers @title and @creator in the first heading [expanded \ using \ the \ +contents \ of \ the \ headers \ @title: \ and \ @author:] + + +.nf + :A~ @title by @author +.fi + +.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 SiSU +0.42 is the same as 0.38 with the introduction of some additional endnote +types, + +.BR +Introduces some variations on endnotes, in particular the use of the asterisk + + +.nf + ~{* for example for describing an author }~ and ~{** for describing a second author }~ +.fi + +.BR +* for example for describing an author + +.BR +** for describing a second author + +.BR +and + + +.nf + ~[* \ my \ note \ ]~ or ~[+ \ another \ note \ ]~ +.fi + +.BR +which numerically increments an asterisk and plus respectively + +.BR +*1 my note +1 another note + +.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 SiSU +0.38 introduced alternative experimental header and heading/structure +markers, + + +.nf + @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ +.fi + +.BR +as the equivalent of: + + +.nf + 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ +.fi + +.BR +The internal document markup of +.B SiSU +0.16 remains valid and standard Though note that +.B SiSU +0.37 introduced a new file naming convention + +.BR +.B SiSU +has in effect two sets of levels to be considered, using 0.38 notation A\-C +headings/levels, pre\-ordinary paragraphs /pre\-substantive text, and 1\-3 +headings/levels, levels which are followed by ordinary text. This may be +conceptualised as levels A,B,C, 1,2,3, and using such letter number notation, +in effect: A must exist, optional B and C may follow in sequence (not strict) 1 +must exist, optional 2 and 3 may follow in sequence i.e. there are two +independent heading level sequences A,B,C and 1,2,3 (using the 0.16 standard +notation 1,2,3 and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 +alternative makes explicit an aspect of structuring documents in +.B SiSU +that is not otherwise obvious to the newcomer (though it appears more +complicated, is more in your face and likely to be understood fairly quickly); +the substantive text follows levels 1,2,3 and it is \'nice\' to do most work in +those levels + +.BR +.B 0.37 +(2006w09/7) introduced new file naming convention, \.sst (text), \.ssm +(master), \.ssi (insert), markup syntax unchanged + +.BR +.B SiSU +0.37 introduced new file naming convention, using the file extensions \.sst + \.ssm and \.ssi to replace \.s1 \.s2 \.s3 \.r1 \.r2 \.r3 and \.si + +.BR +this is captured by the following file \'rename\' instruction: + + +.nf + rename \'s/\.s[123]$/\.sst/\' *.s{1,2,3} + rename \'s/\.r[123]$/\.ssm/\' *.r{1,2,3} + rename \'s/\.si$/\.ssi/\' *.si +.fi + +.BR +The internal document markup remains unchanged, from +.B SiSU +0.16 + +.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 + +.BR +.B SiSU +0.16 (0.15 development branch) introduced the use of + +.BR +the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ + +.BR +in place of the 0.1 header, heading/structure notation + +.BR +.B SiSU +0.1 headers and headings structure represented by header 0{~ and +headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ + +.SH +12. SISU FILETYPES +.BR + +.BR +.B SiSU +has plaintext and binary filetypes, and can process either type of document. + +.SH +12.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 +12.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 +12.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 [^17] + +.BR + + +.BR + + +.SH +12.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 +12.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 +13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS +.BR + +.SH +13.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 +13.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 +13.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 +13.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 +14. CONFIGURATION +.BR + +.SH +14.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 +14.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 +15. 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 +15.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 +15.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 +15.3 SITE SKIN + +.BR +A site skin, modifies the program default skin. + +.SH +15.4 SAMPLE SKINS + +.BR +With +.B SiSU +installed sample skins may be found in: + +.BR + /etc/sisu/skin/doc and + /usr/share/doc/sisu/v2/sisu_markup_samples/samples/_sisu/skin/doc + +.BR +(or equivalent directory) and if sisu\-markup\-samples is installed also under: + +.BR + /usr/share/doc/sisu\-markup\-samples/v2/samples/_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 +16. 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.[^18] + +.SH +17. ORGANISING CONTENT +.BR + +.SH +17.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 + +.SH +18. 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 +18.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 +18.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 +19. MARKUP AND OUTPUT EXAMPLES +.BR + +.SH +19.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 +20. 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 +21. SQL +.BR + +.SH +21.1 POPULATING SQL TYPE DATABASES + +.BR +.B SiSU +feeds sisu markupd documents into sql type databases PostgreSQL[^19] and/or +SQLite[^20] 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 +22. POSTGRESQL +.BR + +.SH +22.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system, +postgresql dependency package + +.SH +22.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 +22.3 SYNOPSIS + +.BR + sisu \-D [instruction] [filename/wildcard \ if \ required] + +.BR + sisu \-D \-\-pg \-\-[instruction] [filename/wildcard \ if \ required] + +.SH +22.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 +22.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 +22.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 +23. SQLITE +.BR + +.SH +23.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system. + +.SH +23.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 +23.3 SYNOPSIS + +.BR + sisu \-d [instruction] [filename/wildcard \ if \ required] + +.BR + sisu \-d \-\-(sqlite|pg) \-\-[instruction] [filename/wildcard \ if \ + required] + +.SH +23.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 +23.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 +23.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 +24. INTRODUCTION +.BR + +.SH +24.1 SEARCH \- DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES, +INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) + +.BR +Sample search frontend [^21] A small database and +sample query front\-end (search from) that makes use of the citation system, +.I object citation numbering +to demonstrates functionality.[^22] + +.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, EPUB, +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.[^23] + +.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 +24.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 +25. HYPERESTRAIER +.BR + +.BR +See the documentation for hyperestraier: + +.BR + + +.BR + /usr/share/doc/hyperestraier/index.html + +.BR + man estcmd + +.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 +26. SISU_WEBRICK +.BR + +.SH +26.1 NAME + +.BR +.B SiSU +\- Structured information, Serialized Units \- a document publishing system + +.SH +26.2 SYNOPSIS + +.BR +sisu_webrick [port] + +.BR +or + +.BR +sisu \-W [port] + +.SH +26.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 +26.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 +26.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 +26.6 FURTHER INFORMATION + +.BR +For more information on +.B SiSU +see: + +.BR +or man sisu + +.SH +26.7 AUTHOR + +.BR +Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com + +.SH +26.8 SEE ALSO + +.BR + sisu(1) + +.BR + sisu_vim(7) + +.BR + sisu(8) + +.SH +27. 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 +28. 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 +28.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 +28.2 CONFIGURATION + +.BR +[expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] + +.SH +29. 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 +30. QUICKSTART \- GETTING STARTED HOWTO +.BR + +.SH +30.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 +30.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 +.BR + 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 +.BR + deb http://ftp.fi.debian.org/debian/ unstable main non\-free contrib +.BR + deb\-src http://ftp.fi.debian.org/debian/ unstable main non\-free contrib +.BR + d +.fi + +.BR +The aptitude commands become: + + +.nf + aptitude update +.BR + 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 +30.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 +30.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, EPUB, 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)[^24] 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 +30.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 +30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB + +.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 +30.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 +30.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 +30.3 GETTING HELP + +.SH +30.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 [^25] + +.BR +* sisu.8 [^26] + +.BR +* man directory [^27] + +.SH +30.3.2 BUILT IN HELP + +.BR +sisu \-\-help + +.BR +sisu \-\-help \-\-env + +.BR +sisu \-\-help \-\-commands + +.BR +sisu \-\-help \-\-markup + +.SH +30.3.3 THE HOME PAGE + +.BR + + +.BR + + +.SH +30.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[^28] 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 +31. EDITOR FILES, SYNTAX HIGHLIGHTING +.BR + +.BR +The directory: + +.BR + \./data/sisu/v2/conf/editor\-syntax\-etc/ + +.BR + /usr/share/sisu/v2/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/v1/conf/editor\-syntax\-etc/emacs\") + +.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 +32. 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 +33. 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, epub, +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 + * epub + +.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, EPUB, 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, epub in 2009 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, EPUB, 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 +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 +.B sisu generated output \- links to html + +.BR + + +.BR +.B help sources lists + +.BR +Alternative sources for this help sources page listed here: + +.BR + man sisu_help_sources + +.BR + + +.SH +34.1 MAN PAGES + +.SH +34.1.1 MAN + +.BR + man sisu + +.BR + man 7 sisu_complete + +.BR + man 7 sisu_pdf + +.BR + man 7 sisu_postgresql + +.BR + man 7 sisu_sqlite + +.BR + man sisu_termsheet + +.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, odf and epub which may be also be accessed via the html pages[^28] + +.SH +34.2.1 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.3 MAN2HTML + +.SH +34.3.1 LOCALLY INSTALLED + +.BR + + +.BR + + +.BR + + +.BR + /usr/share/doc/sisu/v2/html/sisu.1.html + +.BR + /usr/share/doc/sisu/v2/html/sisu_pdf.7.html + +.BR + /usr/share/doc/sisu/v2/html/sisu_postgresql.7.html + +.BR + /usr/share/doc/sisu/v2/html/sisu_sqlite.7.html + +.BR + /usr/share/doc/sisu/v2/html/sisu_webrick.1.html + +.SH +34.3.2 WWW.JUS.UIO.NO/SISU + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.BR + + +.TP +.BI 1. +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 2. +i.e. the html, pdf, epub, 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. + +.BR +.TP +.BI 3. +the different heading levels +.TP +.BI 4. +units of text, primarily paragraphs and headings, also any tables, poems, +code-blocks +.TP +.BI 5. +Specification submitted by Adobe to ISO to become a full open ISO +specification + +.TP +.BI 6. +ISO standard ISO/IEC 26300:2006 + +.BR +.TP +.BI 7. +An open standard format for e-books + +.BR +.TP +.BI *1. +square brackets +.TP +.BI *2. +square brackets +.TP +.BI +1. +square brackets +.TP +.BI 8. + +.TP +.BI 9. + +.TP +.BI 10. +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 11. +files should be prepared using UTF-8 character encoding +.TP +.BI 12. +a footnote or endnote +.TP +.BI 13. +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 14. + +.TP +.BI 15. + +.TP +.BI 16. +Table from the Wealth of Networks by Yochai Benkler + +.TP +.BI 17. +\.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 19. + + + +.TP +.BI 20. + + +.TP +.BI 21. + +.TP +.BI 22. +(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 23. +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 24. +There is nothing to stop MySQL support being added in future. +.TP +.BI 25. + +.TP +.BI 26. + +.TP +.BI 27. + +.TP +.BI 28. +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 29. +named index.html or more extensively through sisu_manifest.html + +.SH SEE ALSO +\fIsisu\fR(1), +.br +\fIsisu\-epub\fR(1), +.br +\fIsisu\-harvest\fR(1), +.br +\fIsisu\-html\fR(1), +.br +\fIsisu\-odf\fR(1), +.br +\fIsisu\-pdf\fR(1), +.br +\fIsisu\-pg\fR(1), +.br +\fIsisu\-sqlite\fR(1), +.br +\fIsisu\-txt\fR(1). +.br +\fIsisu_vim\fR(7) +.br +\fIsisu\fR(8) + +.SH HOMEPAGE +More information about \fBSiSU\fR can be found at <\fIhttp://www.jus.uio.no/sisu/\fR>. + +.SH AUTHOR +\fBSiSU\fR was written by Ralph Amissah <\fIralph@amissah.com\fR>. -- cgit v1.2.3