documentation update !bibliography & !glossary

1 files changed, 2421 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 00000000..6c5fe255
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,2421 @@
+SISU - README
+=============
+
+INTRODUCTION
+************
+
+INTRODUCTION - WHAT IS SISU?
+----------------------------
+
+*SiSU* is a lightweight markup based document creation and publishing framework
+that is controlled from the command line. Prepare documents for *SiSU* using
+your text editor of choice, then use *SiSU* to generate various output document
+formats.
+
+From a single lightly prepared document (plain-text /UTF-8/) sisu custom builds
+several standard output formats which share a common (text object) numbering
+system for citation of content within a document (that also has implications
+for search). The sisu engine works with an abstraction of the document's
+structure and content from which it is possible to generate different forms of
+representation of the document. *SiSU* produces: plain-text, /HTML/, /XHTML/,
+/XML/, /EPUB/, /ODF/: /ODT/ (Opendocument), /LaTeX/, /PDF/, and populates an
+/SQL/ database (/PostgreSQL/ or /SQLite/) with text objects, roughly, paragraph
+sized chunks so that document searches are done at this level of granularity.
+
+Outputs share a common citation numbering system, associated with text objects
+and any semantic meta-data provided about the document.
+
+*SiSU* also provides concordance files, document content certificates and
+manifests of generated output. Book indexes may be made.
+
+Some document markup samples are provided in the package sisu -markup-samples.
+
+Homepages:
+* <http://www.sisudoc.org/>
+* <http://www.jus.uio.no/sisu>
+
+INSTALL OR RUN WITHOUT INSTALLATION
+***********************************
+
+SOURCE TREE
+-----------
+
+RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
+..........................................................
+
+Download & unpack the latest source tarball
+
+or
+
+Git clone the latest source, to clone the latest source without the repo
+history:
+
+git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
+
+Provided you have *Ruby*, *SiSU* can be run without installation straight from
+the source package directory tree. Run ruby against the full path to bin/sisu
+(in the unzipped source package directory tree)
+
+Note however, that additional external package dependencies, such as texlive
+(for pdfs), sqlite3 or postgresql (for search) should you desire to use them
+are not taken care of for you.
+
+GEM INSTALL
+...........
+
+Gem install, you need to:
+
+(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
+the gem
+
+
+----------------------------------------
+
+GEM INSTALL WITH QI (QUICK INSTALL) SCRIPT
+..........................................
+
+(This requires that ruby -thor is installed).
+
+qi (quick install) can go through the steps required to install the gem:
+
+  qi gem --create --build --install --stable
+
+or
+
+  qi gem --create --build --install --unstable
+
+
+----------------------------------------
+
+GEM INSTALL WITH RAKE
+.....................
+
+Provided you have ruby & rake, this can be done with the single command:
+
+  rake gem_create_build_install # (to build and install, alias gemcbi)
+
+for individual steps (create, build, install) see rake options, rake -T to
+specify sisu version for sisu installed via gem
+
+For a list of alternative actions you may type:
+
+  rake help
+
+  rake -T
+
+Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
+
+
+----------------------------------------
+
+MISC GEM
+........
+
+gem search sisu
+
+  sisu _7.0.0_ --version
+
+  sisu _7.0.0_ --version
+
+to uninstall sisu installed via gem
+
+  sudo gem uninstall --verbose sisu
+
+DIRECT INSTALLATION WITH QI (QUICK INSTALL) SCRIPT
+..................................................
+
+(This requires that ruby -thor is installed).
+
+Root will be requested as required:
+
+  qi setup --bin --lib --conf --data --share --man
+
+or
+
+  qi setup --all
+
+You may wish to do a dryrun to see where files would be installed without
+copying them, to do so add the flag --dryrun
+
+INSTALLATION WITH SETUP.RB
+..........................
+
+It should also be possible to install sisu using setup.rb
+
+this is a three step process, in the root directory of the unpacked *SiSU* as
+root type:
+
+ruby setup.rb config
+ruby setup.rb setup
+#[as root:]
+ruby setup.rb install
+
+further information:
+<http://i.loveruby.net/en/projects/setup/>
+<http://i.loveruby.net/en/projects/setup/doc/usage.html>
+
+  ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
+
+UNIX/LINUX DISTRIBUTION
+-----------------------
+
+A distribution install should take care of the dependencies of sisu for
+producing various outputs.
+
+DEBIAN
+......
+
+*SiSU* is available off the *Debian* archives. It should necessary only to run
+as root, Using apt-get:
+
+  apt-get update
+
+  apt get install sisu-complete
+
+(all sisu dependencies should be taken care of)
+
+If there are newer versions of *SiSU* upstream, they will be available by
+adding the following to your sources list /etc/apt/sources.list
+
+#/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
+
+The non-free section is for sisu markup samples provided, which contain
+authored works the substantive text of which cannot be changed, and which as a
+result do not meet the debian free software guidelines.
+
+*SiSU* is developed on *Debian*, and packages are available for *Debian* that
+take care of the dependencies encountered on installation.
+
+The package is divided into the following components:
+
+  *sisu*, the base code, (the main package on which the others depend), without
+  any dependencies other than ruby (and for convenience the ruby webrick web
+  server), this generates a number of types of output on its own, other
+  packages provide additional functionality, and have their dependencies
+
+  *sisu-complete*, a dummy package that installs the whole of greater sisu as
+  described below, apart from sisu -examples
+
+  *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated
+
+  *sisu-postgresql*, dependencies used by sisu to populate postgresql database
+  (further configuration is necessary)
+
+  *sisu-sqlite*, dependencies used by sisu to populate sqlite database
+
+  *sisu-markup-samples*, sisu markup samples and other miscellany (under
+  *Debian* Free Software Guidelines non-free)
+
+*SiSU* is available off Debian Unstable and Testing [link:
+<http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
+[^1] install it using apt-get, aptitude or alternative *Debian* install tools.
+
+DEPENDENCIES
+------------
+
+Here is a list of sisu' s current dependencies,[^2] which depend on such
+factors as whether you want to generate pdf, whether you will be using *SiSU*
+with or without a database, ...). sisu_markup-samples may also be of interest.
+
+Package: sisu
+Depends: ruby | ruby-interpreter, openssl, rsync, unzip, zip
+Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick |
+graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
+ruby-rmagick, tidy, tree, vim-addon-manager
+Suggests: lv, calibre, pinfo, poedit, texinfo, trang
+
+Package: sisu-complete
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
+${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
+${source:Version})
+Description-en: installs all SiSU related packages
+
+Package: sisu-pdf
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
+texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
+texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
+texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
+Suggests: evince | pdf-viewer
+
+Package: sisu-postgresql
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
+ruby-dbd-pg, ruby-dbi, ruby-fcgi
+Suggests: postgresql-contrib
+
+Package: sisu-sqlite
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
+ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
+
+Package: sisu-markup-samples
+Depends: sisu
+
+COMMANDS
+********
+
+COMMANDS SUMMARY
+----------------
+
+DESCRIPTION
+...........
+
+*SiSU* is a document publishing system, that from a simple single marked-up
+document, produces multiple output formats including: /plaintext/, /HTML/,
+/XHTML/, /XML/, /EPUB/, /ODT/ (/OpenDocument/ (/ODF/) text), /LaTeX/, /PDF/,
+info, and /SQL/ (/PostgreSQL/ and /SQLite/) , which share text object numbers
+("object citation numbering") and the same document structure information. For
+more see: <http://sisudoc.org> or <http://www.jus.uio.no/sisu>
+
+DOCUMENT PROCESSING COMMAND FLAGS
+.................................
+
+*-[0-9] [filename/wildcard]*
+see --act
+
+*--ao [filename/wildcard/url]*
+assumed for most other flags, creates new intermediate files for processing
+(abstract objects, 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.
+
+*--act[s0-9] [filename/wildcard]*
+--act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms,
+configure in sisurc.yml; sisu default action on a specified file where no flag
+is provided is --act0; --act or --acts for information on current actions
+ascribed to --act0 to --act9
+
+*--asciidoc [filename/wildcard]*
+asciidoc, smart text (not available)
+
+*-b [filename/wildcard]*
+see --xhtml
+
+*--by-**
+see --output-by-*
+
+*-C*
+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.
+
+*-c [filename/wildcard]*
+see --color-toggle
+
+*--color*
+see --color-on
+
+*--color-off*
+turn off color in output to terminal
+
+*--color-on*
+turn on color in output to terminal
+
+*--color-toggle [filename/wildcard]*
+screen toggle ansi screen colour on or off depending on default set (unless -c
+flag is used: if sisurc colour default is set to 'true', output to screen will
+be with colour, if sisurc colour default is set to 'false' or is undefined
+screen output will be without colour). Alias -c
+
+*--configure*
+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.
+
+*--concordance [filename/wildcard]*
+produces concordance (wordmap) a rudimentary index of all the words in a
+document. (Concordance files are not generated for documents of over 260,000
+words unless this limit is increased in the file sisurc.yml). Alias -w
+
+*-d [filename/wildcard/url]*
+see --docbook
+
+*--dal [filename/wildcard/url]*
+(abstract objects, document abstraction renamed abstract objects in sisu5) see
+--ao
+
+*--delete [filename/wildcard]*
+see --zap
+
+*--digests [filename/wildcard/url]*
+document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to
+screen.
+
+*--docbook [filename/wildcard/url]*
+docbook xml
+
+*--dom [filename/wildcard/url]*
+see --xml-dom
+
+*--dump[=directory_path] [filename/wildcard]*
+places output in directory specified, if none is specified in the current
+directory (pwd). Unlike using default settings /HTML/ files have embedded css.
+Compare --redirect
+
+*-e [filename/wildcard]*
+see --epub
+
+*--epub [filename/wildcard]*
+produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e
+
+*--errors-as-warnings*
+override stop processing on error. Alias --no-stop
+
+*--exc-**
+exclude output feature, overrides configuration settings --exc-numbering, see
+--exc-ocn; --exc-ocn, (exclude "object citation numbering", (switches off
+object citation numbers), affects html (seg, scroll), epub, xhtml, xml, pdf) ;
+--exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) ;
+--exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest,
+affects html (seg, scroll)); --exc-search-form, (exclude search form, affects
+html (seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents,
+affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude
+mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini
+table of contents, affects html (seg), concordance); --exc-html-navigation,
+(exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude
+navigation bar, affects html (seg)); --exc-html-search-form, (exclude search
+form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right
+pane/column, affects html (seg, scroll)); --exc-html-top-band, (exclude top
+band, affects html (seg, scroll), concordance (minitoc forced on to provide seg
+navigation)); --exc-segsubtoc (exclude sub table of contents, affects html
+(seg), epub) ; see also --inc-*
+
+*-F [--webserv=webrick]*
+see --sample-search-form
+
+*-f [optional string part of filename]*
+see --find
+
+*--fictionbook [filename/wildcard/url]*
+fictionbook xml (not available)
+
+*--find [optional string part of filename]*
+see --glob
+
+*-G [optional string part of filename]*
+see --glob
+
+*-g [filename/wildcard]*
+see --git
+
+*--git [filename/wildcard]*
+produces or updates markup source file structure in a git repo (experimental
+and subject to change). Alias -g
+
+*--glob [optional string part of filename]*
+without match string, glob all .sst .ssm files in directory (including language
+subdirectories). With match string, find files that match given string in
+directory (including language subdirectories). Alias -G, -f, --find
+
+*-h [filename/wildcard]*
+see --html
+
+*--harvest *.ss[tm]*
+makes two lists of sisu output based on the sisu markup documents in a
+directory: list of author and authors works (year and titles), and; list by
+topic with titles and author. Makes use of header metadata fields (author,
+title, date, topic_register). Can be used with maintenance (-M) and remote
+placement (-R) flags.
+
+*--html [filename/wildcard]*
+produces html output, in two forms (i) segmented text with table of contents
+(toc.html and index.html) and (ii) the document in a single file (scroll.html).
+Alias -h
+
+*--html-scroll [filename/wildcard]*
+produces html output, the document in a single file (scroll.html) only. Compare
+--html-seg and --html
+
+*--html-seg [filename/wildcard]*
+produces html output, segmented text with table of contents (toc.html and
+index.html). Compare --html-scroll and --html
+
+*--html-strict [filename/wildcard]*
+produces html with --strict option. see --strict
+
+*-I [filename/wildcard]*
+see --texinfo
+
+*-i [filename/wildcard]*
+see --manpage
+
+*--i18n-**
+these flags affect output by filetype and filename): --i18n-mono
+(--monolingual) output filenames without language code for default language
+('en' or as set); --i18n-multi (--multilingual) language code provided as part
+of the output filename, this is the default. Where output is in one language
+only the language code may not be desired. see also --output-by-*
+
+*--inc-**
+include output feature, overrides configuration settings, (usually the default
+if none set), has precedence over --exc-* (exclude output feature). Some detail
+provided under --exc-*, see --exc-*
+
+*-j [filename/wildcard]*
+copies images associated with a file for use by html, xhtml & xml outputs
+(automatically invoked by --dump & redirect).
+
+*-k*
+see --color-off
+
+*--keep-processing-files [filename/wildcard/url]*
+see --maintenance
+
+*-M [filename/wildcard/url]*
+see --maintenance
+
+*-m [filename/wildcard/url]*
+see --dal (document abstraction level/layer)
+
+*--machine [filename/wildcard/url]*
+see --dal (document abstraction level/layer)
+
+*--maintenance [filename/wildcard/url]*
+maintenance mode, interim processing files are preserved and their locations
+indicated. (also see -V). Aliases -M and --keep-processing-files.
+
+*--manifest [filename/wildcard]*
+produces an html summary of output generated (hyperlinked to content) and
+document specific metadata (sisu_manifest.html). This step is assumed for most
+processing flags.
+
+*--manpage [filename/wildcard]*
+produces man page of file, not suitable for all outputs. Alias -i
+
+*--markdown [filename/wildcard/url]*
+markdown smart text (not available)
+
+*--monolingual*
+see --i18n-*
+
+*--multilingual*
+see --i18n-*
+
+*-N [filename/wildcard/url]*
+see --digests
+
+*-n [filename/wildcard/url]*
+skip the creation of intermediate processing files (document abstraction) if
+they already exist, this skips the equivalent of -m which is otherwise assumed
+by most processing flags.
+
+*--no-**
+see --exc-*
+
+*--no-stop*
+override stop processing on error. Alias --erros-as-warnings
+
+*--numbering*
+turn on "object citation numbers". See --inc-ocn and --exc-ocn
+
+*-o [filename/wildcard/url]*
+see --odt
+
+*--ocn*
+"object citation numbers". See --inc-ocn and --exc-ocn
+
+*--odf [filename/wildcard/url]*
+see --odt
+
+*--odt [filename/wildcard/url]*
+output basic document in opendocument file format (opendocument.odt). Alias -o
+
+*--output-by-**
+select output directory structure from 3 alternatives: --output-by-language,
+(language directory (based on language code) with filetype (html, epub, pdf
+etc.) subdirectories); --output-by-filetype, (filetype directories with
+language code as part of filename); --output-by-filename, (filename directories
+with language code as part of filename). This is configurable. Alias --by-*
+
+*-P [language_directory/filename language_directory]*
+see --po4a
+
+*-p [filename/wildcard]*
+see --pdf
+
+*--papersize-(a4|a5|b5|letter|legal)*
+in conjunction with --pdf set pdf papersize, overriding any configuration
+settings, to set more than one papersize repeat the option --pdf --papersize-a4
+--papersize-letter. See also --papersize=*
+
+*--papersize=a4,a5,b5,letter,legal* in conjunction with --pdf set pdf
+papersize, overriding any configuration settings, to set more than one
+papersize list after the equal sign with a comma separator
+--papersize=a4,letter. See also --papersize-*
+
+*--pdf [filename/wildcard]*
+produces /LaTeX/ pdf (portrait.pdf & landscape.pdf). Orientation and papersize
+may be set on the command-line. Default paper size is set in config file, or
+document header, or provided with additional command line parameter, e.g.
+--papersize-a4 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book
+sizes 'A5' and 'B5' (system defaults to A4), and; --landscape or --portrait,
+so: e.g. "sisu --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]"
+or "sisu --pdf --landscape --a4 --letter --verbose [filename/wildcard]". --pdf
+defaults to both landscape & portrait output, and a4 if no other papersizes are
+configured. Related options --pdf-landscape --pdf-portrait --pdf-papersize-*
+--pdf-papersize=[list]. Alias -p
+
+*--pdf-l [filename/wildcard]*
+See --pdf-landscape
+
+*--pdf-landscape [filename/wildcard]*
+sets orientation, produces /LaTeX/ pdf landscape.pdf. Default paper size is set
+in config file, or document header, or provided with additional command line
+parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and
+'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related options
+--pdf --pdf-portrait. See also --papersize-* or --papersize=[list]. Alias
+--pdf-l or in conjunction with --pdf --landscape
+
+*--pdf-p [filename/wildcard]*
+See --pdf-portrait
+
+*--pdf-portrait [filename/wildcard]*
+sets orientation, produces /LaTeX/ pdf portrait.pdf.pdf. Default paper size is
+set in config file, or document header, or provided with additional command
+line parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter'
+and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related
+options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list].
+Alias --pdf-p or in conjunction with --pdf --portrait
+
+*--pg-[instruction] [filename]*
+database /PostgreSQL/ ( --pgsql may be used instead) possible instructions,
+include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename];
+--pg-update [filename]; --pg-remove [filename]; see database section below.
+
+*--po [language_directory/filename language_directory]*
+see --po4a
+
+*--po4a [language_directory/filename language_directory]*
+produces .pot and po files for the file in the languages specified by the
+language directory. *SiSU* markup is placed in subdirectories named with the
+language code, e.g. en/ fr/ es/. The sisu config file must set the output
+directory structure to multilingual. v3, experimental
+
+*-Q [filename/wildcard]*
+see --qrcode
+
+*-q [filename/wildcard]*
+see --quiet
+
+*--qrcode [filename/wildcard]*
+generate QR code image of metadata (used in manifest).
+
+*--quiet [filename/wildcard]*
+quiet less output to screen.
+
+*-R [filename/wildcard]*
+see --rsync
+
+*-r [filename/wildcard]*
+see --scp
+
+*--redirect[=directory_path] [filename/wildcard]*
+places output in subdirectory under specified directory, subdirectory uses the
+filename (without the suffix). If no output directory is specified places the
+subdirectory under the current directory (pwd). Unlike using default settings
+/HTML/ files have embedded css. Compare --dump
+
+*--rst [filename/wildcard/url]*
+ReST (rST restructured text) smart text (not available)
+
+*--rsync [filename/wildcard]*
+copies sisu output files to remote host using rsync. This requires that
+sisurc.yml has been provided with information on hostname and username, and
+that you have your "keys" and ssh agent in place. Note the behavior of rsync
+different if -R is used with other flags from if used alone. Alone the rsync
+--delete parameter is sent, useful for cleaning the remote directory (when -R
+is used together with other flags, it is not). Also see --scp. Alias -R
+
+*-S*
+see --sisupod
+
+*-S [filename/wildcard]*
+see --sisupod
+
+*-s [filename/wildcard]*
+see --source
+
+*--sample-search-form [--db-(pg|sqlite)]*
+generate examples of (naive) cgi search form for /SQLite/ or PgSQL depends on
+your already having used sisu to populate an /SQLite/ 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 --sqlite & --pg and the database section below. Optional
+additional parameters: --db-user='www-data'. The samples are dumped in the
+present work directory which must be writable, (with screen instructions given
+that they be copied to the cgi-bin directory). Alias -F
+
+*--sax [filename/wildcard/url]*
+see --xml-sax
+
+*--scp [filename/wildcard]*
+copies sisu output files to remote host using scp. This requires that
+sisurc.yml has been provided with information on hostname and username, and
+that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r
+
+*--sha256*
+set hash digest where used to sha256
+
+*--sha512*
+set hash digest where used to sha512
+
+*--sqlite-[instruction] [filename]*
+database type set to /SQLite/, this produces one of two possible databases,
+without additional database related instructions it produces a discreet
+/SQLite/ file for the document processed; with additional instructions it
+produces a common /SQLite/ database of all processed documents that (come from
+the same document preparation directory and as a result) share the same output
+directory base path (possible instructions include: --sqlite-createdb;
+--sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update
+[filename]; --sqlite-remove [filename]); see database section below.
+
+*--sisupod*
+produces a sisupod a zipped sisu directory of markup files including sisu
+markup source files and the directories local configuration file, images and
+skins. Note: this only includes the configuration files or skins contained in
+./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option
+is tested only with zsh). Alias -S
+
+*--sisupod [filename/wildcard]*
+produces a zipped file of the prepared document specified along with associated
+images, by default named sisupod.zip they may alternatively be named with the
+filename extension .ssp This provides a quick way of gathering the relevant
+parts of a sisu document which can then for example be emailed. A sisupod
+includes sisu markup source file, (along with associated documents if a master
+file, or available in multilingual versions), together with related images and
+skin. *SiSU* commands can be run directly against a sisupod contained in a
+local directory, or provided as a url on a remote site. As there is a security
+issue with skins provided by other users, they are not applied unless the flag
+--trust or --trusted is added to the command instruction, it is recommended
+that file that are not your own are treated as untrusted. The directory
+structure of the unzipped file is understood by sisu, and sisu commands can be
+run within it. Note: if you wish to send multiple files, it quickly becomes
+more space efficient to zip the sisu markup directory, rather than the
+individual files for sending). See the -S option without [filename/wildcard].
+Alias -S
+
+*--source [filename/wildcard]*
+copies sisu markup file to output directory. Alias -s
+
+*--strict*
+together with --html, produces more w3c compliant html, for example not having
+purely numeric identifiers for text, the location object url#33 becomes url#o33
+
+*-T [filename/wildcard (*.termsheet.rb)]*
+standard form document builder, preprocessing feature
+
+*-t [filename/wildcard]*
+see --txt
+
+*--texinfo [filename/wildcard]*
+produces texinfo and info file, (view with pinfo). Alias -I
+
+*--textile [filename/wildcard/url]*
+textile smart text (not available)
+
+*--txt [filename/wildcard]*
+produces /plaintext/ with Unix linefeeds and without markup, (object numbers
+are omitted), has footnotes at end of each paragraph that contains them [ -A
+for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options
+include: --endnotes for endnotes --footnotes for footnotes at the end of each
+paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias
+-t
+
+*--txt-asciidoc [filename/wildcard]*
+see --asciidoc
+
+*--txt-markdown [filename/wildcard]*
+see --markdown
+
+*--txt-rst [filename/wildcard]*
+see --rst
+
+*--txt-textile [filename/wildcard]*
+see --textile
+
+*-U [filename/wildcard]*
+see --urls
+
+*-u [filename/wildcard]*
+provides url mapping of output files for the flags requested for processing,
+also see -U
+
+*--urls [filename/wildcard]*
+prints url output list/map for the available processing flags options and
+resulting files that could be requested, (can be used to get a list of
+processing options in relation to a file, together with information on the
+output that would be produced), -u provides url output mapping for those flags
+requested for processing. The default assumes sisu_webrick is running and
+provides webrick url mappings where appropriate, but these can be switched to
+file system paths in sisurc.yml. Alias -U
+
+*-V*
+on its own, provides *SiSU* version and environment information (sisu --help
+env)
+
+*-V [filename/wildcard]*
+even more verbose than the -v flag.
+
+*-v*
+on its own, provides *SiSU* version information
+
+*-v [filename/wildcard]*
+see --verbose
+
+*--verbose [filename/wildcard]*
+provides verbose output of what is being generated, where output is placed (and
+error messages if any), as with -u flag provides a url mapping of files created
+for each of the processing flag requests. Alias -v
+
+*--very-verbose [filename/wildcard]*
+provides more verbose output of what is being generated. See --verbose. Alias
+-V
+
+*--version*
+sisu version
+
+*-W*
+see --webrick
+
+*-w [filename/wildcard]*
+see --concordance
+
+*--webrick*
+starts ruby' s webrick webserver points at sisu output directories, the default
+port is set to 8081 and can be changed in the resource configuration files.
+[tip: the webrick server requires link suffixes, so html output should be
+created using the -h option rather than -H ; also, note -F webrick ]. Alias -W
+
+*--wordmap [filename/wildcard]*
+see --concordance
+
+*--xhtml [filename/wildcard]*
+produces xhtml//XML/ output for browser viewing (sax parsing). Alias -b
+
+*--xml-dom [filename/wildcard]*
+produces /XML/ output with deep document structure, in the nature of dom. Alias
+-X
+
+*--xml-sax [filename/wildcard]*
+produces /XML/ output shallow structure (sax parsing). Alias -x
+
+*-X [filename/wildcard]*
+see --xml-dom
+
+*-x [filename/wildcard]*
+see --xml-sax
+
+*-Y [filename/wildcard]*
+produces a short sitemap entry for the document, based on html output and the
+sisu_manifest. --sitemaps generates/updates the sitemap index of existing
+sitemaps. (Experimental, [g,y,m announcement this week])
+
+*-y [filename/wildcard]*
+see --manifest
+
+*-Z [filename/wildcard]*
+see --zap
+
+*--zap [filename/wildcard]*
+Zap, if used with other processing flags deletes output files of the type about
+to be processed, prior to processing. If -Z is used as the lone processing
+related flag (or in conjunction with a combination of -[mMvVq]), will remove
+the related document output directory. Alias -Z
+
+COMMAND LINE MODIFIERS
+----------------------
+
+*--no-ocn*
+[with --html --pdf or --epub] switches off /object citation numbering/. Produce
+output without identifying numbers in margins of html or /LaTeX//pdf output.
+
+*--no-annotate*
+strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus
+sign
+
+*--no-asterisk*
+strips output text of editor endnotes[^*2] denoted by asterisk sign
+
+*--no-dagger*
+strips output text of editor endnotes[^+1] denoted by dagger/plus sign
+
+DATABASE COMMANDS
+-----------------
+
+*dbi - database interface*
+
+*--pg or --pgsql* set for /PostgreSQL/ *--sqlite* default set for /SQLite/ -d
+is modifiable with --db=[database type (PgSQL or /SQLite/) ]
+
+*--pg -v --createall*
+initial step, creates required relations (tables, indexes) in existing
+/PostgreSQL/ database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi) [ -dv --createall /SQLite/
+equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at
+the present time for /PostgreSQL/ it may be necessary to manually create the
+database. The command would be 'createdb [database name]' where database name
+would be SiSU_[present working directory name (without path)]. Please use only
+alphanumerics and underscores.
+
+*--pg -v --import*
+[filename/wildcard] imports data specified to /PostgreSQL/ db (rb.dbi) [ -dv
+--import /SQLite/ equivalent]
+
+*--pg -v --update*
+[filename/wildcard] updates/imports specified data to /PostgreSQL/ db (rb.dbi)
+[ -dv --update /SQLite/ equivalent]
+
+*--pg --remove*
+[filename/wildcard] removes specified data to /PostgreSQL/ db (rb.dbi) [ -d
+--remove /SQLite/ equivalent]
+
+*--pg --dropall*
+kills data" and drops (/PostgreSQL/ or /SQLite/) db, tables & indexes [ -d
+--dropall /SQLite/ equivalent]
+
+The -v is for verbose output.
+
+COMMAND LINE WITH FLAGS - BATCH PROCESSING
+..........................................
+
+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.
+
+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.
+
+INTRODUCTION TO SISU MARKUP[^3]
+-------------------------------
+
+SUMMARY
+.......
+
+*SiSU* source documents are /plaintext/ (/UTF-8/)[^4] files
+
+All paragraphs are separated by an empty line.
+
+Markup is comprised of:
+
+* 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)
+
+* 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:
+
+  * heading levels defines document structure
+
+  * text basic attributes, italics, bold etc.
+
+  * grouped text (objects), which are to be treated differently, such as code
+  blocks or poems.
+
+  * footnotes/endnotes
+
+  * linked text and images
+
+  * paragraph actions, such as indent, bulleted, numbered-lists, etc.
+
+MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS
+..........................................................
+
+minimal content/structure requirement:
+
+[metadata]
+
+A~ (level A [title])
+
+1~ (at least one level 1 [segment/(chapter)])
+
+structure rules (document heirarchy, heading levels):
+
+there are two sets of heading levels ABCD (title & parts if any) and 123
+(segment & subsegments if any)
+
+sisu has the fllowing levels:
+
+A~ [title]              .
+   required (== 1)   followed by B~ or 1~
+B~ [part]               *
+   followed by C~ or 1~
+C~ [subpart]            *
+   followed by D~ or 1~
+D~ [subsubpart]         *
+   followed by 1~
+1~ [segment (chapter)]  +
+   required (>= 1)   followed by text or 2~
+text                    *
+   followed by more text or 1~, 2~
+   or relevant part *()
+2~ [subsegment]         *
+   followed by text or 3~
+text                    *
+   followed by more text or 1~, 2~ or 3~
+   or relevant part, see *()
+3~ [subsubsegment]      *
+   followed by text
+text                    *
+   followed by more text or 1~, 2~ or 3~ or relevant part, see *()
+
+*(B~ if none other used;
+  if C~ is last used: C~ or B~;
+  if D~ is used: D~, C~ or B~)
+
+* level A~ is the tile and is mandatory
+* there can only be one level A~
+* heading levels BCD, are optional and there may be several of each
+  (where all three are used corresponding to e.g. Book Part Section)
+  * sublevels that are used must follow each other sequentially
+    (alphabetically),
+* heading levels A~ B~ C~ D~ are followed by other heading levels rather
+  than substantive text
+  which may be the subsequent sequential (alphabetic) heading part level
+  or a heading (segment) level 1~
+* there must be at least one heading (segment) level 1~
+  (the level on which the text is segmented, in a book would correspond
+  to the Chapter level)
+* additional heading levels 1~ 2~ 3~ are optional and there may be several
+  of each
+* heading levels 1~ 2~ 3~ are followed by text (which may be followed by
+  the same heading level)
+  and/or the next lower numeric heading level (followed by text)
+  or indeed return to the relevant part level
+  (as a corollary to the rules above substantive text/ content
+  must be preceded by a level 1~ (2~ or 3~) heading)
+
+MARKUP EXAMPLES
+...............
+
+
+----------------------------------------
+
+ONLINE
+......
+
+Online markup examples are available together with the respective outputs
+produced from <http://www.jus.uio.no/sisu/SiSU/examples.html> or from
+<http://www.jus.uio.no/sisu/sisu_examples/>
+
+There is of course this document, which provides a cursory overview of sisu
+markup and the respective output produced:
+<http://www.jus.uio.no/sisu/sisu_markup/>
+
+an alternative presentation of markup syntax:
+/usr/share/doc/sisu/on_markup.txt.gz
+
+
+----------------------------------------
+
+INSTALLED
+.........
+
+With *SiSU* installed sample skins may be found in:
+/usr/share/doc/sisu/markup-samples (or equivalent directory) and if sisu
+-markup-samples is installed also under:
+/usr/share/doc/sisu/markup-samples-non-free
+
+MARKUP OF HEADERS
+-----------------
+
+Headers contain either: semantic meta-data about a document, which can be used
+by any output module of the program, or; processing instructions.
+
+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:
+
+% this would be a comment
+
+SAMPLE HEADER
+.............
+
+This current document is loaded by a master document that has a header similar
+to this one:
+
+% SiSU master 4.0
+
+@title: SiSU
+  :subtitle: Manual
+
+@creator:
+  :author: Amissah, Ralph
+
+@publisher: [publisher name]
+
+@rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
+
+@classify:
+  :topic_register: SiSU:manual;electronic documents:SiSU:manual
+  :subject: ebook, epublishing, electronic book, electronic publishing,
+    electronic document, electronic citation, data structure,
+     citation systems, search
+
+% used_by: manual
+
+@date:
+  :published: 2008-05-22
+  :created: 2002-08-28
+  :issued: 2002-08-28
+  :available: 2002-08-28
+  :modified: 2010-03-03
+
+@make:
+  :num_top: 1
+  :breaks: new=C; break=1
+  :bold: /Gnu|Debian|Ruby|SiSU/
+  :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+  :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+  :manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search;
+     synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ]
+     . sisu [-Ddcv] [instruction]
+     . sisu [-CcFLSVvW]
+
+@links:
+  { SiSU Homepage }http://www.sisudoc.org/
+  { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
+  { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
+  { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+  { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
+  { SiSU Git repo }http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
+  { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
+  { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
+  { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
+  { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+
+AVAILABLE HEADERS
+.................
+
+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 the form
+@headername: or on the next line and indented by once space :subheadername: All
+/Dublin Core/ meta tags are available
+
+*@identifier:* information or instructions
+
+where the "identifier" is a tag recognised by the program, and the
+"information" or "instructions" belong to the tag/identifier specified
+
+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.
+
+This is a sample header
+
+% SiSU 2.0 [declared file-type identifier with markup version]
+
+@title: [title text] [this header is the only one that is mandatory]
+  :subtitle: [subtitle if any]
+  :language: English
+
+@creator:
+  :author: [Lastname, First names]
+  :illustrator: [Lastname, First names]
+  :translator: [Lastname, First names]
+  :prepared_by: [Lastname, First names]
+
+@date:
+  :published: [year or yyyy-mm-dd]
+  :created: [year or yyyy-mm-dd]
+  :issued: [year or yyyy-mm-dd]
+  :available: [year or yyyy-mm-dd]
+  :modified: [year or yyyy-mm-dd]
+  :valid: [year or yyyy-mm-dd]
+  :added_to_site: [year or yyyy-mm-dd]
+  :translated: [year or yyyy-mm-dd]
+
+@rights:
+  :copyright: Copyright (C) [Year and Holder]
+  :license: [Use License granted]
+  :text: [Year and Holder]
+  :translation: [Name, Year]
+  :illustrations: [Name, Year]
+
+@classify:
+  :topic_register: SiSU:markup sample:book;book:novel:fantasy
+  :type:
+  :subject:
+  :description:
+  :keywords:
+  :abstract:
+  :loc: [Library of Congress classification]
+  :dewey: [Dewey classification
+
+@identify:
+  :isbn: [ISBN]
+  :oclc:
+
+@links: { SiSU }http://www.sisudoc.org
+  { FSF }http://www.fsf.org
+
+@make:
+  :num_top: 1
+  :headings: [text to match for each level
+    (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
+  :breaks: new=:C; break=1
+  :promo: sisu, ruby, sisu_search_libre, open_society
+  :bold: [regular expression of words/phrases to be made bold]
+  :italics: [regular expression of words/phrases to italicise]
+  :home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+  :footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+
+@original:
+  :language: [language]
+
+@notes:
+  :comment:
+  :prefix: [prefix is placed just after table of contents]
+
+MARKUP OF SUBSTANTIVE TEXT
+--------------------------
+
+HEADING LEVELS
+..............
+
+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)
+
+*:A~ [heading text]* Top level heading [this usually has similar content to the
+title @title: ] NOTE: the heading levels described here are in 0.38 notation,
+see heading
+
+*:B~ [heading text]* Second level heading [this is a heading level divider]
+
+*:C~ [heading text]* Third level heading [this is a heading level divider]
+
+*1~ [heading text]* Top level heading preceding substantive text of document or
+sub-heading 2, the heading level that would normally be marked 1. or 2. or 3.
+etc. in a document, and the level on which sisu by default would break html
+output into named segments, names are provided automatically if none are given
+(a number), otherwise takes the form 1~my_filename_for_this_segment
+
+*2~ [heading text]* Second level heading preceding substantive text of document
+or sub-heading 3 , the heading level that would normally be marked 1.1 or 1.2
+or 1.3 or 2.1 etc. in a document.
+
+*3~ [heading text]* Third level heading preceding substantive text of document,
+that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a
+document
+
+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)
+
+FONT ATTRIBUTES
+...............
+
+*markup example:*
+
+normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
+^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
+
+normal text
+
+*{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
+
+!{bold text}!
+
+/{italics}/
+
+_{underscore}_
+
+"{citation}"
+
+^{superscript}^
+
+,{subscript},
+
++{inserted text}+
+
+-{strikethrough}-
+
+#{monospace}#
+
+*resulting output:*
+
+normal text, *emphasis*, *bold text*, /italics/, _underscore_, "citation",
+^superscript^, [subscript], +inserted text+, -strikethrough-, #monospace#
+
+normal text
+
+*emphasis* [note: can be configured to be represented by bold, italics or
+underscore]
+
+*bold text*
+
+/italics/
+
+_underscore_
+
+"citation"
+
+^superscript^
+
+[subscript]
+
++inserted text+
+
+-strikethrough-
+
+#monospace#
+
+INDENTATION AND BULLETS
+.......................
+
+*markup example:*
+
+ordinary paragraph
+
+_1 indent paragraph one step
+
+_2 indent paragraph two steps
+
+_9 indent paragraph nine steps
+
+*resulting output:*
+
+ordinary paragraph
+
+  indent paragraph one step
+
+    indent paragraph two steps
+
+                  indent paragraph nine steps
+
+*markup example:*
+
+_* bullet text
+
+_1* bullet text, first indent
+
+_2* bullet text, two step indent
+
+*resulting output:*
+
+* bullet text
+
+  * bullet text, first indent
+
+    * bullet text, two step indent
+
+Numbered List (not to be confused with headings/titles, (document structure))
+
+*markup example:*
+
+# numbered list                numbered list 1., 2., 3, etc.
+
+_# numbered list numbered list indented a., b., c., d., etc.
+
+HANGING INDENTS
+...............
+
+*markup example:*
+
+_0_1 first line no indent,
+rest of paragraph indented one step
+
+_1_0 first line indented,
+rest of paragraph no indent
+
+in each case level may be 0-9
+
+*resulting output:*
+
+first line no indent, rest of paragraph indented one step; first line no
+  indent, rest of paragraph indented one step; first line no indent, rest of
+  paragraph indented one step; first line no indent, rest of paragraph indented
+  one step; first line no indent, rest of paragraph indented one step; first
+  line no indent, rest of paragraph indented one step; first line no indent,
+  rest of paragraph indented one step; first line no indent, rest of paragraph
+  indented one step; first line no indent, rest of paragraph indented one step;
+
+A regular paragraph.
+
+  first line indented, rest of paragraph no indent first line indented, rest of
+paragraph no indent first line indented, rest of paragraph no indent first line
+indented, rest of paragraph no indent first line indented, rest of paragraph no
+indent first line indented, rest of paragraph no indent first line indented,
+rest of paragraph no indent first line indented, rest of paragraph no indent
+first line indented, rest of paragraph no indent first line indented, rest of
+paragraph no indent first line indented, rest of paragraph no indent
+
+in each case level may be 0-9
+
+*live-build* A collection of scripts used to build customized *Debian*
+  Livesystems. /live-build/ was formerly known as live-helper, and even earlier
+  known as live-package.
+
+*live-build*
+  A collection of scripts used to build customized *Debian* Livesystems.
+  /live-build/ was formerly known as live-helper, and even earlier known as
+  live-package.
+
+FOOTNOTES / ENDNOTES
+....................
+
+Footnotes and endnotes are marked up at the location where they would be
+indicated within a text. They are automatically numbered. The output type
+determines whether footnotes or endnotes will be produced
+
+*markup example:*
+
+~{ a footnote or endnote }~
+
+*resulting output:*
+
+[^5]
+
+*markup example:*
+
+normal text~{ self contained endnote marker & endnote in one }~ continues
+
+*resulting output:*
+
+normal text[^6] continues
+
+*markup example:*
+
+normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+
+normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
+
+*resulting output:*
+
+normal text [^*] continues
+
+normal text [^**] continues
+
+*markup example:*
+
+normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
+
+*resulting output:*
+
+normal text [^*3] continues
+
+normal text [^+2] continues
+
+*Alternative endnote pair notation for footnotes/endnotes:*
+
+% note the endnote marker "~^"
+
+normal text~^ continues
+
+^~ endnote text following the paragraph in which the marker occurs
+
+the standard and pair notation cannot be mixed in the same document
+
+LINKS
+.....
+
+
+----------------------------------------
+
+NAKED URLS WITHIN TEXT, DEALING WITH URLS
+.........................................
+
+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).
+
+*markup example:*
+
+normal text http://www.sisudoc.org/ continues
+
+*resulting output:*
+
+normal text <http://www.sisudoc.org/> continues
+
+An escaped url without decoration
+
+*markup example:*
+
+normal text _http://www.sisudoc.org/ continues
+
+deb _http://www.jus.uio.no/sisu/archive unstable main non-free
+
+*resulting output:*
+
+normal text http://www.sisudoc.org/ continues
+
+deb http://www.jus.uio.no/sisu/archive unstable main non-free
+
+where a code block is used there is neither decoration nor hyperlinking, code
+blocks are discussed later in this document
+
+*resulting output:*
+
+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
+
+
+----------------------------------------
+
+LINKING TEXT
+............
+
+To link text or an image to a url the markup is as follows
+
+*markup example:*
+
+about { SiSU }http://url.org markup
+
+*resulting output:*
+
+about SiSU [link: <http://www.sisudoc.org/>] markup
+
+A shortcut notation is available so the url link may also be provided
+automatically as a footnote
+
+*markup example:*
+
+about {~^ SiSU }http://url.org markup
+
+*resulting output:*
+
+about SiSU [link: <http://www.sisudoc.org/>] [^7] markup
+
+Internal document links to a tagged location, including an ocn
+
+*markup example:*
+
+about { text links }#link_text
+
+*resulting output:*
+
+about text links
+
+Shared document collection link
+
+*markup example:*
+
+about { SiSU book markup examples }:SiSU/examples.html
+
+*resulting output:*
+
+about *SiSU* book markup examples
+
+
+----------------------------------------
+
+LINKING IMAGES
+..............
+
+*markup example:*
+
+{ tux.png 64x80 }image
+
+% various url linked images
+[image: "a better way"]
+ [image: "Way Better - with Gnu/Linux, Debian and Ruby"]
+
+{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
+
+*resulting output:*
+
+tux.png 64x80 [link: local image]
+
+tux.png 64x80 "Gnu/Linux - a better way" [link: <http://www.sisudoc.org/>]
+
+GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
+and Ruby" [link: <http://www.sisudoc.org/>]
+
+ruby_logo.png 70x90 "Ruby" [link: <http://www.ruby-lang.org/en/>] [^8]
+
+*linked url footnote shortcut*
+
+{~^ [text to link] }http://url.org
+
+% maps to: { [text to link] }http://url.org ~{ http://url.org }~
+
+% which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
+
+text marker *~name
+
+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.
+
+
+----------------------------------------
+
+LINK SHORTCUT FOR MULTIPLE VERSIONS OF A SISU DOCUMENT IN THE SAME DIRECTORY
+TREE
+..............................................................................
+
+*markup example:*
+
+!_ /{"Viral Spiral"}/, David Bollier
+
+{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
+
+*/"Viral Spiral"/, David Bollier*
+
+⌠"Viral Spiral", David Bollier [3sS]⌡viral_spiral.david_bollier.sst
+
+GROUPED TEXT / BLOCKED TEXT
+...........................
+
+There are two markup syntaxes for blocked text, using curly braces or using
+tics
+
+
+----------------------------------------
+
+BLOCKED TEXT CURLY BRACE SYNTAX
+...............................
+
+at the start of a line on its own use name of block type with an opening curly
+brace, follow with the content of the block, and close with a closing curly
+brace and the name of the block type, e.g.
+
+code{
+this is a code block
+
+}code
+
+poem{
+
+this here is a poem
+
+}poem
+
+
+----------------------------------------
+
+BLOCKED TEXT TIC SYNTAX
+.......................
+
+``` code
+this is a code block
+
+```
+
+``` poem
+
+this here is a poem
+
+```
+
+start a line with three backtics, a space followed by the name of the name of
+block type, follow with the content of the block, and close with three back
+ticks on a line of their own, e.g.
+
+
+----------------------------------------
+
+TABLES
+......
+
+Tables may be prepared in two either of two forms
+
+*markup example:*
+
+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
+
+*resulting output:*
+
+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』
+
+a second form may be easier to work with in cases where there is not much
+information in each column
+
+*markup example:*[^9]
+
+!_ 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.
+
+*resulting output:*
+
+*Table 3.1: Contributors to Wikipedia, January 2001 - June 2005*
+
+┆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.
+
+
+----------------------------------------
+
+POEM
+....
+
+*basic markup:*
+
+poem{
+
+  Your poem here
+
+}poem
+
+Each verse in a poem is given an object number.
+
+*markup example:*
+
+poem{
+
+                    `Fury said to a
+                   mouse, That he
+                 met in the
+               house,
+            "Let us
+              both go to
+                law:  I will
+                  prosecute
+                    YOU.  --Come,
+                       I'll take no
+                        denial; We
+                     must have a
+                 trial:  For
+              really this
+           morning I've
+          nothing
+         to do."
+           Said the
+             mouse to the
+               cur, "Such
+                 a trial,
+                   dear Sir,
+                         With
+                     no jury
+                  or judge,
+                would be
+              wasting
+             our
+              breath."
+               "I'll be
+                 judge, I'll
+                   be jury,"
+                         Said
+                    cunning
+                      old Fury:
+                     "I'll
+                      try the
+                         whole
+                          cause,
+                             and
+                        condemn
+                       you
+                      to
+                       death."'
+
+}poem
+
+*resulting output:*
+
+                    `Fury said to a
+                   mouse, That he
+                 met in the
+               house,
+            "Let us
+              both go to
+                law:  I will
+                  prosecute
+                    YOU.  --Come,
+                       I'll take no
+                        denial; We
+                     must have a
+                 trial:  For
+              really this
+           morning I've
+          nothing
+         to do."
+           Said the
+             mouse to the
+               cur, "Such
+                 a trial,
+                   dear Sir,
+                         With
+                     no jury
+                  or judge,
+                would be
+              wasting
+             our
+              breath."
+               "I'll be
+                 judge, I'll
+                   be jury,"
+                         Said
+                    cunning
+                      old Fury:
+                     "I'll
+                      try the
+                         whole
+                          cause,
+                             and
+                        condemn
+                       you
+                      to
+                       death."'
+
+
+----------------------------------------
+
+GROUP
+.....
+
+*basic markup:*
+
+group{
+
+  Your grouped text here
+
+}group
+
+A group is treated as an object and given a single object number.
+
+*markup example:*
+
+group{
+
+                    `Fury said to a
+                   mouse, That he
+                 met in the
+               house,
+            "Let us
+              both go to
+                law:  I will
+                  prosecute
+                    YOU.  --Come,
+                       I'll take no
+                        denial; We
+                     must have a
+                 trial:  For
+              really this
+           morning I've
+          nothing
+         to do."
+           Said the
+             mouse to the
+               cur, "Such
+                 a trial,
+                   dear Sir,
+                         With
+                     no jury
+                  or judge,
+                would be
+              wasting
+             our
+              breath."
+               "I'll be
+                 judge, I'll
+                   be jury,"
+                         Said
+                    cunning
+                      old Fury:
+                     "I'll
+                      try the
+                         whole
+                          cause,
+                             and
+                        condemn
+                       you
+                      to
+                       death."'
+
+}group
+
+*resulting output:*
+
+                    `Fury said to a
+                   mouse, That he
+                 met in the
+               house,
+            "Let us
+              both go to
+                law:  I will
+                  prosecute
+                    YOU.  --Come,
+                       I'll take no
+                        denial; We
+                     must have a
+                 trial:  For
+              really this
+           morning I've
+          nothing
+         to do."
+           Said the
+             mouse to the
+               cur, "Such
+                 a trial,
+                   dear Sir,
+                         With
+                     no jury
+                  or judge,
+                would be
+              wasting
+             our
+              breath."
+               "I'll be
+                 judge, I'll
+                   be jury,"
+                         Said
+                    cunning
+                      old Fury:
+                     "I'll
+                      try the
+                         whole
+                          cause,
+                             and
+                        condemn
+                       you
+                      to
+                       death."'
+
+
+----------------------------------------
+
+CODE
+....
+
+Code tags # code{ ... }code # (used as with other group tags described above)
+are used to escape regular sisu markup, and have been used extensively within
+this document to provide examples of *SiSU* markup. You cannot however use code
+tags to escape code tags. They are however used in the same way as group or
+poem tags.
+
+A code-block is treated as an object and given a single object number. [an
+option to number each line of code may be considered at some later time]
+
+*use of code tags instead of poem compared, resulting output:*
+
+                    `Fury said to a
+                   mouse, That he
+                 met in the
+               house,
+            "Let us
+              both go to
+                law:  I will
+                  prosecute
+                    YOU.  --Come,
+                       I'll take no
+                        denial; We
+                     must have a
+                 trial:  For
+              really this
+           morning I've
+          nothing
+         to do."
+           Said the
+             mouse to the
+               cur, "Such
+                 a trial,
+                   dear Sir,
+                         With
+                     no jury
+                  or judge,
+                would be
+              wasting
+             our
+              breath."
+               "I'll be
+                 judge, I'll
+                   be jury,"
+                         Said
+                    cunning
+                      old Fury:
+                     "I'll
+                      try the
+                         whole
+                          cause,
+                             and
+                        condemn
+                       you
+                      to
+                       death."'
+
+From *SiSU* 2.7.7 on you can number codeblocks by placing a hash after the
+opening code tag # code{# # as demonstrated here:
+
+1  ┆                    `Fury said to a
+2  ┆                   mouse, That he
+3  ┆                 met in the
+4  ┆               house,
+5  ┆            "Let us
+6  ┆              both go to
+7  ┆                law:  I will
+8  ┆                  prosecute
+9  ┆                    YOU.  --Come,
+10 ┆                       I'll take no
+11 ┆                        denial; We
+12 ┆                     must have a
+13 ┆                 trial:  For
+14 ┆              really this
+15 ┆           morning I've
+16 ┆          nothing
+17 ┆         to do."
+18 ┆           Said the
+19 ┆             mouse to the
+20 ┆               cur, "Such
+21 ┆                 a trial,
+22 ┆                   dear Sir,
+23 ┆                         With
+24 ┆                     no jury
+25 ┆                  or judge,
+26 ┆                would be
+27 ┆              wasting
+28 ┆             our
+29 ┆              breath."
+30 ┆               "I'll be
+31 ┆                 judge, I'll
+32 ┆                   be jury,"
+33 ┆                         Said
+34 ┆                    cunning
+35 ┆                      old Fury:
+36 ┆                     "I'll
+37 ┆                      try the
+38 ┆                         whole
+39 ┆                          cause,
+40 ┆                             and
+41 ┆                        condemn
+42 ┆                       you
+43 ┆                      to
+44 ┆                       death."'
+
+ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
+.....................................................................
+
+
+----------------------------------------
+
+LINE-BREAKS
+...........
+
+To break a line within a "paragraph object", two backslashes \\
+with a space before and a space or newline after them
+may be used.
+
+To break a line within a "paragraph object",
+two backslashes \\ with a space before
+and a space or newline after them \\
+may be used.
+
+The html break br enclosed in angle brackets (though undocumented) is available
+in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
+but is depreciated).
+
+To draw a dividing line dividing paragraphs, see the section on page breaks.
+
+
+----------------------------------------
+
+PAGE BREAKS
+...........
+
+Page breaks are only relevant and honored in some output formats. A page break
+or a new page may be inserted manually using the following markup on a line on
+its own:
+
+page new =\= breaks the page, starts a new page.
+
+page break -\- breaks a column, starts a new column, if using columns, else
+breaks the page, starts a new page.
+
+page break line across page -..- draws a dividing line, dividing paragraphs
+
+page break:
+
+-\\-
+
+page (break) new:
+
+=\\=
+
+page (break) line across page (dividing paragraphs):
+
+-..-
+
+BIBLIOGRAPHY / REFERENCES
+.........................
+
+There are three ways to prepare a bibliography using sisu (which are mutually
+exclusive): (i) manually preparing and marking up as regular text in sisu a
+list of references, this is treated as a regular document segment (and placed
+before endnotes if any); (ii) preparing a bibliography, marking a heading level
+1~!biblio (note the exclamation mark) and preparing a bibliography using
+various metadata tags including for author: title: year: a list of which is
+provided below, or; (iii) as an assistance in preparing a bibliography, marking
+a heading level 1~!biblio and tagging citations within footnotes for inclusion,
+identifying citations and having a parser attempt to extract them and build a
+bibliography of the citations provided.
+
+For the heading/section sequence: endnotes, bibliography then book index to
+occur, the name biblio or bibliography must be given to the bibliography
+section, like so:
+
+1~!biblio~ [Note: heading marker::required title missing]
+
+
+----------------------------------------
+
+A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
+.............................................
+
+Here instead of writing your full citations directly in footnotes, each time
+you have new material to cite, you add it to your bibliography section (if it
+has not been added yet) providing the information you need against an available
+list of tags (provided below).
+
+The required tags are au: ti: and year: [^10] an short quick example might be
+as follows:
+
+1~!biblio~ [Note: heading marker::required title missing]
+
+au: von Hippel, E.
+ti: Perspective: User Toolkits for Innovation
+lng: (language)
+jo: Journal of Product Innovation Management
+vo: 18
+ed: (editor)
+yr: 2001
+note:
+sn: Hippel, /{User Toolkits}/ (2001)
+id: vHippel_2001
+% form:
+
+au: Benkler, Yochai
+ti: The Wealth of Networks
+st: How Social Production Transforms Markets and Freedom
+lng: (language)
+pb: Harvard University Press
+edn: (edition)
+yr: 2006
+pl: U.S.
+url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
+note:
+sn: Benkler, /{Wealth of Networks}/ (2006)
+id: Benkler2006
+
+au: Quixote, Don; Panza, Sancho
+ti: Taming Windmills, Keeping True
+jo: Imaginary Journal
+yr: 1605
+url: https://en.wikipedia.org/wiki/Don_Quixote
+note: made up to provide an example of author markup for an article with two authors
+sn: Quixote & Panza, /{Taming Windmills}/ (1605)
+id: quixote1605
+
+Note that the section name !biblio (or !bibliography) is required for the
+bibliography to be treated specially as such, and placed after the
+auto-generated endnote section.
+
+Using this method, work goes into preparing the bibliography, the tags author
+or editor, year and title are required and will be used to sort the
+bibliography that is placed under the Bibliography section
+
+The metadata tags may include shortname (sn:) and id, if provided, which are
+used for substitution within text. Every time the given id is found within the
+text it will be replaced by the given short title of the work (it is for this
+reason the short title has sisu markup to italicize the title), it should work
+with any page numbers to be added, the short title should be one that can
+easily be used to look up the full description in the bibliography.
+
+The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
+
+would be presented as:
+
+Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler,
+/Wealth of Networks/, (2006) p 1 or rather[^11]
+
+au: author Surname, FirstNames (if multiple semi-colon separator)
+    (required unless editor to be used instead)
+ti: title  (required)
+st: subtitle
+jo: journal
+vo: volume
+ed: editor (required if author not provided)
+tr: translator
+src: source (generic field where others are not appropriate)
+in: in (like src)
+pl: place/location (state, country)
+pb: publisher
+edn: edition
+yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required)
+pg: pages
+url: http://url
+note: note
+id: create_short_identifier e.g. authorSurnameYear
+    (used in substitutions: when found within text will be
+    replaced by the short name provided)
+sn: short name e.g. Author, /{short title}/, Year
+    (used in substitutions: when an id is found within text
+    the short name will be used to replace it)
+
+
+----------------------------------------
+
+TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY
+...................................................
+
+Here whenever you make a citation that you wish be included in the
+bibliography, you tag the citation as such using special delimiters (which are
+subsequently removed from the final text produced by sisu)
+
+Here you would write something like the following, either in regular text or a
+footnote
+
+See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
+
+*SiSU* will parse for a number of patterns within the delimiters to try make
+out the authors, title, date etc. and from that create a Bibliography. This is
+more limited than the previously described method of preparing a tagged
+bibliography, and using an id within text to identify the work, which also
+lends itself to greater consistency.
+
+GLOSSARY
+........
+
+Using the section name 1~!glossary results in the Glossary being treated
+specially as such, and placed after the auto-generated endnote section (before
+the bibliography/list of references if there is one).
+
+The Glossary is ordinary text marked up in a manner deemed suitable for that
+purpose. e.g. with the term in bold, possibly with a hanging indent.
+
+1~!glossary~ [Note: heading marker::required title missing]
+
+_0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ...
+
+_0_1 [provide your list of terms and definitions]
+
+In the given example the first line is not indented subsequent lines are by one
+level, and the term to be defined is in bold text.
+
+BOOK INDEX
+..........
+
+To make an index append to paragraph the book index term relates to it, using
+an equal sign and curly braces.
+
+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.
+
+  Paragraph containing main term and sub-term.
+  ={Main term:sub-term}
+
+The index syntax starts on a new line, but there should not be an empty line
+between paragraph and index markup.
+
+The structure of the resulting index would be:
+
+  Main term, 1
+    sub-term, 1
+
+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.
+
+  Paragraph containing main term, second term and sub-term.
+  ={first term; second term: sub-term}
+
+The structure of the resulting index would be:
+
+  First term, 1,
+  Second term, 1,
+    sub-term, 1
+
+If multiple sub-terms appear under one paragraph, they are separated under the
+main term heading from each other by a pipe symbol.
+
+  Paragraph containing main term, second term and sub-term.
+  ={Main term:
+      sub-term+2|second sub-term;
+    Another term
+   }
+
+  A paragraph that continues discussion of the first sub-term
+
+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:
+
+  Main term, 1,
+    sub-term, 1-3,
+    second sub-term, 1,
+  Another term, 1
+
+COMPOSITE DOCUMENTS MARKUP
+--------------------------
+
+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 *.ssm* Within this document you would provide information on the other
+documents that should be included within the text. These may be other documents
+that would be processed in a regular way, or markup bits prepared only for
+inclusion within a master document *.sst* regular markup file, or *.ssi*
+(insert/information) A secondary file of the composite document is built prior
+to processing with the same prefix and the suffix *._sst*
+
+basic markup for importing a document into a master document
+
+<< filename1.sst
+
+<< filename2.ssi
+
+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.
+
+SUBSTITUTIONS
+-------------
+
+*markup example:*
+
+The current Debian is ${debian_stable} the next debian will be ${debian_testing}
+
+Configure substitution in _sisu/sisu_document_make
+
+@make:
+:substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
+
+*resulting output:*
+
+The current *Debian* is *Jessie* the next debian will be *Stretch*
+
+Configure substitution in _sisu/sisu_document_make
+
+
+----------------------------------------
+
+
+----------------------------------------
+
+
+----------------------------------------
+
+
+ [1]: <http://packages.qa.debian.org/s/sisu.html>
+
+ [2]: from the *Debian* control file
+
+ [*1]: square brackets
+
+ [*2]: square brackets
+
+ [+1]: square brackets
+
+ [3]: 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.
+
+ [4]: files should be prepared using /UTF-8/ character encoding
+
+ [5]: a footnote or endnote
+
+ [6]: self contained endnote marker & endnote in one
+
+ [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required
+
+ [**]: another unnumbered asterisk footnote/endnote
+
+ [*3]: editors notes, numbered asterisk footnote/endnote series
+
+ [+2]: editors notes, numbered plus symbol footnote/endnote series
+
+ [7]: <http://www.sisudoc.org/>
+
+ [8]: <http://www.ruby-lang.org/en/>
+
+ [9]: Table from the Wealth of Networks by Yochai Benkler
+
+ http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler
+
+ [10]: for which you may alternatively use the full form author: title: and year:
+
+ [11]: Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler,
+ /Wealth of Networks/ (2006), p 1
+
+==============================================================================
+
+	Title:  SiSU - README
+
+	Creator:  Ralph Amissah
+
+	Rights:  Copyright: Copyright (C) Ralph Amissah 2014 \\ License: GPL 3
+               (part of SiSU documentation)
+
+	Subject:  ebook, epublishing, electronic book, electronic publishing,
+               electronic document, electronic citation, data structure,
+               citation systems, search
+
+	Publisher:  SiSU http://www.jus.uio.no/sisu (this copy)
+
+	Date created:  2014-02-02
+
+	Date available:  2014-02-02
+
+	Date modified:  2014-02-02
+
+	Date:  2014-02-02
+
+	Sourcefile:  README.ssm.sst
+
+	Filetype:  SiSU text insert 5.0, ASCII text, with very long lines
+
+	Source digest:  SHA256(README.ssm.sst)=
+               2084f396c985a9d784d66fd6219c6c4d6b6a7b1d53619f57012641ccaa8b1c5d
+
+	Generated by:  Generated by: SiSU 7.0.1_pre_rel of 2015w18/2 (2015-05-05)
+
+	Ruby version:  ruby 2.1.5p273 (2014-11-13) [x86_64-linux-gnu]
+
+	Document (ao) last generated:  2015-05-12 16:33:24 -0400
+
+==============================================================================
+
+
+plaintext (plain text):
+   http://niu/manual/en/txt/README.txt
+
+Other versions of this document:
+
+manifest:
+   http://niu/manual/en/manifest/README.manifest.html
+
+at:
+   http://niu/manual
+
+
+
+* Generated by: SiSU 7.0.1_pre_rel of 2015w18/2 (2015-05-05)
+* Ruby version: ruby 2.1.5p273 (2014-11-13) [x86_64-linux-gnu]
+* Last Generated on: 2015-05-12 16:33:26 -0400
+* SiSU www.sisudoc.org