Provided by: sisu_3.1.9-1_all bug

NAME

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

SYNOPSIS

       sisu                   [-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0-9]
       [filename/wildcard]

       sisu [-Ddcv] [instruction] [filename/wildcard]

       sisu [-CcFLSVvW]

       sisu [operations]

       sisu --v3 [operations]

       sisu --v2 [operations]

       sisu2 [operations]

SISU - MANUAL,

       RALPH AMISSAH

WHAT IS SISU?

1. INTRODUCTION - WHAT IS SISU?

       SiSU  is  a framework for document structuring, publishing (in multiple
       open standard formats) and search, comprising  of:  (a)  a  lightweight
       document   structure   and  presentation  markup  syntax;  and  (b)  an
       accompanying engine for generating  standard  document  format  outputs
       from documents prepared in sisu markup syntax, which is able to produce
       multiple standard outputs (including the population of  sql  databases)
       that  (can)  share  a  common numbering system for the citation of text
       within a document.

       SiSU is developed under an open source, software libre license  (GPL3).
       Its use case for development is work with medium to large document sets
       and cope with evolving document formats/  representation  technologies.
       Documents  are  prepared  once,  and generated as need be to update the
       technical presentation or add additional output formats. Various output
       formats  (including search related output) share a common mechanism for
       cross-output-format citation.

       SiSU both defines a markup syntax and provides an engine that  produces
       open standards format outputs from documents prepared with SiSU markup.
       From a single lightly prepared  document  sisu  custom  builds  several
       standard  output  formats  which share a common (text object) numbering
       system for citation  of  content  within  a  document  (that  also  has
       implications for search).  The sisu engine works with an abstraction of
       the document's structure and content  from  which  it  is  possible  to
       generate   different   forms   of   representation   of  the  document.
       Significantly SiSU markup is more sparse than html  and  outputs  which
       include  html,  EPUB, LaTeX, landscape and portrait pdfs, Open Document
       Format (ODF), all of which can be added to and updated.  SiSU  is  also
       able  to  populate  SQL  type databases at an object level, which means
       that searches can be made with that degree of granularity.

       Source document  preparation  and  output  generation  is  a  two  step
       process:  (i)  document  source is prepared, that is, marked up in sisu
       markup syntax and (ii) the desired  output  subsequently  generated  by
       running the sisu engine against document source. Output representations
       if updated (in the sisu engine) can  be  generated  by  re-running  the
       engine  against  the  prepared  source.  Using SiSU markup applied to a
       document, SiSU custom builds (to take advantage  of  the  strengths  of
       different  ways of representing documents) various standard open output
       formats including plain text, HTML,  XHTML,  XML,  EPUB,  OpenDocument,
       LaTeX  or  PDF  files,  and  populate  an SQL database with objects[^1]
       (equating generally to  paragraph-sized  chunks)  so  searches  may  be
       performed  and  matches returned with that degree of granularity ( e.g.
       your search criteria is met by these documents and at  these  locations
       within  each  document).  Document output formats share a common object
       numbering system for locating content. This  is  particularly  suitable
       for  "published"  works  (finalized  texts as opposed to works that are
       frequently changed or updated) for which it provides a fixed  means  of
       reference of content.

       In   preparing   a   SiSU  document  you  optionally  provide  semantic
       information related to the  document  in  a  document  header,  and  in
       marking up the substantive text provide information on the structure of
       the document, primarily indicating heading levels  and  footnotes.  You
       also provide information on basic text attributes where used.  The rest
       is  automatic,  sisu  from  this  information  custom  builds[^2]   the
       different forms of output requested.

       SiSU  works  with an abstraction of the document based on its structure
       which is comprised of its headings[^3] and objects[^4],  which  enables
       SiSU  to  represent  the  document  in many different ways, and to take
       advantage of the strengths of different ways of  presenting  documents.
       The  objects  are  numbered, and these numbers can be used to provide a
       common basis for citing material within a document across the different
       output  format  types. This is significant as page numbers are not well
       suited to the digital age, in  web  publishing,  changing  a  browser's
       default  font  or  using  a  different  browser can mean that text will
       appear on a different page; and publishing in different formats,  html,
       landscape  and  portrait  pdf etc. again page numbers are not useful to
       cite text. Dealing with documents at  an  object  level  together  with
       object  numbering also has implications for search that SiSU is able to
       take advantage of.

       One of the challenges of maintaining documents is to  keep  them  in  a
       format  that allows use of them independently of proprietary platforms.
       Consider issues related to  dealing  with  legacy  proprietary  formats
       today  and  what  guarantee  you have that old proprietary formats will
       remain (or can be read without proprietary  software/equipment)  in  15
       years  time,  or  the  way  the  way in which html has evolved over its
       relatively short span of existence.  SiSU provides the  flexibility  of
       producing  documents in multiple non-proprietary open formats including
       html, pdf[^5] ODF,[^6] and EPUB.[^7] Whilst SiSU  relies  on  software,
       the  markup  is  uncomplicated  and  minimalistic which guarantees that
       future engines can be written to run against  it.  It  is  also  easily
       converted  to other formats, which means documents prepared in SiSU can
       be migrated to other document formats. Further security is provided  by
       the  fact  that  the  software  itself,  SiSU is available under GPL3 a
       licence that guarantees that the source code will always be  open,  and
       free  as in libre, which means that that code base can be used, updated
       and further developed as required  under  the  terms  of  its  license.
       Another challenge is to keep up with a moving target.  SiSU permits new
       forms of output to be added as they become  important,  (Open  Document
       Format text was added in 2006 when it became an ISO standard for office
       applications and the archival of documents),  EPUB  was  introduced  in
       2009;  and  allows  the technical representations existing output to be
       updated (html has evolved and  the  related  module  has  been  updated
       repeatedly   over  the  years,  presumably  when  the  World  Wide  Web
       Consortium (w3c) finalises html 5 which is currently under development,
       the  html  module will again be updated allowing all existing documents
       to be regenerated as html 5).

       The document formats are written to the file-system and  available  for
       indexing by independent indexing tools, whether off the web like Google
       and Yahoo or on the site like Lucene and Hyperestraier.

       SiSU also  provides  other  features  such  as  concordance  files  and
       document  content  certificates, and the working against an abstraction
       of document structure has further possibilities for  the  research  and
       development  of  other  document  representations,  the availability of
       objects is useful for example for topic  maps  and  thesauri,  together
       with the flexibility of SiSU offers great possibilities.

       SiSU  is primarily for published works, which can take advantage of the
       citation system to reliably reference its documents.  SiSU  works  well
       in  a  complementary  manner  with  such  collaborative technologies as
       Wikis, which can take advantage of and be used to discuss the substance
       of content prepared in SiSU.

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

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

2. COMMANDS SUMMARY

2.1 DESCRIPTION

       SiSU  is  a  document  publishing  system,  that  from  a simple single
       marked-up  document,  produces  multiple  output   formats   including:
       plaintext,  html,  xhtml,  XML, epub, odt (odf text), LaTeX, pdf, info,
       and SQL (PostgreSQL  and  SQLite),  which  share  text  object  numbers
       ("object   citation   numbering")   and  the  same  document  structure
       information. For more see: <http://www.jus.uio.no/sisu>

