path: root/man/man1/sisu.1

.\" Name: SiSU information Structuring Universe
.\" Author: Ralph Amissah
.\" Description: sisu manpage
.\" arch-tag: sisu manpage
.\" License: GPL 2 or later
.\" Notes: Process this file with
.\" groff -man -Tascii sisu.1
.\" nroff -man sisu.1 | most
.\" /[^\\][-']
.\" :%s/\([^\\]\)\([-']\)/\1\\\2/c
.\" |sisu.1|@|^|<url:sisu.1>
.TH "sisu" "1" "April 04, 2007" "version 0.52" "USER COMMANDS and basic Markup"
.SH "NAME"
.B SiSU
\- Structured information, Serialized Units \- a document publishing system
.SH "SYNOPSIS"
.B sisu
.B [
.I \-AabcDdEeFHhIMmNnopqrRSstUuVvwXxYyZz0\-9
.B ] [
.I filename/ wildcard
.B ]
.PP
.B sisu
.B [
.I \-Ddcv
.B ] [
.I instruction
.B ]
.PP
.B sisu
.B [
.I \-CcFLSVvW
.B ]
.PP
Note: commands should be issued from within the directory that contains the marked up files, cd to markup directory.
.\" %% Description
.SH "DESCRIPTION"
.B 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 ("object citation numbering") and the same document structure information. For more see:
.I <http://www.jus.uio.no/sisu>
.PP
.\" %% Summary
.SH "Summary of man page"
.TP
This man page covers a number of subjects in brief, including: document processing command flags; document markup (basic markup and headers); configuration files; directory structure; skins; document naming; interactive help and other information.
.\" %% Flags
.SH "DOCUMENT PROCESSING COMMAND FLAGS"
.TP
.BI \-A \ [filename/wildcard]
produces
.I plaintext
with
.I dos linefeeds
and without markup, (object numbers are omitted), has footnotes at end of each paragraph that contains them [
.I \-a
for equivalent Unix (linefeed) output file] [see
.I \-E
for endnotes].
.TP
.BI \-a \ [filename/wildcard]
produces
.I plaintext
with
.I Unix linefeeds
and without markup, (object numbers are omitted), has footnotes at end of each paragraph that contains them [
.I \-A
for equivalent dos (linefeed) output file] [see
.I \-e
for endnotes].
.TP
.BI \-b \ [filename/wildcard]
produces
.I xhtml/XML
output for browser viewing (sax parsing).
.TP
.BI \-C \ [\-\-init=site]
.I 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).
.BI \-C \ \-\-init=site
.I configure/initialise site
more extensive than
.I \-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.
.TP
.BI \-c \ [filename/wildcard]
screen
.I 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).
.TP
.BI \-D \ [instruction] \ [filename]
database postgresql
(
.I \-\-pgsql
may be used instead)
possible instructions, include:
.I \-\-createdb;
.I \-\-create;
.I \-\-dropall;
.I \-\-import \ [filename];
.I \-\-update \ [filename];
.I \-\-remove \ [filename];
see database section below.
.TP
.BI \-d \ [\-\-db\-[database \ type \ (sqlite|pg)]] \ \-\-[instruction] \ [filename]
database type
default set to sqlite, (for which
.I \-\-sqlite
may be used instead)
or to specify another database
.I \-\-db\-[pgsql, sqlite]
(however see \-D)
possible instructions include:
.I \-\-createdb;
.I \-\-create;
.I \-\-dropall;
.I \-\-import \ [filename];
.I \-\-update \ [filename];
.I \-\-remove \ [filename];
see database section below.
.TP
.BI \-E \ [filename/wildcard]
produces
.I plaintext
with
.I dos linefeeds,
and without markup, endnotes follow the main text (in
.I \-a
endnotes follow the paragraphs that contain them). There are no object numbers [see
.I \-e
for Unix (linefeed) output file] [see
.I \-A
for footnotes].
.TP
.BI \-e \ [filename/wildcard]
produces
.I plaintext
with
.I Unix linefeeds,
and without markup, endnotes follow the main text. Object numbers are omitted. [
.I \-E
for equivalent dos (linefeed) output file] [
.I \-a
for footnotes].
.TP
.BI \-F \ [\-\-webserv=webrick]
generate examples of (naive)
.I cgi search form
for
.I sqlite
and
.I 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
.I \-d
.I \-D
and the
.I database section
below.
If the optional parameter
.I \-\-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
.I cgi\-bin
directory).
.I \-Fv
(in addition to the above) provides some information on setting up
.I hyperestraier
for sisu
.\" An alternative optional parameter
.\" .I the letters pwd
.\" anticipates that the present work directory will be used to test the cgi script.
.TP
.\" .BI \-g \ [filename/wildcard]
.\" produces html/css/scroll (using markup shared with db)output for browser viewing (easily modified to XML)
.\" .TP
.BI \-H \ [filename/wildcard]
produces
.I html
without link suffixes (.html .pdf etc.) ("Hide"). Requires an appropriately configured web server. [behaviour switched after 0.35 see \-h].
.TP
.BI \-h \ [filename/wildcard]
produces
.I 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].
.TP
.BI \-I \ [filename/wildcard]
produces
.I texinfo
file.
.TP
.BI \-L
prints license information.
.TP
.BI \-M \ [filename/wildcard/url]
.I maintenance mode
files created for processing preserved and their locations indicated. (also see \-V)
.TP
.BI \-m \ [filename/wildcard/url]
assumed for most other flags, creates new meta\-markup file, (the
.I metaverse
) that is used in all subsequent processing of other output. This step is assumed for most processing flags. To skip it see
.I \-n
.TP
.BI \-N \ [filename/wildcard/url]
document
.I digest
or
.I document content certificate
(
.I DCC
)
as
.I 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).
.I \-NV
for verbose digest output to screen.
.TP
.BI \-n \ [filename/wildcard/url]
skip meta\-markup (building of "metaverse"), this skips the equivalent of
.I \-m
which is otherwise assumed by most processing flags.
.TP
.BI \-o \ [filename/wildcard/url]
output basic document in
.I opendocument
file format (opendocument.odt).
.TP
.BI \-p \ [filename/wildcard]
produces
.I 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.
.I \-\-papersize\-a4
preset sizes include: 'A4', U.S. 'letter' and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4).
.TP
.BI \-q \ [filename/wildcard]
.I quiet
less output to screen.
.TP
.BI \-R \ [filename/wildcard]
.I copies
sisu output files to
.I remote host
using rsync. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Note the behavior of rsync different if \-R is used with other flags from if used alone. Alone the rsync \-\-delete parameter is sent, useful for cleaning the remote directory (when \-R is used together with other flags, it is not). Also see
.I \-r
.TP
.BI \-r \ [filename/wildcard]
.I copies
sisu output files to
.I remote host
using scp. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Also see
.I \-R
.TP
.BI \-S
produces a
.I sisupod
a zipped sisu directory of markup files
including
.I sisu markup source files
and the directories local
.I configuration file,
.I images
and
.I skins.
.B Note:
this only includes the configuration files or skins contained in
.I ./_sisu
not those in
.I ~/.sisu
.I \-S \ [filename/wildcard]
option.
.B Note:
(this option is tested only with zsh).
.TP
.BI \-S \ [filename/wildcard]
produces a zipped file of the prepared document specified along with associated images, by default named
.I sisupod.zip
they may alternatively be named with the filename extension
.I .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
.I sisu markup source file,
(along with associated documents if a master file, or available in multilingual versions),
together with related
.I images
and
.I 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.
.B 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
.I \-S
option without [filename/wildcard].
.TP
.BI \-s \ [filename/wildcard]
copies sisu markup file to output directory.
.TP
.BI \-t \ [filename/wildcard \ (*.termsheet.rb)]
standard form document builder, preprocessing feature
.TP
.BI \-U \ [filename/wildcard]
prints
.I 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),
.I \-u
provides
.I 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
.TP
.BI \-u \ [filename/wildcard]
provides
.I url mapping
of output files for the flags requested for processing, also see
.I \-U
.TP
.B \-V
on its own, provides SiSU
.I version
and
.I environment information
(sisu \-\-help env)
.TP
.BI \-V \ [filename/wildcard]
even more
.I verbose
than the
.I \-v
flag. (also see \-M)
.TP
.B \-v
on its own, provides SiSU
.I version information
.TP
.BI \-v \ [filename/wildcard]
provides
.I verbose output
of what is being built, where it is being built (and error messages if any), as with
.I \-u
flag provides a url mapping of files created for each of the processing flag requests. See also
.B \-V
.TP
.BI \-W
starts ruby\'s
.I 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
.I \-h
option rather than
.I \-H
; also, note
.I \-F webrick
].
.\"% An alternative optional parameter
.\" .I the letters pwd
.\" results in the cgi\-bin directory being set to the present work directory. This is offered to simplify testing the cgi test form generated by
.\" .I \-S
.TP
.BI \-w \ [filename/wildcard]
produces
.I concordance (wordmap)
a rudimentary index of all the words in a document.
.TP
.BI \-X \ [filename/wildcard]
produces
.I XML output
with deep document structure, in the nature of dom.
.TP
.BI \-x \ [filename/wildcard]
produces
.I XML output
shallow structure (sax parsing).
.TP
.BI \-Y \ [filename/wildcard]
produces a short sitemap entry for the document, based on html output and the sisu_manifest.
.I \-\-sitemaps
generates/updates the sitemap index of existing sitemaps. (Experimental, [g,y,m announcement this week])
.TP
.BI \-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.
.TP
.BI \-Z \ [filename/wildcard]
Zap, if used with other processing flags
.I 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.
.TP
.BI \-z \ [filename/wildcard]
produces
.I php
(zend) [this feature is disabled for the time being]
.\" %% modifiers
.SH "modifiers"
.TP
.BI \-\-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.
.TP
.BI \-\-no\-annotate
strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk or dagger/plus sign
.TP
.BI \-\-no\-asterisk
strips output text of editor endnotes~[* square brackets ]~ denoted by asterisk sign
.TP
.BI \-\-no\-dagger
strips output text of editor endnotes~[+ square brackets ]~ denoted by dagger/plus sign
.\" .TP
.\" .BI \-\-no\-asterisk
.\" .TP
.\" .BI \-\-no\-dagger
.\" .TP
.\" .BI \-\-no\-annotate
.\" %% Flags Database
.SH "databases"
.TP
dbi \- database interface
.B \-D
or
.B \-\-pgsql
set for
.I postgresql
.B \-d
or
.B \-\-sqlite
default set for
.I sqlite
\-d is modifiable with \-\-db=[database \ type \ (pgsql \ or \ sqlite)]
.TP
.B \-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) [
.I \-dv \-\-createall
sqlite equivalent] it may be necessary to run sisu
.I \-Dv \-\-createdb
initially
.TP
NOTE: at the present time for postgresql it may be necessary to manually create the database. The command would be
.I 'createdb [database name]'
where database name would be SiSU_[present working directory name (without path)]. Please use only alphanumerics and underscores.
.TP
.B \-Dv \-\-import
.I [filename/wildcard]
imports data specified to postgresql db (rb.dbi) [
.I \-dv \-\-import
sqlite equivalent]
.TP
.B \-Dv \-\-update
.I [filename/wildcard]
updates/imports specified data to postgresql db (rb.dbi) [
.I \-dv \-\-update
sqlite equivalent]
.TP
.B \-D \-\-remove
.I [filename/wildcard]
removes specified data to postgresql db (rb.dbi) [
.I \-d \-\-remove
sqlite equivalent]
.TP
.B \-D \-\-dropall
kills data" and drops (postgresql or sqlite) db, tables & indexes [
.I \-d \-\-dropall
sqlite equivalent]
.TP
The v in e.g. \-Dv is for verbose output.
.RE
.\" %% Flags Shorthand
.SH "Shortcuts, Shorthand for multiple flags"
.TP
.BI \-\-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.
.TP
\-0 to \-5 [filename or wildcard]
Default shorthand mappings (note that the defaults can be changed/configured in the sisurc.yml file):
.PP
.I \-0
\-mNhwpAobxXyYv
.PB
[this is the default action run when no options are give, i.e. on 'sisu [filename]']
.PP
.I \-1
\-mNHwpy
.PP
.I \-2
\-mNHwpaoy
.PP
.I \-3
\-mNhwpAobxXyY
.PP
.I \-4
\-mNhwpAobxXDyY \ \-\-import
.PP
.I \-5
\-mNhwpAobxXDyY \ \-\-update
.PP
add
.I \-v
for verbose mode and
.I \-c
for color, e.g.
.I sisu \-2vc
[filename or wildcard]
.PP
consider
.I \-u
for appended url info or
.I \-v
for verbose output
.\" %% Markup
.SH "DOCUMENT MARKUP"
.B SiSU Markup
an incomplete summary.
.PP
.B Note:
files should be marked up for SiSU using
.I UTF\-8
encoding.
.PP
Some interactive help on markup is available, by typing
.I sisu
and selecting
.I markup
or
.I sisu \-\-help markup
.TP
Sample markup files can be used as examples:
.I <http://www.jus.uio.no/sisu/sample>
.TP
actual marked up plaintext files ready for use:
.I <http://www.jus.uio.no/sisu/sample/markup>
.TP
as html with syntax highlighting for viewing:
.I <http://www.jus.uio.no/sisu/sample/syntax>
.TP
an alternative presentation of markup syntax:
.I <http://www.jus.uio.no/sisu/sample/on_markup.txt>
.\" %% Markup Basic
.SH "Basic Markup"
Data text markup (alternative to available html subset)
.\" preformatted text follows
.PP
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.
.BR
.I :A~
usually the title
.BR
.I :A~?
conditional level 1 heading (used where a stand\-alone document may be imported into another)
.PP
.I 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)
.PP
.I !{
emphasis
.I }!
.PP
.I *{
bold text
.I }*
.PP
.I _{
underscore
.I }_
.PP
.I /{
italics
.I }/
.PP
.I \'"{
citation
.I }"
.PP
.I ^{
superscript
.I }^
.PP
.I ,{
subscript
.I },
.PP
.I +{
inserted text
.I }+
.PP
.I \-{
strikethrough
.I }\-
.\" %% Markup Endnotes
.SH "Footnotes/Endnotes"
.PP
.I ~{
a footnote or endnote
.I }~
.PP
footnote/endnote
.I ~{
self contained endnote marker & endnote in one
.I }~
.PP
.I ~{*
unnumbered asterisk footnote/endnote, insert multiple asterisks if required
.I }~
.PP
.I ~[*
editors notes, numbered asterisk footnote/endnote series
.I ]~
(+ the plus sign may be used as well)
.PP
alternative endnote pair notation:
.PP
.I ~^
endnote marker
.PP
.I ^~
endnote text following the paragraph in which the marker occurs
.\" %% Markup Line Operations
.SH "Line Operations (marker placed at start of line)"
.PP
.I !_
bold line
.PP
.I _1
indent paragraph one level
.PP
.I _2
indent paragraph two steps
.PP
.I _*
bullet paragraph
.PP
.I  #
number paragraph          (see headers for numbering document headings)
.PP
.I _#
number paragraph level 2  (see headers for numbering document headings)
.\" %% Markup Links
.SH "Links"
.PP
.I {
link name
.I }http://url.org
.PP
.I {
image.png
.I }http://url.org
.PP
.I {
image.png
.I }image
.PP
.I {
tux.png 64x80
.I }image
.PP
NOTE: (a) png and jpg support only (no gif)
(b) width x height, not required if imagemagick is installed, (where provided, dimensions may be smaller than the actual image), [images should be no larger than width: 480 and height: 640]
.PP
the shortcut:
.PP
.I {~^
[text to link]
.I }http://url.org
.PP
is equivalent to:
.PP
.I {
[text to link]
.I }http://url.org
.I ~{
http://url.org
.I }~
.PP
(which produces hyper\-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink)
.PP
url example:
.PP
.I {
SiSU Geek Writer
.I }http://www.jus.uio.no/sisu/
.PP
linked image:
.PP
.I {
tux.png 64x80 "a better way"
.I }http://www.jus.uio.no/sisu/
image example with all options
.PP
note width x height
.PP
the shortcut:
.PP
.I {
[text to link]
.I [3sS]}markup_source_filename.sst
.PP
if a server host name has been provided/configured, will provide a list of available output types that would be generated using the shortcut command and the markup file provided, i.e. output generated using the command (as configured): "sisu \-3sS markup_source_filename.sst", using server host, directory stub, filename to compose the link.
.\" %% Markup html name tagging
.SH "Adding a fixed names in html"
.PP
.I *~[name]
manual location marker/tagging at present only in html to produce <a name="[name]"></a> (use sparingly)
.RS
note at a heading level the same is automatically achieved by providing names to headings 5 and 6 i.e. 5~[name] and 6~[name] or in the case of auto\-heading numbering, without further intervention.
.RE
.\" %% Markup escape ocn
.SH "Escape object citation numbering"
.PP
(place marker at end of paragraph)
.PP
.I ~#
unnumbered paragraph
.PP
.I \-#
unnumbered paragraph, delete when not required (place marker at end of paragraph) [used in dummy headings, eg. for segmented html]
.PP
It is convenient to mention here that the
.I \-0
flag generates html and latex/pdf output without visible object character numbers.
.PP
.I sisu \-0
[filename.sst]
.\" %% Markup latex/pdf page breaks
.SH "Page breaks (LaTeX/pdf)"
.PP
page breaks are introduced to pdfs either as header instructions, indicating that pages should break at given levels, and mentioned in the header section, or manually, using the following notation
.PP
.I <:pb>
page break, which breaks a page, starting a new page in single column text and a new column in double column text
.PP
.I <:pn>
page new, which starts a new page, in both single and double column text (leaving an empty column in double column text if necessary).
.\" %% Markup comments
.SH "Comment line"
.PP
.I %
ignored by sisu in processing if placed at beginning of line
.PP
.I  %%
ignored by sisu in processing if placed at beginning of line, used for folding by vim folds
.\" %% Special Characters
.SH "Special characters"
special characters can be escaped with a backslash
.I { } < >
are contextual special characters, (in combination with other characters).
.I ~ \- _ / % ^
and occasionally
.I ! # + ,
are special characters in particular circumstances,
see the syntax chart.
[note that SiSU is not optimised for technical writing]
.\" %% Markup Tables
.SH "Tables"
.PP
.I table{
[number of columns] [column width %];[column width %]

  [table content, line breaks are important see example below]

.I }table

  sample table:

