sisu - documents: markup, structuring, publishing in multiple standard formats, and search

SiSU   documents are prepared as plain-text (utf-8) files with SiSU markup. They may  make  reference  to
              and  contain  images  (for  example),  which are stored in the directory beneath them _sisu/image.
              〔b¤SiSU plaintext markup files are of three types that may be distinguished by the file extension
              used: regular text .sst; master documents, composite documents that incorporate other text,  which
              can  be  any  regular text or text insert; and inserts the contents of which are like regular text
              except these are marked .ssi and are not processed.

              SiSU processing can be done directly against a sisu documents; which may be located locally or  on
              a remote server for which a url is provided.

              SiSU source markup can be shared with the command:

                sisu -s [filename]

       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, TamingWindmills (1605), pp 1000 - 1001 also, Benkler, WealthofNetworks, (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)

       There  are 3 possibile output structures described as being, by language, by filetype or by filename, the
       selection is made in sisurc.yml
       #% output_dir_structure_by: language; filetype; or filename
       output_dir_structure_by: language   #(language & filetype, preferred?)
       #output_dir_structure_by: filetype
       #output_dir_structure_by: filename  #(default, closest to original v1 & v2)

       Header  tags  appear at the beginning of a document and provide meta information on the document (such as
       the DublinCore ) , 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 DublinCore 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]

       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]

       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

       ``` 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.

       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

       The by filename directory structure places most output of a particular file (the different filetypes)  in
       a common directory.

       Its selection is configured in sisurc.yml

       output_dir_structure_by: filename
           |-- epub
           |-- po4a
           |-- live-manual
           |     |-- po
           |     |-- fr
           |     `-- pot
           |-- _sisu
           | |-- css
           | |-- image
           | |-- image_sys -> ../../_sisu/image_sys
           | `-- xml
           |     |-- rnc
           |     |-- rng
           |     `-- xsd
           |-- sitemaps
           |-- src
           |-- pod
           `-- viral_spiral.david_bollier

       #by: filename subject_dir/filename/manifest.en.html

       The  by  filetype directory structure separates output files by filetype, all html files in one directory
       pdfs in another and so on. Filenames are given a language extension.

       Its selection is configured in sisurc.yml

       output_dir_structure_by: filetype
           |-- epub
           |-- hashes
           |-- html
           |-- viral_spiral.david_bollier
           |-- manifest
           |-- qrcode
           |-- odt
           |-- pdf
           |-- po4a
           |-- live-manual
           |     |-- po
           |     |-- fr
           |     `-- pot
           |-- _sisu
           | |-- css
           | |-- image
           | |-- image_sys -> ../../_sisu/image_sys
           | `-- xml
           |     |-- rnc
           |     |-- rng
           |     `-- xsd
           |-- sitemaps
           |-- txt
           |-- xhtml
           `-- xml

       #by: filetype subject_dir/html/filename/manifest.en.html

       The by language directory structure places output files

       The by language directory structure separates output files  by  language  code  (all  files  of  a  given
       language), and within the language directory by filetype.

       Its selection is configured in sisurc.yml

       output_dir_structure_by: language
           |-- en
           |-- epub
           |-- hashes
           |-- html
           | |-- viral_spiral.david_bollier
           | |-- manifest
           | |-- qrcode
           | |-- odt
           | |-- pdf
           | |-- sitemaps
           | |-- txt
           | |-- xhtml
           | `-- xml
           |-- po4a
           | `-- live-manual
           |     |-- po
           |     |-- fr
           |     `-- pot
           `-- _sisu
               |-- css
               |-- image
               |-- image_sys -> ../../_sisu/image_sys
               `-- xml
                   |-- rnc
                   |-- rng
                   `-- xsd

       #by: language subject_dir/en/manifest/filename.html

       For the search form, which is a single search page

       * configure the search form

       * generate the sample search form with the sisu  command,  (this  will  be  based  on  the  configuration
       settings and existing found sisu databases)

       For  postgresql  web  content  you may need to edit the search cgi script. Two things to look out for are
       that the user is set as needed, and that the any different databases that you wish to be  able  to  query
       are listed.

       correctly, you may want www-data rather than your username.
       @user='www-data'

       * check the search form, copy it to the appropriate cgi directory and set the correct permissions

       For a search form to appear on each html page, you need to:

       * rely on the above mentioned configuration of the search form

       * configure the html search form to be on

       * run the html command

       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]

       useofcodetagsinsteadofpoemcompared,resultingoutput:
                           `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."'

--no-ocn
              [with --html --pdf or --epub] switches off objectcitationnumbering.   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

       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.

       Mappings to two databases are provided by default, postgresql and sqlite,  the  same  commands  are  used
       within  sisu to construct and populate databases however -d (lowercase) denotes sqlite and -D (uppercase)
       denotes postgresql, alternatively --sqlite or --pgsql may be used

       -dor--sqlite may be used interchangeably.

       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.