2.2 DOCUMENT PROCESSING COMMAND FLAGS

       -a [filename/wildcard]
              produces plaintext  with  Unix  linefeeds  and  without  markup,
              (object  numbers  are  omitted),  has  footnotes  at end of each
              paragraph  that  contains  them  [   -A  for   equivalent    dos
               (linefeed)   output   file]  [see   -e  for endnotes]. (Options
              include: --endnotes for endnotes --footnotes  for  footnotes  at
              the  end  of  each  paragraph --unix for unix linefeed (default)
              --msdos for msdos linefeed)

       -b [filename/wildcard]
              see --xhtml

       --color-toggle [filename/wildcard]
              screen toggle ansi screen colour on or off depending on  default
              set  (unless -c flag is used: if sisurc colour default is set to
              'true', output to screen will be with colour, if  sisurc  colour
              default  is set to 'false' or is undefined screen output will be
              without colour). Alias -c

       --configure
              configure/initialise shared output  directory  files  initialize
              shared  output directory (config files such as css and dtd files
              are not updated if they already exist unless modifier is  used).
              The  equivalent  of:  -C  --init-site configure/initialise site,
              more extensive than -C  on  its  own,  shared  output  directory
              files/force  update, existing shared output config files such as
              css and dtd files are updated if -CC is used.

       --concordance [filename/wildcard]
              produces concordance (wordmap) a rudimentary index  of  all  the
              words  in  a  document. (Concordance files are not generated for
              documents of over 260,000 words unless this limit  is  increased
              in the file sisurc.yml). Alias -w

       -C     configure/initialise  shared  output  directory files initialize
              shared output directory (config files such as css and dtd  files
              are  not updated if they already exist unless modifier is used).
              -C --init-site configure/initialise site more extensive than  -C
              on its own, shared output directory files/force update, existing
              shared output config files such as css and dtd files are updated
              if this modifier is used.

       -CC    see --configure

       -c [filename/wildcard]
              see --color-toggle

       --dal [filename/wildcard/url]
              assumed for most other flags, creates new intermediate files for
              processing (document abstraction) that is used in all subsequent
              processing  of  other  output.  This  step  is  assumed for most
              processing flags. To skip it see -n.  Alias -m

       --delete [filename/wildcard]
              see --zap

       -D [instruction] [filename]
              see --pg

       -d [--db-[database  type  (sqlite|pg)]] --[instruction] [filename]
              see --sqlite

       --epub [filename/wildcard]
              produces   an   epub   document,   [sisu    version    >=2     ]
              (filename.epub). Alias -e

       -e [filename/wildcard]
              see --epub

       --find [optional  string  part  of  filename]
              without  match  string,  glob  all  .sst .ssm files in directory
              (including language subdirectories).  With  match  string,  find
              files  that  match given string in directory (including language
              subdirectories). Alias -f, --glob, -G

       -F [--webserv=webrick]
              see --sample-search-form

       -f [optional  string  part  of  filename]
              see --find

       --git [filename/wildcard]
              produces or updates markup source file structure in a  git  repo
              (experimental and subject to change). Alias -g

       --glob [optional  string  part  of  filename]
              see --find

       -G [optional  string  part  of  filename]
              see --find

       -g [filename/wildcard]
              see --git

       --harvest *.ss[tm]
              makes  two  lists  of  sisu  output  based  on  the  sisu markup
              documents in a directory: list of author and authors works (year
              and  titles),  and;  list by topic with titles and author. Makes
              use  of   header   metadata   fields   (author,   title,   date,
              topic_register).  Can  be  used with maintenance (-M) and remote
              placement (-R) flags.

       --help [topic]
              provides help on the selected  topic,  where  topics  (keywords)
              include:    list,    (com)mands,    short(cuts),    (mod)ifiers,
              (env)ironment,  markup,  syntax,  headers,  headings,  endnotes,
              tables,   example,   customise,   skin,   (dir)ectories,   path,
              (lang)uage, db, install, setup, (conf)igure, convert, termsheet,
              search, sql, features, license

       --html [filename/wildcard]
              produces  html  output,  segmented  text  with table of contents
              (toc.html and index.html) and the  document  in  a  single  file
              (scroll.html). Alias -h

       -h [filename/wildcard]
              see --html

       -I [filename/wildcard]
              see --texinfo

       -i [filename/wildcard]
              see --manpage

       --keep-processing-files [filename/wildcard/url]
              see --maintenance

       -L     prints license information.

       --machine [filename/wildcard/url]
              see --dal (document abstraction level/layer)

       --maintenance [filename/wildcard/url]
              maintenance  mode,  interim  processing  files are preserved and
              their  locations  indicated.  (also  see  -V).  Aliases  -M  and
              --keep-processing-files

       --manpage [filename/wildcard]
              produces  man  page of file, not suitable for all outputs. Alias
              -i

       -M [filename/wildcard/url]
              see --maintenance

       -m [filename/wildcard/url]
              see --dal (document abstraction level/layer)

       --no-ocn
              [with  --html  --pdf  or  --epub] switches off  object  citation
              numbering. Produce output without identifying numbers in margins
              of html or LaTeX/pdf output.

       -N [filename/wildcard/url]
              document digest or document content certificate ( DCC )  as  md5
              digest  tree  of  the document: the digest for the document, and
              digests for each object contained within the document  (together
              with   information   on  software  versions  that  produced  it)
              (digest.txt). -NV for verbose digest output to screen.

       -n [filename/wildcard/url]
              skip the creation of  intermediate  processing  files  (document
              abstraction) if they already exist, this skips the equivalent of
              -m which is otherwise assumed by most processing flags.

       --odf [filename/wildcard/url]
              see --odt

       --odt [filename/wildcard/url]
              output   basic   document   in    opendocument    file    format
              (opendocument.odt). Alias -o

       -o [filename/wildcard/url]
              see --odt

       --pdf [filename/wildcard]
              produces LaTeX pdf (portrait.pdf & landscape.pdf). Default paper
              size is set in config file, or document header, or provided with
              additional  command  line  parameter, e.g. --papersize-a4 preset
              sizes include: 'A4', U.S. 'letter' and

       --pg [instruction] [filename]
              database postgresql ( --pgsql  may  be  used  instead)  possible
              instructions, include: --createdb; --create; --dropall; --import
              [filename];  --update  [filename];  --remove   [filename];   see
              database section below. Alias -D

       --po [language_directory/filename  language_directory]
              see --po4a

       --po4a [language_directory/filename  language_directory]
              produces  .pot  and  po  files  for  the  file  in the languages
              specified by the language directory.  SiSU markup is  placed  in
              subdirectories  named  with the language code, e.g. en/ fr/ es/.
              The sisu config file must set the output directory structure  to
              multilingual. v3, experimental

       -P [language_directory/filename  language_directory]
              see --po4a

       -p [filename/wildcard]
              see --pdf

       --qrcode [filename/wildcard]
              generate QR code image of metadata (used in manifest). v3 only.

       --quiet [filename/wildcard]
              quiet less output to screen.

       -Q [filename/wildcard]
              see --qrcode

       -q [filename/wildcard]
              see --quiet

       --rsync [filename/wildcard]
              copies  sisu  output  files  to  remote  host  using rsync. This
              requires that sisurc.yml has been provided with  information  on
              hostname  and  username,  and  that you have your "keys" and ssh
              agent in place. Note the behavior of rsync different  if  -R  is
              used  with  other  flags  from  if  used  alone. Alone the rsync
              --delete parameter is  sent,  useful  for  cleaning  the  remote
              directory  (when  -R  is  used  together with other flags, it is
              not). Also see --scp. Alias -R

       -R [filename/wildcard]
              see --rsync

       -r [filename/wildcard]
              see --scp

       --sample-search-form [--webserv=webrick]
              generate examples of (naive) cgi  search  form  for  sqlite  and
              pgsql  depends  on  your already having used sisu to populate an
              sqlite and/or pgsql database,  (the  sqlite  version  scans  the
              output  directories for existing sisu_sqlite databases, so it is
              first necessary to create them,  before  generating  the  search
              form)  see -d -D and the database section below. If the optional
              parameter --webserv=webrick is passed, the cgi examples  created
              will  be  set  up  to  use  the  default port set for use by the
              webrick server, (otherwise the port is left blank and the system
              setting used, usually 80). The samples are dumped in the present
              work directory which must be writable, (with screen instructions
              given that they be copied to the cgi-bin directory). Alias -F

       --scp [filename/wildcard]
              copies sisu output files to remote host using scp. This requires
              that sisurc.yml has been provided with information  on  hostname
              and  username,  and  that  you have your "keys" and ssh agent in
              place. Also see --rsync. Alias -r

       --sqlite --[instruction] [filename]
              database type default set to sqlite, (for which --sqlite may  be
              used  instead)  or  to  specify  another  database  --db-[pgsql,
               sqlite]  (however  see  -D)  possible   instructions   include:
              --createdb;  --create;  --dropall; --import [filename]; --update
              [filename]; --remove [filename];  see  database  section  below.
              Alias -d

       --sisupod
              produces  a  sisupod  a  zipped  sisu  directory of markup files
              including sisu markup source files  and  the  directories  local
              configuration  file,  images and skins. Note: this only includes
              the configuration files or skins contained in
               ./_sisu not those in  ~/.sisu  -S  [filename/wildcard]  option.
              Note: (this option is tested only with zsh). Alias -S

       --sisupod [filename/wildcard]
              produces  a zipped file of the prepared document specified along
              with associated images, by default named  sisupod.zip  they  may
              alternatively  be  named  with  the filename extension .ssp This
              provides a quick way of gathering the relevant parts of  a  sisu
              document  which  can  then  for  example  be  emailed. A sisupod
              includes  sisu  markup  source  file,  (along  with   associated
              documents  if  a  master  file,  or  available  in  multilingual
              versions), together with related images and skin.  SiSU commands
              can  be  run  directly  against  a  sisupod contained in a local
              directory, or provided as a url on a remote site. As there is  a
              security  issue with skins provided by other users, they are not
              applied unless the flag --trust or --trusted  is  added  to  the
              command  instruction,  it  is recommended that file that are not
              your own are treated as untrusted. The  directory  structure  of
              the  unzipped  file is understood by sisu, and sisu commands can
              be run within it.  Note: if you wish to send multiple files,  it
              quickly  becomes  more  space  efficient  to zip the sisu markup
              directory, rather than the individual files  for  sending).  See
              the -S option without [filename/wildcard]. Alias -S

       --source [filename/wildcard]
              copies sisu markup file to output directory. Alias -s

       -S     see --sisupod

       -S [filename/wildcard]
              see --sisupod

       -s [filename/wildcard]
              see --source

       --texinfo [filename/wildcard]
              produces texinfo and info file, (view with pinfo). Alias -I

       --txt [filename/wildcard]
              produces  plaintext  with  Unix  linefeeds  and  without markup,
              (object numbers are omitted),  has  footnotes  at  end  of  each
              paragraph   that  contains  them  [   -A  for   equivalent   dos
               (linefeed)  output  file] [see   -e   for  endnotes].  (Options
              include:  --endnotes  for  endnotes --footnotes for footnotes at
              the end of each paragraph --unix  for  unix  linefeed  (default)
              --msdos for msdos linefeed). Alias -t

       -T [filename/wildcard  (*.termsheet.rb)]
              standard form document builder, preprocessing feature

       -t [filename/wildcard]
              see --txt

       --urls [filename/wildcard]
              prints  url  output  list/map for the available processing flags
              options and resulting files that could  be  requested,  (can  be
              used  to get a list of processing options in relation to a file,
              together with information on the output that would be produced),
              -u  provides  url  output  mapping for those flags requested for
              processing. The default  assumes  sisu_webrick  is  running  and
              provides  webrick  url mappings where appropriate, but these can
              be switched to file system paths in sisurc.yml. Alias -U

       -U [filename/wildcard]
              see --urls

       -u [filename/wildcard]
              provides url mapping of output files for the flags requested for
              processing, also see -U

       --v2 [filename/wildcard]
              invokes  the  sisu  v2  document  parser/generator.  This is the
              default and is normally omitted.

       --v3 [filename/wildcard]
              invokes the sisu v3 document parser/generator.  Currently  under
              development  and  incomplete,  v3 requires >= ruby1.9.2p180. You
              may run sisu3 instead.

       --verbose [filename/wildcard]
              provides verbose output of what is being generated, where output
              is  placed (and error messages if any), as with -u flag provides
              a url mapping of files created for each of the  processing  flag
              requests. Alias -v

       -V     on  its  own,  provides SiSU version and environment information
              (sisu --help env)

       -V [filename/wildcard]
              even more verbose than the -v flag.

       -v     on its own, provides SiSU version information

       -v [filename/wildcard]
              see --verbose

       --webrick
              starts  ruby's  webrick  webserver   points   at   sisu   output
              directories,  the default port is set to 8081 and can be changed
              in  the  resource  configuration  files.   [tip:   the   webrick
               server   requires  link  suffixes,  so  html output  should  be
               created  using  the  -h  option   rather   than  -H   ;   also,
               note  -F  webrick  ]. Alias -W

       -W     see --webrick

       --wordmap [filename/wildcard]
              see --concordance

       -w [filename/wildcard]
              see --concordance

       --xhtml [filename/wildcard]
              produces  xhtml/XML  output  for  browser viewing (sax parsing).
              Alias -b

       --xml-dom [filename/wildcard]
              produces XML output with deep document structure, in the  nature
              of dom. Alias -X

       --xml-sax [filename/wildcard]
              produces XML output shallow structure (sax parsing). Alias -x

       -X [filename/wildcard]
              see --xml-dom

       -x [filename/wildcard]
              see --xml-sax

       -Y [filename/wildcard]
              produces  a  short sitemap entry for the document, based on html
              output and the sisu_manifest. --sitemaps  generates/updates  the
              sitemap   index  of  existing  sitemaps.  (Experimental,  [g,y,m
               announcement  this  week])

       -y [filename/wildcard]
              produces an html summary of  output  generated  (hyperlinked  to
              content)  and  document  specific metadata (sisu_manifest.html).
              This step is assumed for most processing flags.

       --zap [filename/wildcard]
              Zap, if used with other processing flags deletes output files of
              the  type  about  to be processed, prior to processing. If -Z is
              used as the lone processing related flag (or in conjunction with
              a  combination  of  -[mMvVq]),  will remove the related document
              output directory. Alias -Z

       -Z [filename/wildcard]
              see --zap

