documentation, text, much todo

11 files changed, 606 insertions, 570 deletions

diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration.txt b/data/doc/sisu/v2/sisu_user_txt/configuration.txt
new file mode 100644
index 00000000..1f122d56
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/configuration.txt
@@ -0,0 +1,8 @@
+                                                                       index.txt
+%% configuration ---------------------------------------------------------------
+
+configuration_sisurc.txt
+
+configuration_skin.txt
+
+configuration_css.txt
diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt
new file mode 100644
index 00000000..17fb2e97
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/configuration_css.txt
@@ -0,0 +1,9 @@
+                                                                       index.txt
+                                                               configuration.txt
+%% css ------------------------------------------------------------------------
+
+the default css may be replaced for the site or particular processing
+directories
+
+[provide information]
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt
new file mode 100644
index 00000000..62a2ce02
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/configuration_sisurc.txt
@@ -0,0 +1,137 @@
+                                                                       index.txt
+                                                               configuration.txt
+%% config, sisurc.yml ----------------------------------------------------------
+
+There are default configuration settings within the program many of which can
+be modified in sisurc.yml
+
+sisurc.yml can be located in one of the following locations:
+/etc/sisu/sisurc.yml    ~/.sisu/sisurc.yml    and ./_sisu/sisurc.yml
+
+if sisu versions 1 and 2 are both in use, the v2 sisurc.yml can be placed a the
+following locations:
+/etc/sisu/v2/sisurc.yml ~/.sisu/v2/sisurc.yml and ./_sisu/v2/sisurc.yml
+
+# Name: SiSU - Simple information Structuring Universe
+# Author: Ralph@Amissah.com
+# Description: Site wide envionment defaults set here
+# system environment info / resource configuration file, for sisu
+# License: GPL v3 or later
+#   site environment configuration file
+#   this file should be configured and live in
+#      /etc/sisu     #per environment settings, overridden by:
+#      ~/.sisu       #per user settings, overridden by:
+#     ./_sisu        #per local markup directory settings
+#% #image source directory, main path and subdirectories
+#image:
+#  path:         'sisu_working'
+#  public:       '_sisu/image'
+#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name)
+#webserv:
+#  url_root:     'http://www.your.url' #without dir stub
+#  path:         '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
+#  images:       '_sisu/image'
+#  man:          'man'
+#  cgi:          '/usr/lib/cgi-bin'
+#  feed:         'feed'
+#  sqlite:       'sisu/sqlite'
+#  webrick_url:  true
+#show_output_on: 'filesystem' #for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path'
+#show_output_on: 'local:8111'
+#webserv_cgi:
+#  host:         localhost
+#  base_path:    ~
+#  port:         '8081'
+#  user:         ~
+show_output_on: 'filesystem_url'
+#texinfo display output
+#texinfo:
+#  stub:         'texinfo'
+##% processing directories, main path and subdirectories (appended to $HOME), using defaults set in sysenv
+#processing:
+#  path:         '~'
+#  dir:         '.sisu_processing~'
+#  metaverse:    'metaverse'
+#  tune:         'tune'
+#  latex:        'tex'
+#  texinfo:      'texinfo'
+#  concord_max:  400000
+#% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default)
+flag:
+  color:        true                        # making colour default -c is toggle, and will now toggle colour off
+  default:      '-NhwepoabxXyYv'            # -m run by default; includes verbose
+  i:            '-hwpoay'                   # -m run by default
+  ii:           '-NhwepoabxXy'              # -m run by default
+  iii:          '-NhwepoabxXyY'             # -m run by default
+  iv:           '-NhwepoabxXYDy --update'   # -m run by default
+  v:            '-NhwepoabxXYDyv --update'  # -m run by default; includes verbose
+#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal
+default:
+  papersize:    'A4,letter'
+  #text_wrap:    78
+  #emphasis:     'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold'
+  #digest:       'sha' #sha is sha256, default is md5
+  #multilingual:  false
+  #language_file: 2
+  #language:     'English'
+#% markup, make *{emphasis}* 'bold' or 'italics', default if not configured is 'bold'
+#% settings used by ssh scp
+#remote:
+#  -
+#    user:         '[usrname]'
+#    host:         '[remote.hostname]'
+#    path:         '.' #no trailing slash eg 'sisu/www'
+#  -
+#    user:         '[usrname]'
+#    host:         '[remote.hostname]'
+#    path:         '.' #no trailing slash eg 'sisu/www'
+#% webrick information
+#webrick:
+#  port:         '8081'
+#% sql database info, postgresql and sqlite
+#db:
+#  share_source: false # boolean, default is false
+#  postgresql:
+#    port:       # '[port (default is 5432)]'
+#    host:       # '[if not localhost, provide host tcp/ip address or domain name]''
+#    user:       # '[(if different from user) provide username]'
+#    password:   # '[password if required]'
+#  sqlite:
+#    path:       ~ # './sisu_sqlite.db'
+#    port:       "**"
+#% possible values ~, true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'.
+#will only ignore if value set to false, absence or nil will not remove program as should operate without rc file
+#ie in case of ~ will ignore and use hard coded defaults within program), true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'
+#on value true system defaults used, to change, e.g. editor specify
+permission_set:
+  zap:          false
+  css_modify:   false
+#  remote_base_site:  true
+program_set:
+  rmagick:       false
+#  wc:           true
+#  editor:       true
+#  postgresql:   true
+#  sqlite:       true
+#  tidy:         true
+#  rexml:        true
+#  pdflatex:     true
+#program_select:
+#  editor:       'gvim -c :R -c :S'
+#  pdf_viewer:   'evince'
+#  web_browser:  'firefox' #'iceweasel' #'epiphany' #'galeon' #'konqueror' #'kazehakase'
+#  console_www_browser:  'links2' #'elinks'
+#  odf_viewer:   'oowriter' #'abiword'
+#  xml_viewer:   'xml-viewer'
+#  man:          'nroff -man' #'groff -man -Tascii' # 'nroff -man'
+#promo:              sisu_icon, sisu, sisu_search_libre, open_society, fsf, ruby
+#search:
+#  sisu:
+#    flag:              true
+##    action:            http://localhost:8081/cgi-bin/sisu_pgsql.cgi
+#    action:            http://search.sisudoc.org
+#    db:                sisu
+#    title:             sample search form
+#  hyperestraier:
+#    flag:              true
+#    action:            http://search.sisudoc.org/cgi-bin/estseek.cgi?
diff --git a/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt b/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt
new file mode 100644
index 00000000..2695dda8
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/configuration_skin.txt
@@ -0,0 +1,15 @@
+                                                                       index.txt
+                                                               configuration.txt
+%% skin ------------------------------------------------------------------------
+
+skins can be used to modify the appearance of output
+
+[provide information]
+
+%% css ------------------------------------------------------------------------
+
+the default css may be replaced for the site or particular processing
+directories
+
+[provide information]
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/index.txt b/data/doc/sisu/v2/sisu_user_txt/index.txt
new file mode 100644
index 00000000..3e66cb19
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/index.txt
@@ -0,0 +1,5 @@
+%% Summary ---------------------------------------------------------------------
+
+markup.txt
+
+configuration.txt
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup.txt b/data/doc/sisu/v2/sisu_user_txt/markup.txt
new file mode 100644
index 00000000..4ab55606
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/markup.txt
@@ -0,0 +1,11 @@
+                                                                       index.txt
+%% Summary ---------------------------------------------------------------------
+
+markup_minimum_requirement.txt
+
+markup_content.txt
+
+markup_headers_metadata.txt
+
+markup_headers_processing_instructions.txt
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_content.txt b/data/doc/sisu/v2/sisu_user_txt/markup_content.txt
new file mode 100644
index 00000000..326fabe1
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/markup_content.txt
@@ -0,0 +1,296 @@
+                                                                       index.txt
+                                                                      markup.txt
+%% The Gory Details ------------------------------------------------------------
+
+%% comments --------------------------------------------------------------------
+
+Comments in sisu are a percentage sign at the start of a line followed by a
+space and then the comment
+
+% this would be a comment
+
+%% headings --------------------------------------------------------------------
+
+There are two sets of docment heading markers :A~ and an optional :B~ & :C~ and
+beneath that 1~, 2~, 3~. These markers are placed at the start of the
+line/paragraph, and followed by the heading
+
+There is usually one :A~ top level heading, which is the document title,
+sometimes including the author. This is such a common occurrence that there is
+a shortcut where metadata headers are provided for @title: and @creator
+:author:, instead of rewriting the title and author's name, you may write :A~
+@title @author
+
+If you have a document/manuscript that has subsections above the level of
+chapter, such as multiple books, parts, section, two additional top level
+headings are available :B~ and :C~
+
+At the main division level, usually chapter heading level 1~ begins, followed
+by 2~ and 3~ if the chapter has subheadings. Because the html and epub
+segmented output breaks level 1~ into separate files it is possible to provide
+the filename, e.g. 1~prologue Prologue
+
+Where names are provided following the heading tilde, these become tagged
+points within the document which can where the output format permits be
+(hyper-)linked to.
+
+%% font effect, modified font including emphasis -------------------------------
+
+Whithin normal text it is possible to modify the font effect of a word or
+phrase using the following markers:
+
+!{ bold }!
+
+/{ italics }/
+
+_{ underscore }_
+
+*{ emphasis }* (how emphasis is represented in output text can be defined in
+the header @make: section of a document or in the sisurc.yml config file, and
+this may be as bold, italics or underscore, the default being bold)
+
+^{ superscript }^
+
+,{ subscript },
+
++{ inserted text }+
+
+_{ strikethrough }_
+
+An exclamation mark followed by an underscore at the start of a line will bold
+that line until the first line-break
+
+!_ this line would be bold
+
+It is also possible to define in the header section under the @make: section
+which words or patterns should automatically be made bold or italics.
+
+@make:
+ :bold: /Gnu|Linux|Debian|Fedora|Ruby|SiSU/
+ :italics: /inter alia/
+
+%% indent ----------------------------------------------------------------------
+
+_1 a paragraph that is indented one level
+
+_2 a paragraph that is indented two steps
+
+%% bullet ----------------------------------------------------------------------
+
+_* bulleted text
+
+_1* bulleted indented text
+
+%% auto-numbering  -------------------------------------------------------------
+
+Some auto-numbering occurs in the building of sisu documents, either by default
+or when requested through configuration options
+
+%% auto-numbering document objects ---------------------------------------------
+
+Document objects are automatically given sequential object numbers, object
+citation numbers (ocn). If there is text that for some reason should not be
+regarded as substantive objects, it is possible to prevent a document number
+being given by adding ~# to the end of the object (paragraph/heading, etc.) ~#
+
+A variation used for headings that are added to provide document structure that
+should where possible not be included in output is -# a heading that is marked
+with -# is un-numbered and may be excluded from document outputs.
+
+%% auto-numbering headings -----------------------------------------------------
+
+Note auto-numbering of headings may be specified in the header @make: :num_top:
+by providing the heading level from which numbering is to start, this is
+usually at the chapter level (1~).
+
+@make:
+ :num_top: 1
+
+numbering continues three levels down, level 1 being numbered 1, 2, 3 ...
+level 2: 1.1, 1.2, 1.3 and so on
+level 3: 1.1.1, 1.1.2, 1.1.3
+
+It is also possible to make an auto-numbered list
+
+# numbered list                numbered list 1., 2., 3, etc.
+
+_# indented lettered list sub-level of previous list number a., b., c., d., etc.
+
+%% line breaks -----------------------------------------------------------------
+
+<:br> line break
+
+In paper/ page oriented outputs, such as LaTeX/pdf the following are avaiable
+
+<:pb> page or column break
+
+<:pn> new page
+
+in the header section under @make: :breaks: new and break set a page break or
+new page at the levels indicated, e.g.
+
+@make:
+ :breaks: new=C; break=1
+
+%% footnotes / endnotes --------------------------------------------------------
+
+This paragraph contains a footnote~{ a footnote or endnote }~ which would be
+automatically numbered
+
+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
+
+In addition to regular footnotes/endnotes there are astrisk and plus sign
+numbered and unnumbered footnotes.
+
+normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+
+%% tag points ------------------------------------------------------------------
+
+Tag points are markers within the document which may be used within the
+document for (internal document) linking where the output format permits. Tag
+names should use alphanumeric characters and underscores [a-z0-9_]+.
+
+There are different types of tag point, some automatically provided by sisu,
+such as each ocn (object citation number)
+
+Manual tags may be provided either:
+
+(a) with headings where a name is added to the heading level after the tilde:
+
+1~prefix [heading]
+
+(b) a tag marker can be added to a paragraph using an asterisk tilde and the
+name *~tag_marker
+
+%% links and urls --------------------------------------------------------------
+
+Urls found within text are marked up automatically, and where the output type
+permits is autmatically hyperlinked to inself and decorated with angled braces
+(unless contained in a code block, or escaped by a preceeding underscore).
+
+To link text or an image to a url the markup is as follows
+
+{ this is the linked section of text}http://url.org
+
+Where it is wished to include the url for the linked text in a footnote, the
+long form of markup would be:
+{ SiSU }http://www.jus.uio.no/sisu/ ~{ http://www.jus.uio.no/sisu/ }~
+
+A short form is provided for achieving the same:
+ {~^ SiSU }http://www.jus.uio.no/sisu/
+
+%% images ----------------------------------------------------------------------
+
+Images are placed in the directory beneath the location of the document to be
+processed _sisu/image
+
+The following are examples of links to images
+
+{ tux.png 64x80 }image
+
+{tux.png 64x80 "Gnu/Linux - a better way" }http://www.jus.uio.no/sisu/
+
+{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.jus.uio.no/sisu/
+
+The 64x80 in the first example is the image dimension, (width x height). This
+may be omitted if imagemagick or graphicsmagick are installed, as they will
+determine the image dimensions
+
+As with other linked text, the following markup
+
+{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
+
+maps to
+
+{ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ ~{ http://www.ruby-lang.org/en/ }~
+
+%% grouped text ----------------------------------------------------------------
+
+%% group -----------------------------------------------------------------------
+
+The start and end of text that is grouped are tagged. Grouped text retains its
+line breaks, and is treated as a unit, getting a single ocn
+
+group{
+
+License: GPL 3 or later:
+
+SiSU, a framework for document structuring, publishing and search
+
+Copyright (C) Ralph Amissah
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.
+
+If you have Internet connection, the latest version of the GPL should be
+available at these locations:
+<http://www.fsf.org/licensing/licenses/gpl.html>
+<http://www.gnu.org/licenses/gpl.html>
+
+}group
+
+%% poem ------------------------------------------------------------------------
+
+The start and end of a poem are tagged. Each verse in a poem is given an object
+number. Verses retain their line breaks.
+
+poem{
+
+verse here
+declare
+
+another verse
+here
+
+}poem
+
+%% table -----------------------------------------------------------------------
+
+{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
+
+
+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
+
+a second form may be easier to work with in cases where there is not much information in each column
+
+%% code ------------------------------------------------------------------------
+
+code{
+
+code lines here
+
+and so on
+
+}code
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt b/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt
new file mode 100644
index 00000000..c24789c8
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/markup_headers_metadata.txt
@@ -0,0 +1,34 @@
+                                                                       index.txt
+                                                                      markup.txt
+%% headers ---------------------------------------------------------------------
+
+%% header metadata -------------------------------------------------------------
+
+@title: SiSU
+ :subtitle: Markup
+
+@creator:
+ :author: Amissah, Ralph
+
+@rights:
+ :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation
+ :license: GPL 3 or later
+
+@classify:
+ :type: information
+ :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup
+ :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
+
+@date:
+ :created: 2002-08-28
+ :issued: 2002-08-28
+ :available: 2002-08-28
+ :published: 2008-05-22
+ :modified: 2010-05-25
+
+@links:
+ { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
+ { Book Samples and Markup Examples }http://www.jus.uio.no/SiSU/examples.html
+ { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+ { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+ { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt b/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt
new file mode 100644
index 00000000..b2c559c1
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/markup_headers_processing_instructions.txt
@@ -0,0 +1,12 @@
+                                                                       index.txt
+                                                                      markup.txt
+%% header processing instructions, @make: --------------------------------------
+
+Some document processing parameters can be set in the @make: section of the header
+
+@make:
+ :num_top: 1
+ :breaks: new=C; break=1
+ :skin: skin_sisu_manual
+ :bold: /Gnu|Debian|Ruby|SiSU/
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt b/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt
new file mode 100644
index 00000000..5eee046d
--- /dev/null
+++ b/data/doc/sisu/v2/sisu_user_txt/markup_minimum_requirement.txt
@@ -0,0 +1,79 @@
+                                                                       index.txt
+                                                                      markup.txt
+%% Summary ---------------------------------------------------------------------
+
+sisu takes an ASCII (UTF-8) document and abstracts the document into its
+structure and smaller constituent parts, objects. This abstraction is then used
+in subsequent processing to reconstitute the document into disparate document
+representations, many quite different from one another, e.g. HTML, ODF, LaTeX
+and to populate SQL
+
+SiSU identifies the document structure (headings and their levels) and pulls
+the document apart in to its constituent parts, objects (paragraphs, headings,
+tables, images etc.) to which it assigns an object number if substantive
+content.
+
+From the marked up document SiSU need to be able to determine a documents
+structure, and the objects that a document contains
+
+The first line of a SiSU marked up document can identify itself with
+
+%% Identify SiSU Document ------------------------------------------------------
+
+% SiSU
+
+%% The Basic SiSU Markup Document ----------------------------------------------
+
+SiSU documents are divided into two parts, (i) the document header and (ii)
+substantive content.
+
+(i) the document header, which contains (a)  metadata and (b) processing
+instructions if any. Document headers take the form of a tag and the related
+related information. The Document header, metadata, should contain at least:
+
+@title:
+
+@creator:
+  :author:
+
+Processing instructions are grouped under the @make: tag. In the absence of any
+program (or configured) defaults will be used.
+
+(ii) for the substantive content the document structure must be defined, here
+structure equates to the headings and their relative levels (this can be done
+either by explicit markup where each heading occurs, or in the header @make:
+section of the, or both).
+
+The basic document objects are headings and paragraphs. Paragraphs are
+identified automatically, and headings must be defined (with respect to
+document structure), so sisu is able to determine the basic objects without
+anything further.
+
+sample_1.sst
+
+%% Document Structure (heading levels) -----------------------------------------
+
+Document structure (heading levels) are determined from information provided in
+the markup of the document. There are two ways to identify document structure:
+(i) manual markup of headings with their level; (ii) in the sisu header, under
+@make: :heading: provide a regex, in the manner understood by sisu, that
+identifies what to look for in headings of various levels.
+
+Document structure is the different headings in a document, and their relative
+levels.
+
+There are two sets of docment level markers :A~ and an optional :B~ & :C~ and
+beneath that 1~, 2~, 3~.
+
+For the first set of document level markers the document Title being the top
+level in the hierarchy; beneath that book titles if the document contains more
+than one book followed by sections
+
+%% Document Objects (paragraphs, headings, tables, verse etc.) -----------------
+
+Document objects are units of text that are identified, stored and processed as
+a block. The most usual document objects would be paragraphs and headings. A
+more complete list of objects includes: paragraphs; headings; tables; code
+blocks; verse (the poem is identified, but each verse is an object); grouped
+text... 
+
diff --git a/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt b/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt
deleted file mode 100644
index 0af080c5..00000000
--- a/data/doc/sisu/v2/sisu_user_txt/sisu_markup.txt
+++ /dev/null
@@ -1,570 +0,0 @@
-%% Summary ---------------------------------------------------------------------
-
-sisu takes an ASCII (UTF-8) document and abstracts the document into its
-structure and smaller constituent parts, objects. This abstraction is then used
-in subsequent processing to reconstitute the document into disparate document
-representations, many quite different from one another, e.g. HTML, ODF, LaTeX
-and to populate SQL
-
-SiSU identifies the document structure (headings and their levels) and pulls
-the document apart in to its constituent parts, objects (paragraphs, headings,
-tables, images etc.) to which it assigns an object number if substantive
-content.
-
-From the marked up document SiSU need to be able to determine a documents
-structure, and the objects that a document contains
-
-The first line of a SiSU marked up document can identify itself with
-
-%% Identify SiSU Document ------------------------------------------------------
-
-% SiSU
-
-%% The Basic SiSU Markup Document ----------------------------------------------
-
-SiSU documents are divided into two parts:
-
-(i) the document header, which contains (a)  metadata and (b) processing
-instructions if any document headers take the form of a tag and the related
-related information
-
-(ii) the substantive content
-
-%% Minimum (SiSU) Markup Requirements ------------------------------------------
-
-minimum requirements for a SiSU document
-
-(i)(a) document header metadata, should contain at least:
-
-@title:
-
-@creator:
-  :author:
-
-(i)(b) processing instructions (grouped under @make:) are not required as there
-are defaults that will be used
-
-(ii) the substantive document structure must be defined, here structure equates
-to the headings and their relative levels, this can be done either by explicit
-markup where each heading occurs, or in the header @make: section of the, or
-both
-
-(iii) the basic document objects are headings and paragraphs. Paragraphs are
-identified automatically, and headings must be defined, so sisu is able to
-determine the basic objects without anything further
-
-sample_1.sst
-
-%% Document Structure ----------------------------------------------------------
-
-Document structure (heading levels) are determined from information provided in
-the markup of the document. There are two ways to identify document structure:
-(i) manual markup of headings with their level; (ii) in the sisu header, under
-@make: :heading: provide a regex, in the manner understood by sisu, that
-identifies what to look for in headings of various levels.
-
-Document structure is the different headings in a document, and their relative
-levels.
-
-There are two sets of docment level markers :A~ and an optional :B~ & :C~ and
-beneath that 1~, 2~, 3~.
-
-For the first set of document level markers the document Title being the top
-level in the hierarchy; beneath that book titles if the document contains more
-than one book followed by sections
-
-%% Document Objects ------------------------------------------------------------
-
-Document objects are units of text that are identified, stored and processed as
-a block. The most usual document objects would be paragraphs and headings. A
-more complete list of objects includes: paragraphs; headings; tables; code
-blocks; verse (the poem is identified, but each verse is an object); grouped
-text... 
-
-%% The Gory Details ------------------------------------------------------------
-
-
-%% comments --------------------------------------------------------------------
-
-Comments in sisu are a percentage sign at the start of a line followed by a
-space and then the comment
-
-% this would be a comment
-
-%% headings --------------------------------------------------------------------
-
-There are two sets of docment heading markers :A~ and an optional :B~ & :C~ and
-beneath that 1~, 2~, 3~. These markers are placed at the start of the
-line/paragraph, and followed by the heading
-
-There is usually one :A~ top level heading, which is the document title,
-sometimes including the author. This is such a common occurrence that there is
-a shortcut where metadata headers are provided for @title: and @creator
-:author:, instead of rewriting the title and author's name, you may write :A~
-@title @author
-
-If you have a document/manuscript that has subsections above the level of
-chapter, such as multiple books, parts, section, two additional top level
-headings are available :B~ and :C~
-
-At the main division level, usually chapter heading level 1~ begins, followed
-by 2~ and 3~ if the chapter has subheadings. Because the html and epub
-segmented output breaks level 1~ into separate files it is possible to provide
-the filename, e.g. 1~prologue Prologue
-
-Where names are provided following the heading tilde, these become tagged
-points within the document which can where the output format permits be
-(hyper-)linked to.
-
-%% font effect, modified font including emphasis -------------------------------
-
-Whithin normal text it is possible to modify the font effect of a word or
-phrase using the following markers:
-
-!{ bold }!
-
-/{ italics }/
-
-_{ underscore }_
-
-*{ emphasis }* (how emphasis is represented in output text can be defined in
-the header @make: section of a document or in the sisurc.yml config file, and
-this may be as bold, italics or underscore, the default being bold)
-
-^{ superscript }^
-
-,{ subscript },
-
-+{ inserted text }+
-
-_{ strikethrough }_
-
-An exclamation mark followed by an underscore at the start of a line will bold
-that line until the first line-break
-
-!_ this line would be bold
-
-It is also possible to define in the header section under the @make: section
-which words or patterns should automatically be made bold or italics.
-
-@make:
- :bold: /Gnu|Linux|Debian|Fedora|Ruby|SiSU/
- :italics: /inter alia/
-
-%% indent ----------------------------------------------------------------------
-
-_1 a paragraph that is indented one level
-
-_2 a paragraph that is indented two steps
-
-%% bullet ----------------------------------------------------------------------
-
-_* bulleted text
-
-_1* bulleted indented text
-
-%% auto-numbering  -------------------------------------------------------------
-
-Some auto-numbering occurs in the building of sisu documents, either by default
-or when requested through configuration options
-
-%% auto-numbering document objects ---------------------------------------------
-
-Document objects are automatically given sequential object numbers, object
-citation numbers (ocn). If there is text that for some reason should not be
-regarded as substantive objects, it is possible to prevent a document number
-being given by adding ~# to the end of the object (paragraph/heading, etc.) ~#
-
-A variation used for headings that are added to provide document structure that
-should where possible not be included in output is -# a heading that is marked
-with -# is un-numbered and may be excluded from document outputs.
-
-%% auto-numbering headings -----------------------------------------------------
-
-Note auto-numbering of headings may be specified in the header @make: :num_top:
-by providing the heading level from which numbering is to start, this is
-usually at the chapter level (1~).
-
-@make:
- :num_top: 1
-
-numbering continues three levels down, level 1 being numbered 1, 2, 3 ...
-level 2: 1.1, 1.2, 1.3 and so on
-level 3: 1.1.1, 1.1.2, 1.1.3
-
-It is also possible to make an auto-numbered list
-
-# numbered list                numbered list 1., 2., 3, etc.
-
-_# indented lettered list sub-level of previous list number a., b., c., d., etc.
-
-%% line breaks -----------------------------------------------------------------
-
-<:br> line break
-
-In paper/ page oriented outputs, such as LaTeX/pdf the following are avaiable
-
-<:pb> page or column break
-
-<:pn> new page
-
-in the header section under @make: :breaks: new and break set a page break or
-new page at the levels indicated, e.g.
-
-@make:
- :breaks: new=C; break=1
-
-%% footnotes / endnotes --------------------------------------------------------
-
-This paragraph contains a footnote~{ a footnote or endnote }~ which would be
-automatically numbered
-
-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
-
-In addition to regular footnotes/endnotes there are astrisk and plus sign
-numbered and unnumbered footnotes.
-
-normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
-
-normal text ~[+ editors notes, numbered asterisk footnote/endnote series ]~ continues
-
-normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
-
-%% tag points ------------------------------------------------------------------
-
-Tag points are markers within the document which may be used within the
-document for (internal document) linking where the output format permits. Tag
-names should use alphanumeric characters and underscores [a-z0-9_]+.
-
-There are different types of tag point, some automatically provided by sisu,
-such as each ocn (object citation number)
-
-Manual tags may be provided either:
-
-(a) with headings where a name is added to the heading level after the tilde:
-
-1~prefix [heading]
-
-(b) a tag marker can be added to a paragraph using an asterisk tilde and the
-name *~tag_marker
-
-%% links and urls --------------------------------------------------------------
-
-Urls found within text are marked up automatically, and where the output type
-permits is autmatically hyperlinked to inself and decorated with angled braces
-(unless contained in a code block, or escaped by a preceeding underscore).
-
-To link text or an image to a url the markup is as follows
-
-{ this is the linked section of text}http://url.org
-
-Where it is wished to include the url for the linked text in a footnote, the
-long form of markup would be:
-{ SiSU }http://www.jus.uio.no/sisu/ ~{ http://www.jus.uio.no/sisu/ }~
-
-A short form is provided for achieving the same:
- {~^ SiSU }http://www.jus.uio.no/sisu/
-
-%% images ----------------------------------------------------------------------
-
-Images are placed in the directory beneath the location of the document to be
-processed _sisu/image
-
-The following are examples of links to images
-
-{ tux.png 64x80 }image
-
-{tux.png 64x80 "Gnu/Linux - a better way" }http://www.jus.uio.no/sisu/
-
-{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.jus.uio.no/sisu/
-
-The 64x80 in the first example is the image dimension, (width x height). This
-may be omitted if imagemagick or graphicsmagick are installed, as they will
-determine the image dimensions
-
-As with other linked text, the following markup
-
-{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
-
-maps to
-
-{ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ ~{ http://www.ruby-lang.org/en/ }~
-
-%% grouped text ----------------------------------------------------------------
-
-%% group -----------------------------------------------------------------------
-
-The start and end of text that is grouped are tagged. Grouped text retains its
-line breaks, and is treated as a unit, getting a single ocn
-
-group{
-
-License: GPL 3 or later:
-
-SiSU, a framework for document structuring, publishing and search
-
-Copyright (C) Ralph Amissah
-
-This program is free software: you can redistribute it and/or modify it under
-the terms of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with
-this program. If not, see <http://www.gnu.org/licenses/>.
-
-If you have Internet connection, the latest version of the GPL should be
-available at these locations:
-<http://www.fsf.org/licensing/licenses/gpl.html>
-<http://www.gnu.org/licenses/gpl.html>
-
-}group
-
-%% poem ------------------------------------------------------------------------
-
-The start and end of a poem are tagged. Each verse in a poem is given an object
-number. Verses retain their line breaks.
-
-poem{
-
-verse here
-declare
-
-another verse
-here
-
-}poem
-
-%% table -----------------------------------------------------------------------
-
-{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
-
-
-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
-
-a second form may be easier to work with in cases where there is not much information in each column
-
-%% code ------------------------------------------------------------------------
-
-code{
-
-code lines here
-
-and so on
-
-}code
-
-%% headers ---------------------------------------------------------------------
-
-%% header metadata -------------------------------------------------------------
-
-@title: SiSU
- :subtitle: Markup
-
-@creator:
- :author: Amissah, Ralph
-
-@rights:
- :copyright: Copyright (C) Ralph Amissah 2007, part of SiSU documentation
- :license: GPL 3 or later
-
-@classify:
- :type: information
- :topic_register: electronic documents:SiSU:document:markup;SiSU:document:markup;SiSU:document:markup;SiSU:manual:markup;electronic documents:SiSU:manual:markup
- :subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search
-
-@date:
- :created: 2002-08-28
- :issued: 2002-08-28
- :available: 2002-08-28
- :published: 2008-05-22
- :modified: 2010-05-25
-
-@links:
- { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/
- { Book Samples and Markup Examples }http://www.jus.uio.no/SiSU/examples.html
- { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
- { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
- { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
-
-%% header processing instructions, @make: --------------------------------------
-
-Some document processing parameters can be set in the @make: section of the header
-
-@make:
- :num_top: 1
- :breaks: new=C; break=1
- :skin: skin_sisu_manual
- :bold: /Gnu|Debian|Ruby|SiSU/
-
-%% config, sisurc.yml ----------------------------------------------------------
-
-There are default configuration settings within the program many of which can
-be modified in sisurc.yml
-
-sisurc.yml can be located in one of the following locations:
-/etc/sisu/sisurc.yml    ~/.sisu/sisurc.yml    and ./_sisu/sisurc.yml
-
-if sisu versions 1 and 2 are both in use, the v2 sisurc.yml can be placed a the
-following locations:
-/etc/sisu/v2/sisurc.yml ~/.sisu/v2/sisurc.yml and ./_sisu/v2/sisurc.yml
-
-# Name: SiSU - Simple information Structuring Universe
-# Author: Ralph@Amissah.com
-# Description: Site wide envionment defaults set here
-# system environment info / resource configuration file, for sisu
-# License: GPL v3 or later
-#   site environment configuration file
-#   this file should be configured and live in
-#      /etc/sisu     #per environment settings, overridden by:
-#      ~/.sisu       #per user settings, overridden by:
-#     ./_sisu        #per local markup directory settings
-#% #image source directory, main path and subdirectories
-#image:
-#  path:         'sisu_working'
-#  public:       '_sisu/image'
-#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name)
-#webserv:
-#  url_root:     'http://www.your.url' #without dir stub
-#  path:         '/var/www' #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
-#  images:       '_sisu/image'
-#  man:          'man'
-#  cgi:          '/usr/lib/cgi-bin'
-#  feed:         'feed'
-#  sqlite:       'sisu/sqlite'
-#  webrick_url:  true
-#show_output_on: 'filesystem' #for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path'
-#show_output_on: 'local:8111'
-#webserv_cgi:
-#  host:         localhost
-#  base_path:    ~
-#  port:         '8081'
-#  user:         ~
-show_output_on: 'filesystem_url'
-#texinfo display output
-#texinfo:
-#  stub:         'texinfo'
-##% processing directories, main path and subdirectories (appended to $HOME), using defaults set in sysenv
-#processing:
-#  path:         '~'
-#  dir:         '.sisu_processing~'
-#  metaverse:    'metaverse'
-#  tune:         'tune'
-#  latex:        'tex'
-#  texinfo:      'texinfo'
-#  concord_max:  400000
-#% flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding colour and verbosity as default)
-flag:
-  color:        true                        # making colour default -c is toggle, and will now toggle colour off
-  default:      '-NhwepoabxXyYv'            # -m run by default; includes verbose
-  i:            '-hwpoay'                   # -m run by default
-  ii:           '-NhwepoabxXy'              # -m run by default
-  iii:          '-NhwepoabxXyY'             # -m run by default
-  iv:           '-NhwepoabxXYDy --update'   # -m run by default
-  v:            '-NhwepoabxXYDyv --update'  # -m run by default; includes verbose
-#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal
-default:
-  papersize:    'A4,letter'
-  #text_wrap:    78
-  #emphasis:     'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold'
-  #digest:       'sha' #sha is sha256, default is md5
-  #multilingual:  false
-  #language_file: 2
-  #language:     'English'
-#% markup, make *{emphasis}* 'bold' or 'italics', default if not configured is 'bold'
-#% settings used by ssh scp
-#remote:
-#  -
-#    user:         '[usrname]'
-#    host:         '[remote.hostname]'
-#    path:         '.' #no trailing slash eg 'sisu/www'
-#  -
-#    user:         '[usrname]'
-#    host:         '[remote.hostname]'
-#    path:         '.' #no trailing slash eg 'sisu/www'
-#% webrick information
-#webrick:
-#  port:         '8081'
-#% sql database info, postgresql and sqlite
-#db:
-#  share_source: false # boolean, default is false
-#  postgresql:
-#    port:       # '[port (default is 5432)]'
-#    host:       # '[if not localhost, provide host tcp/ip address or domain name]''
-#    user:       # '[(if different from user) provide username]'
-#    password:   # '[password if required]'
-#  sqlite:
-#    path:       ~ # './sisu_sqlite.db'
-#    port:       "**"
-#% possible values ~, true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'.
-#will only ignore if value set to false, absence or nil will not remove program as should operate without rc file
-#ie in case of ~ will ignore and use hard coded defaults within program), true, false, or command instruction e.g. editor: 'gvim -c :R -c :S'
-#on value true system defaults used, to change, e.g. editor specify
-permission_set:
-  zap:          false
-  css_modify:   false
-#  remote_base_site:  true
-program_set:
-  rmagick:       false
-#  wc:           true
-#  editor:       true
-#  postgresql:   true
-#  sqlite:       true
-#  tidy:         true
-#  rexml:        true
-#  pdflatex:     true
-#program_select:
-#  editor:       'gvim -c :R -c :S'
-#  pdf_viewer:   'evince'
-#  web_browser:  'firefox' #'iceweasel' #'epiphany' #'galeon' #'konqueror' #'kazehakase'
-#  console_www_browser:  'links2' #'elinks'
-#  odf_viewer:   'oowriter' #'abiword'
-#  xml_viewer:   'xml-viewer'
-#  man:          'nroff -man' #'groff -man -Tascii' # 'nroff -man'
-#promo:              sisu_icon, sisu, sisu_search_libre, open_society, fsf, ruby
-#search:
-#  sisu:
-#    flag:              true
-##    action:            http://localhost:8081/cgi-bin/sisu_pgsql.cgi
-#    action:            http://search.sisudoc.org
-#    db:                sisu
-#    title:             sample search form
-#  hyperestraier:
-#    flag:              true
-#    action:            http://search.sisudoc.org/cgi-bin/estseek.cgi?
-
-
-%% skin ------------------------------------------------------------------------
-
-skins can be used to modify the appearance of output
-
-[provide information]
-
-%% css ------------------------------------------------------------------------
-
-the default css may be replaced for the site or particular processing
-directories
-
-[provide information]