aboutsummaryrefslogtreecommitdiffhomepage
path: root/data/doc/sisu/html/sisu4.1.html
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2012-11-18 21:50:04 -0500
committerRalph Amissah <ralph@amissah.com>2012-12-12 09:44:37 -0500
commiteae9bb93fdd2e677c8882bcc96d42b804ac2bafe (patch)
tree5b5b33598ba30847c07888f6eb8cc644a8133876 /data/doc/sisu/html/sisu4.1.html
parentv4: vim syntax, sisu.vim, make, new headers (diff)
v4: documentation; markup samples & help
Diffstat (limited to 'data/doc/sisu/html/sisu4.1.html')
-rw-r--r--data/doc/sisu/html/sisu4.1.html3693
1 files changed, 3693 insertions, 0 deletions
diff --git a/data/doc/sisu/html/sisu4.1.html b/data/doc/sisu/html/sisu4.1.html
new file mode 100644
index 00000000..345e574b
--- /dev/null
+++ b/data/doc/sisu/html/sisu4.1.html
@@ -0,0 +1,3693 @@
+<!-- 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>
+<br>
+
+<h2><a name='sect0' href='#toc0'>Name</a></h2>
+<br>
+sisu - documents: markup, structuring, publishing in multiple standard formats,
+and search <br>
+
+<h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
+<br>
+sisu [-short-options|--long-options] [filename/wildcard]
+<p> <br>
+sisu [-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0-9] [filename/wildcard]
+
+<p> <br>
+sisu --txt --html --epub --odt --pdf --wordmap --sqlite --manpage --texinfo --sisupod --source
+--qrcode [filename/wildcard]
+<p> <br>
+sisu [-Ddcv] [instruction] [filename/wildcard]
+<p> <br>
+sisu --pg (--createdb|update [filename/wildcard]|--dropall)
+<p> <br>
+sisu [operations]
+<p> <br>
+sisu [-CcFLSVvW]
+<p> <br>
+sisu (--configure|--webrick|--sample-search-form)
+<h2><a name='sect2' href='#toc2'>Sisu - Manual,</a></h2>
+RALPH AMISSAH <br>
+
+<p>
+<h2><a name='sect3' href='#toc3'>What is Sisu?</a></h2>
+<br>
+
+<p>
+<h2><a name='sect4' href='#toc4'>Introduction - What is Sisu?</a></h2>
+<br>
+
+<p> <br>
+<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> <br>
+<b>SiSU</b> is developed under an open source, software libre license ( <i>GPLv3</i>
+). 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> <br>
+<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&rsquo;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 <i>HTML,</i> <i>EPUB,</i> <i>ODT</i> (Open Document Format text), <i>LaTeX,</i>
+landscape and portrait <i>PDF,</i> all of which can be added to and updated. <b>SiSU</b>
+is also able to populate <i>SQL</i> type databases at an object level, which means
+that searches can be made with that degree of granularity.
+<p> <br>
+Source document preparation and output generation is a two step process:
+(i) document source is prepared, that is, marked up in sisu markup syntax
+and (ii) the desired output subsequently generated by running the sisu
+engine against document source. Output representations if updated (in the
+sisu engine) can be generated by re-running the engine against the prepared
+source. Using <b>SiSU</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, <i>HTML,</i> <i>XHTML,</i>
+<i>XML,</i> <i>EPUB,</i> <i>ODT,</i> <i>LaTeX</i> or <i>PDF</i> files, and populate an <i>SQL</i> 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> <br>
+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> <br>
+<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&rsquo;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> <br>
+One of the challenges of maintaining documents is to keep them in a format
+that allows use of them independently of proprietary platforms. Consider
+issues related to dealing with legacy proprietary formats today and what
+guarantee you have that old proprietary formats will remain (or can be
+read without proprietary software/equipment) in 15 years time, or the way
+the way in which html has evolved over its relatively short span of existence.
+<b>SiSU</b> provides the flexibility of producing documents in multiple non-proprietary
+open formats including <i>HTML,</i> <i>EPUB,</i> [^5] <i>ODT,</i> [^6] <i>PDF</i> [^7] <i>ODF,</i> [^8]. 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 <i>GPLv3</i> 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), <i>EPUB</i> was introduced in 2009; and allows the technical
+representations existing output to be updated ( <i>HTML</i> has evolved and the
+related module has been updated repeatedly over the years, presumably when
+the World Wide Web Consortium (w3c) finalises <i>HTML</i> 5 which is currently
+under development, the <i>HTML</i> module will again be updated allowing all existing
+documents to be regenerated as <i>HTML</i> 5).
+<p> <br>
+The document formats are written to the file-system and available for indexing
+by independent indexing tools, whether off the web like Google and Yahoo
+or on the site like Lucene and Hyperestraier.
+<p> <br>
+<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> <br>
+<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> <br>
+&lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt;
+<p> <br>
+&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+<p>
+<h2><a name='sect5' href='#toc5'>Commands Summary</a></h2>
+<br>
+
+<p>
+<h2><a name='sect6' href='#toc6'>Description</a></h2>
+
+<p> <br>
+<b>SiSU</b> is a document publishing system, that from a simple single marked-up
+document, produces multiple output formats including: <i>plaintext,</i> <i>HTML,</i>
+<i>XHTML,</i> <i>XML,</i> <i>EPUB,</i> <i>ODT</i> ( <i>OpenDocument</i> ( <i>ODF</i> ) text), <i>LaTeX,</i> <i>PDF,</i> info, and
+<i>SQL</i> ( <i>PostgreSQL</i> and <i>SQLite</i> ) , which share text object numbers ("object
+citation numbering") and the same document structure information. For more
+see: &lt;<a href='http://sisudoc.org'>http://sisudoc.org</a>
+&gt; or &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+<p>
+<h2><a name='sect7' href='#toc7'>Document Processing
+Command Flags</a></h2>
+
+<p>
+<dl>
+
+<dt><b>-a [filename/wildcard]</b> </dt>
+<dd>produces <i>plaintext</i> with Unix linefeeds
+and without markup, (object numbers are omitted), has footnotes at end
+of each paragraph that contains them [ &nbsp;-A &nbsp;for &nbsp;output &nbsp;file] [see &nbsp;-e &nbsp;for &nbsp;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>
+<dd>see --xhtml
+<p> </dd>
+
+<dt><b>--by-*</b> </dt>
+<dd>see --output-by-*
+<p> </dd>
+
+<dt><b>-C</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>see --configure
+<p> </dd>
+
+<dt><b>-c [filename/wildcard]</b> </dt>
+<dd>see --color-toggle
+<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 &rsquo;true&rsquo;, output to screen will be with colour, if sisurc colour default
+is set to &rsquo;false&rsquo; or is undefined screen output will be without colour). Alias
+
+<p>-
+<p>c
+<p> </dd>
+
+<dt><b>--configure</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>--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>-D [instruction] [filename]</b> </dt>
+<dd>see --pg
+<p> </dd>
+
+<dt><b>-d [--db-[database &nbsp;type
+&nbsp;(sqlite|pg)]] --[instruction] [filename]</b> </dt>
+<dd>see --sqlite
+<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.
+
+<p>Alias -m
+<p> </dd>
+
+<dt><b>--delete [filename/wildcard]</b> </dt>
+<dd>see --zap
+<p> </dd>
+
+<dt><b>--dump[=directory_path] [filename/wildcard]</b>
+</dt>
+<dd>places output in directory specified, if none is specified in the current
+directory (pwd). Compare --redirect
+<p> </dd>
+
+<dt><b>-e [filename/wildcard]</b> </dt>
+<dd>see --epub
+<p> </dd>
+
+<dt><b>--epub
+[filename/wildcard]</b> </dt>
+<dd>produces an epub document, [sisu &nbsp;version &nbsp;&gt;=2 &nbsp;] (filename.epub).
+
+<p>Alias -e
+<p> </dd>
+
+<dt><b>--exc-*</b> </dt>
+<dd>exclude output feature, overrides configuration settings
+--exc- <i>ocn,</i> (exclude <i>object</i> citation numbering, (switches off <i>object</i> citation
+numbering ) , affects html (seg, scroll), epub, xhtml, xml, pdf) ; --exc-toc,
+(exclude table of contents, affects html (scroll), epub, pdf) ; --exc-links-to-manifest,
+--exc-manifest-links, (exclude links to manifest, affects html (seg, scroll));
+--exc-search-form, (exclude search form, affects html (seg, scroll), manifest);
+--exc-minitoc, (exclude mini table of contents, affects html (seg), concordance,
+manifest); --exc-manifest-minitoc, (exclude mini table of contents, affects
+manifest); --exc-html-minitoc, (exclude mini table of contents, affects html
+(seg), concordance); --exc-html-navigation, (exclude navigation, affects html
+(seg)); --exc-html-navigation-bar, (exclude navigation bar, affects html (seg));
+--exc-html-search-form, (exclude search form, affects html (seg, scroll)); --exc-html-right-pane,
+(exclude right pane/column, affects html (seg, scroll)); --exc-html-top-band,
+(exclude top band, affects html (seg, scroll), concordance (minitoc forced
+on to provide seg navigation)); --exc-segsubtoc (exclude sub table of contents,
+affects html (seg), epub) ; see also --inc-*
+<p> </dd>
+
+<dt><b>-F [--webserv=webrick]</b> </dt>
+<dd>see --sample-search-form
+
+<p> </dd>
+
+<dt><b>-f [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dd>see --find
+<p> </dd>
+
+<dt><b>--find [optional &nbsp;string &nbsp;part
+&nbsp;of &nbsp;filename]</b> </dt>
+<dd>without match string, glob all .sst .ssm files in directory
+(including language subdirectories). With match string, find files that
+match given string in directory (including language subdirectories). Alias
+-f, --glob, -G
+<p> </dd>
+
+<dt><b>-G [optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dd>see --find
+<p> </dd>
+
+<dt><b>-g [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --git
+<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>--glob
+[optional &nbsp;string &nbsp;part &nbsp;of &nbsp;filename]</b> </dt>
+<dd>see --find
+<p> </dd>
+
+<dt><b>-h [filename/wildcard]</b> </dt>
+<dd>see
+
+<p>-
+<p>-
+<p>html
+<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,
+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>-I [filename/wildcard]</b> </dt>
+<dd>see --texinfo
+<p> </dd>
+
+<dt><b>-i [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --manpage
+<p> </dd>
+
+<dt><b>--inc-*</b> </dt>
+<dd>include output feature, overrides configuration settings,
+(usually the default if none set), has precedence over --exc-* (exclude output
+feature). Some detail provided under --exc-*, see --exc-*
+<p> </dd>
+
+<dt><b>-j [filename/wildcard]</b>
+</dt>
+<dd>copies images associated with a file for use by html, xhtml &amp; xml outputs
+(automatically invoked by --dump &amp; redirect).
+<p> </dd>
+
+<dt><b>--keep-processing-files [filename/wildcard/url]</b>
+</dt>
+<dd>
+<p>see --maintenance
+<p> </dd>
+
+<dt><b>-L</b> </dt>
+<dd>prints license information.
+<p> </dd>
+
+<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)
+<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, interim
+processing files are preserved and their locations indicated. (also see
+-V). Aliases -M and --keep-processing-files.
+<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>-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>--no-*</b> </dt>
+<dd>see --exc-*
+
+<p> </dd>
+
+<dt><b>-o [filename/wildcard/url]</b> </dt>
+<dd>see --odt
+<p> </dd>
+
+<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
+<p> </dd>
+
+<dt><b>--output-by-*</b> </dt>
+<dd>select output directory structure
+from 3 alternatives: --output-by-language, (language directory (based on language
+code) with filetype (html, epub, pdf etc.) subdirectories); --output-by-filetype,
+(filetype directories with language code as part of filename); --output-by-filename,
+(filename directories with language code as part of filename). This is configurable.
+Alias --by-*
+<p> </dd>
+
+<dt><b>-P [language_directory/filename &nbsp;language_directory]</b> </dt>
+<dd>see --po4a
+
+<p> </dd>
+
+<dt><b>-p [filename/wildcard]</b> </dt>
+<dd>see --pdf
+<p> </dd>
+
+<dt><b>--pdf [filename/wildcard]</b> </dt>
+<dd>produces <i>LaTeX</i>
+pdf (portrait.pdf &amp; 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: &rsquo;A4&rsquo;, U.S. &rsquo;letter&rsquo; and &rsquo;legal&rsquo; and book sizes
+&rsquo;A5&rsquo; and &rsquo;B5&rsquo; (system defaults to A4). Alias -p
+<p> </dd>
+
+<dt><b>--pg [instruction] [filename]</b>
+</dt>
+<dd>database <i>PostgreSQL</i> ( --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
+&nbsp;language_directory]</b> </dt>
+<dd>see --po4a
+<p> </dd>
+
+<dt><b>--po4a [language_directory/filename &nbsp;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>-Q [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --qrcode
+<p> </dd>
+
+<dt><b>-q [filename/wildcard]</b> </dt>
+<dd>see --quiet
+<p> </dd>
+
+<dt><b>--qrcode [filename/wildcard]</b>
+</dt>
+<dd>generate QR code image of metadata (used in manifest). v3 only.
+<p> </dd>
+
+<dt><b>--quiet [filename/wildcard]</b>
+</dt>
+<dd>quiet less output to screen.
+<p> </dd>
+
+<dt><b>-R [filename/wildcard]</b> </dt>
+<dd>see --rsync
+<p> </dd>
+
+<dt><b>-r [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --scp
+<p> </dd>
+
+<dt><b>--redirect[=directory_path] [filename/wildcard]</b> </dt>
+<dd>places output in
+subdirectory under specified directory, subdirectory uses the filename
+(without the suffix). If no output directory is specified places the subdirectory
+under the current directory (pwd). Compare --dump
+<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>-S</b> </dt>
+<dd>see --sisupod
+<p> </dd>
+
+<dt><b>-S [filename/wildcard]</b> </dt>
+<dd>see --sisupod
+<p> </dd>
+
+<dt><b>-s [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --source
+<p> </dd>
+
+<dt><b>--sample-search-form [--webserv=webrick]</b> </dt>
+<dd>generate examples of (naive)
+cgi search form for <i>SQLite</i> and PgSQL depends on your already having used
+sisu to populate an <i>SQLite</i> and/or PgSQL database, (the <i>SQLite</i> 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). 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 set to <i>SQLite,</i> this produces one
+of two possible databases, without additional database related instructions
+it produces a discreet <i>SQLite</i> file for the document processed; with additional
+instructions it produces a common <i>SQLite</i> database of all processed documents
+that (come from the same document preparation directory and as a result)
+share the same output directory base path (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>-T [filename/wildcard &nbsp;(*.termsheet.rb)]</b>
+</dt>
+<dd>standard form document builder, preprocessing feature
+<p> </dd>
+
+<dt><b>-t [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --txt
+<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 <i>plaintext</i> with Unix
+linefeeds and without markup, (object numbers are omitted), has footnotes
+at end of each paragraph that contains them [ &nbsp;-A &nbsp;for &nbsp;output &nbsp;file] [see &nbsp;-e
+&nbsp;for &nbsp;endnotes]. (Options include: --endnotes for endnotes --footnotes for footnotes
+at the end of each paragraph --unix for unix linefeed (default) --msdos for
+msdos linefeed). Alias -t
+<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>--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.
+
+<p>Alias -U
+<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>--v3 [filename/wildcard]</b> </dt>
+<dd>invokes the sisu v3 document parser/generator.
+You may run sisu3 instead.
+<p> </dd>
+
+<dt><b>--v4 [filename/wildcard]</b> </dt>
+<dd>invokes the sisu v4 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. Alias -v
+<p> </dd>
+
+<dt><b>-W</b> </dt>
+<dd>see --webrick
+
+<p> </dd>
+
+<dt><b>-w [filename/wildcard]</b> </dt>
+<dd>see --concordance
+<p> </dd>
+
+<dt><b>--webrick</b> </dt>
+<dd>starts ruby&rsquo; 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: &nbsp;the &nbsp;webrick &nbsp;server
+&nbsp;requires &nbsp;link &nbsp;suffixes, &nbsp;so &nbsp;html output &nbsp;should &nbsp;be &nbsp;created &nbsp;using &nbsp;the &nbsp;-h &nbsp;option
+&nbsp;rather &nbsp;than &nbsp;also, &nbsp;note &nbsp;-F &nbsp;webrick &nbsp;]. Alias -W
+<p> </dd>
+
+<dt><b>--wordmap [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --concordance
+<p> </dd>
+
+<dt><b>--xhtml [filename/wildcard]</b> </dt>
+<dd>produces xhtml/ <i>XML</i> output for
+browser viewing (sax parsing). Alias -b
+<p> </dd>
+
+<dt><b>--xml-dom [filename/wildcard]</b> </dt>
+<dd>produces
+<i>XML</i> output with deep document structure, in the nature of dom. Alias -X
+<p>
+</dd>
+
+<dt><b>--xml-sax [filename/wildcard]</b> </dt>
+<dd>produces <i>XML</i> output shallow structure (sax parsing).
+
+<p>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 &nbsp;announcement &nbsp;this
+&nbsp;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>-Z [filename/wildcard]</b> </dt>
+<dd>see
+
+<p>-
+<p>-
+<p>zap
+<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>
+</dl>
+
+<h2><a name='sect8' href='#toc8'>Command Line Modifiers</a></h2>
+<br>
+
+<p>
+<dl>
+
+<dt><b>--no-</b> </dt>
+<dd><i>ocn</i> [with &nbsp;--html &nbsp;--pdf &nbsp;or &nbsp;--epub] switches off <i>object</i> citation numbering.
+Produce output without identifying numbers in margins of html or <i>LaTeX</i>
+/pdf output.
+<p> </dd>
+
+<dt><b>--no-annotate</b> </dt>
+<dd>strips output text of editor endnotes[^*1] denoted
+
+<p>by asterisk or dagger/plus sign
+<p> </dd>
+
+<dt><b>--no-asterisk</b> </dt>
+<dd>strips output text of editor
+endnotes[^*2] denoted by asterisk sign
+<p> </dd>
+
+<dt><b>--no-dagger</b> </dt>
+<dd>strips output text of editor
+endnotes[^+1] denoted by dagger/plus sign
+<p> </dd>
+</dl>
+
+<h2><a name='sect9' href='#toc9'>Database Commands</a></h2>
+<br>
+
+<p> <br>
+<b>dbi - database interface</b>
+<p> <br>
+<b>-D or --pgsql</b> set for <i>PostgreSQL</i> <b>-d or --sqlite</b> default set for <i>SQLite</i> -d is modifiable
+with --db=[database &nbsp;type &nbsp;(PgSQL &nbsp;or &nbsp;.I &nbsp;SQLite &nbsp;) &nbsp;]
+<p>
+<dl>
+
+<dt><b>--pg -v --createall</b> </dt>
+<dd>initial step,
+creates required relations (tables, indexes) in existing <i>PostgreSQL</i> database
+(a database should be created manually and given the same name as working
+directory, as requested) (rb.dbi) [ &nbsp;-dv &nbsp;--createall &nbsp;.I SQLite &nbsp;equivalent] it
+may be necessary to run sisu -Dv --createdb initially NOTE: at the present
+time for <i>PostgreSQL</i> it may be necessary to manually create the database.
+The command would be working &nbsp;directory &nbsp;name &nbsp;(without &nbsp;path)]. Please use
+only alphanumerics and underscores.
+<p> </dd>
+
+<dt><b>--pg -v --import</b> </dt>
+<dd>[filename/wildcard] imports
+data specified to <i>PostgreSQL</i> db (rb.dbi) [ &nbsp;-dv &nbsp;--import &nbsp;.I &nbsp;SQLite &nbsp;equivalent]
+
+<p> </dd>
+
+<dt><b>--pg -v --update</b> </dt>
+<dd>[filename/wildcard] updates/imports specified data to <i>PostgreSQL</i>
+db (rb.dbi) [ &nbsp;-dv &nbsp;--update &nbsp;.I &nbsp;SQLite &nbsp;equivalent]
+<p> </dd>
+
+<dt><b>--pg --remove</b> </dt>
+<dd>[filename/wildcard]
+removes specified data to <i>PostgreSQL</i> db (rb.dbi) [ &nbsp;-d &nbsp;--remove &nbsp;.I &nbsp;SQLite &nbsp;equivalent]
+
+<p> </dd>
+
+<dt><b>--pg --dropall</b> </dt>
+<dd>kills data" and drops ( <i>PostgreSQL</i> or <i>SQLite</i> ) db, tables &amp;
+indexes [ &nbsp;-d &nbsp;--dropall &nbsp;.I &nbsp;SQLite &nbsp;equivalent]
+<p> <br>
+The -v is for verbose output.
+<p> </dd>
+</dl>
+
+<h2><a name='sect10' href='#toc10'>Shortcuts, Shorthand for Multiple Flags</a></h2>
+<br>
+
+<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 &nbsp;or &nbsp;wildcard]</b> </dt>
+<dd>Default
+shorthand mappings (for v3, note that the defaults can be changed/configured
+in the sisurc.yml file):
+<p> </dd>
+
+<dt><b>-0</b> </dt>
+<dd>-NQhewpotbxXyYv [this &nbsp;is &nbsp;the &nbsp;default &nbsp;action &nbsp;run
+&nbsp;when &nbsp;no options &nbsp;are &nbsp;give, &nbsp;i.e. &nbsp;on &nbsp;&rsquo;sisu &nbsp;[filename]&rsquo;]
+<p> </dd>
+
+<dt><b>-1</b> </dt>
+<dd>-Qhewpoty
+<p> </dd>
+
+<dt><b>-2</b> </dt>
+<dd>-NQhewpotbxXy
+
+<p> </dd>
+
+<dt><b>-3</b> </dt>
+<dd>-NQhewpotbxXyY
+<p> </dd>
+
+<dt><b>-4</b> </dt>
+<dd>-NQhewpotbxXDyY --update
+<p> </dd>
+
+<dt><b>-5</b> </dt>
+<dd>-NQhewpotbxXDyYv --update
+<p> <br>
+add -v for verbose mode and -c to toggle color state, e.g. sisu -2vc [filename
+&nbsp;or &nbsp;wildcard]
+<p> <br>
+
+<p>consider -u for appended url info or -v for verbose output
+<p> </dd>
+</dl>
+
+<h2><a name='sect11' href='#toc11'>Command Line
+with Flags - Batch Processing</a></h2>
+
+<p> <br>
+In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst"
+or "sisu -h *.{sst,ssm}" to produce html version of all documents.
+<p> <br>
+Running sisu (alone without any flags, filenames or wildcards) brings up
+the interactive help, as does any sisu command that is not recognised. Enter
+to escape.
+<p>
+<h2><a name='sect12' href='#toc12'>Help</a></h2>
+<br>
+
+<p>
+<h2><a name='sect13' href='#toc13'>Sisu Manual</a></h2>
+
+<p> <br>
+The most up to date information on sisu should be contained in the sisu_manual,
+available at:
+<p> <br>
+ &lt;<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a>
+&gt;<br>
+
+<p> <br>
+The manual can be generated from source, found respectively, either within
+the <b>SiSU</b> tarball or installed locally at:
+<p> <br>
+ ./data/doc/sisu/markup-samples/sisu_manual<br>
+
+<p> <br>
+ /usr/share/doc/sisu/markup-samples/sisu_manual<br>
+
+<p> <br>
+move to the respective directory and type e.g.:
+<p> <br>
+ sisu sisu_manual.ssm<br>
+
+<p>
+<h2><a name='sect14' href='#toc14'>Sisu Man Pages</a></h2>
+
+<p> <br>
+If <b>SiSU</b> is installed on your system usual man commands should be available,
+try:
+<p> <br>
+ man sisu<br>
+
+<p> <br>
+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> <br>
+ ./data/doc/sisu/markup-samples/sisu_manual<br>
+
+<p> <br>
+Once installed, directory equivalent to:
+<p> <br>
+ /usr/share/doc/sisu/markup-samples/sisu_manual<br>
+
+<p> <br>
+Available man pages are converted back to html using man2html:
+<p> <br>
+ /usr/share/doc/sisu/html/<br>
+
+<p> <br>
+ ./data/doc/sisu/html<br>
+
+<p> <br>
+An online version of the sisu man page is available here:
+<p> <br>
+* various sisu man pages &lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
+&gt; [^9]
+<p> <br>
+* sisu.1 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
+&gt; [^10]
+<p>
+<h2><a name='sect15' href='#toc15'>Sisu Built-in Interactive
+Help</a></h2>
+
+<p> <br>
+This is particularly useful for getting the current sisu setup/environment
+information:
+<p> <br>
+ sisu --help<br>
+
+<p> <br>
+ sisu --help [subject]<br>
+
+<p> <br>
+ sisu --help commands<br>
+
+<p> <br>
+ sisu --help markup<br>
+
+<p> <br>
+ sisu --help env [for &nbsp;feedback &nbsp;on &nbsp;the &nbsp;way &nbsp;your &nbsp;system &nbsp;is <br>
+ setup &nbsp;with &nbsp;regard &nbsp;to &nbsp;sisu &nbsp;]<br>
+
+<p> <br>
+ sisu -V [environment &nbsp;information, &nbsp;same &nbsp;as &nbsp;above &nbsp;command]<br>
+
+<p> <br>
+ sisu (on its own provides version and some help information)<br>
+
+<p> <br>
+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> <br>
+NOTE: Running the command sisu (alone without any flags, filenames or wildcards)
+brings up the interactive help, as does any sisu command that is not recognised.
+Enter to escape.
+<p>
+<h2><a name='sect16' href='#toc16'>Introduction to Sisu Markup[^11]</a></h2>
+<br>
+
+<p>
+<h2><a name='sect17' href='#toc17'>Summary</a></h2>
+
+<p> <br>
+<b>SiSU</b> source documents are <i>plaintext</i> ( <i>UTF-8</i> )[^12] files
+<p> <br>
+All paragraphs are separated by an empty line.
+<p> <br>
+Markup is comprised of:
+<p> <br>
+* at the top of a document, the document header made up of semantic meta-data
+about the document and if desired additional processing instructions (such
+an instruction to automatically number headings from a particular level
+down)
+<p> <br>
+* followed by the prepared substantive text of which the most important
+single characteristic is the markup of different heading levels, which
+define the primary outline of the document structure. Markup of substantive
+text includes:
+<p> <br>
+ * heading levels defines document structure<br>
+
+<p> <br>
+ * text basic attributes, italics, bold etc.<br>
+
+<p> <br>
+ * grouped text (objects), which are to be treated differently, such as
+code<br>
+ blocks or poems.<br>
+
+<p> <br>
+ * footnotes/endnotes<br>
+
+<p> <br>
+ * linked text and images<br>
+
+<p> <br>
+ * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br>
+
+<p> <br>
+Some interactive help on markup is available, by typing sisu and selecting
+
+<p>markup or sisu --help markup
+<p> <br>
+To check the markup in a file:
+<p> <br>
+ sisu --identify [filename].sst<br>
+
+<p> <br>
+
+<p>For brief descriptive summary of markup history
+<p> <br>
+ sisu --query-history<br>
+
+<p> <br>
+or if for a particular version:
+<p> <br>
+ sisu --query-0.38<br>
+
+<p>
+<h2><a name='sect18' href='#toc18'>Markup Examples</a></h2>
+
+<p>
+<h2><a name='sect19' href='#toc19'>Online</a></h2>
+
+<p> <br>
+Online markup examples are available together with the respective outputs
+produced from &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
+&gt; or from &lt;<a href='http://www.jus.uio.no/sisu/sisu_examples/'>http://www.jus.uio.no/sisu/sisu_examples/</a>
+&gt;
+
+<p> <br>
+There is of course this document, which provides a cursory overview of
+sisu markup and the respective output produced: &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup/'>http://www.jus.uio.no/sisu/sisu_markup/</a>
+&gt;
+
+<p> <br>
+an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz
+
+<p>
+<h2><a name='sect20' href='#toc20'>Installed</a></h2>
+
+<p> <br>
+With <b>SiSU</b> installed sample skins may be found in: /usr/share/doc/sisu/markup-samples
+(or equivalent directory) and if sisu -markup-samples is installed also under:
+
+<p>/usr/share/doc/sisu/markup-samples-non-free
+<p>
+<h2><a name='sect21' href='#toc21'>Markup of Headers</a></h2>
+<br>
+
+<p> <br>
+Headers contain either: semantic meta-data about a document, which can be
+used by any output module of the program, or; processing instructions.
+<p>
+<br>
+Note: the first line of a document may include information on the markup
+version used in the form of a comment. Comments are a percentage mark at
+the start of a paragraph (and as the first character in a line of text)
+followed by a space and the comment:
+<p> <br>
+<pre>% this would be a comment
+</pre>
+<p>
+<h2><a name='sect22' href='#toc22'>Sample Header</a></h2>
+
+<p> <br>
+This current document is loaded by a master document that has a header
+similar to this one:
+<p> <br>
+<pre>% SiSU master 2.0
+@title: SiSU
+:subtitle: Manual
+@creator:
+:author: Amissah, Ralph
+@publisher: [publisher &nbsp;name]
+@rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation,
+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
+:bold: /Gnu|Debian|Ruby|SiSU/
+:home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+:footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+:manpage: name=sisu - documents: markup, structuring, publishing in multiple
+standard formats, and search;
+ synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard
+&nbsp;]
+ . sisu [-Ddcv] [instruction]
+ . sisu [-CcFLSVvW]
+ . sisu --v4 [operations]
+ . sisu --v3 [operations]
+@links:
+{ SiSU Homepage }http://www.sisudoc.org/
+{ SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
+{ Book Samples &amp; Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
+{ SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+{ SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
+{ SiSU Git repo }http://git.sisudoc.org/?p=code/sisu.git;a=summary
+{ SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
+{ SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
+{ SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
+{ SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+</pre>
+<p>
+<h2><a name='sect23' href='#toc23'>Available Headers</a></h2>
+
+<p> <br>
+Header tags appear at the beginning of a document and provide meta information
+on the document (such as the <i>Dublin</i> Core ) , or information as to how the
+document as a whole is to be processed. All header instructions take the
+form @headername: or on the next line and indented by once space :subheadername:
+
+<p>All <i>Dublin</i> Core meta tags are available
+<p> <br>
+<b>@indentifier:</b> information or instructions
+<p> <br>
+where the "identifier" is a tag recognised by the program, and the "information"
+or "instructions" belong to the tag/indentifier specified
+<p> <br>
+Note: a header where used should only be used once; all headers apart from
+@title: are optional; the @structure: header is used to describe document
+structure, and can be useful to know.
+<p> <br>
+
+<p>This is a sample header
+<p> <br>
+<pre>% SiSU 2.0 [declared &nbsp;file-type &nbsp;identifier &nbsp;with &nbsp;markup &nbsp;version]
+</pre>
+<p> <br>
+<pre>@title: [title &nbsp;text] [this &nbsp;header &nbsp;is &nbsp;the &nbsp;only &nbsp;one &nbsp;that &nbsp;is &nbsp;mandatory]
+ :subtitle: [subtitle &nbsp;if &nbsp;any]
+ :language: English
+</pre>
+<p> <br>
+<pre>@creator:
+:author: [Lastname, &nbsp;First &nbsp;names]
+:illustrator: [Lastname, &nbsp;First &nbsp;names]
+:translator: [Lastname, &nbsp;First &nbsp;names]
+:prepared_by: [Lastname, &nbsp;First &nbsp;names]
+</pre>
+<p> <br>
+<pre>@date:
+:published: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:created: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:issued: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:available: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:modified: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:valid: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:added_to_site: [year &nbsp;or &nbsp;yyyy-mm-dd]
+:translated: [year &nbsp;or &nbsp;yyyy-mm-dd]
+</pre>
+<p> <br>
+<pre>@rights:
+:copyright: Copyright (C) [Year &nbsp;and &nbsp;Holder]
+:license: [Use &nbsp;License &nbsp;granted]
+:text: [Year &nbsp;and &nbsp;Holder]
+:translation: [Name, &nbsp;Year]
+:illustrations: [Name, &nbsp;Year]
+</pre>
+<p> <br>
+<pre>@classify:
+:topic_register: SiSU:markup sample:book;book:novel:fantasy
+:type:
+:subject:
+:description:
+:keywords:
+:abstract:
+:loc: [Library &nbsp;of &nbsp;Congress &nbsp;classification]
+:dewey: Dewey classification
+</pre>
+<p> <br>
+<pre>@identify:
+:isbn: [ISBN]
+:oclc:
+</pre>
+<p> <br>
+<pre>@links: { SiSU }http://www.sisudoc.org
+ { FSF }http://www.fsf.org
+</pre>
+<p> <br>
+<pre>@make:
+:num_top: 1
+:headings: [text &nbsp;to &nbsp;match &nbsp;for &nbsp;each &nbsp;level &nbsp; (e.g. &nbsp;PART; &nbsp;Chapter; &nbsp;Section;
+&nbsp;Article; &nbsp;or &nbsp;another: &nbsp;none; &nbsp;BOOK|FIRST|SECOND; &nbsp;none; &nbsp;CHAPTER;) &nbsp;:breaks: &nbsp;new=:C;
+&nbsp;break=1 &nbsp;:promo: &nbsp;sisu, &nbsp;ruby, &nbsp;sisu_search_libre, &nbsp;open_society &nbsp;:bold: &nbsp;[regular
+&nbsp;expression &nbsp;of &nbsp;words/phrases &nbsp;to &nbsp;be &nbsp;made &nbsp;bold]
+:italics: [regular &nbsp;expression &nbsp;of &nbsp;words/phrases &nbsp;to &nbsp;italicise]
+:home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+:footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+</pre>
+<p> <br>
+<pre>@original:
+:language: [language]
+</pre>
+<p> <br>
+<pre>@notes:
+:comment:
+:prefix: [prefix &nbsp;is &nbsp;placed &nbsp;just &nbsp;after &nbsp;table &nbsp;of &nbsp;contents]
+</pre>
+<p>
+<h2><a name='sect24' href='#toc24'>Markup of Substantive Text</a></h2>
+<br>
+
+<p>
+<h2><a name='sect25' href='#toc25'>Heading Levels</a></h2>
+
+<p> <br>
+Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
+headings, followed by other heading levels, and 1 -6 being headings followed
+by substantive text or sub-headings. :A~ usually the title :A~? conditional
+level 1 heading (used where a stand-alone document may be imported into
+another)
+<p> <br>
+<b>:A~ [heading &nbsp;text]</b> Top level heading [this &nbsp;usually &nbsp;has &nbsp;similar &nbsp;content
+&nbsp;to &nbsp;the &nbsp;title &nbsp;@title: &nbsp;] NOTE: the heading levels described here are in 0.38
+notation, see heading
+<p> <br>
+<b>:B~ [heading &nbsp;text]</b> Second level heading [this &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
+
+<p> <br>
+<b>:C~ [heading &nbsp;text]</b> Third level heading [this &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
+
+<p> <br>
+<b>1~ [heading &nbsp;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> <br>
+<b>2~ [heading &nbsp;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> <br>
+<b>3~ [heading &nbsp;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> <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>
+<h2><a name='sect26' href='#toc26'>Font Attributes</a></h2>
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_,
+"{citation}",
+^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
+normal text
+*{emphasis}* [note: &nbsp;can &nbsp;be &nbsp;configured &nbsp;to &nbsp;be &nbsp;represented &nbsp;by &nbsp;bold, &nbsp;italics
+&nbsp;or &nbsp;underscore]
+!{bold text}!
+/{italics}/
+_{underscore}_
+"{citation}"
+^{superscript}^
+,{subscript},
++{inserted text}+
+-{strikethrough}-
+#{monospace}#
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text, <b>emphasis,</b> <b>bold text</b> , <i>italics,</i> <i>underscore,</i> "citation", ^superscript^,
+[subscript], ++inserted text++, --strikethrough--, monospace
+<p> <br>
+
+<p>normal text
+<p> <br>
+<b>emphasis</b> [note: &nbsp;can &nbsp;be &nbsp;configured &nbsp;to &nbsp;be &nbsp;represented &nbsp;by &nbsp;bold, &nbsp;italics &nbsp;italics
+&nbsp;or &nbsp;underscore] or &nbsp;underscore]
+<p> <br>
+
+<p><b>bold text</b>
+<p> <br>
+
+<p><i>italics</i>
+<p> <br>
+
+<p><i>underscore</i>
+<p> <br>
+"citation"
+<p> <br>
+^superscript^
+<p> <br>
+[subscript]
+<p> <br>
+++inserted text++
+<p> <br>
+--strikethrough--
+<p> <br>
+
+<p>monospace
+<p>
+<h2><a name='sect27' href='#toc27'>Indentation and Bullets</a></h2>
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>ordinary paragraph
+_1 indent paragraph one step
+_2 indent paragraph two steps
+_9 indent paragraph nine steps
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+
+<p>ordinary paragraph
+<p> <br>
+ indent paragraph one step<br>
+
+<p> <br>
+ indent paragraph two steps<br>
+
+<p> <br>
+ indent paragraph nine steps<br>
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>_* bullet text
+_1* bullet text, first indent
+_2* bullet text, two step indent
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+* bullet text
+<p> <br>
+ * bullet text, first indent<br>
+
+<p> <br>
+ * bullet text, two step indent<br>
+
+<p> <br>
+Numbered List (not to be confused with headings/titles, (document structure))
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre># numbered list numbered list 1., 2., 3, etc.
+_# numbered list numbered list indented a., b., c., d., etc.
+</pre>
+<p>
+<h2><a name='sect28' href='#toc28'>Hanging Indents</a></h2>
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>_0_1 first line no indent,
+rest of paragraph indented one step
+_1_0 first line indented,
+rest of paragraph no indent
+in each case level may be 0-9
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+ first line no indent, rest of paragraph indented one step<br>
+
+<p> <br>
+first line indented, rest of paragraph no indent
+<p> <br>
+
+<p>in each case level may be 0-9
+<p>
+<h2><a name='sect29' href='#toc29'>Footnotes / Endnotes</a></h2>
+
+<p> <br>
+Footnotes and endnotes are marked up at the location where they would be
+indicated within a text. They are automatically numbered. The output type
+
+<p>determines whether footnotes or endnotes will be produced
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>~{ a footnote or endnote }~
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+[^13]
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>normal text~{ self contained endnote marker &amp; endnote in one }~ continues
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text[^14] continues
+<p> <br>
+<b>markup example:</b>
+<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> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text [^*] continues
+<p> <br>
+normal text [^**] continues
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>normal text ~[* &nbsp;editors &nbsp;notes, &nbsp;numbered &nbsp;asterisk &nbsp;footnote/endnote &nbsp;series
+&nbsp;]~ continues
+normal text ~[+ &nbsp;editors &nbsp;notes, &nbsp;numbered &nbsp;asterisk &nbsp;footnote/endnote &nbsp;series
+&nbsp;]~ continues
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text [^*3] continues
+<p> <br>
+normal text [^+2] continues
+<p> <br>
+<b>Alternative endnote pair notation for footnotes/endnotes:</b>
+<p> <br>
+<pre>% note the endnote marker "~^"
+normal text~^ continues
+^~ endnote text following the paragraph in which the marker occurs
+</pre>
+<p> <br>
+
+<p>the standard and pair notation cannot be mixed in the same document
+<p>
+<h2><a name='sect30' href='#toc30'>Links</a></h2>
+
+<p>
+
+<h2><a name='sect31' href='#toc31'>Naked Urls Within Text, Dealing with Urls</a></h2>
+
+<p> <br>
+urls found within text are marked up automatically. A url within text is
+automatically hyperlinked to itself and by default decorated with angled
+braces, unless they are contained within a code block (in which case they
+are passed as normal text), or escaped by a preceding underscore (in which
+case the decoration is omitted).
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>normal text http://www.sisudoc.org/ continues
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt; continues
+<p> <br>
+
+<p>An escaped url without decoration
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>normal text _http://www.sisudoc.org/ continues
+deb _http://www.jus.uio.no/sisu/archive unstable main non-free
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+normal text &lt;_<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt; continues
+<p> <br>
+deb &lt;_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a>
+&gt; unstable main non-free
+<p> <br>
+where a code block is used there is neither decoration nor hyperlinking,
+
+<p>code blocks are discussed later in this document
+<p> <br>
+<b>resulting output:</b>
+<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>
+<h2><a name='sect32' href='#toc32'>Linking Text</a></h2>
+
+<p> <br>
+
+<p>To link text or an image to a url the markup is as follows
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>about { SiSU }http://url.org markup
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+aboutSiSU &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt; markup
+<p> <br>
+
+<p>A shortcut notation is available so the url link may also be provided automatically
+
+<p>as a footnote
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>about {~^ SiSU }http://url.org markup
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+aboutSiSU &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt; [^15] markup
+<p> <br>
+Internal document links to a tagged location, including an <i>ocn</i>
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>about { text links }#link_text
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+about ⌠text links⌡⌈link_text⌋
+<p> <br>
+
+<p>Shared document collection link
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>about { SiSU book markup examples }:SiSU/examples.html
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> <br>
+about ⌠ <b>SiSU</b> book markup examples⌡⌈:SiSU/examples.html⌋
+<p>
+<h2><a name='sect33' href='#toc33'>Linking
+Images</a></h2>
+
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>{ tux.png 64x80 }image
+% various url linked images
+{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> <br>
+<b>resulting output:</b>
+<p> <br>
+[ tux.png ]
+<p> <br>
+tux.png 64x80 "Gnu/Linux - a better way" &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt;
+<p> <br>
+GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
+and Ruby" &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt;
+<p> <br>
+ruby_logo.png 70x90 "Ruby" &lt;<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a>
+&gt; [^16]
+<p> <br>
+
+<p><b>linked url footnote shortcut</b>
+<p> <br>
+<pre>{~^ [text &nbsp;to &nbsp;link] }http://url.org
+% maps to: { [text &nbsp;to &nbsp;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> <br>
+<pre>text marker *~name
+</pre>
+<p> <br>
+note at a heading level the same is automatically achieved by providing
+names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
+auto-heading numbering, without further intervention.
+<p>
+<h2><a name='sect34' href='#toc34'>Link Shortcut for
+Multiple Versions of a Sisu Document in the Same Directory</a></h2>
+TREE
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>!_ /{"Viral Spiral"}/, David Bollier
+{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
+</pre>
+<p> <br>
+<b></b> <i>Viral Spiral</i>, David Bollier
+<p> "Viral Spiral", David Bollier &lt;<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a>
+&gt;
+ document manifest &lt;<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a>
+&gt;<br>
+ ⌠html, segmented text⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a>
+<br>
+ ⌠html, scroll, document in one⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a>
+<br>
+ ⌠epub⌡「<a href='http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」'>http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」</a>
+<br>
+ ⌠pdf, landscape⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a>
+<br>
+ ⌠pdf, portrait⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a>
+<br>
+ ⌠odf: odt, open document text⌡「<a href='http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」'>http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」</a>
+<br>
+ ⌠xhtml scroll⌡「<a href='http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」'>http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」</a>
+<br>
+ ⌠xml, sax⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a>
+<br>
+ ⌠xml, dom⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a>
+<br>
+ ⌠concordance⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a>
+<br>
+ ⌠dcc, document content certificate (digests)⌡「<a href='http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」'>http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」</a>
+<br>
+ ⌠markup source text⌡「<a href='http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」'>http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」</a>
+<br>
+ ⌠markup source (zipped) pod⌡「<a href='http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」'>http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」</a>
+<br>
+
+<p>
+<h2><a name='sect35' href='#toc35'>Grouped Text</a></h2>
+
+<p>
+<h2><a name='sect36' href='#toc36'>Tables</a></h2>
+
+<p> <br>
+
+<p>Tables may be prepared in two either of two forms
+<p> <br>
+<b>markup example:</b>
+<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> <br>
+<b>resulting output:</b>
+<p> 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』
+<p> <br>
+
+<p>a second form may be easier to work with in cases where there is not much
+
+<p>information in each column
+<p> <br>
+<b>markup example:</b> [^18]
+<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> <br>
+<b>resulting output:</b>
+<p> <br>
+<b>Table 3.1: Contributors to Wikipedia, January 2001 - June 2005</b>
+<p> |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』
+<p> <br>
+* Contributed at least ten times; ** at least 5 times in last month; ***
+more than 100 times in last month.
+<p>
+<h2><a name='sect37' href='#toc37'>Poem</a></h2>
+
+<p> <br>
+<b>basic markup:</b>
+<p> <br>
+<pre>poem{
+ Your poem here
+}poem
+Each verse in a poem is given an object number.
+</pre>
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>poem{
+ &lsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I&rsquo;ll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I&rsquo;ve
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I&rsquo;ll be
+ judge, I&rsquo;ll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I&rsquo;ll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."&rsquo;
+}poem
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> &lsquo;Fury said to a<br>
+ mouse, That he<br>
+ met in the<br>
+ house,<br>
+ "Let us<br>
+ both go to<br>
+ law: I will<br>
+ prosecute<br>
+ YOU. --Come,<br>
+ I&rsquo;ll take no<br>
+ denial; We<br>
+ must have a<br>
+ trial: For<br>
+ really this<br>
+ morning I&rsquo;ve<br>
+ nothing<br>
+ to do."<br>
+ Said the<br>
+ mouse to the<br>
+ cur, "Such<br>
+ a trial,<br>
+ dear Sir,<br>
+ With<br>
+ no jury<br>
+ or judge,<br>
+ would be<br>
+ wasting<br>
+ our<br>
+ breath."<br>
+ "I&rsquo;ll be<br>
+ judge, I&rsquo;ll<br>
+ be jury,"<br>
+ Said<br>
+ cunning<br>
+ old Fury:<br>
+ "I&rsquo;ll<br>
+ try the<br>
+ whole<br>
+ cause,<br>
+ and<br>
+ condemn<br>
+ you<br>
+ to<br>
+ death."&rsquo;<br>
+
+<p>
+<h2><a name='sect38' href='#toc38'>Group</a></h2>
+
+<p> <br>
+<b>basic markup:</b>
+<p> <br>
+<pre>group{
+ Your grouped text here
+}group
+A group is treated as an object and given a single object number.
+</pre>
+<p> <br>
+<b>markup example:</b>
+<p> <br>
+<pre>group{
+ &lsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I&rsquo;ll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I&rsquo;ve
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I&rsquo;ll be
+ judge, I&rsquo;ll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I&rsquo;ll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."&rsquo;
+}group
+</pre>
+<p> <br>
+<b>resulting output:</b>
+<p> &lsquo;Fury said to a<br>
+ mouse, That he<br>
+ met in the<br>
+ house,<br>
+ "Let us<br>
+ both go to<br>
+ law: I will<br>
+ prosecute<br>
+ YOU. --Come,<br>
+ I&rsquo;ll take no<br>
+ denial; We<br>
+ must have a<br>
+ trial: For<br>
+ really this<br>
+ morning I&rsquo;ve<br>
+ nothing<br>
+ to do."<br>
+ Said the<br>
+ mouse to the<br>
+ cur, "Such<br>
+ a trial,<br>
+ dear Sir,<br>
+ With<br>
+ no jury<br>
+ or judge,<br>
+ would be<br>
+ wasting<br>
+ our<br>
+ breath."<br>
+ "I&rsquo;ll be<br>
+ judge, I&rsquo;ll<br>
+ be jury,"<br>
+ Said<br>
+ cunning<br>
+ old Fury:<br>
+ "I&rsquo;ll<br>
+ try the<br>
+ whole<br>
+ cause,<br>
+ and<br>
+ condemn<br>
+ you<br>
+ to<br>
+ death."&rsquo;<br>
+
+<p>
+<h2><a name='sect39' href='#toc39'>Code</a></h2>
+
+<p> <br>
+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> <br>
+A code-block is treated as an object and given a single object number. [an
+option &nbsp;to &nbsp;number &nbsp;each &nbsp;line &nbsp;of &nbsp;code &nbsp;may &nbsp;be &nbsp;considered &nbsp;at some &nbsp;later &nbsp;time]
+
+<p> <br>
+<b>use of code tags instead of poem compared, resulting output:</b>
+<p> <br>
+<pre> &lsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I&rsquo;ll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I&rsquo;ve
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I&rsquo;ll be
+ judge, I&rsquo;ll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I&rsquo;ll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."&rsquo;
+</pre>
+<p> <br>
+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> <br>
+<pre>1 | &lsquo;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&rsquo;ll take no
+11 | denial; We
+12 | must have a
+13 | trial: For
+14 | really this
+15 | morning I&rsquo;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&rsquo;ll be
+31 | judge, I&rsquo;ll
+32 | be jury,"
+33 | Said
+34 | cunning
+35 | old Fury:
+36 | "I&rsquo;ll
+37 | try the
+38 | whole
+39 | cause,
+40 | and
+41 | condemn
+42 | you
+43 | to
+44 | death."&rsquo;
+</pre>
+<p>
+<h2><a name='sect40' href='#toc40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></h2>
+
+<p>
+<h2><a name='sect41' href='#toc41'>Line-breaks</a></h2>
+
+<p>
+<br>
+To break a line within a "paragraph object", two backslashes \\ with a space
+before and a space or newline after them may be used.
+<p> <br>
+<pre>To break a line within a "paragraph object",
+two backslashes \\ with a space before
+and a space or newline after them \\
+may be used.
+</pre>
+<p> <br>
+The html break br enclosed in angle brackets (though undocumented) is available
+in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
+but is depreciated).
+<p>
+<h2><a name='sect42' href='#toc42'>Page Breaks</a></h2>
+
+<p> <br>
+Page breaks are only relevant and honored in some output formats. A page
+break or a new page may be inserted manually using the following markup
+on a line on its own:
+<p> <br>
+page new =\= or breaks the page, starts a new page.
+<p> <br>
+page break -\- or breaks a column, starts a new column, if using columns,
+else breaks the page, starts a new page.
+<p> <br>
+<pre>-\\-
+or
+&lt;:pb&gt;
+</pre>
+<p> <br>
+
+<p>or
+<p> <br>
+<pre>=\\=
+or
+&lt;:pn&gt;
+</pre>
+<p>
+<h2><a name='sect43' href='#toc43'>Book Index</a></h2>
+
+<p> <br>
+To make an index append to paragraph the book index term relates to it,
+using an equal sign and curly braces.
+<p> <br>
+Currently two levels are provided, a main term and if needed a sub-term.
+Sub-terms are separated from the main term by a colon.
+<p> <br>
+<pre> Paragraph containing main term and sub-term.
+ ={Main term:sub-term}
+</pre>
+<p> <br>
+The index syntax starts on a new line, but there should not be an empty
+line between paragraph and index markup.
+<p> <br>
+The structure of the resulting index would be:
+<p> <br>
+<pre> Main term, 1
+ sub-term, 1
+</pre>
+<p> <br>
+Several terms may relate to a paragraph, they are separated by a semicolon.
+If the term refers to more than one paragraph, indicate the number of paragraphs.
+
+<p> <br>
+<pre> Paragraph containing main term, second term and sub-term.
+ ={first term; second term: sub-term}
+</pre>
+<p> <br>
+The structure of the resulting index would be:
+<p> <br>
+<pre> First term, 1,
+ Second term, 1,
+ sub-term, 1
+</pre>
+<p> <br>
+If multiple sub-terms appear under one paragraph, they are separated under
+the main term heading from each other by a pipe symbol.
+<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> <br>
+The plus one in the example provided indicates the first sub-term spans
+one additional paragraph. The logical structure of the resulting index would
+be:
+<p> <br>
+<pre> Main term, 1,
+ sub-term, 1-3,
+ second sub-term, 1,
+</pre>
+<p>
+<h2><a name='sect44' href='#toc44'>Composite Documents Markup</a></h2>
+<br>
+
+<p> <br>
+It is possible to build a document by creating a master document that requires
+other documents. The documents required may be complete documents that could
+be generated independently, or they could be markup snippets, prepared
+so as to be easily available to be placed within another text. If the calling
+document is a master document (built from other documents), it should be
+named with the suffix <b>.ssm</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) A secondary file of the composite document
+
+<p>is built prior to processing with the same prefix and the suffix <b>._sst</b>
+<p>
+<br>
+
+<p>basic markup for importing a document into a master document
+<p> <br>
+<pre>&lt;&lt; filename1.sst
+&lt;&lt; filename2.ssi
+</pre>
+<p> <br>
+The form described above should be relied on. Within the <i>Vim</i> editor it results
+in the text thus linked becoming hyperlinked to the document it is calling
+in which is convenient for editing.
+<p>
+<h2><a name='sect45' href='#toc45'>Sisu Filetypes</a></h2>
+<br>
+
+<p> <br>
+<b>SiSU</b> has <i>plaintext</i> and binary filetypes, and can process either type of
+document.
+<p>
+<h2><a name='sect46' href='#toc46'>.sst .ssm .ssi Marked Up Plain Text</a></h2>
+
+<p>
+<dl>
+
+<dt><b>SiSU¤b〕 documents are prepared
+as plain-text (utf-8) files with</b> </dt>
+<dd><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 <i>plaintext</i> 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> <br>
+<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> <br>
+<b>SiSU</b> source markup can be shared with the command:
+<p> <br>
+ sisu -s [filename]<br>
+
+<p> </dd>
+</dl>
+
+<h2><a name='sect47' href='#toc47'>Sisu Text - Regular Files (.sst)</a></h2>
+
+<p> <br>
+The most common form of document in <b>SiSU,</b> see the section on <b>SiSU</b> markup.
+
+<p>
+<h2><a name='sect48' href='#toc48'>Sisu Master Files (.ssm)</a></h2>
+
+<p> <br>
+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> <br>
+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> <br>
+Note: Master documents may be prepared in a similar way to regular documents,
+and processing will occur normally if a .sst file is renamed .ssm without
+requiring any other documents; the .ssm marker flags that the document may
+contain other documents.
+<p> <br>
+Note: a secondary file of the composite document is built prior to processing
+with the same prefix and the suffix ._sst [^19]
+<p>
+<h2><a name='sect49' href='#toc49'>Sisu Insert Files (.ssi)</a></h2>
+
+<p>
+<br>
+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>
+<h2><a name='sect50' href='#toc50'>Sisupod, Zipped Binary Container
+(sisupod.zip, .ssp)</a></h2>
+
+<p> <br>
+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>
+<dl>
+
+<dt><b>SiSU</b> </dt>
+<dd><i>plaintext</i> 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> <br>
+The structure of the sisupod is such that it may for example contain a
+single document and its associated images; a master document and its associated
+documents and anything else; or the zipped contents of a whole directory
+of prepared <b>SiSU</b> documents.
+<p> <br>
+The command to create a sisupod is:
+<p> <br>
+ sisu -S [filename]<br>
+
+<p> <br>
+Alternatively, make a pod of the contents of a whole directory:
+<p> <br>
+ sisu -S<br>
+
+<p> <br>
+<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> <br>
+&lt;<a href='http://www.sisudoc.org/sisu/sisu_commands'>http://www.sisudoc.org/sisu/sisu_commands</a>
+&gt;
+<p> <br>
+&lt;<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a>
+&gt;
+<p> </dd>
+</dl>
+
+<h2><a name='sect51' href='#toc51'>Configuration</a></h2>
+<br>
+
+<p>
+<h2><a name='sect52' href='#toc52'>Configuration Files</a></h2>
+
+<p>
+<h2><a name='sect53' href='#toc53'>Config.yml</a></h2>
+
+<p> <br>
+<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> <br>
+The <b>SiSU</b> configuration file is a yaml file, which means indentation is
+significant.
+<p> <br>
+<b>SiSU</b> resource configuration is determined by looking at the following files
+if they exist:
+<p> <br>
+ ./_sisu/v4/sisurc.yml<br>
+
+<p> <br>
+ ./_sisu/sisurc.yml<br>
+
+<p> <br>
+ ~/.sisu/v4/sisurc.yml<br>
+
+<p> <br>
+ ~/.sisu/sisurc.yml<br>
+
+<p> <br>
+ /etc/sisu/v4/sisurc.yml<br>
+
+<p> <br>
+ /etc/sisu/sisurc.yml<br>
+
+<p> <br>
+The search is in the order listed, and the first one found is used.
+<p> <br>
+In the absence of instructions in any of these it falls back to the internal
+program defaults.
+<p> <br>
+Configuration determines the output and processing directories and the
+database access details.
+<p> <br>
+
+<p>If <b>SiSU</b> is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml
+
+<p>
+<h2><a name='sect54' href='#toc54'>Sisu_document_make</a></h2>
+
+<p> <br>
+Most sisu document headers relate to metadata, the exception is the @make:
+header which provides processing related information. The default contents
+of the @make header may be set by placing them in a file sisu_document_make.
+
+<p> <br>
+The search order is as for resource configuration:
+<p> <br>
+ ./_sisu/v4/sisu_document_make<br>
+
+<p> <br>
+ ./_sisu/sisu_document_make<br>
+
+<p> <br>
+ ~/.sisu/v4/sisu_document_make<br>
+
+<p> <br>
+ ~/.sisu/sisu_document_make<br>
+
+<p> <br>
+ /etc/sisu/v4/sisu_document_make<br>
+
+<p> <br>
+ /etc/sisu/sisu_document_make<br>
+
+<p> <br>
+A sample sisu_document_make can be found in the _sisu/ directory under
+along with the provided sisu markup samples.
+<p>
+<h2><a name='sect55' href='#toc55'>Css - Cascading Style Sheets
+(for Html, Xhtml and Xml)</a></h2>
+<br>
+
+<p> <br>
+CSS files to modify the appearance of <b>SiSU</b> html, <i>XHTML</i> or <i>XML</i> 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> <br>
+The basic CSS file for html output is html. css, placing a file of that
+name in directory _sisu/css or equivalent will result in the default file
+of that name being overwritten.
+<p> <br>
+<i>HTML:</i> html. css
+<p> <br>
+<i>XML</i> DOM: dom.css
+<p> <br>
+<i>XML</i> SAX: sax.css
+<p> <br>
+<i>XHTML:</i> xhtml. css
+<p> <br>
+The default homepage may use homepage.css or html. css
+<p> <br>
+Under consideration is to permit the placement of a CSS file with a different
+name in directory _sisu/css directory or equivalent.[^20]
+<p>
+<h2><a name='sect56' href='#toc56'>Organising Content
+- Directory Structure and Mapping</a></h2>
+<br>
+
+<p> <br>
+<b>SiSU</b> v3 has new options for the source directory tree, and output directory
+structures of which there are 3 alternatives.
+<p>
+<h2><a name='sect57' href='#toc57'>Document Source Directory</a></h2>
+
+<p>
+<br>
+The document source directory is the directory in which sisu processing
+commands are given. It contains the sisu source files (.sst .ssm .ssi), or
+(for sisu v3 may contain) subdirectories with language codes which contain
+the sisu source files, so all English files would go in subdirectory en/,
+French in fr/, Spanish in es/ and so on. ISO 639-1 codes are used (as varied
+by po4a). A list of available languages (and possible sub-directory names)
+can be obtained with the command "sisu --help lang" The list of languages
+is limited to langagues supported by XeTeX polyglosia.
+<p>
+<h2><a name='sect58' href='#toc58'>General Directories</a></h2>
+
+<p>
+<br>
+<pre>% files stored at this level e.g. sisu_manual.sst or
+% for sisu v3 may be under language sub-directories
+% e.g.
+ ./subject_name/en
+ ./subject_name/fr
+ ./subject_name/es
+ ./subject_name/_sisu
+ ./subject_name/_sisu/css
+ ./subject_name/_sisu/image
+</pre>
+<p>
+<h2><a name='sect59' href='#toc59'>Document Output Directory Structures</a></h2>
+
+<p>
+<h2><a name='sect60' href='#toc60'>Output Directory Root</a></h2>
+
+<p> <br>
+The output directory root can be set in the sisurc.yml file. Under the root,
+subdirectories are made for each directory in which a document set resides.
+If you have a directory named poems or conventions, that directory will
+be created under the output directory root and the output for all documents
+contained in the directory of a particular name will be generated to subdirectories
+beneath that directory (poem or conventions). A document will be placed
+in a subdirectory of the same name as the document with the filetype identifier
+stripped (.sst .ssm)
+<p> <br>
+The last part of a directory path, representing the sub-directory in which
+a document set resides, is the directory name that will be used for the
+output directory. This has implications for the organisation of document
+collections as it could make sense to place documents of a particular subject,
+or type within a directory identifying them. This grouping as suggested
+could be by subject (sales_law, english_literature); or just as conveniently
+by some other classification (X University). The mapping means it is also
+possible to place in the same output directory documents that are for organisational
+purposes kept separately, for example documents on a given subject of two
+different institutions may be kept in two different directories of the
+same name, under a directory named after each institution, and these would
+be output to the same output directory. Skins could be associated with each
+institution on a directory basis and resulting documents will take on the
+appropriate different appearance.
+<p>
+<h2><a name='sect61' href='#toc61'>Alternative Output Structures</a></h2>
+
+<p> <br>
+There are 3 possibile output structures described as being, by language,
+by filetype or by filename, the selection is made in sisurc.yml
+<p> <br>
+<pre>#% output_dir_structure_by: language; filetype; or filename
+output_dir_structure_by: language #(language &amp; filetype, preferred?)
+#output_dir_structure_by: filetype
+#output_dir_structure_by: filename #(default, closest to original v1 &amp;
+v2)
+</pre>
+<p>
+<h2><a name='sect62' href='#toc62'>by Language</a></h2>
+
+<p> <br>
+
+<p>The by language directory structure places output files
+<p> <br>
+The by language directory structure separates output files by language
+code (all files of a given language), and within the language directory
+by filetype.
+<p> <br>
+
+<p>Its selection is configured in sisurc.yml
+<p> <br>
+output_dir_structure_by: language
+<p> <br>
+<pre> |-- en
+ |-- epub
+ |-- hashes
+ |-- html
+ | |-- viral_spiral.david_bollier
+ | |-- manifest
+ | |-- qrcode
+ | |-- odt
+ | |-- pdf
+ | |-- sitemaps
+ | |-- txt
+ | |-- xhtml
+ | &lsquo;-- xml
+ |-- po4a
+ | &lsquo;-- live-manual
+ | |-- po
+ | |-- fr
+ | &lsquo;-- pot
+ &lsquo;-- _sisu
+ |-- css
+ |-- image
+ |-- image_sys -&gt; ../../_sisu/image_sys
+ &lsquo;-- xml
+ |-- rnc
+ |-- rng
+ &lsquo;-- xsd
+</pre>
+<p> <br>
+#by: language subject_dir/en/manifest/filename.html
+<p>
+<h2><a name='sect63' href='#toc63'>by Filetype</a></h2>
+
+<p> <br>
+The by filetype directory structure separates output files by filetype,
+all html files in one directory pdfs in another and so on. Filenames are
+given a language extension.
+<p> <br>
+
+<p>Its selection is configured in sisurc.yml
+<p> <br>
+output_dir_structure_by: filetype
+<p> <br>
+<pre> |-- epub
+ |-- hashes
+ |-- html
+ |-- viral_spiral.david_bollier
+ |-- manifest
+ |-- qrcode
+ |-- odt
+ |-- pdf
+ |-- po4a
+ |-- live-manual
+ | |-- po
+ | |-- fr
+ | &lsquo;-- pot
+ |-- _sisu
+ | |-- css
+ | |-- image
+ | |-- image_sys -&gt; ../../_sisu/image_sys
+ | &lsquo;-- xml
+ | |-- rnc
+ | |-- rng
+ | &lsquo;-- xsd
+ |-- sitemaps
+ |-- txt
+ |-- xhtml
+ &lsquo;-- xml
+</pre>
+<p> <br>
+#by: filetype subject_dir/html/filename/manifest.en.html
+<p>
+<h2><a name='sect64' href='#toc64'>by Filename</a></h2>
+
+<p> <br>
+The by filename directory structure places most output of a particular
+file (the different filetypes) in a common directory.
+<p> <br>
+
+<p>Its selection is configured in sisurc.yml
+<p> <br>
+output_dir_structure_by: filename
+<p> <br>
+<pre> |-- epub
+ |-- po4a
+ |-- live-manual
+ | |-- po
+ | |-- fr
+ | &lsquo;-- pot
+ |-- _sisu
+ | |-- css
+ | |-- image
+ | |-- image_sys -&gt; ../../_sisu/image_sys
+ | &lsquo;-- xml
+ | |-- rnc
+ | |-- rng
+ | &lsquo;-- xsd
+ |-- sitemaps
+ |-- src
+ |-- pod
+ &lsquo;-- viral_spiral.david_bollier
+</pre>
+<p> <br>
+#by: filename subject_dir/filename/manifest.en.html
+<p>
+<h2><a name='sect65' href='#toc65'>Remote Directories</a></h2>
+
+<p> <br>
+<pre>% containing sub_directories named after the generated files from which
+they are made
+ ./subject_name/src
+% contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip
+ ./subject_name/_sisu
+% configuration file e.g. sisurc.yml
+ ./subject_name/_sisu/skin
+% skins in various skin directories doc, dir, site, yml
+ ./subject_name/_sisu/css
+ ./subject_name/_sisu/image
+% images for documents contained in this directory
+ ./subject_name/_sisu/mm
+</pre>
+<p>
+<h2><a name='sect66' href='#toc66'>Sisupod</a></h2>
+
+<p> <br>
+<pre>% files stored at this level e.g. sisu_manual.sst
+ ./sisupod/_sisu
+% configuration file e.g. sisurc.yml
+ ./sisupod/_sisu/skin
+% skins in various skin directories doc, dir, site, yml
+ ./sisupod/_sisu/css
+ ./sisupod/_sisu/image
+% images for documents contained in this directory
+ ./sisupod/_sisu/mm
+</pre>
+<p>
+<h2><a name='sect67' href='#toc67'>Organising Content</a></h2>
+
+<p>
+<h2><a name='sect68' href='#toc68'>Homepages</a></h2>
+<br>
+
+<p> <br>
+<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> More accurately, <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&rsquo;s configuration, these being:
+<p> <br>
+1. through placing your home page and other custom built documents in the
+subdirectory _sisu/home/ (this probably being the easier and more convenient
+option)
+<p> <br>
+2. through providing what you want as the home page in a skin,
+<p> <br>
+Document sets are contained in directories, usually organised by site or
+subject. Each directory can/should have its own homepage. See the section
+on directory structure and organisation of content.
+<p>
+<h2><a name='sect69' href='#toc69'>Home Page and Other
+Custom Built Pages in a Sub-directory</a></h2>
+
+<p> <br>
+Custom built pages, including the home page index.html may be placed within
+the configuration directory _sisu/home/ in any of the locations that is
+searched for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu
+From there they are copied to the root of the output directory with the
+command:
+<p> <br>
+ sisu -CC<br>
+
+<p>
+<h2><a name='sect70' href='#toc70'>Markup and Output Examples</a></h2>
+<br>
+
+<p>
+<h2><a name='sect71' href='#toc71'>Markup Examples</a></h2>
+
+<p> <br>
+Current markup examples and document output samples are provided off &lt;<a href='http://sisudoc.org'>http://sisudoc.org</a>
+&gt;
+or &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt; and in the sisu -markup-sample package available
+off &lt;<a href='http://sources.sisudoc.org'>http://sources.sisudoc.org</a>
+&gt;
+<p> <br>
+For some documents hardly any markup at all is required at all, other than
+a header, and an indication that the levels to be taken into account by
+the program in generating its output are.
+<p>
+<h2><a name='sect72' href='#toc72'>Sisu Markup Samples</a></h2>
+
+<p> <br>
+A few additional sample books prepared as sisu markup samples, output formats
+to be generated using <b>SiSU</b> are contained in a separate package sisu -markup-samples.
+sisu -markup-samples contains books (prepared using sisu markup), that were
+released by their authors various licenses mostly different Creative Commons
+licences that do not permit inclusion in the <b>Debian</b> Project as they have
+requirements that do not meet the <b>Debian</b> Free Software Guidelines for various
+reasons, most commonly that they require that the original substantive
+text remain unchanged, and sometimes that the works be used only non-commercially.
+
+<p> <br>
+<i>Accelerando,</i> Charles Stross (2005) accelerando.charles_stross.sst
+<p> <br>
+<i>Alice&rsquo;s</i> Adventures in Wonderland, Lewis Carroll (1865) alices_adventures_in_wonderland.lewis_carroll.sst
+
+<p> <br>
+<i>CONTENT,</i> Cory Doctorow (2008) content.cory_doctorow.sst
+<p> <br>
+<i>Democratizing</i> Innovation, Eric von Hippel (2005) democratizing_innovation.eric_von_hippel.sst
+
+<p> <br>
+<i>Down</i> and Out in the Magic Kingdom, Cory Doctorow (2003) down_and_out_in_the_magic_kingdom.cory_doctorow.sst
+
+<p> <br>
+<i>For</i> the Win, Cory Doctorow (2010) for_the_win.cory_doctorow.sst
+<p> <br>
+<i>Free</i> as in Freedom - Richard Stallman&rsquo;s Crusade for Free Software, Sam Williams
+(2002) free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst
+
+<p> <br>
+<i>Free</i> as in Freedom 2.0 - Richard Stallman and the Free Software Revolution,
+Sam Williams (2002), Richard M. Stallman (2010) free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst
+
+<p> <br>
+<i>Free</i> Culture - How Big Media Uses Technology and the Law to Lock Down Culture
+and Control Creativity, Lawrence Lessig (2004) free_culture.lawrence_lessig.sst
+
+<p> <br>
+<i>Free</i> For All - How Linux and the Free Software Movement Undercut the High
+Tech Titans, Peter Wayner (2002) free_for_all.peter_wayner.sst
+<p> <br>
+<i>GNU</i> GENERAL PUBLIC LICENSE v2, Free Software Foundation (1991) gpl2.fsf.sst
+
+<p> <br>
+<i>GNU</i> GENERAL PUBLIC LICENSE v3, Free Software Foundation (2007) gpl3.fsf.sst
+
+<p> <br>
+<i>Gulliver&rsquo;s</i> Travels, Jonathan Swift (1726 / 1735) gullivers_travels.jonathan_swift.sst
+
+<p> <br>
+<i>Little</i> Brother, Cory Doctorow (2008) little_brother.cory_doctorow.sst
+<p> <br>
+<i>The</i> Cathederal and the Bazaar, Eric Raymond (2000) the_cathedral_and_the_bazaar.eric_s_raymond.sst
+
+<p> <br>
+<i>The</i> Public Domain - Enclosing the Commons of the Mind, James Boyle (2008)
+
+<p>the_public_domain.james_boyle.sst
+<p> <br>
+<i>The</i> Wealth of Networks - How Social Production Transforms Markets and Freedom,
+Yochai Benkler (2006) the_wealth_of_networks.yochai_benkler.sst
+<p> <br>
+<i>Through</i> the Looking Glass, Lewis Carroll (1871) through_the_looking_glass.lewis_carroll.sst
+
+<p> <br>
+<i>Two</i> Bits - The Cultural Significance of Free Software, Christopher Kelty
+(2008) two_bits.christopher_kelty.sst
+<p> <br>
+<i>UN</i> Contracts for International Sale of Goods, UN (1980) un_contracts_international_sale_of_goods_convention_1980.sst
+
+<p> <br>
+<i>Viral</i> Spiral, David Bollier (2008) viral_spiral.david_bollier.sst
+<p>
+<h2><a name='sect73' href='#toc73'>Sisu Search
+- Introduction</a></h2>
+<br>
+
+<p> <br>
+<b>SiSU</b> output can easily and conveniently be indexed by a number of standalone
+indexing tools, such as Lucene, Hyperestraier.
+<p> <br>
+Because the document structure of sites created is clearly defined, and
+the text <i>object</i> 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> <br>
+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>
+<h2><a name='sect74' href='#toc74'>Sql</a></h2>
+<br>
+
+<p>
+<h2><a name='sect75' href='#toc75'>Populating Sql Type Databases</a></h2>
+
+<p> <br>
+<b>SiSU</b> feeds sisu markupd documents into sql type databases <i>PostgreSQL</i> [^21]
+and/or <i>SQLite</i> [^22] database together with information related to document
+structure.
+<p> <br>
+This is one of the more interesting output forms, as all the structural
+data of the documents are retained (though can be ignored by the user of
+the database should they so choose). All site texts/documents are (currently)
+streamed to four tables:
+<p> <br>
+ * one containing semantic (and other) headers, including, title, author,<br>
+ subject, (the<br>
+ .I Dublin Core.<br>
+ ..);<br>
+
+<p> <br>
+ * 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> <br>
+ * 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> <br>
+ * 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<br>
+ .I ascii.<br>
+
+<p> <br>
+There is of course the possibility to add further structures.
+<p> <br>
+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> <br>
+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> As individual text objects of a document stored (and indexed) together
+with object numbers, and all versions of the document have the same numbering,
+complex searches can be tailored to return just the locations of the search
+results relevant for all available output formats, with live links to the
+precise locations in the database or in html/xml documents; or, the structural
+information provided makes it possible to search the full contents of the
+database and have headings in which search content appears, or to search
+only headings etc. (as the <i>Dublin</i> Core is incorporated it is easy to make
+use of that as well).
+<p>
+<h2><a name='sect76' href='#toc76'>Postgresql</a></h2>
+<br>
+
+<p>
+<h2><a name='sect77' href='#toc77'>Name</a></h2>
+
+<p> <br>
+<b>SiSU</b> - Structured information, Serialized Units - a document publishing system,
+
+<p>postgresql dependency package
+<p>
+<h2><a name='sect78' href='#toc78'>Description</a></h2>
+
+<p> <br>
+Information related to using postgresql with sisu (and related to the sisu_postgresql
+dependency package, which is a dummy package to install dependencies needed
+for <b>SiSU</b> to populate a postgresql database, this being part of <b>SiSU</b> - man
+sisu) .
+<p>
+<h2><a name='sect79' href='#toc79'>Synopsis</a></h2>
+
+<p> <br>
+ sisu -D [instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
+
+<p> <br>
+ sisu -D --pg --[instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
+
+<p>
+<h2><a name='sect80' href='#toc80'>Commands</a></h2>
+
+<p> <br>
+Mappings to two databases are provided by default, postgresql and sqlite,
+the same commands are used within sisu to construct and populate databases
+however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
+
+<p>alternatively --sqlite or --pgsql may be used
+<p> <br>
+<b>-D or --pgsql</b> may be used interchangeably.
+<p>
+<h2><a name='sect81' href='#toc81'>Create and Destroy Database</a></h2>
+
+<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>creates database where no database existed before
+<p> </dd>
+
+<dt><b>sisu -D --create</b>
+</dt>
+<dd>
+<p>creates 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>
+
+<h2><a name='sect82' href='#toc82'>Import and Remove Documents</a></h2>
+
+<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 in database
+
+<p> </dd>
+
+<dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt>
+<dd>removes specified document from postgresql
+database.
+<p> </dd>
+</dl>
+
+<h2><a name='sect83' href='#toc83'>Sqlite</a></h2>
+<br>
+
+<p>
+<h2><a name='sect84' href='#toc84'>Name</a></h2>
+
+<p> <br>
+<b>SiSU</b> - Structured information, Serialized Units - a document publishing system.
+
+<p>
+<h2><a name='sect85' href='#toc85'>Description</a></h2>
+
+<p> <br>
+Information related to using sqlite with sisu (and related to the sisu_sqlite
+dependency package, which is a dummy package to install dependencies needed
+for <b>SiSU</b> to populate an sqlite database, this being part of <b>SiSU</b> - man sisu)
+.
+<p>
+<h2><a name='sect86' href='#toc86'>Synopsis</a></h2>
+
+<p> <br>
+ sisu -d [instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
+
+<p> <br>
+ sisu -d --(sqlite|pg) --[instruction] [filename/wildcard &nbsp;if <br>
+ required]<br>
+
+<p>
+<h2><a name='sect87' href='#toc87'>Commands</a></h2>
+
+<p> <br>
+Mappings to two databases are provided by default, postgresql and sqlite,
+the same commands are used within sisu to construct and populate databases
+however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
+
+<p>alternatively --sqlite or --pgsql may be used
+<p> <br>
+<b>-d or --sqlite</b> may be used interchangeably.
+<p>
+<h2><a name='sect88' href='#toc88'>Create and Destroy Database</a></h2>
+
+<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>
+
+<h2><a name='sect89' href='#toc89'>Import and Remove Documents</a></h2>
+
+<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>
+
+<h2><a name='sect90' href='#toc90'>Introduction</a></h2>
+<br>
+
+<p>
+<h2><a name='sect91' href='#toc91'>Search - Database Frontend Sample, Utilising Database and Sisu Features,</a></h2>
+INCLUDING
+OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
+<p> <br>
+Sample search frontend &lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
+&gt; [^23] 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.[^24]
+<p> <br>
+<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 <i>object</i> citation numbering, which includes
+html, <i>XML,</i> <i>EPUB,</i> <i>LaTeX,</i> <i>PDF</i> and indeed the <i>SQL</i> database. You can then refer
+to one of the other outputs or in the <i>SQL</i> database expand the text within
+the matched objects (paragraphs) in the documents matched.
+<p> <br>
+Note you may set results either for documents matched and object number
+locations within each matched document meeting the search criteria; or
+display the names of the documents matched along with the objects (paragraphs)
+that meet the search criteria.[^25]
+<p>
+<dl>
+
+<dt><b>sisu -F --webserv-webrick</b> </dt>
+<dd>builds a cgi web
+
+<p>search frontend for the database created
+<p> <br>
+The following is feedback on the setup on a machine provided by the help
+command:
+<p> <br>
+ sisu --help sql<br>
+
+<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> <br>
+
+<p>Note on databases built
+<p> <br>
+By default, [unless &nbsp;otherwise &nbsp;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 &nbsp;a &nbsp;manual &nbsp;mapping &nbsp;for &nbsp;the &nbsp;collection &nbsp;is
+<p> </dd>
+</dl>
+
+<h2><a name='sect92' href='#toc92'>Search
+Form</a></h2>
+
+<p>
+<dl>
+
+<dt><b>sisu -F</b> </dt>
+<dd>generates a sample search form, which must be copied to the
+
+<p>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 to the web-server
+
+<p>cgi directory
+<p> </dd>
+
+<dt><b>sisu -W</b> </dt>
+<dd>starts the webrick server which should be available
+
+<p>wherever sisu is properly installed
+<p> <br>
+
+<p>The generated search form must be copied manually to the webserver directory
+
+<p>as instructed
+<p> </dd>
+</dl>
+
+<h2><a name='sect93' href='#toc93'>Sisu_webrick</a></h2>
+<br>
+
+<p>
+<h2><a name='sect94' href='#toc94'>Name</a></h2>
+
+<p> <br>
+<b>SiSU</b> - Structured information, Serialized Units - a document publishing system
+
+<p>
+<h2><a name='sect95' href='#toc95'>Synopsis</a></h2>
+
+<p> <br>
+sisu_webrick [port]
+<p> <br>
+
+<p>or
+<p> <br>
+sisu -W [port]
+<p>
+<h2><a name='sect96' href='#toc96'>Description</a></h2>
+
+<p> <br>
+sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick 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> <br>
+The default port for sisu_webrick is set to 8081, this may be modified
+in the yaml file: ~/.sisu/sisurc.yml a sample of which is provided as /etc/sisu/sisurc.yml
+(or in the equivalent directory on your system).
+<p>
+<h2><a name='sect97' href='#toc97'>Summary of Man Page</a></h2>
+
+<p> <br>
+sisu_webrick, may be started on it&rsquo;s own with the command: sisu_webrick
+[port] or using the sisu command with the -W flag: sisu -W [port]
+<p> <br>
+
+<p>where no port is given and settings are unchanged the default port is 8081
+
+<p>
+<h2><a name='sect98' href='#toc98'>Document Processing Command Flags</a></h2>
+
+<p> <br>
+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>
+<h2><a name='sect99' href='#toc99'>Summary of Features</a></h2>
+<br>
+
+<p> <br>
+* sparse/minimal markup (clean utf-8 source texts). Documents are prepared
+in a single <i>UTF-8</i> file using a minimalistic mnemonic syntax. Typical literature,
+documents like "War and Peace" require almost no markup, and most of the
+headers are optional.
+<p> <br>
+* markup is easily readable/parsable by the human eye, (basic markup is
+simpler and more sparse than the most basic <i>HTML</i> ) , [this &nbsp;may &nbsp;also &nbsp;be
+&nbsp;converted &nbsp;to &nbsp;.I &nbsp;XML &nbsp;representations &nbsp;of &nbsp;the &nbsp;same &nbsp;input/source &nbsp;document].
+<p>
+<br>
+* markup defines document structure (this may be done once in a header
+pattern-match description, or for heading levels individually); basic text
+attributes (bold, italics, underscore, strike-through etc.) as required;
+and semantic information related to the document (header information, extended
+beyond the Dublin core and easily further extended as required); the headers
+may also contain processing instructions. <b>SiSU</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 &nbsp;that &nbsp;browser viewing, &nbsp;paper &nbsp;publication,
+&nbsp;sql &nbsp;search &nbsp;etc.] (html, epub, xml, odf, latex, pdf, sql)
+<p> <br>
+* for output produces reasonably elegant output of established industry
+and institutionally accepted open standard formats.[3] takes advantage of
+the different strengths of various standard formats for representing documents,
+amongst the output formats currently supported are:
+<p> <br>
+* <i>HTML</i> - both as a single scrollable text and a segmented document
+<p> <br>
+* <i>XHTML</i>
+<p> <br>
+* <i>EPUB</i>
+<p> <br>
+* <i>XML</i> - both in sax and dom style xml structures for further development
+
+<p>as required
+<p> <br>
+* <i>ODT</i> - Open Document Format text, the iso standard for document storage
+
+<p> <br>
+* <i>LaTeX</i> - used to generate pdf
+<p> <br>
+* <i>PDF</i> (via <i>LaTeX</i> )
+<p> <br>
+* <i>SQL</i> - population of an sql database ( <i>PostgreSQL</i> or <i>SQLite</i> ) , (at the
+same object level that is used to cite text within a document)
+<p> <br>
+Also produces: concordance files; document content certificates (md5 or
+sha256 digests of headings, paragraphs, images etc.) and html manifests
+(and sitemaps of content). (b) takes advantage of the strengths implicit
+in these very different output types, (e.g. PDFs produced using typesetting
+of <i>LaTeX,</i> databases populated with documents at an individual object/paragraph
+level, making possible <i>granular</i> search (and related possibilities))
+<p> <br>
+* ensuring content can be cited in a meaningful way regardless of selected
+output format. Online publishing (and publishing in multiple document formats)
+lacks a useful way of citing text internally within documents (important
+to academics generally and to lawyers) as page numbers are meaningless
+across browsers and formats. sisu seeks to provide a common way of pinpoint
+the text within a document, (which can be utilized for citation and by
+search engines). The outputs share a common numbering system that is meaningful
+(to man and machine) across all digital outputs whether paper, screen,
+or database oriented, (pdf, <i>HTML,</i> <i>EPUB,</i> xml, sqlite, postgresql) , this
+numbering system can be used to reference content.
+<p> <br>
+* Granular search within documents. <i>SQL</i> 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 &nbsp;indexing &nbsp;also &nbsp;work
+<p> <br>
+* long term maintainability of document collections in a world of changing
+formats, having a very sparsely marked-up source document base. there is
+a considerable degree of future-proofing, output representations are "upgradeable",
+and new document formats may be added. e.g. addition of odf (open document
+text) module in 2006, epub in 2009 and in future html5 output sometime
+in future, without modification of existing prepared texts
+<p> <br>
+* <i>SQL</i> search aside, documents are generated as required and static once
+generated.
+<p> <br>
+* documents produced are static files, and may be batch processed, this
+needs to be done only once but may be repeated for various reasons as desired
+(updated content, addition of new output formats, updated technology document
+presentations/representations)
+<p> <br>
+* document source ( <i>plaintext</i> utf-8) if shared on the net may be used as
+
+<p>input and processed locally to produce the different document outputs
+<p>
+<br>
+* document source may be bundled together (automatically) with associated
+documents (multiple language versions or master document with inclusions)
+and images and sent as a zip file called a sisupod, if shared on the net
+
+<p>these too may be processed locally to produce the desired document outputs
+
+<p> <br>
+* generated document outputs may automatically be posted to remote sites.
+
+<p> <br>
+* for basic document generation, the only software dependency is <b>Ruby,</b>
+and a few standard Unix tools (this covers <i>plaintext,</i> <i>HTML,</i> <i>EPUB,</i> <i>XML,</i>
+<i>ODF,</i> <i>LaTeX</i> ) . To use a database you of course need that, and to convert
+the <i>LaTeX</i> generated to pdf, a latex processor like tetex or texlive.
+<p> <br>
+* as a developers tool it is flexible and extensible
+<p> <br>
+Syntax highlighting for <b>SiSU</b> markup is available for a number of text editors.
+
+<p> <br>
+<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> <br>
+i.e. to be able to take advantage from this minimal preparation starting
+point of some of the strengths of rather different established ways of
+representing documents for different purposes, whether for search (relational
+database, or indexed flat files generated for that purpose whether of complete
+documents, or say of files made up of objects), online viewing (e.g. html,
+xml, pdf) , or paper publication (e.g. pdf) ...
+<p> <br>
+the solution arrived at is by extracting structural information about the
+document (about headings within the document) and by tracking objects (which
+are serialized and also given hash values) in the manner described. It makes
+possible representations that are quite different from those offered at
+present. For example objects could be saved individually and identified
+by their hashes, with an index of how the objects relate to each other
+to form a document.
+<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.
+<p> <br>
+</li><b>.</b><li>i.e. the
+<p> <br>
+<i>HTML,</i>
+<p> <br>
+<i>PDF,</i>
+<p> <br>
+<i>EPUB,</i>
+<p> <br>
+
+<p><i>ODT</i>
+<p> <br>
+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> <br>
+</li><b>.</b><li>
+<p>the different heading levels
+<p> <br>
+</li><b>.</b><li>units of text, primarily paragraphs and headings, also any tables, poems,
+
+<p>code-blocks
+<p> <br>
+</li><b>.</b><li>
+<p>An open standard format for e-books
+<p> <br>
+</li><b>.</b><li>Open Document Format (
+<p> <br>
+
+<p><i>ODF</i>
+<p> <br>
+) text
+<p> <br>
+</li><b>.</b><li>
+<p>Specification submitted by Adobe to ISO to become a full open ISO specification
+
+<p> <br>
+&lt;<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>
+<p>ISO standard ISO/IEC 26300:2006
+<p> <br>
+</dd>
+
+<dt><b>*1.</b> </dt>
+<dd>square brackets
+<p> <br>
+</dd>
+
+<dt><b>*2.</b> </dt>
+<dd>square brackets
+<p> <br>
+</dd>
+
+<dt><b>+1.</b> </dt>
+<dd>square brackets
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a>
+&gt;
+<p> <br>
+</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.
+<p> <br>
+</li><b>.</b><li>
+<p>files should be prepared using
+<p> <br>
+
+<p><i>UTF-8</i>
+<p> <br>
+
+<p>character encoding
+<p> <br>
+</li><b>.</b><li>
+<p>a footnote or endnote
+<p> <br>
+</li><b>.</b><li>self contained endnote marker &amp; endnote in one
+<p> <br>
+</dd>
+
+<dt><b>*.</b> </dt>
+<dd>unnumbered asterisk footnote/endnote, insert multiple asterisks if required
+
+<p> <br>
+</dd>
+
+<dt><b>**.</b> </dt>
+<dd>another unnumbered asterisk footnote/endnote
+<p> <br>
+</dd>
+
+<dt><b>*3.</b> </dt>
+<dd>editors notes, numbered asterisk footnote/endnote series
+<p> <br>
+</dd>
+
+<dt><b>+2.</b> </dt>
+<dd>editors notes, numbered asterisk footnote/endnote series
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>
+<p>Table from the Wealth of Networks by Yochai Benkler
+<p> <br>
+&lt;<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>
+&gt;
+<p> <br>
+</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.
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a>
+&gt;
+<p> <br>
+&lt;<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a>
+&gt;
+<p> <br>
+&lt;<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a>
+&gt;
+<p> <br>
+&lt;<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a>
+&gt;
+<p> <br>
+</li><b>.</b><li>&lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
+&gt;
+<p> <br>
+</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.
+<p> <br>
+</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.
+<p> <br>
+
+<p> </li>
+</ol>
+
+<h2><a name='sect100' href='#toc100'>See Also</a></h2>
+ <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-epub:1'>sisu-epub(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-harvest:1'>sisu-harvest(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-html:1'>sisu-html(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-odf:1'>sisu-odf(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-pdf:1'>sisu-pdf(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-pg:1'>sisu-pg(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-sqlite:1'>sisu-sqlite(1)</a>
+,<br>
+ <a href='http:~/bin/man2html?sisu-txt:1'>sisu-txt(1)</a>
+.<br>
+ <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a>
+<br>
+
+<h2><a name='sect101' href='#toc101'>Homepage</a></h2>
+ More information about SiSU can be found at &lt;<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a>
+&gt;
+or &lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
+&gt;<br>
+
+<h2><a name='sect102' href='#toc102'>Source</a></h2>
+ &lt;<a href='http://sources.sisudoc.org/'>http://sources.sisudoc.org/</a>
+&gt;<br>
+
+<h2><a name='sect103' href='#toc103'>Author</a></h2>
+ SiSU is written by Ralph Amissah &lt;ralph@amissah.com&gt;<br>
+ <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'>Sisu - Manual,</a></li>
+<li><a name='toc3' href='#sect3'>What is Sisu?</a></li>
+<li><a name='toc4' href='#sect4'>Introduction - What is Sisu?</a></li>
+<li><a name='toc5' href='#sect5'>Commands Summary</a></li>
+<li><a name='toc6' href='#sect6'>Description</a></li>
+<li><a name='toc7' href='#sect7'>Document Processing Command Flags</a></li>
+<li><a name='toc8' href='#sect8'>Command Line Modifiers</a></li>
+<li><a name='toc9' href='#sect9'>Database Commands</a></li>
+<li><a name='toc10' href='#sect10'>Shortcuts, Shorthand for Multiple Flags</a></li>
+<li><a name='toc11' href='#sect11'>Command Line with Flags - Batch Processing</a></li>
+<li><a name='toc12' href='#sect12'>Help</a></li>
+<li><a name='toc13' href='#sect13'>Sisu Manual</a></li>
+<li><a name='toc14' href='#sect14'>Sisu Man Pages</a></li>
+<li><a name='toc15' href='#sect15'>Sisu Built-in Interactive Help</a></li>
+<li><a name='toc16' href='#sect16'>Introduction to Sisu Markup[^11]</a></li>
+<li><a name='toc17' href='#sect17'>Summary</a></li>
+<li><a name='toc18' href='#sect18'>Markup Examples</a></li>
+<li><a name='toc19' href='#sect19'>Online</a></li>
+<li><a name='toc20' href='#sect20'>Installed</a></li>
+<li><a name='toc21' href='#sect21'>Markup of Headers</a></li>
+<li><a name='toc22' href='#sect22'>Sample Header</a></li>
+<li><a name='toc23' href='#sect23'>Available Headers</a></li>
+<li><a name='toc24' href='#sect24'>Markup of Substantive Text</a></li>
+<li><a name='toc25' href='#sect25'>Heading Levels</a></li>
+<li><a name='toc26' href='#sect26'>Font Attributes</a></li>
+<li><a name='toc27' href='#sect27'>Indentation and Bullets</a></li>
+<li><a name='toc28' href='#sect28'>Hanging Indents</a></li>
+<li><a name='toc29' href='#sect29'>Footnotes / Endnotes</a></li>
+<li><a name='toc30' href='#sect30'>Links</a></li>
+<li><a name='toc31' href='#sect31'>Naked Urls Within Text, Dealing with Urls</a></li>
+<li><a name='toc32' href='#sect32'>Linking Text</a></li>
+<li><a name='toc33' href='#sect33'>Linking Images</a></li>
+<li><a name='toc34' href='#sect34'>Link Shortcut for Multiple Versions of a Sisu Document in the Same Directory</a></li>
+<li><a name='toc35' href='#sect35'>Grouped Text</a></li>
+<li><a name='toc36' href='#sect36'>Tables</a></li>
+<li><a name='toc37' href='#sect37'>Poem</a></li>
+<li><a name='toc38' href='#sect38'>Group</a></li>
+<li><a name='toc39' href='#sect39'>Code</a></li>
+<li><a name='toc40' href='#sect40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></li>
+<li><a name='toc41' href='#sect41'>Line-breaks</a></li>
+<li><a name='toc42' href='#sect42'>Page Breaks</a></li>
+<li><a name='toc43' href='#sect43'>Book Index</a></li>
+<li><a name='toc44' href='#sect44'>Composite Documents Markup</a></li>
+<li><a name='toc45' href='#sect45'>Sisu Filetypes</a></li>
+<li><a name='toc46' href='#sect46'>.sst .ssm .ssi Marked Up Plain Text</a></li>
+<li><a name='toc47' href='#sect47'>Sisu Text - Regular Files (.sst)</a></li>
+<li><a name='toc48' href='#sect48'>Sisu Master Files (.ssm)</a></li>
+<li><a name='toc49' href='#sect49'>Sisu Insert Files (.ssi)</a></li>
+<li><a name='toc50' href='#sect50'>Sisupod, Zipped Binary Container (sisupod.zip, .ssp)</a></li>
+<li><a name='toc51' href='#sect51'>Configuration</a></li>
+<li><a name='toc52' href='#sect52'>Configuration Files</a></li>
+<li><a name='toc53' href='#sect53'>Config.yml</a></li>
+<li><a name='toc54' href='#sect54'>Sisu_document_make</a></li>
+<li><a name='toc55' href='#sect55'>Css - Cascading Style Sheets (for Html, Xhtml and Xml)</a></li>
+<li><a name='toc56' href='#sect56'>Organising Content - Directory Structure and Mapping</a></li>
+<li><a name='toc57' href='#sect57'>Document Source Directory</a></li>
+<li><a name='toc58' href='#sect58'>General Directories</a></li>
+<li><a name='toc59' href='#sect59'>Document Output Directory Structures</a></li>
+<li><a name='toc60' href='#sect60'>Output Directory Root</a></li>
+<li><a name='toc61' href='#sect61'>Alternative Output Structures</a></li>
+<li><a name='toc62' href='#sect62'>by Language</a></li>
+<li><a name='toc63' href='#sect63'>by Filetype</a></li>
+<li><a name='toc64' href='#sect64'>by Filename</a></li>
+<li><a name='toc65' href='#sect65'>Remote Directories</a></li>
+<li><a name='toc66' href='#sect66'>Sisupod</a></li>
+<li><a name='toc67' href='#sect67'>Organising Content</a></li>
+<li><a name='toc68' href='#sect68'>Homepages</a></li>
+<li><a name='toc69' href='#sect69'>Home Page and Other Custom Built Pages in a Sub-directory</a></li>
+<li><a name='toc70' href='#sect70'>Markup and Output Examples</a></li>
+<li><a name='toc71' href='#sect71'>Markup Examples</a></li>
+<li><a name='toc72' href='#sect72'>Sisu Markup Samples</a></li>
+<li><a name='toc73' href='#sect73'>Sisu Search - Introduction</a></li>
+<li><a name='toc74' href='#sect74'>Sql</a></li>
+<li><a name='toc75' href='#sect75'>Populating Sql Type Databases</a></li>
+<li><a name='toc76' href='#sect76'>Postgresql</a></li>
+<li><a name='toc77' href='#sect77'>Name</a></li>
+<li><a name='toc78' href='#sect78'>Description</a></li>
+<li><a name='toc79' href='#sect79'>Synopsis</a></li>
+<li><a name='toc80' href='#sect80'>Commands</a></li>
+<li><a name='toc81' href='#sect81'>Create and Destroy Database</a></li>
+<li><a name='toc82' href='#sect82'>Import and Remove Documents</a></li>
+<li><a name='toc83' href='#sect83'>Sqlite</a></li>
+<li><a name='toc84' href='#sect84'>Name</a></li>
+<li><a name='toc85' href='#sect85'>Description</a></li>
+<li><a name='toc86' href='#sect86'>Synopsis</a></li>
+<li><a name='toc87' href='#sect87'>Commands</a></li>
+<li><a name='toc88' href='#sect88'>Create and Destroy Database</a></li>
+<li><a name='toc89' href='#sect89'>Import and Remove Documents</a></li>
+<li><a name='toc90' href='#sect90'>Introduction</a></li>
+<li><a name='toc91' href='#sect91'>Search - Database Frontend Sample, Utilising Database and Sisu Features,</a></li>
+<li><a name='toc92' href='#sect92'>Search Form</a></li>
+<li><a name='toc93' href='#sect93'>Sisu_webrick</a></li>
+<li><a name='toc94' href='#sect94'>Name</a></li>
+<li><a name='toc95' href='#sect95'>Synopsis</a></li>
+<li><a name='toc96' href='#sect96'>Description</a></li>
+<li><a name='toc97' href='#sect97'>Summary of Man Page</a></li>
+<li><a name='toc98' href='#sect98'>Document Processing Command Flags</a></li>
+<li><a name='toc99' href='#sect99'>Summary of Features</a></li>
+<li><a name='toc100' href='#sect100'>See Also</a></li>
+<li><a name='toc101' href='#sect101'>Homepage</a></li>
+<li><a name='toc102' href='#sect102'>Source</a></li>
+<li><a name='toc103' href='#sect103'>Author</a></li>
+</ul>
+</body>
+</html>