SiSU  configration  parameters  are adjusted in the configuration file, which can be used to override the
       defaults set. This includes such things as which directory interim processing should be done in and where
       the generated output should be placed.

       The SiSU configuration file is a yaml file, which means indentation is significant.

       SiSU resource configuration is determined by looking at the following files if they exist:

         ./_sisu/v7/sisurc.yml

         ./_sisu/sisurc.yml

         ~/.sisu/v7/sisurc.yml~/.sisu/sisurc.yml

         /etc/sisu/v7/sisurc.yml

         /etc/sisu/sisurc.yml

       The search is in the order listed, and the first one found is used.

       In the absence of instructions in any of these it falls back to the internal program defaults.

       Configuration determines the output and processing directories and the database access details.

       If SiSU is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml

--sqlite--createall
              initial step, creates required relations  (tables,  indexes)  in  existing  (sqlite)  database  (a
              database  should  be  created manually and given the same name as working directory, as requested)
              (rb.dbi)

       sisu-d--createdb
              creates database where no database existed before

       sisu-d--create
              creates database tables where no database tables existed before

       sisu-d--dropall
              destroys database (including all its content)! kills data and drops tables, indexes  and  database
              associated with a given directory (and directories of the same name).

       sisu-d--recreate
              destroys existing database and builds a new empty database structure

       CSS  files  to  modify  the  appearance  of  SiSU  html,  XHTML or XML may be placed in the configuration
       directory: ./_sisu/css ; ~/.sisu/css or; /etc/sisu/css and these will be copied to the output directories
       with the command sisu -CC.

       The basic CSS file for html output is html. css, placing a file of that name in  directory  _sisu/css  or
       equivalent will result in the default file of that name being overwritten.

       HTML: html. css

       XML DOM: dom.css

       XML SAX: sax.css

       XHTML: xhtml. css

       The default homepage may use homepage.css or html. css

       Under consideration is to permit the placement of a CSS file with a different name in directory _sisu/css
       directory or equivalent.[^13]

dbi-databaseinterface--pgor--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 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.

       sisu_webrick is part of SiSU (man sisu) sisu_webrick starts RubySiSU output is written, providing a list
       of these directories (assuming SiSU is in use and they exist).

       The  default  port  for  sisu_webrick  is  set  to  8081,  this  may  be  modified  in  the  yaml   file:
       ~/.sisu/sisurc.yml  a sample of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory
       on your system).

       sisu  -W [port] starts Ruby Webrick web-server, serving SiSU output directories, on the port provided, or
       if no port is provided and the defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081

       The  document  source directory is the directory in which sisu processing commands are given. It contains
       the sisu source files (.sst .ssm .ssi), or (for sisu v3 may contain) subdirectories with  language  codes
       which  contain  the  sisu source files, so all English files would go in subdirectory en/, French in fr/,
       Spanish in es/ and so on. ISO 639-1 codes are used (as varied by po4a). A  list  of  available  languages
       (and  possible  sub-directory  names)  can  be  obtained  with the command "sisu --help lang" The list of
       languages is limited to langagues supported by XeTeX polyglosia.

markupexample:
       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}#

       resultingoutput:

       normal  text,  emphasis,boldtext  ,  italics,underscore,  "citation",  ^superscript^,  [subscript],
       ++inserted text++, --strikethrough--, monospace

       normal text

       emphasis [note: can be configured to be represented by bold, italics or underscore]

       boldtextitalicsunderscore

       "citation"

       ^superscript^

       [subscript]

       ++inserted text++


       --strikethrough--
       monospace

       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

       markupexample:
       ~{ a footnote or endnote }~

       resultingoutput:

       [^5]

       markupexample:
       normal text~{ self contained endnote marker & endnote in one }~ continues

       resultingoutput:

       normal text[^6] continues

       markupexample:
       normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues

       normal text ~{** another unnumbered asterisk footnote/endnote }~ continues

       resultingoutput:

       normal text [^*] continues

       normal text [^**] continues

       markupexample:
       normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues

       normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues

       resultingoutput:

       normal text [^*3] continues

       normal text [^+2] continues

       Alternativeendnotepairnotationforfootnotes/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

        ./subject_name/

       % files stored at this level e.g. sisu_manual.sst or
       % for sisu v3 may be under language sub-directories
       % e.g.

        ./subject_name/en

        ./subject_name/fr

        ./subject_name/es

        ./subject_name/_sisu

        ./subject_name/_sisu/css

        ./subject_name/_sisu/image

       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.