.I table{~h c3; 26; 32; 32;

  This is a table, column1
  this would become row one of column two
  column three of row one is here

  column one row 2
  column two of row two
  column three of row two, and so on

  column one row three
  and so on
  here

.I }table

whole table gets an object citation number

.\" %% Markup other grouped text
.SH "Other Grouped or Pre\-formatted Text"
.I poem{

  [Text here]

  [Text here]

.I }poem

each verse is given an object citation number

  \-\-\-\-

.I group{

  [Text here]

.I }group

whole group gets an object citation number

  \-\-\-\-

.I code{

  [Text here]

.I }code

whole group gets an object citation number

.\" %% Composite Documents
.SH "Composite Documents"
.PP
It is possible to build a document by requiring other documents. The documents required may 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 mainly from other documents), by convention it should be named with the suffix
.I .ssm
(master)
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
.I .sst
regular markup file, or
.I .ssi
(insert/information)
.I .sst
A secondary file of the composite document is built prior to processing with the same prefix and the suffix
.I ._sst
and
.I .\_sst
There are a number of alternative syntaxes for requiring external documents in order to permit use of ascii hypertext linking available in the vim editor. They are as follows:

.TP
basic markup for importing a document

.I r{
filename
.I }

.I {
filename.si
.I }require

.I << {
filename.si
.I }
#for vim folds

