primarily todo with sisu documentation, changelog reproduced below:

* start documenting sisu using sisu
  * sisu markup source files in
    data/doc/sisu/sisu_markup_samples/sisu_manual/
    /usr/share/doc/sisu/sisu_markup_samples/sisu_manual/
  * default output [sisu -3] in
    data/doc/manuals_generated/sisu_manual/
    /usr/share/doc/manuals_generated/sisu_manual/
    (adds substantially to the size of sisu package!)

* help related edits

* manpage, work on ability to generate manpages, improved

* param, exclude footnote mark count when occurs within code block

* plaintext changes made

* shared_txt, line wrap visited

* file:// link option introduced (in addition to existing https?:// and
  ftp://) a bit arbitrarily, diff here, [double check changes in sysenv and
  hub]

* minor adjustments
  * html url match refinement
  * css added tiny_center

* plaintext
  * endnotes fix
  * footnote adjustment to make more easily distinguishable from substantive
    text
  * flag -a only [flags -A -e -E dropped]
    controlled by modifiers --unix/msdos --footnote/endnote

* defaults, homepage
  * renamed homepage (instead of index) implications for modifying skins,
    which need likewise to have any homepage entry renamed
  * added link to sisu_manual in homepage

* css the css for the default homepage is renamed homepage.css (instead of
  index.css) [consider removing this and relying on html.css]

* ruby version < ruby1.9
  * place stop on installation and working with for now [ruby String.strip
    broken in ruby 1.9.0 (2007-09-10 patchlevel 0) [i486-linux],
    2007-09-18:38/2]
  * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9

* debian
  * debian/control restrict use to ruby > 1.8.4 and ruby < 1.9
  * sisu-doc new sub-package for sisu documentation
    debian/control and sisu-doc.install

1 files changed, 2283 insertions, 0 deletions