basicmarkup:
       group{

         Your grouped text here

       }group

       A group is treated as an object and given a single object number.

       markupexample:
       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

       resultingoutput:
                           `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."'

       There are two markup syntaxes for blocked text, using curly braces or using tics

markupexample:
       _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

       resultingoutput:

       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.
         .I 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.

       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~[headingtext] 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~[headingtext] Second level heading [this is a heading level divider]

       :C~[headingtext] Third level heading [this is a heading level divider]

       1~[headingtext] 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~[headingtext] 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~[headingtext]  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)

       Custom built pages, including the home page index.html may be placed within the  configuration  directory
       _sisu/home/  in  any  of the locations that is searched for the configuration directory, namely ./_sisu ;
       ~/_sisu ; /etc/sisu From there they are copied to the root of the output directory with the command:

         sisu -CC

SiSU  is about the ability to auto-generate documents. Home pages are regarded as custom built items, and
       are not created by SiSU.  More accurately, SiSU has a default home page, which will  not  be  appropriate
       for  use with other sites, and the means to provide your own home page instead in one of two ways as part
       of a site's configuration, these being:

       1. through placing your home page and other custom built documents in the subdirectory _sisu/home/  (this
       probably being the easier and more convenient option)

       2. through providing what you want as the home page in a skin,

       Document  sets  are  contained  in  directories,  usually  organised  by  site or subject. Each directory
       can/should have its own homepage. See the section on directory structure and organisation of content.

sisu-d--import-v[filename/wildcard]
              populates  database  with  the  contents  of the file. Imports documents(s) specified to an sqlite
              database (at an object level).

       sisu-d--update-v[filename/wildcard]
              updates file contents in database

       sisu-d--remove-v[filename/wildcard]
              removes specified document from sqlite database.

markupexample:
       ordinary paragraph

       _1 indent paragraph one step

       _2 indent paragraph two steps

       _9 indent paragraph nine steps

       resultingoutput:

       ordinary paragraph

         indent paragraph one step

           indent paragraph two steps

                         indent paragraph nine steps

       markupexample:
       _* bullet text

       _1* bullet text, first indent

       _2* bullet text, two step indent

       resultingoutput:

       * bullet text

         * bullet text, first indent

           * bullet text, two step indent

       Numbered List (not to be confused with headings/titles, (document structure))

       markupexample:
       # numbered list                numbered list 1., 2., 3, etc.

       _# numbered list numbered list indented a., b., c., d., etc.

       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

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>

       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.

       TREE

       markupexample:
       !_ /{"Viral Spiral"}/, David Bollier

       { "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst

       ViralSpiral,       David       Bollier       "Viral       Spiral",       David       Bollier
       <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
            document manifest <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
             ⌠html, segmented text⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
             ⌠html,                          scroll,                         document                         in
       one⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
             ⌠epub⌡「http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」
             ⌠pdf, landscape⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
             ⌠pdf, portrait⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
             ⌠odf: odt, open document text⌡「http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」
             ⌠xhtml scroll⌡「http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」
             ⌠xml, sax⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
             ⌠xml, dom⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
             ⌠concordance⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
             ⌠dcc,                      document                       content                       certificate
       (digests)⌡「http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」
             ⌠markup source text⌡「http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」
             ⌠markup                                       source                                       (zipped)
       pod⌡「http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」

markupexample:
       { tux.png 64x80 }image

       % various url linked images

       {tux.png 64x80 "a better way" }http://www.sisudoc.org/

       {GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/

       {~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/resultingoutput:

       [ tux.png ]

       tux.png 64x80 "Gnu/Linux - a better way" <http://www.sisudoc.org/>

       GnuDebianLinuxRubyBetterWay.png    100x101   "Way   Better   -   with   Gnu/Linux,   Debian   and   Ruby"
       <http://www.sisudoc.org/>

       ruby_logo.png 70x90 "Ruby" <http://www.ruby-lang.org/en/> [^8]

       linkedurlfootnoteshortcut
       {~^ [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.

       To link text or an image to a url the markup is as follows

       markupexample:
       about { SiSU }http://url.org markup

       resultingoutput:

       aboutSiSU <http://www.sisudoc.org/> markup

       A shortcut notation is available so the url link may also be provided automatically as a footnote

       markupexample:
       about {~^ SiSU }http://url.org markup

       resultingoutput:

       aboutSiSU <http://www.sisudoc.org/> [^7] markup

       Internal document links to a tagged location, including an ocn

       markupexample:
       about { text links }#link_text

       resultingoutput:

       about ⌠text links⌡⌈link_text⌋

       Shared document collection link

       markupexample:
       about { SiSU book markup examples }:SiSU/examples.html

       resultingoutput:

       about ⌠ SiSU book markup examples⌡⌈:SiSU/examples.html⌋

       Current  markup  examples  and  document  output  samples  are  provided  off   <http://sisudoc.org>   or
       <http://www.jus.uio.no/sisu>    and    in    the    sisu    -markup-sample    package    available    off
       <http://git.sisudoc.org>

       For some documents hardly any markup at all is required at all, other than a header,  and  an  indication
       that the levels to be taken into account by the program in generating its output are.

       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

       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)

       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).

       markupexample:
       normal text http://www.sisudoc.org/ continues

       resultingoutput:

       normal text <http://www.sisudoc.org/> continues

       An escaped url without decoration

       markupexample:
       normal text _http://www.sisudoc.org/ continues

       deb _http://www.jus.uio.no/sisu/archive unstable main non-free

       resultingoutput:

       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

       resultingoutput:
       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

SiSU - Structured information, Serialized Units - a document publishing system

       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

SiSU v3 has new options for the source directory tree, and output directory structures of which there are
       3 alternatives.

       The output directory root can be set in the sisurc.yml file. Under the root, subdirectories are made  for
       each  directory in which a document set resides. If you have a directory named poems or conventions, that
       directory will be created under the output directory root and the output for all documents  contained  in
       the  directory  of  a particular name will be generated to subdirectories beneath that directory (poem or
       conventions). A document will be placed in a subdirectory of the same  name  as  the  document  with  the
       filetype identifier stripped (.sst .ssm)

       The last part of a directory path, representing the sub-directory in which a document set resides, is the
       directory  name that will be used for the output directory. This has implications for the organisation of
       document collections as it could make sense to place documents of a particular subject, or type within  a
       directory   identifying   them.   This   grouping   as   suggested   could   be  by  subject  (sales_law,
       english_literature); or just as conveniently by some other classification  (X  University).  The  mapping
       means  it  is  also  possible to place in the same output directory documents that are for organisational
       purposes kept separately, for example documents on a given subject of two different institutions  may  be
       kept  in  two different directories of the same name, under a directory named after each institution, and
       these would be output to the same output directory. Skins could be associated with each institution on  a
       directory basis and resulting documents will take on the appropriate different appearance.

       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):
       -..-

basicmarkup:
       poem{

         Your poem here

       }poem

       Each verse in a poem is given an object number.

       markupexample:
       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

       resultingoutput:
                           `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."'

       TO populate the sql database, run sisu against a sisu markup file with one of the following sets of flags
       sisu --sqlite filename.sst

       creates an sqlite3 database containing searchable content of just the sisu markup document selected
       sisu --sqlite --update filename.sst

       creates  an  sqlite3 database containing searchable content of marked up document(s) selected by the user
       from a common directory
       sisu --pg --update filename.sst

       fills a postgresql database with searchable content of marked up document(s) selected by the user from  a
       common directory

       For postgresql the first time the command is run in a given directory the user will be prompted to create
       the requisite database, at the time of writing the prompt sisu provides is as follows:
       no connection with pg database established, you may need to run:
           createdb "SiSU.7a.current"
         after that don't forget to run:
           sisu --pg --createall
         before attempting to populate the database

       The  named  database  that  sisu  expects to find must exist and if necessary be created using postgresql
       tools. If the database exist but the database tables do not, sisu will attempt to create  the  tables  it
       needs, the equivalent of the requested sisu --pg --createall command.

       Once this is done, the sql database is populated and ready to be queried.

        ./subject_name/

       % containing sub_directories named after the generated files from which they are made

        ./subject_name/src

       % contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip

        ./subject_name/_sisu

       % configuration file e.g. sisurc.yml

        ./subject_name/_sisu/skin

       % skins in various skin directories doc, dir, site, yml

        ./subject_name/_sisu/css

        ./subject_name/_sisu/image

       % images for documents contained in this directory

        ./subject_name/_sisu/mm

       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

       INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)

       Sample search frontend <http://search.sisudoc.org> [^16] A small  database  and  sample  query  front-end
       (search  from)  that  makes  use  of  the  citation  system, .I object citation numbering to demonstrates
       functionality.[^17]

       SiSU can provide information on which documents are matched and at what locations  within  each  document
       the  matches  are  found.  These results are relevant across all outputs using objectcitationnumbering,
       which includes html, XML,EPUB,LaTeX,PDF and indeed the SQL database. You can then refer to one of  the
       other  outputs  or  in  the  SQL  database expand the text within the matched objects (paragraphs) in the
       documents matched.

       Note you may set results either for documents matched and object number  locations  within  each  matched
       document  meeting  the  search  criteria;  or  display  the names of the documents matched along with the
       objects (paragraphs) that meet the search criteria.[^18]

       sisu-F--webserv-webrick
              builds a cgi web search frontend for the database created

              The following is feedback on the setup on a machine provided by the help command:

                sisu --help sql
              Postgresql
                user:             ralph
                current db set:   SiSU_sisu
                port:             5432
                dbi connect:      DBI:Pg:database=SiSU_sisu;port=5432

              sqlite
                current db set:   /home/ralph/sisu_www/sisu/sisu_sqlite.db
                dbi connect       DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db

              Note on databases built

              By default,  [unless  otherwise  specified]  databases  are  built  on  a  directory  basis,  from
              collections  of documents within that directory. The name of the directory you choose to work from
              is used as the database name, i.e. if you are working in a directory called /home/ralph/ebook  the
              database SiSU_ebook is used. [otherwise a manual mapping for the collection is necessary]

