Provided by: sisu_0.70.5-1_all bug

NAME

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

SYNOPSIS

       sisu  [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9]  [filename/wildcard  ]
       sisu [-Ddcv] [instruction]  sisu [-CcFLSVvW]

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 to cope with medium to large document
       sets  with  evolving  markup  related  technologies,  which  should  be
       prepared  once, and for which you want multiple output formats that can
       be updated and a common mechanism for cross-output-format citation, and
       search.

        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, 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, 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 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 structure (or frame)[^3] and the  objects[^4]
       it  contains,  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 base 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 means that text appears on different pages; and  in  publishing
       in  different formats, html, landscape and portrait pdf etc. again page
       numbers are of no use to cite text in a manner that is relevant against
       the  different output types.  Dealing with documents at an object level
       together with object numbering also has implications for search.

        One of the challenges of maintaining documents is to keep  them  in  a
       format  that  would  allow  users  to  use  them without depending on a
       proprietary software popular at the time. Consider the ease of  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 outputing documents in multiple non-proprietary open
       formats including html, pdf[^5] and the ISO  standard  ODF.[^6]  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),
       and  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 the commercial law
       thesaurus by Vikki Rogers and Al Krtizer, 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.jus.uio.no/sisu>

2. COMMANDS SUMMARY


2.1 SYNOPSIS

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

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

        sisu [  -Ddcv  ] [  instruction  ]

        sisu [  -CcFLSVvW  ]

         Note:  commands  should  be  issued  from  within  the directory that
       contains the marked up files, cd to markup directory.

