Provided by: sisu_0.37.4-1build1_all bug

NAME

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

SYNOPSIS

       sisu [-mhwpxXv...] [ filename/wildcard ]

DESCRIPTION

       A document publishing system,  that  from  a  simple  single  marked-up
       document,  produces  a  multitude  of  output  formats including: html,
       latex, pdf, info, and sql output, which  can  be  cross  referenced  as
       having  the  same document structure and text object numbering, "object
       citation numbering". Features include its´ simple syntax; the  semantic
       identification of documents using the Dublin Core; document management;
       built to be associated with a  revision  control  system;  text  object
       numbering  for  the  identification  of  a texts location in any of the
       output formats, easy skinning on a site wide, or  per  document  basis,
       ... for more see man 1 sisu or http://www.jus.uio.no/sisu

       SiSU is an alternative way of publishing and managing documents.

INSTALLATION

       Up to date information on SiSU downloads, and their installation should
       be available from: http://www.jus.uio.no/sisu/sisu_download/download or
       at: http://www.jus.uio.no/sisu/SiSU/download

       There  you  should  find  links  to  the  latest  source  tarball,  and
       instructions on how to install SiSU.

       NB. SiSU markup syntax changed in sisu-0.16

       Sample    marked    up    documents    are     are     available     at
       /usr/share/sisu-examples/sample/document_samples_sisu_markup         or
       equivalent          directory,          or          online           at
       http://www.jus.uio.no/sisu/sample/markup   or   in   html  with  syntax
       highlighting from http://www.jus.uio.no/sisu/sample/syntax

       A syntax table  is  provided  at  /usr/share/doc/sisu/on_markup.txt  or
       equivalent,                 and                online                at
       http://www.jus.uio.no/sisu/sample/on_markup.txt

       man 1 sisu has a syntax table along with processing commands.

       SiSU also has an interactive help entered by typing sisu and  selecting
       the  subject,  or  to  get  help on a subject directly, e.g.  sisu help
       markup or e.g.  sisu help headers or e.g.  sisu help commands  however,
       the man pages are probably more up to date than the interactive help.

       The  rest  of  this  note is on post installation setup (it assumes you
       have sisu-examples installed for which there are  instructions  on  the
       download page mentioned above).

Post Installation Setup - Quickstart

       A.              Quick              test              cd              to
       /usr/share/sisu-examples/sample/document_samples_sisu_markup  select  a
       document there and run (for example) sisu -mhwpv gpl2.fsf.sst

       that  is  it  information  should be provided as to where the generated
       output was placed.

       B. Generate a (local) document from a markup/work directory.

       1.  Create a directory for sisu marked up documents  within  your  home
       directory: e.g.  ~/sisu_test

       2.      Select     a     sample    markup    file    to    use    from:
       /usr/share/sisu-examples/sample/document_samples_sisu_markup   (created
       with  your  installation  of  the  sisu tarball or of sisu-example), or
       download          sample          markup          files           from:
       http://www.jus.uio.no/sisu/sample/markup  and copy a sample markup file
       into it e.g.  gpl2.fsf.sst

       Note: you may have several directories for marked up documents

       3.  Change to your work directory cd ~/sisu_test and run: sisu  -mHwapv
       gpl2.fsf.sst shortcut to same command: sisu -1v gpl2.fsf.sst

       You should have the document (without images specific to the document),
       and the selected verbose output should inform you where the output  has
       been placed.

       that is it

       C. Generate a (remote) document.

       If  you  are  connected  to  the  Net, change to your work directory cd
       ~/sisu_test and run

       sisu                                                            -mHwapv
       http://www.jus.uio.no/sisu/sample/markup/free_culture.lawrence_lessig.sst

       This generates the  remote  document  after  downloading  it  and  its´
       associated images,

       or again:

       sisu -3cv http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst

       that is it

       Tip:    the    markup    syntax    examples    may   be   of   interest
       http://www.jus.uio.no/sisu/sample/

       Tip: sisu -U [sisu  markup  filename]  should  printout  the  different
       possible outputs and where sisu would place them.

       Tip: if you want to toggle ansi color add c to your flags.

       ----------

       A note on images

       To  add  the  images,  within  your  document  markup directory (in our
       example which we shall use ~/sisu_test ) create a directory,

       ~/sisu_test/_sisu/image

       copy       the       images        from        the        sub-directory
       data/sisu-examples/sample/document_samples_sisu_markup/_sisu/image   in
       the directory from which you got your source markup,  in  this  example
       either,                             or                            from:
       /usr/share/sisu-examples/sample/document_samples_sisu_markup/_sisu/image
       or online from: http://www.jus.uio.no/sisu/sample/markup/_sisu/image

       (copy those images) into ~/sisu_test/_sisu/image

       then regenerate the document

       sisu -mHwapcv gpl2.fsf.sst

       that should be it

       Note:  for  local  documents, SiSU will look for generic images, images
       associated  with  all  documents,  (such  as  navigation  buttons)   in
       /usr/share/sisu-examples/sample/_sisu/image  (or  it´s  equivalent). It
       expects to find all images that are specific to documents contained  in
       the  markup  work  directory,  in  a  sub-directory  within  it  called
       ./_sisu/image

       ----------

       A more comprehensive test

       sisu -mHwabpxXv gpl2.fsf.sst

       which should be the same as

       sisu -3v gpl2.fsf.sst

       add c to toggle screen colour.

       ----------

       SiSU   setup   for   postgresql   and   sqlite   is    configured    in
       ~/.sisu/sisurc.yaml

       a  sample  of  this  file is provided with the examples provided at (or
       equivalent): /etc/sisu/sisurc.yaml the section to take note of in  this
       regard is to be found in that yaml file under db:

       [more extensive notes to be included later]

