aboutsummaryrefslogtreecommitdiffhomepage
path: root/data/doc/sisu/html/sisu3.1.html
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2011-03-05 15:10:16 -0500
committerRalph Amissah <ralph@amissah.com>2011-03-05 15:10:16 -0500
commit0c872f4f046c394e15ab9b802c4226a0e9838aa3 (patch)
tree315a8b57b0ecf8c9c4150feebd81cd946162bc48 /data/doc/sisu/html/sisu3.1.html
parentsisu.8 manpage & html deleted, needs rewrite, unhelpful (diff)
html manpages, re-run man2html
Diffstat (limited to 'data/doc/sisu/html/sisu3.1.html')
-rw-r--r--data/doc/sisu/html/sisu3.1.html3520
1 files changed, 3520 insertions, 0 deletions
diff --git a/data/doc/sisu/html/sisu3.1.html b/data/doc/sisu/html/sisu3.1.html
new file mode 100644
index 00000000..905b05ec
--- /dev/null
+++ b/data/doc/sisu/html/sisu3.1.html
@@ -0,0 +1,3520 @@
+<!-- manual page source format generated by PolyglotMan v3.2, -->
+<!-- available at http://polyglotman.sourceforge.net/ -->
+
+<html>
+<head>
+<title>"sisu"("1") manual page</title>
+</head>
+<body bgcolor='white'>
+<a href='#toc'>Table of Contents</a><p>
+
+<h2><a name='sect0' href='#toc0'>Name</a></h2>
+sisu - documents: markup, structuring, publishing in multiple standard
+formats, and search
+<h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
+sisu [-abcDdFehIiMmNnopqRrSsTtUuVvwXxYyZz0-9]
+[filename/wildcard]
+<p> sisu [-P] [language_directory/filename language_directory]
+
+<p> sisu [-Ddcv] [instruction] [filename/wildcard]
+<p> sisu [-CcFLSVvW]
+<p> sisu
+--v2 [operations]
+<p> sisu --v1 [operations] SISU - MANUAL, RALPH AMISSAH
+<p> WHAT
+IS SISU?
+<p> 1. INTRODUCTION - WHAT IS SISU?
+<p> <b>SiSU</b> is a framework for document
+structuring, publishing (in multiple open standard formats) and search,
+comprising of: (a) a lightweight document structure and presentation markup
+syntax; and (b) an accompanying engine for generating standard document
+format outputs from documents prepared in sisu markup syntax, which is
+able to produce multiple standard outputs (including the population of
+sql databases) that (can) share a common numbering system for the citation
+of text within a document.
+<p> <b>SiSU</b> is developed under an open source, software
+libre license (GPL3). Its use case for development is work with medium to
+large document sets and cope with evolving document formats/ representation
+technologies. Documents are prepared once, and generated as need be to update
+the technical presentation or add additional output formats. Various output
+formats (including search related output) share a common mechanism for
+cross-output-format citation.
+<p> <b>SiSU</b> both defines a markup syntax and provides
+an engine that produces open standards format outputs from documents prepared
+with <b>SiSU</b> markup. From a single lightly prepared document sisu custom builds
+several standard output formats which share a common (text object) numbering
+system for citation of content within a document (that also has implications
+for search). The sisu engine works with an abstraction of the document&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 html, EPUB, LaTeX, landscape and portrait
+pdfs, Open Document Format (ODF), all of which can be added to and updated.
+<b>SiSU</b> is also able to populate SQL type databases at an object level, which
+means that searches can be made with that degree of granularity.
+<p> Source
+document preparation and output generation is a two step process: (i) document
+source is prepared, that is, marked up in sisu markup syntax and (ii) the
+desired output subsequently generated by running the sisu engine against
+document source. Output representations if updated (in the sisu engine)
+can be generated by re-running the engine against the prepared source. Using
+<b>SiSU</b> markup applied to a document, <b>SiSU</b> custom builds (to take advantage
+of the strengths of different ways of representing documents) various standard
+open output formats including plain text, HTML, XHTML, XML, EPUB, OpenDocument,
+LaTeX or PDF files, and populate an SQL database with objects[^1] (equating
+generally to paragraph-sized chunks) so searches may be performed and matches
+returned with that degree of granularity ( e.g. your search criteria is met
+by these documents and at these locations within each document). Document
+output formats share a common object numbering system for locating content.
+This is particularly suitable for "published" works (finalized texts as
+opposed to works that are frequently changed or updated) for which it provides
+a fixed means of reference of content.
+<p> In preparing a <b>SiSU</b> document you
+optionally provide semantic information related to the document in a document
+header, and in marking up the substantive text provide information on the
+structure of the document, primarily indicating heading levels and footnotes.
+You also provide information on basic text attributes where used. The rest
+is automatic, sisu from this information custom builds[^2] the different
+forms of output requested.
+<p> <b>SiSU</b> works with an abstraction of the document
+based on its structure which is comprised of its headings[^3] and objects[^4],
+which enables <b>SiSU</b> to represent the document in many different ways, and
+to take advantage of the strengths of different ways of presenting documents.
+The objects are numbered, and these numbers can be used to provide a common
+basis for citing material within a document across the different output
+format types. This is significant as page numbers are not well suited to
+the digital age, in web publishing, changing a browser&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> One of the challenges
+of maintaining documents is to keep them in a format that allows use of
+them independently of proprietary platforms. Consider issues related to
+dealing with legacy proprietary formats today and what guarantee you have
+that old proprietary formats will remain (or can be read without proprietary
+software/equipment) in 15 years time, or the way the way in which html
+has evolved over its relatively short span of existence. <b>SiSU</b> provides the
+flexibility of producing documents in multiple non-proprietary open formats
+including html, pdf[^5] ODF,[^6] and EPUB.[^7] Whilst <b>SiSU</b> relies on software,
+the markup is uncomplicated and minimalistic which guarantees that future
+engines can be written to run against it. It is also easily converted to
+other formats, which means documents prepared in <b>SiSU</b> can be migrated to
+other document formats. Further security is provided by the fact that the
+software itself, <b>SiSU</b> is available under GPL3 a licence that guarantees
+that the source code will always be open, and free as in libre, which means
+that that code base can be used, updated and further developed as required
+under the terms of its license. Another challenge is to keep up with a moving
+target. <b>SiSU</b> permits new forms of output to be added as they become important,
+(Open Document Format text was added in 2006 when it became an ISO standard
+for office applications and the archival of documents), EPUB was introduced
+in 2009; and allows the technical representations existing output to be
+updated (html has evolved and the related module has been updated repeatedly
+over the years, presumably when the World Wide Web Consortium (w3c) finalises
+html 5 which is currently under development, the html module will again
+be updated allowing all existing documents to be regenerated as html 5).
+
+<p> The document formats are written to the file-system and available for
+indexing by independent indexing tools, whether off the web like Google
+and Yahoo or on the site like Lucene and Hyperestraier.
+<p> <b>SiSU</b> also provides
+other features such as concordance files and document content certificates,
+and the working against an abstraction of document structure has further
+possibilities for the research and development of other document representations,
+the availability of objects is useful for example for topic maps and thesauri,
+together with the flexibility of <b>SiSU</b> offers great possibilities.
+<p> <b>SiSU</b>
+is primarily for published works, which can take advantage of the citation
+system to reliably reference its documents. <b>SiSU</b> works well in a complementary
+manner with such collaborative technologies as Wikis, which can take advantage
+of and be used to discuss the substance of content prepared in <b>SiSU</b>
+<p>
+&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+<p> 2. COMMANDS SUMMARY
+<p> 2.1 DESCRIPTION
+<p> <b>SiSU</b> <b>SiSU</b>
+is a document publishing system, that from a simple single marked-up document,
+produces multiple of output formats including: plaintext, html, xhtml,
+XML, epub, odt (odf text), LaTeX, pdf, info, and SQL (PostgreSQL and SQLite),
+which share numbered text objects ("object citation numbering") and the
+same document structure information. For more see: &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+
+<p> 2.2 DOCUMENT PROCESSING COMMAND FLAGS
+<p>
+<dl>
+
+<dt><b>-a [filename/wildcard]</b> </dt>
+<dd>produces plaintext
+with Unix linefeeds and without markup, (object numbers are omitted), has
+footnotes at end of each paragraph that contains them [ &nbsp;-A &nbsp;for &nbsp;equivalent
+&nbsp;dos &nbsp;(linefeed) &nbsp;output &nbsp;file] [see &nbsp;-e &nbsp;for (Options include: --endnotes for endnotes
+--footnotes for footnotes at the end of each paragraph --unix for unix linefeed
+(default) --msdos for msdos linefeed)
+<p> </dd>
+
+<dt><b>-b [filename/wildcard]</b> </dt>
+<dd>see --xhtml
+<p> </dd>
+
+<dt><b>--color-toggle
+[filename/wildcard]</b> </dt>
+<dd>screen toggle ansi screen colour on or off depending
+on default set (unless -c flag is used: if sisurc colour default is set
+to &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>--concordance [filename/wildcard]</b> </dt>
+<dd>produces concordance (wordmap) a rudimentary
+index of all the words in a document. (Concordance files are not generated
+for documents of over 260,000 words unless this limit is increased in the
+file sisurc.yml). Alias -w
+<p> </dd>
+
+<dt><b>-C [--init-site]</b> </dt>
+<dd>configure/initialise shared output
+directory files initialize shared output directory (config files such as
+css and dtd files are not updated if they already exist unless modifier
+is used). -C --init-site configure/initialise site more extensive than -C on
+its own, shared output directory files/force update, existing shared output
+config files such as css and dtd files are updated if this modifier is
+used.
+<p> </dd>
+
+<dt><b>-CC</b> </dt>
+<dd>configure/initialise shared output directory files initialize
+shared output directory (config files such as css and dtd files are not
+updated if they already exist unless modifier is used). The equivalent of:
+-C --init-site configure/initialise site, more extensive than -C on its own,
+shared output directory files/force update, existing shared output config
+files such as css and dtd files are updated if -CC is used.
+<p> </dd>
+
+<dt><b>-c [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --color-toggle
+<p> </dd>
+
+<dt><b>--dal [filename/wildcard/url]</b> </dt>
+<dd>assumed for most other flags,
+creates new intermediate files for processing (document abstraction) that
+is used in all subsequent processing of other output. This step is assumed
+for most processing flags. To skip it see -n. Alias -m
+<p> </dd>
+
+<dt><b>--delete [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --zap
+<p> </dd>
+
+<dt><b>-D [instruction] [filename]</b> </dt>
+<dd>see --pg
+<p> </dd>
+
+<dt><b>-d [--db-[database &nbsp;type &nbsp;(sqlite|pg)]]
+--[instruction] [filename]</b> </dt>
+<dd>see --sqlite
+<p> </dd>
+
+<dt><b>--epub [filename/wildcard]</b> </dt>
+<dd>produces
+an epub document, [sisu &nbsp;version &nbsp;2 &nbsp;only] (filename.epub). Alias -e
+<p> </dd>
+
+<dt><b>-e [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --epub
+<p> </dd>
+
+<dt><b>-F [--webserv=webrick]</b> </dt>
+<dd>see --sample-search-form
+<p> </dd>
+
+<dt><b>--git [filename/wildcard]</b>
+</dt>
+<dd>produces or updates markup source file structure in a git repo (experimental
+and subject to change). Alias -g
+<p> </dd>
+
+<dt><b>-g [filename/wildcard]</b> </dt>
+<dd>see --git
+<p> </dd>
+
+<dt><b>--harvest
+*.ss[tm]</b> </dt>
+<dd>makes two lists of sisu output based on the sisu markup documents
+in a directory: list of author and authors works (year and titles), and;
+list by topic with titles and author. Makes use of header metadata fields
+(author, title, date, topic_register). Can be used with maintenance (-M)
+and remote placement (-R) flags.
+<p> </dd>
+
+<dt><b>--help [topic]</b> </dt>
+<dd>provides help on the selected
+topic, where topics (keywords) include: list, (com)mands, short(cuts),
+(mod)ifiers, (env)ironment, markup, syntax, headers, headings, endnotes,
+tables, example, customise, skin, (dir)ectories, path, (lang)uage, db,
+install, setup, (conf)igure, convert, termsheet, search, sql, features,
+
+<p>license
+<p> </dd>
+
+<dt><b>--html [filename/wildcard]</b> </dt>
+<dd>produces html output, segmented text
+with table of contents (toc.html and index.html) and the document in a single
+file (scroll.html). Alias -h
+<p> </dd>
+
+<dt><b>-h [filename/wildcard]</b> </dt>
+<dd>see --html
+<p> </dd>
+
+<dt><b>-I [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --texinfo
+<p> </dd>
+
+<dt><b>-i [filename/wildcard]</b> </dt>
+<dd>see --manpage
+<p> </dd>
+
+<dt><b>-L</b> </dt>
+<dd>prints license information.
+
+<p> </dd>
+
+<dt><b>--machine [filename/wildcard/url]</b> </dt>
+<dd>see --dal (document abstraction level/layer)
+
+<p> </dd>
+
+<dt><b>--maintenance [filename/wildcard/url]</b> </dt>
+<dd>maintenance mode files created for
+processing preserved and their locations indicated. (also see -V). Alias -M
+
+<p> </dd>
+
+<dt><b>--manpage [filename/wildcard]</b> </dt>
+<dd>produces man page of file, not suitable for
+all outputs. Alias -i
+<p> </dd>
+
+<dt><b>-M [filename/wildcard/url]</b> </dt>
+<dd>see --maintenance
+<p> </dd>
+
+<dt><b>-m [filename/wildcard/url]</b>
+</dt>
+<dd>see --dal (document abstraction level/layer)
+<p> </dd>
+
+<dt><b>--no-ocn</b> </dt>
+<dd>[with &nbsp;--html &nbsp;--pdf &nbsp;or &nbsp;--epub]
+switches off object citation numbering. Produce output without identifying
+numbers in margins of html or LaTeX/pdf output.
+<p> </dd>
+
+<dt><b>-N [filename/wildcard/url]</b>
+</dt>
+<dd>document digest or document content certificate ( DCC ) as md5 digest tree
+of the document: the digest for the document, and digests for each object
+contained within the document (together with information on software versions
+that produced it) (digest.txt). -NV for verbose digest output to screen.
+<p> </dd>
+
+<dt><b>-n
+[filename/wildcard/url]</b> </dt>
+<dd>skip the creation of intermediate processing files
+(document abstraction) if they already exist, this skips the equivalent
+of -m which is otherwise assumed by most processing flags.
+<p> </dd>
+
+<dt><b>--odf [filename/wildcard/url]</b>
+</dt>
+<dd>
+<p>see --odt
+<p> </dd>
+
+<dt><b>--odt [filename/wildcard/url]</b> </dt>
+<dd>output basic document in opendocument
+file format (opendocument.odt). Alias -o
+<p> </dd>
+
+<dt><b>-o [filename/wildcard/url]</b> </dt>
+<dd>see --odt
+
+<p> </dd>
+
+<dt><b>--pdf [filename/wildcard]</b> </dt>
+<dd>produces LaTeX pdf (portrait.pdf &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
+<p> </dd>
+
+<dt><b>--pg [instruction] [filename]</b> </dt>
+<dd>database postgresql ( --pgsql
+may be used instead) possible instructions, include: --createdb; --create;
+--dropall; --import [filename]; --update [filename]; --remove [filename]; see database
+section below. Alias -D
+<p> </dd>
+
+<dt><b>--po [language_directory/filename language_directory]</b>
+</dt>
+<dd>
+<p>see --po4a
+<p> </dd>
+
+<dt><b>--po4a [language_directory/filename language_directory]</b> </dt>
+<dd>produces
+.pot and po files for the file in the languages specified by the language
+directory. SiSU markup is placed in subdirectories named with the language
+code, e.g. en/ fr/ es/. The sisu config file must set the output directory
+structure to multilingual. v3, experimental
+<p> </dd>
+
+<dt><b>-P [language_directory/filename
+language_directory]</b> </dt>
+<dd>see --po4a
+<p> </dd>
+
+<dt><b>-p [filename/wildcard]</b> </dt>
+<dd>see --pdf
+<p> </dd>
+
+<dt><b>--quiet [filename/wildcard]</b>
+</dt>
+<dd>quiet less output to screen.
+<p> </dd>
+
+<dt><b>-q [filename/wildcard]</b> </dt>
+<dd>see --quiet
+<p> </dd>
+
+<dt><b>--rsync [filename/wildcard]</b>
+</dt>
+<dd>copies sisu output files to remote host using rsync. This requires that
+sisurc.yml has been provided with information on hostname and username,
+and that you have your "keys" and ssh agent in place. Note the behavior
+of rsync different if -R is used with other flags from if used alone. Alone
+the rsync --delete parameter is sent, useful for cleaning the remote directory
+(when -R is used together with other flags, it is not). Also see --scp. Alias
+
+<p>-
+<p>R
+<p> </dd>
+
+<dt><b>-R [filename/wildcard]</b> </dt>
+<dd>see --rsync
+<p> </dd>
+
+<dt><b>-r [filename/wildcard]</b> </dt>
+<dd>see --scp
+<p> </dd>
+
+<dt><b>--sample-search-form
+[--webserv=webrick]</b> </dt>
+<dd>generate examples of (naive) cgi search form for sqlite
+and pgsql depends on your already having used sisu to populate an sqlite
+and/or pgsql database, (the sqlite version scans the output directories
+for existing sisu_sqlite databases, so it is first necessary to create
+them, before generating the search form) see -d -D and the database section
+below. If the optional parameter --webserv=webrick is passed, the cgi examples
+created will be set up to use the default port set for use by the webrick
+server, (otherwise the port is left blank and the system setting used,
+usually 80). The samples are dumped in the present work directory which
+must be writable, (with screen instructions given that they be copied to
+the cgi-bin directory). -Fv (in addition to the above) provides some information
+on setting up hyperestraier for sisu. Alias -F
+<p> </dd>
+
+<dt><b>--scp [filename/wildcard]</b> </dt>
+<dd>copies
+sisu output files to remote host using scp. This requires that sisurc.yml
+has been provided with information on hostname and username, and that you
+have your "keys" and ssh agent in place. Also see --rsync. Alias -r
+<p> </dd>
+
+<dt><b>--sqlite
+--[instruction] [filename]</b> </dt>
+<dd>database type default set to sqlite, (for which
+--sqlite may be used instead) or to specify another database --db-[pgsql, &nbsp;sqlite]
+(however see -D) possible instructions include: --createdb; --create; --dropall;
+--import [filename]; --update [filename]; --remove [filename]; see database section
+below. Alias -d
+<p> </dd>
+
+<dt><b>--sisupod</b> </dt>
+<dd>produces a sisupod a zipped sisu directory of markup
+files including sisu markup source files and the directories local configuration
+file, images and skins. Note: this only includes the configuration files
+or skins contained in ./_sisu not those in ~/.sisu -S [filename/wildcard]
+option. Note: (this<br>
+ option is tested only with zsh). Alias -S
+<p> </dd>
+
+<dt><b>--sisupod [filename/wildcard]</b> </dt>
+<dd>produces
+a zipped file of the prepared document specified along with associated
+images, by default named sisupod.zip they may alternatively be named with
+the filename extension .ssp This provides a quick way of gathering the relevant
+parts of a sisu document which can then for example be emailed. A sisupod
+includes sisu markup source file, (along with associated documents if a
+master file, or available in multilingual versions), together with related
+images and skin. <b>SiSU</b> commands can be run directly against a sisupod contained
+in a local directory, or provided as a url on a remote site. As there is
+a security issue with skins provided by other users, they are not applied
+unless the flag --trust or --trusted is added to the command instruction, it
+is recommended that file that are not your own are treated as untrusted.
+The directory structure of the unzipped file is understood by sisu, and
+sisu commands can be run within it. Note: if you wish to send multiple files,
+it quickly becomes more space efficient to zip the sisu markup directory,
+rather than the individual files for sending). See the -S option without
+[filename/wildcard]. Alias -S
+<p> </dd>
+
+<dt><b>--source [filename/wildcard]</b> </dt>
+<dd>copies sisu markup
+file to output directory. Alias -s
+<p> </dd>
+
+<dt><b>-S</b> </dt>
+<dd>see --sisupod
+<p> </dd>
+
+<dt><b>-S [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --sisupod
+<p> </dd>
+
+<dt><b>-s [filename/wildcard]</b> </dt>
+<dd>see --source
+<p> </dd>
+
+<dt><b>--texinfo [filename/wildcard]</b>
+</dt>
+<dd>produces texinfo and info file, (view with pinfo). Alias -I
+<p> </dd>
+
+<dt><b>--txt [filename/wildcard]</b>
+</dt>
+<dd>produces plaintext with Unix linefeeds and without markup, (object numbers
+are omitted), has footnotes at end of each paragraph that contains them
+[ &nbsp;-A &nbsp;for &nbsp;equivalent &nbsp;dos &nbsp;(linefeed) &nbsp;output &nbsp;file] [see &nbsp;-e &nbsp;for (Options include:
+--endnotes for endnotes --footnotes for footnotes at the end of each paragraph
+--unix for unix linefeed (default) --msdos for msdos linefeed). Alias -t
+<p> </dd>
+
+<dt><b>-T [filename/wildcard
+&nbsp;(*.termsheet.rb)]</b> </dt>
+<dd>standard form document builder, preprocessing feature
+<p>
+</dd>
+
+<dt><b>-t [filename/wildcard]</b> </dt>
+<dd>see --txt
+<p> </dd>
+
+<dt><b>--urls [filename/wildcard]</b> </dt>
+<dd>prints url output
+list/map for the available processing flags options and resulting files
+that could be requested, (can be used to get a list of processing options
+in relation to a file, together with information on the output that would
+be produced), -u provides url output mapping for those flags requested for
+processing. The default assumes sisu_webrick is running and provides webrick
+url mappings where appropriate, but these can be switched to file system
+paths in sisurc.yml. Alias -U
+<p> </dd>
+
+<dt><b>-U [filename/wildcard]</b> </dt>
+<dd>see --urls
+<p> </dd>
+
+<dt><b>-u [filename/wildcard]</b>
+</dt>
+<dd>provides url mapping of output files for the flags requested for processing,
+
+<p>also see -U
+<p> </dd>
+
+<dt><b>--v1 [filename/wildcard]</b> </dt>
+<dd>invokes the sisu v1 document parser/generator.
+For use with sisu v1 markup documents. (Markup conversion to v2 involves
+the modification of document headers)
+<p> </dd>
+
+<dt><b>--v2 [filename/wildcard]</b> </dt>
+<dd>invokes the
+sisu v2 document parser/generator. This is the default and is normally omitted.
+
+<p> </dd>
+
+<dt><b>--verbose [filename/wildcard]</b> </dt>
+<dd>provides verbose output of what is being generated,
+where output is placed (and error messages if any), as with -u flag provides
+a url mapping of files created for each of the processing flag requests.
+
+<p>Alias -v
+<p> </dd>
+
+<dt><b>-V</b> </dt>
+<dd>on its own, provides <b>SiSU</b> version and environment information
+(sisu --help env)
+<p> </dd>
+
+<dt><b>-V [filename/wildcard]</b> </dt>
+<dd>even more verbose than the -v flag.
+
+<p> </dd>
+
+<dt><b>-v</b> </dt>
+<dd>on its own, provides <b>SiSU</b> version information
+<p> </dd>
+
+<dt><b>-v [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --verbose
+<p> </dd>
+
+<dt><b>--webrick</b> </dt>
+<dd>starts ruby&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 &nbsp;output &nbsp;should &nbsp;be &nbsp;created &nbsp;using &nbsp;the &nbsp;-h &nbsp;option &nbsp;rather &nbsp;than and search
+-H &nbsp;; &nbsp;also, &nbsp;note &nbsp;-F &nbsp;webrick &nbsp;]. Alias -W
+<p> </dd>
+
+<dt><b>-W</b> </dt>
+<dd>see --webrick
+<p> </dd>
+
+<dt><b>--wordmap [filename/wildcard]</b>
+</dt>
+<dd>
+<p>see --concordance
+<p> </dd>
+
+<dt><b>-w [filename/wildcard]</b> </dt>
+<dd>see --concordance
+<p> </dd>
+
+<dt><b>--xhtml [filename/wildcard]</b>
+</dt>
+<dd>produces xhtml/XML output for browser viewing (sax parsing). Alias -b
+<p> </dd>
+
+<dt><b>--xml-dom
+[filename/wildcard]</b> </dt>
+<dd>produces XML output with deep document structure, in
+the nature of dom. Alias -X
+<p> </dd>
+
+<dt><b>--xml-sax [filename/wildcard]</b> </dt>
+<dd>produces XML output
+shallow structure (sax parsing). Alias -x
+<p> </dd>
+
+<dt><b>-X [filename/wildcard]</b> </dt>
+<dd>see --xml-dom
+
+<p> </dd>
+
+<dt><b>-x [filename/wildcard]</b> </dt>
+<dd>see --xml-sax
+<p> </dd>
+
+<dt><b>-Y [filename/wildcard]</b> </dt>
+<dd>produces a short
+sitemap entry for the document, based on html output and the sisu_manifest.
+--sitemaps generates/updates the sitemap index of existing sitemaps. (Experimental,
+[g,y,m &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>--zap [filename/wildcard]</b> </dt>
+<dd>Zap, if used with other processing flags deletes
+output files of the type about to be processed, prior to processing. If
+-Z is used as the lone processing related flag (or in conjunction with a
+combination of -[mMvVq]), will remove the related document output directory.
+
+<p>Alias -Z
+<p> </dd>
+
+<dt><b>-Z [filename/wildcard]</b> </dt>
+<dd>see --zap
+<p> </dd>
+</dl>
+3. COMMAND LINE MODIFIERS
+<p>
+<dl>
+
+<dt><b>--no-ocn</b>
+</dt>
+<dd>[with &nbsp;--html &nbsp;--pdf &nbsp;or &nbsp;--epub] switches off object citation numbering. Produce
+output without identifying numbers in margins of html or LaTeX/pdf output.
+
+<p> </dd>
+
+<dt><b>--no-annotate</b> </dt>
+<dd>strips output text of editor endnotes[^*1] denoted by asterisk
+
+<p>or dagger/plus sign
+<p> </dd>
+
+<dt><b>--no-asterisk</b> </dt>
+<dd>strips output text of editor endnotes[^*2]
+
+<p>denoted by asterisk sign
+<p> </dd>
+
+<dt><b>--no-dagger</b> </dt>
+<dd>strips output text of editor endnotes[^+1]
+
+<p>denoted by dagger/plus sign
+<p> </dd>
+</dl>
+4. DATABASE COMMANDS
+<p> dbi - database interface
+
+<p> -D or --pgsql set for postgresql -d or --sqlite default set for sqlite -d is
+modifiable with --db=[database &nbsp;type &nbsp;(pgsql &nbsp;or &nbsp;sqlite)]
+<p>
+<dl>
+
+<dt><b>--pg -v --createall</b> </dt>
+<dd>initial
+step, creates required relations (tables, indexes) in existing postgresql
+database (a database should be created manually and given the same name
+as working directory, as requested) (rb.dbi) [ &nbsp;-dv &nbsp;--createall sqlite &nbsp;equivalent]
+it may be necessary to run sisu -Dv --createdb initially NOTE: at the present
+time for postgresql it may be necessary to manually create the database.
+The command would be &rsquo;createdb [database &nbsp;name]&rsquo; where database name would
+be SiSU_[present &nbsp;working &nbsp;directory &nbsp;name (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 postgresql db (rb.dbi) [ &nbsp;-dv &nbsp;--import &nbsp;sqlite &nbsp;equivalent]
+
+<p> </dd>
+
+<dt><b>--pg -v --update</b> </dt>
+<dd>[filename/wildcard] updates/imports specified data to postgresql
+db (rb.dbi) [ &nbsp;-dv &nbsp;--update &nbsp;sqlite &nbsp;equivalent]
+<p> </dd>
+
+<dt><b>--pg --remove</b> </dt>
+<dd>[filename/wildcard]
+removes specified data to postgresql db (rb.dbi) [ &nbsp;-d &nbsp;--remove &nbsp;sqlite &nbsp;equivalent]
+
+<p> </dd>
+
+<dt><b>--pg --dropall</b> </dt>
+<dd>kills data" and drops (postgresql or sqlite) db, tables &amp; indexes
+[ &nbsp;-d --dropall &nbsp;sqlite &nbsp;equivalent]
+<p> The -v is for verbose output.
+<p> </dd>
+</dl>
+5. SHORTCUTS,
+SHORTHAND FOR MULTIPLE FLAGS
+<p>
+<dl>
+
+<dt><b>--update [filename/wildcard]</b> </dt>
+<dd>Checks existing
+file output and runs the flags required to update this output. This means
+that if only html and pdf output was requested on previous runs, only the
+-hp files will be applied, and only these will be generated this time, together
+with the summary. This can be very convenient, if you offer different outputs
+of different files, and just want to do the same again.
+<p> </dd>
+
+<dt><b>-0 to -5 [filename
+&nbsp;or &nbsp;wildcard]</b> </dt>
+<dd>Default shorthand mappings (note that the defaults can be
+changed/configured in the sisurc.yml file):
+<p> </dd>
+
+<dt><b>-0</b> </dt>
+<dd>-mNhwpAobxXyYv [this &nbsp;is &nbsp;the
+&nbsp;default &nbsp;action &nbsp;run &nbsp;when &nbsp;no &nbsp;i.e. &nbsp;on &nbsp;&rsquo;sisu &nbsp;[filename]&rsquo;]
+<p> </dd>
+
+<dt><b>-1</b> </dt>
+<dd>-mhewpy
+<p> </dd>
+
+<dt><b>-2</b> </dt>
+<dd>-mhewpaoy
+
+<p> </dd>
+
+<dt><b>-3</b> </dt>
+<dd>-mhewpAobxXyY
+<p> </dd>
+
+<dt><b>-4</b> </dt>
+<dd>-mhewpAobxXDyY --import
+<p> </dd>
+
+<dt><b>-5</b> </dt>
+<dd>-mhewpAobxXDyY --update
+<p> add -v
+for verbose mode and -c for color, e.g. sisu -2vc [filename &nbsp;or
+<p> consider -u
+
+<p>for appended url info or -v for verbose output
+<p> </dd>
+</dl>
+5.1 COMMAND LINE WITH FLAGS
+- BATCH PROCESSING
+<p> In the data directory run sisu -mh filename or wildcard
+eg. "sisu -h cisg.sst" or "sisu -h *.{sst,ssm}" to produce html version of all
+documents.
+<p> Running sisu (alone without any flags, filenames or wildcards)
+brings up the interactive help, as does any sisu command that is not recognised.
+Enter to escape.
+<p> 6. HELP
+<p> 6.1 SISU MANUAL
+<p> The most up to date information
+on sisu should be contained in the sisu_manual, available at:
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a>
+&gt;<br>
+
+<p> The manual can be generated from source, found respectively, either
+within the <b>SiSU</b> tarball or installed locally at:
+<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br>
+
+<p> /usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br>
+
+<p> move to the respective directory and type e.g.:
+<p> sisu sisu_manual.ssm<br>
+
+<p> 6.2 SISU MAN PAGES
+<p> If <b>SiSU</b> is installed on your system usual man commands
+should be available, try:
+<p> man sisu<br>
+
+<p> man sisu_markup<br>
+
+<p> man sisu_commands<br>
+
+<p> Most <b>SiSU</b> man pages are generated directly from sisu documents that
+are used to prepare the sisu manual, the sources files for which are located
+within the <b>SiSU</b> tarball at:
+<p> ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual/<br>
+
+<p> Once installed, directory equivalent to:
+<p> /usr/share/doc/sisu/sisu_manual/<br>
+
+<p> Available man pages are converted back to html using man2html:
+<p> /usr/share/doc/sisu/v2/html/<br>
+
+<p> ./data/doc/sisu/v2/html/<br>
+
+<p> An online version of the sisu man page is available here:
+<p> * various
+sisu man pages &lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
+&gt; [^8]
+<p> * 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;
+[^9]
+<p> 6.3 SISU BUILT-IN INTERACTIVE HELP
+<p> This is particularly useful for
+getting the current sisu setup/environment information:
+<p> sisu --help<br>
+
+<p> sisu --help [subject]<br>
+
+<p> sisu --help commands<br>
+
+<p> sisu --help markup<br>
+
+<p> sisu --help env [for &nbsp;feedback &nbsp;on &nbsp;the &nbsp;way &nbsp;your &nbsp;system &nbsp;is <br>
+ setup &nbsp;with &nbsp;regard &nbsp;to &nbsp;sisu]<br>
+
+<p> sisu -V [environment &nbsp;information, &nbsp;same &nbsp;as &nbsp;above &nbsp;command]<br>
+
+<p> sisu (on its own provides version and some help information)<br>
+
+<p> Apart from real-time information on your current configuration the <b>SiSU</b>
+manual and man pages are likely to contain more up-to-date information than
+the sisu interactive help (for example on commands and markup).
+<p> NOTE:
+Running the command sisu (alone without any flags, filenames or wildcards)
+brings up the interactive help, as does any sisu command that is not recognised.
+Enter to escape.
+<p> 6.4 HELP SOURCES
+<p> For lists of alternative help sources,
+see:
+<p> <b>man page</b>
+<p> man sisu_help_sources<br>
+
+<p> <b>man2html</b>
+<p> /usr/share/doc/sisu/v2/html/sisu.1.html<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
+&gt;<br>
+
+<p> 7. INTRODUCTION TO SISU MARKUP[^10]
+<p> 7.1 SUMMARY
+<p> <b>SiSU</b> source documents
+are plaintext (UTF-8)[^11] files
+<p> All paragraphs are separated by an empty
+line.
+<p> Markup is comprised of:
+<p> * at the top of a document, the document
+header made up of semantic meta-data about the document and if desired additional
+processing instructions (such an instruction to automatically number headings
+from a particular level down)
+<p> * followed by the prepared substantive
+text of which the most important single characteristic is the markup of
+different heading levels, which define the primary outline of the document
+structure. Markup of substantive text includes:
+<p> * heading levels defines
+document structure<br>
+
+<p> * text basic attributes, italics, bold etc.<br>
+
+<p> * grouped text (objects), which are to be treated differently, such
+as code<br>
+ blocks or poems.<br>
+
+<p> * footnotes/endnotes<br>
+
+<p> * linked text and images<br>
+
+<p> * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br>
+
+<p> Some interactive help on markup is available, by typing sisu and selecting
+
+<p>markup or sisu --help markup
+<p> To check the markup in a file:
+<p> sisu --identify
+[filename].sst<br>
+
+<p> For brief descriptive summary of markup history
+<p> sisu --query-history<br>
+
+<p> or if for a particular version:
+<p> sisu --query-0.38<br>
+
+<p> 7.2 MARKUP EXAMPLES
+<p> 7.2.1 ONLINE
+<p> Online markup examples are available
+together with the respective outputs produced from &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> 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> Some example marked
+up files are available as html with syntax highlighting for viewing: &lt;<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a>
+&gt;
+
+<p> an alternative presentation of markup syntax: &lt;<a href='http://www.jus.uio.no/sisu/sample/on_markup.txt'>http://www.jus.uio.no/sisu/sample/on_markup.txt</a>
+&gt;
+
+<p> 7.2.2 INSTALLED
+<p> With <b>SiSU</b> installed sample skins may be found in: /usr/share/doc/sisu/sisu_markup_samples/dfsg
+(or equivalent directory) and if sisu-markup-samples is installed also under:
+
+<p>/usr/share/doc/sisu/sisu_markup_samples/non-free
+<p> 8. MARKUP OF HEADERS
+<p>
+ Headers contain either: semantic meta-data about a document, which can
+be used by any output module of the program, or; processing instructions.
+
+<p> Note: the first line of a document may include information on the markup
+version used in the form of a comment. Comments are a percentage mark at
+the start of a paragraph (and as the first character in a line of text)
+followed by a space and the comment:
+<p>
+<p> <br>
+<pre> % this would be a comment
+</pre>
+<p> 8.1 SAMPLE HEADER
+<p> This current document is loaded by a master document
+that has a header similar to this one:
+<p>
+<p> <br>
+<pre> % SiSU master 2.0
+ @title: SiSU
+ :subtitle: Manual
+ @creator: :author: Amissah, Ralph
+ @rights: Copyright (C) Ralph Amissah 2007, License GPL 3
+ @classify:
+ :type: information
+ :topic_register: SiSU:manual;electronic documents:SiSU:manual
+ :subject: ebook, epublishing, electronic book, electronic publishing,
+ electronic document, electronic citation, data structure,
+ citation systems, search
+ % used_by: manual
+ @date: :published: 2008-05-22
+ :created: 2002-08-28
+ :issued: 2002-08-28
+ :available: 2002-08-28
+ :modified: 2010-03-03
+ @make: :num_top: 1
+ :breaks: new=C; break=1
+ :skin: skin_sisu_manual
+ :bold: /Gnu|Debian|Ruby|SiSU/
+ :manpage: name=sisu - documents: markup, structuring, publishing
+ in multiple standard formats, and search;
+ synopsis=sisu &nbsp;[-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] &nbsp;[filename/wildcard
+&nbsp;]
+ . sisu &nbsp;[-Ddcv] &nbsp;[instruction]
+ . sisu &nbsp;[-CcFLSVvW]
+ . sisu --v2 &nbsp;[operations]
+ . sisu --v1 &nbsp;[operations]
+ @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
+ { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
+ { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+ { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/
+ { SiSU @ Ruby Application Archive }http://raa.ruby-lang.org/project/sisu/
+ { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
+ { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+ { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
+ { SiSU help }http://www.jus.uio.no/sisu/sisu_manual/sisu_help/
+ { SiSU help sources }http://www.jus.uio.no/sisu/sisu_manual/sisu_help_sources/
+</pre>
+<p> 8.2 AVAILABLE HEADERS
+<p> Header tags appear at the beginning of a document
+and provide meta information on the document (such as the Dublin Core),
+or information as to how the document as a whole is to be processed. All
+header instructions take either the form @headername: or 0~headername. All
+
+<p>Dublin Core meta tags are available
+<p> <b>@indentifier:</b> information or instructions
+
+<p> where the "identifier" is a tag recognised by the program, and the "information"
+or "instructions" belong to the tag/indentifier specified
+<p> Note: a header
+where used should only be used once; all headers apart from @title: are
+optional; the @structure: header is used to describe document structure,
+and can be useful to know.
+<p> This is a sample header
+<p>
+<p> <br>
+<pre> % SiSU 2.0 &nbsp;[declared &nbsp;file-type &nbsp;identifier &nbsp;with &nbsp;markup &nbsp;version]
+</pre>
+<p> <br>
+<pre> @title: &nbsp;[title &nbsp;text] &nbsp;[this &nbsp;header &nbsp;is &nbsp;the &nbsp;only &nbsp;one &nbsp;that &nbsp;is &nbsp;mandatory]
+ :subtitle: &nbsp;[subtitle &nbsp;if &nbsp;any]
+ :language: English
+</pre>
+<p> <br>
+<pre> @creator: :author: &nbsp;[Lastname, &nbsp;First &nbsp;names]
+ :illustrator: &nbsp;[Lastname, &nbsp;First &nbsp;names]
+ :translator: &nbsp;[Lastname, &nbsp;First &nbsp;names]
+ :prepared_by: &nbsp;[Lastname, &nbsp;First &nbsp;names]
+</pre>
+<p> <br>
+<pre> @date: :published: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :created: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :issued: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :available: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :modified: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :valid: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :added_to_site: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+ :translated: &nbsp;[year &nbsp;or &nbsp;yyyy-mm-dd]
+</pre>
+<p> <br>
+<pre> @rights: :copyright: Copyright (C) &nbsp;[Year &nbsp;and &nbsp;Holder]
+ :license: &nbsp;[Use &nbsp;License &nbsp;granted]
+ :text: &nbsp;[Year &nbsp;and &nbsp;Holder]
+ :translation: &nbsp;[Name, &nbsp;Year]
+ :illustrations: &nbsp;[Name, &nbsp;Year]
+</pre>
+<p> <br>
+<pre> @classify:
+ :topic_register: SiSU:markup sample:book;book:novel:fantasy
+ :type:
+ :subject:
+ :description:
+ :keywords:
+ :abstract:
+ :isbn: &nbsp;[ISBN]
+ :loc: &nbsp;[Library &nbsp;of &nbsp;Congress &nbsp;classification]
+ :dewey: &nbsp;[Dewey &nbsp;classification
+ :pg: &nbsp;[Project &nbsp;Gutenberg &nbsp;text &nbsp;number]
+</pre>
+<p> <br>
+<pre> @links: { SiSU }http://www.jus.uio.no/sisu/
+ { FSF }http://www.fsf.org
+</pre>
+<p> <br>
+<pre> @make:
+ :skin: skin_name
+ [skins change default settings related to the appearance of documents
+generated]
+ :num_top: 1
+ :headings: &nbsp;[text &nbsp;to &nbsp;match &nbsp;for &nbsp;each &nbsp;level
+ (e.g. PART; Chapter; Section; Article;
+ or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
+ :breaks: new=:C; break=1
+ :promo: sisu, ruby, sisu_search_libre, open_society
+ :bold: [regular expression of words/phrases to be made bold]
+ :italics: &nbsp;[regular &nbsp;expression &nbsp;of &nbsp;words/phrases &nbsp;to &nbsp;italicise]
+</pre>
+<p> <br>
+<pre> @original: :language: &nbsp;[language]
+</pre>
+<p> <br>
+<pre> @notes: :comment:
+ :prefix: &nbsp;[prefix &nbsp;is &nbsp;placed &nbsp;just &nbsp;after &nbsp;table &nbsp;of &nbsp;contents]
+</pre>
+<p> 9. MARKUP OF SUBSTANTIVE TEXT
+<p> 9.1 HEADING LEVELS
+<p> Heading levels are
+:A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section headings, followed
+by other heading levels, and 1 -6 being headings followed by substantive
+text or sub-headings. :A~ usually the title :A~? conditional level 1 heading
+(used where a stand-alone document may be imported into another)
+<p> <b>:A~ [heading
+&nbsp;text]</b> Top level heading [this &nbsp;usually &nbsp;has &nbsp;similar &nbsp;content &nbsp;to &nbsp;the &nbsp;] NOTE:
+the heading levels described here are in 0.38 notation, see heading
+<p> <b>:B~
+[heading &nbsp;text]</b> Second level heading [this &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
+<p>
+ <b>:C~ [heading &nbsp;text]</b> Third level heading [this &nbsp;is &nbsp;a &nbsp;heading &nbsp;level &nbsp;divider]
+
+<p> <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> <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> <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>
+<p> <br>
+<pre> 1~filename level 1 heading,
+ % the primary division such as Chapter that is followed by substantive
+text,
+ % and may be further subdivided (this is the level on which by default
+html
+ % segments are made)
+</pre>
+<p> 9.2 FONT ATTRIBUTES
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_,
+"{citation}",
+ ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}- #{monospace}#
+ normal text
+ !{emphasis}!
+ *{bold text}*
+ _{underscore}_
+ /{italics}/
+ "{citation}"
+ ^{superscript}^
+ ,{subscript},
+ +{inserted text}+
+ -{strikethrough}-
+ #{monospace}#
+</pre>
+<p> <b>resulting output:</b>
+<p> normal text <b>emphasis</b> <b>bold text</b> <i>underscore</i> <i>italics</i>
+"citation" ^superscript^ [subscript] ++inserted text++ --strikethrough-- monospace
+
+<p> normal text
+<p> <b>emphasis</b> [note: &nbsp;can &nbsp;be &nbsp;configured &nbsp;to &nbsp;be &nbsp;represented &nbsp;by
+&nbsp;bold, &nbsp;italics &nbsp;or &nbsp;underscore]
+<p> <b>bold text</b>
+<p> <i>italics</i>
+<p> <i>underscore</i>
+<p> "citation"
+
+<p> ^superscript^
+<p> [subscript]
+<p> ++inserted text++
+<p> --strikethrough--
+<p> monospace
+
+<p> 9.3 INDENTATION AND BULLETS
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> ordinary paragraph
+ _1 indent paragraph one step
+ _2 indent paragraph two steps
+ _9 indent paragraph nine steps
+</pre>
+<p>
+<p> <b>resulting output:</b>
+<p> ordinary paragraph
+<p> indent paragraph one step<br>
+
+<p> indent paragraph two steps<br>
+
+<p> indent paragraph nine steps<br>
+
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> _* bullet text
+ _1* bullet text, first indent
+ _2* bullet text, two step indent
+</pre>
+<p> <b>resulting output:</b>
+<p> * bullet text
+<p> * bullet text, first indent<br>
+
+<p> * bullet text, two step indent<br>
+
+<p> Numbered List (not to be confused with headings/titles, (document structure))
+
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> # numbered list numbered list 1., 2., 3, etc.
+ _# numbered list numbered list indented a., b., c., d., etc.
+</pre>
+<p> 9.4 FOOTNOTES / ENDNOTES
+<p> Footnotes and endnotes not distinguished in
+markup. They are automatically numbered. Depending on the output file format
+(html, EPUB, odf, pdf etc.), the document output selected will have either
+footnotes or endnotes.
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> ~{ a footnote or endnote }~
+</pre>
+<p> <b>resulting output:</b>
+<p> [^12]
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text~{ self contained endnote marker &amp; endnote in one }~ continues
+</pre>
+<p> <b>resulting output:</b>
+<p> normal text[^13] continues
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text ~{* unnumbered asterisk footnote/endnote, insert multiple
+asterisks if required }~ continues
+ normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
+</pre>
+<p> <b>resulting output:</b>
+<p> normal text [^*] continues
+<p> normal text [^**] continues
+
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text ~[* &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> <b>resulting output:</b>
+<p> normal text [^*3] continues
+<p> normal text [^+2] continues
+
+<p> <b>Alternative endnote pair notation for footnotes/endnotes:</b>
+<p>
+<p> <br>
+<pre> % note the endnote marker
+ normal text~^ continues
+ ^~ endnote text following the paragraph in which the marker occurs
+</pre>
+<p> the standard and pair notation cannot be mixed in the same document
+<p>
+
+<p>9.5 LINKS
+<p> 9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS
+<p> urls found within
+text are marked up automatically. A url within text is automatically hyperlinked
+to itself and by default decorated with angled braces, unless they are
+contained within a code block (in which case they are passed as normal
+text), or escaped by a preceding underscore (in which case the decoration
+is omitted).
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text http://www.jus.uio.no/sisu continues
+</pre>
+<p> <b>resulting output:</b>
+<p> normal text &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt; continues
+<p> An
+
+<p>escaped url without decoration
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> normal text _http://www.jus.uio.no/sisu continues
+ deb http://www.jus.uio.no/sisu/archive unstable main non-free
+</pre>
+<p> <b>resulting output:</b>
+<p> normal text &lt;_<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt; continues
+<p>
+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> where a code
+block is used there is neither decoration nor hyperlinking, code blocks
+
+<p>are discussed later in this document
+<p> <b>resulting output:</b>
+<p>
+<p> <br>
+<pre> deb http://www.jus.uio.no/sisu/archive unstable main non-free
+ deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+</pre>
+<p> To link text or an image to a url the markup is as follows
+<p> <b>markup example:</b>
+
+<p>
+<p> <br>
+<pre> about { SiSU }http://url.org markup
+</pre>
+<p> 9.5.2 LINKING TEXT
+<p> <b>resulting output:</b>
+<p> about SiSU &lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
+&gt;
+
+<p>markup
+<p> A shortcut notation is available so the url link may also be provided
+
+<p>automatically as a footnote
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> about {~^ SiSU }http://url.org markup
+</pre>
+<p> <b>resulting output:</b>
+<p> abou tSiSU &lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
+&gt; [^14] markup
+<p>
+
+<p>9.5.3 LINKING IMAGES
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> { tux.png 64x80 }image
+ % various url linked images
+ {tux.png 64x80
+ {GnuDebianLinuxRubyBetterWay.png 100x101
+ {~^ ruby_logo.png
+</pre>
+<p> <b>resulting output:</b>
+<p> [ tux.png ]
+<p> tux.png 64x80
+<p> [ &nbsp;ruby_logo &nbsp;(png &nbsp;missing)
+&nbsp;] [^15]
+<p> GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby
+<p> <b>linked url footnote
+
+<p>shortcut</b>
+<p>
+<p> <br>
+<pre> {~^ &nbsp;[text &nbsp;to &nbsp;link] }http://url.org
+ % maps to: { &nbsp;[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>
+<p> <br>
+<pre> text marker *~name
+</pre>
+<p> note at a heading level the same is automatically achieved by providing
+names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
+auto-heading numbering, without further intervention.
+<p> 9.6 GROUPED TEXT
+<p> 9.6.1
+
+<p>TABLES
+<p> Tables may be prepared in two either of two forms
+<p> <b>markup example:</b>
+
+<p>
+<p> <br>
+<pre> table{ c3; 40; 30; 30;
+ This is a table
+ this would become column two of row one
+ column three of row one is here
+ And here begins another row
+ column two of row two
+ column three of row two, and so on
+ }table
+</pre>
+<p> <b>resulting output:</b>
+<p> &nbsp;[table &nbsp;omitted, &nbsp;see &nbsp;other &nbsp;document &nbsp;formats]<br>
+
+<p> a second form may be easier to work with in cases where there is not
+
+<p>much information in each column
+<p> <b>markup example:</b> [^16]
+<p>
+<p> <br>
+<pre> !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
+ {table~h 24; 12; 12; 12; 12; 12; 12;}
+ |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July
+2004|June 2006
+ Contributors* | 10| 472| 2,188| 9,653|
+ 25,011| 48,721
+ Active contributors** | 9| 212| 846| 3,228|
+ 8,442| 16,945
+ Very active contributors*** | 0| 31| 190| 692|
+ 1,639| 3,016
+ No. of English language articles| 25| 16,000| 101,000| 190,000|
+320,000| 630,000
+ No. of articles, all languages | 25| 19,000| 138,000| 490,000|
+862,000|1,600,000
+ \* Contributed at least ten times; \** at least 5 times in last month;
+\* more than 100 times in last month.
+</pre>
+<p> <b>resulting output:</b>
+<p> <b>Table 3.1: Contributors to Wikipedia, January 2001
+- June 2005</b>
+<p> &nbsp;[table &nbsp;omitted, &nbsp;see &nbsp;other &nbsp;document &nbsp;formats]<br>
+
+<p> * Contributed at least ten times; ** at least 5 times in last month;
+*** more than 100 times in last month.
+<p> 9.6.2 POEM
+<p> <b>basic markup:</b>
+<p>
+<p> <br>
+<pre> poem{
+ Your poem here
+ }poem
+ Each verse in a poem is given a separate object number.
+</pre>
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> poem{
+ &lsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+
+ 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,
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath.
+
+ judge, I&rsquo;ll
+ be jury,
+ Said
+ cunning
+ old Fury:
+
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death.
+ }poem
+</pre>
+<p> <b>resulting output:</b>
+<p> &rsquo;Fury said to a<br>
+ mouse, That he<br>
+ met in the<br>
+ house,<br>
+ <br>
+ both go to<br>
+ law: I will<br>
+ prosecute<br>
+ YOU. --Come,<br>
+ I&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,<br>
+ a trial,<br>
+ dear Sir,<br>
+ With<br>
+ no jury<br>
+ or judge,<br>
+ would be<br>
+ wasting<br>
+ our<br>
+ breath.<br>
+ <br>
+ judge, I&rsquo;ll<br>
+ be jury,<br>
+ Said<br>
+ cunning<br>
+ old Fury:<br>
+ <br>
+ try the<br>
+ whole<br>
+ cause,<br>
+ and<br>
+ condemn<br>
+ you<br>
+ to<br>
+ death.<br>
+
+<p> 9.6.3 GROUP
+<p> <b>basic markup:</b>
+<p>
+<p> <br>
+<pre> group{
+ Your grouped text here
+ }group
+ A group is treated as an object and given a single object number.
+</pre>
+<p> <b>markup example:</b>
+<p>
+<p> <br>
+<pre> group{
+ &rsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+
+ 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,
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath.
+
+ judge, I&rsquo;ll
+ be jury,
+ Said
+ cunning
+ old Fury:
+
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death.
+ }group
+</pre>
+<p> <b>resulting output:</b>
+<p> &rsquo;Fury said to a<br>
+ mouse, That he<br>
+ met in the<br>
+ house,<br>
+ <br>
+ both go to<br>
+ law: I will<br>
+ prosecute<br>
+ YOU. --Come,<br>
+ I&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,<br>
+ a trial,<br>
+ dear Sir,<br>
+ With<br>
+ no jury<br>
+ or judge,<br>
+ would be<br>
+ wasting<br>
+ our<br>
+ breath.<br>
+ <br>
+ judge, I&rsquo;ll<br>
+ be jury,<br>
+ Said<br>
+ cunning<br>
+ old Fury:<br>
+ <br>
+ try the<br>
+ whole<br>
+ cause,<br>
+ and<br>
+ condemn<br>
+ you<br>
+ to<br>
+ death.<br>
+
+<p> 9.6.4 CODE
+<p> Code tags are used to escape regular sisu markup, and have
+been used extensively within this document to provide examples of <b>SiSU</b>
+markup. You cannot however use code tags to escape code tags. They are however
+used in the same way as group or poem tags.
+<p> A code-block is treated as
+an object and given a single object number. [an more than 100 times in last
+month. option &nbsp;to &nbsp;number &nbsp;each &nbsp;line &nbsp;of &nbsp;code &nbsp;may &nbsp;be &nbsp;considered &nbsp;at more than
+100 times in last month. some &nbsp;later &nbsp;time]
+<p> <b>use of code tags instead of
+poem compared, resulting output:</b>
+<p>
+<p> <br>
+<pre> &rsquo;Fury said to a
+ mouse, That he
+ met in the
+ house,
+
+ 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,
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath.
+
+ judge, I&rsquo;ll
+ be jury,
+ Said
+ cunning
+ old Fury:
+
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death.
+</pre>
+<p> 9.7 BOOK INDEX
+<p> To make an index append to paragraph the book index term
+relates to it, using an equal sign and curly braces.
+<p> Currently two levels
+are provided, a main term and if needed a sub-term. Sub-terms are separated
+from the main term by a colon.
+<p>
+<p> <br>
+<pre> Paragraph containing main term and sub-term.
+ ={Main term:sub-term}
+</pre>
+<p> The index syntax starts on a new line, but there should not be an empty
+line between paragraph and index markup.
+<p> The structure of the resulting
+index would be:
+<p>
+<p> <br>
+<pre> Main term, 1
+ sub-term, 1
+</pre>
+<p> Several terms may relate to a paragraph, they are separated by a semicolon.
+If the term refers to more than one paragraph, indicate the number of paragraphs.
+
+<p>
+<p> <br>
+<pre> Paragraph containing main term, second term and sub-term.
+ ={first term; second term: sub-term}
+</pre>
+<p> The structure of the resulting index would be:
+<p>
+<p> <br>
+<pre> First term, 1,
+ Second term, 1,
+ sub-term, 1
+</pre>
+<p> If multiple sub-terms appear under one paragraph, they are separated under
+the main term heading from each other by a pipe symbol.
+<p>
+<p> <br>
+<pre> Paragraph containing main term, second term and sub-term.
+ ={Main term:sub-term+1|second sub-term
+ A paragraph that continues discussion of the first sub-term
+</pre>
+<p> The plus one in the example provided indicates the first sub-term spans
+one additional paragraph. The logical structure of the resulting index would
+be:
+<p>
+<p> <br>
+<pre> Main term, 1,
+ sub-term, 1-3,
+ second sub-term, 1,
+</pre>
+<p> 10. COMPOSITE DOCUMENTS MARKUP
+<p> It is possible to build a document by
+creating a master document that requires other documents. The documents
+required may be complete documents that could be generated independently,
+or they could be markup snippets, prepared so as to be easily available
+to be placed within another text. If the calling document is a master document
+(built from other documents), it should be named with the suffix <b>.ssm</b> Within
+this document you would provide information on the other documents that
+should be included within the text. These may be other documents that would
+be processed in a regular way, or markup bits prepared only for inclusion
+within a master document <b>.sst</b> regular markup file, or <b>.ssi</b> (insert/information)
+
+<p>A secondary file of the composite document is built prior to processing
+
+<p>with the same prefix and the suffix <b>._sst</b>
+<p> basic markup for importing a
+
+<p>document into a master document
+<p>
+<p> <br>
+<pre> &lt;&lt; filename1.sst
+ &lt;&lt; filename2.ssi
+</pre>
+<p> The form described above should be relied on. Within the Vim editor it
+results in the text thus linked becoming hyperlinked to the document it
+is calling in which is convenient for editing. Alternative markup for importation
+of documents under consideration, and occasionally supported have been.
+
+<p>
+<p> <br>
+<pre> &lt;&lt; filename.ssi
+ &lt;&lt;{filename.ssi}
+ % using textlink alternatives
+ &lt;&lt; |filename.ssi|@|^|
+</pre>
+<p> MARKUP SYNTAX HISTORY
+<p> 11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX
+
+<p> 0.38 is substantially current, depreciated 0.16 supported, though file
+
+<p>names were changed at 0.37
+<p> * sisu --query=[sisu &nbsp;version &nbsp;[0.38] or &rsquo;history]
+
+<p> provides a short history of changes to <b>SiSU</b> markup
+<p> <b>0.57</b> (2007w34/4)
+<b>SiSU</b> 0.57 is the same as 0.42 with the introduction of some a shortcut to
+use the headers @title and @creator in the first heading [expanded &nbsp;using
+&nbsp;the &nbsp;and &nbsp;@author:]
+<p>
+<p> <br>
+<pre> :A~ @title by @author
+</pre>
+<p> <b>0.52</b> (2007w14/6) declared document type identifier at start of text/document:
+
+<p> .B SiSU<br>
+ 0.52
+<p> or, backward compatible using the comment marker:
+<p> %<br>
+ <b>SiSU</b> 0.38
+<p> variations include &rsquo; <b>SiSU</b> (text|master|insert) [version]&rsquo; and &rsquo;sisu-[version]&rsquo;
+
+<p> <b>0.51</b> (2007w13/6) skins changed (simplified), markup unchanged
+<p> <b>0.42</b> (2006w27/4)
+* (asterisk) type endnotes, used e.g. in relation to author
+<p> <b>SiSU</b> 0.42 is
+the same as 0.38 with the introduction of some additional endnote types,
+
+<p> Introduces some variations on endnotes, in particular the use of the
+
+<p>asterisk
+<p>
+<p> <br>
+<pre> ~{* for example for describing an author }~ and ~{** for describing a
+second author }~
+</pre>
+<p> * for example for describing an author
+<p> ** for describing a second author
+
+<p> and
+<p>
+<p> <br>
+<pre> ~[* &nbsp;my &nbsp;note &nbsp;]~ or ~[+ &nbsp;another &nbsp;note &nbsp;]~
+</pre>
+<p> which numerically increments an asterisk and plus respectively
+<p> *1 my
+
+<p>note +1 another note
+<p> <b>0.38</b> (2006w15/7) introduced new/alternative notation
+for headers, e.g. @title: (instead of 0~title), and accompanying document
+structure markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6)
+<p> <b>SiSU</b>
+0.38 introduced alternative experimental header and heading/structure markers,
+
+<p>
+<p> <br>
+<pre> @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~
+</pre>
+<p> as the equivalent of:
+<p>
+<p> <br>
+<pre> 0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~
+</pre>
+<p> The internal document markup of <b>SiSU</b> 0.16 remains valid and standard Though
+
+<p>note that <b>SiSU</b> 0.37 introduced a new file naming convention
+<p> <b>SiSU</b> has in
+effect two sets of levels to be considered, using 0.38 notation A-C headings/levels,
+pre-ordinary paragraphs /pre-substantive text, and 1-3 headings/levels, levels
+which are followed by ordinary text. This may be conceptualised as levels
+A,B,C, 1,2,3, and using such letter number notation, in effect: A must
+exist, optional B and C may follow in sequence (not strict) 1 must exist,
+optional 2 and 3 may follow in sequence i.e. there are two independent heading
+level sequences A,B,C and 1,2,3 (using the 0.16 standard notation 1,2,3
+and 4,5,6) on the positive side: the 0.38 A,B,C,1,2,3 alternative makes
+explicit an aspect of structuring documents in <b>SiSU</b> that is not otherwise
+obvious to the newcomer (though it appears more complicated, is more in
+your face and likely to be understood fairly quickly); the substantive
+text follows levels 1,2,3 and it is &rsquo;nice&rsquo; to do most work in those levels
+
+<p> <b>0.37</b> (2006w09/7) introduced new file naming convention, .sst (text), .ssm
+(master), .ssi (insert), markup syntax unchanged
+<p> <b>SiSU</b> 0.37 introduced new
+file naming convention, using the file extensions .sst .ssm and .ssi to replace
+.s1 .s2 .s3 .r1 .r2 .r3 and .si<br>
+
+<p> this is captured by the following file &rsquo;rename&rsquo; instruction:
+<p>
+<p> <br>
+<pre> rename &rsquo;s/.s[123]$/.sst/&rsquo; *.s{1,2,3}
+ rename &rsquo;s/.r[123]$/.ssm/&rsquo; *.r{1,2,3}
+ rename &rsquo;s/.si$/.ssi/&rsquo; *.si
+</pre>
+<p> The internal document markup remains unchanged, from <b>SiSU</b> 0.16
+<p> <b>0.35</b> (2005w52/3)
+sisupod, zipped content file introduced
+<p> <b>0.23</b> (2005w36/2) utf-8 for markup
+
+<p>file
+<p> <b>0.22</b> (2005w35/3) image dimensions may be omitted if rmagick is available
+
+<p>to be relied upon
+<p> <b>0.20.4</b> (2005w33/4) header 0~links
+<p> <b>0.16</b> (2005w25/2) substantial
+changes introduced to make markup cleaner, header 0~title type, and headings
+[1-6]~ introduced, also percentage sign (%) at start of a text line as comment
+
+<p>marker
+<p> <b>SiSU</b> 0.16 (0.15 development branch) introduced the use of
+<p> the
+header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~
+<p> in place of the 0.1
+header, heading/structure notation
+<p> <b>SiSU</b> 0.1 headers and headings structure
+represented by header 0{~ and headings/structure 1{ 2{ 3{ 4{~ 5{ 6{
+<p> 12.
+SISU FILETYPES
+<p> <b>SiSU</b> has plaintext and binary filetypes, and can process
+either type of document.
+<p> 12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT
+<p> <b>SiSU</b> documents
+are prepared as plain-text (utf-8) files with <b>SiSU</b> markup. They may make reference
+to and contain images (for example), which are stored in the directory
+beneath them _sisu/image. <b>SiSU</b> plaintext markup files are of three types
+that may be distinguished by the file extension used: regular text .sst;
+master documents, composite documents that incorporate other text, which
+can be any regular text or text insert; and inserts the contents of which
+are like regular text except these are marked .ssi and are not processed.<br>
+
+<p> <b>SiSU</b> processing can be done directly against a sisu documents; which
+may be located locally or on a remote server for which a url is provided.
+
+<p> <b>SiSU</b> source markup can be shared with the command:
+<p> sisu -s [filename]<br>
+
+<p> 12.1.1 SISU TEXT - REGULAR FILES (.SST)
+<p> The most common form of document
+in <b>SiSU</b> , see the section on <b>SiSU</b> markup.
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a>
+&gt;
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
+&gt;
+<p> 12.1.2 SISU MASTER FILES (.SSM)
+<p> Composite
+documents which incorporate other <b>SiSU</b> documents which may be either regular
+<b>SiSU</b> text .sst which may be generated independently, or inserts prepared
+solely for the purpose of being incorporated into one or more master documents.
+
+<p> The mechanism by which master files incorporate other documents is described
+as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual.
+<p> Note:
+Master documents may be prepared in a similar way to regular documents,
+and processing will occur normally if a .sst file is renamed .ssm without
+requiring any other documents; the .ssm marker flags that the document may
+contain other documents.
+<p> Note: a secondary file of the composite document
+is built prior to processing with the same prefix and the suffix ._sst [^17]
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_markup'>http://www.jus.uio.no/sisu/sisu_markup</a>
+&gt;
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
+&gt;
+
+<p> 12.1.3 SISU INSERT FILES (.SSI)
+<p> Inserts are documents prepared solely for
+the purpose of being incorporated into one or more master documents. They
+resemble regular <b>SiSU</b> text files except they are ignored by the <b>SiSU</b> processor.
+Making a file a .ssi file is a quick and convenient way of flagging that
+it is not intended that the file should be processed on its own.
+<p> 12.2 SISUPOD,
+ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
+<p> A sisupod is a zipped <b>SiSU</b>
+text file or set of <b>SiSU</b> text files and any associated images that they
+contain (this will be extended to include sound and multimedia-files)
+<p>
+<b>SiSU</b> plaintext files rely on a recognised directory structure to find contents
+such as images associated with documents, but all images for example for
+all documents contained in a directory are located in the sub-directory
+_sisu/image. Without the ability to create a sisupod it can be inconvenient
+to manually identify all other files associated with a document. A sisupod
+automatically bundles all associated files with the document that is turned
+into a pod.
+<p> The structure of the sisupod is such that it may for example
+contain a single document and its associated images; a master document
+and its associated documents and anything else; or the zipped contents
+of a whole directory of prepared <b>SiSU</b> documents.
+<p> The command to create
+a sisupod is:
+<p> sisu -S [filename]<br>
+
+<p> Alternatively, make a pod of the contents of a whole directory:
+<p>
+sisu -S<br>
+
+<p> <b>SiSU</b> processing can be done directly against a sisupod; which may be
+located locally or on a remote server for which a url is provided.
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_commands'>http://www.jus.uio.no/sisu/sisu_commands</a>
+&gt;
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/sisu_manual'>http://www.jus.uio.no/sisu/sisu_manual</a>
+&gt;
+<p> 13. EXPERIMENTAL ALTERNATIVE INPUT
+REPRESENTATIONS
+<p> 13.1 ALTERNATIVE XML
+<p> <b>SiSU</b> offers alternative XML input
+representations of documents as a proof of concept, experimental feature.
+They are however not strictly maintained, and incomplete and should be
+handled with care.
+<p> <b>convert from sst to simple xml representations (sax,
+dom and node):</b>
+<p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br>
+
+<p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br>
+
+<p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br>
+
+<p> <b>convert to sst from any sisu xml representation (sax, dom and node):</b>
+
+<p> sisu --from-xml2sst [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> or the same:
+<p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> 13.1.1 XML SAX REPRESENTATION
+<p> To convert from sst to simple xml (sax)
+representation:
+<p> sisu --to-sax [filename/wildcard] or sisu --to-sxs [filename/wildcard]<br>
+
+<p> To convert from any sisu xml representation back to sst
+<p> sisu --from-xml2sst
+[filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> or the same:
+<p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> 13.1.2 XML DOM REPRESENTATION
+<p> To convert from sst to simple xml (dom)
+representation:
+<p> sisu --to-dom [filename/wildcard] or sisu --to-sxd [filename/wildcard]<br>
+
+<p> To convert from any sisu xml representation back to sst
+<p> sisu --from-xml2sst
+[filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> or the same:
+<p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> 13.1.3 XML NODE REPRESENTATION
+<p> To convert from sst to simple xml (node)
+representation:
+<p> sisu --to-node [filename/wildcard] or sisu --to-sxn [filename/wildcard]<br>
+
+<p> To convert from any sisu xml representation back to sst
+<p> sisu --from-xml2sst
+[filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> or the same:
+<p> sisu --from-sxml [filename/wildcard &nbsp;[.sxs.xml,.sxd.xml,sxn.xml]]<br>
+
+<p> 14. CONFIGURATION
+<p> 14.1 DETERMINING THE CURRENT CONFIGURATION
+<p> Information
+on the current configuration of <b>SiSU</b> should be available with the help
+command:
+<p> sisu -v<br>
+
+<p> which is an alias for:
+<p> sisu --help env<br>
+
+<p> Either of these should be executed from within a directory that contains
+sisu markup source documents.
+<p> 14.2 CONFIGURATION FILES (CONFIG.YML)
+<p> <b>SiSU</b>
+configration parameters are adjusted in the configuration file, which can
+be used to override the defaults set. This includes such things as which
+directory interim processing should be done in and where the generated
+output should be placed.
+<p> The <b>SiSU</b> configuration file is a yaml file, which
+means indentation is significant.
+<p> <b>SiSU</b> resource configuration is determined
+by looking at the following files if they exist:
+<p> ./_sisu/sisurc.yml<br>
+
+<p> ~/.sisu/sisurc.yml<br>
+
+<p> /etc/sisu/sisurc.yml<br>
+
+<p> The search is in the order listed, and the first one found is used.
+<p>
+ In the absence of instructions in any of these it falls back to the internal
+program defaults.
+<p> Configuration determines the output and processing directories
+and the database access details.
+<p> If <b>SiSU</b> is installed a sample sisurc.yml
+
+<p>may be found in /etc/sisu/sisurc.yml
+<p> 15. SKINS
+<p> Skins modify the default
+appearance of document output on a document, directory, or site wide basis.
+Skins are looked for in the following locations:
+<p> ./_sisu/skin<br>
+
+<p> ~/.sisu/skin<br>
+
+<p> /etc/sisu/skin<br>
+
+<p> <b>Within the skin directory</b> are the following the default sub-directories
+for document skins:
+<p> ./skin/doc<br>
+
+<p> ./skin/dir<br>
+
+<p> ./skin/site<br>
+
+<p> A skin is placed in the appropriate directory and the file named skin_[name].rb
+
+<p> The skin itself is a ruby file which modifies the default appearances
+set in the program.
+<p> 15.1 DOCUMENT SKIN
+<p> Documents take on a document skin,
+if the header of the document specifies a skin to be used.
+<p>
+<p> <br>
+<pre> @skin: skin_united_nations
+</pre>
+<p> 15.2 DIRECTORY SKIN
+<p> A directory may be mapped on to a particular skin,
+so all documents within that directory take on a particular appearance.
+If a skin exists in the skin/dir with the same name as the document directory,
+it will automatically be used for each of the documents in that directory,
+(except where a document specifies the use of another skin, in the skin/doc
+directory).
+<p> A personal habit is to place all skins within the doc directory,
+and symbolic links as needed from the site, or dir directories as required.
+
+<p> 15.3 SITE SKIN
+<p> A site skin, modifies the program default skin.
+<p> 15.4 SAMPLE
+
+<p>SKINS
+<p> With <b>SiSU</b> installed sample skins may be found in:
+<p> /etc/sisu/skin/doc
+and<br>
+ /usr/share/doc/sisu/v2/sisu_markup_samples/samples/_sisu/skin/doc<br>
+
+<p> (or equivalent directory) and if sisu-markup-samples is installed also
+under:
+<p> /usr/share/doc/sisu-markup-samples/v2/samples/_sisu/skin/doc<br>
+
+<p> Samples of list.yml and promo.yml (which are used to create the right
+column list) may be found in:
+<p> /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml
+(or equivalent<br>
+ directory)<br>
+
+<p> 16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
+<p> CSS files
+to modify the appearance of <b>SiSU</b> html, XHTML or XML may be placed in the
+configuration directory: ./_sisu/css ; ~/.sisu/css or; /etc/sisu/css and
+these will be copied to the output directories with the command sisu -CC.
+
+<p> The basic CSS file for html output is html.css, placing a file of that
+name in directory _sisu/css or equivalent will result in the default file
+of that name being overwritten.
+<p> HTML: html.css
+<p> XML DOM: dom.css
+<p> XML
+SAX: sax.css
+<p> XHTML: xhtml.css
+<p> The default homepage may use homepage.css
+
+<p>or html.css
+<p> Under consideration is to permit the placement of a CSS file
+with a different name in directory _sisu/css directory or equivalent, and
+change the default CSS file that is looked for in a skin.[^18]
+<p> 17. ORGANISING
+CONTENT
+<p> 17.1 DIRECTORY STRUCTURE AND MAPPING
+<p> The output directory root
+can be set in the sisurc.yml file. Under the root, subdirectories are made
+for each directory in which a document set resides. If you have a directory
+named poems or conventions, that directory will be created under the output
+directory root and the output for all documents contained in the directory
+of a particular name will be generated to subdirectories beneath that directory
+(poem or conventions). A document will be placed in a subdirectory of the
+same name as the document with the filetype identifier stripped (.sst .ssm)
+
+<p> The last part of a directory path, representing the sub-directory in which
+a document set resides, is the directory name that will be used for the
+output directory. This has implications for the organisation of document
+collections as it could make sense to place documents of a particular subject,
+or type within a directory identifying them. This grouping as suggested
+could be by subject (sales_law, english_literature); or just as conveniently
+by some other classification (X University). The mapping means it is also
+possible to place in the same output directory documents that are for organisational
+purposes kept separately, for example documents on a given subject of two
+different institutions may be kept in two different directories of the
+same name, under a directory named after each institution, and these would
+be output to the same output directory. Skins could be associated with each
+institution on a directory basis and resulting documents will take on the
+appropriate different appearance.
+<p>
+<p> 18. HOMEPAGES
+<p> <b>SiSU</b> is about the ability
+to auto-generate documents. Home pages are regarded as custom built items,
+and are not created by <b>SiSU</b> <b>SiSU</b> has a default home page, which will not
+be appropriate for use with other sites, and the means to provide your
+own home page instead in one of two ways as part of a site&rsquo;s configuration,
+these being:
+<p> 1. through placing your home page and other custom built
+documents in the subdirectory _sisu/home/ (this probably being the easier
+and more convenient option)
+<p> 2. through providing what you want as the
+home page in a skin,
+<p> Document sets are contained in directories, usually
+organised by site or subject. Each directory can/should have its own homepage.
+See the section on directory structure and organisation of content.
+<p> 18.1
+
+<p>HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY
+<p> Custom built
+pages, including the home page index.html may be placed within the configuration
+directory _sisu/home/ in any of the locations that is searched for the
+configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu From there
+they are copied to the root of the output directory with the command:
+<p>
+ sisu -CC<br>
+
+<p> 18.2 HOME PAGE WITHIN A SKIN
+<p> Skins are described in a separate section,
+but basically are a file written in the programming language <b>Ruby</b> that
+may be provided to change the defaults that are provided with sisu with
+respect to individual documents, a directories contents or for a site.
+<p>
+ If you wish to provide a homepage within a skin the skin should be in
+the directory _sisu/skin/dir and have the name of the directory for which
+it is to become the home page. Documents in the directory commercial_law
+would have the homepage modified in skin_commercial law.rb; or the directory
+
+<p>poems in skin_poems.rb
+<p>
+<p> <br>
+<pre> class Home
+ def homepage
+ # place the html content of your homepage here, this will become
+index.html
+ &lt;&lt;HOME &lt;html&gt;
+ &lt;head&gt;&lt;/head&gt;
+ &lt;doc&gt;
+ &lt;p&gt;this is my new homepage.&lt;/p&gt;
+ &lt;/doc&gt;
+ &lt;/html&gt;
+ HOME
+ end
+ end
+</pre>
+<p> 19. MARKUP AND OUTPUT EXAMPLES
+<p> 19.1 MARKUP EXAMPLES
+<p> Current markup examples
+and document output samples are provided at &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
+&gt;
+
+<p> Some markup with syntax highlighting may be found under &lt;<a href='http://www.jus.uio.no/sisu/sample/syntax'>http://www.jus.uio.no/sisu/sample/syntax</a>
+&gt;
+but is not as up to date.
+<p> For some documents hardly any markup at all
+is required at all, other than a header, and an indication that the levels
+to be taken into account by the program in generating its output are.
+<p> 20.
+SISU SEARCH - INTRODUCTION
+<p> <b>SiSU</b> output can easily and conveniently be
+indexed by a number of standalone indexing tools, such as Lucene, Hyperestraier.
+
+<p> Because the document structure of sites created is clearly defined, and
+the text object citation system is available hypothetically at least, for
+all forms of output, it is possible to search the sql database, and either
+read results from that database, or just as simply map the results to the
+html output, which has richer text markup.
+<p> In addition to this <b>SiSU</b> has
+the ability to populate a relational sql type database with documents at
+an object level, with objects numbers that are shared across different
+output types, which make them searchable with that degree of granularity.
+Basically, your match criteria is met by these documents and at these locations
+within each document, which can be viewed within the database directly
+or in various output formats.
+<p> 21. SQL
+<p> 21.1 POPULATING SQL TYPE DATABASES
+
+<p> <b>SiSU</b> feeds sisu markupd documents into sql type databases PostgreSQL[^19]
+and/or SQLite[^20] database together with information related to document
+structure.
+<p> This is one of the more interesting output forms, as all the
+structural data of the documents are retained (though can be ignored by
+the user of the database should they so choose). All site texts/documents
+are (currently) streamed to four tables:
+<p> * one containing semantic
+(and other) headers, including, title, author,<br>
+ subject, (the Dublin Core...);<br>
+
+<p> * another the substantive texts by individual "paragraph" (or object)
+-<br>
+ along with structural information, each paragraph being identifiable
+by its<br>
+ paragraph number (if it has one which almost all of them do), and the<br>
+ substantive text of each paragraph quite naturally being searchable
+(both in<br>
+ formatted and clean text versions for searching); and<br>
+
+<p> * a third containing endnotes cross-referenced back to the paragraph
+from<br>
+ which they are referenced (both in formatted and clean text versions
+for<br>
+ searching).<br>
+
+<p> * a fourth table with a one to one relation with the headers table
+contains<br>
+ full text versions of output, eg. pdf, html, xml, and ascii.<br>
+
+<p> There is of course the possibility to add further structures.
+<p> At this
+level <b>SiSU</b> loads a relational database with documents chunked into objects,
+their smallest logical structurally constituent parts, as text objects,
+with their object citation number and all other structural information
+needed to construct the document. Text is stored (at this text object level)
+with and without elementary markup tagging, the stripped version being
+so as to facilitate ease of searching.
+<p> Being able to search a relational
+database at an object level with the <b>SiSU</b> citation system is an effective
+way of locating content generated by <b>SiSU</b> object numbers, and all versions
+of the document have the same numbering, complex searches can be tailored
+to return just the locations of the search results relevant for all available
+output formats, with live links to the precise locations in the database
+or in html/xml documents; or, the structural information provided makes
+it possible to search the full contents of the database and have headings
+in which search content appears, or to search only headings etc. (as the
+Dublin Core is incorporated it is easy to make use of that as well).
+<p> 22.
+POSTGRESQL
+<p> 22.1 NAME
+<p> <b>SiSU</b> - Structured information, Serialized Units
+- a document publishing system, postgresql dependency package
+<p> 22.2 DESCRIPTION
+
+<p> Information related to using postgresql with sisu (and related to the
+sisu_postgresql dependency package, which is a dummy package to install
+dependencies needed for <b>SiSU</b> to populate a postgresql database, this being
+part of <b>SiSU</b> - man sisu).
+<p> 22.3 SYNOPSIS
+<p> sisu -D [instruction] [filename/wildcard
+&nbsp;if &nbsp;required]<br>
+
+<p> sisu -D --pg --[instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
+
+<p> 22.4 COMMANDS
+<p> Mappings to two databases are provided by default, postgresql
+and sqlite, the same commands are used within sisu to construct and populate
+databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
+postgresql, alternatively --sqlite or --pgsql may be used
+<p> <b>-D or --pgsql</b> may
+be used interchangeably.
+<p> 22.4.1 CREATE AND DESTROY DATABASE
+<p>
+<dl>
+
+<dt><b>--pgsql --createall</b>
+</dt>
+<dd>initial step, creates required relations (tables, indexes) in existing
+(postgresql) database (a database should be created manually and given
+the same name as working directory, as requested) (rb.dbi)
+<p> </dd>
+
+<dt><b>sisu -D --createdb</b>
+</dt>
+<dd>
+<p>creates database where no database existed before
+<p> </dd>
+
+<dt><b>sisu -D --create</b> </dt>
+<dd>creates
+
+<p>database tables where no database tables existed before
+<p> </dd>
+
+<dt><b>sisu -D --Dropall</b>
+</dt>
+<dd>destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories
+of the same name).
+<p> </dd>
+
+<dt><b>sisu -D --recreate</b> </dt>
+<dd>destroys existing database and builds
+
+<p>a new empty database structure
+<p> </dd>
+</dl>
+22.4.2 IMPORT AND REMOVE DOCUMENTS
+<p>
+<dl>
+
+<dt><b>sisu
+-D --import -v [filename/wildcard]</b> </dt>
+<dd>populates database with the contents of
+the file. Imports documents(s) specified to a postgresql database (at an
+object level).
+<p> </dd>
+
+<dt><b>sisu -D --update -v [filename/wildcard]</b> </dt>
+<dd>updates file contents
+
+<p>in database
+<p> </dd>
+
+<dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt>
+<dd>removes specified document
+from postgresql database.
+<p> </dd>
+</dl>
+23. SQLITE
+<p> 23.1 NAME
+<p> <b>SiSU</b> - Structured information,
+Serialized Units - a document publishing system.
+<p> 23.2 DESCRIPTION
+<p> Information
+related to using sqlite with sisu (and related to the sisu_sqlite dependency
+package, which is a dummy package to install dependencies needed for <b>SiSU</b>
+to populate an sqlite database, this being part of <b>SiSU</b> - man sisu).
+<p> 23.3
+
+<p>SYNOPSIS
+<p> sisu -d [instruction] [filename/wildcard &nbsp;if &nbsp;required]<br>
+
+<p> sisu -d --(sqlite|pg) --[instruction] [filename/wildcard &nbsp;if <br>
+ required]<br>
+
+<p> 23.4 COMMANDS
+<p> Mappings to two databases are provided by default, postgresql
+and sqlite, the same commands are used within sisu to construct and populate
+databases however -d (lowercase) denotes sqlite and -D (uppercase) denotes
+postgresql, alternatively --sqlite or --pgsql may be used
+<p> <b>-d or --sqlite</b> may
+be used interchangeably.
+<p> 23.4.1 CREATE AND DESTROY DATABASE
+<p>
+<dl>
+
+<dt><b>--sqlite --createall</b>
+</dt>
+<dd>initial step, creates required relations (tables, indexes) in existing
+(sqlite) database (a database should be created manually and given the
+same name as working directory, as requested) (rb.dbi)
+<p> </dd>
+
+<dt><b>sisu -d --createdb</b>
+</dt>
+<dd>
+<p>creates database where no database existed before
+<p> </dd>
+
+<dt><b>sisu -d --create</b> </dt>
+<dd>creates
+
+<p>database tables where no database tables existed before
+<p> </dd>
+
+<dt><b>sisu -d --dropall</b>
+</dt>
+<dd>destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories
+of the same name).
+<p> </dd>
+
+<dt><b>sisu -d --recreate</b> </dt>
+<dd>destroys existing database and builds
+
+<p>a new empty database structure
+<p> </dd>
+</dl>
+23.4.2 IMPORT AND REMOVE DOCUMENTS
+<p>
+<dl>
+
+<dt><b>sisu
+-d --import -v [filename/wildcard]</b> </dt>
+<dd>populates database with the contents of
+the file. Imports documents(s) specified to an sqlite database (at an object
+level).
+<p> </dd>
+
+<dt><b>sisu -d --update -v [filename/wildcard]</b> </dt>
+<dd>updates file contents in database
+
+<p> </dd>
+
+<dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt>
+<dd>removes specified document from sqlite
+database.
+<p> </dd>
+</dl>
+24. INTRODUCTION
+<p> 24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING
+DATABASE AND SISU FEATURES, INCLUDING OBJECT CITATION NUMBERING (BACKEND
+CURRENTLY POSTGRESQL)
+<p> Sample search frontend &lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
+&gt;
+[^21] A small database and sample query front-end (search from) that makes
+use of the citation system, <i>object</i> citation numbering to demonstrates functionality.[^22]
+
+<p> <b>SiSU</b> can provide information on which documents are matched and at what
+locations within each document the matches are found. These results are
+relevant across all outputs using object citation numbering, which includes
+html, XML, EPUB, LaTeX, PDF and indeed the SQL database. You can then refer
+to one of the other outputs or in the SQL database expand the text within
+the matched objects (paragraphs) in the documents matched.
+<p> Note you may
+set results either for documents matched and object number locations within
+each matched document meeting the search criteria; or display the names
+of the documents matched along with the objects (paragraphs) that meet
+the search criteria.[^23]
+<p>
+<dl>
+
+<dt><b>sisu -F --webserv-webrick</b> </dt>
+<dd>builds a cgi web search
+
+<p>frontend for the database created
+<p> The following is feedback on the setup
+on a machine provided by the help command:
+<p> sisu --help sql<br>
+
+<p>
+<p> <br>
+<pre> Postgresql
+ user: ralph
+ current db set: SiSU_sisu
+ port: 5432
+ dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
+ sqlite
+ current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
+ dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
+</pre>
+<p> Note on databases built
+<p> By default, [unless &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>
+24.2 SEARCH FORM
+<p>
+<dl>
+
+<dt><b>sisu -F</b> </dt>
+<dd>generates a sample search form, which must
+
+<p>be copied to the web-server cgi directory
+<p> </dd>
+
+<dt><b>sisu -F --webserv-webrick</b> </dt>
+<dd>generates
+a sample search form for use with the webrick server, which must be copied
+
+<p>to the web-server cgi directory
+<p> </dd>
+
+<dt><b>sisu -Fv</b> </dt>
+<dd>as above, and provides some information
+
+<p>on setting up hyperestraier
+<p> </dd>
+
+<dt><b>sisu -W</b> </dt>
+<dd>starts the webrick server which should
+
+<p>be available wherever sisu is properly installed
+<p> The generated search
+
+<p>form must be copied manually to the webserver directory as instructed
+<p>
+</dd>
+</dl>
+25. HYPERESTRAIER
+<p> See the documentation for hyperestraier:
+<p> &lt;<a href='http://hyperestraier.sourceforge.net/'>http://hyperestraier.sourceforge.net/</a>
+&gt;<br>
+
+<p> /usr/share/doc/hyperestraier/index.html<br>
+
+<p> man estcmd<br>
+
+<p> NOTE: the examples that follow assume that sisu output is placed in
+
+<p>the directory /home/ralph/sisu_www
+<p> (A) to generate the index within the
+webserver directory to be indexed:
+<p> estcmd gather -sd [index &nbsp;name] [directory
+&nbsp;path &nbsp;to &nbsp;index]<br>
+
+<p> the following are examples that will need to be tailored according to
+your needs:
+<p> cd /home/ralph/sisu_www<br>
+
+<p> estcmd gather -sd casket /home/ralph/sisu_www<br>
+
+<p> you may use the &rsquo;find&rsquo; command together with &rsquo;egrep&rsquo; to limit indexing to
+particular document collection directories within the web server directory:
+
+<p> find /home/ralph/sisu_www -type f | egrep<br>
+ &rsquo;/home/ralph/sisu_www/sisu/.+?.html$&rsquo; |estcmd gather -sd casket -<br>
+
+<p> Check which directories in the webserver/output directory (~/sisu_www
+or elsewhere depending on configuration) you wish to include in the search
+index.
+<p> As sisu duplicates output in multiple file formats, it it is probably
+preferable to limit the estraier index to html output, and as it may also
+be desirable to exclude files &rsquo;plain.txt&rsquo;, &rsquo;toc.html&rsquo; and &rsquo;concordance.html&rsquo;, as
+these duplicate information held in other html output e.g.
+<p> find /home/ralph/sisu_www
+-type f | egrep<br>
+ &rsquo;/sisu_www/(sisu|bookmarks)/.+?.html$&rsquo; | egrep -v<br>
+ &rsquo;(doc|concordance).html$&rsquo; |estcmd gather -sd casket -<br>
+
+<p> from your current document preparation/markup directory, you would construct
+a rune along the following lines:
+<p> find /home/ralph/sisu_www -type f
+| egrep &rsquo;/home/ralph/sisu_www/([specify <br>
+ first &nbsp;directory &nbsp;for &nbsp;inclusion]|[specify &nbsp;second &nbsp;directory &nbsp;for <br>
+ inclusion]|[another &nbsp;directory &nbsp;for &nbsp;inclusion? &nbsp;...])/.+?.html$&rsquo; |<br>
+ egrep -v &rsquo;(doc|concordance).html$&rsquo; |estcmd gather -sd<br>
+ /home/ralph/sisu_www/casket -<br>
+
+<p> (B) to set up the search form
+<p> (i) copy estseek.cgi to your cgi directory
+and set file permissions to 755:
+<p> sudo cp -vi /usr/lib/estraier/estseek.cgi
+/usr/lib/cgi-bin<br>
+
+<p> sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi<br>
+
+<p> sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin<br>
+
+<p> [see &nbsp;estraier &nbsp;documentation &nbsp;for &nbsp;paths]<br>
+
+<p> (ii) edit estseek.conf, with attention to the lines starting &rsquo;indexname:&rsquo;
+and &rsquo;replace:&rsquo;:
+<p> indexname: /home/ralph/sisu_www/casket<br>
+
+<p> replace: ^file:///home/ralph/sisu_www{{!}}<a href='http://localhost'>http://localhost</a>
+<br>
+
+<p> replace: /index.html?${{!}}/<br>
+
+<p> (C) to test using webrick, start webrick:
+<p> sisu -W<br>
+
+<p> and try open the url: &lt;<a href='http://localhost:8081/cgi-bin/estseek.cgi'>http://localhost:8081/cgi-bin/estseek.cgi</a>
+&gt;
+<p> 26. SISU_WEBRICK
+
+<p> 26.1 NAME
+<p> <b>SiSU</b> - Structured information, Serialized Units - a document
+
+<p>publishing system
+<p> 26.2 SYNOPSIS
+<p> sisu_webrick [port]
+<p> or
+<p> sisu -W [port]
+
+<p> 26.3 DESCRIPTION
+<p> sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick
+starts <b>Ruby</b> &rsquo;s Webrick web-server and points it to the directories to which
+<b>SiSU</b> output is written, providing a list of these directories (assuming
+<b>SiSU</b> is in use and they exist).
+<p> The default port for sisu_webrick is set
+to 8081, this may be modified in the yaml file: ~/.sisu/sisurc.yml a sample
+of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory
+on your system).
+<p> 26.4 SUMMARY OF MAN PAGE
+<p> sisu_webrick, may be started
+on it&rsquo;s own with the command: sisu_webrick [port] or using the sisu command
+with the -W flag: sisu -W [port]
+<p> where no port is given and settings are
+
+<p>unchanged the default port is 8081
+<p> 26.5 DOCUMENT PROCESSING COMMAND FLAGS
+
+<p> sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories,
+on the port provided, or if no port is provided and the defaults have not
+
+<p>been changed in ~/.sisu/sisurc.yaml then on port 8081
+<p> 26.6 FURTHER INFORMATION
+
+<p> For more information on <b>SiSU</b> see: &lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+<p> or man sisu
+
+<p> 26.7 AUTHOR
+<p> Ralph Amissah ralph@amissah.com or ralph.amissah@gmail.com
+<p>
+
+<p>26.8 SEE ALSO
+<p> <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a>
+<br>
+
+<p> <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a>
+<br>
+
+<p> <a href='http:~/bin/man2html?sisu:8'>sisu(8)</a>
+<br>
+
+<p> 27. REMOTE SOURCE DOCUMENTS
+<p> <b>SiSU</b> processing instructions can be run
+against remote source documents by providing the url of the documents against
+which the processing instructions are to be carried out. The remote <b>SiSU</b>
+documents can either be sisu marked up files in plaintext .sst or .ssm or;
+zipped sisu files, sisupod.zip or filename.ssp
+<p> <b>.sst / .ssm - sisu text files</b>
+
+<p> <b>SiSU</b> can be run against source text files on a remote machine, provide
+the processing instruction and the url. The source file and any associated
+parts (such as images) will be downloaded and generated locally.
+<p>
+<p> <br>
+<pre> sisu -3 http://[provide &nbsp;url &nbsp;to &nbsp;valid &nbsp;.sst &nbsp;or &nbsp;.ssm &nbsp;file]
+</pre>
+<p> Any of the source documents in the sisu examples page can be used in
+this way, see &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
+&gt; and use the url
+for the desired document.
+<p> NOTE: to set up a remote machine to serve <b>SiSU</b>
+documents in this way, images should be in the directory relative to the
+
+<p>document source ../_sisu/image
+<p> <b>sisupod - zipped sisu files</b>
+<p> A sisupod is
+the zipped content of a sisu marked up text or texts and any other associated
+parts to the document such as images.
+<p> <b>SiSU</b> can be run against a sisupod
+on a (local or) remote machine, provide the processing instruction and
+the url, the sisupod will be downloaded and the documents it contains generated
+locally.
+<p>
+<p> <br>
+<pre> sisu -3 http://[provide &nbsp;url &nbsp;to &nbsp;valid &nbsp;sisupod.zip &nbsp;or &nbsp;.ssp &nbsp;file]
+</pre>
+<p> Any of the source documents in the sisu examples page can be used in
+this way, see &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
+&gt; and use the url
+for the desired document.
+<p> REMOTE DOCUMENT OUTPUT
+<p> 28. REMOTE OUTPUT
+<p>
+Once properly configured <b>SiSU</b> output can be automatically posted once generated
+to a designated remote machine using either rsync, or scp.
+<p> In order to
+do this some ssh authentication agent and keychain or similar tool will
+need to be configured. Once that is done the placement on a remote host
+can be done seamlessly with the -r (for scp) or -R (for rsync) flag, which
+may be used in conjunction with other processing flags, e.g.
+<p>
+<p> <br>
+<pre> sisu -3R sisu_remote.sst
+</pre>
+<p> 28.1 COMMANDS
+<p>
+<dl>
+
+<dt><b>-R [filename/wildcard]</b> </dt>
+<dd>copies sisu output files to remote
+host using rsync. This requires that sisurc.yml has been provided with information
+on hostname and username, and that you have your different if -R is used
+with other flags from if used alone. Alone the rsync --delete parameter is
+sent, useful for cleaning the remote directory (when -R is used together
+with other flags, it is not). Also see -r
+<p> </dd>
+
+<dt><b>-r [filename/wildcard]</b> </dt>
+<dd>copies sisu
+output files to remote host using scp. This requires that sisurc.yml has
+been provided with information on hostname and username, and that you have
+
+<p>your
+<p> </dd>
+</dl>
+28.2 CONFIGURATION
+<p> [expand &nbsp;on &nbsp;the &nbsp;setting &nbsp;up &nbsp;of &nbsp;an &nbsp;ssh-agent &nbsp;/ &nbsp;keychain]
+
+<p> 29. REMOTE SERVERS
+<p> As <b>SiSU</b> is generally operated using the command line,
+and works within a Unix type environment, <b>SiSU</b> the program and all documents
+can just as easily be on a remote server, to which you are logged on using
+a terminal, and commands and operations would be pretty much the same as
+they would be on your local machine.
+<p> 30. QUICKSTART - GETTING STARTED HOWTO
+
+<p> 30.1 INSTALLATION
+<p> Installation is currently most straightforward and
+tested on the <b>Debian</b> platform, as there are packages for the installation
+of sisu and all requirements for what it does.
+<p> 30.1.1 DEBIAN INSTALLATION
+
+<p> <b>SiSU</b> is available directly from the <b>Debian</b> Sid and testing archives (and
+possibly Ubuntu), assuming your /etc/apt/sources.list is set accordingly:
+
+<p>
+<p> <br>
+<pre> aptitude update
+ aptitude install sisu-complete
+</pre>
+<p> The following /etc/apt/sources.list setting permits the download of additional
+markup samples:
+<p>
+<p> <br>
+<pre> #/etc/apt/sources.list
+ deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
+ deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib
+ d
+</pre>
+<p> The aptitude commands become:
+<p>
+<p> <br>
+<pre> aptitude update
+ aptitude install sisu-complete sisu-markup-samples
+</pre>
+<p> If there are newer versions of <b>SiSU</b> upstream of the <b>Debian</b> archives,
+
+<p>they will be available by adding the following to your /etc/apt/sources.list
+
+<p>
+<p> <br>
+<pre> #/etc/apt/sources.list
+ deb http://www.jus.uio.no/sisu/archive unstable main non-free
+ deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+</pre>
+<p> repeat the aptitude commands
+<p>
+<p> <br>
+<pre> aptitude update
+ aptitude install sisu-complete sisu-markup-samples
+</pre>
+<p> Note however that it is not necessary to install sisu-complete if not
+all components of sisu are to be used. Installing just the package sisu
+will provide basic functionality.
+<p> 30.1.2 RPM INSTALLATION
+<p> RPMs are provided
+though untested, they are prepared by running alien against the source
+package, and against the debs.
+<p> They may be downloaded from:
+<p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html#rpm'>http://www.jus.uio.no/sisu/SiSU/download.html#rpm</a>
+&gt;<br>
+
+<p> as root type:
+<p> rpm -i [rpm &nbsp;package &nbsp;name]<br>
+
+<p> 30.1.3 INSTALLATION FROM SOURCE
+<p> To install <b>SiSU</b> from source check information
+at:
+<p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/download.html#current'>http://www.jus.uio.no/sisu/SiSU/download.html#current</a>
+&gt;<br>
+
+<p> * download the source package
+<p> * Unpack the source
+<p> Two alternative
+modes of installation from source are provided, setup.rb (by Minero Aoki)
+and a rant(by Stefan Lang) built install file, in either case: the first
+steps are the same, download and unpack the source file:
+<p> For basic use
+<b>SiSU</b> is only dependent on the programming language in which it is written
+<b>Ruby</b> , and <b>SiSU</b> will be able to generate html, EPUB, various XMLs, including
+ODF (and will also produce LaTeX). Dependencies required for further actions,
+though it relies on the installation of additional dependencies which the
+source tarball does not take care of, for things like using a database
+(postgresql or sqlite)[^24] or converting LaTeX to pdf.
+<p> <b>setup.rb</b>
+<p> This
+is a standard ruby installer, using setup.rb is a three step process. In
+the root directory of the unpacked <b>SiSU</b> as root type:
+<p>
+<p> <br>
+<pre> ruby setup.rb config
+ ruby setup.rb setup
+ #[and &nbsp;as &nbsp;root:]
+ ruby setup.rb install
+</pre>
+<p> further information on setup.rb is available from:
+<p> &lt;<a href='http://i.loveruby.net/en/projects/setup/'>http://i.loveruby.net/en/projects/setup/</a>
+&gt;<br>
+
+<p> &lt;<a href='http://i.loveruby.net/en/projects/setup/doc/usage.html'>http://i.loveruby.net/en/projects/setup/doc/usage.html</a>
+&gt;<br>
+
+<p> <b></b>
+<p> The root directory of the unpacked <b>SiSU</b> as root type:
+<p> ruby install
+base<br>
+
+<p> or for a more complete installation:
+<p> ruby install<br>
+
+<p> or
+<p> ruby install base<br>
+
+<p> This makes use of Rant (by Stefan Lang) and the provided Rantfile. It
+has been configured to do post installation setup setup configuration and
+generation of first test file. Note however, that additional external package
+dependencies, such as tetex-extra are not taken care of for you.
+<p> Further
+
+<p>information on
+<p> &lt;<a href='http://make.rubyforge.org/'>http://make.rubyforge.org/</a>
+&gt;<br>
+
+<p> &lt;<a href='http://rubyforge.org/frs/?group_id=615'>http://rubyforge.org/frs/?group_id=615</a>
+&gt;<br>
+
+<p> For a list of alternative actions you may type:
+<p> ruby install help<br>
+
+<p> ruby install -T<br>
+
+<p> 30.2 TESTING SISU, GENERATING OUTPUT
+<p> To check which version of sisu
+is installed:
+<p> sisu -v
+<p> Depending on your mode of installation one or
+a number of markup sample files may be found either in the directory:
+<p>
+
+<p> or
+<p>
+<p> change directory to the appropriate one:
+<p> cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
+
+<p> 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB
+<p> Having moved to the
+directory that contains the markup samples (see instructions above if necessary),
+
+<p>choose a file and run sisu against it
+<p> sisu -NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+<p> this will generate html including a concordance file, opendocument text
+format, plaintext, XHTML and various forms of XML, and OpenDocument text
+
+<p> 30.2.2 LATEX / PDF
+<p> Assuming a LaTeX engine such as tetex or texlive is
+installed with the required modules (done automatically on selection of
+sisu-pdf in <b>Debian</b> )
+<p> Having moved to the directory that contains the markup
+samples (see instructions above if necessary), choose a file and run sisu
+
+<p>against it
+<p> sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+<p> sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+<p> should
+generate most available output formats: html including a concordance file,
+opendocument text format, plaintext, XHTML and various forms of XML, and
+
+<p>OpenDocument text and pdf
+<p> 30.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE
+
+<p> Relational databases need some setting up - you must have permission to
+create the database and write to it when you run sisu.
+<p> Assuming you have
+
+<p>the database installed and the requisite permissions
+<p> sisu --sqlite --recreate
+
+<p> sisu --sqlite -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+<p> sisu --pgsql --recreate
+<p> sisu --pgsql -v --import free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+<p> 30.3 GETTING HELP
+<p> 30.3.1 THE MAN PAGES
+<p> Type:
+<p> man sisu<br>
+
+<p> The man pages are also available online, though not always kept as up
+to date as within the package itself:
+<p> * sisu.1 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a>
+&gt;
+[^25]
+<p> * sisu.8 &lt;<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a>
+&gt; [^26]
+<p> * man directory
+&lt;<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a>
+&gt; [^27]
+<p> 30.3.2 BUILT IN HELP
+<p> sisu --help
+<p> sisu
+
+<p>-
+<p>-
+<p>help --env
+<p> sisu --help --commands
+<p> sisu --help --markup
+<p> 30.3.3 THE HOME PAGE
+<p>
+&lt;<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a>
+&gt;
+<p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU'>http://www.jus.uio.no/sisu/SiSU</a>
+&gt;
+<p> 30.4 MARKUP SAMPLES
+
+<p> A number of markup samples (along with output) are available off:
+<p> &lt;<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a>
+&gt;
+
+<p> Additional markup samples are packaged separately in the file:
+<p> <b>*</b>
+<p>
+On <b>Debian</b> they are available in non-free[^28] to include them it is necessary
+to include non-free in your /etc/apt/source.list or obtain them from the
+sisu home site.
+<p> 31. EDITOR FILES, SYNTAX HIGHLIGHTING
+<p> The directory:
+
+<p> ./data/sisu/v2/conf/editor-syntax-etc/<br>
+
+<p> /usr/share/sisu/v2/conf/editor-syntax-etc<br>
+
+<p> contains rudimentary sisu syntax highlighting files for:
+<p> * (g)vim
+&lt;<a href='http://www.vim.org'>http://www.vim.org</a>
+&gt;
+<p> package: sisu-vim<br>
+
+<p> status: largely done
+<p> there is a vim syntax highlighting and folds
+component<br>
+
+<p> * gedit &lt;<a href='http://www.gnome.org/projects/gedit'>http://www.gnome.org/projects/gedit</a>
+&gt;
+<p> * gobby &lt;<a href='http://gobby.0x539.de/'>http://gobby.0x539.de/</a>
+&gt;
+
+<p> file: sisu.lang<br>
+
+<p> place in:
+<p> /usr/share/gtksourceview-1.0/language-specs<br>
+
+<p> or
+<p> ~/.gnome2/gtksourceview-1.0/language-specs<br>
+
+<p> status: very basic syntax highlighting<br>
+
+<p> comments: this editor features display line wrap and is used by Goby!<br>
+
+<p> * nano &lt;<a href='http://www.nano-editor.org'>http://www.nano-editor.org</a>
+&gt;
+<p> file: nanorc<br>
+
+<p> save as:
+<p> ~/.nanorc<br>
+
+<p> status: basic syntax highlighting<br>
+
+<p> comments: assumes dark background; no display line-wrap; does line
+breaks<br>
+
+<p> * diakonos (an editor written in ruby) &lt;<a href='http://purepistos.net/diakonos'>http://purepistos.net/diakonos</a>
+&gt;
+
+<p> file: diakonos.conf
+<p> save as:
+<p> ~/.diakonos/diakonos.conf<br>
+
+<p> includes:
+<p> status: basic syntax highlighting<br>
+
+<p> comments: assumes dark background; no display line-wrap
+<p> * kate &amp; kwrite
+&lt;<a href='http://kate.kde.org'>http://kate.kde.org</a>
+&gt;
+<p> file: sisu.xml<br>
+
+<p> place in:<br>
+
+<p> /usr/share/apps/katepart/syntax<br>
+
+<p> or<br>
+
+<p> ~/.kde/share/apps/katepart/syntax<br>
+
+<p> [settings::configure &nbsp;kate::{highlighting,filetypes}]<br>
+
+<p> [tools::highlighting::{markup,scripts}:: &nbsp;.B &nbsp;SiSU &nbsp;]<br>
+
+<p> * nedit &lt;<a href='http://www.nedit.org'>http://www.nedit.org</a>
+&gt;
+<p> file: sisu_nedit.pats<br>
+
+<p> nedit -import sisu_nedit.pats<br>
+
+<p> status: a very clumsy first attempt [not &nbsp;really &nbsp;done]<br>
+
+<p> comments: this editor features display line wrap<br>
+
+<p> * emacs &lt;<a href='http://www.gnu.org/software/emacs/emacs.html'>http://www.gnu.org/software/emacs/emacs.html</a>
+&gt;
+<p> files: sisu-mode.el<br>
+
+<p> to file ~/.emacs add the following 2 lines:<br>
+
+<p> (add-to-list &rsquo;load-path<br>
+
+<p> (require &rsquo;sisu-mode.el)<br>
+
+<p> [not &nbsp;done &nbsp;/ &nbsp;not &nbsp;yet &nbsp;included]<br>
+
+<p> * vim &amp; gvim &lt;<a href='http://www.vim.org'>http://www.vim.org</a>
+&gt;
+<p> files:<br>
+
+<p> package is the most comprehensive sisu syntax highlighting and editor<br>
+ environment provided to date (is for vim/ gvim, and is separate from
+the<br>
+ contents of this directory)<br>
+
+<p> status: this includes: syntax highlighting; vim folds; some error
+checking<br>
+
+<p> comments: this editor features display line wrap<br>
+
+<p> NOTE:
+<p> [ &nbsp;.B &nbsp;SiSU &nbsp;parses &nbsp;files &nbsp;with &nbsp;long &nbsp;lines &nbsp;or &nbsp;line &nbsp;breaks, &nbsp;display
+&nbsp;linewrap &nbsp;(without &nbsp;line-breaks) &nbsp;is &nbsp;a &nbsp;convenient editor &nbsp;feature &nbsp;to &nbsp;have &nbsp;for
+&nbsp;sisu &nbsp;markup]
+<p> 32. HOW DOES SISU WORK?
+<p> <b>SiSU</b> markup is fairly minimalistic,
+it consists of: a (largely optional) document header, made up of information
+about the document (such as when it was published, who authored it, and
+granting what rights) and any processing instructions; and markup within
+the substantive text of the document, which is related to document structure
+and typeface. <b>SiSU</b> must be able to discern the structure of a document,
+(text headings and their levels in relation to each other), either from
+information provided in the document header or from markup within the text
+(or from a combination of both). Processing is done against an abstraction
+of the document comprising of information on the document&rsquo;s structure and
+its objects,[2] which the program serializes (providing the object numbers)
+and which are assigned hash sum values based on their content. This abstraction
+of information about document structure, objects, (and hash sums), provides
+considerable flexibility in representing documents different ways and for
+different purposes (e.g. search, document layout, publishing, content certification,
+concordance etc.), and makes it possible to take advantage of some of the
+strengths of established ways of representing documents, (or indeed to
+create new ones).
+<p> 33. SUMMARY OF FEATURES
+<p> * sparse/minimal markup (clean
+utf-8 source texts). Documents are prepared in a single UTF-8 file using a
+minimalistic mnemonic syntax. Typical literature, documents like headers
+are optional.
+<p> * markup is easily readable/parsable by the human eye, (basic
+markup is simpler and more sparse than the most basic HTML), [this &nbsp;may
+&nbsp;also &nbsp;be &nbsp;converted &nbsp;to &nbsp;XML &nbsp;representations &nbsp;of &nbsp;the &nbsp;same &nbsp;input/source &nbsp;document].
+
+<p> * markup defines document structure (this may be done once in a header
+pattern-match description, or for heading levels individually); basic text
+attributes (bold, italics, underscore, strike-through etc.) as required;
+and semantic information related to the document (header information, extended
+beyond the Dublin core and easily further extended as required); the headers
+may also contain processing instructions. <b>SiSU</b> markup is primarily an abstraction
+of document structure and document metadata to permit taking advantage
+of the basic strengths of existing alternative practical standard ways
+of representing documents [be &nbsp;that &nbsp;paper &nbsp;publication, &nbsp;sql &nbsp;search &nbsp;etc.] (html,
+epub, xml, odf, latex, pdf, sql)
+<p> * for output produces reasonably elegant
+output of established industry and institutionally accepted open standard
+formats.[3] takes advantage of the different strengths of various standard
+formats for representing documents, amongst the output formats currently
+supported are:
+<p> * html - both as a single scrollable text and a segmented
+document<br>
+
+<p> * xhtml<br>
+
+<p> * epub<br>
+
+<p> * XML - both in sax and dom style xml structures for further development
+as<br>
+ required<br>
+
+<p> * ODF - open document format, the iso standard for document storage<br>
+
+<p> * LaTeX - used to generate pdf<br>
+
+<p> * pdf (via LaTeX)<br>
+
+<p> * sql - population of an sql database, (at the same object level that
+is<br>
+ used to cite text within a document)<br>
+
+<p> Also produces: concordance files; document content certificates (md5
+or sha256 digests of headings, paragraphs, images etc.) and html manifests
+(and sitemaps of content). (b) takes advantage of the strengths implicit
+in these very different output types, (e.g. PDFs produced using typesetting
+of LaTeX, databases populated with documents at an individual object/paragraph
+level, making possible granular search (and related possibilities))
+<p> *
+ensuring content can be cited in a meaningful way regardless of selected
+output format. Online publishing (and publishing in multiple document formats)
+lacks a useful way of citing text internally within documents (important
+to academics generally and to lawyers) as page numbers are meaningless
+across browsers and formats. sisu seeks to provide a common way of pinpoint
+the text within a document, (which can be utilized for citation and by
+search engines). The outputs share a common numbering system that is meaningful
+(to man and machine) across all digital outputs whether paper, screen,
+or database oriented, (pdf, HTML, EPUB, xml, sqlite, postgresql), this
+numbering system can be used to reference content.
+<p> * Granular search within
+documents. SQL databases are populated at an object level (roughly headings,
+paragraphs, verse, tables) and become searchable with that degree of granularity,
+the output information provides the object/paragraph numbers which are
+relevant across all generated outputs; it is also possible to look at just
+the matching paragraphs of the documents in the database; [output &nbsp;indexing
+&nbsp;also &nbsp;work &nbsp;well &nbsp;with &nbsp;search &nbsp;indexing tools &nbsp;like &nbsp;hyperestraier].
+<p> <b>*</b>long<b>term</b>maintainability<b>of</b>document<b>collections</b>in<b>a</b>world<b>of</b>changing
+formats, having a very sparsely marked-up source document base. there is
+a considerable degree of future-proofing, output representations are upgradeable
+(open document text) module in 2006, epub in 2009 and in future html5 output
+sometime in future, without modification of existing prepared texts
+<p> *
+SQL search aside, documents are generated as required and static once generated.
+
+<p> * documents produced are static files, and may be batch processed, this
+needs to be done only once but may be repeated for various reasons as desired
+(updated content, addition of new output formats, updated technology document
+presentations/representations)
+<p> * document source (plaintext utf-8) if
+
+<p>shared on the net may be used as input and processed locally to produce
+
+<p>the different document outputs
+<p> * document source may be bundled together
+(automatically) with associated documents (multiple language versions or
+master document with inclusions) and images and sent as a zip file called
+a sisupod, if shared on the net these too may be processed locally to produce
+
+<p>the desired document outputs
+<p> * generated document outputs may automatically
+be posted to remote sites.
+<p> * for basic document generation, the only software
+dependency is <b>Ruby</b> , and a few standard Unix tools (this covers plaintext,
+HTML, EPUB, XML, ODF, LaTeX). To use a database you of course need that,
+and to convert the LaTeX generated to pdf, a latex processor like tetex
+or texlive.
+<p> * as a developers tool it is flexible and extensible
+<p> Syntax
+highlighting for <b>SiSU</b> markup is available for a number of text editors.
+
+<p> <b>SiSU</b> is less about document layout than about finding a way with little
+markup to be able to construct an abstract representation of a document
+that makes it possible to produce multiple representations of it which
+may be rather different from each other and used for different purposes,
+whether layout and publishing, or search of content
+<p> i.e. to be able to
+take advantage from this minimal preparation starting point of some of
+the strengths of rather different established ways of representing documents
+for different purposes, whether for search (relational database, or indexed
+flat files generated for that purpose whether of complete documents, or
+say of files made up of objects), online viewing (e.g. html, xml, pdf), or
+paper publication (e.g. pdf)...
+<p> the solution arrived at is by extracting structural
+information about the document (about headings within the document) and
+by tracking objects (which are serialized and also given hash values) in
+the manner described. It makes possible representations that are quite different
+from those offered at present. For example objects could be saved individually
+and identified by their hashes, with an index of how the objects relate
+to each other to form a document.
+<p> 34. HELP SOURCES
+<p> For a summary of alternative
+ways to get help on <b>SiSU</b> try one of the following:
+<p> <b>man page</b>
+<p> man sisu_help<br>
+
+<p> <b>man2html</b>
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_help.1.html'>http://www.jus.uio.no/sisu/man/sisu_help.1.html</a>
+&gt;<br>
+
+<p> <b>sisu generated output - links to html</b>
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a>
+&gt;<br>
+
+<p> <b>help sources lists</b>
+<p> Alternative sources for this help sources page
+listed here:
+<p> man sisu_help_sources<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
+&gt;<br>
+
+<p> 34.1 MAN PAGES
+<p> 34.1.1 MAN
+<p> man sisu<br>
+
+<p> man 7 sisu_complete<br>
+
+<p> man 7 sisu_pdf<br>
+
+<p> man 7 sisu_postgresql<br>
+
+<p> man 7 sisu_sqlite<br>
+
+<p> man sisu_termsheet<br>
+
+<p> man sisu_webrick<br>
+
+<p> 34.2 SISU GENERATED OUTPUT - LINKS TO HTML
+<p> Note <b>SiSU</b> documentation is
+prepared in <b>SiSU</b> and output is available in multiple formats including
+amongst others html, pdf, odf and epub which may be also be accessed via
+the html pages[^28]
+<p> 34.2.1 WWW.SISUDOC.ORG
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
+&gt;
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_commands/index.html'>http://sisudoc.org/sisu/sisu_commands/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_complete/index.html'>http://sisudoc.org/sisu/sisu_complete/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_configuration/index.html'>http://sisudoc.org/sisu/sisu_configuration/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_description/index.html'>http://sisudoc.org/sisu/sisu_description/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_examples/index.html'>http://sisudoc.org/sisu/sisu_examples/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_faq/index.html'>http://sisudoc.org/sisu/sisu_faq/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_filetypes/index.html'>http://sisudoc.org/sisu/sisu_filetypes/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_help/index.html'>http://sisudoc.org/sisu/sisu_help/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_help_sources/index.html'>http://sisudoc.org/sisu/sisu_help_sources/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_howto/index.html'>http://sisudoc.org/sisu/sisu_howto/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_introduction/index.html'>http://sisudoc.org/sisu/sisu_introduction/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_manual/index.html'>http://sisudoc.org/sisu/sisu_manual/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_markup/index.html'>http://sisudoc.org/sisu/sisu_markup/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_output_overview/index.html'>http://sisudoc.org/sisu/sisu_output_overview/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_pdf/index.html'>http://sisudoc.org/sisu/sisu_pdf/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_postgresql/index.html'>http://sisudoc.org/sisu/sisu_postgresql/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_quickstart/index.html'>http://sisudoc.org/sisu/sisu_quickstart/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_remote/index.html'>http://sisudoc.org/sisu/sisu_remote/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_search/index.html'>http://sisudoc.org/sisu/sisu_search/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_skin/index.html'>http://sisudoc.org/sisu/sisu_skin/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_sqlite/index.html'>http://sisudoc.org/sisu/sisu_sqlite/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html'>http://sisudoc.org/sisu/sisu_syntax_highlighting/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_vim/index.html'>http://sisudoc.org/sisu/sisu_vim/index.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://sisudoc.org/sisu/sisu_webrick/index.html'>http://sisudoc.org/sisu/sisu_webrick/index.html</a>
+&gt;<br>
+
+<p> 34.3 MAN2HTML
+<p> 34.3.1 LOCALLY INSTALLED
+<p> &lt;file:///usr/share/doc/sisu/v2/html/sisu.1.html&gt;
+
+<p> &lt;file:///usr/share/doc/sisu/v2/html/sisu_help.1.html&gt;
+<p> &lt;file:///usr/share/doc/sisu/v2/html/sisu_help_sources.1.html&gt;
+
+<p> /usr/share/doc/sisu/v2/html/sisu.1.html<br>
+
+<p> /usr/share/doc/sisu/v2/html/sisu_pdf.7.html<br>
+
+<p> /usr/share/doc/sisu/v2/html/sisu_postgresql.7.html<br>
+
+<p> /usr/share/doc/sisu/v2/html/sisu_sqlite.7.html<br>
+
+<p> /usr/share/doc/sisu/v2/html/sisu_webrick.1.html<br>
+
+<p> 34.3.2 WWW.JUS.UIO.NO/SISU
+<p> &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> &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;<br>
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_complete.7.html'>http://www.jus.uio.no/sisu/man/sisu_complete.7.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_pdf.7.html'>http://www.jus.uio.no/sisu/man/sisu_pdf.7.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html'>http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html'>http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html</a>
+&gt;<br>
+
+<p> &lt;<a href='http://www.jus.uio.no/sisu/man/sisu_webrick.1.html'>http://www.jus.uio.no/sisu/man/sisu_webrick.1.html</a>
+&gt;<br>
+
+<p>
+<ol>
+<b>.</b><li>objects include: headings, paragraphs, verse, tables, images, but not
+footnotes/endnotes which are numbered separately and tied to the object
+from which they are referenced. </li><b>.</b><li>i.e. the html, pdf, epub, odf outputs are
+each built individually and optimised for that form of presentation, rather
+than for example the html being a saved version of the odf, or the pdf
+being a saved version of the html.
+<p> </li><b>.</b><li>the different heading levels </li><b>.</b><li>units
+of text, primarily paragraphs and headings, also any tables, poems, code-blocks
+</li><b>.</b><li>Specification submitted by Adobe to ISO to become a full open ISO specification
+&lt;<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a>
+&gt; </li><b>.</b><li>ISO standard ISO/IEC 26300:2006
+
+<p> </li><b>.</b><li>An open standard format for e-books
+<p> </dd>
+
+<dt><b>*1.</b> </dt>
+<dd>square brackets </dd>
+
+<dt><b>*2.</b> </dt>
+<dd>square brackets
+</dd>
+
+<dt><b>+1.</b> </dt>
+<dd>square brackets </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a>
+&gt; </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;
+</li><b>.</b><li>From sometime after SiSU 0.58 it should be possible to describe SiSU markup
+using SiSU, which though not an original design goal is useful. </li><b>.</b><li>files should
+be prepared using UTF-8 character encoding </li><b>.</b><li>a footnote or endnote </li><b>.</b><li>self contained
+endnote marker &amp; endnote in one </dd>
+
+<dt><b>*.</b> </dt>
+<dd>unnumbered asterisk footnote/endnote,
+insert multiple asterisks if required </dd>
+
+<dt><b>**.</b> </dt>
+<dd>another unnumbered asterisk footnote/endnote
+</dd>
+
+<dt><b>*3.</b> </dt>
+<dd>editors notes, numbered asterisk footnote/endnote series </dd>
+
+<dt><b>+2.</b> </dt>
+<dd>editors
+notes, numbered asterisk footnote/endnote series </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a>
+&gt;
+</li><b>.</b><li>&lt;<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a>
+&gt; </li><b>.</b><li>Table from the Wealth of Networks by Yochai Benkler
+&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; </li><b>.</b><li>.ssc (for composite)
+is under consideration but ._sst makes clear that this is not a regular
+file to be worked on, and thus less likely that people will have processing.
+It may be however that when the resulting file is shared .ssc is an appropriate
+suffix to use. </li><b>.</b><li>&lt;<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a>
+&gt; &lt;<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a>
+&gt; &lt;<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a>
+&gt;
+</li><b>.</b><li>&lt;<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a>
+&gt; &lt;<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a>
+&gt; </li><b>.</b><li>&lt;<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a>
+&gt;
+</li><b>.</b><li>(which could be extended further with current back-end). As regards scaling
+of the database, it is as scalable as the database (here Postgresql) and
+hardware allow. </li><b>.</b><li>of this feature when demonstrated to an IBM software innovations
+evaluator in 2004 he said to paraphrase: this could be of interest to us.
+We have large document management systems, you can search hundreds of thousands
+of documents and we can tell you which documents meet your search criteria,
+but there is no way we can tell you without opening each document where
+within each your matches are found. </li><b>.</b><li>There is nothing to stop MySQL support
+being added in future. </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.1'>http://www.jus.uio.no/sisu/man/sisu.1</a>
+&gt; </li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man/sisu.8'>http://www.jus.uio.no/sisu/man/sisu.8</a>
+&gt;
+</li><b>.</b><li>&lt;<a href='http://www.jus.uio.no/sisu/man'>http://www.jus.uio.no/sisu/man</a>
+&gt; </li><b>.</b><li>the <b>Debian</b> Free Software guidelines require
+that everything distributed within <b>Debian</b> can be changed - and the documents
+are authors&rsquo; works that while freely distributable are not freely changeable.
+</li><b>.</b><li>
+<p>named index.html or more extensively through sisu_manifest.html
+<p> </li>
+</ol>
+
+<h2><a name='sect2' href='#toc2'>See Also</a></h2>
+<a href='http:~/bin/man2html?sisu:1'><i>sisu</i>(1)</a>
+,
+<br>
+<a href='http:~/bin/man2html?sisu-epub:1'><i>sisu-epub</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-harvest:1'><i>sisu-harvest</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-html:1'><i>sisu-html</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-odf:1'><i>sisu-odf</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-pdf:1'><i>sisu-pdf</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-pg:1'><i>sisu-pg</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-sqlite:1'><i>sisu-sqlite</i>(1)</a>
+, <br>
+<a href='http:~/bin/man2html?sisu-txt:1'><i>sisu-txt</i>(1)</a>
+. <br>
+<a href='http:~/bin/man2html?sisu_vim:7'><i>sisu_vim</i>(7)</a>
+ <br>
+<a href='http:~/bin/man2html?sisu:8'><i>sisu</i>(8)</a>
+
+<p>
+<h2><a name='sect3' href='#toc3'>Homepage</a></h2>
+More information about <b>SiSU</b> can be found at &lt;<a href='http://www.jus.uio.no/sisu/'><i>http://www.jus.uio.no/sisu/</i></a>
+&gt;.
+
+<p>
+<h2><a name='sect4' href='#toc4'>Author</a></h2>
+<b>SiSU</b> was written by Ralph Amissah &lt;<i>ralph@amissah.com</i>&gt;. <p>
+
+<hr><p>
+<a name='toc'><b>Table of Contents</b></a><p>
+<ul>
+<li><a name='toc0' href='#sect0'>Name</a></li>
+<li><a name='toc1' href='#sect1'>Synopsis</a></li>
+<li><a name='toc2' href='#sect2'>See Also</a></li>
+<li><a name='toc3' href='#sect3'>Homepage</a></li>
+<li><a name='toc4' href='#sect4'>Author</a></li>
+</ul>
+</body>
+</html>