sisu-F
              generates a sample search form, which must be copied to the web-server cgi directory

       sisu-F--webserv-webrick
              generates  a  sample search form for use with the webrick server, which must be copied to the web-
              server cgi directory

       sisu-W
              starts the webrick server which should be available wherever sisu is properly installed

              The generated search form must be copied manually to the webserver directory as instructed

       You  will  need  a web server, httpd with cgi enabled, and a postgresql database to which you are able to
       create databases.

       Setup postgresql, make sure you are able to create and write to the database, e.g.:
       sudo su postgres
         createuser -d -a ralph

       You then need to create the database that sisu will use, for sisu manual in the directory  manual/en  for
       example, (when you try to populate a database that does not exist sisu prompts as to whether it exists):
       createdb SiSU.7a.manual

       SiSU is then able to create the required tables that allow you to populate the database with documents in
       the directory for which it has been created:
       sisu --pg --createall -v

       You can then start to populate the database, in this example with a single document:
       sisu --pg --update -v en/sisu_manual.ssm

       To create a sample search form, from within the same directory run:
       sisu --sample-search-form --db-pg

       and copy the resulting cgi form to your cgi-bin directory

       A  sample  setup  for  nginx  is provided that assumes data will be stored under /srv/www and cgi scripts
       under /srv/cgi

       RALPH AMISSAH

       This fell out of date and has been discontinued.