.TP
importing a document with textlink syntax

.I |filename.si|@|^|require

.I << |filename.si|@|^|
#for vim folds

.TP
importing a document with thlnk syntax

.I <url:filename.si>require

.I << <url:filename.si>
#for vim folds

.TP
remote documents may be called with the thlnk syntax (or regular sisu syntax), e.g.

.I << <url:http://www.url.com/filename.si>

.\" %% Document Headers
.SH "Document 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 may take either form:
.I @headername:
[introduced in 0.38] or
.I 0~headername
All Dublin Core meta tags are available

.I @indentifier:
information or instructions [introduced in 0.38]

or

.I 0~indentifier
information or instructions, old equivalent, depreciated

where the "identifier" is a tag recognised by the program, and the "information" or "instructions" belong to the tag/indentifier specified.

Note: a header where used should only be used once; all headers apart from @title: (0~title) are optional; the @structure: (0~toc) header is used to describe document structure, and can be useful to know.

@structure: PART; CHAPTER; SECTION; ARTICLE; none; none;

structure can be defined by a match words or regular expression (the regular expression is assumed to start at the beginning of a line of text i.e. ^)

  For help see one of the following (and markup samples):

  *  interactive help \- type \'sisu \-\-help headers\'

  *  marked up text samples

  *  the SiSU_Markup.txt file provided with the program

  *  an outline of headers is provided below \-\->
