aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/man/man1/spine.14088
1 files changed, 4088 insertions, 0 deletions
diff --git a/doc/man/man1/spine.1 b/doc/man/man1/spine.1
new file mode 100644
index 0000000..255119a
--- /dev/null
+++ b/doc/man/man1/spine.1
@@ -0,0 +1,4088 @@
+.TH "spine" "1" "2020-04-05" "0.10.0" "Spine"
+.br
+.SH NAME
+.br
+sisu - documents: markup, structuring, publishing in multiple standard formats, and search
+.br
+.SH SYNOPSIS
+.br
+sisu [--options] [filename/wildcard]
+
+.br
+sisu --txt --html --epub --odt --pdf --wordmap --sqlite --manpage --texinfo --sisupod --source --qrcode [filename/wildcard]
+
+.br
+sisu --pg (--createdb|update [filename/wildcard]|--dropall)
+
+.SH SISU - MANUAL,
+RALPH AMISSAH
+
+.SH WHAT IS SISU?
+
+.SH INTRODUCTION - WHAT IS SISU?
+
+.BR
+
+.B SiSU
+is a 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
+From a single lightly prepared document (plain-text
+.I UTF-8
+) sisu custom builds several standard output formats which share a common (text
+object) numbering system for citation of content within a document (that also
+has implications for search). The sisu engine works with an abstraction of the
+document's structure and content from which it is possible to generate
+different forms of representation of the document.
+.B SiSU
+produces: plain-text,
+.I HTML,
+.I XHTML,
+.I XML,
+.I EPUB,
+.I ODF:
+.I ODT
+(Opendocument),
+.I LaTeX,
+.I PDF,
+and populates an
+.I SQL
+database (
+.I PostgreSQL
+or
+.I SQLite
+) with text objects, roughly, paragraph sized chunks so that document searches
+are done at this level of granularity.
+
+.BR
+Outputs share a common citation numbering system, associated with text objects
+and any semantic meta-data provided about the document.
+
+.BR
+
+.B SiSU
+also provides concordance files, document content certificates and manifests of
+generated output. Book indexes may be made.
+
+.BR
+Some document markup samples are provided in the package sisu -markup-samples.
+Homepages:
+
+- <http://www.sisudoc.org/>
+
+- <http://www.jus.uio.no/sisu>
+
+.SH COMMANDS SUMMARY
+
+.SH DESCRIPTION
+
+.BR
+
+.B SiSU
+is a document publishing system, that from a simple single marked-up document,
+produces multiple output formats including:
+.I plaintext,
+.I HTML,
+.I XHTML,
+.I XML,
+.I EPUB,
+.I ODT
+(
+.I OpenDocument
+(
+.I ODF
+) text),
+.I LaTeX,
+.I PDF,
+info, and
+.I SQL
+(
+.I PostgreSQL
+and
+.I SQLite
+) , which share text object numbers ("object citation numbering") and the same
+document structure information. For more see: <http://sisudoc.org> or
+<http://www.jus.uio.no/sisu>
+.SH DOCUMENT PROCESSING COMMAND FLAGS
+
+.TP
+.B --abstraction [path + filename]
+run document abstraction
+.TP
+.B --act[s0-9] [path + filename]
+--act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms,
+configure in sisurc.yml; sisu default action on a specified file where no flag
+is provided is --act0; --act or --acts for information on current actions
+ascribed to --act0 to --act9
+.TP
+.B --asciidoc [path + filename]
+asciidoc, smart text (not available)
+.TP
+.B --cgi-search-form-codegen
+ generate d code search form to search db specfied needs --output=[path] and
+--sqlite-db-filename=[cgi search form name] or path to configuration file
+--config=[full path to config file]
+.TP
+.B --cgi-sqlite-search-filename=[filename]
+name to give cgi-search form, (it generates a [filename].d file that requires
+subsequent compilation) also required is the name of the sqlite db to be
+searched by the form.
+.TP
+.B --concordance [path + filename]
+(not implemented)
+.TP
+.B --config=[path to config file + filename]
+.TP
+.B --dark
+ alternative theme for html and epub output, a light (default) theme is
+ also provided
+.TP
+.B --digest (not implemented)
+.TP
+.B --delete [path + filename]
+see --zap
+.TP
+.B --digests [path + filename]
+not implemented
+.TP
+.B --epub [path + filename]
+produces an epub document
+.TP
+.B --harvest [path to files]
+extract and present info on authors & topics from document header metadata.
+makes two lists of sisu output based on the sisu markup documents in a
+directory: list of author and authors works (year and titles), and; list by
+topic with titles and author. Makes use of header metadata fields (author,
+title, date, topic_register).
+.TP
+.B --harvest-authors [path to files]
+extract and present info on authors from metadata in document headers
+.TP
+.B --harvest-topics [path to files]
+extract and present info on topics from metadata in document headers
+.TP
+.B --hide-ocn
+turn visibility of object numbers off
+.TP
+.B --html [path + filename]
+produces html output in two forms (i) segmented text with table of contents
+(toc.html and index.html) and (ii) the document in a single file (scroll.html).
+.TP
+.B --html-link-harvest
+within html output creates link to the document set metadata harvest output
+part of --html output instruction and assumes that --harvest has been or will
+ be run
+.TP
+.B --html-link-search
+within html output creates a search form for submission, requires information
+on the name of the search form --search part of --html output instruction it
+assumes there is a cgi search form and related document database
+.TP
+.B --html-scroll [path + filename]
+produces html output, the document in a single file (scroll.html) only. Compare
+--html-seg and --html
+.TP
+.B --html-seg [path + filename]
+produces html output, segmented text with table of contents (toc.html and
+index.html). Compare --html-scroll and --html
+.TP
+.B --lang=[language code, e.g. =en or =en,es]
+provide language code of document
+.TP
+.B --latex [path + filename]
+.I LaTeX
+output for different document sizes (a4, a5, b4, letter) and orientations
+(portrait, landscape) for downstream (processing and) conversion to pdf, (used
+with xetex no direct link between programs provided as this is a much slower
+process)
+.TP
+.B --latex-color-links
+monochrome or color links within pdf, toggle (mono better for printing),
+the default is mono for portrait and color for landscape documents
+.TP
+.B --light theme
+for html and epub output, default, a dark alternative is provided
+.TP
+.B --manifest [path + filename]
+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
+.B --markdown [path + filename]
+markdown smart text (not available)
+.TP
+.B --no-*
+negate a toggle
+.TP
+.B --ocn-off
+object numbers off (the c in ocn is for citation). See --hide-ocn
+.TP
+.B --odf [path + filename]
+see --odt
+.TP
+.B --odt [path + filename]
+produce open document output
+.TP
+.B --output=[path to output directories]
+where to place document output
+.TP
+.B --parallel
+parallelization on (the default except for sqlite)
+.TP
+.B --parallel-subprocesses
+nested parallelization on (the default except for sqlite)
+.TP
+.B --papersize-(a4|a5|b5|letter|legal)
+in conjunction with --pdf set pdf papersize, overriding any configuration
+settings, to set more than one papersize repeat the option --pdf --papersize-a4
+--papersize-letter. See also --papersize=* (NOT implemented)
+.BR
+.B --papersize=a4,a5,b5,letter,legal
+in conjunction with --pdf set pdf papersize, overriding any configuration
+settings, to set more than one papersize list after the equal sign with a comma
+separator --papersize=a4,letter. See also --papersize-* (NOT implemented)
+.TP
+.B --pdf [path + filename]
+produces
+.I LaTeX
+see --latex
+.TP
+.B --pdf-color-links
+monochrome or color links within latex for pdf. See --latex-color-links
+.TP
+.B --pod
+markup source bundled in a zip file.
+Produces a zipped file of the prepared document specified along with associated
+images This provides a quick way of gathering the relevant
+parts of a sisu document which can then for example be emailed. A sisupod
+includes sisu markup source file, (along with associated documents if a master
+file, or available in multilingual versions), together with related images.
+(it should be possible in future to run spine commands directly against a pod).
+.TP
+.B --qrcode [path + filename]
+generate QR code image of metadata (used in manifest). (not implemented)
+.TP
+.B --quiet
+quiet less output to terminal.
+.TP
+.B --section-*
+provides finer grain control over which parts of the document are processed
+to produce output, toc, body, endnotes, glossary, biblio, bookindex and blurb
+.TP
+.B --section-biblio
+produce document bibliography output, toggle
+.TP
+.B --section-blurb
+produce document blurb output, toggle
+.TP
+.B --section-body
+produce document body output, toggle
+.TP
+.B --section-bookindex
+produce document bookindex output, toggle
+.TP
+.B --section-endnotes
+produce document endnotes output, toggle
+.TP
+.B --section-endnotes
+produce document glossary output, toggle
+.TP
+.B --serial
+serial processing --no-parallel
+.TP
+.B --show-config
+show site and document configuration instructions. Requires path to
+configuration file or path to documents to be processed.
+.TP
+.B --show-make
+show document make instructions
+.TP
+.B --show-metadata
+show document metadata
+.TP
+.B --show-summary
+show document summary
+.TP
+.B --source [path + filename]
+document markup source
+.TP
+.B --sha256
+set hash digest where used to sha256 (not implemented)
+.TP
+.B --sha512
+set hash digest where used to sha512 (not implemented)
+.TP
+.B --sqlite-discrete [path + filename]
+create a per document sqlite db
+.TP
+.B --sqlite-db-create --sqlite-db-filename="[db filename]" --output="[output path]"
+create a shared db and its tables. Requires a db filename, which may be set in the configuration file or on the command line as shown
+.TP
+.B --sqlite-db-drop [path + db filename]
+drop (remove) db and its tables
+.TP
+.B --sqlite-db-recreate [path + filename]
+drop and re-create a shared db and its tables. Requires a db filename, which may be set in the configuration file or on the command line with --sqlite-db-filename="[db name]"
+.TP
+.B --sqlite-db-filename="[db name]"
+provide name of sqlite db, to be created, dropped, populated or for which a search form is to be made. This information may also be set in the configuration file.
+.TP
+.B --sqlite-delete [path + filename]
+process sqlite output, remove file
+.TP
+.B --sqlite-insert [path + filename]
+process sqlite output, insert file. See --sqlite-update
+.TP
+.B --sqlite-update [path + filename]
+process sqlite output, update file
+.TP
+.B --source [filename/wildcard]
+copies sisu markup file to output directory. Alias -s
+.TP
+.B --text [filename/wildcard]
+produces
+.I plaintext
+output
+(not implemented)
+.TP
+.B --theme-dark
+See --dark
+.TP
+.B --theme-light
+See --light
+.TP
+.B --txt [filename/wildcard]
+produces
+.I plaintext
+output
+(not implemented)
+.TP
+.B --txt-asciidoc [filename/wildcard]
+see --asciidoc
+(not implemented)
+.TP
+.B --txt-markdown [filename/wildcard]
+see --markdown
+(not implemented)
+.TP
+.B --txt-rst [filename/wildcard]
+see --rst
+(not implemented)
+.TP
+.B --txt-textile [filename/wildcard]
+see --textile
+(not implemented)
+.TP
+.B -v
+on its own, provides
+.B SiSU
+version information
+.TP
+.B -v [filename/wildcard]
+see --verbose
+.TP
+.B --verbose [filename/wildcard]
+provides verbose output of what is being generated, where output is placed (and
+error messages if any). Alias -v
+.TP
+.B --very-verbose [filename/wildcard]
+provides more verbose output of what is being generated. See --verbose. Alias
+-V
+.TP
+.B --version
+spine version
+(not implemented)
+.TP
+.B --xhtml
+xhtml output
+(not implemented)
+
+.SH COMMAND LINE MODIFIERS
+
+.TP
+.B --no-ocn
+[with --html --pdf or --epub] switches off
+.I object citation numbering.
+Produce output without identifying numbers in margins of html or
+.I LaTeX
+/pdf output.
+.SH DATABASE COMMANDS
+
+.BR
+
+.B dbi - database interface
+
+.BR
+
+.B --pg or --pgsql
+set for
+.I PostgreSQL
+.B --sqlite
+default set for
+.I SQLite
+-d is modifiable with --db=[database type (PgSQL or
+.I SQLite
+) ]
+.TP
+.B --pg -v --createall
+initial step, creates required relations (tables, indexes) in existing
+.I PostgreSQL
+database (a database should be created manually and given the same name as
+working directory, as requested) (rb.dbi) [ -dv --createall
+.I SQLite
+equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at
+the present time for
+.I PostgreSQL
+it may be necessary to manually create the database. The command would be
+'createdb [database name]' where database name would be SiSU_[present working
+directory name (without path)]. Please use only alphanumerics and underscores.
+.TP
+.B --pg -v --import
+[filename/wildcard] imports data specified to
+.I PostgreSQL
+db (rb.dbi) [ -dv --import
+.I SQLite
+equivalent]
+.TP
+.B --pg -v --update
+[filename/wildcard] updates/imports specified data to
+.I PostgreSQL
+db (rb.dbi) [ -dv --update
+.I SQLite
+equivalent]
+.TP
+.B --pg --remove
+[filename/wildcard] removes specified data to
+.I PostgreSQL
+db (rb.dbi) [ -d --remove
+.I SQLite
+equivalent]
+.TP
+.B --pg --dropall
+kills data" and drops (
+.I PostgreSQL
+or
+.I SQLite
+) db, tables & indexes [ -d --dropall
+.I SQLite
+equivalent]
+
+.BR
+The -v is for verbose output.
+.SH CONFIGURATION
+
+.BR
+
+default location:
+.TP
+~/.dr/config_local_site
+.TP
+.nf
+flag:
+ act0: "--html"
+ act1: "--html --epub"
+output:
+ path: "/var/www/html"
+default:
+ language: "en"
+ papersize: "a4"
+ text_wrap: "80"
+ digest: "sha256"
+webserv:
+ http: "http"
+ domain: "localhost"
+ data_http: "http"
+ data_domain: "localhost"
+ data_root_url: "http://localhost"
+ data_root_path: "/var/www/html"
+ data_root_part: ""
+ images_root_part: "image"
+ cgi_title: "≅ SiSU Spine search"
+ cgi_http: "http"
+ cgi_domain: "localhost"
+ cgi_bin_url: "http://localhost/cgi-bin"
+ cgi_bin_part: "cgi-bin"
+ cgi_bin_path: "/usr/lib/cgi-bin"
+ cgi_search_script: "spine-search"
+ cgi_search_script_raw_fn_d: "spine_search.d"
+ cgi_port: ""
+ cgi_user: ""
+ cgi_action: "http://localhost/cgi-bin/spine-search"
+ db_sqlite: "spine.search.db"
+ db_pg_table: ""
+ db_pg_user: ""
+.fi
+
+.BR
+.SH SAMPLE POD DIRECTORY STRUCTURE
+.BR
+.TP
+.nf
+
+pod (directory may contain multiple documents)
+ └── the_wealth_of_networks.yochai_benkler
+ ├── conf
+ │   └── sisu_document_make
+ ├── media
+ │   ├── image
+ │   │   ├── won_benkler_2_1.png
+ │   │   ├── won_benkler_6_1.png
+ │   │   ├── won_benkler_7_1.png
+ │   │   ├── won_benkler_7_2.png
+ │   │   ├── won_benkler_7_3a.png
+ │   │   ├── won_benkler_7_3b.png
+ │   │   ├── won_benkler_7_4.png
+ │   │   ├── won_benkler_7_5.png
+ │   │   ├── won_benkler_7_6.png
+ │   │   └── won_benkler_9_1.png
+ │   └── text
+ │   └── en
+ │   └── the_wealth_of_networks.yochai_benkler.sst
+ └── pod.manifest
+
+.fi
+.SH COMMAND LINE EXAMPLES
+
+.TP
+note: ~webDocRoot should be the path to web doc root, provide a suitable output path.
+.TP
+spine -v --html --html-link-search --html-link-harvest --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+.TP
+spine -v --html --html-link-search --html-link-harvest --epub --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+.TP
+spine -v --sqlite-db-create --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod
+.TP
+spine -v --sqlite-db-create ~spineMarkupSamples/pod
+.TP
+spine -v --sqlite-update --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+.TP
+spine -v --sqlite-update ~spineMarkupSamples/pod/*
+.TP
+spine -v --show-config
+.TP
+spine -v --show-config --config= ~spineMarkupSamples/pod/.dr/config_local_site_test
+.TP
+spine -v --show-config --config=~spineMarkupSamples/pod/.dr
+.TP
+spine -v --cgi-search-form-codegen --config=~spineMarkupSamples/pod/.dr/config_local
+.TP
+cd ~webDocRoot/cgi
+.TP
+dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/.
+.TP
+
+.BR
+Running sisu (alone without any flags, filenames or wildcards) brings up the
+interactive help, as does any sisu command that is not recognised. Enter to
+escape.
+.SH HELP
+
+.SH SISU MANUAL
+
+
+.BR
+The most up to date information on sisu should be contained in the sisu_manual,
+available at:
+
+.BR
+ <http://sisudoc.org/sisu/sisu_manual/>
+
+.BR
+The manual can be generated from source, found respectively, either within the
+.B SiSU
+tarball or installed locally at:
+
+.BR
+ ./data/doc/sisu/markup-samples/sisu_manual
+
+.BR
+ /usr/share/doc/sisu/markup-samples/sisu_manual
+
+.BR
+move to the respective directory and type e.g.:
+
+.BR
+ sisu sisu_manual.ssm
+.SH SISU MAN PAGES
+
+
+.BR
+If
+.B SiSU
+is installed on your system usual man commands should be available, try:
+
+.BR
+ man sisu
+
+.BR
+Most
+.B SiSU
+man pages are generated directly from sisu documents that are used to prepare
+the sisu manual, the sources files for which are located within the
+.B SiSU
+tarball at:
+
+.BR
+ ./data/doc/sisu/markup-samples/sisu_manual
+
+.BR
+Once installed, directory equivalent to:
+
+.BR
+ /usr/share/doc/sisu/markup-samples/sisu_manual
+
+.BR
+Available man pages are converted back to html using man2html:
+
+.BR
+ /usr/share/doc/sisu/html/
+
+.BR
+ ./data/doc/sisu/html
+
+.BR
+An online version of the sisu man page is available here:
+
+.BR
+
+- various sisu man pages <http://www.jus.uio.no/sisu/man/> [^1]
+
+.BR
+- sisu.1 <http://www.jus.uio.no/sisu/man/sisu.1.html> [^2]
+.SH SISU BUILT-IN INTERACTIVE HELP, [DISCONTINUED]
+
+
+.BR
+This fell out of date and has been discontinued.
+.SH INTRODUCTION TO SISU MARKUP[^3]
+
+.SH SUMMARY
+
+.BR
+
+.B SiSU
+source documents are
+.I plaintext
+(
+.I UTF-8
+)[^4] files
+
+.BR
+All paragraphs are separated by an empty line.
+
+.BR
+Markup is comprised of:
+
+.BR
+- at the top of a document, the document header made up of semantic meta-data
+about the document and if desired additional processing instructions (such an
+instruction to automatically number headings from a particular level down)
+
+.BR
+- followed by the prepared substantive text of which the most important single
+characteristic is the markup of different heading levels, which define the
+primary outline of the document structure. Markup of substantive text includes:
+
+.BR
+ * heading levels defines document structure
+
+.BR
+ * text basic attributes, italics, bold etc.
+
+.BR
+ * grouped text (objects), which are to be treated differently, such as code
+ blocks or poems.
+
+.BR
+ * footnotes/endnotes
+
+.BR
+ * linked text and images
+
+.BR
+ * paragraph actions, such as indent, bulleted, numbered-lists, etc.
+.SH MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS
+
+
+.BR
+minimal content/structure requirement:
+
+.BR
+[metadata]
+.nf
+A~ (level A [title])
+
+1~ (at least one level 1 [segment/(chapter)])
+.fi
+
+
+.BR
+structure rules (document heirarchy, heading levels):
+
+.BR
+there are two sets of heading levels ABCD (title & parts if any) and 123
+(segment & subsegments if any)
+
+.BR
+sisu has the fllowing levels:
+.nf
+A~ [title] .
+ required (== 1) followed by B~ or 1~
+B~ [part] *
+ followed by C~ or 1~
+C~ [subpart] *
+ followed by D~ or 1~
+D~ [subsubpart] *
+ followed by 1~
+1~ [segment (chapter)] +
+ required (>= 1) followed by text or 2~
+text *
+ followed by more text or 1~, 2~
+ or relevant part *()
+2~ [subsegment] *
+ followed by text or 3~
+text *
+ followed by more text or 1~, 2~ or 3~
+ or relevant part, see *()
+3~ [subsubsegment] *
+ followed by text
+text *
+ followed by more text or 1~, 2~ or 3~ or relevant part, see *()
+
+*(B~ if none other used;
+ if C~ is last used: C~ or B~;
+ if D~ is used: D~, C~ or B~)
+.fi
+
+.nf
+- level A~ is the tile and is mandatory
+- there can only be one level A~
+
+- heading levels BCD, are optional and there may be several of each
+ (where all three are used corresponding to e.g. Book Part Section)
+ * sublevels that are used must follow each other sequentially
+ (alphabetically),
+- heading levels A~ B~ C~ D~ are followed by other heading levels rather
+ than substantive text
+ which may be the subsequent sequential (alphabetic) heading part level
+ or a heading (segment) level 1~
+- there must be at least one heading (segment) level 1~
+ (the level on which the text is segmented, in a book would correspond
+ to the Chapter level)
+- additional heading levels 1~ 2~ 3~ are optional and there may be several
+ of each
+- heading levels 1~ 2~ 3~ are followed by text (which may be followed by
+ the same heading level)
+ and/or the next lower numeric heading level (followed by text)
+ or indeed return to the relevant part level
+ (as a corollary to the rules above substantive text/ content
+ must be preceded by a level 1~ (2~ or 3~) heading)
+.fi
+
+.SH MARKUP EXAMPLES
+
+.SH ONLINE
+
+
+.BR
+Online markup examples are available together with the respective outputs
+produced from <http://www.jus.uio.no/sisu/SiSU/examples.html> or from
+<http://www.jus.uio.no/sisu/sisu_examples/>
+
+.BR
+There is of course this document, which provides a cursory overview of sisu
+markup and the respective output produced:
+<http://www.jus.uio.no/sisu/sisu_markup/>
+
+.BR
+an alternative presentation of markup syntax:
+/usr/share/doc/sisu/on_markup.txt.gz
+.SH INSTALLED
+
+
+.BR
+With
+.B SiSU
+installed sample skins may be found in: /usr/share/doc/sisu/markup-samples (or
+equivalent directory) and if sisu -markup-samples is installed also under:
+/usr/share/doc/sisu/markup-samples-non-free
+
+.SH MARKUP OF HEADERS
+
+.BR
+Headers contain either: semantic meta-data about a document, which can be used
+by any output module of the program, or; processing instructions.
+
+.BR
+Note: the first line of a document may include information on the markup
+version used in the form of a comment. Comments are a percentage mark at the
+start of a paragraph (and as the first character in a line of text) followed by
+a space and the comment:
+.nf
+% this would be a comment
+.fi
+
+.SH SAMPLE HEADER
+
+
+.BR
+This current document is loaded by a master document that has a header similar
+to this one:
+.nf
+% SiSU master 4.0
+
+title: SiSU
+ subtitle: Manual
+
+creator:
+ author: Amissah, Ralph
+
+publisher: [publisher name]
+
+rights: Copyright (C) Ralph Amissah 2007, part of SiSU documentation, License GPL 3
+
+classify:
+ topic_register: SiSU:manual;electronic documents:SiSU:manual
+ subject: ebook, epublishing, electronic book, electronic publishing,
+ electronic document, electronic citation, data structure,
+ citation systems, search
+
+% used_by: manual
+
+date:
+ published: 2008-05-22
+ created: 2002-08-28
+ issued: 2002-08-28
+ available: 2002-08-28
+ modified: 2010-03-03
+
+make:
+ num_top: 1
+ breaks: new=C; break=1
+ bold: /Gnu|Debian|Ruby|SiSU/
+ home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+ footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+ manpage: name=sisu - documents: markup, structuring, publishing in multiple standard formats, and search;
+ synopsis=sisu [-abcDdeFhIiMmNnopqRrSsTtUuVvwXxYyZz0-9] [filename/wildcard ]
+ . sisu [-Ddcv] [instruction]
+ . sisu [-CcFLSVvW]
+
+@links:
+ { SiSU Homepage }http://www.sisudoc.org/
+ { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/
+ { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html
+ { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html
+ { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html
+ { SiSU Git repo }http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary
+ { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/
+ { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html
+ { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org
+ { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU
+.fi
+
+.SH AVAILABLE HEADERS
+
+
+.BR
+Header tags appear at the beginning of a document and provide meta information
+on the document (such as the
+.I Dublin Core
+) , or information as to how the document as a whole is to be processed. All
+header instructions take the form @headername: or on the next line and indented
+by once space :subheadername: All
+.I Dublin Core
+meta tags are available
+
+.BR
+
+.B @identifier:
+information or instructions
+
+.BR
+where the "identifier" is a tag recognised by the program, and the
+"information" or "instructions" belong to the tag/identifier specified
+
+.BR
+Note: a header where used should only be used once; all headers apart from
+@title: are optional; the @structure: header is used to describe document
+structure, and can be useful to know.
+
+.BR
+This is a sample header
+.nf
+% SiSU 2.0 [declared file-type identifier with markup version]
+.fi
+
+.nf
+@title: [title text] [this header is the only one that is mandatory]
+ subtitle: [subtitle if any]
+ language: English
+.fi
+
+.nf
+creator:
+ author: [Lastname, First names]
+ illustrator: [Lastname, First names]
+ translator: [Lastname, First names]
+ prepared_by: [Lastname, First names]
+.fi
+
+.nf
+date:
+ published: [year or yyyy-mm-dd]
+ created: [year or yyyy-mm-dd]
+ issued: [year or yyyy-mm-dd]
+ available: [year or yyyy-mm-dd]
+ modified: [year or yyyy-mm-dd]
+ valid: [year or yyyy-mm-dd]
+ added_to_site: [year or yyyy-mm-dd]
+ translated: [year or yyyy-mm-dd]
+.fi
+
+.nf
+rights:
+ copyright: Copyright (C) [Year and Holder]
+ license: [Use License granted]
+ text: [Year and Holder]
+ translation: [Name, Year]
+ illustrations: [Name, Year]
+.fi
+
+.nf
+classify:
+ topic_register: SiSU:markup sample:book;book:novel:fantasy
+ type:
+ subject:
+ description:
+ keywords:
+ abstract:
+ loc: [Library of Congress classification]
+ dewey: [Dewey classification
+.fi
+
+.nf
+identify:
+ :isbn: [ISBN]
+ :oclc:
+.fi
+
+.nf
+links: { SiSU }http://www.sisudoc.org
+ { FSF }http://www.fsf.org
+.fi
+
+.nf
+make:
+ num_top: 1
+ headings: [text to match for each level
+ (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
+ breaks: new=:C; break=1
+ promo: sisu, ruby, sisu_search_libre, open_society
+ bold: [regular expression of words/phrases to be made bold]
+ italics: [regular expression of words/phrases to italicise]
+ home_button_text: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+ footer: {SiSU}http://sisudoc.org; {git}http://git.sisudoc.org
+.fi
+
+.nf
+original:
+ language: [language]
+.fi
+
+.nf
+notes:
+ comment:
+ prefix: [prefix is placed just after table of contents]
+.fi
+
+.SH MARKUP OF SUBSTANTIVE TEXT
+
+.SH HEADING LEVELS
+
+
+.BR
+Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
+headings, followed by other heading levels, and 1 -6 being headings followed by
+substantive text or sub-headings. :A~ usually the title :A~? conditional level
+1 heading (used where a stand-alone document may be imported into another)
+
+.BR
+
+.B :A~ [heading text]
+Top level heading [this usually has similar content to the title @title: ]
+NOTE: the heading levels described here are in 0.38 notation, see heading
+
+.BR
+
+.B :B~ [heading text]
+Second level heading [this is a heading level divider]
+
+.BR
+
+.B :C~ [heading text]
+Third level heading [this is a heading level divider]
+
+.BR
+
+.B 1~ [heading text]
+Top level heading preceding substantive text of document or sub-heading 2, the
+heading level that would normally be marked 1. or 2. or 3. etc. in a document,
+and the level on which sisu by default would break html output into named
+segments, names are provided automatically if none are given (a number),
+otherwise takes the form 1~my_filename_for_this_segment
+
+.BR
+
+.B 2~ [heading text]
+Second level heading preceding substantive text of document or sub-heading 3 ,
+the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc.
+in a document.
+
+.BR
+
+.B 3~ [heading text]
+Third level heading preceding substantive text of document, that would normally
+be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
+.nf
+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)
+.fi
+
+.SH FONT ATTRIBUTES
+
+.BR
+
+.B markup example:
+.nf
+normal text, *{emphasis}*, !{bold text}!, /{italics}/, _{underscore}_, "{citation}",
+^{superscript}^, ,{subscript},, +{inserted text}+, -{strikethrough}-, #{monospace}#
+
+normal text
+
+*{emphasis}* [note: can be configured to be represented by bold, italics or underscore]
+
+!{bold text}!
+
+/{italics}/
+
+_{underscore}_
+
+"{citation}"
+
+^{superscript}^
+
+,{subscript},
+
++{inserted text}+
+
+-{strikethrough}-
+
+#{monospace}#
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text,
+.B emphasis,
+.B bold text
+,
+.I italics,
+.I underscore,
+"citation", ^superscript^, [subscript], ++inserted text++, --strikethrough--,
+monospace
+
+.BR
+normal text
+
+.BR
+
+.B emphasis
+[note: can be configured to be represented by bold, italics or underscore]
+
+.BR
+
+.B bold text
+
+.BR
+
+.I italics
+
+.BR
+.I underscore
+
+.BR
+"citation"
+
+.BR
+^superscript^
+
+.BR
+[subscript]
+
+.BR
+++inserted text++
+
+.BR
+--strikethrough--
+
+.BR
+monospace
+.SH INDENTATION AND BULLETS
+
+
+.BR
+
+.B markup example:
+.nf
+ordinary paragraph
+
+_1 indent paragraph one step
+
+_2 indent paragraph two steps
+
+_9 indent paragraph nine steps
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+ordinary paragraph
+
+.BR
+ indent paragraph one step
+
+.BR
+ indent paragraph two steps
+
+.BR
+ indent paragraph nine steps
+
+.BR
+
+.B markup example:
+.nf
+_* bullet text
+
+_1* bullet text, first indent
+
+_2* bullet text, two step indent
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+- bullet text
+
+.BR
+ * bullet text, first indent
+
+.BR
+ * bullet text, two step indent
+
+.BR
+Numbered List (not to be confused with headings/titles, (document structure))
+
+.BR
+
+.B markup example:
+.nf
+# numbered list numbered list 1., 2., 3, etc.
+
+_# numbered list numbered list indented a., b., c., d., etc.
+.fi
+
+.SH HANGING INDENTS
+
+
+.BR
+
+.B markup example:
+.nf
+_0_1 first line no indent,
+rest of paragraph indented one step
+
+_1_0 first line indented,
+rest of paragraph no indent
+
+in each case level may be 0-9
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+first line no indent, rest of paragraph indented one step; first line no
+ indent, rest of paragraph indented one step; first line no indent, rest of
+ paragraph indented one step; first line no indent, rest of paragraph indented
+ one step; first line no indent, rest of paragraph indented one step; first
+ line no indent, rest of paragraph indented one step; first line no indent,
+ rest of paragraph indented one step; first line no indent, rest of paragraph
+ indented one step; first line no indent, rest of paragraph indented one step;
+
+.BR
+A regular paragraph.
+
+.BR
+first line indented, rest of paragraph no indent first line indented, rest of
+paragraph no indent first line indented, rest of paragraph no indent first line
+indented, rest of paragraph no indent first line indented, rest of paragraph no
+indent first line indented, rest of paragraph no indent first line indented,
+rest of paragraph no indent first line indented, rest of paragraph no indent
+first line indented, rest of paragraph no indent first line indented, rest of
+paragraph no indent first line indented, rest of paragraph no indent
+
+.BR
+in each case level may be 0-9
+
+.BR
+
+.B live-build
+ A collection of scripts used to build customized
+.B Debian
+ Livesystems.
+ .I live-build
+ was formerly known as live-helper, and even earlier known as live-package.
+
+.BR
+
+.B live-build
+
+ A collection of scripts used to build customized
+.B Debian
+ Livesystems.
+.I live-build
+ was formerly known as live-helper, and even earlier known as live-package.
+.SH FOOTNOTES / ENDNOTES
+
+
+.BR
+Footnotes and endnotes are marked up at the location where they would be
+indicated within a text. They are automatically numbered. The output type
+determines whether footnotes or endnotes will be produced
+
+.BR
+
+.B markup example:
+.nf
+~{ a footnote or endnote }~
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+[^5]
+
+.BR
+
+.B markup example:
+.nf
+normal text~{ self contained endnote marker & endnote in one }~ continues
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text[^6] continues
+
+.BR
+
+.B markup example:
+.nf
+normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+
+normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text [^*] continues
+
+.BR
+normal text [^**] continues
+
+.BR
+
+.B markup example:
+.nf
+normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text [^*3] continues
+
+.BR
+normal text [^+2] continues
+
+.BR
+
+.B Alternative endnote pair notation for footnotes/endnotes:
+.nf
+% note the endnote marker "~^"
+
+normal text~^ continues
+
+^~ endnote text following the paragraph in which the marker occurs
+.fi
+
+
+.BR
+the standard and pair notation cannot be mixed in the same document
+.SH LINKS
+
+.SH NAKED URLS WITHIN TEXT, DEALING WITH URLS
+
+
+.BR
+urls found within text are marked up automatically. A url within text is
+automatically hyperlinked to itself and by default decorated with angled
+braces, unless they are contained within a code block (in which case they are
+passed as normal text), or escaped by a preceding underscore (in which case the
+decoration is omitted).
+
+.BR
+
+.B markup example:
+.nf
+normal text http://www.sisudoc.org/ continues
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text <http://www.sisudoc.org/> continues
+
+.BR
+An escaped url without decoration
+
+.BR
+
+.B markup example:
+.nf
+normal text _http://www.sisudoc.org/ continues
+
+deb _http://www.jus.uio.no/sisu/archive unstable main non-free
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+normal text <_http://www.sisudoc.org/> continues
+
+.BR
+deb <_http://www.jus.uio.no/sisu/archive> unstable main non-free
+
+.BR
+where a code block is used there is neither decoration nor hyperlinking, code
+blocks are discussed later in this document
+
+.BR
+
+.B resulting output:
+.nf
+deb http://www.jus.uio.no/sisu/archive unstable main non-free
+deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+.fi
+
+.SH LINKING TEXT
+
+
+.BR
+To link text or an image to a url the markup is as follows
+
+.BR
+
+.B markup example:
+.nf
+about { SiSU }http://url.org markup
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+aboutSiSU <http://www.sisudoc.org/> markup
+
+.BR
+A shortcut notation is available so the url link may also be provided
+automatically as a footnote
+
+.BR
+
+.B markup example:
+.nf
+about {~^ SiSU }http://url.org markup
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+aboutSiSU <http://www.sisudoc.org/> [^7] markup
+
+.BR
+Internal document links to a tagged location, including an ocn
+
+.BR
+
+.B markup example:
+.nf
+about { text links }#link_text
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+about ⌠text links⌡⌈link_text⌋
+
+.BR
+Shared document collection link
+
+.BR
+
+.B markup example:
+.nf
+about { SiSU book markup examples }:SiSU/examples.html
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+about ⌠
+.B SiSU
+book markup examples⌡⌈:SiSU/examples.html⌋
+.SH LINKING IMAGES
+
+
+.BR
+
+.B markup example:
+.nf
+{ tux.png 64x80 }image
+
+% various url linked images
+
+{tux.png 64x80 "a better way" }http://www.sisudoc.org/
+
+{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian and Ruby" }http://www.sisudoc.org/
+
+{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+[ tux.png ]
+
+.BR
+tux.png 64x80 "Gnu/Linux - a better way" <http://www.sisudoc.org/>
+
+.BR
+GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
+and Ruby" <http://www.sisudoc.org/>
+
+.BR
+ruby_logo.png 70x90 "Ruby" <http://www.ruby-lang.org/en/> [^8]
+
+.BR
+
+.B linked url footnote shortcut
+.nf
+{~^ [text to link] }http://url.org
+
+% maps to: { [text to link] }http://url.org ~{ http://url.org }~
+
+% which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
+.fi
+
+.nf
+text marker *~name
+.fi
+
+
+.BR
+note at a heading level the same is automatically achieved by providing names
+to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
+auto-heading numbering, without further intervention.
+.SH LINK SHORTCUT FOR MULTIPLE VERSIONS OF A SISU DOCUMENT IN THE SAME DIRECTORY
+TREE
+
+
+.BR
+
+.B markup example:
+.nf
+!_ /{"Viral Spiral"}/, David Bollier
+
+{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
+.fi
+
+
+.BR
+
+.B
+.I "Viral Spiral",
+David Bollier
+"Viral Spiral", David Bollier <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
+ document manifest <http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html>
+ ⌠html, segmented text⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
+ ⌠html, scroll, document in one⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
+ ⌠epub⌡「http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」
+ ⌠pdf, landscape⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
+ ⌠pdf, portrait⌡「http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」
+ ⌠odf: odt, open document text⌡「http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」
+ ⌠xhtml scroll⌡「http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」
+ ⌠xml, sax⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
+ ⌠xml, dom⌡「http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」
+ ⌠concordance⌡「http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」
+ ⌠dcc, document content certificate (digests)⌡「http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」
+ ⌠markup source text⌡「http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」
+ ⌠markup source (zipped) pod⌡「http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」
+
+.SH GROUPED TEXT / BLOCKED TEXT
+
+
+.BR
+There are two markup syntaxes for blocked text, using curly braces or using
+tics
+.SH BLOCKED TEXT CURLY BRACE SYNTAX
+
+
+.BR
+at the start of a line on its own use name of block type with an opening curly
+brace, follow with the content of the block, and close with a closing curly
+brace and the name of the block type, e.g.
+.nf
+code{
+
+this is a code block
+
+}code
+.fi
+
+.nf
+
+poem{
+
+this here is a poem
+
+}poem
+.fi
+
+.SH BLOCKED TEXT TIC SYNTAX
+
+.nf
+``` code
+this is a code block
+
+```
+
+``` poem
+this here is a poem
+
+```
+.fi
+
+
+.BR
+start a line with three backtics, a space followed by the name of the name of
+block type, follow with the content of the block, and close with three back
+ticks on a line of their own, e.g.
+.SH TABLES
+
+
+.BR
+Tables may be prepared in two either of two forms
+
+.BR
+
+.B markup example:
+.nf
+table{ c3; 40; 30; 30;
+
+This is a table
+this would become column two of row one
+column three of row one is here
+
+And here begins another row
+column two of row two
+column three of row two, and so on
+
+}table
+.fi
+
+
+.BR
+
+.B resulting output:
+This is a table|this would become column two of row one|column three of row one is here』And here begins another row|column two of row two|column three of row two, and so on』
+
+
+.BR
+a second form may be easier to work with in cases where there is not much
+information in each column
+
+.BR
+
+.B markup example:
+[^9]
+.nf
+!_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
+
+{table~h 24; 12; 12; 12; 12; 12; 12;}
+ |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
+Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
+Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
+Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
+No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
+No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
+
+- Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+
+.B Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
+|Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006』Contributors*|10|472|2,188|9,653|25,011|48,721』Active contributors**|9|212|846|3,228|8,442|16,945』Very active contributors***|0|31|190|692|1,639|3,016』No. of English language articles|25|16,000|101,000|190,000|320,000|630,000』No. of articles, all languages|25|19,000|138,000|490,000|862,000|1,600,000』
+
+
+.BR
+- Contributed at least ten times; ** at least 5 times in last month; *** more
+than 100 times in last month.
+.SH POEM
+
+
+.BR
+
+.B basic markup:
+.nf
+poem{
+
+ Your poem here
+
+}poem
+
+Each verse in a poem is given an object number.
+.fi
+
+
+.BR
+
+.B markup example:
+.nf
+poem{
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+}poem
+.fi
+
+
+.BR
+
+.B resulting output:
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+
+.SH GROUP
+
+
+.BR
+
+.B basic markup:
+.nf
+group{
+
+ Your grouped text here
+
+}group
+
+A group is treated as an object and given a single object number.
+.fi
+
+
+.BR
+
+.B markup example:
+.nf
+group{
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+}group
+.fi
+
+
+.BR
+
+.B resulting output:
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+
+.SH CODE
+
+
+.BR
+Code tags code{ ... }code (used as with other group tags described above) are
+used to escape regular sisu markup, and have been used extensively within this
+document to provide examples of
+.B SiSU
+markup. You cannot however use code tags to escape code tags. They are however
+used in the same way as group or poem tags.
+
+.BR
+A code-block is treated as an object and given a single object number. [an
+option to number each line of code may be considered at some later time]
+
+.BR
+
+.B use of code tags instead of poem compared, resulting output:
+.nf
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+.fi
+
+
+.BR
+From
+.B SiSU
+2.7.7 on you can number codeblocks by placing a hash after the opening code tag
+code{# as demonstrated here:
+.nf
+1 | `Fury said to a
+2 | mouse, That he
+3 | met in the
+4 | house,
+5 | "Let us
+6 | both go to
+7 | law: I will
+8 | prosecute
+9 | YOU. --Come,
+10 | I'll take no
+11 | denial; We
+12 | must have a
+13 | trial: For
+14 | really this
+15 | morning I've
+16 | nothing
+17 | to do."
+18 | Said the
+19 | mouse to the
+20 | cur, "Such
+21 | a trial,
+22 | dear Sir,
+23 | With
+24 | no jury
+25 | or judge,
+26 | would be
+27 | wasting
+28 | our
+29 | breath."
+30 | "I'll be
+31 | judge, I'll
+32 | be jury,"
+33 | Said
+34 | cunning
+35 | old Fury:
+36 | "I'll
+37 | try the
+38 | whole
+39 | cause,
+40 | and
+41 | condemn
+42 | you
+43 | to
+44 | death."'
+.fi
+
+.SH ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
+
+.SH LINE-BREAKS
+
+
+.BR
+To break a line within a "paragraph object", two backslashes \e\e
+with a space before and a space or newline after them
+may be used.
+.nf
+To break a line within a "paragraph object",
+two backslashes \e\e with a space before
+and a space or newline after them \e\e
+may be used.
+.fi
+
+
+.BR
+The html break br enclosed in angle brackets (though undocumented) is available
+in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
+but is depreciated).
+
+.BR
+To draw a dividing line dividing paragraphs, see the section on page breaks.
+.SH PAGE BREAKS
+
+
+.BR
+Page breaks are only relevant and honored in some output formats. A page break
+or a new page may be inserted manually using the following markup on a line on
+its own:
+
+.BR
+page new =\e= breaks the page, starts a new page.
+
+.BR
+page break -\- breaks a column, starts a new column, if using columns, else
+breaks the page, starts a new page.
+
+.BR
+page break line across page -..- draws a dividing line, dividing paragraphs
+
+.BR
+page break:
+.nf
+-\e\e-
+.fi
+
+
+.BR
+page (break) new:
+.nf
+=\e\e=
+.fi
+
+
+.BR
+page (break) line across page (dividing paragraphs):
+.nf
+-..-
+.fi
+
+.SH BIBLIOGRAPHY / REFERENCES
+
+
+.BR
+There are three ways to prepare a bibliography using sisu (which are mutually
+exclusive): (i) manually preparing and marking up as regular text in sisu a
+list of references, this is treated as a regular document segment (and placed
+before endnotes if any); (ii) preparing a bibliography, marking a heading level
+1~!biblio (note the exclamation mark) and preparing a bibliography using
+various metadata tags including for author: title: year: a list of which is
+provided below, or; (iii) as an assistance in preparing a bibliography, marking
+a heading level 1~!biblio and tagging citations within footnotes for inclusion,
+identifying citations and having a parser attempt to extract them and build a
+bibliography of the citations provided.
+
+.BR
+For the heading/section sequence: endnotes, bibliography then book index to
+occur, the name biblio or bibliography must be given to the bibliography
+section, like so:
+.nf
+1~!biblio~ [Note: heading marker::required title missing]
+.fi
+
+.SH A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
+
+
+.BR
+Here instead of writing your full citations directly in footnotes, each time
+you have new material to cite, you add it to your bibliography section (if it
+has not been added yet) providing the information you need against an available
+list of tags (provided below).
+
+.BR
+The required tags are au: ti: and year: [^10] an short quick example might be
+as follows:
+.nf
+1~!biblio~ [Note: heading marker::required title missing]
+
+au: von Hippel, E.
+ti: Perspective: User Toolkits for Innovation
+lng: (language)
+jo: Journal of Product Innovation Management
+vo: 18
+ed: (editor)
+yr: 2001
+note:
+sn: Hippel, /{User Toolkits}/ (2001)
+id: vHippel_2001
+% form:
+
+au: Benkler, Yochai
+ti: The Wealth of Networks
+st: How Social Production Transforms Markets and Freedom
+lng: (language)
+pb: Harvard University Press
+edn: (edition)
+yr: 2006
+pl: U.S.
+url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
+note:
+sn: Benkler, /{Wealth of Networks}/ (2006)
+id: Benkler2006
+
+au: Quixote, Don; Panza, Sancho
+ti: Taming Windmills, Keeping True
+jo: Imaginary Journal
+yr: 1605
+url: https://en.wikipedia.org/wiki/Don_Quixote
+note: made up to provide an example of author markup for an article with two authors
+sn: Quixote & Panza, /{Taming Windmills}/ (1605)
+id: quixote1605
+.fi
+
+
+.BR
+Note that the section name !biblio (or !bibliography) is required for the
+bibliography to be treated specially as such, and placed after the
+auto-generated endnote section.
+
+.BR
+Using this method, work goes into preparing the bibliography, the tags author
+or editor, year and title are required and will be used to sort the
+bibliography that is placed under the Bibliography section
+
+.BR
+The metadata tags may include shortname (sn:) and id, if provided, which are
+used for substitution within text. Every time the given id is found within the
+text it will be replaced by the given short title of the work (it is for this
+reason the short title has sisu markup to italicize the title), it should work
+with any page numbers to be added, the short title should be one that can
+easily be used to look up the full description in the bibliography.
+.nf
+The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
+.fi
+
+
+.BR
+would be presented as:
+
+.BR
+Quixote and Panza,
+.I Taming Windmills
+(1605), pp 1000 - 1001 also, Benkler,
+.I Wealth of Networks,
+(2006) p 1 or rather[^11]
+.nf
+au: author Surname, FirstNames (if multiple semi-colon separator)
+ (required unless editor to be used instead)
+ti: title (required)
+st: subtitle
+jo: journal
+vo: volume
+ed: editor (required if author not provided)
+tr: translator
+src: source (generic field where others are not appropriate)
+in: in (like src)
+pl: place/location (state, country)
+pb: publisher
+edn: edition
+yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required)
+pg: pages
+url: http://url
+note: note
+id: create_short_identifier e.g. authorSurnameYear
+ (used in substitutions: when found within text will be
+ replaced by the short name provided)
+sn: short name e.g. Author, /{short title}/, Year
+ (used in substitutions: when an id is found within text
+ the short name will be used to replace it)
+.fi
+
+.SH TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY
+
+
+.BR
+Here whenever you make a citation that you wish be included in the
+bibliography, you tag the citation as such using special delimiters (which are
+subsequently removed from the final text produced by sisu)
+
+.BR
+Here you would write something like the following, either in regular text or a
+footnote
+.nf
+See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
+.fi
+
+
+.BR
+
+.B SiSU
+will parse for a number of patterns within the delimiters to try make out the
+authors, title, date etc. and from that create a Bibliography. This is more
+limited than the previously described method of preparing a tagged
+bibliography, and using an id within text to identify the work, which also
+lends itself to greater consistency.
+.SH GLOSSARY
+
+
+.BR
+Using the section name 1~!glossary results in the Glossary being treated
+specially as such, and placed after the auto-generated endnote section (before
+the bibliography/list of references if there is one).
+
+.BR
+The Glossary is ordinary text marked up in a manner deemed suitable for that
+purpose. e.g. with the term in bold, possibly with a hanging indent.
+.nf
+1~!glossary~ [Note: heading marker::required title missing]
+
+_0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ...
+
+_0_1 [provide your list of terms and definitions]
+.fi
+
+
+.BR
+In the given example the first line is not indented subsequent lines are by one
+level, and the term to be defined is in bold text.
+.SH BOOK INDEX
+
+
+.BR
+To make an index append to paragraph the book index term relates to it, using
+an equal sign and curly braces.
+
+.BR
+Currently two levels are provided, a main term and if needed a sub-term.
+Sub-terms are separated from the main term by a colon.
+.nf
+ Paragraph containing main term and sub-term.
+ ={Main term:sub-term}
+.fi
+
+
+.BR
+The index syntax starts on a new line, but there should not be an empty line
+between paragraph and index markup.
+
+.BR
+The structure of the resulting index would be:
+.nf
+ Main term, 1
+ sub-term, 1
+.fi
+
+
+.BR
+Several terms may relate to a paragraph, they are separated by a semicolon. If
+the term refers to more than one paragraph, indicate the number of paragraphs.
+.nf
+ Paragraph containing main term, second term and sub-term.
+ ={first term; second term: sub-term}
+.fi
+
+
+.BR
+The structure of the resulting index would be:
+.nf
+ First term, 1,
+ Second term, 1,
+ sub-term, 1
+.fi
+
+
+.BR
+If multiple sub-terms appear under one paragraph, they are separated under the
+main term heading from each other by a pipe symbol.
+.nf
+ Paragraph containing main term, second term and sub-term.
+ ={Main term:
+ sub-term+2|second sub-term;
+ Another term
+ }
+
+ A paragraph that continues discussion of the first sub-term
+.fi
+
+
+.BR
+The plus one in the example provided indicates the first sub-term spans one
+additional paragraph. The logical structure of the resulting index would be:
+.nf
+ Main term, 1,
+ sub-term, 1-3,
+ second sub-term, 1,
+ Another term, 1
+.fi
+
+.SH COMPOSITE DOCUMENTS MARKUP
+
+
+.BR
+It is possible to build a document by creating a master document that requires
+other documents. The documents required may be complete documents that could be
+generated independently, or they could be markup snippets, prepared so as to be
+easily available to be placed within another text. If the calling document is a
+master document (built from other documents), it should be named with the
+suffix
+.B .ssm
+Within this document you would provide information on the other documents that
+should be included within the text. These may be other documents that would be
+processed in a regular way, or markup bits prepared only for inclusion within a
+master document
+.B .sst
+regular markup file, or
+.B .ssi
+(insert/information) A secondary file of the composite document is built prior
+to processing with the same prefix and the suffix
+.B ._sst
+
+.BR
+basic markup for importing a document into a master document
+.nf
+<< filename1.sst
+
+<< filename2.ssi
+.fi
+
+
+.BR
+The form described above should be relied on. Within the
+.I Vim
+editor it results in the text thus linked becoming hyperlinked to the document
+it is calling in which is convenient for editing.
+.SH SUBSTITUTIONS
+
+
+.BR
+
+.B markup example:
+.nf
+The current Debian is ${debian_stable} the next debian will be ${debian_testing}
+
+Configure substitution in _sisu/sisu_document_make
+
+make:
+ substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
+.fi
+
+
+.BR
+
+.B resulting output:
+
+.BR
+The current
+.B Debian
+is
+.B Jessie
+the next debian will be
+.B Stretch
+
+.BR
+Configure substitution in _sisu/sisu_document_make
+.SH SISU FILETYPES
+
+
+.BR
+
+.B SiSU
+has
+.I plaintext
+and binary filetypes, and can process either type of document.
+.SH .SST .SSM .SSI MARKED UP PLAIN TEXT
+
+.TP
+.B SiSU
+documents are prepared as plain-text (utf-8) files with
+.B SiSU
+markup. They may make reference to and contain images (for example), which are
+stored in the directory beneath them _sisu/image. 〔b¤SiSU
+.I plaintext
+markup files are of three types that may be distinguished by the file extension
+used: regular text .sst; master documents, composite documents that incorporate
+other text, which can be any regular text or text insert; and inserts the
+contents of which are like regular text except these are marked .ssi and are
+not processed.
+
+.BR
+
+.B SiSU
+processing can be done directly against a sisu documents; which may be located
+locally or on a remote server for which a url is provided.
+
+.BR
+
+.B SiSU
+source markup can be shared with the command:
+
+.BR
+ sisu -s [filename]
+.SH SISU TEXT - REGULAR FILES (.SST)
+
+
+.BR
+The most common form of document in
+.B SiSU,
+see the section on
+.B SiSU
+markup.
+.SH SISU MASTER FILES (.SSM)
+
+
+.BR
+Composite documents which incorporate other
+.B SiSU
+documents which may be either regular
+.B SiSU
+text .sst which may be generated independently, or inserts prepared solely for
+the purpose of being incorporated into one or more master documents.
+
+.BR
+The mechanism by which master files incorporate other documents is described as
+one of the headings under under
+.B SiSU
+markup in the
+.B SiSU
+manual.
+
+.BR
+Note: Master documents may be prepared in a similar way to regular documents,
+and processing will occur normally if a .sst file is renamed .ssm without
+requiring any other documents; the .ssm marker flags that the document may
+contain other documents.
+
+.BR
+Note: a secondary file of the composite document is built prior to processing
+with the same prefix and the suffix ._sst
+.SH SISU INSERT FILES (.SSI)
+
+
+.BR
+Inserts are documents prepared solely for the purpose of being incorporated
+into one or more master documents. They resemble regular
+.B SiSU
+text files (.sst). Since sisu -5.5.0 (6.1.0) .ssi files can like .ssm files
+include other .sst or .ssm files. .ssi files cannot be called by the sisu
+processor directly and can only be incorporated in other documents. Making a
+file a .ssi file is a quick and convenient way of breaking up a document that
+is to be included in a master document, and flagging that the file to be
+incorporated .ssi is not intended that the file should be processed on its own.
+.SH SISUPOD, ZIPPED BINARY CONTAINER (SISUPOD.ZIP, .SSP)
+
+
+.BR
+A sisupod is a zipped
+.B SiSU
+text file or set of
+.B SiSU
+text files and any associated images that they contain (this will be extended
+to include sound and multimedia-files)
+.TP
+.B SiSU
+.I plaintext
+files rely on a recognised directory structure to find contents such as images
+associated with documents, but all images for example for all documents
+contained in a directory are located in the sub-directory _sisu/image. Without
+the ability to create a sisupod it can be inconvenient to manually identify all
+other files associated with a document. A sisupod automatically bundles all
+associated files with the document that is turned into a pod.
+
+.BR
+The structure of the sisupod is such that it may for example contain a single
+document and its associated images; a master document and its associated
+documents and anything else; or the zipped contents of a whole directory of
+prepared
+.B SiSU
+documents.
+
+.BR
+The command to create a sisupod is:
+
+.BR
+ sisu -S [filename]
+
+.BR
+Alternatively, make a pod of the contents of a whole directory:
+
+.BR
+ sisu -S
+
+.BR
+
+.B SiSU
+processing can be done directly against a sisupod; which may be located locally
+or on a remote server for which a url is provided.
+
+.BR
+<http://www.sisudoc.org/sisu/sisu_commands>
+
+.BR
+<http://www.sisudoc.org/sisu/sisu_manual>
+.SH CONFIGURATION
+
+.SH CONFIGURATION FILES
+
+.SH CONFIG.YML
+
+
+.BR
+
+.B SiSU
+configration parameters are adjusted in the configuration file, which can be
+used to override the defaults set. This includes such things as which directory
+interim processing should be done in and where the generated output should be
+placed.
+
+.BR
+The
+.B SiSU
+configuration file is a yaml file, which means indentation is significant.
+
+.BR
+
+.B SiSU
+resource configuration is determined by looking at the following files if they
+exist:
+
+.BR
+ ./_sisu/v7/sisurc.yml
+
+.BR
+ ./_sisu/sisurc.yml
+
+.BR
+ ~/.sisu/v7/sisurc.yml
+
+.BR
+ ~/.sisu/sisurc.yml
+
+.BR
+ /etc/sisu/v7/sisurc.yml
+
+.BR
+ /etc/sisu/sisurc.yml
+
+.BR
+The search is in the order listed, and the first one found is used.
+
+.BR
+In the absence of instructions in any of these it falls back to the internal
+program defaults.
+
+.BR
+Configuration determines the output and processing directories and the database
+access details.
+
+.BR
+If
+.B SiSU
+is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml
+.SH SISU_DOCUMENT_MAKE
+
+
+.BR
+Most sisu document headers relate to metadata, the exception is the @make:
+header which provides processing related information. The default contents of
+the @make header may be set by placing them in a file sisu_document_make.
+
+.BR
+The search order is as for resource configuration:
+
+.BR
+ ./_sisu/v7/sisu_document_make
+
+.BR
+ ./_sisu/sisu_document_make
+
+.BR
+ ~/.sisu/v7/sisu_document_make
+
+.BR
+ ~/.sisu/sisu_document_make
+
+.BR
+ /etc/sisu/v7/sisu_document_make
+
+.BR
+ /etc/sisu/sisu_document_make
+
+.BR
+A sample sisu_document_make can be found in the _sisu/ directory under along
+with the provided sisu markup samples.
+.SH CSS - CASCADING STYLE SHEETS (FOR HTML, XHTML AND XML)
+
+
+.BR
+CSS files to modify the appearance of
+.B SiSU
+html,
+.I XHTML
+or
+.I XML
+may be placed in the configuration directory: ./_sisu/css ; ~/.sisu/css or;
+/etc/sisu/css and these will be copied to the output directories with the
+command sisu -CC.
+
+.BR
+The basic CSS file for html output is html. css, placing a file of that name in
+directory _sisu/css or equivalent will result in the default file of that name
+being overwritten.
+
+.BR
+
+.I HTML:
+html. css
+
+.BR
+
+.I XML
+DOM: dom.css
+
+.BR
+
+.I XML
+SAX: sax.css
+
+.BR
+
+.I XHTML:
+xhtml. css
+
+.BR
+The default homepage may use homepage.css or html. css
+
+.BR
+Under consideration is to permit the placement of a CSS file with a different
+name in directory _sisu/css directory or equivalent.[^12]
+.SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING
+
+
+.BR
+
+.B SiSU
+v3 has new options for the source directory tree, and output directory
+structures of which there are 3 alternatives.
+.SH DOCUMENT SOURCE DIRECTORY
+
+
+.BR
+The document source directory is the directory in which sisu processing
+commands are given. It contains the sisu source files (.sst .ssm .ssi), or (for
+sisu v3 may contain) subdirectories with language codes which contain the sisu
+source files, so all English files would go in subdirectory en/, French in fr/,
+Spanish in es/ and so on. ISO 639-1 codes are used (as varied by po4a). A list
+of available languages (and possible sub-directory names) can be obtained with
+the command "sisu --help lang" The list of languages is limited to langagues
+supported by XeTeX polyglosia.
+.SH GENERAL DIRECTORIES
+
+.nf
+ ./subject_name/
+
+% files stored at this level e.g. sisu_manual.sst or
+% for sisu v3 may be under language sub-directories
+% e.g.
+
+ ./subject_name/en
+
+ ./subject_name/fr
+
+ ./subject_name/es
+
+ ./subject_name/_sisu
+
+ ./subject_name/_sisu/css
+
+ ./subject_name/_sisu/image
+.fi
+
+.SH DOCUMENT OUTPUT DIRECTORY STRUCTURES
+
+.SH OUTPUT DIRECTORY ROOT
+
+
+.BR
+The output directory root can be set in the sisurc.yml file. Under the root,
+subdirectories are made for each directory in which a document set resides. If
+you have a directory named poems or conventions, that directory will be created
+under the output directory root and the output for all documents contained in
+the directory of a particular name will be generated to subdirectories beneath
+that directory (poem or conventions). A document will be placed in a
+subdirectory of the same name as the document with the filetype identifier
+stripped (.sst .ssm)
+
+.BR
+The last part of a directory path, representing the sub-directory in which a
+document set resides, is the directory name that will be used for the output
+directory. This has implications for the organisation of document collections
+as it could make sense to place documents of a particular subject, or type
+within a directory identifying them. This grouping as suggested could be by
+subject (sales_law, english_literature); or just as conveniently by some other
+classification (X University). The mapping means it is also possible to place
+in the same output directory documents that are for organisational purposes
+kept separately, for example documents on a given subject of two different
+institutions may be kept in two different directories of the same name, under a
+directory named after each institution, and these would be output to the same
+output directory. Skins could be associated with each institution on a
+directory basis and resulting documents will take on the appropriate different
+appearance.
+.SH ALTERNATIVE OUTPUT STRUCTURES
+
+
+.BR
+There are 3 possibile output structures described as being, by language, by
+filetype or by filename, the selection is made in sisurc.yml
+.nf
+#% output_dir_structure_by: language; filetype; or filename
+output_dir_structure_by: language #(language & filetype, preferred?)
+#output_dir_structure_by: filetype
+#output_dir_structure_by: filename #(default, closest to original v1 & v2)
+.fi
+
+.SH BY LANGUAGE
+
+
+.BR
+The by language directory structure places output files
+
+.BR
+The by language directory structure separates output files by language code
+(all files of a given language), and within the language directory by filetype.
+
+.BR
+Its selection is configured in sisurc.yml
+
+.BR
+output_dir_structure_by: language
+.nf
+ |-- en
+ |-- epub
+ |-- hashes
+ |-- html
+ | |-- viral_spiral.david_bollier
+ | |-- manifest
+ | |-- qrcode
+ | |-- odt
+ | |-- pdf
+ | |-- sitemaps
+ | |-- txt
+ | |-- xhtml
+ | `-- xml
+ |-- po4a
+ | `-- live-manual
+ | |-- po
+ | |-- fr
+ | `-- pot
+ `-- _sisu
+ |-- css
+ |-- image
+ |-- image_sys -> ../../_sisu/image_sys
+ `-- xml
+ |-- rnc
+ |-- rng
+ `-- xsd
+.fi
+
+
+.BR
+#by: language subject_dir/en/manifest/filename.html
+.SH BY FILETYPE
+
+
+.BR
+The by filetype directory structure separates output files by filetype, all
+html files in one directory pdfs in another and so on. Filenames are given a
+language extension.
+
+.BR
+Its selection is configured in sisurc.yml
+
+.BR
+output_dir_structure_by: filetype
+.nf
+ |-- epub
+ |-- hashes
+ |-- html
+ |-- viral_spiral.david_bollier
+ |-- manifest
+ |-- qrcode
+ |-- odt
+ |-- pdf
+ |-- po4a
+ |-- live-manual
+ | |-- po
+ | |-- fr
+ | `-- pot
+ |-- _sisu
+ | |-- css
+ | |-- image
+ | |-- image_sys -> ../../_sisu/image_sys
+ | `-- xml
+ | |-- rnc
+ | |-- rng
+ | `-- xsd
+ |-- sitemaps
+ |-- txt
+ |-- xhtml
+ `-- xml
+.fi
+
+
+.BR
+#by: filetype subject_dir/html/filename/manifest.en.html
+.SH BY FILENAME
+
+
+.BR
+The by filename directory structure places most output of a particular file
+(the different filetypes) in a common directory.
+
+.BR
+Its selection is configured in sisurc.yml
+
+.BR
+output_dir_structure_by: filename
+.nf
+ |-- epub
+ |-- po4a
+ |-- live-manual
+ | |-- po
+ | |-- fr
+ | `-- pot
+ |-- _sisu
+ | |-- css
+ | |-- image
+ | |-- image_sys -> ../../_sisu/image_sys
+ | `-- xml
+ | |-- rnc
+ | |-- rng
+ | `-- xsd
+ |-- sitemaps
+ |-- src
+ |-- pod
+ `-- viral_spiral.david_bollier
+.fi
+
+
+.BR
+#by: filename subject_dir/filename/manifest.en.html
+.SH REMOTE DIRECTORIES
+
+.nf
+ ./subject_name/
+
+% containing sub_directories named after the generated files from which they are made
+
+ ./subject_name/src
+
+% contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip
+
+ ./subject_name/_sisu
+
+% configuration file e.g. sisurc.yml
+
+ ./subject_name/_sisu/skin
+
+% skins in various skin directories doc, dir, site, yml
+
+ ./subject_name/_sisu/css
+
+ ./subject_name/_sisu/image
+
+% images for documents contained in this directory
+
+ ./subject_name/_sisu/mm
+.fi
+
+.SH SISUPOD
+
+.nf
+ ./sisupod/
+
+% files stored at this level e.g. sisu_manual.sst
+
+ ./sisupod/_sisu
+
+% configuration file e.g. sisurc.yml
+
+ ./sisupod/_sisu/skin
+
+% skins in various skin directories doc, dir, site, yml
+
+ ./sisupod/_sisu/css
+
+ ./sisupod/_sisu/image
+
+% images for documents contained in this directory
+
+ ./sisupod/_sisu/mm
+.fi
+
+.SH HOMEPAGES
+
+
+.BR
+
+.B SiSU
+is about the ability to auto-generate documents. Home pages are regarded as
+custom built items, and are not created by
+.B SiSU.
+More accurately,
+.B SiSU
+has a default home page, which will not be appropriate for use with other
+sites, and the means to provide your own home page instead in one of two ways
+as part of a site's configuration, these being:
+
+.BR
+1. through placing your home page and other custom built documents in the
+subdirectory _sisu/home/ (this probably being the easier and more convenient
+option)
+
+.BR
+2. through providing what you want as the home page in a skin,
+
+.BR
+Document sets are contained in directories, usually organised by site or
+subject. Each directory can/should have its own homepage. See the section on
+directory structure and organisation of content.
+.SH HOME PAGE AND OTHER CUSTOM BUILT PAGES IN A SUB-DIRECTORY
+
+
+.BR
+Custom built pages, including the home page index.html may be placed within the
+configuration directory _sisu/home/ in any of the locations that is searched
+for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu From
+there they are copied to the root of the output directory with the command:
+
+.BR
+ sisu -CC
+.SH MARKUP AND OUTPUT EXAMPLES
+
+.SH MARKUP EXAMPLES
+
+
+.BR
+Current markup examples and document output samples are provided off
+<http://sisudoc.org> or <http://www.jus.uio.no/sisu> and in the sisu
+-markup-sample package available off <http://git.sisudoc.org>
+
+.BR
+For some documents hardly any markup at all is required at all, other than a
+header, and an indication that the levels to be taken into account by the
+program in generating its output are.
+.SH SISU MARKUP SAMPLES
+
+
+.BR
+A few additional sample books prepared as sisu markup samples, output formats
+to be generated using
+.B SiSU
+are contained in a separate package sisu -markup-samples. sisu -markup-samples
+contains books (prepared using sisu markup), that were released by their
+authors various licenses mostly different Creative Commons licences that do not
+permit inclusion in the
+.B Debian
+Project as they have requirements that do not meet the
+.B Debian
+Free Software Guidelines for various reasons, most commonly that they require
+that the original substantive text remain unchanged, and sometimes that the
+works be used only non-commercially.
+
+.BR
+
+.I Accelerando,
+Charles Stross (2005)
+accelerando.charles_stross.sst
+
+.BR
+
+.I Alice's Adventures in Wonderland,
+Lewis Carroll (1865)
+alices_adventures_in_wonderland.lewis_carroll.sst
+
+.BR
+
+.I CONTENT,
+Cory Doctorow (2008)
+content.cory_doctorow.sst
+
+.BR
+
+.I Democratizing Innovation,
+Eric von Hippel (2005)
+democratizing_innovation.eric_von_hippel.sst
+
+.BR
+
+.I Down and Out in the Magic Kingdom,
+Cory Doctorow (2003)
+down_and_out_in_the_magic_kingdom.cory_doctorow.sst
+
+.BR
+
+.I For the Win,
+Cory Doctorow (2010)
+for_the_win.cory_doctorow.sst
+
+.BR
+
+.I Free as in Freedom - Richard Stallman's Crusade for Free Software,
+Sam Williams (2002)
+free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst
+
+.BR
+
+.I Free as in Freedom 2.0 - Richard Stallman and the Free Software Revolution,
+Sam Williams (2002), Richard M. Stallman (2010)
+free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst
+
+.BR
+
+.I Free Culture - How Big Media Uses Technology and the Law to Lock Down
+Culture and Control Creativity,
+Lawrence Lessig (2004)
+free_culture.lawrence_lessig.sst
+
+.BR
+
+.I Free For All - How Linux and the Free Software Movement Undercut the High
+Tech Titans,
+Peter Wayner (2002)
+free_for_all.peter_wayner.sst
+
+.BR
+
+.I GNU GENERAL PUBLIC LICENSE v2,
+Free Software Foundation (1991)
+gpl2.fsf.sst
+
+.BR
+
+.I GNU GENERAL PUBLIC LICENSE v3,
+Free Software Foundation (2007)
+gpl3.fsf.sst
+
+.BR
+
+.I Gulliver's Travels,
+Jonathan Swift (1726 / 1735)
+gullivers_travels.jonathan_swift.sst
+
+.BR
+
+.I Little Brother,
+Cory Doctorow (2008)
+little_brother.cory_doctorow.sst
+
+.BR
+
+.I The Cathederal and the Bazaar,
+Eric Raymond (2000)
+the_cathedral_and_the_bazaar.eric_s_raymond.sst
+
+.BR
+
+.I The Public Domain - Enclosing the Commons of the Mind,
+James Boyle (2008)
+the_public_domain.james_boyle.sst
+
+.BR
+
+.I The Wealth of Networks - How Social Production Transforms Markets and
+Freedom,
+Yochai Benkler (2006)
+the_wealth_of_networks.yochai_benkler.sst
+
+.BR
+
+.I Through the Looking Glass,
+Lewis Carroll (1871)
+through_the_looking_glass.lewis_carroll.sst
+
+.BR
+
+.I Two Bits - The Cultural Significance of Free Software,
+Christopher Kelty (2008)
+two_bits.christopher_kelty.sst
+
+.BR
+
+.I UN Contracts for International Sale of Goods,
+UN (1980)
+un_contracts_international_sale_of_goods_convention_1980.sst
+
+.BR
+
+.I Viral Spiral,
+David Bollier (2008)
+viral_spiral.david_bollier.sst
+.SH SISU SEARCH - INTRODUCTION
+
+
+.BR
+Because the document structure of sites created is clearly defined, and the
+text
+.I object citation system
+is available hypothetically at least, for all forms of output, it is possible
+to search the sql database, and either read results from that database, or map
+the results to the html or other output, which has richer text markup.
+
+.BR
+
+.B SiSU
+can populate a relational sql type database with documents at an object level,
+including objects numbers that are shared across different output types. Making
+a document corpus searchable with that degree of granularity. Basically, your
+match criteria is met by these documents and at these locations within each
+document, which can be viewed within the database directly or in various output
+formats.
+
+.BR
+
+.B SiSU
+can populate an sql database (sqlite3 or postgresql) with documents made up of
+their objects. It also can generate a cgi search form that can be used to query
+the database.
+
+.BR
+In order to use the built in search functionality you would take the following
+steps.
+
+.BR
+- use sisu to populate an sql database with with a sisu markup content
+
+.BR
+ * sqlite3 should work out of the box
+
+.BR
+ * postgresql may require some initial database configuration
+
+.BR
+- provide a way to query the database, which sisu can assist with by
+
+.BR
+ * generating a sample ruby cgi search form, required (sisu configuration
+ recommended)
+
+.BR
+ * adding a query field for this search form to be added to all html files
+ (sisu configuration required)
+.SH SQL
+
+.SH POPULATE THE DATABASE
+
+
+.BR
+TO populate the sql database, run sisu against a sisu markup file with one of
+the following sets of flags
+.nf
+sisu --sqlite filename.sst
+.fi
+
+
+.BR
+creates an sqlite3 database containing searchable content of just the sisu
+markup document selected
+.nf
+sisu --sqlite --update filename.sst
+.fi
+
+
+.BR
+creates an sqlite3 database containing searchable content of marked up
+document(s) selected by the user from a common directory
+.nf
+sisu --pg --update filename.sst
+.fi
+
+
+.BR
+fills a postgresql database with searchable content of marked up document(s)
+selected by the user from a common directory
+
+.BR
+For postgresql the first time the command is run in a given directory the user
+will be prompted to create the requisite database, at the time of writing the
+prompt sisu provides is as follows:
+.nf
+no connection with pg database established, you may need to run:
+ createdb "SiSU.7a.current"
+ after that don't forget to run:
+ sisu --pg --createall
+ before attempting to populate the database
+.fi
+
+
+.BR
+The named database that sisu expects to find must exist and if necessary be
+created using postgresql tools. If the database exist but the database tables
+do not, sisu will attempt to create the tables it needs, the equivalent of the
+requested sisu --pg --createall command.
+
+.BR
+Once this is done, the sql database is populated and ready to be queried.
+.SH SQL TYPE DATABASES
+
+
+.BR
+
+.B SiSU
+feeds sisu markup documents into sql type databases
+.I PostgreSQL
+[^13] and/or
+.I SQLite
+[^14] database together with information related to document structure.
+
+.BR
+This is one of the more interesting output forms, as all the structural data of
+the documents are retained (though can be ignored by the user of the database
+should they so choose). All site texts/documents are (currently) streamed to
+four tables:
+
+.BR
+ * one containing semantic (and other) headers, including, title, author,
+ subject, (the
+ .I Dublin Core.
+ ..);
+
+.BR
+ * another the substantive texts by individual "paragraph" (or object) - along
+ with structural information, each paragraph being identifiable by its
+ paragraph number (if it has one which almost all of them do), and the
+ substantive text of each paragraph quite naturally being searchable (both in
+ formatted and clean text versions for searching); and
+
+.BR
+ * a third containing endnotes cross-referenced back to the paragraph from
+ which they are referenced (both in formatted and clean text versions for
+ searching).
+
+.BR
+ * a fourth table with a one to one relation with the headers table contains
+ full text versions of output, eg. pdf, html, xml, and
+ .I ascii.
+
+.BR
+There is of course the possibility to add further structures.
+
+.BR
+At this level
+.B SiSU
+loads a relational database with documents chunked into objects, their smallest
+logical structurally constituent parts, as text objects, with their object
+citation number and all other structural information needed to construct the
+document. Text is stored (at this text object level) with and without
+elementary markup tagging, the stripped version being so as to facilitate ease
+of searching.
+
+.BR
+Being able to search a relational database at an object level with the
+.B SiSU
+citation system is an effective way of locating content generated by
+.B SiSU.
+As individual text objects of a document stored (and indexed) together with
+object numbers, and all versions of the document have the same numbering,
+complex searches can be tailored to return just the locations of the search
+results relevant for all available output formats, with live links to the
+precise locations in the database or in html/xml documents; or, the structural
+information provided makes it possible to search the full contents of the
+database and have headings in which search content appears, or to search only
+headings etc. (as the
+.I Dublin Core
+is incorporated it is easy to make use of that as well).
+.SH POSTGRESQL
+
+.SH NAME
+
+
+.BR
+
+.B SiSU
+- Structured information, Serialized Units - a document publishing system,
+postgresql dependency package
+.SH DESCRIPTION
+
+
+.BR
+Information related to using postgresql with sisu (and related to the
+sisu_postgresql dependency package, which is a dummy package to install
+dependencies needed for
+.B SiSU
+to populate a postgresql database, this being part of
+.B SiSU
+- man sisu) .
+.SH SYNOPSIS
+
+
+.BR
+ sisu -D [instruction] [filename/wildcard if required]
+
+.BR
+ sisu -D --pg --[instruction] [filename/wildcard if required]
+.SH COMMANDS
+
+
+.BR
+Mappings to two databases are provided by default, postgresql and sqlite, the
+same commands are used within sisu to construct and populate databases however
+-d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
+alternatively --sqlite or --pgsql may be used
+
+.BR
+
+.B -D or --pgsql
+may be used interchangeably.
+.SH CREATE AND DESTROY DATABASE
+
+.TP
+.B --pgsql --createall
+initial step, creates required relations (tables, indexes) in existing
+(postgresql) database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi)
+.TP
+.B sisu -D --createdb
+creates database where no database existed before
+.TP
+.B sisu -D --create
+creates database tables where no database tables existed before
+.TP
+.B sisu -D --Dropall
+destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories of the
+same name).
+.TP
+.B sisu -D --recreate
+destroys existing database and builds a new empty database structure
+.SH IMPORT AND REMOVE DOCUMENTS
+
+.TP
+.B sisu -D --import -v [filename/wildcard]
+populates database with the contents of the file. Imports documents(s)
+specified to a postgresql database (at an object level).
+.TP
+.B sisu -D --update -v [filename/wildcard]
+updates file contents in database
+.TP
+.B sisu -D --remove -v [filename/wildcard]
+removes specified document from postgresql database.
+.SH SQLITE
+
+.SH NAME
+
+
+.BR
+
+.B SiSU
+- Structured information, Serialized Units - a document publishing system.
+.SH DESCRIPTION
+
+
+.BR
+Information related to using sqlite with sisu (and related to the sisu_sqlite
+dependency package, which is a dummy package to install dependencies needed for
+.B SiSU
+to populate an sqlite database, this being part of
+.B SiSU
+- man sisu) .
+.SH SYNOPSIS
+
+
+.BR
+ sisu -d [instruction] [filename/wildcard if required]
+
+.BR
+ sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if required]
+.SH COMMANDS
+
+
+.BR
+Mappings to two databases are provided by default, postgresql and sqlite, the
+same commands are used within sisu to construct and populate databases however
+-d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql,
+alternatively --sqlite or --pgsql may be used
+
+.SH CREATE AND DESTROY DATABASE
+
+.TP
+.B --sqlite --createall
+initial step, creates required relations (tables, indexes) in existing (sqlite)
+database (a database should be created manually and given the same name as
+working directory, as requested) (rb.dbi)
+.TP
+.B sisu -d --createdb
+creates database where no database existed before
+.TP
+.B sisu -d --create
+creates database tables where no database tables existed before
+.TP
+.B sisu -d --dropall
+destroys database (including all its content)! kills data and drops tables,
+indexes and database associated with a given directory (and directories of the
+same name).
+.TP
+.B sisu -d --recreate
+destroys existing database and builds a new empty database structure
+.SH IMPORT AND REMOVE DOCUMENTS
+
+.TP
+.B sisu -d --import -v [filename/wildcard]
+populates database with the contents of the file. Imports documents(s)
+specified to an sqlite database (at an object level).
+.TP
+.B sisu -d --update -v [filename/wildcard]
+updates file contents in database
+.TP
+.B sisu -d --remove -v [filename/wildcard]
+removes specified document from sqlite database.
+.SH CGI SEARCH FORM
+
+
+.BR
+For the search form, which is a single search page
+
+.BR
+- configure the search form
+
+.BR
+- generate the sample search form with the sisu command, (this will be based on
+the configuration settings and existing found sisu databases)
+
+.BR
+For postgresql web content you may need to edit the search cgi script. Two
+things to look out for are that the user is set as needed, and that the any
+different databases that you wish to be able to query are listed.
+
+.BR
+correctly, you may want www-data rather than your username.
+.nf
+@user='www-data'
+.fi
+
+
+.BR
+- check the search form, copy it to the appropriate cgi directory and set the
+correct permissions
+
+.BR
+For a search form to appear on each html page, you need to:
+
+.BR
+- rely on the above mentioned configuration of the search form
+
+.BR
+- configure the html search form to be on
+
+.BR
+- run the html command
+.SH SETUP SEARCH FORM
+
+
+.BR
+You will need a web server, httpd with cgi enabled, and a postgresql database
+to which you are able to create databases.
+
+.BR
+Setup postgresql, make sure you are able to create and write to the database,
+e.g.:
+.nf
+sudo su postgres
+ createuser -d -a ralph
+.fi
+
+
+.BR
+You then need to create the database that sisu will use, for sisu manual in the
+directory manual/en for example, (when you try to populate a database that does
+not exist sisu prompts as to whether it exists):
+.nf
+createdb SiSU.7a.manual
+.fi
+
+
+.BR
+
+.B SiSU
+is then able to create the required tables that allow you to populate the
+database with documents in the directory for which it has been created:
+.nf
+sisu --pg --createall -v
+.fi
+
+
+.BR
+You can then start to populate the database, in this example with a single
+document:
+.nf
+sisu --pg --update -v en/sisu_manual.ssm
+.fi
+
+
+.BR
+To create a sample search form, from within the same directory run:
+.nf
+sisu --sample-search-form --db-pg
+.fi
+
+
+.BR
+and copy the resulting cgi form to your cgi-bin directory
+
+.BR
+A sample setup for nginx is provided that assumes data will be stored under
+/srv/www and cgi scripts under /srv/cgi
+.SH SEARCH - DATABASE FRONTEND SAMPLE, UTILISING DATABASE AND SISU FEATURES,
+INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
+
+
+.BR
+Sample search frontend <http://search.sisudoc.org> [^15] A small database and
+sample query front-end (search from) that makes use of the citation system, .I
+object citation numbering
+to demonstrates functionality.[^16]
+
+.BR
+
+.B SiSU
+can provide information on which documents are matched and at what locations
+within each document the matches are found. These results are relevant across
+all outputs using
+.I object citation numbering,
+which includes html,
+.I XML,
+.I EPUB,
+.I LaTeX,
+.I PDF
+and indeed the
+.I SQL
+database. You can then refer to one of the other outputs or in the
+.I SQL
+database expand the text within the matched objects (paragraphs) in the
+documents matched.
+
+.BR
+Note you may set results either for documents matched and object number
+locations within each matched document meeting the search criteria; or display
+the names of the documents matched along with the objects (paragraphs) that
+meet the search criteria.[^17]
+.TP
+.B sisu -F --webserv-webrick
+builds a cgi web search frontend for the database created
+
+.BR
+The following is feedback on the setup on a machine provided by the help
+command:
+
+.BR
+ sisu --help sql
+.nf
+Postgresql
+ user: ralph
+ current db set: SiSU_sisu
+ port: 5432
+ dbi connect: DBI:Pg:database=SiSU_sisu;port=5432
+
+sqlite
+ current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db
+ dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db
+.fi
+
+.BR
+Note on databases built
+
+.BR
+By default, [unless otherwise specified] databases are built on a directory
+basis, from collections of documents within that directory. The name of the
+directory you choose to work from is used as the database name, i.e. if you are
+working in a directory called /home/ralph/ebook the database SiSU_ebook is
+used. [otherwise a manual mapping for the collection is necessary]
+
+.SH SEARCH FORM
+
+.TP
+.B sisu -F
+generates a sample search form, which must be copied to the web-server cgi
+directory
+.TP
+.B sisu -F --webserv-webrick
+generates a sample search form for use with the webrick server, which must be
+copied to the web-server cgi directory
+.TP
+.B sisu -W
+starts the webrick server which should be available wherever sisu is properly
+installed
+
+.BR
+The generated search form must be copied manually to the webserver directory as
+instructed
+.SH SISU_WEBRICK
+
+.SH NAME
+
+
+.BR
+
+.B SiSU
+- Structured information, Serialized Units - a document publishing system
+.SH SYNOPSIS
+
+
+.BR
+sisu_webrick [port]
+
+.BR
+or
+
+.BR
+sisu -W [port]
+.SH DESCRIPTION
+
+
+.BR
+sisu_webrick is part of
+.B SiSU
+(man sisu) sisu_webrick starts
+.B Ruby
+' s Webrick web-server and points it to the directories to which
+.B SiSU
+output is written, providing a list of these directories (assuming
+.B SiSU
+is in use and they exist).
+
+.BR
+The default port for sisu_webrick is set to 8081, this may be modified in the
+yaml file: ~/.sisu/sisurc.yml a sample of which is provided as
+/etc/sisu/sisurc.yml (or in the equivalent directory on your system).
+.SH SUMMARY OF MAN PAGE
+
+
+.BR
+sisu_webrick, may be started on it's own with the command: sisu_webrick [port]
+or using the sisu command with the -W flag: sisu -W [port]
+
+.BR
+where no port is given and settings are unchanged the default port is 8081
+.SH DOCUMENT PROCESSING COMMAND FLAGS
+
+
+.BR
+sisu -W [port] starts
+.B Ruby
+Webrick web-server, serving
+.B SiSU
+output directories, on the port provided, or if no port is provided and the
+defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081
+.SH SUMMARY OF FEATURES
+
+
+.BR
+- sparse/minimal markup (clean utf-8 source texts). Documents are prepared in a
+single
+.I UTF-8
+file using a minimalistic mnemonic syntax. Typical literature, documents like
+"War and Peace" require almost no markup, and most of the headers are optional.
+
+.BR
+- markup is easily readable/parsable by the human eye, (basic markup is simpler
+and more sparse than the most basic
+.I HTML
+) , [this may also be converted to
+.I XML
+representations of the same input/source document].
+
+.BR
+- markup defines document structure (this may be done once in a header
+pattern-match description, or for heading levels individually); basic text
+attributes (bold, italics, underscore, strike-through etc.) as required; and
+semantic information related to the document (header information, extended
+beyond the Dublin core and easily further extended as required); the headers
+may also contain processing instructions.
+.B SiSU
+markup is primarily an abstraction of document structure and document metadata
+to permit taking advantage of the basic strengths of existing alternative
+practical standard ways of representing documents [be that browser viewing,
+paper publication, sql search etc.] (html, epub, xml, odf, latex, pdf, sql)
+
+.BR
+- for output produces reasonably elegant output of established industry and
+institutionally accepted open standard formats.[3] takes advantage of the
+different strengths of various standard formats for representing documents,
+amongst the output formats currently supported are:
+
+.BR
+*
+.I HTML
+- both as a single scrollable text and a segmented document
+
+.BR
+*
+.I XHTML
+
+.BR
+*
+.I EPUB
+
+.BR
+*
+.I XML
+- both in sax and dom style xml structures for further development as required
+
+.BR
+*
+.I ODT
+- Open Document Format text, the iso standard for document storage
+
+.BR
+*
+.I LaTeX
+- used to generate pdf
+
+.BR
+*
+.I PDF
+(via
+.I LaTeX
+)
+
+.BR
+*
+.I SQL
+- population of an sql database (
+.I PostgreSQL
+or
+.I SQLite
+) , (at the same object level that is used to cite text within a document)
+
+.BR
+Also produces: concordance files; document content certificates (md5 or sha256
+digests of headings, paragraphs, images etc.) and html manifests (and sitemaps
+of content). (b) takes advantage of the strengths implicit in these very
+different output types, (e.g. PDFs produced using typesetting of
+.I LaTeX,
+databases populated with documents at an individual object/paragraph level,
+making possible
+.I granular search
+(and related possibilities))
+
+.BR
+- ensuring content can be cited in a meaningful way regardless of selected
+output format. Online publishing (and publishing in multiple document formats)
+lacks a useful way of citing text internally within documents (important to
+academics generally and to lawyers) as page numbers are meaningless across
+browsers and formats. sisu seeks to provide a common way of pinpoint the text
+within a document, (which can be utilized for citation and by search engines).
+The outputs share a common numbering system that is meaningful (to man and
+machine) across all digital outputs whether paper, screen, or database
+oriented, (pdf,
+.I HTML,
+.I EPUB,
+xml, sqlite, postgresql) , this numbering system can be used to reference
+content.
+
+.BR
+- Granular search within documents.
+.I SQL
+databases are populated at an object level (roughly headings, paragraphs,
+verse, tables) and become searchable with that degree of granularity, the
+output information provides the object/paragraph numbers which are relevant
+across all generated outputs; it is also possible to look at just the matching
+paragraphs of the documents in the database; [output indexing also work well
+with search indexing tools like hyperestraier].
+
+.BR
+- long term maintainability of document collections in a world of changing
+formats, having a very sparsely marked-up source document base. there is a
+considerable degree of future-proofing, output representations are
+"upgradeable", and new document formats may be added. e.g. addition of odf
+(open document text) module in 2006, epub in 2009 and in future html5 output
+sometime in future, without modification of existing prepared texts
+
+.BR
+*
+.I SQL
+search aside, documents are generated as required and static once generated.
+
+.BR
+- documents produced are static files, and may be batch processed, this needs
+to be done only once but may be repeated for various reasons as desired
+(updated content, addition of new output formats, updated technology document
+presentations/representations)
+
+.BR
+- document source (
+.I plaintext
+utf-8) if shared on the net may be used as input and processed locally to
+produce the different document outputs
+
+.BR
+- document source may be bundled together (automatically) with associated
+documents (multiple language versions or master document with inclusions) and
+images and sent as a zip file called a sisupod, if shared on the net these too
+may be processed locally to produce the desired document outputs
+
+.BR
+- generated document outputs may automatically be posted to remote sites.
+
+.BR
+- for basic document generation, the only software dependency is
+.B Ruby,
+and a few standard Unix tools (this covers
+.I plaintext,
+.I HTML,
+.I EPUB,
+.I XML,
+.I ODF,
+.I LaTeX
+) . To use a database you of course need that, and to convert the
+.I LaTeX
+generated to pdf, a latex processor like tetex or texlive.
+
+.BR
+- as a developers tool it is flexible and extensible
+
+.BR
+Syntax highlighting for
+.B SiSU
+markup is available for a number of text editors.
+
+.BR
+
+.B SiSU
+is less about document layout than about finding a way with little markup to be
+able to construct an abstract representation of a document that makes it
+possible to produce multiple representations of it which may be rather
+different from each other and used for different purposes, whether layout and
+publishing, or search of content
+
+.BR
+i.e. to be able to take advantage from this minimal preparation starting point
+of some of the strengths of rather different established ways of representing
+documents for different purposes, whether for search (relational database, or
+indexed flat files generated for that purpose whether of complete documents, or
+say of files made up of objects), online viewing (e.g. html, xml, pdf) , or
+paper publication (e.g. pdf) ...
+
+.BR
+the solution arrived at is by extracting structural information about the
+document (about headings within the document) and by tracking objects (which
+are serialized and also given hash values) in the manner described. It makes
+possible representations that are quite different from those offered at
+present. For example objects could be saved individually and identified by
+their hashes, with an index of how the objects relate to each other to form a
+document.
+.TP
+.BI *1.
+square brackets
+
+.BR
+.TP
+.BI *2.
+square brackets
+
+.BR
+.TP
+.BI +1.
+square brackets
+
+.BR
+.TP
+.BI 1.
+<http://www.jus.uio.no/sisu/man/>
+
+.BR
+.TP
+.BI 2.
+<http://www.jus.uio.no/sisu/man/sisu.1.html>
+
+.BR
+.TP
+.BI 3.
+From sometime after SiSU 0.58 it should be possible to describe SiSU markup
+using SiSU, which though not an original design goal is useful.
+
+.BR
+.TP
+.BI 4.
+files should be prepared using UTF-8 character encoding
+
+.BR
+.TP
+.BI 5.
+a footnote or endnote
+
+.BR
+.TP
+.BI 6.
+self contained endnote marker & endnote in one
+
+.BR
+.TP
+.BI *.
+unnumbered asterisk footnote/endnote, insert multiple asterisks if required
+
+.BR
+.TP
+.BI **.
+another unnumbered asterisk footnote/endnote
+
+.BR
+.TP
+.BI *3.
+editors notes, numbered asterisk footnote/endnote series
+
+.BR
+.TP
+.BI +2.
+editors notes, numbered plus symbol footnote/endnote series
+
+.BR
+.TP
+.BI 7.
+<http://www.sisudoc.org/>
+
+.BR
+.TP
+.BI 8.
+<http://www.ruby-lang.org/en/>
+
+.BR
+.TP
+.BI 9.
+Table from the Wealth of Networks by Yochai Benkler
+<http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
+
+.BR
+.TP
+.BI 10.
+for which you may alternatively use the full form author: title: and year:
+
+.BR
+.TP
+.BI 11.
+Quixote and Panza, Taming Windmills (1605), pp 1000 - 1001 also, Benkler, Wealth of Networks (2006), p 1
+
+.BR
+.TP
+.BI 12.
+SiSU has worked this way in the past, though this was dropped as it was
+thought the complexity outweighed the flexibility, however, the balance was
+rather fine and this behaviour could be reinstated.
+
+.BR
+.TP
+.BI 13.
+<http://www.postgresql.org/> <http://advocacy.postgresql.org/>
+<http://en.wikipedia.org/wiki/Postgresql>
+
+.BR
+.TP
+.BI 14.
+<http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>
+
+.BR
+.TP
+.BI 15.
+<http://search.sisudoc.org>
+
+.BR
+.TP
+.BI 16.
+(which could be extended further with current back-end). As regards scaling
+of the database, it is as scalable as the database (here Postgresql) and
+hardware allow.
+
+.BR
+.TP
+.BI 17.
+of this feature when demonstrated to an IBM software innovations evaluator
+in 2004 he said to paraphrase: this could be of interest to us. We have large
+document management systems, you can search hundreds of thousands of documents
+and we can tell you which documents meet your search criteria, but there is no
+way we can tell you without opening each document where within each your
+matches are found.
+
+.BR
+
+.TP
+.SH SEE ALSO
+ sisu(1),
+ sisu-epub(1),
+ sisu-harvest(1),
+ sisu-html(1),
+ sisu-odf(1),
+ sisu-pdf(1),
+ sisu-pg(1),
+ sisu-sqlite(1),
+ sisu-txt(1).
+ sisu_vim(7)
+.TP
+.SH HOMEPAGE
+ More information about SiSU can be found at <http://www.sisudoc.org/> or <http://www.jus.uio.no/sisu/>
+.TP
+.SH SOURCE
+ <http://git.sisudoc.org/>
+.TP
+.SH AUTHOR
+ SiSU is written by Ralph Amissah <ralph@amissah.com>