diff options
Diffstat (limited to 'data')
| -rw-r--r-- | data/doc/sisu/html/sisu-concordance.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-epub.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-git.1.html | 2 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-harvest.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-html.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-odf.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-pdf.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-pg.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-po.1.html | 73 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-sqlite.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu-txt.1.html | 4 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu.1.html | 1509 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu3.1.html | 3520 | ||||
| -rw-r--r-- | data/doc/sisu/html/sisu_vim.7.html | 101 |
14 files changed, 4410 insertions, 831 deletions
diff --git a/data/doc/sisu/html/sisu-concordance.1.html b/data/doc/sisu/html/sisu-concordance.1.html index 0c1f5622..f1ca71bb 100644 --- a/data/doc/sisu/html/sisu-concordance.1.html +++ b/data/doc/sisu/html/sisu-concordance.1.html @@ -30,6 +30,8 @@ for <b>sisu --concordance</b> (or <b>sisu -w</b>) which produces an HTML concord , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -40,6 +42,8 @@ for <b>sisu --concordance</b> (or <b>sisu -w</b>) which produces an HTML concord , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-epub.1.html b/data/doc/sisu/html/sisu-epub.1.html index f3722477..747756ac 100644 --- a/data/doc/sisu/html/sisu-epub.1.html +++ b/data/doc/sisu/html/sisu-epub.1.html @@ -30,6 +30,8 @@ The <b>sisu-epub</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-concordance:1'><i>sisu-concordance</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -40,6 +42,8 @@ The <b>sisu-epub</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-git.1.html b/data/doc/sisu/html/sisu-git.1.html index 8df25642..6c70396f 100644 --- a/data/doc/sisu/html/sisu-git.1.html +++ b/data/doc/sisu/html/sisu-git.1.html @@ -40,6 +40,8 @@ document and associated parts (images, ). , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-harvest.1.html b/data/doc/sisu/html/sisu-harvest.1.html index 8a542a94..410c805f 100644 --- a/data/doc/sisu/html/sisu-harvest.1.html +++ b/data/doc/sisu/html/sisu-harvest.1.html @@ -34,6 +34,8 @@ Also</a></h2> , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a> @@ -42,6 +44,8 @@ Also</a></h2> , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-html.1.html b/data/doc/sisu/html/sisu-html.1.html index 99fd959f..2672f615 100644 --- a/data/doc/sisu/html/sisu-html.1.html +++ b/data/doc/sisu/html/sisu-html.1.html @@ -32,6 +32,8 @@ The <b>sisu-html</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a> @@ -40,6 +42,8 @@ The <b>sisu-html</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-odf.1.html b/data/doc/sisu/html/sisu-odf.1.html index ae929917..ef3110f8 100644 --- a/data/doc/sisu/html/sisu-odf.1.html +++ b/data/doc/sisu/html/sisu-odf.1.html @@ -32,6 +32,8 @@ file. , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -40,6 +42,8 @@ file. , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-pdf.1.html b/data/doc/sisu/html/sisu-pdf.1.html index 685e0a68..bb34a771 100644 --- a/data/doc/sisu/html/sisu-pdf.1.html +++ b/data/doc/sisu/html/sisu-pdf.1.html @@ -32,6 +32,8 @@ Also</a></h2> , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -40,6 +42,8 @@ Also</a></h2> , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-pg.1.html b/data/doc/sisu/html/sisu-pg.1.html index c87ae7a7..fec48e39 100644 --- a/data/doc/sisu/html/sisu-pg.1.html +++ b/data/doc/sisu/html/sisu-pg.1.html @@ -32,12 +32,16 @@ The <b>sisu-pq</b> command is an alias for <b>sisu , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-odf:1'><i>sisu-odf</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> diff --git a/data/doc/sisu/html/sisu-po.1.html b/data/doc/sisu/html/sisu-po.1.html new file mode 100644 index 00000000..681cda4c --- /dev/null +++ b/data/doc/sisu/html/sisu-po.1.html @@ -0,0 +1,73 @@ +<!-- manual page source format generated by PolyglotMan v3.2, --> +<!-- available at http://polyglotman.sourceforge.net/ --> + +<html> +<head> +<title>SISU\-ODF(1) manual page</title> +</head> +<body bgcolor='white'> +<a href='#toc'>Table of Contents</a><p> + +<p> +<h2><a name='sect0' href='#toc0'>Name</a></h2> +<b>SiSU</b> - Structured information, Serialized Units - a document publishing + +<p>system +<p> +<h2><a name='sect1' href='#toc1'>Synopsis</a></h2> +<b>sisu-odf</b> <i>sisu_document.sst</i> | <i>sisu_document.ssm</i> +<p> +<h2><a name='sect2' href='#toc2'>Description</a></h2> +<b>SiSU</b> +is a lightweight markup based document structuring, publishing and search +framework for document collections. <p> +The <b>sisu-po</b> command is an alias for <b>sisu +--po4a</b> (or <b>sisu -o</b>) 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. +<p> +<h2><a name='sect3' href='#toc3'>See Also</a></h2> +<a href='http:~/bin/man2html?sisu:1'><i>sisu</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-concordance:1'><i>sisu-concordance</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-odf:1'><i>sisu-odf</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> +. +<p> +<h2><a name='sect4' href='#toc4'>Homepage</a></h2> +More information about <b>SiSU</b> can be found at <<a href='http://www.jus.uio.no/sisu/'><i>http://www.jus.uio.no/sisu/</i></a> +>. + +<p> +<h2><a name='sect5' href='#toc5'>Author</a></h2> +<b>SiSU</b> was written by Ralph Amissah <<i>ralph@amissah.com</i>>. +<p> <p> + +<hr><p> +<a name='toc'><b>Table of Contents</b></a><p> +<ul> +<li><a name='toc0' href='#sect0'>Name</a></li> +<li><a name='toc1' href='#sect1'>Synopsis</a></li> +<li><a name='toc2' href='#sect2'>Description</a></li> +<li><a name='toc3' href='#sect3'>See Also</a></li> +<li><a name='toc4' href='#sect4'>Homepage</a></li> +<li><a name='toc5' href='#sect5'>Author</a></li> +</ul> +</body> +</html> diff --git a/data/doc/sisu/html/sisu-sqlite.1.html b/data/doc/sisu/html/sisu-sqlite.1.html index ab0997e8..7a09c353 100644 --- a/data/doc/sisu/html/sisu-sqlite.1.html +++ b/data/doc/sisu/html/sisu-sqlite.1.html @@ -32,6 +32,8 @@ The <b>sisu-sqlite</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -42,6 +44,8 @@ The <b>sisu-sqlite</b> command is an alias for , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> . <p> diff --git a/data/doc/sisu/html/sisu-txt.1.html b/data/doc/sisu/html/sisu-txt.1.html index 2479cd8e..3edb168f 100644 --- a/data/doc/sisu/html/sisu-txt.1.html +++ b/data/doc/sisu/html/sisu-txt.1.html @@ -32,6 +32,8 @@ file. , <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-git:1'><i>sisu-git</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> @@ -42,6 +44,8 @@ file. , <br> <a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> , <br> +<a href='http:~/bin/man2html?sisu-po:1'><i>sisu-po</i>(1)</a> +, <br> <a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> . <p> diff --git a/data/doc/sisu/html/sisu.1.html b/data/doc/sisu/html/sisu.1.html index 67867294..1a598784 100644 --- a/data/doc/sisu/html/sisu.1.html +++ b/data/doc/sisu/html/sisu.1.html @@ -18,20 +18,20 @@ sisu [-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0-9] <p> sisu [-CcFLSVvW] <p> sisu --v2 [operations] -<p> sisu --v1 [operations] SISU - MANUAL, -RALPH AMISSAH +<p> sisu --v3 [operations] +<p> sisu3 [operations] +SISU - MANUAL, RALPH AMISSAH <p> WHAT IS SISU? <p> 1. INTRODUCTION - WHAT IS SISU? -<p> <b>SiSU</b> 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. -<p> <b>SiSU</b> is developed under an -open source, software libre license (GPL3). Its use case for development +<p> <b>SiSU</b> 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. +<p> <b>SiSU</b> 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 @@ -128,158 +128,159 @@ system to reliably reference its documents. <b>SiSU</b> works well in a compleme 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</b> <p> -<<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > <p> 2. COMMANDS SUMMARY -<p> 2.1 DESCRIPTION -<p> <b>SiSU</b> <b>SiSU</b> -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: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<p> 2.1 + +<p>DESCRIPTION +<p> <b>SiSU</b> <b>SiSU</b> 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: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > - <p> 2.2 DOCUMENT PROCESSING COMMAND FLAGS <p> <dl> -<dt><b>-a [filename/wildcard]</b> </dt> -<dd>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 (Options include: --endnotes for endnotes ---footnotes for footnotes at the end of each paragraph --unix for unix linefeed -(default) --msdos for msdos linefeed) +<dt><b>-a [filename/wildcard]</b> +</dt> +<dd>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 -A endnotes]. (Options +include: --endnotes for endnotes --footnotes for footnotes at the end of each +paragraph --unix for unix linefeed (default) --msdos for msdos linefeed) <p> </dd> -<dt><b>-b [filename/wildcard]</b> </dt> +<dt><b>-b +[filename/wildcard]</b> </dt> <dd>see --xhtml <p> </dd> -<dt><b>--color-toggle -[filename/wildcard]</b> </dt> -<dd>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 +<dt><b>--color-toggle [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> -<p>- -<p>c +<dt><b>--concordance [filename/wildcard]</b> +</dt> +<dd>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 <p> </dd> -<dt><b>--concordance [filename/wildcard]</b> </dt> -<dd>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 +<dt><b>-C +[--init-site]</b> </dt> +<dd>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. <p> </dd> -<dt><b>-C [--init-site]</b> </dt> +<dt><b>-CC</b> </dt> <dd>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. +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. <p> </dd> -<dt><b>-CC</b> </dt> -<dd>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. +<dt><b>-c [filename/wildcard]</b> </dt> +<dd>see --color-toggle <p> </dd> -<dt><b>-c [filename/wildcard]</b> +<dt><b>--dal [filename/wildcard/url]</b> </dt> -<dd> -<p>see --color-toggle +<dd>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. + +<p>Alias -m <p> </dd> -<dt><b>--dal [filename/wildcard/url]</b> </dt> -<dd>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 +<dt><b>--delete [filename/wildcard]</b> </dt> +<dd>see --zap <p> </dd> -<dt><b>--delete [filename/wildcard]</b> +<dt><b>-D [instruction] [filename]</b> </dt> <dd> -<p>see --zap +<p>see --pg <p> </dd> -<dt><b>-D [instruction] [filename]</b> </dt> -<dd>see --pg -<p> </dd> - -<dt><b>-d [--db-[database type (sqlite|pg)]] ---[instruction] [filename]</b> </dt> +<dt><b>-d [--db-[database type (sqlite|pg)]] --[instruction] [filename]</b> </dt> <dd>see --sqlite + <p> </dd> <dt><b>--epub [filename/wildcard]</b> </dt> -<dd>produces -an epub document, [sisu version 2 only] (filename.epub). Alias -e +<dd>produces an epub document, [sisu version 2 only] +(filename.epub). Alias -e +<p> </dd> + +<dt><b>-e [filename/wildcard]</b> </dt> +<dd>see --epub <p> </dd> -<dt><b>-e [filename/wildcard]</b> +<dt><b>-F [--webserv=webrick]</b> </dt> <dd> -<p>see --epub +<p>see --sample-search-form <p> </dd> -<dt><b>-F [--webserv=webrick]</b> </dt> -<dd>see --sample-search-form -<p> </dd> +<dt><b>--git [filename/wildcard]</b> </dt> +<dd>produces or updates markup +source file structure in a git repo (experimental and subject to change). -<dt><b>--git [filename/wildcard]</b> -</dt> -<dd>produces or updates markup source file structure in a git repo (experimental -and subject to change). Alias -g +<p>Alias -g <p> </dd> <dt><b>-g [filename/wildcard]</b> </dt> <dd>see --git <p> </dd> -<dt><b>--harvest -*.ss[tm]</b> </dt> -<dd>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. +<dt><b>--harvest *.ss[tm]</b> </dt> +<dd>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. <p> </dd> <dt><b>--help [topic]</b> </dt> -<dd>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, - -<p>license +<dd>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 <p> </dd> <dt><b>--html [filename/wildcard]</b> </dt> -<dd>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 -<p> </dd> - -<dt><b>-h [filename/wildcard]</b> </dt> -<dd>see --html +<dd>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 <p> </dd> -<dt><b>-I [filename/wildcard]</b> +<dt><b>-h [filename/wildcard]</b> </dt> <dd> -<p>see --texinfo +<p>see --html +<p> </dd> + +<dt><b>-I [filename/wildcard]</b> </dt> +<dd>see --texinfo <p> </dd> <dt><b>-i [filename/wildcard]</b> </dt> @@ -288,83 +289,102 @@ file (scroll.html). Alias -h <dt><b>-L</b> </dt> <dd>prints license information. - <p> </dd> -<dt><b>--machine [filename/wildcard/url]</b> </dt> +<dt><b>--machine [filename/wildcard/url]</b> +</dt> <dd>see --dal (document abstraction level/layer) - <p> </dd> -<dt><b>--maintenance [filename/wildcard/url]</b> </dt> -<dd>maintenance mode files created for -processing preserved and their locations indicated. (also see -V). Alias -M - +<dt><b>--maintenance [filename/wildcard/url]</b> +</dt> +<dd>maintenance mode files created for processing preserved and their locations +indicated. (also see -V). Alias -M <p> </dd> <dt><b>--manpage [filename/wildcard]</b> </dt> -<dd>produces man page of file, not suitable for -all outputs. Alias -i +<dd>produces man +page of file, not suitable for all outputs. Alias -i <p> </dd> -<dt><b>-M [filename/wildcard/url]</b> </dt> -<dd>see --maintenance +<dt><b>-M [filename/wildcard/url]</b> +</dt> +<dd> +<p>see --maintenance <p> </dd> -<dt><b>-m [filename/wildcard/url]</b> -</dt> -<dd>see --dal (document abstraction level/layer) +<dt><b>-m [filename/wildcard/url]</b> </dt> +<dd>see --dal (document abstraction +level/layer) <p> </dd> <dt><b>--no-ocn</b> </dt> -<dd>[with --html --pdf or --epub] -switches off object citation numbering. Produce output without identifying -numbers in margins of html or LaTeX/pdf output. +<dd>[with --html --pdf or --epub] switches off object citation +numbering. Produce output without identifying numbers in margins of html +or LaTeX/pdf output. <p> </dd> -<dt><b>-N [filename/wildcard/url]</b> -</dt> -<dd>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. +<dt><b>-N [filename/wildcard/url]</b> </dt> +<dd>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. <p> </dd> -<dt><b>-n -[filename/wildcard/url]</b> </dt> -<dd>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. +<dt><b>-n [filename/wildcard/url]</b> </dt> +<dd>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. <p> </dd> -<dt><b>--odf [filename/wildcard/url]</b> -</dt> -<dd> -<p>see --odt +<dt><b>--odf [filename/wildcard/url]</b> </dt> +<dd>see --odt <p> </dd> -<dt><b>--odt [filename/wildcard/url]</b> </dt> -<dd>output basic document in opendocument -file format (opendocument.odt). Alias -o +<dt><b>--odt [filename/wildcard/url]</b> +</dt> +<dd>output basic document in opendocument file format (opendocument.odt). Alias + +<p>- +<p>o <p> </dd> <dt><b>-o [filename/wildcard/url]</b> </dt> <dd>see --odt - <p> </dd> <dt><b>--pdf [filename/wildcard]</b> </dt> -<dd>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 +<dd>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 +<p> </dd> + +<dt><b>--pg [instruction] +[filename]</b> </dt> +<dd>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 <p> </dd> -<dt><b>--pg [instruction] [filename]</b> </dt> -<dd>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 +<dt><b>--po [language_directory/filename + language_directory]</b> </dt> +<dd>see --po4a +<p> </dd> + +<dt><b>--po4a [language_directory/filename language_directory]</b> +</dt> +<dd>produces .pot and po files for the file in the languages specified by the +language directory. <b>SiSU</b> 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 +<p> </dd> + +<dt><b>-P [language_directory/filename + language_directory]</b> </dt> +<dd>see --po4a <p> </dd> <dt><b>-p [filename/wildcard]</b> </dt> @@ -438,8 +458,8 @@ below. Alias -d 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<br> - option is tested only with zsh). Alias -S +option. Note: (this option<br> + is tested only with zsh). Alias -S <p> </dd> <dt><b>--sisupod [filename/wildcard]</b> </dt> @@ -490,47 +510,43 @@ file to output directory. Alias -s </dt> <dd>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 (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 +[ -A for equivalent dos (linefeed) output file] [see -e for -A 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 + +<p>- +<p>t <p> </dd> -<dt><b>-T [filename/wildcard - (*.termsheet.rb)]</b> </dt> -<dd>standard form document builder, preprocessing feature -<p> -</dd> +<dt><b>-T [filename/wildcard (*.termsheet.rb)]</b> </dt> +<dd>standard form document builder, + +<p>preprocessing feature +<p> </dd> <dt><b>-t [filename/wildcard]</b> </dt> <dd>see --txt <p> </dd> -<dt><b>--urls [filename/wildcard]</b> </dt> -<dd>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 +<dt><b>--urls [filename/wildcard]</b> +</dt> +<dd>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 <p> </dd> <dt><b>-U [filename/wildcard]</b> </dt> <dd>see --urls -<p> </dd> - -<dt><b>-u [filename/wildcard]</b> -</dt> -<dd>provides url mapping of output files for the flags requested for processing, -<p>also see -U <p> </dd> -<dt><b>--v1 [filename/wildcard]</b> </dt> -<dd>invokes the sisu v1 document parser/generator. -For use with sisu v1 markup documents. (Markup conversion to v2 involves -the modification of document headers) +<dt><b>-u [filename/wildcard]</b> </dt> +<dd>provides url mapping of output files for the flags +requested for processing, also see -U <p> </dd> <dt><b>--v2 [filename/wildcard]</b> </dt> @@ -539,75 +555,79 @@ sisu v2 document parser/generator. This is the default and is normally omitted. <p> </dd> -<dt><b>--verbose [filename/wildcard]</b> </dt> -<dd>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. +<dt><b>--v3 [filename/wildcard]</b> </dt> +<dd>invokes the sisu v3 document parser/generator. Currently +under development and incomplete, v3 requires >= ruby1.9.2p180. You may run +sisu3 instead. +<p> </dd> -<p>Alias -v +<dt><b>--verbose [filename/wildcard]</b> </dt> +<dd>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 <p> </dd> <dt><b>-V</b> </dt> -<dd>on its own, provides <b>SiSU</b> version and environment information -(sisu --help env) +<dd>on its own, provides <b>SiSU</b> version and +environment information (sisu --help env) <p> </dd> <dt><b>-V [filename/wildcard]</b> </dt> -<dd>even more verbose than the -v flag. - +<dd>even more +verbose than the -v flag. <p> </dd> <dt><b>-v</b> </dt> <dd>on its own, provides <b>SiSU</b> version information + <p> </dd> -<dt><b>-v [filename/wildcard]</b> -</dt> -<dd> -<p>see --verbose +<dt><b>-v [filename/wildcard]</b> </dt> +<dd>see --verbose <p> </dd> <dt><b>--webrick</b> </dt> -<dd>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 and search --H ; also, note -F webrick ]. Alias -W +<dd>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 <p> </dd> <dt><b>-W</b> </dt> <dd>see --webrick <p> </dd> -<dt><b>--wordmap [filename/wildcard]</b> -</dt> -<dd> -<p>see --concordance +<dt><b>--wordmap +[filename/wildcard]</b> </dt> +<dd>see --concordance <p> </dd> <dt><b>-w [filename/wildcard]</b> </dt> <dd>see --concordance -<p> </dd> -<dt><b>--xhtml [filename/wildcard]</b> -</dt> -<dd>produces xhtml/XML output for browser viewing (sax parsing). Alias -b <p> </dd> -<dt><b>--xml-dom -[filename/wildcard]</b> </dt> -<dd>produces XML output with deep document structure, in -the nature of dom. Alias -X +<dt><b>--xhtml [filename/wildcard]</b> </dt> +<dd>produces xhtml/XML output for browser viewing +(sax parsing). Alias -b <p> </dd> -<dt><b>--xml-sax [filename/wildcard]</b> </dt> -<dd>produces XML output -shallow structure (sax parsing). Alias -x +<dt><b>--xml-dom [filename/wildcard]</b> </dt> +<dd>produces XML output with +deep document structure, in the nature of dom. Alias -X <p> </dd> -<dt><b>-X [filename/wildcard]</b> </dt> -<dd>see --xml-dom +<dt><b>--xml-sax [filename/wildcard]</b> +</dt> +<dd>produces XML output shallow structure (sax parsing). Alias -x +<p> </dd> +<dt><b>-X [filename/wildcard]</b> +</dt> +<dd> +<p>see --xml-dom <p> </dd> <dt><b>-x [filename/wildcard]</b> </dt> @@ -615,8 +635,8 @@ shallow structure (sax parsing). Alias -x <p> </dd> <dt><b>-Y [filename/wildcard]</b> </dt> -<dd>produces a short -sitemap entry for the document, based on html output and the sisu_manifest. +<dd>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]) <p> </dd> @@ -682,60 +702,60 @@ modifiable with --db=[database type (pgsql or sqlite)] <dd>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. +as working directory, as requested) (rb.dbi) [ -dv --createall 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. + <p> </dd> <dt><b>--pg -v --import</b> </dt> -<dd>[filename/wildcard] imports -data specified to postgresql db (rb.dbi) [ -dv --import sqlite equivalent] - +<dd>[filename/wildcard] imports data specified to postgresql db +(rb.dbi) [ -dv --import sqlite equivalent] <p> </dd> <dt><b>--pg -v --update</b> </dt> -<dd>[filename/wildcard] updates/imports specified data to postgresql -db (rb.dbi) [ -dv --update sqlite equivalent] +<dd>[filename/wildcard] +updates/imports specified data to postgresql db (rb.dbi) [ -dv --update sqlite + equivalent] <p> </dd> <dt><b>--pg --remove</b> </dt> -<dd>[filename/wildcard] -removes specified data to postgresql db (rb.dbi) [ -d --remove sqlite equivalent] - +<dd>[filename/wildcard] removes specified data to postgresql +db (rb.dbi) [ -d --remove sqlite equivalent] <p> </dd> <dt><b>--pg --dropall</b> </dt> -<dd>kills data" and drops (postgresql or sqlite) db, tables & indexes -[ -d --dropall sqlite equivalent] +<dd>kills data" and drops +(postgresql or sqlite) db, tables & indexes [ -d --dropall sqlite equivalent] + <p> The -v is for verbose output. <p> </dd> </dl> -5. SHORTCUTS, -SHORTHAND FOR MULTIPLE FLAGS +5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS + <p> <dl> <dt><b>--update [filename/wildcard]</b> </dt> -<dd>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. +<dd>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. <p> </dd> -<dt><b>-0 to -5 [filename - or wildcard]</b> </dt> -<dd>Default shorthand mappings (note that the defaults can be -changed/configured in the sisurc.yml file): +<dt><b>-0 to -5 [filename or wildcard]</b> </dt> +<dd>Default +shorthand mappings (note that the defaults can be changed/configured in +the sisurc.yml file): <p> </dd> <dt><b>-0</b> </dt> -<dd>-mNhwpAobxXyYv [this is the - default action run when no i.e. on ’sisu [filename]’] +<dd>-mNhwpAobxXyYv [this is the default action run when + no i.e. on ’sisu [filename]’] <p> </dd> <dt><b>-1</b> </dt> @@ -744,7 +764,6 @@ changed/configured in the sisurc.yml file): <dt><b>-2</b> </dt> <dd>-mhewpaoy - <p> </dd> <dt><b>-3</b> </dt> @@ -752,38 +771,43 @@ changed/configured in the sisurc.yml file): <p> </dd> <dt><b>-4</b> </dt> -<dd>-mhewpAobxXDyY --import +<dd>-mhewpAobxXDyY + +<p>- +<p>- +<p>import <p> </dd> <dt><b>-5</b> </dt> <dd>-mhewpAobxXDyY --update -<p> add -v -for verbose mode and -c for color, e.g. sisu -2vc [filename or -<p> consider -u +<p> add -v for verbose mode and -c for color, +e.g. sisu -2vc [filename or +<p> consider -u for appended url info or -v for verbose -<p>for appended url info or -v for verbose output +<p>output <p> </dd> </dl> -5.1 COMMAND LINE WITH FLAGS -- BATCH PROCESSING -<p> 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. -<p> 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. +5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING +<p> 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. +<p> 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. <p> 6. HELP -<p> 6.1 SISU MANUAL -<p> The most up to date information -on sisu should be contained in the sisu_manual, available at: +<p> 6.1 SISU + +<p>MANUAL +<p> The most up to date information on sisu should be contained in +the sisu_manual, available at: <p> <<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a> ><br> <p> The manual can be generated from source, found respectively, either within the <b>SiSU</b> tarball or installed locally at: -<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> +<p> ./data/doc/sisu/markup-samples/sisu_manual<br> -<p> /usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> +<p> /usr/share/doc/sisu/markup-samples/sisu_manual<br> <p> move to the respective directory and type e.g.: <p> sisu sisu_manual.ssm<br> @@ -800,15 +824,15 @@ should be available, try: <p> Most <b>SiSU</b> 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</b> tarball at: -<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> +<p> ./data/doc/sisu/markup-samples/sisu_manual<br> <p> Once installed, directory equivalent to: -<p> /usr/share/doc/sisu/sisu_manual/<br> +<p> /usr/share/doc/sisu/markup-samples/sisu_manual<br> <p> Available man pages are converted back to html using man2html: -<p> /usr/share/doc/sisu/v2/html/<br> +<p> /usr/share/doc/sisu/html/<br> -<p> ./data/doc/sisu/v2/html/<br> +<p> ./data/doc/sisu/html<br> <p> An online version of the sisu man page is available here: <p> * various @@ -851,6 +875,9 @@ see: <p> <b>man2html</b> <p> /usr/share/doc/sisu/v2/html/sisu.1.html<br> +<p> <b>sisu generated html</b> +<p> /usr/share/doc/sisu/html/sisu_help_sources/index.html<br> + <p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> ><br> @@ -982,17 +1009,18 @@ that has a header similar to this one: <p> 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 +header instructions take the form @headername: or on the next line and +indented by once space :subheadername: All Dublin Core meta tags are available -<p>Dublin Core meta tags are available <p> <b>@indentifier:</b> information or instructions +<p> where the "identifier" is +a tag recognised by the program, and the "information" or "instructions" + +<p>belong to the tag/indentifier specified +<p> 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. -<p> where the "identifier" is a tag recognised by the program, and the "information" -or "instructions" belong to the tag/indentifier specified -<p> 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. <p> This is a sample header <p> <p> <br> @@ -1040,7 +1068,7 @@ and can be useful to know. :pg: [Project Gutenberg text number] </pre> <p> <br> -<pre> @links: { SiSU }http://www.jus.uio.no/sisu/ +<pre> @links: { SiSU }http://www.sisudoc.org { FSF }http://www.fsf.org </pre> <p> <br> @@ -1072,21 +1100,22 @@ 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) <p> <b>:A~ [heading - text]</b> Top level heading [this usually has similar content to the ] NOTE: -the heading levels described here are in 0.38 notation, see heading -<p> <b>:B~ -[heading text]</b> Second level heading [this is a heading level divider] -<p> - <b>:C~ [heading text]</b> Third level heading [this is a heading level divider] - -<p> <b>1~ [heading text]</b> 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 + text]</b> Top level heading [this usually has similar content to the title + @title: ] NOTE: the heading levels described here are in 0.38 notation, + +<p>see heading +<p> <b>:B~ [heading text]</b> Second level heading [this is a heading + level divider] +<p> <b>:C~ [heading text]</b> Third level heading [this is a heading + level divider] +<p> <b>1~ [heading text]</b> 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 <p> <b>2~ [heading text]</b> Second level heading preceding substantive text of -document or sub-heading 3, the heading level that would normally be marked +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. <p> <b>3~ [heading text]</b> Third level heading preceding substantive text of document, that would normally be @@ -1106,13 +1135,14 @@ html <p> <br> <pre> normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}", - ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}- #{monospace}# + ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}# normal text - !{emphasis}! - *{bold text}* + *{emphasis}* [note: can be configured to be represented by bold, italics + or underscore] + !{bold text}! _{underscore}_ /{italics}/ - + "{citation}" ^{superscript}^ ,{subscript}, +{inserted text}+ @@ -1120,12 +1150,13 @@ html #{monospace}# </pre> <p> <b>resulting output:</b> -<p> normal text <b>emphasis</b> <b>bold text</b> <i>underscore</i> <i>italics</i> -"citation" ^superscript^ [subscript] ++inserted text++ --strikethrough-- monospace +<p> normal text, <b>emphasis</b> , <b>bold text</b> , <i>italics</i> , <i>underscore</i> +, "citation", ^superscript^, [subscript], ++inserted text++, --strikethrough--, +<p>monospace <p> normal text -<p> <b>emphasis</b> [note: can be configured to be represented by - bold, italics or underscore] +<p> <b>emphasis</b> [note: can be configured to be represented + by bold, italics or underscore] <p> <b>bold text</b> <p> <i>italics</i> <p> <i>underscore</i> @@ -1177,10 +1208,11 @@ html _# numbered list numbered list indented a., b., c., d., etc. </pre> <p> 9.4 FOOTNOTES / ENDNOTES -<p> 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. +<p> Footnotes and endnotes are marked up at the +location where they would be indicated within a text. They are automatically +numbered. The output type determines whether footnotes or endnotes will + +<p>be produced <p> <b>markup example:</b> <p> <p> <br> @@ -1221,7 +1253,7 @@ asterisks if required }~ continues <p> <b>Alternative endnote pair notation for footnotes/endnotes:</b> <p> <p> <br> -<pre> % note the endnote marker +<pre> % note the endnote marker "~^" normal text~^ continues ^~ endnote text following the paragraph in which the marker occurs </pre> @@ -1239,10 +1271,10 @@ is omitted). <p> <b>markup example:</b> <p> <p> <br> -<pre> normal text http://www.jus.uio.no/sisu continues +<pre> normal text http://www.sisudoc.org/ continues </pre> <p> <b>resulting output:</b> -<p> normal text <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<p> normal text <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> > continues <p> An @@ -1250,70 +1282,74 @@ is omitted). <p> <b>markup example:</b> <p> <p> <br> -<pre> normal text _http://www.jus.uio.no/sisu continues +<pre> normal text _http://www.sisudoc.org/ continues deb http://www.jus.uio.no/sisu/archive unstable main non-free </pre> <p> <b>resulting output:</b> -<p> normal text <_<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<p> normal text <_<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> > continues -<p> -deb <_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> +<p> deb +<_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> > unstable main non-free -<p> where a code -block is used there is neither decoration nor hyperlinking, code blocks +<p> where a code block +is used there is neither decoration nor hyperlinking, code blocks are discussed -<p>are discussed later in this document +<p>later in this document <p> <b>resulting output:</b> <p> <p> <br> <pre> 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 </pre> -<p> To link text or an image to a url the markup is as follows -<p> <b>markup example:</b> +<p> 9.5.2 LINKING TEXT +<p> To link text or an image to a url the markup is as +<p>follows +<p> <b>markup example:</b> <p> <p> <br> <pre> about { SiSU }http://url.org markup </pre> -<p> 9.5.2 LINKING TEXT <p> <b>resulting output:</b> -<p> about SiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> -> +<p> aboutSiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> markup +<p> A shortcut -<p>markup -<p> A shortcut notation is available so the url link may also be provided +<p>notation is available so the url link may also be provided automatically -<p>automatically as a footnote +<p>as a footnote <p> <b>markup example:</b> <p> <p> <br> <pre> about {~^ SiSU }http://url.org markup </pre> <p> <b>resulting output:</b> -<p> abou tSiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +<p> about SiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> > [^14] markup -<p> +<p> 9.5.3 -<p>9.5.3 LINKING IMAGES +<p>LINKING IMAGES <p> <b>markup example:</b> <p> <p> <br> <pre> { tux.png 64x80 }image % various url linked images - {tux.png 64x80 - {GnuDebianLinuxRubyBetterWay.png 100x101 - {~^ ruby_logo.png + {tux.png 64x80 "a better way" }http://www.sisudoc.org/ + {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, +Debian and Ruby" }http://www.sisudoc.org/ + {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ </pre> <p> <b>resulting output:</b> <p> [ tux.png ] -<p> tux.png 64x80 -<p> [ ruby_logo (png missing) - ] [^15] -<p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby -<p> <b>linked url footnote +<p> tux.png 64x80 "Gnu/Linux - a better way" +<<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> [ ruby_logo (png missing) ] [^15] +<p> GnuDebianLinuxRubyBetterWay.png +100x101 "Way Better - with Gnu/Linux, Debian and Ruby" <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +> -<p>shortcut</b> +<p> <b>linked url footnote shortcut</b> <p> <p> <br> <pre> {~^ [text to link] }http://url.org @@ -1347,7 +1383,7 @@ auto-heading numbering, without further intervention. }table </pre> <p> <b>resulting output:</b> -<p> [table omitted, see other document formats]<br> +<p> [table omitted, see other document formats]<br> <p> a second form may be easier to work with in cases where there is not @@ -1375,7 +1411,7 @@ auto-heading numbering, without further intervention. <p> <b>resulting output:</b> <p> <b>Table 3.1: Contributors to Wikipedia, January 2001 - June 2005</b> -<p> [table omitted, see other document formats]<br> +<p> [table omitted, see other document formats]<br> <p> * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. @@ -1386,7 +1422,7 @@ auto-heading numbering, without further intervention. <pre> poem{ Your poem here }poem - Each verse in a poem is given a separate object number. + Each verse in a poem is given an object number. </pre> <p> <b>markup example:</b> <p> @@ -1396,7 +1432,7 @@ auto-heading numbering, without further intervention. mouse, That he met in the house, - + "Let us both go to law: I will prosecute @@ -1408,10 +1444,10 @@ auto-heading numbering, without further intervention. really this morning I’ve nothing - to do. + to do." Said the mouse to the - cur, + cur, "Such a trial, dear Sir, With @@ -1420,14 +1456,14 @@ auto-heading numbering, without further intervention. would be wasting our - breath. - + breath." + "I’ll be judge, I’ll - be jury, + be jury," Said cunning old Fury: - + "I’ll try the whole cause, @@ -1435,15 +1471,15 @@ auto-heading numbering, without further intervention. condemn you to - death. + death."’ }poem </pre> <p> <b>resulting output:</b> -<p> ’Fury said to a<br> +<p> ‘Fury said to a<br> mouse, That he<br> met in the<br> house,<br> - <br> + "Let us<br> both go to<br> law: I will<br> prosecute<br> @@ -1455,10 +1491,10 @@ auto-heading numbering, without further intervention. really this<br> morning I’ve<br> nothing<br> - to do.<br> + to do."<br> Said the<br> mouse to the<br> - cur,<br> + cur, "Such<br> a trial,<br> dear Sir,<br> With<br> @@ -1467,14 +1503,14 @@ auto-heading numbering, without further intervention. would be<br> wasting<br> our<br> - breath.<br> - <br> + breath."<br> + "I’ll be<br> judge, I’ll<br> - be jury,<br> + be jury,"<br> Said<br> cunning<br> old Fury:<br> - <br> + "I’ll<br> try the<br> whole<br> cause,<br> @@ -1482,7 +1518,7 @@ auto-heading numbering, without further intervention. condemn<br> you<br> to<br> - death.<br> + death."’<br> <p> 9.6.3 GROUP <p> <b>basic markup:</b> @@ -1501,7 +1537,7 @@ auto-heading numbering, without further intervention. mouse, That he met in the house, - + "Let us both go to law: I will prosecute @@ -1513,10 +1549,10 @@ auto-heading numbering, without further intervention. really this morning I’ve nothing - to do. + to do." Said the mouse to the - cur, + cur, "Such a trial, dear Sir, With @@ -1525,14 +1561,14 @@ auto-heading numbering, without further intervention. would be wasting our - breath. - + breath." + "I’ll be judge, I’ll - be jury, + be jury," Said cunning old Fury: - + "I’ll try the whole cause, @@ -1540,15 +1576,15 @@ auto-heading numbering, without further intervention. condemn you to - death. + death."’ }group </pre> <p> <b>resulting output:</b> -<p> ’Fury said to a<br> +<p> ‘Fury said to a<br> mouse, That he<br> met in the<br> house,<br> - <br> + "Let us<br> both go to<br> law: I will<br> prosecute<br> @@ -1560,10 +1596,10 @@ auto-heading numbering, without further intervention. really this<br> morning I’ve<br> nothing<br> - to do.<br> + to do."<br> Said the<br> mouse to the<br> - cur,<br> + cur, "Such<br> a trial,<br> dear Sir,<br> With<br> @@ -1572,14 +1608,14 @@ auto-heading numbering, without further intervention. would be<br> wasting<br> our<br> - breath.<br> - <br> + breath."<br> + "I’ll be<br> judge, I’ll<br> - be jury,<br> + be jury,"<br> Said<br> cunning<br> old Fury:<br> - <br> + "I’ll<br> try the<br> whole<br> cause,<br> @@ -1587,26 +1623,25 @@ auto-heading numbering, without further intervention. condemn<br> you<br> to<br> - death.<br> + death."’<br> <p> 9.6.4 CODE -<p> Code tags are used to escape regular sisu markup, and have -been used extensively within this document to provide examples of <b>SiSU</b> -markup. You cannot however use code tags to escape code tags. They are however -used in the same way as group or poem tags. -<p> A code-block is treated as -an object and given a single object number. [an more than 100 times in last -month. option to number each line of code may be considered at more than -100 times in last month. some later time] +<p> Code tags code{ ... }code (used as with other group tags described +above) are used to escape regular sisu markup, and have been used extensively +within this document to provide examples of <b>SiSU</b> markup. You cannot however +use code tags to escape code tags. They are however used in the same way +as group or poem tags. +<p> A code-block is treated as an object and given a +single object number. [an some later time] <p> <b>use of code tags instead of poem compared, resulting output:</b> <p> <p> <br> -<pre> ’Fury said to a +<pre> ‘Fury said to a mouse, That he met in the house, - + "Let us both go to law: I will prosecute @@ -1618,10 +1653,10 @@ poem compared, resulting output:</b> really this morning I’ve nothing - to do. + to do." Said the mouse to the - cur, + cur, "Such a trial, dear Sir, With @@ -1630,14 +1665,14 @@ poem compared, resulting output:</b> would be wasting our - breath. - + breath." + "I’ll be judge, I’ll - be jury, + be jury," Said cunning old Fury: - + "I’ll try the whole cause, @@ -1645,7 +1680,56 @@ poem compared, resulting output:</b> condemn you to - death. + death."’ +</pre> +<p> From <b>SiSU</b> 2.7.7 on you can number codeblocks by placing a hash after the +opening code tag code{# as demonstrated here: +<p> +<p> <br> +<pre>1 | ‘Fury said to a +2 | mouse, That he +3 | met in the +4 | house, +5 | "Let us +6 | both go to +7 | law: I will +8 | prosecute +9 | YOU. --Come, +10 | I’ll take no +11 | denial; We +12 | must have a +13 | trial: For +14 | really this +15 | morning I’ve +16 | nothing +17 | to do." +18 | Said the +19 | mouse to the +20 | cur, "Such +21 | a trial, +22 | dear Sir, +23 | With +24 | no jury +25 | or judge, +26 | would be +27 | wasting +28 | our +29 | breath." +30 | "I’ll be +31 | judge, I’ll +32 | be jury," +33 | Said +34 | cunning +35 | old Fury: +36 | "I’ll +37 | try the +38 | whole +39 | cause, +40 | and +41 | condemn +42 | you +43 | to +44 | death."’ </pre> <p> 9.7 BOOK INDEX <p> To make an index append to paragraph the book index term @@ -1737,16 +1821,17 @@ of documents under consideration, and occasionally supported have been. <p> MARKUP SYNTAX HISTORY <p> 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX -<p> 0.38 is substantially current, depreciated 0.16 supported, though file - -<p>names were changed at 0.37 -<p> * sisu --query=[sisu version [0.38] or ’history] +<p> 2.0 introduced new headers and is therefore incompatible with 1.0 though +otherwise the same with the addition of a couple of tags (i.e. a superset) +<p> 0.38 is substantially current for version 1.0 +<p> * sisu --query=[sisu version + [0.38] or ’history] <p> provides a short history of changes to <b>SiSU</b> markup -<p> <b>0.57</b> (2007w34/4) -<b>SiSU</b> 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 and @author:] + +<p> <b>0.57</b> (2007w34/4) <b>SiSU</b> 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 and @author:] <p> <p> <br> <pre> :A~ @title by @author @@ -1876,30 +1961,30 @@ may be located locally or on a remote server for which a url is provided. <p> 12.1.1 SISU TEXT - REGULAR FILES (.SST) <p> The most common form of document in <b>SiSU</b> , see the section on <b>SiSU</b> markup. -<p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_markup'>http://www.sisudoc.org/sisu/sisu_markup</a> > -<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a> > <p> 12.1.2 SISU MASTER FILES (.SSM) -<p> Composite -documents which incorporate other <b>SiSU</b> documents which may be either regular -<b>SiSU</b> text .sst which may be generated independently, or inserts prepared -solely for the purpose of being incorporated into one or more master documents. - -<p> The mechanism by which master files incorporate other documents is described -as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual. -<p> 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. -<p> Note: a secondary file of the composite document -is built prior to processing with the same prefix and the suffix ._sst [^17] - -<p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> +<p> + Composite documents which incorporate other <b>SiSU</b> documents which may be +either regular <b>SiSU</b> text .sst which may be generated independently, or inserts +prepared solely for the purpose of being incorporated into one or more +master documents. +<p> The mechanism by which master files incorporate other +documents is described as one of the headings under under <b>SiSU</b> markup in +the <b>SiSU</b> manual. +<p> 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. +<p> Note: a secondary file +of the composite document is built prior to processing with the same prefix +and the suffix ._sst [^17] +<p> <<a href='http://www.sisudoc.org/sisu/sisu_markup'>http://www.sisudoc.org/sisu/sisu_markup</a> > -<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a> > <p> 12.1.3 SISU INSERT FILES (.SSI) @@ -1935,10 +2020,10 @@ sisu -S<br> <p> <b>SiSU</b> processing can be done directly against a sisupod; which may be located locally or on a remote server for which a url is provided. -<p> <<a href='http://www.jus.uio.no/sisu/sisu_commands'>http://www.jus.uio.no/sisu/sisu_commands</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_commands'>http://www.sisudoc.org/sisu/sisu_commands</a> > -<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a> > <p> 13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS @@ -2082,17 +2167,17 @@ and symbolic links as needed from the site, or dir directories as required. <p> With <b>SiSU</b> installed sample skins may be found in: <p> /etc/sisu/skin/doc and<br> - /usr/share/doc/sisu/v2/sisu_markup_samples/samples/_sisu/skin/doc<br> + /usr/share/doc/sisu/markup-samples/samples/_sisu/skin/doc<br> <p> (or equivalent directory) and if sisu-markup-samples is installed also under: -<p> /usr/share/doc/sisu-markup-samples/v2/samples/_sisu/skin/doc<br> +<p> /usr/share/doc/sisu/markup-samples-non-free/samples/_sisu/skin/doc<br> <p> Samples of list.yml and promo.yml (which are used to create the right column list) may be found in: -<p> /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml -(or equivalent<br> - directory)<br> +<p> /usr/share/doc/sisu/markup-samples-non-free/samples/_sisu/skin/yml +(or<br> + equivalent directory)<br> <p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) <p> CSS files @@ -2201,47 +2286,42 @@ index.html and document output samples are provided at <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > -<p> Some markup with syntax highlighting may be found under <<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> -> -but is not as up to date. -<p> 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. -<p> 20. -SISU SEARCH - INTRODUCTION -<p> <b>SiSU</b> output can easily and conveniently be -indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. - -<p> 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. -<p> In addition to this <b>SiSU</b> 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. -<p> 21. SQL +<p> 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. +<p> 20. SISU SEARCH - INTRODUCTION + +<p> <b>SiSU</b> output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. +<p> 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. +<p> In addition to this <b>SiSU</b> 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. +<p> 21. +SQL <p> 21.1 POPULATING SQL TYPE DATABASES - -<p> <b>SiSU</b> feeds sisu markupd documents into sql type databases PostgreSQL[^19] -and/or SQLite[^20] database together with information related to document -structure. -<p> 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: -<p> * one containing semantic -(and other) headers, including, title, author,<br> +<p> <b>SiSU</b> feeds sisu markupd documents +into sql type databases PostgreSQL[^19] and/or SQLite[^20] database together +with information related to document structure. +<p> 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: + +<p> * one containing semantic (and other) headers, including, title, author,<br> subject, (the Dublin Core...);<br> <p> * another the substantive texts by individual "paragraph" (or object) --<br> - along with structural information, each paragraph being identifiable -by its<br> +- along<br> + with structural information, each paragraph being identifiable by its<br> paragraph number (if it has one which almost all of them do), and the<br> substantive text of each paragraph quite naturally being searchable (both in<br> @@ -2371,8 +2451,7 @@ to populate an sqlite database, this being part of <b>SiSU</b> - man sisu). <p>SYNOPSIS <p> sisu -d [instruction] [filename/wildcard if required]<br> -<p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if <br> - required]<br> +<p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required]<br> <p> 23.4 COMMANDS <p> Mappings to two databases are provided by default, postgresql @@ -2560,8 +2639,8 @@ be desirable to exclude files ’plain.txt’, ’toc.html’ an these duplicate information held in other html output e.g. <p> find /home/ralph/sisu_www -type f | egrep<br> - ’/sisu_www/(sisu|bookmarks)/.+?.html$’ | egrep -v<br> - ’(doc|concordance).html$’ |estcmd gather -sd casket -<br> + ’/sisu_www/(sisu|bookmarks)/.+?.html$’ | egrep -v ’(doc|concordance).html$’<br> + |estcmd gather -sd casket -<br> <p> from your current document preparation/markup directory, you would construct a rune along the following lines: @@ -2585,7 +2664,7 @@ and set file permissions to 755: <p> [see estraier documentation for paths]<br> <p> (ii) edit estseek.conf, with attention to the lines starting ’indexname:’ -and ’replace:’: +and <p> indexname: /home/ralph/sisu_www/casket<br> <p> replace: ^file:///home/ralph/sisu_www{{!}}<a href='http://localhost'>http://localhost</a> @@ -2611,37 +2690,38 @@ and ’replace:’: <p> 26.3 DESCRIPTION <p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick -starts <b>Ruby</b> ’s Webrick web-server and points it to the directories to which -<b>SiSU</b> output is written, providing a list of these directories (assuming -<b>SiSU</b> is in use and they exist). -<p> 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). +starts <b>Ruby</b> <b>SiSU</b> output is written, providing a list of these directories +(assuming <b>SiSU</b> is in use and they exist). +<p> 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). <p> 26.4 SUMMARY OF MAN PAGE -<p> 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] -<p> where no port is given and settings are +<p> 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] +<p> where no port is given and -<p>unchanged the default port is 8081 -<p> 26.5 DOCUMENT PROCESSING COMMAND FLAGS +<p>settings are unchanged the default port is 8081 +<p> 26.5 DOCUMENT PROCESSING -<p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories, -on the port provided, or if no port is provided and the defaults have not +<p>COMMAND FLAGS +<p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> +output directories, on the port provided, or if no port is provided and -<p>been changed in ~/.sisu/sisurc.yaml then on port 8081 -<p> 26.6 FURTHER INFORMATION +<p>the defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081 -<p> For more information on <b>SiSU</b> see: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<p> 26.6 FURTHER INFORMATION +<p> For more information on <b>SiSU</b> see: <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +or <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > <p> or man sisu - <p> 26.7 AUTHOR -<p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com -<p> +<p> Ralph Amissah ralph@amissah.com -<p>26.8 SEE ALSO +<p>or ralph.amissah@gmail.com +<p> 26.8 SEE ALSO <p> <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a> <br> @@ -2669,19 +2749,19 @@ parts (such as images) will be downloaded and generated locally. <p> Any of the source documents in the sisu examples page can be used in this way, see <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > and use the url -for the desired document. -<p> NOTE: to set up a remote machine to serve <b>SiSU</b> -documents in this way, images should be in the directory relative to the +to the .sst for the desired document.<br> + +<p> NOTE: to set up a remote machine to serve <b>SiSU</b> documents in this way, + +<p>images should be in the directory relative to the document source ../_sisu/image -<p>document source ../_sisu/image <p> <b>sisupod - zipped sisu files</b> -<p> 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. -<p> <b>SiSU</b> 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. +<p> 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. +<p> <b>SiSU</b> 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. <p> <p> <br> <pre> sisu -3 http://[provide url to valid sisupod.zip or .ssp file] @@ -2711,40 +2791,40 @@ may be used in conjunction with other processing flags, e.g. <dt><b>-R [filename/wildcard]</b> </dt> <dd>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 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 +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 <p> </dd> <dt><b>-r [filename/wildcard]</b> </dt> -<dd>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 - -<p>your +<dd>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 <p> </dd> </dl> 28.2 CONFIGURATION -<p> [expand on the setting up of an ssh-agent / keychain] - +<p> [expand on the setting + up of an ssh-agent / keychain] <p> 29. REMOTE SERVERS -<p> As <b>SiSU</b> is generally operated using the command line, -and works within a Unix type environment, <b>SiSU</b> 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. -<p> 30. QUICKSTART - GETTING STARTED HOWTO - +<p> As <b>SiSU</b> is generally +operated using the command line, and works within a Unix type environment, +<b>SiSU</b> 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. +<p> 30. +QUICKSTART - GETTING STARTED HOWTO <p> 30.1 INSTALLATION -<p> Installation is currently most straightforward and -tested on the <b>Debian</b> platform, as there are packages for the installation -of sisu and all requirements for what it does. +<p> Installation is +currently most straightforward and tested on the <b>Debian</b> platform, as there +are packages for the installation of sisu and all requirements for what +it does. <p> 30.1.1 DEBIAN INSTALLATION - -<p> <b>SiSU</b> is available directly from the <b>Debian</b> Sid and testing archives (and -possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: - +<p> <b>SiSU</b> is available directly from the +<b>Debian</b> Sid and testing archives (and possibly Ubuntu), assuming your /etc/apt/sources.list +is set accordingly: <p> <p> <br> <pre> aptitude update @@ -2757,7 +2837,6 @@ markup samples: <pre> #/etc/apt/sources.list deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib - d </pre> <p> The aptitude commands become: <p> @@ -2832,10 +2911,11 @@ the root directory of the unpacked <b>SiSU</b> as root type: <p> <<a href='http://i.loveruby.net/en/projects/setup/doc/usage.html'>http://i.loveruby.net/en/projects/setup/doc/usage.html</a> ><br> -<p> <b></b> -<p> The root directory of the unpacked <b>SiSU</b> as root type: -<p> ruby install -base<br> +<p> <b>install</b> +<p> The "install" file provided is an installer prepared using +"rant". In the root directory of the unpacked <b>SiSU</b> as root type: +<p> ruby +install base<br> <p> or for a more complete installation: <p> ruby install<br> @@ -2848,8 +2928,7 @@ 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. <p> Further - -<p>information on +information on "rant" is available from: <p> <<a href='http://make.rubyforge.org/'>http://make.rubyforge.org/</a> ><br> @@ -2921,10 +3000,10 @@ create the database and write to it when you run sisu. <p> The man pages are also available online, though not always kept as up to date as within the package itself: -<p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a> +<p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> > [^25] -<p> * sisu.8 <<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a> +<p> * sisu.8 <<a href='http://www.jus.uio.no/sisu/man/sisu.8.html'>http://www.jus.uio.no/sisu/man/sisu.8.html</a> > [^26] <p> * man directory <<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> @@ -2940,29 +3019,35 @@ to date as within the package itself: <p> sisu --help --markup <p> 30.3.3 THE HOME PAGE <p> -<<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > <p> <<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a> > -<p> 30.4 MARKUP SAMPLES -<p> A number of markup samples (along with output) are available off: +<p> 30.4 MARKUP SAMPLES +<p> A number of markup samples (along with output) are +available off: <p> <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> > - -<p> Additional markup samples are packaged separately in the file: +<p> Additional +markup samples are packaged separately in the file: <p> <b>*</b> -<p> -On <b>Debian</b> 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. +<p> On <b>Debian</b> 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. + <p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING <p> The directory: - <p> ./data/sisu/v2/conf/editor-syntax-etc/<br> +<p> ./data/sisu/v3/conf/editor-syntax-etc/<br> + <p> /usr/share/sisu/v2/conf/editor-syntax-etc<br> +<p> /usr/share/sisu/v3/conf/editor-syntax-etc<br> + <p> contains rudimentary sisu syntax highlighting files for: <p> * (g)vim <<a href='http://www.vim.org'>http://www.vim.org</a> @@ -3047,6 +3132,7 @@ breaks<br> <p> to file ~/.emacs add the following 2 lines:<br> <p> (add-to-list ’load-path<br> + "/usr/share/sisu/v2/conf/editor-syntax-etc/emacs")<br> <p> (require ’sisu-mode.el)<br> @@ -3092,29 +3178,29 @@ create new ones). <p> 33. SUMMARY OF FEATURES <p> * 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 headers -are optional. -<p> * 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]. - -<p> * 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</b> 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 paper publication, sql search etc.] (html, -epub, xml, odf, latex, pdf, sql) -<p> * 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: -<p> * html - both as a single scrollable text and a segmented -document<br> +minimalistic mnemonic syntax. Typical literature, documents like "War and +Peace" require almost no markup, and most of the headers are optional. +<p> + * 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]. +<p> * 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</b> 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 paper publication, sql search etc.] (html, epub, xml, odf, latex, +pdf, sql) +<p> * 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: +<p> * html +- both as a single scrollable text and a segmented document<br> <p> * xhtml<br> @@ -3131,8 +3217,8 @@ as<br> <p> * pdf (via LaTeX)<br> <p> * sql - population of an sql database, (at the same object level that -is<br> - used to cite text within a document)<br> +is used<br> + to cite text within a document)<br> <p> Also produces: concordance files; document content certificates (md5 or sha256 digests of headings, paragraphs, images etc.) and html manifests @@ -3158,62 +3244,66 @@ 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]. -<p> <b>*</b>long<b>term</b>maintainability<b>of</b>document<b>collections</b>in<b>a</b>world<b>of</b>changing -formats, having a very sparsely marked-up source document base. there is -a considerable degree of future-proofing, output representations are upgradeable -(open document text) module in 2006, epub in 2009 and in future html5 output -sometime in future, without modification of existing prepared texts -<p> * -SQL search aside, documents are generated as required and static once generated. - -<p> * 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) -<p> * document source (plaintext utf-8) if - -<p>shared on the net may be used as input and processed locally to produce - -<p>the different document outputs -<p> * 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 - -<p>the desired document outputs -<p> * generated document outputs may automatically -be posted to remote sites. -<p> * for basic document generation, the only software -dependency is <b>Ruby</b> , 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. -<p> * as a developers tool it is flexible and extensible -<p> Syntax -highlighting for <b>SiSU</b> markup is available for a number of text editors. - -<p> <b>SiSU</b> 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 -<p> 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)... -<p> 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. +<p> * 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, + +<p>without modification of existing prepared texts +<p> * SQL search aside, documents +are generated as required and static once generated. +<p> * 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) + +<p> * document source (plaintext utf-8) if shared on the net may be used as + +<p>input and processed locally to produce the different document outputs +<p> + * 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 + +<p>these too may be processed locally to produce the desired document outputs + +<p> * generated document outputs may automatically be posted to remote sites. + +<p> * for basic document generation, the only software dependency is <b>Ruby</b> +, 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. +<p> * as + +<p>a developers tool it is flexible and extensible +<p> Syntax highlighting for +<b>SiSU</b> markup is available for a number of text editors. +<p> <b>SiSU</b> 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, + +<p>or search of content +<p> 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)... +<p> 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. <p> 34. HELP SOURCES -<p> For a summary of alternative -ways to get help on <b>SiSU</b> try one of the following: +<p> For a summary of alternative ways +to get help on <b>SiSU</b> try one of the following: <p> <b>man page</b> <p> man sisu_help<br> @@ -3237,6 +3327,28 @@ listed here: <p> 34.1.1 MAN <p> man sisu<br> +<p> man sisu-concordance<br> + +<p> man sisu-epub<br> + +<p> man sisu-git<br> + +<p> man sisu-harvest<br> + +<p> man sisu-html<br> + +<p> man sisu-odf<br> + +<p> man sisu-pdf<br> + +<p> man sisu-pg<br> + +<p> man sisu-po<br> + +<p> man sisu-sqlite<br> + +<p> man sisu-txt<br> + <p> man 7 sisu_complete<br> <p> man 7 sisu_pdf<br> @@ -3252,8 +3364,8 @@ listed here: <p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML <p> Note <b>SiSU</b> documentation is prepared in <b>SiSU</b> 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] +amongst others html, pdf, odf and epub, which may be also be accessed via +the html pages[^29] <p> 34.2.1 WWW.SISUDOC.ORG <p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> > @@ -3261,94 +3373,19 @@ the html pages[^28] <p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> ><br> -<p> <<a href='http://sisudoc.org/sisu/sisu_commands/index.html'>http://sisudoc.org/sisu/sisu_commands/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_complete/index.html'>http://sisudoc.org/sisu/sisu_complete/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_configuration/index.html'>http://sisudoc.org/sisu/sisu_configuration/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_description/index.html'>http://sisudoc.org/sisu/sisu_description/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_examples/index.html'>http://sisudoc.org/sisu/sisu_examples/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_faq/index.html'>http://sisudoc.org/sisu/sisu_faq/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_filetypes/index.html'>http://sisudoc.org/sisu/sisu_filetypes/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_howto/index.html'>http://sisudoc.org/sisu/sisu_howto/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_introduction/index.html'>http://sisudoc.org/sisu/sisu_introduction/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_markup/index.html'>http://sisudoc.org/sisu/sisu_markup/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_output_overview/index.html'>http://sisudoc.org/sisu/sisu_output_overview/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_pdf/index.html'>http://sisudoc.org/sisu/sisu_pdf/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_postgresql/index.html'>http://sisudoc.org/sisu/sisu_postgresql/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_quickstart/index.html'>http://sisudoc.org/sisu/sisu_quickstart/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_remote/index.html'>http://sisudoc.org/sisu/sisu_remote/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_search/index.html'>http://sisudoc.org/sisu/sisu_search/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_skin/index.html'>http://sisudoc.org/sisu/sisu_skin/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_sqlite/index.html'>http://sisudoc.org/sisu/sisu_sqlite/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_vim/index.html'>http://sisudoc.org/sisu/sisu_vim/index.html</a> -><br> - -<p> <<a href='http://sisudoc.org/sisu/sisu_webrick/index.html'>http://sisudoc.org/sisu/sisu_webrick/index.html</a> -><br> - <p> 34.3 MAN2HTML <p> 34.3.1 LOCALLY INSTALLED -<p> <file:///usr/share/doc/sisu/v2/html/sisu.1.html> - -<p> <file:///usr/share/doc/sisu/v2/html/sisu_help.1.html> -<p> <file:///usr/share/doc/sisu/v2/html/sisu_help_sources.1.html> +<p> file:///usr/share/doc/sisu/html/sisu.1.html -<p> /usr/share/doc/sisu/v2/html/sisu.1.html<br> +<p> file:///usr/share/doc/sisu/html/sisu.1.html<br> -<p> /usr/share/doc/sisu/v2/html/sisu_pdf.7.html<br> +<p> file:///usr/share/doc/sisu/html/sisu_pdf.7.html<br> -<p> /usr/share/doc/sisu/v2/html/sisu_postgresql.7.html<br> +<p> file:///usr/share/doc/sisu/html/sisu_postgresql.7.html<br> -<p> /usr/share/doc/sisu/v2/html/sisu_sqlite.7.html<br> +<p> file:///usr/share/doc/sisu/html/sisu_sqlite.7.html<br> -<p> /usr/share/doc/sisu/v2/html/sisu_webrick.1.html<br> +<p> file:///usr/share/doc/sisu/html/sisu_webrick.1.html<br> <p> 34.3.2 WWW.JUS.UIO.NO/SISU <p> <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> @@ -3417,47 +3454,51 @@ insert multiple asterisks if required </dd> <dt><b>+2.</b> </dt> <dd>editors -notes, numbered asterisk footnote/endnote series </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +notes, numbered asterisk footnote/endnote series </li><b>.</b><li><<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> > -</li><b>.</b><li><<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> -> </li><b>.</b><li>Table from the Wealth of Networks by Yochai Benkler -<<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a> -> </li><b>.</b><li>.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 processing. -It may be however that when the resulting file is shared .ssc is an appropriate -suffix to use. </li><b>.</b><li><<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a> + +<p> </li><b>.</b><li><<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> +> </li><b>.</b><li>Table from the Wealth of Networks by Yochai +Benkler <<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a> +> </li><b>.</b><li>.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. </li><b>.</b><li><<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a> > <<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a> -> <<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a> > -</li><b>.</b><li><<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a> +<<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a> +> </li><b>.</b><li><<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a> > <<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a> -> </li><b>.</b><li><<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> > -</li><b>.</b><li>(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. </li><b>.</b><li>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. </li><b>.</b><li>There is nothing to stop MySQL support -being added in future. </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a> -> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a> +</li><b>.</b><li><<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> +> </li><b>.</b><li>(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. </li><b>.</b><li>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. +</li><b>.</b><li>There is nothing to stop MySQL support being added in future. </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> + +<p> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.8.html'>http://www.jus.uio.no/sisu/man/sisu.8.html</a> > -</li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> -> </li><b>.</b><li>the <b>Debian</b> Free Software guidelines require -that everything distributed within <b>Debian</b> can be changed - and the documents -are authors’ works that while freely distributable are not freely changeable. -</li><b>.</b><li> -<p>named index.html or more extensively through sisu_manifest.html +<p> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> +> </li><b>.</b> +<li>the <b>Debian</b> Free Software guidelines require that everything distributed +within <b>Debian</b> can be changed - and the documents are authors’ works that +while freely distributable are not freely changeable. </li><b>.</b><li>named index.html or + +<p>more extensively through sisu_manifest.html <p> </li> </ol> <h2><a name='sect2' href='#toc2'>See Also</a></h2> <a href='http:~/bin/man2html?sisu:1'><i>sisu</i>(1)</a> -, -<br> +, <br> <a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> , <br> <a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> @@ -3475,12 +3516,10 @@ are authors’ works that while freely distributable are not freely changeab <a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> . <br> <a href='http:~/bin/man2html?sisu_vim:7'><i>sisu_vim</i>(7)</a> - <br> -<a href='http:~/bin/man2html?sisu:8'><i>sisu</i>(8)</a> <p> <h2><a name='sect3' href='#toc3'>Homepage</a></h2> -More information about <b>SiSU</b> can be found at <<a href='http://www.jus.uio.no/sisu/'><i>http://www.jus.uio.no/sisu/</i></a> +More information about <b>SiSU</b> can be found at <<a href='http://www.sisudoc.org/'><i>http://www.sisudoc.org/</i></a> >. <p> diff --git a/data/doc/sisu/html/sisu3.1.html b/data/doc/sisu/html/sisu3.1.html new file mode 100644 index 00000000..905b05ec --- /dev/null +++ b/data/doc/sisu/html/sisu3.1.html @@ -0,0 +1,3520 @@ +<!-- manual page source format generated by PolyglotMan v3.2, --> +<!-- available at http://polyglotman.sourceforge.net/ --> + +<html> +<head> +<title>"sisu"("1") manual page</title> +</head> +<body bgcolor='white'> +<a href='#toc'>Table of Contents</a><p> + +<h2><a name='sect0' href='#toc0'>Name</a></h2> +sisu - documents: markup, structuring, publishing in multiple standard +formats, and search +<h2><a name='sect1' href='#toc1'>Synopsis</a></h2> +sisu [-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0-9] +[filename/wildcard] +<p> sisu [-P] [language_directory/filename language_directory] + +<p> sisu [-Ddcv] [instruction] [filename/wildcard] +<p> sisu [-CcFLSVvW] +<p> sisu +--v2 [operations] +<p> sisu --v1 [operations] SISU - MANUAL, RALPH AMISSAH +<p> WHAT +IS SISU? +<p> 1. INTRODUCTION - WHAT IS SISU? +<p> <b>SiSU</b> 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. +<p> <b>SiSU</b> 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. +<p> <b>SiSU</b> both defines a markup syntax and provides +an engine that produces open standards format outputs from documents prepared +with <b>SiSU</b> 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</b> 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</b> is also able to populate SQL type databases at an object level, which +means that searches can be made with that degree of granularity. +<p> 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</b> markup applied to a document, <b>SiSU</b> 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. +<p> In preparing a <b>SiSU</b> 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. +<p> <b>SiSU</b> 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</b> 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</b> is able to take advantage of. +<p> 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</b> provides the +flexibility of producing documents in multiple non-proprietary open formats +including html, pdf[^5] ODF,[^6] and EPUB.[^7] Whilst <b>SiSU</b> 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</b> can be migrated to +other document formats. Further security is provided by the fact that the +software itself, <b>SiSU</b> 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</b> 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). + +<p> 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. +<p> <b>SiSU</b> 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</b> offers great possibilities. +<p> <b>SiSU</b> +is primarily for published works, which can take advantage of the citation +system to reliably reference its documents. <b>SiSU</b> 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</b> +<p> +<<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> +<p> 2. COMMANDS SUMMARY +<p> 2.1 DESCRIPTION +<p> <b>SiSU</b> <b>SiSU</b> +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: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> + +<p> 2.2 DOCUMENT PROCESSING COMMAND FLAGS +<p> +<dl> + +<dt><b>-a [filename/wildcard]</b> </dt> +<dd>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 (Options include: --endnotes for endnotes +--footnotes for footnotes at the end of each paragraph --unix for unix linefeed +(default) --msdos for msdos linefeed) +<p> </dd> + +<dt><b>-b [filename/wildcard]</b> </dt> +<dd>see --xhtml +<p> </dd> + +<dt><b>--color-toggle +[filename/wildcard]</b> </dt> +<dd>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 + +<p>- +<p>c +<p> </dd> + +<dt><b>--concordance [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-C [--init-site]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-CC</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-c [filename/wildcard]</b> +</dt> +<dd> +<p>see --color-toggle +<p> </dd> + +<dt><b>--dal [filename/wildcard/url]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--delete [filename/wildcard]</b> +</dt> +<dd> +<p>see --zap +<p> </dd> + +<dt><b>-D [instruction] [filename]</b> </dt> +<dd>see --pg +<p> </dd> + +<dt><b>-d [--db-[database type (sqlite|pg)]] +--[instruction] [filename]</b> </dt> +<dd>see --sqlite +<p> </dd> + +<dt><b>--epub [filename/wildcard]</b> </dt> +<dd>produces +an epub document, [sisu version 2 only] (filename.epub). Alias -e +<p> </dd> + +<dt><b>-e [filename/wildcard]</b> +</dt> +<dd> +<p>see --epub +<p> </dd> + +<dt><b>-F [--webserv=webrick]</b> </dt> +<dd>see --sample-search-form +<p> </dd> + +<dt><b>--git [filename/wildcard]</b> +</dt> +<dd>produces or updates markup source file structure in a git repo (experimental +and subject to change). Alias -g +<p> </dd> + +<dt><b>-g [filename/wildcard]</b> </dt> +<dd>see --git +<p> </dd> + +<dt><b>--harvest +*.ss[tm]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--help [topic]</b> </dt> +<dd>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, + +<p>license +<p> </dd> + +<dt><b>--html [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-h [filename/wildcard]</b> </dt> +<dd>see --html +<p> </dd> + +<dt><b>-I [filename/wildcard]</b> +</dt> +<dd> +<p>see --texinfo +<p> </dd> + +<dt><b>-i [filename/wildcard]</b> </dt> +<dd>see --manpage +<p> </dd> + +<dt><b>-L</b> </dt> +<dd>prints license information. + +<p> </dd> + +<dt><b>--machine [filename/wildcard/url]</b> </dt> +<dd>see --dal (document abstraction level/layer) + +<p> </dd> + +<dt><b>--maintenance [filename/wildcard/url]</b> </dt> +<dd>maintenance mode files created for +processing preserved and their locations indicated. (also see -V). Alias -M + +<p> </dd> + +<dt><b>--manpage [filename/wildcard]</b> </dt> +<dd>produces man page of file, not suitable for +all outputs. Alias -i +<p> </dd> + +<dt><b>-M [filename/wildcard/url]</b> </dt> +<dd>see --maintenance +<p> </dd> + +<dt><b>-m [filename/wildcard/url]</b> +</dt> +<dd>see --dal (document abstraction level/layer) +<p> </dd> + +<dt><b>--no-ocn</b> </dt> +<dd>[with --html --pdf or --epub] +switches off object citation numbering. Produce output without identifying +numbers in margins of html or LaTeX/pdf output. +<p> </dd> + +<dt><b>-N [filename/wildcard/url]</b> +</dt> +<dd>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. +<p> </dd> + +<dt><b>-n +[filename/wildcard/url]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--odf [filename/wildcard/url]</b> +</dt> +<dd> +<p>see --odt +<p> </dd> + +<dt><b>--odt [filename/wildcard/url]</b> </dt> +<dd>output basic document in opendocument +file format (opendocument.odt). Alias -o +<p> </dd> + +<dt><b>-o [filename/wildcard/url]</b> </dt> +<dd>see --odt + +<p> </dd> + +<dt><b>--pdf [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--pg [instruction] [filename]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--po [language_directory/filename language_directory]</b> +</dt> +<dd> +<p>see --po4a +<p> </dd> + +<dt><b>--po4a [language_directory/filename language_directory]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-P [language_directory/filename +language_directory]</b> </dt> +<dd>see --po4a +<p> </dd> + +<dt><b>-p [filename/wildcard]</b> </dt> +<dd>see --pdf +<p> </dd> + +<dt><b>--quiet [filename/wildcard]</b> +</dt> +<dd>quiet less output to screen. +<p> </dd> + +<dt><b>-q [filename/wildcard]</b> </dt> +<dd>see --quiet +<p> </dd> + +<dt><b>--rsync [filename/wildcard]</b> +</dt> +<dd>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 + +<p>- +<p>R +<p> </dd> + +<dt><b>-R [filename/wildcard]</b> </dt> +<dd>see --rsync +<p> </dd> + +<dt><b>-r [filename/wildcard]</b> </dt> +<dd>see --scp +<p> </dd> + +<dt><b>--sample-search-form +[--webserv=webrick]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--scp [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--sqlite +--[instruction] [filename]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>--sisupod</b> </dt> +<dd>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<br> + option is tested only with zsh). Alias -S +<p> </dd> + +<dt><b>--sisupod [filename/wildcard]</b> </dt> +<dd>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</b> 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 +<p> </dd> + +<dt><b>--source [filename/wildcard]</b> </dt> +<dd>copies sisu markup +file to output directory. Alias -s +<p> </dd> + +<dt><b>-S</b> </dt> +<dd>see --sisupod +<p> </dd> + +<dt><b>-S [filename/wildcard]</b> +</dt> +<dd> +<p>see --sisupod +<p> </dd> + +<dt><b>-s [filename/wildcard]</b> </dt> +<dd>see --source +<p> </dd> + +<dt><b>--texinfo [filename/wildcard]</b> +</dt> +<dd>produces texinfo and info file, (view with pinfo). Alias -I +<p> </dd> + +<dt><b>--txt [filename/wildcard]</b> +</dt> +<dd>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 (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 +<p> </dd> + +<dt><b>-T [filename/wildcard + (*.termsheet.rb)]</b> </dt> +<dd>standard form document builder, preprocessing feature +<p> +</dd> + +<dt><b>-t [filename/wildcard]</b> </dt> +<dd>see --txt +<p> </dd> + +<dt><b>--urls [filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-U [filename/wildcard]</b> </dt> +<dd>see --urls +<p> </dd> + +<dt><b>-u [filename/wildcard]</b> +</dt> +<dd>provides url mapping of output files for the flags requested for processing, + +<p>also see -U +<p> </dd> + +<dt><b>--v1 [filename/wildcard]</b> </dt> +<dd>invokes the sisu v1 document parser/generator. +For use with sisu v1 markup documents. (Markup conversion to v2 involves +the modification of document headers) +<p> </dd> + +<dt><b>--v2 [filename/wildcard]</b> </dt> +<dd>invokes the +sisu v2 document parser/generator. This is the default and is normally omitted. + +<p> </dd> + +<dt><b>--verbose [filename/wildcard]</b> </dt> +<dd>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. + +<p>Alias -v +<p> </dd> + +<dt><b>-V</b> </dt> +<dd>on its own, provides <b>SiSU</b> version and environment information +(sisu --help env) +<p> </dd> + +<dt><b>-V [filename/wildcard]</b> </dt> +<dd>even more verbose than the -v flag. + +<p> </dd> + +<dt><b>-v</b> </dt> +<dd>on its own, provides <b>SiSU</b> version information +<p> </dd> + +<dt><b>-v [filename/wildcard]</b> +</dt> +<dd> +<p>see --verbose +<p> </dd> + +<dt><b>--webrick</b> </dt> +<dd>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 and search +-H ; also, note -F webrick ]. Alias -W +<p> </dd> + +<dt><b>-W</b> </dt> +<dd>see --webrick +<p> </dd> + +<dt><b>--wordmap [filename/wildcard]</b> +</dt> +<dd> +<p>see --concordance +<p> </dd> + +<dt><b>-w [filename/wildcard]</b> </dt> +<dd>see --concordance +<p> </dd> + +<dt><b>--xhtml [filename/wildcard]</b> +</dt> +<dd>produces xhtml/XML output for browser viewing (sax parsing). Alias -b +<p> </dd> + +<dt><b>--xml-dom +[filename/wildcard]</b> </dt> +<dd>produces XML output with deep document structure, in +the nature of dom. Alias -X +<p> </dd> + +<dt><b>--xml-sax [filename/wildcard]</b> </dt> +<dd>produces XML output +shallow structure (sax parsing). Alias -x +<p> </dd> + +<dt><b>-X [filename/wildcard]</b> </dt> +<dd>see --xml-dom + +<p> </dd> + +<dt><b>-x [filename/wildcard]</b> </dt> +<dd>see --xml-sax +<p> </dd> + +<dt><b>-Y [filename/wildcard]</b> </dt> +<dd>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]) +<p> </dd> + +<dt><b>-y [filename/wildcard]</b> </dt> +<dd>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. + +<p> </dd> + +<dt><b>--zap [filename/wildcard]</b> </dt> +<dd>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. + +<p>Alias -Z +<p> </dd> + +<dt><b>-Z [filename/wildcard]</b> </dt> +<dd>see --zap +<p> </dd> +</dl> +3. COMMAND LINE MODIFIERS +<p> +<dl> + +<dt><b>--no-ocn</b> +</dt> +<dd>[with --html --pdf or --epub] switches off object citation numbering. Produce +output without identifying numbers in margins of html or LaTeX/pdf output. + +<p> </dd> + +<dt><b>--no-annotate</b> </dt> +<dd>strips output text of editor endnotes[^*1] denoted by asterisk + +<p>or dagger/plus sign +<p> </dd> + +<dt><b>--no-asterisk</b> </dt> +<dd>strips output text of editor endnotes[^*2] + +<p>denoted by asterisk sign +<p> </dd> + +<dt><b>--no-dagger</b> </dt> +<dd>strips output text of editor endnotes[^+1] + +<p>denoted by dagger/plus sign +<p> </dd> +</dl> +4. DATABASE COMMANDS +<p> dbi - database interface + +<p> -D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is +modifiable with --db=[database type (pgsql or sqlite)] +<p> +<dl> + +<dt><b>--pg -v --createall</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--pg -v --import</b> </dt> +<dd>[filename/wildcard] imports +data specified to postgresql db (rb.dbi) [ -dv --import sqlite equivalent] + +<p> </dd> + +<dt><b>--pg -v --update</b> </dt> +<dd>[filename/wildcard] updates/imports specified data to postgresql +db (rb.dbi) [ -dv --update sqlite equivalent] +<p> </dd> + +<dt><b>--pg --remove</b> </dt> +<dd>[filename/wildcard] +removes specified data to postgresql db (rb.dbi) [ -d --remove sqlite equivalent] + +<p> </dd> + +<dt><b>--pg --dropall</b> </dt> +<dd>kills data" and drops (postgresql or sqlite) db, tables & indexes +[ -d --dropall sqlite equivalent] +<p> The -v is for verbose output. +<p> </dd> +</dl> +5. SHORTCUTS, +SHORTHAND FOR MULTIPLE FLAGS +<p> +<dl> + +<dt><b>--update [filename/wildcard]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-0 to -5 [filename + or wildcard]</b> </dt> +<dd>Default shorthand mappings (note that the defaults can be +changed/configured in the sisurc.yml file): +<p> </dd> + +<dt><b>-0</b> </dt> +<dd>-mNhwpAobxXyYv [this is the + default action run when no i.e. on ’sisu [filename]’] +<p> </dd> + +<dt><b>-1</b> </dt> +<dd>-mhewpy +<p> </dd> + +<dt><b>-2</b> </dt> +<dd>-mhewpaoy + +<p> </dd> + +<dt><b>-3</b> </dt> +<dd>-mhewpAobxXyY +<p> </dd> + +<dt><b>-4</b> </dt> +<dd>-mhewpAobxXDyY --import +<p> </dd> + +<dt><b>-5</b> </dt> +<dd>-mhewpAobxXDyY --update +<p> add -v +for verbose mode and -c for color, e.g. sisu -2vc [filename or +<p> consider -u + +<p>for appended url info or -v for verbose output +<p> </dd> +</dl> +5.1 COMMAND LINE WITH FLAGS +- BATCH PROCESSING +<p> 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. +<p> 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. +<p> 6. HELP +<p> 6.1 SISU MANUAL +<p> The most up to date information +on sisu should be contained in the sisu_manual, available at: +<p> <<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a> +><br> + +<p> The manual can be generated from source, found respectively, either +within the <b>SiSU</b> tarball or installed locally at: +<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> + +<p> /usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> + +<p> move to the respective directory and type e.g.: +<p> sisu sisu_manual.ssm<br> + +<p> 6.2 SISU MAN PAGES +<p> If <b>SiSU</b> is installed on your system usual man commands +should be available, try: +<p> man sisu<br> + +<p> man sisu_markup<br> + +<p> man sisu_commands<br> + +<p> Most <b>SiSU</b> 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</b> tarball at: +<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br> + +<p> Once installed, directory equivalent to: +<p> /usr/share/doc/sisu/sisu_manual/<br> + +<p> Available man pages are converted back to html using man2html: +<p> /usr/share/doc/sisu/v2/html/<br> + +<p> ./data/doc/sisu/v2/html/<br> + +<p> An online version of the sisu man page is available here: +<p> * various +sisu man pages <<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> +> [^8] +<p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> +[^9] +<p> 6.3 SISU BUILT-IN INTERACTIVE HELP +<p> This is particularly useful for +getting the current sisu setup/environment information: +<p> sisu --help<br> + +<p> sisu --help [subject]<br> + +<p> sisu --help commands<br> + +<p> sisu --help markup<br> + +<p> sisu --help env [for feedback on the way your system is <br> + setup with regard to sisu]<br> + +<p> sisu -V [environment information, same as above command]<br> + +<p> sisu (on its own provides version and some help information)<br> + +<p> Apart from real-time information on your current configuration the <b>SiSU</b> +manual and man pages are likely to contain more up-to-date information than +the sisu interactive help (for example on commands and markup). +<p> 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. +<p> 6.4 HELP SOURCES +<p> For lists of alternative help sources, +see: +<p> <b>man page</b> +<p> man sisu_help_sources<br> + +<p> <b>man2html</b> +<p> /usr/share/doc/sisu/v2/html/sisu.1.html<br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> +><br> + +<p> 7. INTRODUCTION TO SISU MARKUP[^10] +<p> 7.1 SUMMARY +<p> <b>SiSU</b> source documents +are plaintext (UTF-8)[^11] files +<p> All paragraphs are separated by an empty +line. +<p> Markup is comprised of: +<p> * 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) +<p> * 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: +<p> * heading levels defines +document structure<br> + +<p> * text basic attributes, italics, bold etc.<br> + +<p> * grouped text (objects), which are to be treated differently, such +as code<br> + blocks or poems.<br> + +<p> * footnotes/endnotes<br> + +<p> * linked text and images<br> + +<p> * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br> + +<p> Some interactive help on markup is available, by typing sisu and selecting + +<p>markup or sisu --help markup +<p> To check the markup in a file: +<p> sisu --identify +[filename].sst<br> + +<p> For brief descriptive summary of markup history +<p> sisu --query-history<br> + +<p> or if for a particular version: +<p> sisu --query-0.38<br> + +<p> 7.2 MARKUP EXAMPLES +<p> 7.2.1 ONLINE +<p> Online markup examples are available +together with the respective outputs produced from <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> +or from <<a href='http://www.jus.uio.no/sisu/sisu_examples/'>http://www.jus.uio.no/sisu/sisu_examples/</a> +> +<p> There is of course this +document, which provides a cursory overview of sisu markup and the respective +output produced: <<a href='http://www.jus.uio.no/sisu/sisu_markup/'>http://www.jus.uio.no/sisu/sisu_markup/</a> +> +<p> Some example marked +up files are available as html with syntax highlighting for viewing: <<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> +> + +<p> an alternative presentation of markup syntax: <<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a> +> + +<p> 7.2.2 INSTALLED +<p> With <b>SiSU</b> 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: + +<p>/usr/share/doc/sisu/sisu_markup_samples/non-free +<p> 8. MARKUP OF HEADERS +<p> + Headers contain either: semantic meta-data about a document, which can +be used by any output module of the program, or; processing instructions. + +<p> 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: +<p> +<p> <br> +<pre> % this would be a comment +</pre> +<p> 8.1 SAMPLE HEADER +<p> This current document is loaded by a master document +that has a header similar to this one: +<p> +<p> <br> +<pre> % 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/ +</pre> +<p> 8.2 AVAILABLE HEADERS +<p> 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 + +<p>Dublin Core meta tags are available +<p> <b>@indentifier:</b> information or instructions + +<p> where the "identifier" is a tag recognised by the program, and the "information" +or "instructions" belong to the tag/indentifier specified +<p> 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. +<p> This is a sample header +<p> +<p> <br> +<pre> % SiSU 2.0 [declared file-type identifier with markup version] +</pre> +<p> <br> +<pre> @title: [title text] [this header is the only one that is mandatory] + :subtitle: [subtitle if any] + :language: English +</pre> +<p> <br> +<pre> @creator: :author: [Lastname, First names] + :illustrator: [Lastname, First names] + :translator: [Lastname, First names] + :prepared_by: [Lastname, First names] +</pre> +<p> <br> +<pre> @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] +</pre> +<p> <br> +<pre> @rights: :copyright: Copyright (C) [Year and Holder] + :license: [Use License granted] + :text: [Year and Holder] + :translation: [Name, Year] + :illustrations: [Name, Year] +</pre> +<p> <br> +<pre> @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] +</pre> +<p> <br> +<pre> @links: { SiSU }http://www.jus.uio.no/sisu/ + { FSF }http://www.fsf.org +</pre> +<p> <br> +<pre> @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] +</pre> +<p> <br> +<pre> @original: :language: [language] +</pre> +<p> <br> +<pre> @notes: :comment: + :prefix: [prefix is placed just after table of contents] +</pre> +<p> 9. MARKUP OF SUBSTANTIVE TEXT +<p> 9.1 HEADING LEVELS +<p> 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) +<p> <b>:A~ [heading + text]</b> Top level heading [this usually has similar content to the ] NOTE: +the heading levels described here are in 0.38 notation, see heading +<p> <b>:B~ +[heading text]</b> Second level heading [this is a heading level divider] +<p> + <b>:C~ [heading text]</b> Third level heading [this is a heading level divider] + +<p> <b>1~ [heading text]</b> 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 + +<p> <b>2~ [heading text]</b> 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. +<p> <b>3~ [heading text]</b> 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 +<p> +<p> <br> +<pre> 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) +</pre> +<p> 9.2 FONT ATTRIBUTES +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, +"{citation}", + ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}- #{monospace}# + normal text + !{emphasis}! + *{bold text}* + _{underscore}_ + /{italics}/ + "{citation}" + ^{superscript}^ + ,{subscript}, + +{inserted text}+ + -{strikethrough}- + #{monospace}# +</pre> +<p> <b>resulting output:</b> +<p> normal text <b>emphasis</b> <b>bold text</b> <i>underscore</i> <i>italics</i> +"citation" ^superscript^ [subscript] ++inserted text++ --strikethrough-- monospace + +<p> normal text +<p> <b>emphasis</b> [note: can be configured to be represented by + bold, italics or underscore] +<p> <b>bold text</b> +<p> <i>italics</i> +<p> <i>underscore</i> +<p> "citation" + +<p> ^superscript^ +<p> [subscript] +<p> ++inserted text++ +<p> --strikethrough-- +<p> monospace + +<p> 9.3 INDENTATION AND BULLETS +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> ordinary paragraph + _1 indent paragraph one step + _2 indent paragraph two steps + _9 indent paragraph nine steps +</pre> +<p> +<p> <b>resulting output:</b> +<p> ordinary paragraph +<p> indent paragraph one step<br> + +<p> indent paragraph two steps<br> + +<p> indent paragraph nine steps<br> + +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> _* bullet text + _1* bullet text, first indent + _2* bullet text, two step indent +</pre> +<p> <b>resulting output:</b> +<p> * bullet text +<p> * bullet text, first indent<br> + +<p> * bullet text, two step indent<br> + +<p> Numbered List (not to be confused with headings/titles, (document structure)) + +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> # numbered list numbered list 1., 2., 3, etc. + _# numbered list numbered list indented a., b., c., d., etc. +</pre> +<p> 9.4 FOOTNOTES / ENDNOTES +<p> 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. +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> ~{ a footnote or endnote }~ +</pre> +<p> <b>resulting output:</b> +<p> [^12] +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text~{ self contained endnote marker & endnote in one }~ continues +</pre> +<p> <b>resulting output:</b> +<p> normal text[^13] continues +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text ~{* unnumbered asterisk footnote/endnote, insert multiple +asterisks if required }~ continues + normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +</pre> +<p> <b>resulting output:</b> +<p> normal text [^*] continues +<p> normal text [^**] continues + +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text ~[* editors notes, numbered asterisk footnote/endnote series + ]~ continues + normal text ~[+ editors notes, numbered asterisk footnote/endnote series + ]~ continues +</pre> +<p> <b>resulting output:</b> +<p> normal text [^*3] continues +<p> normal text [^+2] continues + +<p> <b>Alternative endnote pair notation for footnotes/endnotes:</b> +<p> +<p> <br> +<pre> % note the endnote marker + normal text~^ continues + ^~ endnote text following the paragraph in which the marker occurs +</pre> +<p> the standard and pair notation cannot be mixed in the same document +<p> + +<p>9.5 LINKS +<p> 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS +<p> 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). +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text http://www.jus.uio.no/sisu continues +</pre> +<p> <b>resulting output:</b> +<p> normal text <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> continues +<p> An + +<p>escaped url without decoration +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> normal text _http://www.jus.uio.no/sisu continues + deb http://www.jus.uio.no/sisu/archive unstable main non-free +</pre> +<p> <b>resulting output:</b> +<p> normal text <_<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> continues +<p> +deb <_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> +> unstable main non-free +<p> where a code +block is used there is neither decoration nor hyperlinking, code blocks + +<p>are discussed later in this document +<p> <b>resulting output:</b> +<p> +<p> <br> +<pre> 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 +</pre> +<p> To link text or an image to a url the markup is as follows +<p> <b>markup example:</b> + +<p> +<p> <br> +<pre> about { SiSU }http://url.org markup +</pre> +<p> 9.5.2 LINKING TEXT +<p> <b>resulting output:</b> +<p> about SiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +> + +<p>markup +<p> A shortcut notation is available so the url link may also be provided + +<p>automatically as a footnote +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> about {~^ SiSU }http://url.org markup +</pre> +<p> <b>resulting output:</b> +<p> abou tSiSU <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +> [^14] markup +<p> + +<p>9.5.3 LINKING IMAGES +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> { tux.png 64x80 }image + % various url linked images + {tux.png 64x80 + {GnuDebianLinuxRubyBetterWay.png 100x101 + {~^ ruby_logo.png +</pre> +<p> <b>resulting output:</b> +<p> [ tux.png ] +<p> tux.png 64x80 +<p> [ ruby_logo (png missing) + ] [^15] +<p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby +<p> <b>linked url footnote + +<p>shortcut</b> +<p> +<p> <br> +<pre> {~^ [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 +</pre> +<p> +<p> <br> +<pre> text marker *~name +</pre> +<p> 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. +<p> 9.6 GROUPED TEXT +<p> 9.6.1 + +<p>TABLES +<p> Tables may be prepared in two either of two forms +<p> <b>markup example:</b> + +<p> +<p> <br> +<pre> 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 +</pre> +<p> <b>resulting output:</b> +<p> [table omitted, see other document formats]<br> + +<p> a second form may be easier to work with in cases where there is not + +<p>much information in each column +<p> <b>markup example:</b> [^16] +<p> +<p> <br> +<pre> !_ 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. +</pre> +<p> <b>resulting output:</b> +<p> <b>Table 3.1: Contributors to Wikipedia, January 2001 +- June 2005</b> +<p> [table omitted, see other document formats]<br> + +<p> * Contributed at least ten times; ** at least 5 times in last month; +*** more than 100 times in last month. +<p> 9.6.2 POEM +<p> <b>basic markup:</b> +<p> +<p> <br> +<pre> poem{ + Your poem here + }poem + Each verse in a poem is given a separate object number. +</pre> +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> poem{ + ‘Fury said to a + mouse, That he + met in the + house, + + 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, + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath. + + judge, I’ll + be jury, + Said + cunning + old Fury: + + try the + whole + cause, + and + condemn + you + to + death. + }poem +</pre> +<p> <b>resulting output:</b> +<p> ’Fury said to a<br> + mouse, That he<br> + met in the<br> + house,<br> + <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,<br> + a trial,<br> + dear Sir,<br> + With<br> + no jury<br> + or judge,<br> + would be<br> + wasting<br> + our<br> + breath.<br> + <br> + judge, I’ll<br> + be jury,<br> + Said<br> + cunning<br> + old Fury:<br> + <br> + try the<br> + whole<br> + cause,<br> + and<br> + condemn<br> + you<br> + to<br> + death.<br> + +<p> 9.6.3 GROUP +<p> <b>basic markup:</b> +<p> +<p> <br> +<pre> group{ + Your grouped text here + }group + A group is treated as an object and given a single object number. +</pre> +<p> <b>markup example:</b> +<p> +<p> <br> +<pre> group{ + ’Fury said to a + mouse, That he + met in the + house, + + 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, + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath. + + judge, I’ll + be jury, + Said + cunning + old Fury: + + try the + whole + cause, + and + condemn + you + to + death. + }group +</pre> +<p> <b>resulting output:</b> +<p> ’Fury said to a<br> + mouse, That he<br> + met in the<br> + house,<br> + <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,<br> + a trial,<br> + dear Sir,<br> + With<br> + no jury<br> + or judge,<br> + would be<br> + wasting<br> + our<br> + breath.<br> + <br> + judge, I’ll<br> + be jury,<br> + Said<br> + cunning<br> + old Fury:<br> + <br> + try the<br> + whole<br> + cause,<br> + and<br> + condemn<br> + you<br> + to<br> + death.<br> + +<p> 9.6.4 CODE +<p> Code tags are used to escape regular sisu markup, and have +been used extensively within this document to provide examples of <b>SiSU</b> +markup. You cannot however use code tags to escape code tags. They are however +used in the same way as group or poem tags. +<p> A code-block is treated as +an object and given a single object number. [an more than 100 times in last +month. option to number each line of code may be considered at more than +100 times in last month. some later time] +<p> <b>use of code tags instead of +poem compared, resulting output:</b> +<p> +<p> <br> +<pre> ’Fury said to a + mouse, That he + met in the + house, + + 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, + a trial, + dear Sir, + With + no jury + or judge, + would be + wasting + our + breath. + + judge, I’ll + be jury, + Said + cunning + old Fury: + + try the + whole + cause, + and + condemn + you + to + death. +</pre> +<p> 9.7 BOOK INDEX +<p> To make an index append to paragraph the book index term +relates to it, using an equal sign and curly braces. +<p> 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. +<p> +<p> <br> +<pre> Paragraph containing main term and sub-term. + ={Main term:sub-term} +</pre> +<p> The index syntax starts on a new line, but there should not be an empty +line between paragraph and index markup. +<p> The structure of the resulting +index would be: +<p> +<p> <br> +<pre> Main term, 1 + sub-term, 1 +</pre> +<p> 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. + +<p> +<p> <br> +<pre> Paragraph containing main term, second term and sub-term. + ={first term; second term: sub-term} +</pre> +<p> The structure of the resulting index would be: +<p> +<p> <br> +<pre> First term, 1, + Second term, 1, + sub-term, 1 +</pre> +<p> If multiple sub-terms appear under one paragraph, they are separated under +the main term heading from each other by a pipe symbol. +<p> +<p> <br> +<pre> 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 +</pre> +<p> 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: +<p> +<p> <br> +<pre> Main term, 1, + sub-term, 1-3, + second sub-term, 1, +</pre> +<p> 10. COMPOSITE DOCUMENTS MARKUP +<p> 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</b> 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</b> regular markup file, or <b>.ssi</b> (insert/information) + +<p>A secondary file of the composite document is built prior to processing + +<p>with the same prefix and the suffix <b>._sst</b> +<p> basic markup for importing a + +<p>document into a master document +<p> +<p> <br> +<pre> << filename1.sst + << filename2.ssi +</pre> +<p> 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. + +<p> +<p> <br> +<pre> << filename.ssi + <<{filename.ssi} + % using textlink alternatives + << |filename.ssi|@|^| +</pre> +<p> MARKUP SYNTAX HISTORY +<p> 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX + +<p> 0.38 is substantially current, depreciated 0.16 supported, though file + +<p>names were changed at 0.37 +<p> * sisu --query=[sisu version [0.38] or ’history] + +<p> provides a short history of changes to <b>SiSU</b> markup +<p> <b>0.57</b> (2007w34/4) +<b>SiSU</b> 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 and @author:] +<p> +<p> <br> +<pre> :A~ @title by @author +</pre> +<p> <b>0.52</b> (2007w14/6) declared document type identifier at start of text/document: + +<p> .B SiSU<br> + 0.52 +<p> or, backward compatible using the comment marker: +<p> %<br> + <b>SiSU</b> 0.38 +<p> variations include ’ <b>SiSU</b> (text|master|insert) [version]’ and ’sisu-[version]’ + +<p> <b>0.51</b> (2007w13/6) skins changed (simplified), markup unchanged +<p> <b>0.42</b> (2006w27/4) +* (asterisk) type endnotes, used e.g. in relation to author +<p> <b>SiSU</b> 0.42 is +the same as 0.38 with the introduction of some additional endnote types, + +<p> Introduces some variations on endnotes, in particular the use of the + +<p>asterisk +<p> +<p> <br> +<pre> ~{* for example for describing an author }~ and ~{** for describing a +second author }~ +</pre> +<p> * for example for describing an author +<p> ** for describing a second author + +<p> and +<p> +<p> <br> +<pre> ~[* my note ]~ or ~[+ another note ]~ +</pre> +<p> which numerically increments an asterisk and plus respectively +<p> *1 my + +<p>note +1 another note +<p> <b>0.38</b> (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) +<p> <b>SiSU</b> +0.38 introduced alternative experimental header and heading/structure markers, + +<p> +<p> <br> +<pre> @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~ +</pre> +<p> as the equivalent of: +<p> +<p> <br> +<pre> 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~ +</pre> +<p> The internal document markup of <b>SiSU</b> 0.16 remains valid and standard Though + +<p>note that <b>SiSU</b> 0.37 introduced a new file naming convention +<p> <b>SiSU</b> 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</b> 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 + +<p> <b>0.37</b> (2006w09/7) introduced new file naming convention, .sst (text), .ssm +(master), .ssi (insert), markup syntax unchanged +<p> <b>SiSU</b> 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> + +<p> this is captured by the following file ’rename’ instruction: +<p> +<p> <br> +<pre> rename ’s/.s[123]$/.sst/’ *.s{1,2,3} + rename ’s/.r[123]$/.ssm/’ *.r{1,2,3} + rename ’s/.si$/.ssi/’ *.si +</pre> +<p> The internal document markup remains unchanged, from <b>SiSU</b> 0.16 +<p> <b>0.35</b> (2005w52/3) +sisupod, zipped content file introduced +<p> <b>0.23</b> (2005w36/2) utf-8 for markup + +<p>file +<p> <b>0.22</b> (2005w35/3) image dimensions may be omitted if rmagick is available + +<p>to be relied upon +<p> <b>0.20.4</b> (2005w33/4) header 0~links +<p> <b>0.16</b> (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 + +<p>marker +<p> <b>SiSU</b> 0.16 (0.15 development branch) introduced the use of +<p> the +header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~ +<p> in place of the 0.1 +header, heading/structure notation +<p> <b>SiSU</b> 0.1 headers and headings structure +represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{ +<p> 12. +SISU FILETYPES +<p> <b>SiSU</b> has plaintext and binary filetypes, and can process +either type of document. +<p> 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT +<p> <b>SiSU</b> documents +are prepared as plain-text (utf-8) files with <b>SiSU</b> markup. They may make reference +to and contain images (for example), which are stored in the directory +beneath them _sisu/image. <b>SiSU</b> 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> + +<p> <b>SiSU</b> 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. + +<p> <b>SiSU</b> source markup can be shared with the command: +<p> sisu -s [filename]<br> + +<p> 12.1.1 SISU TEXT - REGULAR FILES (.SST) +<p> The most common form of document +in <b>SiSU</b> , see the section on <b>SiSU</b> markup. +<p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> +> + +<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +> +<p> 12.1.2 SISU MASTER FILES (.SSM) +<p> Composite +documents which incorporate other <b>SiSU</b> documents which may be either regular +<b>SiSU</b> text .sst which may be generated independently, or inserts prepared +solely for the purpose of being incorporated into one or more master documents. + +<p> The mechanism by which master files incorporate other documents is described +as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual. +<p> 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. +<p> Note: a secondary file of the composite document +is built prior to processing with the same prefix and the suffix ._sst [^17] + +<p> <<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a> +> +<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +> + +<p> 12.1.3 SISU INSERT FILES (.SSI) +<p> Inserts are documents prepared solely for +the purpose of being incorporated into one or more master documents. They +resemble regular <b>SiSU</b> text files except they are ignored by the <b>SiSU</b> 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. +<p> 12.2 SISUPOD, +ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP) +<p> A sisupod is a zipped <b>SiSU</b> +text file or set of <b>SiSU</b> text files and any associated images that they +contain (this will be extended to include sound and multimedia-files) +<p> +<b>SiSU</b> 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. +<p> 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</b> documents. +<p> The command to create +a sisupod is: +<p> sisu -S [filename]<br> + +<p> Alternatively, make a pod of the contents of a whole directory: +<p> +sisu -S<br> + +<p> <b>SiSU</b> processing can be done directly against a sisupod; which may be +located locally or on a remote server for which a url is provided. +<p> <<a href='http://www.jus.uio.no/sisu/sisu_commands'>http://www.jus.uio.no/sisu/sisu_commands</a> +> + +<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a> +> +<p> 13. EXPERIMENTAL ALTERNATIVE INPUT +REPRESENTATIONS +<p> 13.1 ALTERNATIVE XML +<p> <b>SiSU</b> 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. +<p> <b>convert from sst to simple xml representations (sax, +dom and node):</b> +<p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br> + +<p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br> + +<p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br> + +<p> <b>convert to sst from any sisu xml representation (sax, dom and node):</b> + +<p> sisu --from-xml2sst [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> or the same: +<p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> 13.1.1 XML SAX REPRESENTATION +<p> To convert from sst to simple xml (sax) +representation: +<p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br> + +<p> To convert from any sisu xml representation back to sst +<p> sisu --from-xml2sst +[filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> or the same: +<p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> 13.1.2 XML DOM REPRESENTATION +<p> To convert from sst to simple xml (dom) +representation: +<p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br> + +<p> To convert from any sisu xml representation back to sst +<p> sisu --from-xml2sst +[filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> or the same: +<p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> 13.1.3 XML NODE REPRESENTATION +<p> To convert from sst to simple xml (node) +representation: +<p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br> + +<p> To convert from any sisu xml representation back to sst +<p> sisu --from-xml2sst +[filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> or the same: +<p> sisu --from-sxml [filename/wildcard [.sxs.xml,.sxd.xml,sxn.xml]]<br> + +<p> 14. CONFIGURATION +<p> 14.1 DETERMINING THE CURRENT CONFIGURATION +<p> Information +on the current configuration of <b>SiSU</b> should be available with the help +command: +<p> sisu -v<br> + +<p> which is an alias for: +<p> sisu --help env<br> + +<p> Either of these should be executed from within a directory that contains +sisu markup source documents. +<p> 14.2 CONFIGURATION FILES (CONFIG.YML) +<p> <b>SiSU</b> +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. +<p> The <b>SiSU</b> configuration file is a yaml file, which +means indentation is significant. +<p> <b>SiSU</b> resource configuration is determined +by looking at the following files if they exist: +<p> ./_sisu/sisurc.yml<br> + +<p> ~/.sisu/sisurc.yml<br> + +<p> /etc/sisu/sisurc.yml<br> + +<p> The search is in the order listed, and the first one found is used. +<p> + In the absence of instructions in any of these it falls back to the internal +program defaults. +<p> Configuration determines the output and processing directories +and the database access details. +<p> If <b>SiSU</b> is installed a sample sisurc.yml + +<p>may be found in /etc/sisu/sisurc.yml +<p> 15. SKINS +<p> Skins modify the default +appearance of document output on a document, directory, or site wide basis. +Skins are looked for in the following locations: +<p> ./_sisu/skin<br> + +<p> ~/.sisu/skin<br> + +<p> /etc/sisu/skin<br> + +<p> <b>Within the skin directory</b> are the following the default sub-directories +for document skins: +<p> ./skin/doc<br> + +<p> ./skin/dir<br> + +<p> ./skin/site<br> + +<p> A skin is placed in the appropriate directory and the file named skin_[name].rb + +<p> The skin itself is a ruby file which modifies the default appearances +set in the program. +<p> 15.1 DOCUMENT SKIN +<p> Documents take on a document skin, +if the header of the document specifies a skin to be used. +<p> +<p> <br> +<pre> @skin: skin_united_nations +</pre> +<p> 15.2 DIRECTORY SKIN +<p> 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). +<p> 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. + +<p> 15.3 SITE SKIN +<p> A site skin, modifies the program default skin. +<p> 15.4 SAMPLE + +<p>SKINS +<p> With <b>SiSU</b> installed sample skins may be found in: +<p> /etc/sisu/skin/doc +and<br> + /usr/share/doc/sisu/v2/sisu_markup_samples/samples/_sisu/skin/doc<br> + +<p> (or equivalent directory) and if sisu-markup-samples is installed also +under: +<p> /usr/share/doc/sisu-markup-samples/v2/samples/_sisu/skin/doc<br> + +<p> Samples of list.yml and promo.yml (which are used to create the right +column list) may be found in: +<p> /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml +(or equivalent<br> + directory)<br> + +<p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML) +<p> CSS files +to modify the appearance of <b>SiSU</b> 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. + +<p> 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. +<p> HTML: html.css +<p> XML DOM: dom.css +<p> XML +SAX: sax.css +<p> XHTML: xhtml.css +<p> The default homepage may use homepage.css + +<p>or html.css +<p> 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] +<p> 17. ORGANISING +CONTENT +<p> 17.1 DIRECTORY STRUCTURE AND MAPPING +<p> 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) + +<p> 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. +<p> +<p> 18. HOMEPAGES +<p> <b>SiSU</b> is about the ability +to auto-generate documents. Home pages are regarded as custom built items, +and are not created by <b>SiSU</b> <b>SiSU</b> 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: +<p> 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) +<p> 2. through providing what you want as the +home page in a skin, +<p> 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. +<p> 18.1 + +<p>HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY +<p> 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: +<p> + sisu -CC<br> + +<p> 18.2 HOME PAGE WITHIN A SKIN +<p> Skins are described in a separate section, +but basically are a file written in the programming language <b>Ruby</b> 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. +<p> + 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 + +<p>poems in skin_poems.rb +<p> +<p> <br> +<pre> class Home + def homepage + # place the html content of your homepage here, this will become +index.html + <<HOME <html> + <head></head> + <doc> + <p>this is my new homepage.</p> + </doc> + </html> + HOME + end + end +</pre> +<p> 19. MARKUP AND OUTPUT EXAMPLES +<p> 19.1 MARKUP EXAMPLES +<p> Current markup examples +and document output samples are provided at <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> + +<p> Some markup with syntax highlighting may be found under <<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a> +> +but is not as up to date. +<p> 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. +<p> 20. +SISU SEARCH - INTRODUCTION +<p> <b>SiSU</b> output can easily and conveniently be +indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier. + +<p> 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. +<p> In addition to this <b>SiSU</b> 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. +<p> 21. SQL +<p> 21.1 POPULATING SQL TYPE DATABASES + +<p> <b>SiSU</b> feeds sisu markupd documents into sql type databases PostgreSQL[^19] +and/or SQLite[^20] database together with information related to document +structure. +<p> 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: +<p> * one containing semantic +(and other) headers, including, title, author,<br> + subject, (the Dublin Core...);<br> + +<p> * another the substantive texts by individual "paragraph" (or object) +-<br> + along with structural information, each paragraph being identifiable +by its<br> + paragraph number (if it has one which almost all of them do), and the<br> + substantive text of each paragraph quite naturally being searchable +(both in<br> + formatted and clean text versions for searching); and<br> + +<p> * a third containing endnotes cross-referenced back to the paragraph +from<br> + which they are referenced (both in formatted and clean text versions +for<br> + searching).<br> + +<p> * a fourth table with a one to one relation with the headers table +contains<br> + full text versions of output, eg. pdf, html, xml, and ascii.<br> + +<p> There is of course the possibility to add further structures. +<p> At this +level <b>SiSU</b> 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. +<p> Being able to search a relational +database at an object level with the <b>SiSU</b> citation system is an effective +way of locating content generated by <b>SiSU</b> 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). +<p> 22. +POSTGRESQL +<p> 22.1 NAME +<p> <b>SiSU</b> - Structured information, Serialized Units +- a document publishing system, postgresql dependency package +<p> 22.2 DESCRIPTION + +<p> 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</b> to populate a postgresql database, this being +part of <b>SiSU</b> - man sisu). +<p> 22.3 SYNOPSIS +<p> sisu -D [instruction] [filename/wildcard + if required]<br> + +<p> sisu -D --pg --[instruction] [filename/wildcard if required]<br> + +<p> 22.4 COMMANDS +<p> 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 +<p> <b>-D or --pgsql</b> may +be used interchangeably. +<p> 22.4.1 CREATE AND DESTROY DATABASE +<p> +<dl> + +<dt><b>--pgsql --createall</b> +</dt> +<dd>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) +<p> </dd> + +<dt><b>sisu -D --createdb</b> +</dt> +<dd> +<p>creates database where no database existed before +<p> </dd> + +<dt><b>sisu -D --create</b> </dt> +<dd>creates + +<p>database tables where no database tables existed before +<p> </dd> + +<dt><b>sisu -D --Dropall</b> +</dt> +<dd>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). +<p> </dd> + +<dt><b>sisu -D --recreate</b> </dt> +<dd>destroys existing database and builds + +<p>a new empty database structure +<p> </dd> +</dl> +22.4.2 IMPORT AND REMOVE DOCUMENTS +<p> +<dl> + +<dt><b>sisu +-D --import -v [filename/wildcard]</b> </dt> +<dd>populates database with the contents of +the file. Imports documents(s) specified to a postgresql database (at an +object level). +<p> </dd> + +<dt><b>sisu -D --update -v [filename/wildcard]</b> </dt> +<dd>updates file contents + +<p>in database +<p> </dd> + +<dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt> +<dd>removes specified document +from postgresql database. +<p> </dd> +</dl> +23. SQLITE +<p> 23.1 NAME +<p> <b>SiSU</b> - Structured information, +Serialized Units - a document publishing system. +<p> 23.2 DESCRIPTION +<p> 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</b> +to populate an sqlite database, this being part of <b>SiSU</b> - man sisu). +<p> 23.3 + +<p>SYNOPSIS +<p> sisu -d [instruction] [filename/wildcard if required]<br> + +<p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if <br> + required]<br> + +<p> 23.4 COMMANDS +<p> 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 +<p> <b>-d or --sqlite</b> may +be used interchangeably. +<p> 23.4.1 CREATE AND DESTROY DATABASE +<p> +<dl> + +<dt><b>--sqlite --createall</b> +</dt> +<dd>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) +<p> </dd> + +<dt><b>sisu -d --createdb</b> +</dt> +<dd> +<p>creates database where no database existed before +<p> </dd> + +<dt><b>sisu -d --create</b> </dt> +<dd>creates + +<p>database tables where no database tables existed before +<p> </dd> + +<dt><b>sisu -d --dropall</b> +</dt> +<dd>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). +<p> </dd> + +<dt><b>sisu -d --recreate</b> </dt> +<dd>destroys existing database and builds + +<p>a new empty database structure +<p> </dd> +</dl> +23.4.2 IMPORT AND REMOVE DOCUMENTS +<p> +<dl> + +<dt><b>sisu +-d --import -v [filename/wildcard]</b> </dt> +<dd>populates database with the contents of +the file. Imports documents(s) specified to an sqlite database (at an object +level). +<p> </dd> + +<dt><b>sisu -d --update -v [filename/wildcard]</b> </dt> +<dd>updates file contents in database + +<p> </dd> + +<dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt> +<dd>removes specified document from sqlite +database. +<p> </dd> +</dl> +24. INTRODUCTION +<p> 24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING +DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND +CURRENTLY POSTGRESQL) +<p> Sample search frontend <<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> +> +[^21] A small database and sample query front-end (search from) that makes +use of the citation system, <i>object</i> citation numbering to demonstrates functionality.[^22] + +<p> <b>SiSU</b> 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. +<p> 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] +<p> +<dl> + +<dt><b>sisu -F --webserv-webrick</b> </dt> +<dd>builds a cgi web search + +<p>frontend for the database created +<p> The following is feedback on the setup +on a machine provided by the help command: +<p> sisu --help sql<br> + +<p> +<p> <br> +<pre> 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 +</pre> +<p> Note on databases built +<p> 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 +<p> </dd> +</dl> +24.2 SEARCH FORM +<p> +<dl> + +<dt><b>sisu -F</b> </dt> +<dd>generates a sample search form, which must + +<p>be copied to the web-server cgi directory +<p> </dd> + +<dt><b>sisu -F --webserv-webrick</b> </dt> +<dd>generates +a sample search form for use with the webrick server, which must be copied + +<p>to the web-server cgi directory +<p> </dd> + +<dt><b>sisu -Fv</b> </dt> +<dd>as above, and provides some information + +<p>on setting up hyperestraier +<p> </dd> + +<dt><b>sisu -W</b> </dt> +<dd>starts the webrick server which should + +<p>be available wherever sisu is properly installed +<p> The generated search + +<p>form must be copied manually to the webserver directory as instructed +<p> +</dd> +</dl> +25. HYPERESTRAIER +<p> See the documentation for hyperestraier: +<p> <<a href='http://hyperestraier.sourceforge.net/'>http://hyperestraier.sourceforge.net/</a> +><br> + +<p> /usr/share/doc/hyperestraier/index.html<br> + +<p> man estcmd<br> + +<p> NOTE: the examples that follow assume that sisu output is placed in + +<p>the directory /home/ralph/sisu_www +<p> (A) to generate the index within the +webserver directory to be indexed: +<p> estcmd gather -sd [index name] [directory + path to index]<br> + +<p> the following are examples that will need to be tailored according to +your needs: +<p> cd /home/ralph/sisu_www<br> + +<p> estcmd gather -sd casket /home/ralph/sisu_www<br> + +<p> you may use the ’find’ command together with ’egrep’ to limit indexing to +particular document collection directories within the web server directory: + +<p> find /home/ralph/sisu_www -type f | egrep<br> + ’/home/ralph/sisu_www/sisu/.+?.html$’ |estcmd gather -sd casket -<br> + +<p> Check which directories in the webserver/output directory (~/sisu_www +or elsewhere depending on configuration) you wish to include in the search +index. +<p> 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. +<p> find /home/ralph/sisu_www +-type f | egrep<br> + ’/sisu_www/(sisu|bookmarks)/.+?.html$’ | egrep -v<br> + ’(doc|concordance).html$’ |estcmd gather -sd casket -<br> + +<p> from your current document preparation/markup directory, you would construct +a rune along the following lines: +<p> find /home/ralph/sisu_www -type f +| egrep ’/home/ralph/sisu_www/([specify <br> + first directory for inclusion]|[specify second directory for <br> + inclusion]|[another directory for inclusion? ...])/.+?.html$’ |<br> + egrep -v ’(doc|concordance).html$’ |estcmd gather -sd<br> + /home/ralph/sisu_www/casket -<br> + +<p> (B) to set up the search form +<p> (i) copy estseek.cgi to your cgi directory +and set file permissions to 755: +<p> sudo cp -vi /usr/lib/estraier/estseek.cgi +/usr/lib/cgi-bin<br> + +<p> sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi<br> + +<p> sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin<br> + +<p> [see estraier documentation for paths]<br> + +<p> (ii) edit estseek.conf, with attention to the lines starting ’indexname:’ +and ’replace:’: +<p> indexname: /home/ralph/sisu_www/casket<br> + +<p> replace: ^file:///home/ralph/sisu_www{{!}}<a href='http://localhost'>http://localhost</a> +<br> + +<p> replace: /index.html?${{!}}/<br> + +<p> (C) to test using webrick, start webrick: +<p> sisu -W<br> + +<p> and try open the url: <<a href='http://localhost:8081/cgi-bin/estseek.cgi'>http://localhost:8081/cgi-bin/estseek.cgi</a> +> +<p> 26. SISU_WEBRICK + +<p> 26.1 NAME +<p> <b>SiSU</b> - Structured information, Serialized Units - a document + +<p>publishing system +<p> 26.2 SYNOPSIS +<p> sisu_webrick [port] +<p> or +<p> sisu -W [port] + +<p> 26.3 DESCRIPTION +<p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick +starts <b>Ruby</b> ’s Webrick web-server and points it to the directories to which +<b>SiSU</b> output is written, providing a list of these directories (assuming +<b>SiSU</b> is in use and they exist). +<p> 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). +<p> 26.4 SUMMARY OF MAN PAGE +<p> 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] +<p> where no port is given and settings are + +<p>unchanged the default port is 8081 +<p> 26.5 DOCUMENT PROCESSING COMMAND FLAGS + +<p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories, +on the port provided, or if no port is provided and the defaults have not + +<p>been changed in ~/.sisu/sisurc.yaml then on port 8081 +<p> 26.6 FURTHER INFORMATION + +<p> For more information on <b>SiSU</b> see: <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> +<p> or man sisu + +<p> 26.7 AUTHOR +<p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com +<p> + +<p>26.8 SEE ALSO +<p> <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a> +<br> + +<p> <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a> +<br> + +<p> <a href='http:~/bin/man2html?sisu:8'>sisu(8)</a> +<br> + +<p> 27. REMOTE SOURCE DOCUMENTS +<p> <b>SiSU</b> 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</b> +documents can either be sisu marked up files in plaintext .sst or .ssm or; +zipped sisu files, sisupod.zip or filename.ssp +<p> <b>.sst / .ssm - sisu text files</b> + +<p> <b>SiSU</b> 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. +<p> +<p> <br> +<pre> sisu -3 http://[provide url to valid .sst or .ssm file] +</pre> +<p> Any of the source documents in the sisu examples page can be used in +this way, see <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> and use the url +for the desired document. +<p> NOTE: to set up a remote machine to serve <b>SiSU</b> +documents in this way, images should be in the directory relative to the + +<p>document source ../_sisu/image +<p> <b>sisupod - zipped sisu files</b> +<p> 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. +<p> <b>SiSU</b> 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. +<p> +<p> <br> +<pre> sisu -3 http://[provide url to valid sisupod.zip or .ssp file] +</pre> +<p> Any of the source documents in the sisu examples page can be used in +this way, see <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> and use the url +for the desired document. +<p> REMOTE DOCUMENT OUTPUT +<p> 28. REMOTE OUTPUT +<p> +Once properly configured <b>SiSU</b> output can be automatically posted once generated +to a designated remote machine using either rsync, or scp. +<p> 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. +<p> +<p> <br> +<pre> sisu -3R sisu_remote.sst +</pre> +<p> 28.1 COMMANDS +<p> +<dl> + +<dt><b>-R [filename/wildcard]</b> </dt> +<dd>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 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 +<p> </dd> + +<dt><b>-r [filename/wildcard]</b> </dt> +<dd>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 + +<p>your +<p> </dd> +</dl> +28.2 CONFIGURATION +<p> [expand on the setting up of an ssh-agent / keychain] + +<p> 29. REMOTE SERVERS +<p> As <b>SiSU</b> is generally operated using the command line, +and works within a Unix type environment, <b>SiSU</b> 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. +<p> 30. QUICKSTART - GETTING STARTED HOWTO + +<p> 30.1 INSTALLATION +<p> Installation is currently most straightforward and +tested on the <b>Debian</b> platform, as there are packages for the installation +of sisu and all requirements for what it does. +<p> 30.1.1 DEBIAN INSTALLATION + +<p> <b>SiSU</b> is available directly from the <b>Debian</b> Sid and testing archives (and +possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly: + +<p> +<p> <br> +<pre> aptitude update + aptitude install sisu-complete +</pre> +<p> The following /etc/apt/sources.list setting permits the download of additional +markup samples: +<p> +<p> <br> +<pre> #/etc/apt/sources.list + deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib + deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib + d +</pre> +<p> The aptitude commands become: +<p> +<p> <br> +<pre> aptitude update + aptitude install sisu-complete sisu-markup-samples +</pre> +<p> If there are newer versions of <b>SiSU</b> upstream of the <b>Debian</b> archives, + +<p>they will be available by adding the following to your /etc/apt/sources.list + +<p> +<p> <br> +<pre> #/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 +</pre> +<p> repeat the aptitude commands +<p> +<p> <br> +<pre> aptitude update + aptitude install sisu-complete sisu-markup-samples +</pre> +<p> 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. +<p> 30.1.2 RPM INSTALLATION +<p> RPMs are provided +though untested, they are prepared by running alien against the source +package, and against the debs. +<p> They may be downloaded from: +<p> <<a href='http://www.jus.uio.no/sisu/SiSU/download.html#rpm'>http://www.jus.uio.no/sisu/SiSU/download.html#rpm</a> +><br> + +<p> as root type: +<p> rpm -i [rpm package name]<br> + +<p> 30.1.3 INSTALLATION FROM SOURCE +<p> To install <b>SiSU</b> from source check information +at: +<p> <<a href='http://www.jus.uio.no/sisu/SiSU/download.html#current'>http://www.jus.uio.no/sisu/SiSU/download.html#current</a> +><br> + +<p> * download the source package +<p> * Unpack the source +<p> 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: +<p> For basic use +<b>SiSU</b> is only dependent on the programming language in which it is written +<b>Ruby</b> , and <b>SiSU</b> 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. +<p> <b>setup.rb</b> +<p> This +is a standard ruby installer, using setup.rb is a three step process. In +the root directory of the unpacked <b>SiSU</b> as root type: +<p> +<p> <br> +<pre> ruby setup.rb config + ruby setup.rb setup + #[and as root:] + ruby setup.rb install +</pre> +<p> further information on setup.rb is available from: +<p> <<a href='http://i.loveruby.net/en/projects/setup/'>http://i.loveruby.net/en/projects/setup/</a> +><br> + +<p> <<a href='http://i.loveruby.net/en/projects/setup/doc/usage.html'>http://i.loveruby.net/en/projects/setup/doc/usage.html</a> +><br> + +<p> <b></b> +<p> The root directory of the unpacked <b>SiSU</b> as root type: +<p> ruby install +base<br> + +<p> or for a more complete installation: +<p> ruby install<br> + +<p> or +<p> ruby install base<br> + +<p> 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. +<p> Further + +<p>information on +<p> <<a href='http://make.rubyforge.org/'>http://make.rubyforge.org/</a> +><br> + +<p> <<a href='http://rubyforge.org/frs/?group_id=615'>http://rubyforge.org/frs/?group_id=615</a> +><br> + +<p> For a list of alternative actions you may type: +<p> ruby install help<br> + +<p> ruby install -T<br> + +<p> 30.2 TESTING SISU, GENERATING OUTPUT +<p> To check which version of sisu +is installed: +<p> sisu -v +<p> Depending on your mode of installation one or +a number of markup sample files may be found either in the directory: +<p> + +<p> or +<p> +<p> change directory to the appropriate one: +<p> cd /usr/share/doc/sisu/sisu_markup_samples/dfsg + +<p> 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB +<p> Having moved to the +directory that contains the markup samples (see instructions above if necessary), + +<p>choose a file and run sisu against it +<p> sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +<p> this will generate html including a concordance file, opendocument text +format, plaintext, XHTML and various forms of XML, and OpenDocument text + +<p> 30.2.2 LATEX / PDF +<p> 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</b> ) +<p> Having moved to the directory that contains the markup +samples (see instructions above if necessary), choose a file and run sisu + +<p>against it +<p> sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst + +<p> sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst +<p> should +generate most available output formats: html including a concordance file, +opendocument text format, plaintext, XHTML and various forms of XML, and + +<p>OpenDocument text and pdf +<p> 30.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE + +<p> Relational databases need some setting up - you must have permission to +create the database and write to it when you run sisu. +<p> Assuming you have + +<p>the database installed and the requisite permissions +<p> sisu --sqlite --recreate + +<p> sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst + +<p> sisu --pgsql --recreate +<p> sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst + +<p> 30.3 GETTING HELP +<p> 30.3.1 THE MAN PAGES +<p> Type: +<p> man sisu<br> + +<p> The man pages are also available online, though not always kept as up +to date as within the package itself: +<p> * sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a> +> +[^25] +<p> * sisu.8 <<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a> +> [^26] +<p> * man directory +<<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> +> [^27] +<p> 30.3.2 BUILT IN HELP +<p> sisu --help +<p> sisu + +<p>- +<p>- +<p>help --env +<p> sisu --help --commands +<p> sisu --help --markup +<p> 30.3.3 THE HOME PAGE +<p> +<<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> +<p> <<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a> +> +<p> 30.4 MARKUP SAMPLES + +<p> A number of markup samples (along with output) are available off: +<p> <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> + +<p> Additional markup samples are packaged separately in the file: +<p> <b>*</b> +<p> +On <b>Debian</b> 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. +<p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING +<p> The directory: + +<p> ./data/sisu/v2/conf/editor-syntax-etc/<br> + +<p> /usr/share/sisu/v2/conf/editor-syntax-etc<br> + +<p> contains rudimentary sisu syntax highlighting files for: +<p> * (g)vim +<<a href='http://www.vim.org'>http://www.vim.org</a> +> +<p> package: sisu-vim<br> + +<p> status: largely done +<p> there is a vim syntax highlighting and folds +component<br> + +<p> * gedit <<a href='http://www.gnome.org/projects/gedit'>http://www.gnome.org/projects/gedit</a> +> +<p> * gobby <<a href='http://gobby.0x539.de/'>http://gobby.0x539.de/</a> +> + +<p> file: sisu.lang<br> + +<p> place in: +<p> /usr/share/gtksourceview-1.0/language-specs<br> + +<p> or +<p> ~/.gnome2/gtksourceview-1.0/language-specs<br> + +<p> status: very basic syntax highlighting<br> + +<p> comments: this editor features display line wrap and is used by Goby!<br> + +<p> * nano <<a href='http://www.nano-editor.org'>http://www.nano-editor.org</a> +> +<p> file: nanorc<br> + +<p> save as: +<p> ~/.nanorc<br> + +<p> status: basic syntax highlighting<br> + +<p> comments: assumes dark background; no display line-wrap; does line +breaks<br> + +<p> * diakonos (an editor written in ruby) <<a href='http://purepistos.net/diakonos'>http://purepistos.net/diakonos</a> +> + +<p> file: diakonos.conf +<p> save as: +<p> ~/.diakonos/diakonos.conf<br> + +<p> includes: +<p> status: basic syntax highlighting<br> + +<p> comments: assumes dark background; no display line-wrap +<p> * kate & kwrite +<<a href='http://kate.kde.org'>http://kate.kde.org</a> +> +<p> file: sisu.xml<br> + +<p> place in:<br> + +<p> /usr/share/apps/katepart/syntax<br> + +<p> or<br> + +<p> ~/.kde/share/apps/katepart/syntax<br> + +<p> [settings::configure kate::{highlighting,filetypes}]<br> + +<p> [tools::highlighting::{markup,scripts}:: .B SiSU ]<br> + +<p> * nedit <<a href='http://www.nedit.org'>http://www.nedit.org</a> +> +<p> file: sisu_nedit.pats<br> + +<p> nedit -import sisu_nedit.pats<br> + +<p> status: a very clumsy first attempt [not really done]<br> + +<p> comments: this editor features display line wrap<br> + +<p> * emacs <<a href='http://www.gnu.org/software/emacs/emacs.html'>http://www.gnu.org/software/emacs/emacs.html</a> +> +<p> files: sisu-mode.el<br> + +<p> to file ~/.emacs add the following 2 lines:<br> + +<p> (add-to-list ’load-path<br> + +<p> (require ’sisu-mode.el)<br> + +<p> [not done / not yet included]<br> + +<p> * vim & gvim <<a href='http://www.vim.org'>http://www.vim.org</a> +> +<p> files:<br> + +<p> package is the most comprehensive sisu syntax highlighting and editor<br> + environment provided to date (is for vim/ gvim, and is separate from +the<br> + contents of this directory)<br> + +<p> status: this includes: syntax highlighting; vim folds; some error +checking<br> + +<p> comments: this editor features display line wrap<br> + +<p> NOTE: +<p> [ .B SiSU parses files with long lines or line breaks, display + linewrap (without line-breaks) is a convenient editor feature to have for + sisu markup] +<p> 32. HOW DOES SISU WORK? +<p> <b>SiSU</b> 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</b> 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). +<p> 33. SUMMARY OF FEATURES +<p> * 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 headers +are optional. +<p> * 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]. + +<p> * 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</b> 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 paper publication, sql search etc.] (html, +epub, xml, odf, latex, pdf, sql) +<p> * 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: +<p> * html - both as a single scrollable text and a segmented +document<br> + +<p> * xhtml<br> + +<p> * epub<br> + +<p> * XML - both in sax and dom style xml structures for further development +as<br> + required<br> + +<p> * ODF - open document format, the iso standard for document storage<br> + +<p> * LaTeX - used to generate pdf<br> + +<p> * pdf (via LaTeX)<br> + +<p> * sql - population of an sql database, (at the same object level that +is<br> + used to cite text within a document)<br> + +<p> 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)) +<p> * +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. +<p> * 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]. +<p> <b>*</b>long<b>term</b>maintainability<b>of</b>document<b>collections</b>in<b>a</b>world<b>of</b>changing +formats, having a very sparsely marked-up source document base. there is +a considerable degree of future-proofing, output representations are upgradeable +(open document text) module in 2006, epub in 2009 and in future html5 output +sometime in future, without modification of existing prepared texts +<p> * +SQL search aside, documents are generated as required and static once generated. + +<p> * 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) +<p> * document source (plaintext utf-8) if + +<p>shared on the net may be used as input and processed locally to produce + +<p>the different document outputs +<p> * 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 + +<p>the desired document outputs +<p> * generated document outputs may automatically +be posted to remote sites. +<p> * for basic document generation, the only software +dependency is <b>Ruby</b> , 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. +<p> * as a developers tool it is flexible and extensible +<p> Syntax +highlighting for <b>SiSU</b> markup is available for a number of text editors. + +<p> <b>SiSU</b> 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 +<p> 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)... +<p> 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. +<p> 34. HELP SOURCES +<p> For a summary of alternative +ways to get help on <b>SiSU</b> try one of the following: +<p> <b>man page</b> +<p> man sisu_help<br> + +<p> <b>man2html</b> +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_help.1.html'>http://www.jus.uio.no/sisu/man/sisu_help.1.html</a> +><br> + +<p> <b>sisu generated output - links to html</b> +<p> <<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a> +><br> + +<p> <b>help sources lists</b> +<p> Alternative sources for this help sources page +listed here: +<p> man sisu_help_sources<br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> +><br> + +<p> 34.1 MAN PAGES +<p> 34.1.1 MAN +<p> man sisu<br> + +<p> man 7 sisu_complete<br> + +<p> man 7 sisu_pdf<br> + +<p> man 7 sisu_postgresql<br> + +<p> man 7 sisu_sqlite<br> + +<p> man sisu_termsheet<br> + +<p> man sisu_webrick<br> + +<p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML +<p> Note <b>SiSU</b> documentation is +prepared in <b>SiSU</b> 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] +<p> 34.2.1 WWW.SISUDOC.ORG +<p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> +> + +<p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_commands/index.html'>http://sisudoc.org/sisu/sisu_commands/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_complete/index.html'>http://sisudoc.org/sisu/sisu_complete/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_configuration/index.html'>http://sisudoc.org/sisu/sisu_configuration/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_description/index.html'>http://sisudoc.org/sisu/sisu_description/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_examples/index.html'>http://sisudoc.org/sisu/sisu_examples/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_faq/index.html'>http://sisudoc.org/sisu/sisu_faq/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_filetypes/index.html'>http://sisudoc.org/sisu/sisu_filetypes/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_howto/index.html'>http://sisudoc.org/sisu/sisu_howto/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_introduction/index.html'>http://sisudoc.org/sisu/sisu_introduction/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_markup/index.html'>http://sisudoc.org/sisu/sisu_markup/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_output_overview/index.html'>http://sisudoc.org/sisu/sisu_output_overview/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_pdf/index.html'>http://sisudoc.org/sisu/sisu_pdf/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_postgresql/index.html'>http://sisudoc.org/sisu/sisu_postgresql/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_quickstart/index.html'>http://sisudoc.org/sisu/sisu_quickstart/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_remote/index.html'>http://sisudoc.org/sisu/sisu_remote/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_search/index.html'>http://sisudoc.org/sisu/sisu_search/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_skin/index.html'>http://sisudoc.org/sisu/sisu_skin/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_sqlite/index.html'>http://sisudoc.org/sisu/sisu_sqlite/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_vim/index.html'>http://sisudoc.org/sisu/sisu_vim/index.html</a> +><br> + +<p> <<a href='http://sisudoc.org/sisu/sisu_webrick/index.html'>http://sisudoc.org/sisu/sisu_webrick/index.html</a> +><br> + +<p> 34.3 MAN2HTML +<p> 34.3.1 LOCALLY INSTALLED +<p> <file:///usr/share/doc/sisu/v2/html/sisu.1.html> + +<p> <file:///usr/share/doc/sisu/v2/html/sisu_help.1.html> +<p> <file:///usr/share/doc/sisu/v2/html/sisu_help_sources.1.html> + +<p> /usr/share/doc/sisu/v2/html/sisu.1.html<br> + +<p> /usr/share/doc/sisu/v2/html/sisu_pdf.7.html<br> + +<p> /usr/share/doc/sisu/v2/html/sisu_postgresql.7.html<br> + +<p> /usr/share/doc/sisu/v2/html/sisu_sqlite.7.html<br> + +<p> /usr/share/doc/sisu/v2/html/sisu_webrick.1.html<br> + +<p> 34.3.2 WWW.JUS.UIO.NO/SISU +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +><br> + +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_complete.7.html'>http://www.jus.uio.no/sisu/man/sisu_complete.7.html</a> +><br> + +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_pdf.7.html'>http://www.jus.uio.no/sisu/man/sisu_pdf.7.html</a> +><br> + +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html'>http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html</a> +><br> + +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html'>http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html</a> +><br> + +<p> <<a href='http://www.jus.uio.no/sisu/man/sisu_webrick.1.html'>http://www.jus.uio.no/sisu/man/sisu_webrick.1.html</a> +><br> + +<p> +<ol> +<b>.</b><li>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. </li><b>.</b><li>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. +<p> </li><b>.</b><li>the different heading levels </li><b>.</b><li>units +of text, primarily paragraphs and headings, also any tables, poems, code-blocks +</li><b>.</b><li>Specification submitted by Adobe to ISO to become a full open ISO specification +<<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a> +> </li><b>.</b><li>ISO standard ISO/IEC 26300:2006 + +<p> </li><b>.</b><li>An open standard format for e-books +<p> </dd> + +<dt><b>*1.</b> </dt> +<dd>square brackets </dd> + +<dt><b>*2.</b> </dt> +<dd>square brackets +</dd> + +<dt><b>+1.</b> </dt> +<dd>square brackets </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> +> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> +</li><b>.</b><li>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. </li><b>.</b><li>files should +be prepared using UTF-8 character encoding </li><b>.</b><li>a footnote or endnote </li><b>.</b><li>self contained +endnote marker & endnote in one </dd> + +<dt><b>*.</b> </dt> +<dd>unnumbered asterisk footnote/endnote, +insert multiple asterisks if required </dd> + +<dt><b>**.</b> </dt> +<dd>another unnumbered asterisk footnote/endnote +</dd> + +<dt><b>*3.</b> </dt> +<dd>editors notes, numbered asterisk footnote/endnote series </dd> + +<dt><b>+2.</b> </dt> +<dd>editors +notes, numbered asterisk footnote/endnote series </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +> +</li><b>.</b><li><<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> +> </li><b>.</b><li>Table from the Wealth of Networks by Yochai Benkler +<<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a> +> </li><b>.</b><li>.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 processing. +It may be however that when the resulting file is shared .ssc is an appropriate +suffix to use. </li><b>.</b><li><<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a> +> <<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a> +> <<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a> +> +</li><b>.</b><li><<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a> +> <<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a> +> </li><b>.</b><li><<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> +> +</li><b>.</b><li>(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. </li><b>.</b><li>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. </li><b>.</b><li>There is nothing to stop MySQL support +being added in future. </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a> +> </li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a> +> +</li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a> +> </li><b>.</b><li>the <b>Debian</b> Free Software guidelines require +that everything distributed within <b>Debian</b> can be changed - and the documents +are authors’ works that while freely distributable are not freely changeable. +</li><b>.</b><li> +<p>named index.html or more extensively through sisu_manifest.html +<p> </li> +</ol> + +<h2><a name='sect2' href='#toc2'>See Also</a></h2> +<a href='http:~/bin/man2html?sisu:1'><i>sisu</i>(1)</a> +, +<br> +<a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-odf:1'><i>sisu-odf</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a> +, <br> +<a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a> +. <br> +<a href='http:~/bin/man2html?sisu_vim:7'><i>sisu_vim</i>(7)</a> + <br> +<a href='http:~/bin/man2html?sisu:8'><i>sisu</i>(8)</a> + +<p> +<h2><a name='sect3' href='#toc3'>Homepage</a></h2> +More information about <b>SiSU</b> can be found at <<a href='http://www.jus.uio.no/sisu/'><i>http://www.jus.uio.no/sisu/</i></a> +>. + +<p> +<h2><a name='sect4' href='#toc4'>Author</a></h2> +<b>SiSU</b> was written by Ralph Amissah <<i>ralph@amissah.com</i>>. <p> + +<hr><p> +<a name='toc'><b>Table of Contents</b></a><p> +<ul> +<li><a name='toc0' href='#sect0'>Name</a></li> +<li><a name='toc1' href='#sect1'>Synopsis</a></li> +<li><a name='toc2' href='#sect2'>See Also</a></li> +<li><a name='toc3' href='#sect3'>Homepage</a></li> +<li><a name='toc4' href='#sect4'>Author</a></li> +</ul> +</body> +</html> diff --git a/data/doc/sisu/html/sisu_vim.7.html b/data/doc/sisu/html/sisu_vim.7.html index f9e18237..b7ee2028 100644 --- a/data/doc/sisu/html/sisu_vim.7.html +++ b/data/doc/sisu/html/sisu_vim.7.html @@ -18,14 +18,9 @@ publishing in multiple standard formats, and search<br> <p> <b>SiSU</b> has syntax highlighting for a number of editors including vim which are documented under: -<p> man sisu_syntax_highlighting<br> +<p> /usr/share/doc/sisu/markup-samples/sisu_manual/sisu_syntax_highlighting.sst<br> -<p> /usr/share/doc/sisu/sisu_manual/sisu_syntax_highlighting/index.html<br> - -<p> <<a href='http://sisudoc.org/sisu_manual/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu_manual/sisu_syntax_highlighting/index.html</a> -><br> - -<p> <<a href='http://www.jus.uio.no/sisu/sisu_manual/sisu_syntax_highlighting/index.html'>http://www.jus.uio.no/sisu/sisu_manual/sisu_syntax_highlighting/index.html</a> +<p> <<a href='http://www.sisudoc.org/sisu/sisu_manual/sisu_syntax_highlighting/index.html'>http://www.sisudoc.org/sisu/sisu_manual/sisu_syntax_highlighting/index.html</a> ><br> <p> <b>SiSU</b> also provides an ftplugin to provide vim folds for <b>SiSU</b> markup, @@ -51,98 +46,12 @@ on files with the suffix .sst .ssm .ssi .-sst ._sst (and the same with a furthe </pre> <p> FURTHER INFORMATION <p> For more information on <b>SiSU</b> see: -<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +<p> <<a href='http://sisudoc.org/'>http://sisudoc.org/</a> > -<p> or man sisu -<p> DOCUMENT INFORMATION (METADATA) -<p> METADATA -<p> Document Manifest -@ <<a href='http://sisudoc.org/sisu_manual/sisu_vim/sisu_manifest.html'>http://sisudoc.org/sisu_manual/sisu_vim/sisu_manifest.html</a> -> -<p> <b>Dublin Core</b> -(DC) -<p> <i>DC</i> tags included with this document are provided here. -<p> DC Title: -<i>SiSU</i> - Vim -<p> DC Creator: <i>Ralph</i> Amissah -<p> DC Rights: <i>Copyright</i> (C) Ralph -Amissah 2008, part of SiSU documentation, License GPL 3 -<p> DC Type: <i>information</i> - -<p> DC Date created: <i>2002-11-12</i> -<p> DC Date issued: <i>2002-11-12</i> -<p> DC Date available: - -<p><i>2002-11-12</i> -<p> DC Date modified: <i>2008-02-12</i> -<p> DC Date: <i>2008-02-12</i> -<p> <b>Version Information</b> - -<p> Sourcefile: <i>sisu_vim.sst</i> -<p> Filetype: <i>SiSU</i> text insert 0.58 -<p> Sourcefile -Digest, MD5(sisu_vim.sst)= <i>b5028f957b128162f7653bbd940042ca</i> -<p> Skin_Digest: -MD5(skin_sisu_manual.rb)= <i>072b2584bedea82ea8a416587b9fa244</i> -<p> <b>Generated</b> -<p> - Document (metaverse) last generated: <i>Thu</i> Feb 14 02:44:14 +0000 2008 -<p> -Generated by: <i>SiSU</i> <i>0.64.4</i> of 2008w06/4 (2008-02-14) -<p> Ruby version: <i>ruby</i> 1.8.6 -(2007-09-24 patchlevel 111) [i486-linux] -<p> -<p> -<dl> - -<dt>Other versions of this document: -</dt> -<dd></dd> - -<dt>manifest: <<a href='http://www.jus.uio.no/sisu/sisu_vim/sisu_manifest.html'><a href='http://www.jus.uio.no/sisu/sisu_vim/sisu_manifest.html'>http://www.jus.uio.no/sisu/sisu_vim/sisu_manifest.html</a> -</a> -> </dt> -<dd></dd> - -<dt>html: <<a href='http://www.jus.uio.no/sisu/sisu_vim/toc.html'><a href='http://www.jus.uio.no/sisu/sisu_vim/toc.html'>http://www.jus.uio.no/sisu/sisu_vim/toc.html</a> -</a> -> -</dt> -<dd></dd> - -<dt>pdf: <<a href='http://www.jus.uio.no/sisu/sisu_vim/portrait.pdf'><a href='http://www.jus.uio.no/sisu/sisu_vim/portrait.pdf'>http://www.jus.uio.no/sisu/sisu_vim/portrait.pdf</a> -</a> -> </dt> -<dd></dd> - -<dt>pdf: <<a href='http://www.jus.uio.no/sisu/sisu_vim/landscape.pdf'><a href='http://www.jus.uio.no/sisu/sisu_vim/landscape.pdf'>http://www.jus.uio.no/sisu/sisu_vim/landscape.pdf</a> -</a> +<p> <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> > -</dt> -<dd></dd> - -<dt>at: <<a href='http://www.jus.uio.no/sisu'><a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> -</a> -> </dt> -<dd></dd> - -<dt>* Generated by: SiSU 0.64.4 of 2008w06/4 (2008-02-14) -</dt> -<dd></dd> - -<dt>* Ruby version: ruby 1.8.6 (2007-09-24 patchlevel 111) [i486-linux] </dt> -<dd></dd> - -<dt>* Last Generated -on: Thu Feb 14 02:44:14 +0000 2008 </dt> -<dd></dd> - -<dt>* SiSU <a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> - </dt> -<dd></dd> -</dl> -<p> +<p> or man sisu <p> <hr><p> <a name='toc'><b>Table of Contents</b></a><p> |