.\" %% Header options
.SH "Outline of header options"
.I % SiSU 0.38
[declared file\-type identifier with markup version]

.I @title:
My Title \- This is now the Title of the Document and used as such

.I @subtitle:
The Subtitle if any

.I @creator:
[or ~author] Ralph Amissah

.I @subject:
(whatever your subject)

.I @description:

.I @publisher:

.I @contributor:

.I @translator:
[or ~translated_by]

.I @illustrator:
[or ~illustrated_by]

.I @prepared_by:
[or ~digitized_by]

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

.I @type:
article

.I @format:

.I @identifier:

.I @source:

.I @language:
[or @language.document:]
language in which current version of document is published. Some country settings result in processing adjustments, e.g. in LaTeX hyphenation, some country codes are recognized, but the language name in Engish is preferred. English 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, ee \- Estonian, hu \- Hungarian, pl \- Polish, ro \- Romanian, ru \- Russian, gl \- Greek, uk \- Ukranian, tr \- Turkish, si \- Slovene, sk \- Slovak, hr \- Croatian, cs \- Czech, bg \- Bulgarian ) [however, encodings are not available for all of the languages listed.]

.I @language.original:
original language in which the work was published

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

.I @relation:

.I @coverage:

.I @rights:
copyright, all rights reserved, public domain, copyleft, creative commons variant, etc.