SiSU has plaintext and binary filetypes, and can process either type of document.

       Inserts  are  documents  prepared  solely  for  the purpose of being incorporated into one or more master
       documents. They resemble regular SiSU text files (.sst). Since sisu -5.5.0 (6.1.0) .ssi  files  can  like
       .ssm  files  include other .sst or .ssm files. .ssi files cannot be called by the sisu processor directly
       and can only be incorporated in other documents. Making a file a .ssi file is a quick and convenient  way
       of  breaking  up a document that is to be included in a master document, and flagging that the file to be
       incorporated .ssi is not intended that the file should be processed on its own.

       If SiSU is installed on your system usual man commands should be available, try:

         man sisu

       Most  SiSU man pages are generated directly from sisu documents that are used to prepare the sisu manual,
       the sources files for which are located within the SiSU tarball at:

         ./data/doc/sisu/markup-samples/sisu_manual

       Once installed, directory equivalent to:

         /usr/share/doc/sisu/markup-samples/sisu_manual

       Available man pages are converted back to html using man2html:

         /usr/share/doc/sisu/html/

         ./data/doc/sisu/html

       An online version of the sisu man page is available here:

       * various sisu man pages <http://www.jus.uio.no/sisu/man/> [^1]

       * sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> [^2]

       The most up to date information on sisu should be contained in the sisu_manual, available at:

         <http://sisudoc.org/sisu/sisu_manual/>

       The manual can be generated from source, found respectively, either within the SiSU tarball or  installed
       locally at:

         ./data/doc/sisu/markup-samples/sisu_manual

         /usr/share/doc/sisu/markup-samples/sisu_manual

       move to the respective directory and type e.g.:

         sisu sisu_manual.ssm

       A  few additional sample books prepared as sisu markup samples, output formats to be generated using SiSU
       are contained in a separate package sisu -markup-samples. sisu -markup-samples contains  books  (prepared
       using  sisu  markup),  that  were  released  by  their authors various licenses mostly different Creative
       Commons licences that do not permit inclusion in the Debian Project as they have requirements that do not
       meet the Debian Free Software Guidelines for various reasons, most commonly that they  require  that  the
       original substantive text remain unchanged, and sometimes that the works be used only non-commercially.

       Accelerando, Charles Stross (2005) accelerando.charles_stross.sst

       Alice'sAdventuresinWonderland, Lewis Carroll (1865) alices_adventures_in_wonderland.lewis_carroll.sst

       CONTENT, Cory Doctorow (2008) content.cory_doctorow.sst

       DemocratizingInnovation, Eric von Hippel (2005) democratizing_innovation.eric_von_hippel.sst

       DownandOutintheMagicKingdom,      Cory      Doctorow      (2003)
       down_and_out_in_the_magic_kingdom.cory_doctorow.sst

       FortheWin, Cory Doctorow (2010) for_the_win.cory_doctorow.sst

       FreeasinFreedom-RichardStallman'sCrusadeforFreeSoftware,   Sam   Williams   (2002)
       free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst

       FreeasinFreedom2.0-RichardStallmanandtheFreeSoftwareRevolution, Sam Williams (2002), Richard
       M.                                            Stallman                                             (2010)
       free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst

       FreeCulture-HowBigMediaUsesTechnologyandtheLawtoLockDown Culture and Control Creativity,
       Lawrence Lessig (2004) free_culture.lawrence_lessig.sst

       FreeForAll-HowLinuxandtheFreeSoftwareMovementUndercuttheHigh  Tech  Titans,  Peter  Wayner
       (2002) free_for_all.peter_wayner.sst

       GNUGENERALPUBLICLICENSEv2, Free Software Foundation (1991) gpl2.fsf.sst

       GNUGENERALPUBLICLICENSEv3, Free Software Foundation (2007) gpl3.fsf.sst

       Gulliver'sTravels, Jonathan Swift (1726 / 1735) gullivers_travels.jonathan_swift.sst

       LittleBrother, Cory Doctorow (2008) little_brother.cory_doctorow.sst

       TheCathederalandtheBazaar, Eric Raymond (2000) the_cathedral_and_the_bazaar.eric_s_raymond.sst

       ThePublicDomain-EnclosingtheCommonsoftheMind,   James   Boyle   (2008)
       the_public_domain.james_boyle.sst

       TheWealthofNetworks-HowSocialProductionTransformsMarketsand  Freedom,  Yochai  Benkler  (2006)
       the_wealth_of_networks.yochai_benkler.sst

       ThroughtheLookingGlass, Lewis Carroll (1871) through_the_looking_glass.lewis_carroll.sst

       TwoBits-TheCulturalSignificanceofFreeSoftware,   Christopher   Kelty   (2008)
       two_bits.christopher_kelty.sst

       UNContractsforInternationalSaleofGoods,        UN        (1980)
       un_contracts_international_sale_of_goods_convention_1980.sst

       ViralSpiral, David Bollier (2008) viral_spiral.david_bollier.sst

       Composite  documents  which  incorporate  other SiSU documents which may be either regular SiSU text .sst
       which may be generated independently, or inserts prepared solely for the purpose  of  being  incorporated
       into one or more master documents.

       The mechanism by which master files incorporate other documents is described as one of the headings under
       under SiSU markup in the SiSU manual.

       Note:  Master  documents may be prepared in a similar way to regular documents, and processing will occur
       normally if a .sst file is renamed .ssm without requiring any other documents; the .ssm marker flags that
       the document may contain other documents.

       Note: a secondary file of the composite document is built prior to processing with the  same  prefix  and
       the suffix ._sst [^12]

       Because  the  document structure of sites created is clearly defined, and the text objectcitationsystem
       is available hypothetically at least, for all forms of output, it is possible to search the sql database,
       and either read results from that database, or map the results to the html or  other  output,  which  has
       richer text markup.

       SiSU  can  populate  a  relational sql type database with documents at an object level, including objects
       numbers that are shared across different output types. Making a  document  corpus  searchable  with  that
       degree  of  granularity.  Basically, your match criteria is met by these documents and at these locations
       within each document, which can be viewed within the database directly or in various output formats.

       SiSU can populate an sql database (sqlite3 or postgresql) with documents made up  of  their  objects.  It
       also can generate a cgi search form that can be used to query the database.

       In order to use the built in search functionality you would take the following steps.

       * use sisu to populate an sql database with with a sisu markup content

         * sqlite3 should work out of the box

         * postgresql may require some initial database configuration

       * provide a way to query the database, which sisu can assist with by

         * generating a sample ruby cgi search form, required (sisu configuration
         recommended)

         * adding a query field for this search form to be added to all html files
         (sisu configuration required)

       The most common form of document in SiSU, see the section on SiSU markup.

       Most sisu document headers relate to  metadata,  the  exception  is  the  @make:  header  which  provides
       processing  related information. The default contents of the @make header may be set by placing them in a
       file sisu_document_make.

       The search order is as for resource configuration:

         ./_sisu/v7/sisu_document_make

         ./_sisu/sisu_document_make

         ~/.sisu/v7/sisu_document_make~/.sisu/sisu_document_make

         /etc/sisu/v7/sisu_document_make

         /etc/sisu/sisu_document_make

       A sample sisu_document_make can be found in the _sisu/ directory  under  along  with  the  provided  sisu
       markup samples.

        ./sisupod/

       % files stored at this level e.g. sisu_manual.sst

        ./sisupod/_sisu

       % configuration file e.g. sisurc.yml

        ./sisupod/_sisu/skin

       % skins in various skin directories doc, dir, site, yml

        ./sisupod/_sisu/css

        ./sisupod/_sisu/image

       % images for documents contained in this directory

        ./sisupod/_sisu/mm

       A sisupod is a zipped SiSU text file or set of SiSU text  files  and  any  associated  images  that  they
       contain (this will be extended to include sound and multimedia-files)

       SiSUplaintext  files  rely  on  a  recognised  directory  structure  to  find  contents such as images
              associated with documents, but all images for example for all documents contained in  a  directory
              are  located  in  the sub-directory _sisu/image. Without the ability to create a sisupod it can be
              inconvenient to  manually  identify  all  other  files  associated  with  a  document.  A  sisupod
              automatically bundles all associated files with the document that is turned into a pod.

              The  structure  of  the  sisupod is such that it may for example contain a single document and its
              associated images; a master document and its associated documents and anything else; or the zipped
              contents of a whole directory of prepared SiSU documents.

              The command to create a sisupod is:

                sisu -S [filename]

              Alternatively, make a pod of the contents of a whole directory:

                sisu -S

              SiSU processing can be done directly against a sisupod; which may  be  located  locally  or  on  a
              remote server for which a url is provided.

              <http://www.sisudoc.org/sisu/sisu_commands>

              <http://www.sisudoc.org/sisu/sisu_manual>