2.2 DESCRIPTION

        SiSU SiSU is a document publishing system, that from a  simple  single
       marked-up  document,  produces  multiple  of  output formats including:
       plaintext, html, LaTeX, pdf, xhtml, XML, info, and SQL (PostgreSQL  and
       SQLite), which share numbered text objects ( structure information. For
       more see: <http://www.jus.uio.no/sisu>

2.3 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]
              produces xhtml/XML output for browser viewing (sax parsing).

       -C [--init-site]
              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    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.

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

       -D [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.

       -d [--db-[database  type  (sqlite|pg)]] --[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.

       -F [--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).  -Fv  (in
              addition  to  the above) provides some information on setting up
              hyperestraier for sisu

       -H [filename/wildcard]
              produces html without link  suffixes  (.html  .pdf  etc.)  (  an
              appropriately configured web server. [behaviour  switched  after
               0.35 see  -h].

       -h [filename/wildcard]
              produces  html  (with  hardlinks  i.e.  with  name  suffixes  in
              links/local  urls).   html,  with  internal  document links that
              include the document suffix, i.e.  whether it is .html  or  .pdf
              (required  for  browsing  directly  off a file system, and works
              with most web servers). [behaviour  switched  after   0.35   see
               -H].

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

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

       -L     prints license information.

       -M [filename/wildcard/url]
              maintenance  mode  files  created  for  processing preserved and
              their locations indicated. (also see -V)

       -m [filename/wildcard/url]
              assumed for most other flags, creates new meta-markup file, (the
              metaverse  )  that is used in all subsequent processing of other
              output. This step is assumed for most processing flags. To  skip
              it see -n

       -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  meta-markup  (building of -m which is otherwise assumed by
              most processing flags.

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

       -p [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 ´legal´  and  book  sizes
              ´A5´ and ´B5´ (system defaults to A4).

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

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

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

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

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

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

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

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

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

       -V [filename/wildcard]
              even more verbose than the -v flag. (also see -M)

       -v     on its own, provides SiSU version information

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

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

       -w [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)

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

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

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

       -Z [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.

       -z [filename/wildcard]
              produces php (zend) [this  feature  is  disabled  for  the  time
              being]

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

3. COMMAND LINE MODIFIERS


       --no-ocn
              [with   -h   -H  or  -p] 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)]

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

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

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

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

       -D --dropall
              kills data --dropall  sqlite  equivalent]

               The v in e.g. -Dv 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  (note  that  the  defaults  can be
              changed/configured in the sisurc.yml file):

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

       -1     -mNHwpy

       -2     -mNHwpaoy

       -3     -mNhwpAobxXyY

       -4     -mNhwpAobxXDyY --import

       -5     -mNhwpAobxXDyY --update

                add  -v  for  verbose  mode  and  -c for color, 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.   cisg.sst
       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/sisu_markup_samples/sisu_manual/

         /usr/share/doc/sisu/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

         man sisu_markup

         man sisu_commands

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

        Once installed, directory equivalent to:

         /usr/share/doc/sisu/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/> [^7]

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

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.

6.4 HELP SOURCES

        For lists of alternative help sources, see:

        man page

         man sisu_help_sources

        man2html

         /usr/share/doc/sisu/sisu_manual/sisu_help_sources/index.html

        sisu generated html

         /usr/share/doc/sisu/html/sisu_help_sources/index.html

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

7. INTRODUCTION TO SISU MARKUP[^9]


7.1 SUMMARY

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

         Some  example  marked  up  files  are  available  as html with syntax
       highlighting for viewing: <http://www.jus.uio.no/sisu/sample/syntax>

            an     alternative     presentation     of     markup      syntax:
       <http://www.jus.uio.no/sisu/sample/on_markup.txt>

7.2.2 INSTALLED

           With    SiSU    installed   sample   skins   may   be   found   in:
       /usr/share/doc/sisu/sisu_markup_samples/dfsg (or equivalent  directory)
       and     if     sisu-markup-samples    is    installed    also    under:
       /usr/share/doc/sisu/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 has a header similar to this one (without the
       comments):

         % SiSU 0.57

         @title: SiSU

         @subtitle: Markup

         @creator: Amissah, Ralph

         % note formatting rules on author / creator field,

         @rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3

         @type: information

         @subject: ebook, epublishing, electronic book, electronic publishing, electronic document, electronic citation, data structure, citation systems, search

         @topic_register: text markup language; application:text processing;output:html|xml|latex|pdf|sql

         % note formatting for topic_register topic levels are separated by a colon, a semi-colon separates main topics

         @date: 2007-09-16

         % original publication date unless the substantive text is updated/modified, then date of update

         @date.created: 2002-08-28

         @date.issued: 2002-08-28

         @date.available: 2002-08-28

         @date.modified: 2007-09-16

         @level: new=C; break=1; num_top=1

         % comment: in this @level header num_top=1 starts automatic heading numbering at heading level 1 (numbering continues 3 levels down); the new and break instructions are used by the LaTeX/pdf and odf output to determine where to put page breaks (that are not used by html output or say sql database population).

         @skin: skin_sisu_manual

         % skins modify the appearance of a document and are placed in a sub-directory under ./_sisu/skin ~/.sisu/skin or /etc/sisu/skin. A skin may affect single documents that request them, all documents in a directory, or be site-wide. (A document is affected by a single skin)

         @bold: /Gnu|Debian|Ruby|SiSU/

         @links: { SiSU Manual }http://www.jus.uio.no/sisu/sisu_manual/

         { Book Samples and Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html

         { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU

         { SiSU @ Freshmeat }http://freshmeat.net/projects/sisu/

         { SiSU @ Ruby Application Archive }http://raa.ruby-lang.org/project/sisu/

         { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html

         { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html

         { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html

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  either  the  form @headername: or 0~headername. All
       Dublin Core meta tags are available

        @indentifier: information or instructions

        where the

        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 0.38 [declared  file-type  identifier  with  markup  version]

        @title:
         [title  text] This is the title of the document  and  used  as  such,
       this header is the only one that is mandatory

        @subtitle: The Subtitle if any

        @creator: [or  @author:] Name of Author

        @subject: (whatever your subject)

        @description:

        @publisher:

        @contributor:

        @translator:  [or  @translated_by:]

        @illustrator:  [or  @illustrated_by:]

        @prepared_by:  [or  @digitized_by:]

           @date:    2000-08-27   [    also    @date.created:    @date.issued:
        @date.available:  @date.valid: @date.modified:  ]

        @type: article

        @format:

        @identifier:

        @source:

        @language: [or  @language.document:] [country  code  for  language  if
        available,   or   language,   English,  en  is  the  default  setting]
       (en - English, fr - French, de - German, it - Italian, es - Spanish, pt
       -  Portuguese, sv - Swedish, da - Danish, fi - Finnish, no - Norwegian,
       is - Icelandic, nl - Dutch, et - Estonian, hu - Hungarian, pl - Polish,
       ro  -  Romanian, ru - Russian, el - Greek, uk - Ukranian, tr - Turkish,
       sk - Slovak, sl - Slovenian, hr - Croatian, cs - Czech, bg - Bul garian
       )  [however,   encodings   are   not   available   for   all   of   the
       languages  listed.]

        [@language.original:  original  language  in  which   the   work   was
       published]

        @papersize: (A4|US_letter|book_B5|book_A5|US_legal)

        @relation:

        @coverage:

         @rights:  Copyright (c) Name of Right Holder, all rights reserved, or
       as granted: public domain, copyleft, creative commons variant, etc.

        @owner:

        @keywords: text document generation processing  management  latex  pdf
       structured  xml citation [your  keywords  here,  used  for  example  by
        rss  feeds, and  in  sql  searches]

        @abstract: [paper  abstract,  placed  after  table  of  contents]

        @comment: [...]

        @catalogue: loc=[Library  of  Congress  classification];  dewey=[Dewey
       classification]; isbn=[ISBN]; pg=[Project  Gutenberg  text  number]

        @classify_loc: [Library  of  Congress  classification]

        @classify_dewey: [Dewey  classification]

        @classify_isbn: [ISBN]

        @classify_pg: [Project  Gutenberg  text  number]

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

         @prefix_a:  [prefix  is  placed  just  before  table  of  contents  -
        not implemented]

        @prefix_b:

        @rcs: $Id: sisu_markup.sst,v 1.2 2007/09/08 17:12:47 ralph Exp $ [used
        by   rcs or  cvs  to  embed  version  (revision  control)  information
        into document,  rcs  or  cvs  can  usefully  provide  a   history   of
       updates  to  a  document  ]

         @structure:  PART;  CHAPTER;  SECTION; ARTICLE; none; none; optional,
       document structure  can  be  defined  by  words  to  match  or  regular
       expression (the regular expression is assumed to start at the beginning
       of a line of text i.e. ^) default markers :A~ to :C~ and 1~ to  6~  can
       be  used  within text instead, without this header tag, and may be used
       to supplement the instructions provided in this header tag if  provided
       (@structure: is a synonym for @toc:)

        @level: newpage=3; breakpage=4 [paragraph  level,  used  by  latex  to
        breakpages,  the  page  is  optional  eg.  in  newpage]

        @markup: information on the  markup  used,  e.g.  new=1,2,3;  break=4;
       num_top=4  [or  newpage=1,2,3;   breakpage=4;   num_top=4]  newpage and
       breakpage, heading level,  used  by  LaTeX  to  breakpages.  breakpage:
       starts  on  a  new  page  in  single column text and on a new column in
       double column text; newpage: starts on a new page for both  single  and
       double  column  texts.  num_top=4 [auto-number  document,  starting  at
        level  4.  the default  is  to  provide  3  levels,  as  in  1   level
        4,   1.1  level   5,  1.1.1  level  6,  markup  to  be  merged  within
        level] num_extract [take  numbering  of  headings  provided  (manually
        in  marked   up   source   document),   and   use   for  numbering  of
       segments.   Available   where   a   clear   numbering   structure    is
       provided  within  document,  without  the  repetition  of  a  number in
        a  header.] [In  0.38  notation,  you  would  map  to  the  equivalent
        levels,   the   examples   provided   would   map   to   the following
        new=A,B,C;   break=1;   num_top=1   [or   newpage=A,B,C;  breakpage=1;
        num_top=1] see headings]

        @bold: [regular  expression  of  words/phrases  to  be  made  bold]

        @italics: [regular  expression  of  words/phrases  to  italicise]

         @vocabulary:  name  of  taxonomy/vocabulary/wordlist  to  use against
       document

        @skin: skin_doc_[name_of_desired_document_skin] skins  change  default
       settings  related to the appearance of documents generated, such as the
       urls of the home site, and the icon/logo for the document or site.

       @man: 8;
              name=sisu  -  documents:  markup,  structuring,  publishing   in
              multiple    standard    formats,   and   search;   synopsis=sisu
              [-abcDdFHhIiMmNnopqRrSsTtUuVvwXxYyZz0-9]  [filename/wildcard   ]
              sisu   [-Ddcv]  [instruction]  sisu  [-CcFLSVvW]  the  man  page
              category number (default 1) and special tags used  in  preparing
              man page headings

                  @links:   {   SiSU   }http://www.jus.uio.no/sisu/;   {   FSF
              }http://www.fsf.org

               @promo: sisu,  ruby,  search_libre_docs,  open_society  [places
               content   in   right   pane  in  html,  makes  use  of list.yml
               and  promo.yml,  commented  out  sample  in   document  sample:
              free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst]

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}* _{underscore}_ /{italics}/

         normal text

         !{emphasis}!

         *{bold text}*

         _{underscore}_

         /{italics}/

         ^{superscript}^

         ,{subscript},

         +{inserted text}+

         -{strikethrough}-

        resulting output:

           normal    text    emphasis    bold    text    underscore    italics
       <cite>citation</cite>    ^superscript^     [subscript]    <ins>inserted
       text</ins> <del>strikethrough</del>

        normal text

        bold text

        underscore

        italics

        <cite>citation</cite>

        ^superscript^

        [subscript]

        <ins>inserted text</ins>

        <del>strikethrough</del>

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 FOOTNOTES / ENDNOTES

         Footnotes  and  endnotes  not  distinguished  in  markup.  They   are
       automatically numbered. Depending on the output file format (html, odf,
       pdf etc.), the document output selected will have either  footnotes  or
       endnotes.

        markup example:

         ~{ a footnote or endnote }~

        resulting output:

        [^11]

        markup example:

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

        resulting output:

        normal text[^12] 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.5 LINKS

9.5.1 NAKED URLS WITHIN TEXT, DEALING WITH URLS

         urls  are found within text and 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.jus.uio.no/sisu continues

        resulting output:

        normal text <http://www.jus.uio.no/sisu> continues

        An escaped url without decoration

        markup example:

         normal text http://www.jus.uio.no/sisu continues

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

        resulting output:

        normal text http://www.jus.uio.no/sisu 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

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

        markup example:

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

9.5.2 LINKING TEXT

        resulting output:

        about SiSU <http://www.jus.uio.no/sisu/> 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.jus.uio.no/sisu/> [^13] markup

9.5.3 LINKING IMAGES

        markup example:

         { tux.png 64x80 }image

         % various url linked images

         {tux.png 64x80

         {GnuDebianLinuxRubyBetterWay.png 100x101

         {~^ ruby_logo.png

        resulting output:

        [ tux.png ]

        tux.png 64x80

        [  ruby_logo  (png  missing)  ] [^14]

        GnuDebianLinuxRubyBetterWay.png 100x101 and Ruby

        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.6 GROUPED TEXT

9.6.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: [^15]

         !_ 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.6.2 POEM

        basic markup:

         poem{

           Your poem here

         }poem

         Each verse in a poem is given a separate object number.

        markup example:

         poem{

                             ´Fury said to a

                            mouse, That he

                          met in the

                        house,

                       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,

                          a trial,

                            dear Sir,

                                  With

                              no jury

                           or judge,

                         would be

                       wasting

                      our

                       breath.

                          judge, I´ll

                            be jury,

                                  Said

                             cunning

                               old Fury:

                               try the

                                  whole

                                   cause,

                                      and

                                 condemn

                                you

                               to

                                death.

         }poem

        resulting output:

                           ´Fury said to a
                          mouse, That he
                        met in the
                      house,

                     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,
                        a trial,
                          dear Sir,
                                With
                            no jury
                         or judge,
                       would be
                     wasting
                    our
                     breath.

                        judge, I´ll
                          be jury,
                                Said
                           cunning
                             old Fury:

                             try the
                                whole
                                 cause,
                                    and
                               condemn
                              you
                             to
                              death.

9.6.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,

                       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,

                          a trial,

                            dear Sir,

                                  With

                              no jury

                           or judge,

                         would be

                       wasting

                      our

                       breath.

                          judge, I´ll

                            be jury,

                                  Said

                             cunning

                               old Fury:

                               try the

                                  whole

                                   cause,

                                      and

                                 condemn

                                you

                               to

                                death.

         }group

        resulting output:

                           ´Fury said to a
                          mouse, That he
                        met in the
                      house,

                     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,
                        a trial,
                          dear Sir,
                                With
                            no jury
                         or judge,
                       would be
                     wasting
                    our
                     breath.

                        judge, I´ll
                          be jury,
                                Said
                           cunning
                             old Fury:

                             try the
                                whole
                                 cause,
                                    and
                               condemn
                              you
                             to
                              death.

9.6.4 CODE

         Code  tags 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,

                       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,

                          a trial,

                            dear Sir,

                                  With

                              no jury

                           or judge,

                         would be

                       wasting

                      our

                       breath.

                          judge, I´ll

                            be jury,

                                  Said

                             cunning

                               old Fury:

                               try the

                                  whole

                                   cause,

                                      and

                                 condemn

                                you

                               to

                                death.

9.7 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|@|^|

MARKUP SYNTAX HISTORY


11. NOTES RELATED TO FILES-TYPES AND MARKUP SYNTAX


        0.38 is substantially current, 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

         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.jus.uio.no/sisu/sisu_markup>

        <http://www.jus.uio.no/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 [^16]

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

        <http://www.jus.uio.no/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.jus.uio.no/sisu/sisu_commands>

        <http://www.jus.uio.no/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/sisu_markup_samples/dfsg/_sisu/skin/doc

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

         /usr/share/doc/sisu/sisu_markup_samples/non-free/_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/sisu_markup_samples/dfsg/_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.[^17]

17. ORGANISING CONTENT


17.1 DIRECTORY STRUCTURE AND MAPPING

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

          Some   markup   with   syntax   highlighting   may  be  found  under
       <http://www.jus.uio.no/sisu/sample/syntax> but is not as up to date.

        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[^18] and/or SQLite[^19] 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
         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 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>  [^20]  A small
       database and sample query front-end (search from) that makes use of the
       citation    system,   object   citation   numbering   to   demonstrates
       functionality.[^21]

        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,  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.[^22]

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


        See the documentation for hyperestraier:

         <http://hyperestraier.sourceforge.net/>

         /usr/share/doc/hyperestraier/index.html

         man estcmd

        on sisu_hyperestraier:

         man sisu_hyperestraier

         /usr/share/doc/sisu/sisu_markup/sisu_hyperestraier/index.html

         NOTE:  the  examples that follow assume that sisu output is placed in
       the directory /home/ralph/sisu_www

        (A) to generate  the  index  within  the  webserver  directory  to  be
       indexed:

         estcmd gather -sd [index  name] [directory  path  to  index]

         the following are examples that will need to be tailored according to
       your needs:

         cd /home/ralph/sisu_www

         estcmd gather -sd casket /home/ralph/sisu_www

        you may use the ´find´ command together with ´egrep´ to limit indexing
       to  particular  document  collection  directories within the web server
       directory:

         find /home/ralph/sisu_www -type f | egrep
         ´/home/ralph/sisu_www/sisu/.+?.html$´ |estcmd gather -sd casket -

        Check which directories in the webserver/output directory  (~/sisu_www
       or  elsewhere  depending  on  configuration) you wish to include in the
       search index.

        As sisu duplicates output in multiple file formats, it it is  probably
       preferable  to  limit  the estraier index to html output, and as it may
       also  be  desirable  to  exclude  files  ´plain.txt´,  ´toc.html´   and
       ´concordance.html´,  as  these duplicate information held in other html
       output e.g.

         find /home/ralph/sisu_www -type f | egrep
         ´/sisu_www/(sisu|bookmarks)/.+?.html$´ | egrep -v
         ´(doc|concordance).html$´ |estcmd gather -sd casket -

        from your current document  preparation/markup  directory,  you  would
       construct a rune along the following lines:

         find       /home/ralph/sisu_www       -type       f      |      egrep
       ´/home/ralph/sisu_www/([specify        first       directory        for
        inclusion]|[specify    second   directory   for    inclusion]|[another
        directory  for  inclusion?  ...])/.+?.html$´ |
         egrep -v ´(doc|concordance).html$´ |estcmd gather -sd
         /home/ralph/sisu_www/casket -

        (B) to set up the search form

        (i) copy estseek.cgi to your cgi directory and set file permissions to
       755:

         sudo cp -vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi-bin

         sudo chmod -v 755 /usr/lib/cgi-bin/estseek.cgi

         sudo cp -v /usr/share/hyperestraier/estseek.* /usr/lib/cgi-bin

         [see  estraier  documentation  for  paths]

          (ii)  edit  estseek.conf,  with  attention  to  the  lines  starting
       ´indexname:´ and ´replace:´:

         indexname: /home/ralph/sisu_www/casket

         replace: ^file:///home/ralph/sisu_www{{!}}http://localhost

         replace: /index.html?${{!}}/

        (C) to test using webrick, start webrick:

         sisu -W

        and try open the url: <http://localhost:8081/cgi-bin/estseek.cgi>

26. SISU_WEBRICK


26.1 NAME

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

26.2 SYNOPSIS

        sisu_webrick [port]

        or

        sisu -W [port]

26.3 DESCRIPTION

         sisu_webrick  is  part of SiSU (man sisu) sisu_webrick starts Ruby ´s
       Webrick web-server and points it  to  the  directories  to  which  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).

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

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

26.6 FURTHER INFORMATION

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

        or man sisu

26.7 AUTHOR

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

26.8 SEE ALSO


         sisu(1)

         sisu_vim(7)

         sisu(8)

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


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

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

28.2 CONFIGURATION

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

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

30. QUICKSTART - GETTING STARTED HOWTO


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

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

         d

        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.

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

30.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,
       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)[^23] 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>

        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

         <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

30.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/sisu_markup_samples/dfsg

30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF

        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

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

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

30.3 GETTING HELP

30.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> [^24]

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

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

30.3.2 BUILT IN HELP

        sisu --help

        sisu --help --env

        sisu --help --commands

        sisu --help --markup

30.3.3 THE HOME PAGE

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

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

30.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[^27] to include  them  it  is
       necessary  to  include  non-free in your /etc/apt/source.list or obtain
       them from the sisu home site.

31. EDITOR FILES, SYNTAX HIGHLIGHTING


        The directory:

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

         /usr/share/sisu/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

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

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

33. 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 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, 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

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

       (open document text) module in 2006 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, 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.

34. HELP SOURCES


        For a summary of alternative ways to get help on SiSU try one  of  the
       following:

        man page

         man sisu_help

        man2html

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

        sisu generated output - links to html

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

        help sources lists

        Alternative sources for this help sources page listed here:

         man sisu_help_sources

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

34.1 MAN PAGES

34.1.1 MAN


         man sisu

         man 7 sisu_complete

         man 7 sisu_pdf

         man 7 sisu_postgresql

         man 7 sisu_sqlite

         man sisu_termsheet

         man sisu_webrick

34.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, and odf which  may
       be also be accessed via the html pages[^28]

34.2.1 WWW.SISUDOC.ORG

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

34.3 MAN2HTML

34.3.1 LOCALLY INSTALLED

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

        <file:///usr/share/doc/sisu/html/sisu_help.1.html>

        <file:///usr/share/doc/sisu/html/sisu_help_sources.1.html>

         /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

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

DOCUMENT INFORMATION (METADATA)


METADATA


                         Document                  Manifest                  @
       <http://sisudoc.org/sisu_manual/sisu/sisu_manifest.html>

        Dublin Core (DC)

        DC tags included with this document are provided here.

       Title: SiSU - Manual

       Creator: Ralph Amissah

       Rights: Copyright (C) Ralph Amissah 2008, part of  SiSU  documentation,
       License GPL 3

        Type: information

        Date created: 2002-08-28

        Date issued: 2002-08-28

        Date available: 2002-08-28

        Date modified: 2008-12-16

        Date: 2008-12-16

        Version Information

        Sourcefile: sisu.ssm.sst

        Filetype: SiSU text insert 0.67

        Sourcefile Digest, MD5(sisu.ssm.sst)= 96d1e268b43e0430a2720e67a5876e5e

                        Skin_Digest:                 MD5(skin_sisu_manual.rb)=
       072b2584bedea82ea8a416587b9fa244

        Generated

        Document (metaverse) last generated: Tue Dec 16 00:16:50 -0500 2008

        Generated by: SiSU 0.70.2 of 2008w50/2 (2008-12-16)

        Ruby version: ruby 1.8.7 (2008-08-11 patchlevel 72)  [i486-linux]

       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, 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/IEC 26300:2006

       *1.    square brackets

       *2.    square brackets

       +1.    square brackets

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

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

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

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

       11.    a footnote or endnote

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

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

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

       15.    Table  from  the  Wealth   of   Networks   by   Yochai   Benkler
              <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>

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

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

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

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

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

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

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

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

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

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

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

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

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

       Other versions of this document:

       manifest: <http://www.jus.uio.no/sisu/sisu/sisu_manifest.html>

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

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

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

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

       * Generated by: SiSU 0.70.2 of 2008w50/2 (2008-12-16)

       *  Ruby  version:  ruby   1.8.7   (2008-08-11   patchlevel   72)
       [i486-linux]

       * Last Generated on: Tue Dec 16 00:16:50 -0500 2008

       * SiSU http://www.jus.uio.no/sisu