.I @owner:

.I @keywords:
text document generation processing management LaTeX pdf structured XML citation [your keywords here, used for example by rss feeds, and in sql sear ches]

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

.I @comment:
[...]

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

.I @classify_loc:
Library of Congress classification

.I @classify_dewey:
Dewey classification

.I @classify_isbn:
ISBN

.I @classify_pg:
Project Gutenberg text number

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

.I @prefix_b:
or @prefix: [prefix is placed just after table of contents]

.I @rcs:
$Id$ [or
.I @cvs:
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 ]

.I @structure:
PART; CHAPTER; SECTION; ARTICLE; none; none; optional, where document structure can be defined by a match words 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 ta g, and may be used to supplement the instructions provided in this header tag if provided (@structure: is a synonym for @toc:)

.I @markup:
information on the markup used, e.g.
.I 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.
.I 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]
.I 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]

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

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

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

.I @skin:
skin_doc_[name_of_desired_document_skin]

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

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

.I :A~
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

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

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

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

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

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

NOTE: headers and heading levels used in the description provided refer to 0.38 markup
(a conversion script provided in sisu\-examples, modify.rb makes conversion between 0.37 and 0.38 markup simple)

For some help on document structure try

.I sisu \-\-help headings

and view sample markup documents provided

.\" % .I number in sequence but do not make a heading
.\" where autonmumbering has been selected, autonumbering may be applied to a paragraph which is not to become a heading, by use of the heading level to which a dash sign is added i.e. 1~ would become 1~\- (this may be done for the second and third autonumber levels)