SiSU  feeds  sisu  markup documents into sql type databases PostgreSQL [^14] and/or SQLite [^15] database
       together with information related to document structure.

       This is one of the more interesting output forms, as  all  the  structural  data  of  the  documents  are
       retained  (though  can  be  ignored  by  the  user  of  the  database  should  they  so choose). All site
       texts/documents are (currently) streamed to four tables:

         * one containing semantic (and other) headers, including, title, author,
         subject, (the
         .I Dublin Core.
         ..);

         * another the substantive texts by individual "paragraph" (or object) - along
         with structural information, each paragraph being identifiable by its
         paragraph number (if it has one which almost all of them do), and the
         substantive text of each paragraph quite naturally being searchable (both in
         formatted and clean text versions for searching); and

         * a third containing endnotes cross-referenced back to the paragraph from
         which they are referenced (both in formatted and clean text versions for
         searching).

         * a fourth table with a one to one relation with the headers table contains
         full text versions of output, eg. pdf, html, xml, and
         .I ascii.

       There is of course the possibility to add further structures.

       At this level SiSU loads a relational database  with  documents  chunked  into  objects,  their  smallest
       logical  structurally constituent parts, as text objects, with their object citation number and all other
       structural information needed to construct the document. Text is stored (at this text object level)  with
       and without elementary markup tagging, the stripped version being so as to facilitate ease of searching.

       Being  able  to  search  a  relational  database  at  an object level with the SiSU citation system is an
       effective way of locating content generated by SiSU.  As individual text objects  of  a  document  stored
       (and  indexed)  together  with  object numbers, and all versions of the document have the same numbering,
       complex searches can be tailored to return just the locations of the  search  results  relevant  for  all
       available  output  formats,  with  live  links  to  the  precise locations in the database or in html/xml
       documents; or, the structural information provided makes it possible to search the full contents  of  the
       database  and  have  headings  in  which  search content appears, or to search only headings etc. (as the
       DublinCore is incorporated it is easy to make use of that as well).