Debian INSTALLATION Note

       It  is best you see http://www.jus.uio.no/sisu/SiSU/download#debian for
       up the most up to date information.

       The following command should include  the  external  packages  used  by
       SiSU:

       required ruby (>=1.8.2)

       recommends  tetex-bin,  tetex-extra,  latex-ucs,  postgresql (>=8.0.0),
       libdbi-ruby,       libdbm-ruby,       libdbd-pg-ruby,        libsqlite,
       libdbd-sqlite-ruby,     librmagick-ruby,    trang,    tidy,    libtidy,
       librexml-ruby, sisu-examples, vim-ruby, sisu-vim

       suggested   makeinfo,   pgaccess,    texinfo,    pinfo,    libcgi_ruby,
       libfcgi-ruby1.8,       libdbd-pgsql,       libdbd-sqlite,      openssl,
       openssh-client|openssh-client, rcs|cvs

       A rough breakdown of additional additional packages and libraries

       ruby is required, sisu is written in ruby and needs it to run

       sisu-examples provides examples of various things including sisu markup
       which are usually placed under the tree /usr/share/sisu-examples it has
       its own man page,  "man  sisu_examples"  and  include  document  markup
       samples;  vim  syntax  highlighting and folds; a sample cgi frontend to
       database.

       sisu-vim provides vim syntax highlighting for the sisu markup, man page
       under "man sisu_vim"

       sisu-webrick  is  installed  with sisu runs the ruby webserver webrick,
       this has a man page "man sisu_webrick" -W

       The following output require nothing, and should work out of  the  box:
       plaintext  -a  -e, html -H -h, xhtml -b, xml -x -X, [php -z], latex -p,
       wordmap -w however the latex output in particular is used  to  generate
       pdf  which has several other requirements listed below, and some of the
       other libraries can take advantage of additional packages.

       xhtml and xml output -b -x -X will  use  the  following  if  available:
       tidy, libtidy to check that the output is well formed with the -v flag,
       and librexml-ruby , for an additional check that the output is readable
       with the -V flag

       The  metaverse,  the  first  step  in  processing  -m which produces an
       initial markup step, will make use if available of: librmagick-ruby  to
       determine  image  dimensions,  if  they are not provided in the markup,
       and, if instructed to in the document it will make use of  any  rcs  or
       cvs document version information provided in it using the Id tag

       Pdf  output  -p  (and latex though it can be generated without as it is
       used to produce  the  pdf),  require  tetex-bin,  tetex-extra,  (for  "
       pdfetex  "  aka.  pdflatex) latex-ucs, (to do utf-8 ) and if a document
       contains images requires the image  dimension  information  which  must
       either  be  provided  (manually  so  to  speak) as part of the document
       markup, or extracted (autmatically) during the "metaverse"  step  using
       librmagick-ruby

       if  sisu  output is to be streamed into a database -D or -d then either
       postgresql  (>=8.0.0),  libdbi-ruby,  libdbm-ruby,  libdbd-pg-ruby   or
       libsqlite, libdbd-sqlite-ruby, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby

       The cgi generator -S used to create a sample  database  front  end  cgi
       search form assumes the availability of libcgi_ruby, libfcgi-ruby1.8

       The texinfo output -I makes use of makeinfo, texinfo and is best viewed
       with pinfo

       Remote    placement    of    sisu    output    -r    makes    use    of
       openssh-client|openssh-client,   and  key  management  client  such  as
       keychain

OPTIONS

       SiSU has several modules that can be used independently of each  other,
       or  together  (you  could  just use SiSU to generate html). SiSU can be
       used either off the file system or with a relational database, or both.

       Once  a document is marked up all possibilities are available, provided
       external programs where required are present on  the  system.  External
       programs  can  be installed later to make these possibilities available
       at a subsequent date.

       Ruby > 1.8.2 required

plaintext -a -e

       [ no external programs required ]

html -H -h

       [ no external programs required ]

xhtml -b

       [ no external programs required, tidy and rexml recommended, check that
       documents are well formed ]

XML -x -X

       [ no external programs required, tidy and rexml recommended, check that
       documents are well formed ]

       tidy [recommended] is used when SiSU is run in verbose  mode  to  check
       that XML output is well formed and without errors

       rexml  (ruby  xml  parser)  [recommended  -  should  be  part  of  ruby
       distribution] is used in verbose mode, to read in document headers  and
       write them to screen in verbose mode (double check that output document
       is well formed)

LaTeX -p

       [ no external programs required ]  SiSU  generates  LaTeX,  however  to
       produce   pdfs   from   the  LaTeX  produced  you  require  tetex-base,
       tetex-extra and latex-ucs to interpret LaTeX generated  and  utf-8  and
       produce pdf

pdf -p

       [  requires  pdflatex  and ucs ] conversion from LaTeX to pdf file. For
       this you require tetex-bin, tex base package tetex-extra which includes
       pdflatex  and  latex-ucs for utf-8 also image dimensions must either be
       provided in document markup, or extracted using librmagick-ruby

texinfo -I

       [ requires makeinfo, texinfo ]

word map -w

       [ no external programs required, word  count  recommended  ]  wc  (word
       count)  [recommended]  is used so as not to create wordmaps, indexes on
       files that  are  over  200,000  words,  takes  a  bit  long,  but  more
       importantly  resulting  output  of indexed words becomes so large as to
       freeze browser.  tetex base and tetex extra required to interpret LaTeX
       generated

relational database

postgresql -D

       [  requires  postgresql (>=8.0.0), libdbi-ruby, libdbm-ruby, libdbd-pg-
       ruby ]

sqlite -d

       [ requires  libsqlite,  libdbd-sqlite-ruby,  libdbi-ruby,  libdbm-ruby,
       libdbd-pg-ruby ]

       sisu can be used without a database module

External Programs

general

       rcs  or  cvs  recommended  for  document versioning, RCS or CVS provide
       version control  and  version  stamps  for  documents.  The  versioning
       history can be incorporated into output. If used properly you can track
       which version of a document you are looking at.

wc

       [ word count, recommended ] used so as not to create wordmaps,  indexes
       on  files  that  are  over  200,000  words,  takes a bit long, but more
       importantly resulting output of indexed words becomes so  large  as  to
       freeze browser.

DOCUMENT RESOURCE CONFIGURATION

       sisu resource configuration information is obtained from sources (where
       they exist):
       ~/.sisu/sisurc.yaml
       /etc/sisu/[sisu version]/sisurc.yaml
       sisu program defaults

       Skins

       default document appearance may be modified using  skins  contained  in
       sub-directories located at the following paths:
       ~/.sisu/skin
       /etc/sisu/[sisu version]/skin

       more   specifically,   the  following  locations  (or  their  /etc/sisu
       equivalent) should be used:

       ~/.sisu/skin/doc skins for individual documents;

       ~/.sisu/skin/dir skins for directories of matching names;

       ~/.sisu/skin/site site-wide skin modifying the site-wide appearance  of
       documents.

       Usually  all  skin  files  are  placed  in the document skin directory:
       ~/.sisu/skin/doc with softlinks being made to the skins contained there
       from other skin directories as required.

FURTHER INFORMATION

       For more information on SiSU see: http://www.jus.uio.no/sisu

       or man sisu

AUTHOR

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

SEE ALSO

       sisu(1),  sisu_examples(1), sisu_webrick(1), sisu_pdf(1) sisu_sqlite(1)
       sisu_postgresql(1) sisu_makeinfo(1) sisu_termsheet(1), sisu_vim(1)