.\" %% Configuration files
.SH "CONFIGURATION FILES"
.PP
Some configuration is required for SiSU, specifying in which directory processing should be done, and where the generated output should be placed.
.PP
SiSU resource configuration is determined by looking at the following files if they exist:
.PP
.I ./_sisu/sisurc.yml
.PP
.I ~/.sisu/sisurc.yml
.PP
.I /etc/sisu/sisurc.yml
.PP
In the absence of instructions in any of these it falls back to the internal program defaults.
.PP
Configuration determines the output and processing directories and the database access details.
.PP
A sample sisurc.yml may be found in /etc/sisu/sisurc.yml

.\" %% More Help on Markup and headers
.SH "More HELP on Markup and headers"
type:
    sisu ~
    sisu \-\-help

  markup help is available on:
    document wide instructions: headers (document structure)
    general text markup: headings; endnotes; tables

A markup table and sample marked\-up files (also in html with syntax highlighting) are available at:

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

.\" %% Directory Structure and Document Output
.SH "DIRECTORY STRUCTURE & Document Output"
.TP
SiSU determines output directories by looking at the resource configuration files, and in their absence the programs internal defaults.
.\" %% Directory defaults
.SH "Default Directories"
.TP
In the absence of other specifications in
.I ~/.sisu/sisurc.yml
in
.I /etc/sisu/sisurc.yml
SiSU writes to the following directories, processing files are placed in sub\-directories within
.I ./_sisu/processing
and if that is not writable to
.I /tmp/sisu_processing
.PP
Output is written to sub\-directories within
.I /var/www/
if it exists and is writable, and otherwise to
.I ~/sisu_output
.\" %% Directory markup and file mapping
.SH "Markup Document Directories and File Mapping"
.TP
Ideally documents should be placed as collections sub\-directories of their own, with a common denominator, such as subject or author.
.TP
The last part of a directory path is used to create a sub\-directory into which generated documents are placed, in (sub\-sub)directories of their own.
.TP
the document
.PP
.RS
.I ~/ebook/free_culture.sst
.RE
.TP
would map to
.PP
.RS
.I ~[configured output path]/ebook/free_culture
.RE
.TP
within which would be placed all html, XML, pdf output, typically under the names:
.PP
.RS
.I index.html
index for segmented text
.PP
.I doc.html
full length scrollable document
.PP
.I toc.html
index for segmented text
.PP
html segments, as many as there may be...
.TP
.I portrait.pdf
.PP
.I landscape.pdf
.PP
.I sax.xml
XML shallow structure, sax type parsing
.PP
.I dom.xml
XML deeper structure, dom type parsing
.PP
.I scroll.xhtml
xhtml
.PP
.I plain.txt
plain text
.\" %% Directory multi\-language document convention and file mapping
.SH "Multi\-language Document File Naming and Directory Mapping"
.TP
If the same document exists in different language versions, and it is desired that the published language versions should reside in the same output directory, the following filenaming convention should be observed, using Spannish as the sample language code (es) [it is very likley the use of country codes as language codes will be changed or extended in future] [filename]~[language code].sst
.TP
filename~es.sst
.TP
within sisurc.yml under the heading default the setting of language file: at 1, 2 or 3 determines the output filenaming convention used, as follows:
.TP
(1) [output directory path]/filename/es.index.html
.TP
(2) [output directory path]/filename/index.es.html
.TP
(3) [output directory path]/filename/index.html.es (which Apache for example can be configured to use to automatically serve each users preference)
.TP
filename~fr.sst
.TP
filename~de.sst
.TP
etc. would be placed in the same directory using the same convention as indeed would:
.TP
filename.sst
.TP
using the default convention mapping convention.
.TP
Selecting this form of filename will overide other language settings including the language header within a document.
.\" %% Directory db mapping
.SH "Markup Document Directories and Database Mapping"
.PP
Similarly there is a mapping to the database into which documents are placed.
.PP
The last part of a directory path is used to create a sub\-directory into which generated documents are placed, in a database of the same name, unless overridden.
.PP
Documents within the directory
.I ~/ebook
.PP
.RS
.I ~/ebook/free_culture.sst
.RE
.PP
would be placed in tables within the database
.PP
.RS
.I SiSU_ebook
.RE
.\" %% Skins
.SH "SKINS \- document, directory and site skins"
.PP
Skins modify the default appearance of document output on a document, directory, or site wide basis. Skins are looked for in the following locations:
.PP
.I ./_sisu/skin
.PP
.I ~/.sisu/skin
.PP
.I /etc/sisu/skin
.PP
Within the skin directory are the following the default sub\-directories for document skins:
.PP
.I ./skin/doc
.PP
.I ./skin/dir
.PP
.I ./skin/site
.PP
Documents take on a document skin, if the header of the document specifies a skin to be used.
.PP
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).
when
end
.PP
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.
.PP
A site skin, modifies the program default skin.
.PP
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)
.PP
Samples of list.yml and promo.yml may be found in /usr/share/doc/sisu/sisu_markup_samples/dfsg/_sisu/skin/yml (or equivalent directory)
.\" %% Document Naming convention
.SH "DOCUMENT NAMING CONVENTION"
.PP
SiSU documents are named with the suffix
.I ss
followed by a third distinguishing letter, usually t for ordinary text files.
.PP
.I .sst
is used by regular documents, and for most purposes is all you need to be aware of
.PP
.I .ssm
suffix indicates a master or composite document, i.e. a document which requests other documents, which may have the file extension .sst or .ssi. See section on Composite Documents for information on how these are prepared.
.PP
.I .ssi
indicates some prepared sisu markup information that is to be requested within master or composite document(s) and is not to be processed as a stand\-alone document.
.PP
.I ._sst
and
.I .\-sst
suffix are reserved for SiSU processing, and indicate a secondary file. Such secondary files are created when a composite file is constructed, and when a url is provided, it is saved locally for processing, as a secondary processing file. Secondary files may be clobbered by SiSU at will, and are not a way of storing information.