diff --git a/man/man8/sisu_howto.8 b/man/man8/sisu_howto.8
new file mode 100644
index 00000000..42bd1caf
--- /dev/null
+++ b/man/man8/sisu_howto.8
@@ -0,0 +1,2283 @@
+.TH "sisu_howto" "1" "2007-09-16" "0.58.3" "SiSU - SiSU information Structuring Universe / Structured information, Serialized Units"
+.SH
+SISU \- SISU INFORMATION STRUCTURING UNIVERSE / STRUCTURED INFORMATION,
+SERIALIZED UNITS \- TECHNICAL, HOWTO,
+RALPH AMISSAH
+.BR
+
+.SH
+SISU SOME TECHNICAL INFORMATION
+.BR
+
+.SH
+HOWTO
+.BR
+
+.SH
+1. GETTING HELP
+.BR
+
+.BR
+An online manual of sorts should be available at:
+
+.BR
+<http://www.jus.uio.no/sisu_manual/>
+
+.BR
+The manual pages provided with
+.B SiSU
+are also available online, and there is an interactive help, which is being
+superseded by the man page, and possibly some document which contains this
+component.
+
+.SH
+1.1 SISU \"MAN\" PAGES
+
+.BR
+If
+.B SiSU
+is installed on your system usual man commands should be available, try:
+
+.BR
+man sisu
+
+.BR
+The
+.B SiSU
+man pages can be viewed online at:[^1]
+
+.BR
+An online version of the sisu man page is available here:
+
+.BR
+* various sisu man pages <http://www.jus.uio.no/sisu/man/> \ [^2]
+
+.BR
+* sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> \ [^3]
+
+.BR
+* sisu.8 <http://www.jus.uio.no/sisu/man/sisu.8.html> \ [^4]
+
+.BR
+* sisu_examples.1 <http://www.jus.uio.no/sisu/man/sisu_examples.1.html> \ [^5]
+
+.BR
+* sisu_webrick.1 <http://www.jus.uio.no/sisu/man/sisu_webrick.1.html> \ [^6]
+
+.SH
+1.2 SISU BUILT\-IN HELP
+
+.BR
+  sisu \-\-help
+
+.BR
+  sisu \-\-help \ [subject]
+
+.BR
+    sisu \-\-help env \ [for \ feedback \ on \ the \ way \ your \ system \ is \
+    setup \ with \ regard \ to \ sisu]
+
+.BR
+    sisu \-V \ [same \ as \ above \ command]
+
+.BR
+    sisu \-\-help commands
+
+.BR
+    sisu \-\-help markup
+
+.SH
+1.3 COMMAND LINE WITH FLAGS \- BATCH PROCESSING
+
+.BR
+Running sisu (alone without any flags, filenames or wildcards) brings up the
+interactive help, as does any sisu command that is not recognised.
+
+.BR
+In the data directory run sisu \-mh filename or wildcard eg. \"sisu \-h
+cisg.sst\" or \"sisu \-h *.{sst,ssm}\" to produce html version of all
+documents.
+
+.SH
+2. SETUP, INITIALISATION
+.BR
+
+.SH
+2.1 INITIALISE OUTPUT DIRECTORY
+
+.BR
+Images, css files for a document directory are copied to their respective
+locations in the output directory.
+
+.BR
+while within your document markup/preparation directory, issue the following
+command
+
+.BR
+  sisu \-CC
+
+.SH
+2.1.1 USE OF SEARCH FUNCTIONALITY, AN EXAMPLE USING SQLITE
+
+.BR
+.B SiSU
+can populate PostgreSQL and Sqlite databases and provides a sample search
+form for querying these databases.
+
+.BR
+This note provides an example to get you started and will use sqlite
+
+.BR
+It is necessary to:
+
+.BR
+(1) make sure the required dependencies have been installed
+
+.BR
+(2) have a directory with sisu markup samples that is writable
+
+.BR
+(3) use sisu to create a database
+
+.BR
+(4) use sisu tp populate a database
+
+.BR
+(5) use sisu to start the webrick (httpd) server
+
+.BR
+(6) use sisu to create a search form
+
+.BR
+(7) copy the search form to the cgi directory
+
+.BR
+(8) open up the form in your browser
+
+.BR
+(9) query the database using the search form
+
+.BR
+.B (1) make sure the required dependencies have been installed
+
+.BR
+if you use
+.B Debian
+, the following command will install the required dependencies
+
+.BR
+aptitude install sisu\-sqlite
+
+.BR
+.B (2) have a directory with sisu markup samples that is writable
+
+.BR
+ideally copy the sisu\-examples directory to your home directory (because the
+directory in which you run this example should be writable)
+
+.BR
+cp \-rv /usr/share/sisu\-examples/sample/document_samples_sisu_markup ~/.
+
+.BR
+.B (3) use sisu to create an sqlite database
+
+.BR
+within the sisu\-examples directory
+
+.BR
+sisu \-dv createall
+
+.BR
+.B (4) use sisu tp populate a database with some text
+
+.BR
+within the sisu\-examples directory
+
+.BR
+sisu \-div free_*.sst
+
+.BR
+or
+
+.BR
+sisu \-dv import free_*.sst debian_constitution_v1.2.sst
+debian_social_contract_v1.1.sst gpl2.fsf.sst
+
+.BR
+.B (5) use sisu to start the webrick (httpd) server (if it has not already
+been started):
+
+.BR
+sisu \-W
+
+.BR
+.B (6) use sisu to create a search form (for use with the webrick server, and
+your sample documents)
+
+.BR
+within the sisu\-examples directory
+
+.BR
+sisu \-F webrick
+
+.BR
+#here i run into a problem, you are working from a read only #directory..., not
+my usual mode of operation, to complete the example #the following is necessary
+sudo touch sisu_sqlite.cgi sisu_pgsql.cgi sudo \-P chown $USER sisu_sqlite.cgi
+sisu_pgsql.cgi
+
+.BR
+#now this should be possible: sisu \-F webrick
+
+.BR
+.B (7) copy the search form to the cgi directory
+
+.BR
+the string should be provided as output from the previous command
+
+.BR
+sudo cp \-vi
+/usr/share/sisu\-examples/sample/document_samples_sisu_markup/sisu_sqlite.cgi
+/usr/lib/cgi\-bin
+
+.BR
+sudo chmod \-v 755 /usr/lib/cgi\-bin/sisu_sqlite.cgi
+
+.BR
+.B (8) open up the form in your browser and query it
+
+.BR
+url:
+
+.BR
+<http://localhost:8081/cgi\-bin/sisu_sqlite.cgi>
+
+.BR
+or as instructed by command sisu \-F webrick
+
+.BR
+.B (9) query the database using the search form
+
+.BR
+if there are other options in the dropdown menu select
+
+.BR
+document_samples_sisu_markup
+
+.BR
+and search for some text, e.g.:
+
+.BR
+aim OR project
+
+.BR
+* selecting the
+.B index
+radio button gives an index of results using the object numbers
+
+.BR
+* selecting the
+.B text
+radio button gives the content of the matched paragraphs with the match
+highlighted
+
+.BR
+.B (10) to start again with a new database
+
+.BR
+to start from scratch you can drop the database with the command
+
+.BR
+sisu \-dv dropall
+
+.BR
+and go to step 3
+
+.BR
+to get to step 3 in one step with a single command
+
+.BR
+sisu \-dv recreate
+
+.BR
+continue subsequent steps
+
+.SH
+2.2 MISC
+
+.SH
+2.2.1 URL FOR OUTPUT FILES \-U \-U
+
+.BR
+  sisu \-uv[and \ other \ flags] \ [filename/wildcard]
+
+.BR
+  sisu \-Uv \ [filename/wildcard]
+
+.SH
+2.2.2 TOGGLE SCREEN COLOR
+
+.BR
+  sisu \-cv[and \ processing \ flags] \ [filename/wildcard]
+
+.SH
+2.2.3 VERBOSE MODE
+
+.BR
+  sisu \-v[and \ processing \ flags] \ [filename/wildcard]
+
+.BR
+  sisu \-V[and \ processing \ flags] \ [filename/wildcard]
+
+.SH
+2.2.4 QUIET MODE
+
+.BR
+  sisu \-q[and \ processing \ flags] \ [filename/wildcard]
+
+.SH
+2.2.5 MAINTENANCE MODE INTERMEDIATE FILES KEPT \-M
+
+.BR
+  sisu \-Mv[and \ other \ flags] \ [filename/wildcard]
+
+.SH
+2.2.6 START THE WEBRICK SERVER
+
+.BR
+  sisu \-W
+
+.SH
+2.3 REMOTE PLACEMENT OF OUTPUT
+
+.BR
+configuration is necessary
+
+.BR
+scp
+
+.BR
+  sisu \-vr[and \ processing \ flags] \ [filename/wildcard]
+
+.BR
+rsync
+
+.BR
+  sisu \-vR[and \ processing \ flags] \ [filename/wildcard]
+
+.SH
+3. CONFIGURATION FILES
+.BR
+
+.BR
+Sample provided, on untarring the source tarball:
+
+.BR
+  conf/sisu/sisurc.yaml
+
+.BR
+and on installation under:
+
+.BR
+  /etc/sisu/sisurc.yaml
+
+.BR
+The following paths are searched:
+
+.BR
+  ./_sisu/sisurc.yaml
+
+.BR
+  ~/.sisu/sisurc.yaml
+
+.BR
+  ./etc/sisu/sisurc.yaml
+
+.SH
+4. MARKUP
+.BR
+
+.BR
+See sample markup provided on
+
+.BR
+<http://www.jus.uio.no/sisu>
+
+.BR
+<http://www.jus.uio.no/sisu_markup>
+
+.BR
+<http://www.jus.uio.no/sisu/SiSU>
+
+.BR
+in particular for each of the document output samples provided, the source
+document is provided as well
+
+.BR
+<http://www.jus.uio.no/sisu/SiSU/2#books>
+
+.BR
+on untarring the source tarball:
+
+.BR
+  data/sisu\-examples/sample/document_samples_sisu_markup/
+
+.BR
+or the same once source is installed (or sisu\-examples) under:
+
+.BR
+  /usr/share/sisu\-examples/sample/document_samples_sisu_markup/
+
+.BR
+Some notes are contained within the man page,
+.B man sisu
+and within sisu help via the commands
+.B sisu help markup
+and
+.B sisu help headers
+
+.BR
+.B SiSU
+is for literary and legal text, also for some social science material. In
+particular it does not do formula, and is not particularly suited to technical
+documentation. Despite the latter caveat, some notes will be provided here and
+added to over time:
+
+.SH
+4.1 HEADERS
+
+.BR
+Headers @headername: provide information related to the document, this may
+relate to
+
+.BR
+1. how it is to be processed, such as whether headings are to be numbered, what
+skin is to be used and markup instructions, such as the document structure, or
+words to be made bold within the document
+
+.BR
+2. semantic information about the document including the dublin core
+
+.SH
+4.2 FONT FACE
+
+.BR
+Defaults are set. You may change the face to: bold, italics, underscore,
+strikethrough, ...
+
+.SH
+4.2.1 BOLD
+
+.BR
+\@bold: \ [list \ of \ words \ that \ should \ be \ made \ bold \ within \
+document]
+
+.BR
+.B bold line
+
+.BR
+!_ bold line
+
+.BR
+.B bold word or sentence
+
+.BR
+!{ bold word or sentence }!
+
+.BR
+*{ bold word or sentence }*
+
+.BR
+.B boldword
+or
+.B boldword
+
+.BR
+*boldword* or !boldword!
+
+.SH
+4.2.2 ITALICS
+
+.BR
+\@italics: \ [list \ of \ words \ that \ should \ be \ italicised \ within \
+document]
+
+.BR
+.I italicise word or sentence
+
+.BR
+/{ italicise word or sentence }/
+
+.BR
+.I italicisedword
+
+.BR
+/italicisedword/
+
+.SH
+4.2.3 UNDERSCORE
+
+.BR
+.I underscore word or sentence
+
+.BR
+_{ underscore word or sentence }_
+
+.BR
+.I underscoreword
+
+.SH
+4.2.4 STRIKETHROUGH
+
+.BR
+<del> strikethrough word or sentence </del>
+
+.BR
+\-{ strikethrough word or sentence }\-
+
+.BR
+<del>strikeword</del>
+
+.BR
+\-strikeword\-
+
+.SH
+4.3 ENDNOTES
+
+.BR
+There are two forms of markup for endnotes, they cannot be mixed within the
+same document
+
+.BR
+here[^7]
+
+.BR
+1. preferred endnote markup
+
+.BR
+here~{ this is an endnote }~
+
+.BR
+2. alternative markup equivalent, kept because it is possible to search and
+replace to get markup in existing texts such as Project Gutenberg
+
+.BR
+here~^
+
+.BR
+^~ this is an endote
+
+.SH
+4.4 LINKS
+
+.BR
+SiSU <http://sisudoc.org>
+
+.BR
+{
+.B SiSU
+}http://sisudoc.org
+
+.BR
+sisu.png 120x39 <http://sisudoc.org>
+
+.BR
+{sisu.png }http://sisudoc.org
+
+.BR
+[ tux.png ]
+
+.BR
+{ tux.png 64x80 }image
+
+.BR
+SiSU <http://sisudoc.org> \ [^8]
+
+.BR
+{
+.B SiSU
+}http://sisudoc.org
+
+.BR
+is equivalent to:
+
+.BR
+{
+.B SiSU
+}http://sisudoc.org ~{ <http://sisudoc.org> }~
+
+.BR
+the same can be done with an image:
+
+.BR
+sisu.png 120x39 \"SiSU\" <http://sisudoc.org> \ [^10]
+
+.BR
+{ sisu.png \"
+.B SiSU
+\" }http://sisudoc.org
+
+.SH
+4.5 NUMBER TITLES
+
+.BR
+Set with the header @markup:
+
+.SH
+4.6 LINE OPERATIONS
+
+.BR
+Line Operations (marker placed at start of line)
+
+.BR
+!_ bold line
+
+.BR
+.B bold line
+
+.BR
+_1 indent paragraph one level
+
+.BR
+  indent paragraph one level
+
+.BR
+_2 indent paragraph two steps
+
+.BR
+    indent paragraph two steps
+
+.BR
+_* bullet paragraph
+
+.BR
+* bullet paragraph
+
+.BR
+# number paragraph (see headers for numbering document headings)
+
+.BR
+1. number paragraph (see headers for numbering document headings)
+
+.BR
+_# number paragraph level 2 (see headers for numbering document headings)
+
+.BR
+  a. number paragraph level 2 (see headers for numbering document headings)
+
+.SH
+4.7 TABLES
+
+.BR
+Table markup sample
+
+
+table{~h c3; 26; 32; 32;
+.P
+
+
+This is a table, column1
+.P
+this would become row one of column two
+.P
+column three of row one is here
+.P
+
+
+column one row 2
+.P
+column two of row two
+.P
+column three of row two, and so on
+.P
+
+
+column one row three
+.P
+and so on
+.P
+here
+.P
+
+
+}table
+.P
+
+.BR
+Alternative form of table markup
+
+
+.nf
+  {t\~h}
+       |Mon|Tue|Wed|Thu|Fri|Sat|Sun
+  0    | * | * | * | * | * | * | *
+  1    | * | * | * | * |   |   |
+  2    | \- | * | * | * | * | * |
+  3    | \- | * | * | * | * | * | *
+  4    | \- |   |   | * | * | * |
+  5    | * | * | * | * | * | * | *
+.fi
+
+.SH
+4.8 GROUPED TEXT
+
+
+.nf
+    5.times { puts \'Ruby\' }
+.fi
+
+.BR
+code{
+
+
+.nf
+    5.times { puts \'Ruby\' }
+.fi
+
+.BR
+}code
+
+
+A Limerick
+.P
+
+
+There was a young lady from Clyde,
+.P
+who ate a green apple and died,
+.P
+but the apple fermented inside the lamented,
+.P
+and made cider inside her inside.
+.P
+
+
+poem{
+.P
+
+
+There was a young lady from Clyde,
+.P
+who ate a green apple and died,
+.P
+but the apple fermented inside the lamented,
+.P
+and made cider inside her inside.
+.P
+
+
+}\poem
+.P
+
+.SH
+4.9 COMPOSITE DOCUMENT
+
+.BR
+To import another document, the master document or importing document should be
+named filename.r3 (r for require)
+
+.BR
+&lt;&lt; { filename.sst }
+
+.BR
+&lt;&lt; { filename.ssi }
+
+.SH
+5. CHANGE APPEARANCE
+.BR
+
+.SH
+5.1 SKINS
+
+.BR
+\"Skins\" may be used to change various aspects related to the output documents
+appearance, including such things as the url for the home page on which the
+material will be published, information on the credit band, and for html
+documents colours and icons used in navigation bars. Skins are ruby files which
+permit changing of the default values set within the program for
+.B SiSU
+output.
+
+.BR
+There are a few examples provided, on untarring the source tarball:
+
+.BR
+  conf/sisu/skin/doc/
+
+.BR
+  data/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc
+
+.BR
+and on installation under:
+
+.BR
+  /etc/sisu/skin/doc/
+
+.BR
+  /usr/share/sisu\-examples/sample/document_samples_sisu_markup/_sisu/skin/doc
+
+.BR
+The following paths are searched:
+
+.BR
+  ./_sisu/skin
+
+.BR
+  ~/.sisu/skin
+
+.BR
+  /etc/sisu/skin
+
+.BR
+Skins under the searched paths in a per document directory, a per directory
+directory, or a site directory, named:
+
+.BR
+doc \ [may \ be \ specified \ individually \ in \ each \ document]
+
+.BR
+dir \ [used \ if \ identifier \ part \ of \ name \ matches \ markup \ directory
+\ name]
+
+.BR
+site
+
+.BR
+It is usual to place all skins in the document directory, with symbolic links
+as required from dir or site directories.
+
+.SH
+5.2 CSS
+
+.BR
+The appearance of html and XML related output can be changed for an ouput
+collection directory by prepareing and placing a new css file in one of the
+sisu css directories searched in the sisu configuration path. These are located
+at:
+
+.BR
+_./_sisu/css
+
+.BR
+~/.sisu/css
+
+.BR
+and
+
+.BR
+/etc/sisu/css
+
+.BR
+The contents of the first directory found in the search path are copied to the
+corresponding sisu output directory with the commnd:
+
+.BR
+sisu \-CC
+
+.BR
+The
+.B SiSU
+standard css files for
+.B SiSU
+output are:
+
+.BR
+dom.css html.css html_tables.css index.css sax.css xhtml.css
+
+.BR
+A document may specify its own/bespoke css file using the css header.
+
+.BR
+\@css:
+
+.BR
+[expand]
+
+.SH
+EXTRACTS FROM THE README
+.BR
+
+.SH
+6. README
+.BR
+
+.BR
+.B SiSU
+0.55 2007w27/6 2007\-07\-07
+
+.BR
+Homepage: <http://www.jus.uio.no/sisu>
+
+.BR
+.B Description
+
+.BR
+.B SiSU
+is lightweight markup based document creation and publishing framework that
+is controlled from the command line. Prepare documents for
+.B SiSU
+using your text editor of choice, then use
+.B SiSU
+to generate various output document formats.
+
+.BR
+With minimal preparation of a plain\-text (UTF\-8) file using its native
+markup\-syntax,
+.B SiSU
+produces: plain\-text, HTML, XHTML, XML, ODF:ODT (Opendocument), LaTeX, PDF,
+and populates an SQL database (PostgreSQL or SQLite) in paragraph sized chunks
+so that document searches are done at this \"atomic\" level of granularity.
+
+.BR
+Outputs share a common citation numbering system, and any semantic meta\-data
+provided about the document.
+
+.BR
+.B SiSU
+also provides concordance files, document content certificates and manifests
+of generated output.
+
+.BR
+.B SiSU
+takes advantage of well established open standard ways of representing text,
+and provides a bridge to take advantage of the strengths of each, while
+remaining simple.
+.B SiSU
+implements across document formats a \"useful common feature set\" \ [coming
+\ from \ a \ humanities, \ law, \ and \ possibly \ social \ sciences \
+perspective, \ rather \ than \ technical \ or \ scientific \ writing] ... focus
+is primarily on content and data integrity rather than appearance, (though
+outputs in the various formats are respectable).
+
+.BR
+A vim syntax highlighting file and an ftplugin with folds for sisu markup is
+provided. Vim 7 includes syntax highlighting for
+.B SiSU
+.
+
+.BR
+man pages, and interactive help are provided.
+
+.BR
+Dependencies for various features are taken care of in sisu related packages.
+The package sisu\-complete installs the whole of
+.B SiSU
+.
+
+.BR
+Additional document markup samples are provided in the package
+sisu\-markup\-samples which is found in the non\-free archive the licenses for
+the substantive content of the marked up documents provided is that provided by
+the author or original publisher.
+
+.BR
+Homepage: <http://www.jus.uio.no/sisu>
+
+.BR
+.B SiSU
+\- simple information structuring universe, is a publishing tool, document
+generation and management, (and search enabling) tool primarily for literary,
+academic and legal published works.
+
+.BR
+.B SiSU
+can be used for Internet, Intranet, local filesystem or cd publishing.
+
+.BR
+.B SiSU
+can be used directly off the filesystem, or from a database.
+
+.BR
+.B SiSU
+\'s scalability, is be dependent on your hardware, and filesystem (in my case
+Reiserfs), and/or database Postgresql.
+
+.BR
+Amongst it\'s characteristics are:
+
+.BR
+* simple mnemonoic markup style,
+
+.BR
+* the ability to produce multiple output formats, including html, structured
+XML, LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining
+document structure \- Postgresql and Sqlite,
+
+.BR
+* that all share a common citation system (a simple idea from which much good),
+possibly most exciting, the following: if fed into a relational database (as it
+can be automatically), the document set is searchable, with results displayed
+at a paragraph level, or the possibility of an indexed display of documents in
+which the match is found together with a hyperlinked listing for each of each
+paragraph in which the match is found. In any event citations using this system
+(with or without the relational database) are relevant for all output formats.
+
+.BR
+* it is command line driven, and can be set up on a remote server
+
+.BR
+* Documents are marked up in
+.B SiSU
+syntax in your favourite editor.
+.B SiSU
+syntax may be regarded as a type of smart ascii \- which in its basic form is
+simpler than the most elementary html. There is currently a syntax highlighter,
+and folding for Vim. Syntax highlighters for other editors are welcome.
+
+.BR
+Input files should be UTF\-8
+
+.BR
+Once set up it is simple to use.
+
+.SH
+6.1 ONLINE INFORMATION, PLACES TO LOOK
+
+.BR
+<http://www.jus.uio.no/sisu>
+
+.BR
+Download Sources:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#current>
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
+
+.SH
+6.2 INSTALLATION
+
+.BR
+NB. Platform is Unix / Linux.
+
+.SH
+6.2.1 DEBIAN
+
+.BR
+If you use
+.B Debian
+use the
+.B Debian
+packages, check the information at:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
+
+.BR
+(A)
+.B SiSU
+is available directly off the
+.B Debian
+archives for Sid and testing. It should necessary only to run as root:
+
+.BR
+  aptitude update
+
+.BR
+  aptitude install sisu\-complete
+
+.BR
+(B) If there are newer versions of
+.B SiSU
+upstream of the
+.B Debian
+archives, they will be available by adding the following to your
+/etc/apt/sources.list
+
+.BR
+  deb <http://www.jus.uio.no/sisu/archive> unstable main non\-free
+
+.BR
+  deb\-src <http://www.jus.uio.no/sisu/archive> unstable main non\-free
+
+.BR
+[the \ non\-free \ line \ is \ for \ document \ markup \ samples, \ for \ which
+\ the \ substantive \ text \ is \ provided \ under \ the \ author \ or \
+original \ publisher\'s \ license \ and \ which \ in \ most \ cases \ will \
+not \ be \ debian \ free \ software \ guideline \ compliant]
+
+.BR
+Then as root run:
+
+.BR
+  aptitude update
+
+.BR
+  aptitude install sisu\-complete
+
+.SH
+6.2.2 RPM
+
+.BR
+RPMs are provided though untested, they are prepared by running alien against
+the source package, and against the debs.
+
+.BR
+They may be downloaded from:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>
+
+.SH
+6.2.3 SOURCE PACKAGE .TGZ
+
+.BR
+Otherwise to install
+.B SiSU
+from source, check information at:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#current>
+
+.BR
+alternative modes of installation from source are provided, setup.rb (by Minero
+Aoki), rake (by Jim Weirich) built install file, rant (by Stefan Lang) built
+install file,
+
+.BR
+.B Ruby
+is the essential dependency for the basic operation of
+.B SiSU
+
+.BR
+1. Download the latest source (information available) from:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#current>
+
+.BR
+2. Unpack the source
+
+.BR
+Note however, that additional external package dependencies, such as texlive or
+postgresql should you desire to use it are not taken care of for you.
+
+.SH
+6.2.4 TO USE SETUP.RB
+
+.BR
+this is a three step process, in the root directory of the unpacked
+.B SiSU
+as root type:
+
+.BR
+  ruby setup.rb config
+
+.BR
+  ruby setup.rb setup
+
+.BR
+as root:
+
+.BR
+  ruby setup.rb install
+
+.BR
+further information:
+
+.BR
+  <http://i.loveruby.net/en/projects/setup/>
+
+.BR
+  <http://i.loveruby.net/en/projects/setup/doc/usage.html>
+
+.SH
+6.2.5 TO USE INSTALL (PRAPARED WITH \"RAKE\")
+
+.BR
+Rake must be installed on your system:
+
+.BR
+  <http://rake.rubyforge.org/>
+
+.BR
+  <http://rubyforge.org/frs/?group_id=50>
+
+.BR
+in the root directory of the unpacked
+.B SiSU
+as root type:
+
+.BR
+  rake
+
+.BR
+or
+
+.BR
+  rake base
+
+.BR
+This makes use of Rake (by Jim Weirich) and the provided Rakefile
+
+.BR
+For a list of alternative actions you may type:
+
+.BR
+  rake help
+
+.BR
+  rake \-T
+
+.SH
+6.2.6 TO USE INSTALL (PRAPARED WITH \"RANT\")
+
+.BR
+(you may use the instructions above for rake substituting rant if rant is
+installed on your system, or you may use an independent installer created using
+rant as follows:)
+
+.BR
+in the root directory of the unpacked
+.B SiSU
+as root type:
+
+.BR
+  ruby ./sisu\-install
+
+.BR
+or
+
+.BR
+  ruby ./sisu\-install base
+
+.BR
+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.
+
+.BR
+further information:
+
+.BR
+  <http://make.rubyforge.org/>
+
+.BR
+  <http://rubyforge.org/frs/?group_id=615>
+
+.BR
+For a list of alternative actions you may type:
+
+.BR
+  ruby ./sisu\-install help
+
+.BR
+  ruby ./sisu\-install \-T
+
+.SH
+6.3 DEPENDENCIES
+
+.BR
+Once installed see \'man 8 sisu\' for some information on additional programs
+that sisu makes use of, and that you may need or wish to install. (this will
+depend on such factors as whether you want to generate pdf, whether you will be
+using
+.B SiSU
+with or without a database, ...) \'man sisu_markup\-samples\' may also be of
+interest if the sisu\-markup\-samples package has also been installed.
+
+.BR
+The information in man 8 may not be most up to date, and it is possible that
+more useful information can be gleaned from the following notes taken from the
+.B Debian
+control file (end edited), gives an idea of additional packages that
+.B SiSU
+can make use of if available, (the use/requirement of some of which are
+interdependent for specific actions by
+.B SiSU
+).
+
+.BR
+The following is from the debian/control file of sisu\-0.58.2, which amongst
+other things provides the dependencies of sisu within
+.B Debian
+.
+
+
+.nf
+  Package: sisu
+  Architecture: all
+  Depends: ruby (>= 1.8.2), libwebrick\-ruby, unzip, zip
+  Conflicts: vim\-sisu, sisu\-vim, sisu\-remote
+  Replaces: vim\-sisu, sisu\-vim
+  Recommends: sisu\-pdf, sisu\-sqlite, sisu\-postgresql, librmagick\-ruby, trang,
+  tidy, librexml\-ruby, openssl, rsync, openssh\-client | lsh\-client, keychain,
+  hyperestraier, kdissert, vim\-addon\-manager
+  Suggests: rcs | cvs, lv, texinfo, pinfo
+  Package: sisu\-complete
+  Depends: ruby (>= 1.8.4), sisu, sisu\-pdf, sisu\-postgresql, sisu\-sqlite
+  Recommends: hyperestraier
+  Package: sisu\-pdf
+  Architecture: all
+  Depends: sisu, texlive\-latex\-base, texlive\-fonts\-recommended,
+  texlive\-latex\-recommended, texlive\-latex\-extra
+  Suggests: evince, xpdf
+  Package: sisu\-postgresql
+  Depends: sisu, postgresql\-8.1, libdbi\-ruby, libdbm\-ruby, libdbd\-pg\-ruby
+  Suggests: pgaccess, libdbd\-pgsql, postgresql\-contrib\-8.1
+  Package: sisu\-sqlite
+  Depends: sisu, sqlite, libdbi\-ruby, libdbm\-ruby, libdbd\-sqlite\-ruby
+  Suggests: libdbd\-sqlite
+  Package: sisu\-markup\-samples
+  Depends: sisu
+.fi
+
+
+.nf
+  Source: sisu
+  Section: text
+  Priority: optional
+  Maintainer: Ralph Amissah <ralph@amissah.com>
+  Build\-Depends: debhelper (>= 5)
+  Standards\-Version: 3.7.2
+  Package: sisu
+  Architecture: all
+  Depends: ruby (>= 1.8.2), libwebrick\-ruby, unzip, zip
+  Conflicts: vim\-sisu, sisu\-vim, sisu\-remote
+  Replaces: vim\-sisu, sisu\-vim
+  Recommends: sisu\-pdf, sisu\-sqlite, sisu\-postgresql, hyperestraier, keychain, librmagick\-ruby, librexml\-ruby, openssl, openssh\-client | lsh\-client, rsync, tidy, vim\-addon\-manager
+  Suggests: kdissert, lv, rcs | cvs, pinfo, texinfo, trang
+  Description: documents \- structuring, publishing in multiple formats and search
+   SiSU is a lightweight markup based, command line oriented, document
+   structuring, publishing and search framework for document collections.
+   .
+   With minimal preparation of a plain\-text, (UTF\-8) file, using its native
+   markup syntax in your text editor of choice, SiSU can generate various
+   document formats (most of which share a common object numbering system for
+   locating content), including plain text, HTML, XHTML, XML, OpenDocument text
+   (ODF:ODT), LaTeX, PDF files, and populate an SQL database with objects
+   (roughly paragraph\-sized chunks) so searches may be performed and matches
+   returned with that degree of granularity: your search criteria is met by these
+   documents and at these locations within each document. Object numbering is
+   particularly suitable for \"published\" works (finalized texts as opposed to
+   works that are frequently changed or updated) for which it provides a fixed
+   means of reference of content. Document outputs also share semantic meta\-data
+   provided.
+   .
+   SiSU also provides concordance files, document content certificates and
+   manifests of generated output.
+   .
+   A vim syntax highlighting file and an ftplugin with folds for sisu markup is
+   provided, as are syntax highlighting files for kate, kwrite, gedit and
+   diakonos. Vim 7 includes syntax highlighting for SiSU.
+   .
+   man pages, and interactive help are provided.
+   .
+   Dependencies for various features are taken care of in sisu related packages.
+   The package sisu\-complete installs the whole of SiSU.
+   .
+   Additional document markup samples are provided in the package
+   sisu\-markup\-samples which is found in the non\-free archive the licenses for
+   the substantive content of the marked up documents provided is that provided
+   by the author or original publisher.
+   .
+    Homepage: <http://www.jus.uio.no/sisu>
+.fi
+
+
+.nf
+  Package: sisu\-complete
+  Architecture: all
+  Depends: ruby (>= 1.8.2), sisu, sisu\-pdf, sisu\-postgresql, sisu\-sqlite
+  Recommends: hyperestraier
+  Description: installs all SiSU related packages
+   This package installs SiSU and related packages that enable sisu to produce
+   pdf and to populate postgresql and sqlite databases.
+   .
+   SiSU is a lightweight markup based document publishing framework.
+   .
+   See sisu for a description of the package.
+   .
+    Homepage: <http://www.jus.uio.no/sisu>
+.fi
+
+
+.nf
+  Package: sisu\-pdf
+  Architecture: all
+  Depends: sisu, texlive\-latex\-base, texlive\-fonts\-recommended, texlive\-latex\-recommended, texlive\-latex\-extra
+  #Suggests: evince, xpdf
+  Description: dependencies to convert SiSU LaTeX output to pdf
+   This package enables the conversion of SiSU LaTeX output to pdf.
+   .
+   SiSU is a lightweight markup based document publishing framework.
+   .
+    Homepage: <http://www.jus.uio.no/sisu>
+.fi
+
+
+.nf
+  Package: sisu\-postgresql
+  Architecture: all
+  Depends: sisu, libdbd\-pg\-ruby, libdbi\-ruby, libdbm\-ruby, postgresql
+  Recommends: libfcgi\-ruby
+  Suggests: postgresql\-contrib
+  Description: SiSU dependencies for use with postgresql database
+   This package enables SiSU to populate a postgresql database. This is done at
+   an object/paragraph level, making granular searches of documents possible.
+   .
+   This relational database feature of SiSU is not required but provides
+   interesting possibilities, including that of granular searches of documents
+   for matching units of text, primarily paragraphs that can be displayed or
+   identified by object citation number, from which an index of documents
+   matched and each matched paragraph within them can be displayed.
+   .
+   SiSU is a lightweight markup based document publishing framework.
+   .
+    Homepage: <http://www.jus.uio.no/sisu>
+.fi
+
+
+.nf
+  Package: sisu\-sqlite
+  Architecture: all
+  Depends: sisu, sqlite, libdbd\-sqlite\-ruby, libdbi\-ruby, libdbm\-ruby
+  Recommends: libfcgi\-ruby
+  Description: SiSU dependencies for use with sqlite database
+   This package enables SiSU to populate an sqlite database. This is done at an
+   object/paragraph level, making granular searches of documents possible.
+   .
+   This relational database feature of SiSU is not required but provides
+   interesting possibilities, including that of granular searches of documents
+   for matching units of text, primarily paragraphs that can be displayed or
+   identified by object citation number, from which an index of documents
+   matched and each matched paragraph within them can be displayed.
+   .
+   SiSU is a lightweight markup based document publishing framework.
+   .
+    Homepage: <http://www.jus.uio.no/sisu>
+.fi
+
+.SH
+6.4 QUICK START
+
+.BR
+Most of the installation should be taken care of by the aptitude or rant
+install. (The rant install if run in full will also test run the generation of
+the first document).
+
+.BR
+After installation of sisu\-complete, move to the document samples directory
+
+.BR
+  cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
+
+.BR
+and run
+
+.BR
+  sisu \-3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+or the same:
+
+.BR
+  sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+look at output results, see the \"sisu_manifest\" page created for the document
+
+.BR
+or to generate an online document move to a writable directory, as the file
+will be downloaded there and e.g.
+
+.BR
+sisu \-3
+<http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst>
+
+.BR
+the database stuff is extra perhaps, the latex stuff could be considered extra
+perhaps but neither needs to be installed for most of sisu output to work
+
+.BR
+examine source document, vim has syntax support
+
+.BR
+gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+additional markup samples in
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/2.html>
+
+.BR
+For help
+
+.BR
+  man sisu
+
+.BR
+or
+
+.BR
+  sisu \-\-help
+
+.BR
+e.g.
+
+.BR
+for the way sisu \"sees/maps\" your system
+
+.BR
+  sisu \-\-help env
+
+.BR
+for list of commands and so on
+
+.BR
+  sisu \-\-help commands
+
+.SH
+6.5 CONFIGURATION FILES
+
+.BR
+The default configuration/setup is contained within the program and is altered
+by configuration settings in
+.I etc
+[sisu \ version]/sisurc.yml or in ~/.sisu/sisurc.yml
+
+.BR
+* configuration file \- a yaml file
+
+.BR
+  /etc/sisu/[sisu \ version]/sisurc.yml
+
+.BR
+  ~/.sisu/sisurc.yml
+
+.BR
+* directory structure \- setting up of output and working directory.
+
+.BR
+* skins \- changing the appearance of a project, directory or individual
+documents within ~/.sisu/skin
+
+.BR
+  ~/.sisu/skin/doc contains individual skins, with symbolic links from
+
+.BR
+  ~/.sisu/skin/dir if the contents of a directory are to take a particular
+  document skin.
+
+.BR
+* additional software \- eg. Tex and LaTeX (tetex, tetex\-base, tetex\-extra on
+.B Debian
+), Postgresql, \ [sqlite], trang, tidy, makeinfo, ... none of which are
+required for basic html or XML processing.
+
+.BR
+* if you use Vim as editor there is a syntax highlighter and fold resource
+config file for
+.B SiSU
+. I hope more syntax highlighters follow.
+
+.BR
+There are post installation steps (which are really part of the overall
+installation)
+
+.BR
+sisu \-C in your marked up document directory, should do some auto\-configuring
+provided you have the right permissions for the output directories. (and
+provided the output directories have already been specified if you are not
+using the defaults).
+
+.SH
+6.6 USE GENERAL OVERVIEW
+
+.BR
+Documents are marked up in
+.B SiSU
+syntax and kept in an ordinary text editable file, named with the suffix
+.sst, or .ssm
+
+.BR
+Marked up
+.B SiSU
+documents are usually kept in a sub\-directory of your choosing
+
+.BR
+use the interactive help and man pages
+
+.BR
+  sisu \-\-help
+
+.BR
+  man sisu
+
+.SH
+6.7 HELP
+
+.BR
+interactive help described below, or man page:
+
+.BR
+  man sisu
+
+.BR
+  man 8 sisu
+
+.BR
+\'man sisu_markup\-samples\' \ [if \ the \ sisu\-markup\-samples \ package \ is
+\ also \ installed]
+
+.BR
+Once installed an interactive help is available typing \'sisu\' (without) any
+flags, and select an option:
+
+.BR
+  sisu
+
+.BR
+alternatively, you could type e.g.
+
+.BR
+  sisu \-\-help commands
+
+.BR
+  sisu \-\-help env
+
+.BR
+  sisu \-\-help headers
+
+.BR
+  sisu \-\-help markup
+
+.BR
+  sisu \-\-help headings
+
+.BR
+etc.
+
+.BR
+for questions about mappings, output paths etc.
+
+.BR
+  sisu \-\-help env
+
+.BR
+  sisu \-\-help path
+
+.BR
+  sisu \-\-help directory
+
+.SH
+6.8 DIRECTORY STRUCTURE
+
+.BR
+Once installed, type:
+
+.BR
+  sisu \-\-help env
+
+.BR
+or
+
+.BR
+  sisu \-V
+
+.SH
+6.9 CONFIGURATION FILE
+
+.BR
+The defaults can be changed via
+.B SiSU
+\'s configure file sisurc.yml which the program expects to find in ./_sisu
+~/.sisu or /etc/sisu (searched in that order, stopping on the first one found)
+
+.SH
+6.10 MARKUP
+
+.BR
+See man pages.
+
+.BR
+  man sisu
+
+.BR
+  man 8 sisu
+
+.BR
+Once installed there is some information on
+.B SiSU
+Markup in its help:
+
+.BR
+  sisu \-\-help markup
+
+.BR
+and
+
+.BR
+  sisu \-\-help headers
+
+.BR
+Sample marked up document are provided with the download tarball in the
+directory:
+
+.BR
+  ./data/doc/sisu/sisu_markup_samples/dfsg
+
+.BR
+These are installed on the system usually at:
+
+.BR
+  /usr/share/doc/sisu/sisu_markup_samples/dfsg
+
+.BR
+More markup samples are available in the package sisu\-markup\-samples
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#sisu\-markup\-samples>
+
+.BR
+Many more are available online off:
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/2.html>
+
+.SH
+6.11 ADDITIONAL THINGS
+
+.BR
+There is syntax support for some editors provided (together with a README file)
+in
+
+.BR
+  ./data/sisu/conf/syntax
+
+.BR
+usually installed to:
+
+.BR
+  /usr/share/sisu/conf/syntax
+
+.SH
+6.12 LICENSE
+
+.BR
+License: GPL 3 or later see the copyright file in
+
+.BR
+  ./data/doc/sisu
+
+.BR
+usually installed to:
+
+.BR
+  /usr/share/doc/sisu
+
+.SH
+6.13 SISU STANDARD
+
+.BR
+.B SiSU
+uses:
+
+.BR
+* Standard
+.B SiSU
+markup syntax,
+
+.BR
+* Standard
+.B SiSU
+meta\-markup syntax, and the
+
+.BR
+* Standard
+.B SiSU
+object citation numbering and system
+
+.BR
+© Ralph Amissah 1997, current 2006 All Rights Reserved.
+
+.BR
+* however note the License section
+
+.BR
+CHANGELOG
+
+.BR
+  ./CHANGELOG
+
+.BR
+and see
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/changelog.html>
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>
+
+.SH
+EXTRACTS FROM MAN 8 SISU
+.BR
+
+.SH
+7. POST INSTALLATION SETUP
+.BR
+
+.SH
+7.1 POST INSTALLATION SETUP \- QUICK START
+
+.BR
+After installation of sisu\-complete, move to the document samples directory,
+
+.BR
+  cd /usr/share/doc/sisu/sisu_markup_samples/dfsg
+
+.BR
+[this \ is \ not \ where \ you \ would \ normally \ work \ but \ provides \
+sample \ documents \ for \ testing, \ you \ may \ prefer \ instead \ to \ copy
+\ the \ contents \ of \ that \ directory \ to \ a \ local \ directory \ before
+\ proceeding]
+
+.BR
+and in that directory, initialise the output directory with the command
+
+.BR
+  sisu \-CC
+
+.BR
+then run:
+
+.BR
+  sisu \-1 free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+or the same:
+
+.BR
+  sisu \-NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+look at output results, see the \"sisu_manifest\" page created for the document
+
+.BR
+for an overview of your current sisu setup, type:
+
+.BR
+  sisu \-\-help env
+
+.BR
+or
+
+.BR
+  sisu \-V
+
+.BR
+To generate a document from a remote url accessible location move to a writable
+directory, (create a work directory and cd into it) as the file will be
+downloaded there and e.g.
+
+.BR
+  sisu \-1 <http://www.jus.uio.no/sisu/gpl3.fsf/gpl3.fsf.sst>
+
+.BR
+  sisu \-3
+  <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst>
+
+.BR
+examine source document, vim has syntax highlighting support
+
+.BR
+gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
+
+.BR
+additional markup samples in
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/2.html>
+
+.BR
+it should also be possible to run sisu against sisupods (prepared zip files,
+created by running the command sisu \-S \ [filename]), whether stored locally
+or remotely.
+
+.BR
+  sisu \-3
+  <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip>
+
+.BR
+there is a security issue associated with the running of document skins that
+are not your own, so these are turned of by default, and the use of the
+following command, which switches on the associated skin is not recommended:
+
+.BR
+  sisu \-3 \-\-trust
+  <http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/sisupod.zip>
+
+.BR
+For help
+
+.BR
+  man sisu
+
+.BR
+  sisu \-\-help
+
+.BR
+  sisu \-\-help env for the way sisu \"sees/maps\" your system
+
+.BR
+  sisu \-\-help commands for list of commands and so on
+
+.SH
+7.2 DOCUMENT MARKUP DIRECTORY
+
+.BR
+Perhaps the easiest way to begin is to create a directory for sisu marked up
+documents within your home directory, and copy the file structure (and document
+samples) provided in the document sample directory:
+
+.BR
+  mkdir ~/sisu_test
+
+.BR
+  cd ~/sisu_test
+
+.BR
+  cp \-a /usr/share/doc/sisu/sisu_markup_samples/dfsg/* ~/sisu_test/.
+
+.BR
+.B Tip:
+the markup syntax examples may be of interest
+
+.BR
+  <http://www.jus.uio.no/sisu/sample/>
+
+.BR
+.B Tip:
+
+.BR
+  sisu \-U \ [sisu \ markup \ filename]
+
+.BR
+should printout the different possible outputs and where sisu would place them.
+
+.BR
+.B Tip:
+if you want to toggle ansi color add
+
+.BR
+  c
+
+.BR
+to your flags.
+
+.SH
+7.2.1 CONFIGURATION FILES
+
+.BR
+.B SiSU
+configuration file search path is:
+
+.BR
+  ./_sisu/sisurc.yaml
+
+.BR
+  ~/.sisu/sisurc.yaml
+
+.BR
+  /etc/sisu/sisurc.yaml
+
+.BR
+.\\"%%
+.B Debian
+Installation Note
+
+.SH
+7.2.2 DEBIAN INSTALLATION NOTE
+
+.BR
+It is best you see
+
+.BR
+  <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
+
+.BR
+for up the most up to date information.
+
+.BR
+notes taken from the
+.B Debian
+control file (end edited), gives an idea of additional packages that
+.B SiSU
+can make use of if available, (the use/requirement of some of which are
+interdependent for specific actions by
+.B SiSU
+):
+
+.BR
+Package: sisu
+
+.BR
+.B SiSU
+is a lightweight markup based, command line oriented, document structuring,
+publishing and search framework for document collections.
+
+.BR
+With minimal preparation of a plain\-text, (UTF\-8) file, using its native
+markup syntax in your text editor of choice,
+.B SiSU
+can generate various document formats (most of which share a common object
+numbering system for locating content), including plain text, HTML, XHTML, XML,
+OpenDocument text (ODF:ODT), LaTeX, PDF files, and populate an SQL database
+with objects (roughly paragraph\-sized chunks) so searches may be performed and
+matches returned with that degree of granularity: your search criteria is met
+by these documents and at these locations within each document. Object
+numbering is particularly suitable for \"published\" works (finalized texts as
+opposed to works that are frequently changed or updated) for which it provides
+a fixed means of reference of content. Document outputs also share semantic
+meta\-data provided.
+
+.BR
+.B SiSU
+also provides concordance files, document content certificates and manifests
+of generated output.
+
+.BR
+A vim syntax highlighting file and an ftplugin with folds for sisu markup is
+provided, as are syntax highlighting files for kate, kwrite, gedit and
+diakonos. Vim 7 includes syntax highlighting for
+.B SiSU
+.
+
+.BR
+man pages, and interactive help are provided.
+
+.BR
+Dependencies for various features are taken care of in sisu related packages.
+The package sisu\-complete installs the whole of
+.B SiSU
+.
+
+.BR
+Additional document markup samples are provided in the package
+sisu\-markup\-samples which is found in the non\-free archive the licenses for
+the substantive content of the marked up documents provided is that provided by
+the author or original publisher.
+
+.BR
+Homepage: <http://www.jus.uio.no/sisu>
+
+.SH
+7.2.3 DOCUMENT RESOURCE CONFIGURATION
+
+.BR
+.B sisu
+resource configuration information is obtained from sources (where they
+exist):
+
+.BR
+  ~/.sisu/sisurc.yaml
+
+.BR
+  /etc/sisu/[sisu \ version]/sisurc.yaml
+
+.BR
+  sisu program defaults
+
+.SH
+7.2.4 SKINS
+
+.BR
+.B Skins
+default document appearance may be modified using skins contained in
+sub\-directories located at the following paths:
+
+.BR
+  ./_sisu/skin
+
+.BR
+  ~/.sisu/skin
+
+.BR
+  /etc/sisu/skin
+
+.BR
+more specifically, the following locations (or their /etc/sisu equivalent)
+should be used:
+
+.BR
+  ~/.sisu/skin/doc
+
+.BR
+skins for individual documents;
+
+.BR
+  ~/.sisu/skin/dir
+
+.BR
+skins for directories of matching names;
+
+.BR
+  ~/.sisu/skin/site
+
+.BR
+site\-wide skin modifying the site\-wide appearance of documents.
+
+.BR
+Usually all skin files are placed in the document skin directory:
+
+.BR
+  ~/.sisu/skin/doc
+
+.BR
+with softlinks being made to the skins contained there from other skin
+directories as required.
+
+.SH
+DOCUMENT INFORMATION (METADATA)
+.BR
+
+.SH
+METADATA
+.BR
+
+.BR
+Document Manifest @
+<http://www.jus.uio.no/sisu/sisu_manual/sisu_howto/sisu_manifest.html>
+
+.BR
+.B Dublin Core
+(DC)
+
+.BR
+.I DC tags included with this document are provided here.
+
+.BR
+DC Title:
+.I SiSU \- SiSU information Structuring Universe / Structured information,
+Serialized Units \- Technical, Howto
+
+.BR
+DC Creator:
+.I Ralph Amissah
+
+.BR
+DC Rights:
+.I Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL
+3
+
+.BR
+DC Type:
+.I information
+
+.BR
+DC Date created:
+.I 2002\-11\-12
+
+.BR
+DC Date issued:
+.I 2002\-11\-12
+
+.BR
+DC Date available:
+.I 2002\-11\-12
+
+.BR
+DC Date modified:
+.I 2007\-09\-16
+
+.BR
+DC Date:
+.I 2007\-09\-16
+
+.BR
+.B Version Information
+
+.BR
+Sourcefile:
+.I sisu_howto.sst
+
+.BR
+Filetype:
+.I SiSU text insert 0.57
+
+.BR
+Sourcefile Digest, MD5(sisu_howto.sst)=
+.I 82c606e66689bcb5d190edf8fc7227a0
+
+.BR
+Skin_Digest:
+MD5(/home/ralph/grotto/theatre/dbld/sisu\-dev/sisu/data/doc/sisu/sisu_markup_samples/sisu_manual/_sisu/skin/doc/skin_sisu_manual.rb)=
+.I 20fc43cf3eb6590bc3399a1aef65c5a9
+
+.BR
+.B Generated
+
+.BR
+Document (metaverse) last generated:
+.I Sun Sep 23 01:14:01 +0100 2007
+
+.BR
+Generated by:
+.I SiSU
+.I 0.58.3
+of 2007w36/4 (2007\-09\-06)
+
+.BR
+Ruby version:
+.I ruby 1.8.6 (2007\-06\-07 patchlevel 36) \ [i486\-linux]
+
+.TP
+.BI 1.
+generated from source using rman
+ <http://polyglotman.sourceforge.net/rman.html>
+ With regard to
+.B SiSU
+man pages the formatting generated for markup syntax is not quite right, for
+that you might prefer the links under:
+ <http://www.jus.uio.no/sample>
+.TP
+.BI 2.
+<http://www.jus.uio.no/sisu/man/>
+.TP
+.BI 3.
+<http://www.jus.uio.no/sisu/man/sisu.1.html>
+.TP
+.BI 4.
+<http://www.jus.uio.no/sisu/man/sisu.8.html>
+.TP
+.BI 5.
+<http://www.jus.uio.no/sisu/man/sisu_examples.1.html>
+.TP
+.BI 6.
+<http://www.jus.uio.no/sisu/man/sisu_webrick.1.html>
+.TP
+.BI 7.
+this is an endnote
+.TP
+.BI 8.
+<http://sisudoc.org>
+.TP
+.BI 10.
+<http://sisudoc.org>
+
+.TP
+Other versions of this document:
+.TP
+manifest: <http://www.jus.uio.no/sisu/sisu_howto/sisu_manifest.html>
+.TP
+html: <http://www.jus.uio.no/sisu/sisu_howto/toc.html>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_howto/portrait.pdf>
+.TP
+pdf: <http://www.jus.uio.no/sisu/sisu_howto/landscape.pdf>
+." .TP
+." manpage: http://www.jus.uio.no/sisu/sisu_howto/sisu_howto.1
+.TP
+at: <http://www.jus.uio.no/sisu>
+.TP
+.TP
+* Generated by: SiSU 0.58.3 of 2007w36/4 (2007-09-06)
+.TP
+* Ruby version: ruby 1.8.6 (2007-06-07 patchlevel 36) [i486-linux]
+.TP
+* Last Generated on: Sun Sep 23 01:14:06 +0100 2007
+.TP
+* SiSU http://www.jus.uio.no/sisu