markupexample:
       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}*'

       resultingoutput:

       The current Debian is Jessie the next debian will be Stretch

       Configure substitution in _sisu/sisu_document_make

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.

       * sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a single UTF-8 file using a
       minimalistic mnemonic syntax. Typical literature, documents  like  "War  and  Peace"  require  almost  no
       markup, and most of the headers are optional.

       *  markup is easily readable/parsable by the human eye, (basic markup is simpler and more sparse than the
       most basic HTML ) , [this may  also  be  converted  to  XML  representations  of  the  same  input/source
       document].

       *  markup defines document structure (this may be done once in a header pattern-match description, or for
       heading levels individually); basic text attributes (bold, italics, underscore, strike-through  etc.)  as
       required;  and  semantic  information  related  to  the document (header information, extended beyond the
       Dublin core  and  easily  further  extended  as  required);  the  headers  may  also  contain  processing
       instructions.   SiSU  markup  is  primarily an abstraction of document structure and document metadata to
       permit taking advantage of the basic  strengths  of  existing  alternative  practical  standard  ways  of
       representing  documents  [be  that browser viewing, paper publication, sql search etc.] (html, epub, xml,
       odf, latex, pdf, sql)

       * for output produces reasonably elegant output of established industry and institutionally accepted open
       standard formats.[3] takes  advantage  of  the  different  strengths  of  various  standard  formats  for
       representing documents, amongst the output formats currently supported are:

       * HTML - both as a single scrollable text and a segmented document

       * XHTML

       * EPUB

       * XML - both in sax and dom style xml structures for further development as required

       * ODT - Open Document Format text, the iso standard for document storage

       * LaTeX - used to generate pdf

       * PDF (via LaTeX )

       *  SQL  - population of an sql database ( PostgreSQL or SQLite ) , (at the same object level that is used
       to cite text within a document)

       Also produces: concordance files; document content certificates  (md5  or  sha256  digests  of  headings,
       paragraphs,  images  etc.)  and  html  manifests  (and  sitemaps  of content). (b) takes advantage of the
       strengths implicit in these very different output types, (e.g. PDFs produced using typesetting of  LaTeX,
       databases  populated  with  documents  at  an individual object/paragraph level, making possible granularsearch (and related possibilities))

       * ensuring content can be cited in  a  meaningful  way  regardless  of  selected  output  format.  Online
       publishing  (and  publishing  in  multiple document formats) lacks a useful way of citing text internally
       within documents (important to academics generally and to lawyers) as page numbers are meaningless across
       browsers and formats. sisu seeks to provide a common way of pinpoint the text within a  document,  (which
       can be utilized for citation and by search engines).  The outputs share a common numbering system that is
       meaningful  (to  man and machine) across all digital outputs whether paper, screen, or database oriented,
       (pdf, HTML,EPUB, xml, sqlite, postgresql) , this numbering system can be used to reference content.

       * Granular search within documents.  SQL databases are populated at an object  level  (roughly  headings,
       paragraphs,  verse, tables) and become searchable with that degree of granularity, the output information
       provides the object/paragraph numbers which are  relevant  across  all  generated  outputs;  it  is  also
       possible  to look at just the matching paragraphs of the documents in the database; [output indexing also
       work well with search indexing tools like hyperestraier].

       * long term maintainability of document collections in  a  world  of  changing  formats,  having  a  very
       sparsely  marked-up  source  document  base.  there  is  a considerable degree of future-proofing, output
       representations are "upgradeable", and new document formats may be added.  e.g.  addition  of  odf  (open
       document  text)  module  in  2006,  epub  in  2009 and in future html5 output sometime in future, without
       modification of existing prepared texts

       * SQL search aside, documents are generated as required and static once generated.

       * documents produced are static files, and may be batch processed, this needs to be done  only  once  but
       may  be repeated for various reasons as desired (updated content, addition of new output formats, updated
       technology document presentations/representations)

       * document source ( plaintext utf-8) if shared on the net may be used as input and processed  locally  to
       produce the different document outputs

       *  document  source  may be bundled together (automatically) with associated documents (multiple language
       versions or master document with inclusions) and images and sent as a  zip  file  called  a  sisupod,  if
       shared on the net these too may be processed locally to produce the desired document outputs

       * generated document outputs may automatically be posted to remote sites.

       *  for  basic  document  generation,  the only software dependency is Ruby, and a few standard Unix tools
       (this covers plaintext,HTML,EPUB,XML,ODF,LaTeX ) . To use a database you of course need that, and to
       convert the LaTeX generated to pdf, a latex processor like tetex or texlive.

       * as a developers tool it is flexible and extensible

       Syntax highlighting for SiSU markup is available for a number of text editors.

       SiSU is less about document layout than about finding a way with little markup to be able to construct an
       abstract representation of a document that makes it possible to produce multiple  representations  of  it
       which  may  be  rather  different  from  each  other  and used for different purposes, whether layout and
       publishing, or search of content

       i.e. to be able to take advantage from this minimal preparation starting point of some of  the  strengths
       of rather different established ways of representing documents for different purposes, whether for search
       (relational  database, or indexed flat files generated for that purpose whether of complete documents, or
       say of files made up of objects), online viewing (e.g. html, xml, pdf) , or paper publication (e.g.  pdf)
       ...

       the solution arrived at is by extracting structural information about the document (about headings within
       the  document)  and  by  tracking objects (which are serialized and also given hash values) in the manner
       described. It makes possible representations that are quite different from those offered at present.  For
       example  objects  could  be  saved  individually and identified by their hashes, with an index of how the
       objects relate to each other to form a document.

       *1.    square brackets

       *2.    square brackets

       +1.    square brackets

       1.     <http://www.jus.uio.no/sisu/man/>

       2.     <http://www.jus.uio.no/sisu/man/sisu.1.html>

       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

       12.    is  not  a  regular  file to be worked on, and thus less likely that people will have "accidents",
              working on a .ssc file that is overwritten by subsequent processing. It may be however  that  when
              the resulting file is shared .ssc is an appropriate suffix to use.

       13.    SiSU  has  worked  this  way in the past, though this was dropped as it was thought the complexity
              outweighed the flexibility, however, the balance was rather  fine  and  this  behaviour  could  be
              reinstated.

       14.    <http://www.postgresql.org/>                                     <http://advocacy.postgresql.org/>
              <http://en.wikipedia.org/wiki/Postgresql>

       15.    <http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>

       16.    <http://search.sisudoc.org>

       17.    (which could be extended further with current back-end). As regards scaling of the database, it is
              as scalable as the database (here Postgresql) and hardware allow.

       18.    of this feature when demonstrated to an IBM software innovations evaluator  in  2004  he  said  to
              paraphrase:  this  could  be of interest to us. We have large document management systems, you can
              search hundreds of thousands of documents and we can tell you which  documents  meet  your  search
              criteria, but there is no way we can tell you without opening each document where within each your
              matches are found.

       SEEALSOsisu(1),
                     sisu-epub(1),
                     sisu-harvest(1),
                     sisu-html(1),
                     sisu-odf(1),
                     sisu-pdf(1),
                     sisu-pg(1),
                     sisu-sqlite(1),
                     sisu-txt(1).
                     sisu_vim(7)

       HOMEPAGE
                     More    information   about   SiSU   can   be   found   at   <http://www.sisudoc.org/>   or
              <http://www.jus.uio.no/sisu/>

       SOURCE
                     <http://git.sisudoc.org/>

       AUTHOR
                     SiSU is written by Ralph Amissah <ralph@amissah.com>

7.1.5                                              2014-02-05                                            sisu(1)

       sisu_webrick, may be started on it's own with the command: sisu_webrick [port] or using the sisu  command
       with the -W flag: sisu -W [port]

       where no port is given and settings are unchanged the default port is 8081

       sisu_webrick [port]

       or

       sisu -W [port]

       Tables may be prepared in two either of two forms

       markupexample:
       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

       resultingoutput:  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

       markupexample: [^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.

       resultingoutput:Table3.1:ContributorstoWikipedia,January2001-June2005  |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.

       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.