.I .sxs.xml
simple xml sax, sisu markup representation

.I .sxd.xml
simple xml dom, sisu markup representation

.I .sxn.xml
simple xml node, sisu markup representation

.I .sxs.xml.sst
or
.I .sxd.xml.sst
or
.I .sxn.xml.sst
auto\-converted from a simple xml markup representation (sxs, sxd, sxn)
.\" %% Remote Operations
.SH "REMOTE OPERATIONS"
.PP
These may be of three basic types.
.PP
Instruction that processed files are to be copied to a remote server, using the \-r or \-R flag as part of the processing instruction. This requires previous setting up/configuration of the method to be used (eg scp assumed for \-r and rsync for \-R) and url to which these files are to be sent. *
.PP
The downloading of a remote file for processing using SiSU locally, which is achieved in one of two ways:
.PP
A processing instruction may include the url to the a remote file that is to be processed \- this will be downloaded and given a temporary file .t extension, and will be processed using SiSU locally.
.PP
A file may request the inclusion of a remote document within it, see comments on "Composite Documents" for the request syntax.
.PP
Finally SiSU may be run on a remote server, which you download marked up files to for processing. This is not really a function of the operation of SiSU, just an available possibility given that not much bandwidth is required.
.PP
* with regard to remote files processed locally, the \-r option, a limitation is that it is up to the user to ensure that the remote file does not have an identical filename to another, e.g. local file, that is to be processed in the same directory. So far this has not been found to happen in practice... Alternative solutions are under consideration, but it is desired that filenames be human assigned, and meaningful, so hash keys of contents for filenames are not amongst the options considered.
.\" %% Note
.SH "NOTE"
.PP
For basic use only a fraction of the information provided here is required. There may be a bit of an information management problem in determining what though.
For the markup of a book see the samples provided in
.I <http://www.jus.uio.no/sisu/sample>
and referred to in the text
.I <http://www.jus.uio.no/sisu/SiSU>
The flags to generate html and pdf for use locally would be sisu \-mHp [name of file to be processed]
This does assume an ok install and setup of SiSU and the associated software it uses.