3. COMMAND LINE MODIFIERS

       --no-ocn
              [with  --html  --pdf  or  --epub] switches off  object  citation
              numbering. Produce output without identifying numbers in margins
              of html or LaTeX/pdf output.

       --no-annotate
              strips output text of editor endnotes[^*1] denoted  by  asterisk
              or dagger/plus sign

       --no-asterisk
              strips  output  text of editor endnotes[^*2] denoted by asterisk
              sign

       --no-dagger
              strips  output  text  of   editor   endnotes[^+1]   denoted   by
              dagger/plus sign

4. DATABASE COMMANDS

       dbi - database interface

       -D  or --pgsql set for postgresql -d or --sqlite default set for sqlite
       -d is modifiable with --db=[database  type  (pgsql  or  sqlite)]

       --pg -v --createall
              initial step, creates required relations  (tables,  indexes)  in
              existing  postgresql  database  (a  database  should  be created
              manually and given  the  same  name  as  working  directory,  as
              requested)  (rb.dbi)  [  -dv  --createall sqlite  equivalent] it
              may be necessary to run sisu -Dv --createdb initially  NOTE:  at
              the  present time for postgresql it may be necessary to manually
              create the database. The command would  be  'createdb  [database
               name]'  where  database  name  would  be SiSU_[present  working
               directory  name (without  path)]. Please use only alphanumerics
              and underscores.

       --pg -v --import
              [filename/wildcard]  imports  data  specified  to  postgresql db
              (rb.dbi) [  -dv --import  sqlite  equivalent]

       --pg -v --update
              [filename/wildcard] updates/imports specified data to postgresql
              db (rb.dbi) [  -dv  --update  sqlite  equivalent]

       --pg --remove
              [filename/wildcard]  removes  specified  data  to  postgresql db
              (rb.dbi) [  -d --remove  sqlite  equivalent]

       --pg --dropall
              kills data" and  drops  (postgresql  or  sqlite)  db,  tables  &
              indexes [  -d --dropall  sqlite  equivalent]

              The -v is for verbose output.

5. SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS

       --update [filename/wildcard]
              Checks  existing  file  output  and  runs  the flags required to
              update this output.  This means that if only html and pdf output
              was  requested  on  previous  runs,  only  the -hp files will be
              applied, and only these will be generated  this  time,  together
              with  the  summary.  This  can  be very convenient, if you offer
              different outputs of different files, and just want  to  do  the
              same again.

       -0 to -5 [filename  or  wildcard]
              Default  shorthand  mappings (for v3, note that the defaults can
              be changed/configured in the sisurc.yml file):

       -0     -NQhewpotbxXyYv [this  is  the  default  action  run   when   no
              options  are  give,  i.e.  on  'sisu  [filename]']

       -1     -Qhewpoty

       -2     -NQhewpotbxXy

       -3     -NQhewpotbxXyY

       -4     -NQhewpotbxXDyY --update

       -5     -NQhewpotbxXDyYv --update

              add  -v for verbose mode and -c to toggle color state, e.g. sisu
              -2vc [filename  or  wildcard]

              consider -u for appended url info or -v for verbose output

5.1 COMMAND LINE WITH FLAGS - BATCH PROCESSING

       In the data directory run sisu -mh filename or wildcard  eg.  "sisu  -h
       cisg.sst"  or  "sisu  -h  *.{sst,ssm}"  to  produce html version of all
       documents.

       Running sisu (alone without any flags, filenames or  wildcards)  brings
       up  the  interactive  help,  as  does  any  sisu  command  that  is not
       recognised. Enter to escape.

6. HELP

6.1 SISU MANUAL

       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

6.2 SISU MAN PAGES

       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/> [^8]

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

6.3 SISU BUILT-IN INTERACTIVE HELP

       This   is   particularly   useful   for   getting   the   current  sisu
       setup/environment information:

         sisu --help

         sisu --help [subject]

           sisu --help commands

           sisu --help markup

           sisu --help env [for  feedback  on   the   way   your   system   is
       setup  with  regard  to  sisu]

         sisu -V [environment  information,  same  as  above  command]

         sisu (on its own provides version and some help information)

       Apart from real-time information on your current configuration the SiSU
       manual and man pages are likely to contain more up-to-date  information
       than the sisu interactive help (for example on commands and markup).

       NOTE:  Running  the command sisu (alone without any flags, filenames or
       wildcards) brings up the interactive help, as  does  any  sisu  command
       that is not recognised. Enter to escape.

7. INTRODUCTION TO SISU MARKUP[^10]

7.1 SUMMARY

       SiSU source documents are plaintext (UTF-8)[^11] 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.

       Some interactive help on  markup  is  available,  by  typing  sisu  and
       selecting markup or sisu --help markup

       To check the markup in a file:

         sisu --identify [filename].sst

       For brief descriptive summary of markup history

         sisu --query-history

       or if for a particular version:

         sisu --query-0.38

7.2 MARKUP EXAMPLES

7.2.1 ONLINE

       Online  markup  examples  are  available  together  with the respective
       outputs produced  from  <http://www.jus.uio.no/sisu/SiSU/examples.html>
       or from <http://www.jus.uio.no/sisu/sisu_examples/>

       There  is of course this document, which provides a cursory overview of
       sisu     markup     and     the     respective     output     produced:
       <http://www.jus.uio.no/sisu/sisu_markup/>

       an       alternative      presentation      of      markup      syntax:
       /usr/share/doc/sisu/on_markup.txt.gz

7.2.2 INSTALLED

       With   SiSU   installed    sample    skins    may    be    found    in:
       /usr/share/doc/sisu/markup-samples  (or  equivalent  directory)  and if
       sisu-markup-samples       is        installed        also        under:
       /usr/share/doc/sisu/markup-samples-non-free

8. MARKUP OF HEADERS

       Headers  contain either: semantic meta-data about a document, which can
       be  used  by  any  output  module  of  the  program,   or;   processing
       instructions.

       Note:  the  first  line  of  a  document may include information on the
       markup version used in the form of a comment. Comments are a percentage
       mark  at the start of a paragraph (and as the first character in a line
       of text) followed by a space and the comment:

         % this would be a comment

8.1 SAMPLE HEADER

       This current document is loaded by a master document that has a  header
       similar to this one:

         % SiSU master 2.0
         @title: SiSU
          :subtitle: Manual
         @creator:
          :author: Amissah, Ralph
         @publisher:  [publisher  name]
         @rights: Copyright (C) Ralph Amissah 2007, License GPL 3
         @classify:
          :type: information
          :topic_register: SiSU:manual;electronic documents:SiSU:manual
          :subject: ebook, epublishing, electronic book, electronic publishing,
             electronic document, electronic citation, data structure,
              citation systems, search
         % used_by: manual
         @date:
          :published: 2008-05-22
          :created: 2002-08-28
          :issued: 2002-08-28
          :available: 2002-08-28
          :modified: 2010-03-03
         @make:
          :num_top: 1
          :breaks: new=C; break=1
          :skin: skin_sisu_manual
          :bold: /Gnu|Debian|Ruby|SiSU/
          :manpage: name=sisu - documents: markup, structuring, publishing
              in multiple standard formats, and search;
              synopsis=sisu  [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9]  [filename/wildcard  ]
              . sisu  [-Ddcv]  [instruction]
              . sisu  [-CcFLSVvW]
              . sisu --v2  [operations]
              . sisu --v3  [operations]
         @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/?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