.\" %% Processing Examples
.SH "PROCESSING EXAMPLES"
.PP
To initialise a new directory
.B sisu
.I \-C
.PP
Note: this create a corresponding output subdirectory and this copies css stylesheet files and basic image files to the output directory. The output directory is created in the output path/directory as a subdirectory with its name corresponding to that of the directory you are currently initialising.
.PP
generate the metafile used in subsequent processing only (note changes made to the markup file will not appear in subsequently generated text unless this flag is used:
.B sisu
.I \-m
[filename or wildcard]
.PP
to create html and pdf output, with verbose output of samplefile1.sst and samplefile2.sst
.B sisu
.I \-mhpv
samplefile1.sst samplefile2.sst
.RS
Note:
.I \-m
does initial processing, and
.I \-H
omits filename suffixes and requires a properly configured web server.
.I \-h
is used to include filename suffixes for file system viewing
.RE
.PP
generate html, a word map and pdf with verbose output for all marked up documents in a directory:
.B sisu
.I \-mhwpv
*
.PP
generate html, word map, pdf, plaintext, xhtml, xml sax and xml dom versions with verbose output for all marked up documents in a directory:
.B sisu
.I \-mhwpabxXv
*
.PP
to create html, pdf, xml, plaintext and a concordance file (wordmap) as output, with verbose output of all marked up files in a directory
.B sisu
.I \-mhpxXawv
*.{r,s}?
.PP
generate html, word map and pdf and place on remote server with verbose output 2 named example files in a directory (assumes has been set up, and first time must be run without other flags ie sisu
.I \-mrv
[filenames/wildcard]):
.B sisu
.I \-mhwprv
example_file.sst other_example_file.sst
.PP
to process a remote sisu marked up file (html,pdf,concordance), provide the url(s) (works for text only files, will be downloaded and processed locally):
.B sisu
.I \-mhwpv
http://www.jus.uio.no/sisu/sample/markup/gpl2.fsf.sst http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst
.PP
one file is local the other remote process (html,pdf,concordance,plaintext and place on pre\-set remote destination):
.B sisu
.I \-mhwparv
gpl2.fsf.sst http://www.jus.uio.no/sisu/sample/markup/autonomy_markup0.sst
.PP
initialize database, create relations (first manually create database with same name as working directory):
.B sisu
.I \-Dv createall
.PP
it may be necessary to first run
.B sisu
.I \-Dv createdb
.PP
import all marked up files first time into a database:
.B sisu
.I \-Dv import
*
.PP
.I \-c
toggles color
.\" %% Interactive help
.SH "INTERACTIVE HELP OPTIONS"
.PP
SiSU has an interactive help, which is accessed by typing just "sisu" at the command line, or as described below:
.B sisu
commands, document preparation, customisation, installation etc.
.\" preformatted text follows
.nf
try:
.I sisu \-\-help

  sisu help
    help             sisu \-\-help
    commands         sisu \-\-help commands
    environment      sisu \-\-help env
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  Using SiSU
    commands:        sisu \-\-help commands
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  Preparing Documents for SiSU
    markup:          sisu \-\-help markup     (an incomplete overview)
    headers:         sisu \-\-help headers    (document\-wide instructions, meta\-data)
    structure        sisu \-\-help structure  (document structure, headings, tables of contents)
    endnotes:        sisu \-\-help endnotes
    tables:          sisu \-\-help tables
    an example 0.37: sisu \-\-help example37
    an example 0.38: sisu \-\-help example38
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
    search           sisu \-\-help search
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
    customise:       sisu \-\-help customise
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  SiSU\'s License
    license:         sisu \-\-help license

  sisu interactive help topics include:
        keywords include: list, commands, shortcuts, markup, syntax, headers,
        headings, endnotes, tables, example, customise, skin, environment,
        directories, path, language, db, install, setup, configure,
        external_programs, dublincore, termsheet, search, features,
        external_programs, license, exit
.fi

.SH "SiSU VERSION CONVERSION"
.PP
.I sisu \-\-to\-current [filename/wildcard]
converts from 0.37 markup to current markup (0.38)

.I sisu \-\-to\-38 [filename/wildcard]
converts from 0.37 markup to 0.38

.I sisu \-\-to\-37 [filename/wildcard]
converts from 0.38 markup to 0.37

.I sisu \-\-convert\-36to37 [filename/wildcard]
re\-names file from pre\-0.36 convention to 0.37

.I sisu \-\-convert\-footnotes [filename/wildcard]
converts footnotes to preferred embedded footnote markup style

.I sisu \-\-convert\-footnotes\-force [filename/wildcard]
converts footnotes to preferred embedded footnote markup style, even if there is a mismatch of footnote numbers. WARNING: there is a problem with the source document and it is necessary to manually check where each footnotes actually should be.

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

.I sisu \-\-to\-sax [filename/wildcard]
or
.I sisu \-\-to\-sxs [filename/wildcard]

.I sisu \-\-to\-dom [filename/wildcard]
or
.I sisu \-\-to\-sxd [filename/wildcard]

.I sisu \-\-to\-node [filename/wildcard]
or
.I sisu \-\-to\-sxn [filename/wildcard]

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

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

or the same:

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

.I sisu \-\-from\-kdi [kdissert filename]
attempts to convert a kdissert file (.kdi) to sisu markup

.I sisu \-\-identify [filename/wildcard]
attempts to identify the markup version of the file

.I sisu \-\-query=[version number]
and
.I sisu \-\-query=history
provides a brief summary of changes to SiSU markup

.SH "SAMPLE MARKUP DOCUMENTS"
.PP

Sample markup documents are provided in sisu\-examples and are available online.

.\" %% Further Information
.SH "HOME PAGE"
.PP
.I <http://www.jus.uio.no/sisu>

.SH "AUTHOR"
Ralph Amissah
.I <ralph@amissah.com>
or
.I <ralph.amissah@gmail.com>

.SH "SEE ALSO"
.BR sisu(8),
.BR sisu_webrick(1),
.BR sisu_termsheet(1),
.BR sisu_pdf(1)
.BR sisu_sqlite(1)
.BR sisu_postgresql(1)
.BR sisu_vim(7)