8.2 AVAILABLE HEADERS

       Header  tags  appear  at  the  beginning of a document and provide meta
       information on the document (such as the Dublin Core),  or  information
       as  to  how  the  document  as  a  whole is to be processed. All header
       instructions take the  form  @headername:  or  on  the  next  line  and
       indented  by  once  space :subheadername: All Dublin Core meta tags are
       available

       @indentifier: information or instructions

       where the "identifier" is a tag recognised  by  the  program,  and  the
       "information" or "instructions" belong to the tag/indentifier 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:
          :isbn:  [ISBN]
          :loc:  [Library  of  Congress  classification]
          :dewey:  [Dewey  classification]
          :pg:  [Project  Gutenberg  text  number]

         @links: { SiSU }http://www.sisudoc.org
           { FSF }http://www.fsf.org

         @make:
          :skin: skin_name
            [skins change default settings related to the appearance of documents generated]
          :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]

         @original:
          :language:  [language]

         @notes:
          :comment:
          :prefix:  [prefix  is  placed  just  after  table  of  contents]

9. MARKUP OF SUBSTANTIVE TEXT

9.1 HEADING LEVELS

       Heading  levels  are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part /
       section headings, followed by other heading  levels,  and  1  -6  being
       headings  followed by substantive text or sub-headings. :A~ usually the
       title :A~? conditional  level  1  heading  (used  where  a  stand-alone
       document may be imported into another)

       :A~  [heading   text]  Top  level  heading [this  usually  has  similar
        content  to  the  title  @title:  ] NOTE: the heading levels described
       here are in 0.38 notation, see heading

       :B~  [heading   text] Second level heading [this  is  a  heading  level
        divider]

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

       1~  [heading   text]  Top  level  heading preceding substantive text of
       document or sub-heading 2, the heading level  that  would  normally  be
       marked  1.  or 2. or 3. etc. in a document, and the level on which sisu
       by default would break html  output  into  named  segments,  names  are
       provided  automatically  if  none are given (a number), otherwise takes
       the form 1~my_filename_for_this_segment

       2~ [heading  text] Second level heading preceding substantive  text  of
       document  or  sub-heading  3,  the heading level that would normally be
       marked 1.1 or 1.2 or 1.3 or 2.1 etc.  in a document.

       3~ [heading  text] Third level heading preceding  substantive  text  of
       document,  that  would  normally  be  marked 1.1.1 or 1.1.2 or 1.2.1 or
       2.1.1 etc. in a document

         1~filename level 1 heading,
         % the primary division such as Chapter that is followed by substantive text,
         % and may be further subdivided (this is the level on which by default html
         % segments are made)

9.2 FONT ATTRIBUTES

       markup example:

         normal text,  *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
         ^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
         normal text
         *{emphasis}*  [note:  can  be  configured  to  be  represented  by  bold,  italics  or  underscore]
         !{bold text}!
         _{underscore}_
         /{italics}/
         "{citation}"
         ^{superscript}^
         ,{subscript},
         +{inserted text}+
         -{strikethrough}-
         #{monospace}#

       resulting output:

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

       normal text

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

       bold text

       italics

       underscore

       "citation"

       ^superscript^

       [subscript]

       ++inserted text++


       --strikethrough--
       monospace

9.3 INDENTATION AND BULLETS

       markup example:

         ordinary paragraph
         _1 indent paragraph one step
         _2 indent paragraph two steps
         _9 indent paragraph nine steps

       resulting output:

       ordinary paragraph

         indent paragraph one step

           indent paragraph two steps

                         indent paragraph nine steps

       markup example:

         _* bullet text
         _1* bullet text, first indent
         _2* bullet text, two step indent

       resulting output:

       * bullet text

         * bullet text, first indent

           * bullet text, two step indent

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

       markup example:

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

9.4 HANGING INDENTS

       markup example:

         _0_1 first line no indent,
         rest of paragraph indented one step
         _1_0 first line indented,
         rest of paragraph no indent
         in each case level may be 0-9

       resulting output:

         first line no indent, rest of paragraph indented one step

       first line indented, rest of paragraph no indent

       in each case level may be 0-9

9.5 FOOTNOTES / ENDNOTES

       Footnotes and endnotes are marked up at the location where  they  would
       be indicated within a text. They are automatically numbered. The output
       type determines whether footnotes or endnotes will be produced

       markup example:

         ~{ a footnote or endnote }~

       resulting output:

       [^12]

       markup example:

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

       resulting output:

       normal text[^13] continues

       markup example:

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

       resulting output:

       normal text [^*] continues

       normal text [^**] continues

       markup example:

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

       resulting output:

       normal text [^*3] continues

       normal text [^+2] continues

       Alternative endnote pair notation for footnotes/endnotes:

         % note the endnote marker "~^"
         normal text~^ continues
         ^~ endnote text following the paragraph in which the marker occurs

       the standard and pair notation cannot be mixed in the same document

9.6 LINKS

9.6.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS

       urls found within text are marked up automatically. A url  within  text
       is  automatically  hyperlinked  to itself and by default decorated with
       angled braces, unless they are contained within a code block (in  which
       case  they  are  passed  as  normal  text),  or  escaped by a preceding
       underscore (in which case the decoration is omitted).

       markup example:

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

       resulting output:

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

       An escaped url without decoration

       markup example:

         normal text _http://www.sisudoc.org/ continues
         deb _http://www.jus.uio.no/sisu/archive unstable main non-free

       resulting output:

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

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

       where  a  code  block  is  used  there  is   neither   decoration   nor
       hyperlinking, code blocks are discussed later in this document

       resulting output:

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

9.6.2 LINKING TEXT

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

       markup example:

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

       resulting output:

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

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

       markup example:

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

       resulting output:

       about SiSU <http://www.sisudoc.org/> [^14] markup

       markup example:

         { 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/
       markup example:

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

       resulting output:

       [ tux.png ]

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

       [  ruby_logo  (png  missing)  ] [^15]

       GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better -  with  Gnu/Linux,
       Debian and Ruby" <http://www.jus.uio.no/sisu/>

       linked url footnote shortcut

         {~^  [text  to  link] }http://url.org
         % maps to: {  [text  to  link] }http://url.org ~{ http://url.org }~
         % which produces hyper-linked text within a document/paragraph,
         % with an endnote providing the url for the text location used in the hyperlink

         text marker *~name

       note at a heading level the same is automatically achieved by providing
       names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the  case
       of auto-heading numbering, without further intervention.

9.7 GROUPED TEXT

9.7.1 TABLES

       Tables may be prepared in two either of two forms

       markup example:

         table{ c3; 40; 30; 30;
         This is a table
         this would become column two of row one
         column three of row one is here
         And here begins another row
         column two of row two
         column three of row two, and so on
         }table

       resulting output:

         [table  omitted,  see  other  document  formats]

       a  second  form  may be easier to work with in cases where there is not
       much information in each column

       markup example: [^16]

         !_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
         {table~h 24; 12; 12; 12; 12; 12; 12;}
                                         |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
         Contributors*                   |       10|      472|    2,188|    9,653|   25,011|   48,721
         Active contributors**           |        9|      212|      846|    3,228|    8,442|   16,945
         Very active contributors***     |        0|       31|      190|      692|    1,639|    3,016
         No. of English language articles|       25|   16,000|  101,000|  190,000|  320,000|  630,000
         No. of articles, all languages  |       25|   19,000|  138,000|  490,000|  862,000|1,600,000
         * Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.

       resulting output:

       Table 3.1: Contributors to Wikipedia, January 2001 - June 2005

         [table  omitted,  see  other  document  formats]

       * Contributed at least ten times; ** at least 5 times  in  last  month;
       *** more than 100 times in last month.

9.7.2 POEM

       basic markup:

         poem{
           Your poem here
         }poem
         Each verse in a poem is given an object number.

       markup example:

         poem{
                             `Fury said to a
                            mouse, That he
                          met in the
                        house,
                     "Let us
                       both go to
                         law:  I will
                           prosecute
                             YOU.  --Come,
                                I'll take no
                                 denial; We
                              must have a
                          trial:  For
                       really this
                    morning I've
                   nothing
                  to do."
                    Said the
                      mouse to the
                        cur, "Such
                          a trial,
                            dear Sir,
                                  With
                              no jury
                           or judge,
                         would be
                       wasting
                      our
                       breath."
                        "I'll be
                          judge, I'll
                            be jury,"
                                  Said
                             cunning
                               old Fury:
                              "I'll
                               try the
                                  whole
                                   cause,
                                      and
                                 condemn
                                you
                               to
                                death."'
         }poem

       resulting output:

                           `Fury said to a
                          mouse, That he
                        met in the
                      house,
                   "Let us
                     both go to
                       law:  I will
                         prosecute
                           YOU.  --Come,
                              I'll take no
                               denial; We
                            must have a
                        trial:  For
                     really this
                  morning I've
                 nothing
                to do."
                  Said the
                    mouse to the
                      cur, "Such
                        a trial,
                          dear Sir,
                                With
                            no jury
                         or judge,
                       would be
                     wasting
                    our
                     breath."
                      "I'll be
                        judge, I'll
                          be jury,"
                                Said
                           cunning
                             old Fury:
                            "I'll
                             try the
                                whole
                                 cause,
                                    and
                               condemn
                              you
                             to
                              death."'

9.7.3 GROUP

       basic markup:

         group{
           Your grouped text here
         }group
         A group is treated as an object and given a single object number.

       markup example:

         group{
                             'Fury said to a
                            mouse, That he
                          met in the
                        house,
                     "Let us
                       both go to
                         law:  I will
                           prosecute
                             YOU.  --Come,
                                I'll take no
                                 denial; We
                              must have a
                          trial:  For
                       really this
                    morning I've
                   nothing
                  to do."
                    Said the
                      mouse to the
                        cur, "Such
                          a trial,
                            dear Sir,
                                  With
                              no jury
                           or judge,
                         would be
                       wasting
                      our
                       breath."
                        "I'll be
                          judge, I'll
                            be jury,"
                                  Said
                             cunning
                               old Fury:
                              "I'll
                               try the
                                  whole
                                   cause,
                                      and
                                 condemn
                                you
                               to
                                death."'
         }group

       resulting output:

                           `Fury said to a
                          mouse, That he
                        met in the
                      house,
                   "Let us
                     both go to
                       law:  I will
                         prosecute
                           YOU.  --Come,
                              I'll take no
                               denial; We
                            must have a
                        trial:  For
                     really this
                  morning I've
                 nothing
                to do."
                  Said the
                    mouse to the
                      cur, "Such
                        a trial,
                          dear Sir,
                                With
                            no jury
                         or judge,
                       would be
                     wasting
                    our
                     breath."
                      "I'll be
                        judge, I'll
                          be jury,"
                                Said
                           cunning
                             old Fury:
                            "I'll
                             try the
                                whole
                                 cause,
                                    and
                               condemn
                              you
                             to
                              death."'

9.7.4 CODE

       Code  tags  code{  ...  }code  (used as with other group tags described
       above) are used to escape regular  sisu  markup,  and  have  been  used
       extensively  within  this  document to provide examples of SiSU markup.
       You cannot however use code tags to escape code tags. They are  however
       used in the same way as group or poem tags.

       A  code-block is treated as an object and given a single object number.
       [an option  to  number  each  line  of  code  may  be   considered   at
       some  later  time]

       use of code tags instead of poem compared, resulting output:

                             `Fury said to a
                            mouse, That he
                          met in the
                        house,
                     "Let us
                       both go to
                         law:  I will
                           prosecute
                             YOU.  --Come,
                                I'll take no
                                 denial; We
                              must have a
                          trial:  For
                       really this
                    morning I've
                   nothing
                  to do."
                    Said the
                      mouse to the
                        cur, "Such
                          a trial,
                            dear Sir,
                                  With
                              no jury
                           or judge,
                         would be
                       wasting
                      our
                       breath."
                        "I'll be
                          judge, I'll
                            be jury,"
                                  Said
                             cunning
                               old Fury:
                              "I'll
                               try the
                                  whole
                                   cause,
                                      and
                                 condemn
                                you
                               to
                                death."'

       From  SiSU  2.7.7  on you can number codeblocks by placing a hash after
       the opening code tag code{# as demonstrated here:

       1  |                      `Fury said to a
       2  |                     mouse, That he
       3  |                   met in the
       4  |                 house,
       5  |              "Let us
       6  |                both go to
       7  |                  law:  I will
       8  |                    prosecute
       9  |                      YOU.  --Come,
       10 |                         I'll take no
       11 |                          denial; We
       12 |                       must have a
       13 |                   trial:  For
       14 |                really this
       15 |             morning I've
       16 |            nothing
       17 |           to do."
       18 |             Said the
       19 |               mouse to the
       20 |                 cur, "Such
       21 |                   a trial,
       22 |                     dear Sir,
       23 |                           With
       24 |                       no jury
       25 |                    or judge,
       26 |                  would be
       27 |                wasting
       28 |               our
       29 |                breath."
       30 |                 "I'll be
       31 |                   judge, I'll
       32 |                     be jury,"
       33 |                           Said
       34 |                      cunning
       35 |                        old Fury:
       36 |                       "I'll
       37 |                        try the
       38 |                           whole
       39 |                            cause,
       40 |                               and
       41 |                          condemn
       42 |                         you
       43 |                        to
       44 |                         death."'

9.8 ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS

9.8.1 LINE-BREAKS

       To break a line within a "paragraph object", two backslashes \\ with  a
       space before and a space or newline after them may be used.

         To break a line within a "paragraph object",
         two backslashes \\ with a space before
         and a space or newline after them \\
         may be used.

       The  html  break br enclosed in angle brackets (though undocumented) is
       available in versions prior to 3.0.13 and 2.9.7 (it  remains  available
       for the time being, but is depreciated).

9.8.2 PAGE BREAKS

       Page  breaks  are  only  relevant and honored in some output formats. A
       page break or a new page may be inserted manually using  the  following
       markup on a line on its own:

         <:pb>

       or

         <:pn>

       page new <:pn> breaks the page, starts a new page.

       page  break  <:pb>  breaks  a  column,  starts  a  new column, if using
       columns, else breaks the page, starts a new page.

9.9 BOOK INDEX

       To make an index append to paragraph the book index term relates to it,
       using an equal sign and curly braces.

       Currently  two  levels  are  provided,  a  main  term  and  if needed a
       sub-term.  Sub-terms are separated from the main term by a colon.

           Paragraph containing main term and sub-term.
           ={Main term:sub-term}

       The index syntax starts on a new line, but there should not be an empty
       line between paragraph and index markup.

       The structure of the resulting index would be:

           Main term, 1
             sub-term, 1

       Several  terms  may  relate  to  a  paragraph,  they are separated by a
       semicolon. If the term refers to more than one paragraph, indicate  the
       number of paragraphs.

           Paragraph containing main term, second term and sub-term.
           ={first term; second term: sub-term}

       The structure of the resulting index would be:

           First term, 1,
           Second term, 1,
             sub-term, 1

       If  multiple  sub-terms  appear under one paragraph, they are separated
       under the main term heading from each other by a pipe symbol.

           Paragraph containing main term, second term and sub-term.
           ={Main term:sub-term+1|second sub-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,

10. COMPOSITE DOCUMENTS MARKUP

       It is possible to build a document by creating a master  document  that
       requires  other  documents.  The  documents  required  may  be complete
       documents that could be  generated  independently,  or  they  could  be
       markup  snippets,  prepared  so  as to be easily available to be placed
       within another text. If the  calling  document  is  a  master  document
       (built  from  other documents), it should be named with the suffix .ssm
       Within this  document  you  would  provide  information  on  the  other
       documents  that  should be included within the text. These may be other
       documents that would be processed in a  regular  way,  or  markup  bits
       prepared  only  for  inclusion  within  a  master document .sst regular
       markup file, or .ssi  (insert/information)  A  secondary  file  of  the
       composite  document  is  built prior to processing with the same prefix
       and the suffix ._sst

       basic markup for importing a document into a master document

         << filename1.sst
         << filename2.ssi

       The form described above should be relied on. Within the Vim editor  it
       results in the text thus linked becoming hyperlinked to the document it
       is calling in which is convenient for editing. Alternative  markup  for
       importation   of   documents   under  consideration,  and  occasionally
       supported have been.

         << filename.ssi
         <<{filename.ssi}
         % using textlink alternatives
         << |filename.ssi|@|^|

11. MARKUP SYNTAX HISTORY

11.1 NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX

       2.0 introduced new headers  and  is  therefore  incompatible  with  1.0
       though otherwise the same with the addition of a couple of tags (i.e. a
       superset)

       0.38 is substantially current for version 1.0

       depreciated 0.16 supported, though file names were changed at 0.37

       * sisu --query=[sisu  version  [0.38] or 'history]

       provides a short history of changes to SiSU markup

       SiSU 2.0 (2010-03-06:09/6) same as 1.0,  apart  from  the  changing  of
       headers  and  the  addition  of  a  monospace  tag  related headers now
       grouped, e.g.

         @title:
          :subtitle:

         @creator:
          :author:
          :translator:
          :illustrator:

         @rights:
          :text:
          :illustrations:

       see document markup samples, and sisu --help headers

       the monospace tag takes the form of a hash '#'

         #{ this enclosed text would be monospaced }#

       1.0 (2009-12-19:50/6) same as 0.69

       0.69 (2008-09-16:37/2) (same as 1.0) and as previous  (0.57)  with  the
       addition of book index tags

         /^={.+?}$/

       e.g.  appended  to  a paragraph, on a new-line (without a blank line in
       between) logical structure produced assuming this  is  the  first  text
       "object"

          ={GNU/Linux community distribution:Debian+2|Fedora|Gentoo;Free Software Foundation+5}

         Free Software Foundation, 1-6
         GNU/Linux community distribution, 1
             Debian, 1-3
             Fedora, 1
             Gentoo,

       0.66   (2008-02-24:07/7)   same   as   previous,  adds  semantic  tags,
       [experimental  and not-used]

         /[:;]{.+?}[:;][a-z+]/

       0.57 (2007w34/4) SiSU 0.57 is the same as 0.42 with the introduction of
       some  a  shortcut  to  use the headers @title and @creator in the first
       heading [expanded  using  the contents  of  the  headers  @title:   and
        @author:]

         :A~ @title by @author

       0.52   (2007w14/6)  declared  document  type  identifier  at  start  of
       text/document:

         .B SiSU 0.52

       or, backward compatible using the comment marker:

         % SiSU 0.38

       variations  include  '   SiSU   (text|master|insert)   [version]'   and
       'sisu-[version]'

       0.51 (2007w13/6) skins changed (simplified), markup unchanged

       0.42  (2006w27/4)  * (asterisk) type endnotes, used e.g. in relation to
       author

       SiSU 0.42 is the same as 0.38 with the introduction of some  additional
       endnote types,

       Introduces  some  variations  on endnotes, in particular the use of the
       asterisk

         ~{* for example for describing an author }~ and ~{** for describing a second author }~

       * for example for describing an author

       ** for describing a second author

       and

         ~[*  my  note  ]~ or ~[+  another  note  ]~

       which numerically increments an asterisk and plus respectively

       *1 my note +1 another note

       0.38 (2006w15/7) introduced new/alternative notation for headers,  e.g.
       @title:  (instead  of  0~title),  and  accompanying  document structure
       markup, :A,:B,:C,1,2,3 (maps to previous 1,2,3,4,5,6)

       SiSU   0.38   introduced   alternative    experimental    header    and
       heading/structure markers,

         @headername: and headers :A~ :B~ :C~ 1~ 2~ 3~

       as the equivalent of:

         0~headername and headers 1~ 2~ 3~ 4~ 5~ 6~

       The  internal  document  markup of SiSU 0.16 remains valid and standard
       Though note that SiSU 0.37 introduced a new file naming convention

       SiSU has in effect two sets of levels  to  be  considered,  using  0.38
       notation  A-C headings/levels, pre-ordinary paragraphs /pre-substantive
       text, and 1-3 headings/levels, levels which are  followed  by  ordinary
       text. This may be conceptualised as levels A,B,C, 1,2,3, and using such
       letter number notation, in effect: A must exist, optional B and  C  may
       follow  in  sequence  (not  strict)  1 must exist, optional 2 and 3 may
       follow in  sequence  i.e.  there  are  two  independent  heading  level
       sequences  A,B,C  and 1,2,3 (using the 0.16 standard notation 1,2,3 and
       4,5,6) on the positive side: the  0.38  A,B,C,1,2,3  alternative  makes
       explicit  an  aspect  of  structuring  documents  in  SiSU  that is not
       otherwise obvious to the newcomer (though it appears more  complicated,
       is  more  in your face and likely to be understood fairly quickly); the
       substantive text follows levels 1,2,3 and it is 'nice' to do most  work
       in those levels

       0.37  (2006w09/7)  introduced  new file naming convention, .sst (text),
       .ssm (master), .ssi (insert), markup syntax unchanged

       SiSU 0.37  introduced  new  file  naming  convention,  using  the  file
       extensions .sst
        .ssm and .ssi to replace .s1 .s2 .s3 .r1 .r2 .r3 and .si

       this is captured by the following file 'rename' instruction:

         rename 's/\.s[123]$/\.sst/' *.s{1,2,3}
         rename 's/\.r[123]$/\.ssm/' *.r{1,2,3}
         rename 's/\.si$/\.ssi/' *.si

       The internal document markup remains unchanged, from SiSU 0.16

       0.35 (2005w52/3) sisupod, zipped content file introduced

       0.23 (2005w36/2) utf-8 for markup file

       0.22  (2005w35/3)  image  dimensions  may  be  omitted  if  rmagick  is
       available to be relied upon

       0.20.4 (2005w33/4) header 0~links

       0.16 (2005w25/2) substantial changes introduced to make markup cleaner,
       header  0~title  type,  and headings [1-6]~ introduced, also percentage
       sign (%) at start of a text line as comment marker

       SiSU 0.16 (0.15 development branch) introduced the use of

       the header 0~ and headings/structure 1~ 2~ 3~ 4~ 5~ 6~

       in place of the 0.1 header, heading/structure notation

       SiSU 0.1 headers and headings structure represented by header  0{~  and
       headings/structure 1{ 2{ 3{ 4{~ 5{ 6{

12. SISU FILETYPES

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

12.1 .SST .SSM .SSI MARKED UP PLAIN TEXT

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

12.1.1 SISU TEXT - REGULAR FILES (.SST)

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

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

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

12.1.2 SISU MASTER FILES (.SSM)

       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 [^17]

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

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

12.1.3 SISU INSERT FILES (.SSI)

       Inserts  are  documents  prepared  solely  for  the  purpose  of  being
       incorporated into one or more master documents. They  resemble  regular
       SiSU text files except they are ignored by the SiSU processor. Making a
       file a .ssi file is a quick and convenient way of flagging that  it  is
       not intended that the file should be processed on its own.

12.2 SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)

       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)

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

       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>

13. EXPERIMENTAL ALTERNATIVE INPUT REPRESENTATIONS

13.1 ALTERNATIVE XML

       SiSU  offers  alternative  XML  input representations of documents as a
       proof of concept, experimental feature. They are however  not  strictly
       maintained, and incomplete and should be handled with care.

       convert from sst to simple xml representations (sax, dom and node):

         sisu     --to-sax     [filename/wildcard]     or     sisu    --to-sxs
       [filename/wildcard]

         sisu    --to-dom     [filename/wildcard]     or     sisu     --to-sxd
       [filename/wildcard]

         sisu     --to-node     [filename/wildcard]     or    sisu    --to-sxn
       [filename/wildcard]

       convert to sst from any sisu xml representation (sax, dom and node):

         sisu --from-xml2sst [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

       or the same:

         sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

13.1.1 XML SAX REPRESENTATION

       To convert from sst to simple xml (sax) representation:

         sisu    --to-sax     [filename/wildcard]     or     sisu     --to-sxs
       [filename/wildcard]

       To convert from any sisu xml representation back to sst

         sisu --from-xml2sst [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

       or the same:

         sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

13.1.2 XML DOM REPRESENTATION

       To convert from sst to simple xml (dom) representation:

         sisu     --to-dom     [filename/wildcard]     or     sisu    --to-sxd
       [filename/wildcard]

       To convert from any sisu xml representation back to sst

         sisu --from-xml2sst [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

       or the same:

         sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

13.1.3 XML NODE REPRESENTATION

       To convert from sst to simple xml (node) representation:

         sisu    --to-node    [filename/wildcard]     or     sisu     --to-sxn
       [filename/wildcard]

       To convert from any sisu xml representation back to sst

         sisu --from-xml2sst [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

       or the same:

         sisu --from-sxml [filename/wildcard  [.sxs.xml,.sxd.xml,sxn.xml]]

14. CONFIGURATION

14.1 DETERMINING THE CURRENT CONFIGURATION

       Information  on  the  current configuration of SiSU should be available
       with the help command:

         sisu -v

       which is an alias for:

         sisu --help env

       Either of these  should  be  executed  from  within  a  directory  that
       contains sisu markup source documents.

14.2 CONFIGURATION FILES (CONFIG.YML)

       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/sisurc.yml

         ~/.sisu/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

15. SKINS

       Skins  modify  the default appearance of document output on a document,
       directory, or site wide basis. Skins are looked for  in  the  following
       locations:

         ./_sisu/skin

         ~/.sisu/skin

         /etc/sisu/skin

       Within the skin directory are the following the default sub-directories
       for document skins:

         ./skin/doc

         ./skin/dir

         ./skin/site

       A skin is placed in  the  appropriate  directory  and  the  file  named
       skin_[name].rb

       The  skin  itself is a ruby file which modifies the default appearances
       set in the program.

15.1 DOCUMENT SKIN

       Documents take on a document  skin,  if  the  header  of  the  document
       specifies a skin to be used.

         @skin: skin_united_nations

15.2 DIRECTORY SKIN

       A  directory  may  be  mapped on to a particular skin, so all documents
       within that directory take on a particular appearance. If a skin exists
       in  the  skin/dir with the same name as the document directory, it will
       automatically be used for each of  the  documents  in  that  directory,
       (except  where  a  document  specifies  the use of another skin, in the
       skin/doc directory).

       A personal habit is to place all skins within the  doc  directory,  and
       symbolic links as needed from the site, or dir directories as required.

15.3 SITE SKIN

       A site skin, modifies the program default skin.

15.4 SAMPLE SKINS

       With SiSU installed sample skins may be found in:

         /etc/sisu/skin/doc and
         /usr/share/doc/sisu/markup-samples/samples/_sisu/skin/doc

       (or  equivalent directory) and if sisu-markup-samples is installed also
       under:

         /usr/share/doc/sisu/markup-samples-non-free/samples/_sisu/skin/doc

       Samples of list.yml and promo.yml (which are used to create  the  right
       column list) may be found in:

         /usr/share/doc/sisu/markup-samples-non-free/samples/_sisu/skin/yml
       (or
         equivalent directory)

16. CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)

       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,  and
       change the default CSS file that is looked for in a skin.[^18]

17. ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING

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

17.1 DOCUMENT SOURCE DIRECTORY

       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  ...
       codes   are   usedr.  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.

17.1.1 GENERAL DIRECTORIES

         ./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
         % 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

17.2 DOCUMENT OUTPUT DIRECTORY STRUCTURES

17.2.1 OUTPUT DIRECTORY ROOT

       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.

17.2.2 ALTERNATIVE OUTPUT STRUCTURES

       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)

17.2.3 BY LANGUAGE

       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

17.2.4 BY FILETYPE

       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

17.2.5 BY FILENAME

       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

17.2.6 REMOTE DIRECTORIES

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

17.2.7 SISUPOD

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

17.3 ORGANISING CONTENT

18. HOMEPAGES

       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.

18.1 HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY

       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

18.2 HOME PAGE WITHIN A SKIN

       Skins  are  described  in  a separate section, but basically are a file
       written in the programming language Ruby that may be provided to change
       the  defaults  that  are  provided with sisu with respect to individual
       documents, a directories contents or for a site.

       If you wish to provide a homepage within a skin the skin should  be  in
       the  directory  _sisu/skin/dir  and  have the name of the directory for
       which it is to  become  the  home  page.  Documents  in  the  directory
       commercial_law  would  have  the  homepage  modified in skin_commercial
       law.rb; or the directory poems in skin_poems.rb

           class Home
             def homepage
               # place the html content of your homepage here, this will become index.html
               <<HOME <html>
         <head></head>
         <doc>
         <p>this is my new homepage.</p>
         </doc>
         </html>
         HOME
             end
           end

19. MARKUP AND OUTPUT EXAMPLES

19.1 MARKUP EXAMPLES

       Current markup examples and document output  samples  are  provided  at
       <http://www.jus.uio.no/sisu/SiSU/examples.html>

       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.

20. SISU SEARCH - INTRODUCTION

       SiSU  output  can  easily  and  conveniently  be indexed by a number of
       standalone indexing tools, such as Lucene, Hyperestraier.

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

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

21. SQL

21.1 POPULATING SQL TYPE DATABASES

       SiSU  feeds  sisu   markupd   documents   into   sql   type   databases
       PostgreSQL[^19]  and/or  SQLite[^20] 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 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 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  Dublin  Core  is  incorporated  it  is easy to make use of that as
       well).

22. POSTGRESQL

22.1 NAME

       SiSU - Structured information, Serialized Units - a document publishing
       system, postgresql dependency package

22.2 DESCRIPTION

       Information  related  to using postgresql with sisu (and related to the
       sisu_postgresql dependency package, which is a dummy package to install
       dependencies  needed  for  SiSU to populate a postgresql database, this
       being part of SiSU - man sisu).

22.3 SYNOPSIS

         sisu -D [instruction] [filename/wildcard  if  required]

         sisu -D --pg --[instruction] [filename/wildcard  if  required]

22.4 COMMANDS

       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

       -D or --pgsql may be used interchangeably.

22.4.1 CREATE AND DESTROY DATABASE

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

       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

22.4.2 IMPORT AND REMOVE DOCUMENTS

       sisu -D --import -v [filename/wildcard]
              populates database  with  the  contents  of  the  file.  Imports
              documents(s)  specified  to  a postgresql 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 postgresql database.

23. SQLITE

23.1 NAME

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

23.2 DESCRIPTION

       Information  related  to  using  sqlite  with  sisu (and related to the
       sisu_sqlite dependency package, which is a  dummy  package  to  install
       dependencies needed for SiSU to populate an sqlite database, this being
       part of SiSU - man sisu).

23.3 SYNOPSIS

         sisu -d [instruction] [filename/wildcard  if  required]

         sisu  -d   --(sqlite|pg)   --[instruction]   [filename/wildcard    if
       required]

23.4 COMMANDS

       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

       -d or --sqlite may be used interchangeably.

23.4.1 CREATE AND DESTROY DATABASE

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

23.4.2 IMPORT AND REMOVE DOCUMENTS

       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.

24. INTRODUCTION

24.1 SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES,

       INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)

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

       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  object  citation  numbering,  which
       includes  html,  XML, EPUB, LaTeX, PDF and indeed the SQL database. You
       can then refer to one of the other  outputs  or  in  the  SQL  database
       expand  the  text  within  the  matched  objects  (paragraphs)  in  the
       documents matched.

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

       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]

24.2 SEARCH FORM

       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 -Fv
              as  above,  and  provides  some  information   on   setting   up
              hyperestraier

       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

25. SISU_WEBRICK

25.1 NAME

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

25.2 SYNOPSIS

       sisu_webrick [port]

       or

       sisu -W [port]

25.3 DESCRIPTION

       sisu_webrick is part of SiSU (man sisu) sisu_webrick starts  Ruby  SiSU
       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).

25.4 SUMMARY OF MAN PAGE

       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

25.5 DOCUMENT PROCESSING COMMAND FLAGS

       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

25.6 FURTHER INFORMATION

       For  more  information  on  SiSU  see:   <http://www.sisudoc.org/>   or
       <http://www.jus.uio.no/sisu>

       or man sisu

25.7 AUTHOR

       Ralph Amissah <ralph@amissah.com> or <ralph.amissah@gmail.com>

25.8 SEE ALSO

         sisu(1)

         sisu_vim(7)

26. REMOTE SOURCE DOCUMENTS

       SiSU processing instructions can be run against remote source documents
       by providing the url of the  documents  against  which  the  processing
       instructions  are  to  be  carried  out.  The remote SiSU documents can
       either be sisu marked up files in plaintext .sst  or  .ssm  or;  zipped
       sisu files, sisupod.zip or filename.ssp

       .sst / .ssm - sisu text files

       SiSU  can be run against source text files on a remote machine, provide
       the processing instruction  and  the  url.  The  source  file  and  any
       associated  parts  (such  as  images)  will be downloaded and generated
       locally.

         sisu -3 http://[provide  url  to  valid  .sst  or  .ssm  file]

       Any of the source documents in the sisu examples page can  be  used  in
       this  way,  see <http://www.jus.uio.no/sisu/SiSU/examples.html> and use
       the url to the
        .sst for the desired document.

       NOTE: to set up a remote machine to serve SiSU documents in  this  way,
       images  should  be  in  the  directory  relative to the document source
       ../_sisu/image

       sisupod - zipped sisu files

       A sisupod is the zipped content of a sisu marked up text or  texts  and
       any other associated parts to the document such as images.

       SiSU  can  be  run  against  a  sisupod on a (local or) remote machine,
       provide the processing instruction and the url,  the  sisupod  will  be
       downloaded and the documents it contains generated locally.

         sisu -3 http://[provide  url  to  valid  sisupod.zip  or  .ssp  file]

       Any  of  the  source documents in the sisu examples page can be used in
       this way, see <http://www.jus.uio.no/sisu/SiSU/examples.html>  and  use
       the url for the desired document.

REMOTE DOCUMENT OUTPUT

27. REMOTE OUTPUT

       Once  properly  configured SiSU output can be automatically posted once
       generated to a designated remote machine using either rsync, or scp.

       In order to do this some  ssh  authentication  agent  and  keychain  or
       similar  tool  will  need  to  be  configured.  Once  that  is done the
       placement on a remote host can be done seamlessly with the -r (for scp)
       or  -R  (for  rsync)  flag, which may be used in conjunction with other
       processing flags, e.g.

         sisu -3R sisu_remote.sst

27.1 COMMANDS

       -R [filename/wildcard]
              copies sisu output  files  to  remote  host  using  rsync.  This
              requires  that  sisurc.yml has been provided with information on
              hostname and username, and that you have  your  "keys"  and  ssh
              agent  in  place.  Note the behavior of rsync different if -R is
              used with other flags  from  if  used  alone.  Alone  the  rsync
              --delete  parameter  is  sent,  useful  for  cleaning the remote
              directory (when -R is used together  with  other  flags,  it  is
              not). Also see -r

       -r [filename/wildcard]
              copies sisu output files to remote host using scp. This requires
              that sisurc.yml has been provided with information  on  hostname
              and  username,  and  that  you have your "keys" and ssh agent in
              place. Also see -R

27.2 CONFIGURATION

       [expand  on  the  setting  up  of  an  ssh-agent  /  keychain]

28. REMOTE SERVERS

       As SiSU is generally operated using the command line, and works  within
       a Unix type environment, SiSU the program and all documents can just as
       easily be on a remote server, to  which  you  are  logged  on  using  a
       terminal,  and commands and operations would be pretty much the same as
       they would be on your local machine.

29. QUICKSTART - GETTING STARTED HOWTO

29.1 INSTALLATION

       Installation is currently most straightforward and tested on the Debian
       platform,  as  there  are packages for the installation of sisu and all
       requirements for what it does.

29.1.1 DEBIAN INSTALLATION

       SiSU is available directly from the Debian  Sid  and  testing  archives
       (and  possibly  Ubuntu),  assuming  your  /etc/apt/sources.list  is set
       accordingly:

           aptitude update
           aptitude install sisu-complete

       The following /etc/apt/sources.list setting  permits  the  download  of
       additional markup samples:

         #/etc/apt/sources.list
           deb http://ftp.fi.debian.org/debian/ unstable main non-free contrib
           deb-src http://ftp.fi.debian.org/debian/ unstable main non-free contrib

       The aptitude commands become:

           aptitude update
           aptitude install sisu-complete sisu-markup-samples

       If  there  are  newer versions of SiSU upstream of the Debian archives,
       they  will   be   available   by   adding   the   following   to   your
       /etc/apt/sources.list

         #/etc/apt/sources.list
           deb http://www.jus.uio.no/sisu/archive unstable main non-free
           deb-src http://www.jus.uio.no/sisu/archive unstable main non-free

       repeat the aptitude commands

           aptitude update
           aptitude install sisu-complete sisu-markup-samples

       Note  however  that it is not necessary to install sisu-complete if not
       all components of sisu are to be used. Installing just the package sisu
       will provide basic functionality.

29.1.2 RPM INSTALLATION

       RPMs  are  provided though untested, they are prepared by running alien
       against the source package, and against the debs.

       They may be downloaded from:

         <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>

       as root type:

         rpm -i [rpm  package  name]

29.1.3 INSTALLATION FROM SOURCE

       To install SiSU from source check information at:

         <http://www.jus.uio.no/sisu/SiSU/download.html#current>

       * download the source package

       * Unpack the source

       Two  alternative  modes  of  installation  from  source  are  provided,
       setup.rb  (by  Minero  Aoki)  and  a rant(by Stefan Lang) built install
       file, in either case: the first steps are the same, download and unpack
       the source file:

       For  basic  use  SiSU  is only dependent on the programming language in
       which it is written Ruby, and SiSU will be able to generate html, EPUB,
       various XMLs, including ODF (and will also produce LaTeX). Dependencies
       required for further actions, though it relies on the  installation  of
       additional dependencies which the source tarball does not take care of,
       for things  like  using  a  database  (postgresql  or  sqlite)[^24]  or
       converting LaTeX to pdf.

       setup.rb

       This  is  a  standard  ruby  installer,  using setup.rb is a three step
       process. In the root directory of the unpacked SiSU as root type:

             ruby setup.rb config
             ruby setup.rb setup
             #[and  as  root:]
             ruby setup.rb install

       further information on setup.rb is available from:

         <http://i.loveruby.net/en/projects/setup/>

         <http://i.loveruby.net/en/projects/setup/doc/usage.html>

       install

       The "install" file provided is an installer prepared using  "rant".  In
       the root directory of the unpacked SiSU as root type:

         ruby install base

       or for a more complete installation:

         ruby install

       or

         ruby install base

       This  makes  use of Rant (by Stefan Lang) and the provided Rantfile. It
       has been configured to do post installation setup  setup  configuration
       and  generation  of  first  test  file.  Note  however, that additional
       external package dependencies, such as tetex-extra are not  taken  care
       of for you.

       Further information on "rant" is available from:

         <http://make.rubyforge.org/>

         <http://rubyforge.org/frs/?group_id=615>

       For a list of alternative actions you may type:

         ruby install help

         ruby install -T

29.2 TESTING SISU, GENERATING OUTPUT

       To check which version of sisu is installed:

       sisu -v

       Depending on your mode of installation one or a number of markup sample
       files may be found either in the directory:

       or

       change directory to the appropriate one:

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

29.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB

       Having moved to the directory that contains  the  markup  samples  (see
       instructions above if necessary), choose a file and run sisu against it

       sisu                                                        -NhwoabxXyv
       free_as_in_freedom.rms_and_free_software.sam_williams.sst

       this will generate html including a concordance file, opendocument text
       format,  plaintext,  XHTML  and  various forms of XML, and OpenDocument
       text

29.2.2 LATEX / PDF

       Assuming a LaTeX engine such as tetex or texlive is installed with  the
       required modules (done automatically on selection of sisu-pdf in Debian
       )

       Having moved to the directory that contains  the  markup  samples  (see
       instructions above if necessary), choose a file and run sisu against it

       sisu -pv free_as_in_freedom.rms_and_free_software.sam_williams.sst

       sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst

       should  generate  most  available  output  formats:  html  including  a
       concordance  file,  opendocument  text  format,  plaintext,  XHTML  and
       various forms of XML, and OpenDocument text and pdf

29.2.3 RELATIONAL DATABASE - POSTGRESQL, SQLITE

       Relational databases need some setting up - you must have permission to
       create the database and write to it when you run sisu.

       Assuming you have the database installed and the requisite permissions

       sisu --sqlite --recreate

       sisu                --sqlite                -v                 --import
       free_as_in_freedom.rms_and_free_software.sam_williams.sst

       sisu --pgsql --recreate

       sisu                 --pgsql                 -v                --import
       free_as_in_freedom.rms_and_free_software.sam_williams.sst

29.3 GETTING HELP

29.3.1 THE MAN PAGES

       Type:

         man sisu

       The man pages are also available online, though not always kept  as  up
       to date as within the package itself:

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

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

       * man directory <http://www.jus.uio.no/sisu/man> [^27]

29.3.2 BUILT IN HELP

       sisu --help

       sisu --help --env

       sisu --help --commands

       sisu --help --markup

29.3.3 THE HOME PAGE

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

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

       <http://www.jus.uio.no/sisu/SiSU>

29.4 MARKUP SAMPLES

       A number of markup samples (along with output) are available off:

       <http://www.jus.uio.no/sisu/SiSU/examples.html>

       Additional markup samples are packaged separately in the file:

       ***

       On  Debian  they  are  available in non-free[^28] to include them it is
       necessary to include non-free in your  /etc/apt/source.list  or  obtain
       them from the sisu home site.

30. EDITOR FILES, SYNTAX HIGHLIGHTING

       The directory:

         ./data/sisu/v2/conf/editor-syntax-etc/

         ./data/sisu/v3/conf/editor-syntax-etc/

         /usr/share/sisu/v2/conf/editor-syntax-etc

         /usr/share/sisu/v3/conf/editor-syntax-etc

       contains rudimentary sisu syntax highlighting files for:

       * (g)vim <http://www.vim.org>

         package: sisu-vim

       status: largely done

         there is a vim syntax highlighting and folds component

       * gedit <http://www.gnome.org/projects/gedit>

       * gobby <http://gobby.0x539.de/>

         file: sisu.lang

       place in:

         /usr/share/gtksourceview-1.0/language-specs

       or

         ~/.gnome2/gtksourceview-1.0/language-specs

         status: very basic syntax highlighting

         comments: this editor features display line wrap and is used by Goby!

       * nano <http://www.nano-editor.org>

         file: nanorc

       save as:

         ~/.nanorc

         status: basic syntax highlighting

         comments:  assumes  dark  background; no display line-wrap; does line
       breaks

       * diakonos (an editor written in ruby) <http://purepistos.net/diakonos>

       file: diakonos.conf

       save as:

         ~/.diakonos/diakonos.conf

       includes:

         status: basic syntax highlighting

       comments: assumes dark background; no display line-wrap

       * kate & kwrite <http://kate.kde.org>

         file: sisu.xml

         place in:

           /usr/share/apps/katepart/syntax

         or

           ~/.kde/share/apps/katepart/syntax

         [settings::configure  kate::{highlighting,filetypes}]

         [tools::highlighting::{markup,scripts}::  .B  SiSU  ]

       * nedit <http://www.nedit.org>

         file: sisu_nedit.pats

         nedit -import sisu_nedit.pats

         status: a very clumsy first attempt [not  really  done]

         comments: this editor features display line wrap

       * emacs <http://www.gnu.org/software/emacs/emacs.html>

         files: sisu-mode.el

         to file ~/.emacs add the following 2 lines:

           (add-to-list 'load-path
           "/usr/share/sisu/v2/conf/editor-syntax-etc/emacs")

           (require 'sisu-mode.el)

         [not  done  /  not  yet  included]

       * vim & gvim <http://www.vim.org>

         files:

         package is the most comprehensive sisu syntax highlighting and editor
         environment provided to date (is for vim/ gvim, and is separate  from
       the
         contents of this directory)

         status:  this  includes:  syntax  highlighting; vim folds; some error
       checking

         comments: this editor features display line wrap

       NOTE:

       [  .B  SiSU  parses  files  with  long  lines  or  line   breaks,  but,
        display   linewrap   (without   line-breaks)  is  a  convenient editor
        feature  to  have  for  sisu  markup]

31. HOW DOES SISU WORK?

       SiSU  markup  is  fairly  minimalistic,  it  consists  of:  a  (largely
       optional)  document  header,  made up of information about the document
       (such as when it was published, who  authored  it,  and  granting  what
       rights)   and  any  processing  instructions;  and  markup  within  the
       substantive  text  of  the  document,  which  is  related  to  document
       structure  and typeface.  SiSU must be able to discern the structure of
       a document, (text headings and their levels in relation to each other),
       either  from information provided in the document header or from markup
       within the text (or from a combination of both).   Processing  is  done
       against an abstraction of the document comprising of information on the
       document's structure and its objects,[2] which the  program  serializes
       (providing  the  object numbers) and which are assigned hash sum values
       based on their content. This abstraction of information about  document
       structure,  objects, (and hash sums), provides considerable flexibility
       in representing documents different ways  and  for  different  purposes
       (e.g.  search,  document  layout,  publishing,  content  certification,
       concordance etc.), and makes it possible to take advantage of  some  of
       the strengths of established ways of representing documents, (or indeed
       to create new ones).

32. SUMMARY OF FEATURES

       * 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

         * ODF - open document format, the iso standard for document storage

         * LaTeX - used to generate pdf

         * pdf (via LaTeX)

         * sql - population of an sql database, (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 granular search (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.

33. HELP SOURCES

33.1 MAN PAGES

         man sisu

         man sisu-concordance

         man sisu-epub

         man sisu-git

         man sisu-harvest

         man sisu-html

         man sisu-odf

         man sisu-pdf

         man sisu-pg

         man sisu-po

         man sisu-sqlite

         man sisu-txt

         man 7 sisu_complete

         man 7 sisu_pdf

         man 7 sisu_postgresql

         man 7 sisu_sqlite

         man sisu_termsheet

         man sisu_webrick

33.2 SISU GENERATED OUTPUT - LINKS TO HTML

       Note  SiSU documentation is prepared in SiSU and output is available in
       multiple formats including amongst others  html,  pdf,  odf  and  epub,
       which may be also be accessed via the html pages[^29]

33.2.1 WWW.SISUDOC.ORG

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

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

33.3 MAN2HTML

33.3.1 LOCALLY INSTALLED

       file:///usr/share/doc/sisu/html/sisu.1.html

         file:///usr/share/doc/sisu/html/sisu.1.html

         /usr/share/doc/sisu/html/sisu_pdf.7.html

         /usr/share/doc/sisu/html/sisu_postgresql.7.html

         /usr/share/doc/sisu/html/sisu_sqlite.7.html

         /usr/share/doc/sisu/html/sisu_webrick.1.html

33.3.2 WWW.JUS.UIO.NO/SISU

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

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

         <http://www.jus.uio.no/sisu/man/sisu_complete.7.html>

         <http://www.jus.uio.no/sisu/man/sisu_pdf.7.html>

         <http://www.jus.uio.no/sisu/man/sisu_postgresql.7.html>

         <http://www.jus.uio.no/sisu/man/sisu_sqlite.7.html>

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

       1.     objects  include:  headings,  paragraphs, verse, tables, images,
              but not footnotes/endnotes which  are  numbered  separately  and
              tied to the object from which they are referenced.

       2.     i.e.   the   html,   pdf,  epub,  odf  outputs  are  each  built
              individually and optimised for that form of presentation, rather
              than  for  example the html being a saved version of the odf, or
              the pdf being a saved version of the html.

       3.     the different heading levels

       4.     units of text,  primarily  paragraphs  and  headings,  also  any
              tables, poems, code-blocks

       5.     Specification  submitted  by  Adobe to ISO to become a full open
              ISO specification

              <http://www.linux-watch.com/news/NS7542722606.html>

       6.     ISO standard ISO/IEC 26300:2006

       7.     An open standard format for e-books

       *1.    square brackets

       *2.    square brackets

       +1.    square brackets

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

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

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

       11.    files should be prepared using UTF-8 character encoding

       12.    a footnote or endnote

       13.    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 asterisk footnote/endnote series

       14.    <http://www.sisudoc.org/>

       15.    <http://www.ruby-lang.org/en/>

       16.    Table from the Wealth of Networks by Yochai Benkler

              <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>

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

       19.    <http://www.postgresql.org/>

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

       20.    <http://www.hwaci.com/sw/sqlite/>

              <http://en.wikipedia.org/wiki/Sqlite>

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

       22.    (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.

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

       24.    There is nothing to stop MySQL support being added in future.

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

       26.    <http://www.jus.uio.no/sisu/man/sisu.8.html>

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

              28. the Debian Free Software guidelines require that  everything
              distributed within Debian can be changed - and the documents are
              authors' works that while freely distributable  are  not  freely
              changeable.

              29.    named    index.html    or    more   extensively   through
              sisu_manifest.html

SEE ALSO

       sisu(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/>.

AUTHOR

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