aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2014-02-05 01:27:25 -0500
committerRalph Amissah <ralph@amissah.com>2014-02-05 01:27:25 -0500
commit4e7fb32481df6e47db28888ff1e8a63d39aa92c4 (patch)
tree254a9e1ce784d24538db843f6bbbbe9a87ea622f
parentsisu manual update (diff)
README & manpage (sisu.1) updatesisu_5.3.1
-rw-r--r--README2469
-rw-r--r--data/doc/sisu/CHANGELOG_v51
-rw-r--r--data/doc/sisu/CHANGELOG_v61
-rw-r--r--man/man1/sisu.1209
4 files changed, 2141 insertions, 539 deletions
diff --git a/README b/README
index 624f370c..e0550c83 100644
--- a/README
+++ b/README
@@ -1,518 +1,2235 @@
-%% SiSU versions 4 & 3, 2011
-Homepage: <http://www.jus.uio.no/sisu>
-* README
-* CHANGELOGS/CHANGELOG_v4
-* CHANGELOGS/CHANGELOG_v3
-* CHANGELOGS/CHANGELOG_v2
-* CHANGELOGS/CHANGELOG_v1
-
-Herein (this package) reside SiSU versions 4 and 3.
-
-%% Description
----------------
-
- SiSU is lightweight markup based document creation and publishing framework
- that is controlled from the command line. Prepare documents for SiSU using
- your text editor of choice, then use SiSU to generate various output document
- formats.
+SISU - README
+=============
- With minimal preparation of a plain-text (UTF-8) file using its native
- markup-syntax, SiSU produces: plain-text, HTML, XHTML, XML, EPUB (v2 only)
- ODF:ODT (Opendocument), LaTeX, PDF, and populates an SQL database (PostgreSQL
- or SQLite) with text objects, roughly, paragraph sized chunks so that
- document searches are done at this level of granularity.
+INTRODUCTION
+************
- Outputs share a common citation numbering system, associated with text
- objects and any semantic meta-data provided about the document.
+INTRODUCTION - WHAT IS SISU?
+----------------------------
- SiSU also provides concordance files, document content certificates and
- manifests of generated output. Book indexes may be made.
+*SiSU* is a lightweight markup based document creation and publishing framework
+that is controlled from the command line. Prepare documents for *SiSU* using
+your text editor of choice, then use *SiSU* to generate various output document
+formats.
- SiSU takes advantage of well established open standard ways of representing
- text, and provides a bridge to take advantage of the strengths of each,
- while retaining minimal markup requirement. SiSU implements a "useful
- common feature set" across document formats [coming from a humanities, law,
- and possibly social sciences perspective, rather than technical or
- scientific writing] ... focus is primarily on content and data integrity
- rather than appearance, (though outputs in the various formats are
- respectable).
+From a single lightly prepared document (plain-text /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. *SiSU* produces: plain-text, /HTML/, /XHTML/,
+/XML/, /EPUB/, /ODF/: /ODT/ (Opendocument), /LaTeX/, /PDF/, and populates an
+/SQL/ database (/PostgreSQL/ or /SQLite/) with text objects, roughly, paragraph
+sized chunks so that document searches are done at this level of granularity.
- Syntax highlighting files for a number of editors are provided.
- A vim syntax highlighting file and an ftplugin with folds for sisu markup is
- provided. Vim 7 includes syntax highlighting for SiSU.
+Outputs share a common citation numbering system, associated with text objects
+and any semantic meta-data provided about the document.
- man pages, and interactive help are provided.
+*SiSU* also provides concordance files, document content certificates and
+manifests of generated output. Book indexes may be made.
- Dependencies for various features are taken care of in sisu related packages.
- The package sisu-complete installs the whole of SiSU.
+Some document markup samples are provided in the package sisu -markup-samples.
- Additional document markup samples are provided in the package
- sisu-markup-samples which is found in the non-free archive the licenses for
- the substantive content of the marked up documents provided is that provided
- by the author or original publisher.
+Homepages:
+* <http://www.sisudoc.org/>
+* <http://www.jus.uio.no/sisu>
- Homepage: <http://www.jus.uio.no/sisu>
+INSTALL OR RUN WITHOUT INSTALLATION
+***********************************
-%% Take 2
----------
+SOURCE TARBALL
+--------------
-The ideas behind SiSU evolved working with managing static, published documents
-that needed to be citable, ideally searchable and preferably available in
-multiple formats over a period of time with a rapidly changing World Wide Web.
-Initial experience was in 1993, one issue being that the document content
-remained the same, but presentation needed to be updated with changing formats,
-html in particular has really changed since then.
+RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
+..........................................................
-So the idea was to provide a minimal markup requirement for documents that
-remained the same, and a generator to convert that markup custom producing
-various output types. This made it possible to:
+1. Download the latest source (information available) from:
+<http://www.jus.uio.no/sisu/SiSU/download.html#current>
-* have a marked-up document set and continue improving the presentation, as the
-generators code was updated, e.g. update HTML as it evolves, and improve upon
-LaTeX driven pdf output
+2. Unpack the source
-* have available new document formats/ output types as they came to be of
-interest, e.g. version 2 includes EPUB
+Provided you have *Ruby*, *SiSU* can be run without installation straight from
+the source package directory tree. Run ruby against the full path to bin/sisu
+(in the unzipped source package directory tree)
-* produce a citation system that is available across different output types,
-text based on objects (rather than page numbers), i.e. you can accurately and
-reliably cite text within a document regardless of the document format version
-that is being looked at
+Note however, that additional external package dependencies, such as texlive
+(for pdfs), sqlite3 or postgresql (for search) should you desire to use them
+are not taken care of for you.
-* take advantage of the strengths of disparate technologies representing text,
-each output type being custom generated for that format, the object citation
-system lends itself as a result is that there is little necessity that one
-output type should be based on or related to another, just that the content is
-preserved and presented in a way that is well suited to the output type in
-question
+GEM INSTALL (WITH RAKE)
+.......................
-* produce consistent quality presentation for material, suitable where
-substance/content is more important than appearance, there is some sacrifice of
-flexibility and no concept of wysiwyg, e.g. there is no attempt to make pdf
-output identical to html, rather the system attempts to take advantage of
-making the best presentation it can in each output format taking advantage of
-the strengths of that format available to it given the minimal markup (sisu
-document preparation); the citation system ensures you can pinpoint the same
-text
+Gem install, you need to:
-SiSU works best:
+(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
+the gem
-* with published works (e.g. books, articles), static documents the content of
-which is changed rarely, and ideally when they do in the form of a new edition.
+Provided you have ruby & rake, this can be done with the single command:
-* for literature and law related content
+ rake gem_create_build_install # (to build and install sisu v5 & sisu v6,
+ alias gemcbi)
-SiSU uses Unicode, utf-8 where it is available,
------
+separate gems are made/installed for sisu v5 & sisu v6 contained in source:
-SiSU - simple information structuring universe, is a publishing tool, document
-generation and management, (and search enabling) tool primarily for literary,
-academic and legal published works.
+ rake gem_create_build_install_stable # (to build and install sisu v5, alias
+ gem5cbi)
-SiSU can be used for Internet, Intranet, local filesystem or cd publishing.
+ rake gem_create_build_install_unstable # (to build and install sisu v6, alias
+ gem6cbi)
-SiSU can be used directly off the filesystem, or from a database.
+for individual steps (create, build, install) see rake options, rake -T to
+specify sisu version for sisu installed via gem
-SiSU's scalability, is be dependent on your hardware, and filesystem and/or
-database Postgresql.
+ sisu _5.3.0_ --version
-Amongst it's characteristics are:
+ sisu _6.0.0_ --version
-* simple mnemonoic markup style,
+to uninstall sisu installed via gem
-* the ability to produce multiple output formats, including html, XML, EPUB,
-LaTeX, pdf (via LaTeX), stream to a relational database whilst retaining
-document structure - Postgresql and Sqlite,
+ sudo gem uninstall --verbose sisu
-* that all share a common citation system (a simple idea from which much good),
-possibly most exciting, the following: if fed into a relational database (as it
-can be automatically), the document set is searchable, with results displayed
-at a paragraph level, or the possibility of an indexed display of documents
-identifying the paragraph in which the match is found (using the object
-citation numbering system) together with a hyperlinked listing for each of each
-paragraph in which the match is found. In any event citations using this system
-(with or without the relational database) are relevant for all output formats.
+For a list of alternative actions you may type:
-* it is command line driven, and can be set up on a remote server
+ rake help
-* Documents are marked up in SiSU syntax in your favourite editor. SiSU syntax
-may be regarded as a type of smart ascii - which in its basic form is simpler
-than the most elementary html. There is currently a syntax highlighter, and
-folding for Vim. Syntax highlighters for other editors are welcome.
+ rake -T
-Input files should be UTF-8
+Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50>
-Once set up it is simple to use.
+Rant: <http://make.rubyforge.org/> <http://rubyforge.org/frs/?group_id=615>
-%% Information, places to look
----------------
+INSTALLATION WITH SETUP.RB
+..........................
-Within the SiSU tarball:
+It should also be possible to install sisu using setup.rb
- ./data/doc/sisu/v2/sisu_markup_samples/sisu_manual
+this is a three step process, in the root directory of the unpacked *SiSU* as
+root type:
-Once installed, directory equivalent to:
+ruby setup.rb config
+ruby setup.rb setup
+#[as root:]
+ruby setup.rb install
- <file:///usr/share/doc/sisu/v2/sisu_markup_samples/sisu_manual/>
-Available man pages are converted back to html using man2html:
+further information:
+<http://i.loveruby.net/en/projects/setup/>
+<http://i.loveruby.net/en/projects/setup/doc/usage.html>
- <file:///usr/share/doc/sisu/v2/html/>
+ ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
- ./data/doc/sisu/v2/html/
+UNIX/LINUX DISTRIBUTION
+-----------------------
-%% Online Information, places to look
----------------
+A distribution install should take care of the dependencies of sisu for
+producing various outputs.
- <http://www.jus.uio.no/sisu>
+DEBIAN
+......
-Download Sources:
- <http://www.jus.uio.no/sisu/SiSU/download.html#current>
- <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
+*SiSU* is available off the *Debian* archives. It should necessary only to run
+as root, Using apt-get:
-%% Installation
----------------
-NB. Platform is Unix / Linux.
+ apt-get update
-%% Debian
----------------
-If you use Debian use the Debian packages,
-check the information at:
- <http://www.jus.uio.no/sisu/SiSU/download.html#debian>
+ apt get install sisu-complete
-(A) SiSU is available directly off the Debian archives for Sid and testing. It
-should necessary only to run as root:
- aptitude update
- aptitude install sisu-complete
+(all sisu dependencies should be taken care of)
-(B) If there are newer versions of SiSU upstream of the Debian archives, they
-will be available by adding the following to your /etc/apt/sources.list
+If there are newer versions of *SiSU* upstream, they will be available by
+adding the following to your sources list /etc/apt/sources.list
- deb http://www.jus.uio.no/sisu/archive unstable main non-free
- deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+#/etc/apt/sources.list
- [the non-free line is for document markup
- samples, for which the substantive text is
- provided under the author or original
- publisher's license and which in most cases will
- not be debian free software guideline compliant]
+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
-Then as root run:
- aptitude update
- aptitude install sisu-complete
-%% RPM
----------------
-RPMs are provided though untested, they are prepared by running alien against the
-source package, and against the debs.
+The non-free section is for sisu markup samples provided, which contain
+authored works the substantive text of which cannot be changed, and which as a
+result do not meet the debian free software guidelines.
-They may be downloaded from:
- <http://www.jus.uio.no/sisu/SiSU/download.html#rpm>
+*SiSU* is developed on *Debian*, and packages are available for *Debian* that
+take care of the dependencies encountered on installation.
-%% Source package .tgz
----------------
-Otherwise to install SiSU from source, check information at:
- <http://www.jus.uio.no/sisu/SiSU/download.html#current>
+The package is divided into the following components:
-alternative modes of installation from source are provided,
-setup.rb (by Minero Aoki),
-rake (by Jim Weirich) built install file,
-rant (by Stefan Lang) built install file,
+ *sisu*, the base code, (the main package on which the others depend), without
+ any dependencies other than ruby (and for convenience the ruby webrick web
+ server), this generates a number of types of output on its own, other
+ packages provide additional functionality, and have their dependencies
-Ruby is the essential dependency for the basic operation of SiSU
+ *sisu-complete*, a dummy package that installs the whole of greater sisu as
+ described below, apart from sisu -examples
-1. Download the latest source (information available) from:
- <http://www.jus.uio.no/sisu/SiSU/download.html#current>
+ *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated
-2. Unpack the source
+ *sisu-postgresql*, dependencies used by sisu to populate postgresql database
+ (further configuration is necessary)
-Note however, that additional external package dependencies,
-such as texlive or postgresql should you desire to use it
-are not taken care of for you.
+ *sisu-sqlite*, dependencies used by sisu to populate sqlite database
+
+ *sisu-markup-samples*, sisu markup samples and other miscellany (under
+ *Debian* Free Software Guidelines non-free)
+
+*SiSU* is available off Debian Unstable and Testing [link:
+<http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
+[^1] install it using apt-get, aptitude or alternative *Debian* install tools.
+
+DEPENDENCIES
+------------
+
+Here is a list of sisu' s current dependencies,[^2] which depend on such
+factors as whether you want to generate pdf, whether you will be using *SiSU*
+with or without a database, ...). sisu_markup-samples may also be of interest.
+
+Package: sisu
+Depends: ruby | ruby-interpreter, openssl, rsync, unzip, zip
+Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick |
+graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
+ruby-rmagick, tidy, tree, vim-addon-manager
+Suggests: lv, calibre, pinfo, poedit, texinfo, trang
+
+
+Package: sisu-complete
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
+${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
+${source:Version})
+Description-en: installs all SiSU related packages
+
+
+Package: sisu-pdf
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
+texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
+texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
+texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
+Suggests: evince | pdf-viewer
+
+
+Package: sisu-postgresql
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
+ruby-dbd-pg, ruby-dbi, ruby-fcgi
+Suggests: postgresql-contrib
+
+
+Package: sisu-sqlite
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
+ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
+
+
+Package: sisu-markup-samples
+Depends: sisu
+
+
+COMMANDS
+********
+
+COMMANDS SUMMARY
+----------------
+
+DESCRIPTION
+...........
+
+*SiSU* is a document publishing system, that from a simple single marked-up
+document, produces multiple output formats including: /plaintext/, /HTML/,
+/XHTML/, /XML/, /EPUB/, /ODT/ (/OpenDocument/ (/ODF/) text), /LaTeX/, /PDF/,
+info, and /SQL/ (/PostgreSQL/ and /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>
+
+DOCUMENT PROCESSING COMMAND FLAGS
+.................................
+
+*-a [filename/wildcard]*
+produces /plaintext/ with Unix linefeeds and without markup, (object numbers
+are omitted), has footnotes at end of each paragraph that contains them [ -A
+for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options
+include: --endnotes for endnotes --footnotes for footnotes at the end of each
+paragraph --unix for unix linefeed (default) --msdos for msdos linefeed)
+
+*--ao [filename/wildcard/url]*
+assumed for most other flags, creates new intermediate files for processing
+(abstract objects, document abstraction) that is used in all subsequent
+processing of other output. This step is assumed for most processing flags. To
+skip it see -n. Alias -m. (sisu v5)
+
+*-b [filename/wildcard]*
+see --xhtml
+
+*--by-**
+see --output-by-*
+
+*-C*
+configure/initialise shared output directory files initialize shared output
+directory (config files such as css and dtd files are not updated if they
+already exist unless modifier is used). -C --init-site configure/initialise
+site more extensive than -C on its own, shared output directory files/force
+update, existing shared output config files such as css and dtd files are
+updated if this modifier is used.
+
+*-CC*
+see --configure
+
+*-c [filename/wildcard]*
+see --color-toggle
+
+*--color*
+see --color-on
+
+*--color-off*
+turn off color in output to terminal
+
+*--color-on*
+turn on color in output to terminal
+
+*--color-toggle [filename/wildcard]*
+screen toggle ansi screen colour on or off depending on default set (unless -c
+flag is used: if sisurc colour default is set to 'true', output to screen will
+be with colour, if sisurc colour default is set to 'false' or is undefined
+screen output will be without colour). Alias -c
+
+*--configure*
+configure/initialise shared output directory files initialize shared output
+directory (config files such as css and dtd files are not updated if they
+already exist unless modifier is used). The equivalent of: -C --init-site
+configure/initialise site, more extensive than -C on its own, shared output
+directory files/force update, existing shared output config files such as css
+and dtd files are updated if -CC is used.
+
+*--concordance [filename/wildcard]*
+produces concordance (wordmap) a rudimentary index of all the words in a
+document. (Concordance files are not generated for documents of over 260,000
+words unless this limit is increased in the file sisurc.yml). Alias -w
+
+*-D [instruction] [filename]*
+see --pg
+
+*-d [--db-[database type (sqlite|pg)]] --[instruction] [filename]*
+see --sqlite
+
+*--dal [filename/wildcard/url]*
+assumed for most other flags, creates new intermediate files for processing
+(abstract objects, document abstraction) that is used in all subsequent
+processing of other output. This step is assumed for most processing flags. To
+skip it see -n. Renamed --ao (abstract objects) in sisu v5. Alias -m
+
+*--delete [filename/wildcard]*
+see --zap
+
+*--docbook [filename/wildcard/url]*
+docbook smart text (sisu v5)
+
+*--dump[=directory_path] [filename/wildcard]*
+places output in directory specified, if none is specified in the current
+directory (pwd). Unlike using default settings /HTML/ files have embedded css.
+Compare --redirect
+
+*-e [filename/wildcard]*
+see --epub
+
+*--epub [filename/wildcard]*
+produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e
+
+*--exc-**
+exclude output feature, overrides configuration settings --exc-ocn, (exclude
+/object citation numbering/, (switches off /object citation numbering/) ,
+affects html (seg, scroll), epub, xhtml, xml, pdf) ; --exc-toc, (exclude table
+of contents, affects html (scroll), epub, pdf) ; --exc-links-to-manifest,
+--exc-manifest-links, (exclude links to manifest, affects html (seg, scroll));
+--exc-search-form, (exclude search form, affects html (seg, scroll), manifest);
+--exc-minitoc, (exclude mini table of contents, affects html (seg),
+concordance, manifest); --exc-manifest-minitoc, (exclude mini table of
+contents, affects manifest); --exc-html-minitoc, (exclude mini table of
+contents, affects html (seg), concordance); --exc-html-navigation, (exclude
+navigation, affects html (seg)); --exc-html-navigation-bar, (exclude navigation
+bar, affects html (seg)); --exc-html-search-form, (exclude search form, affects
+html (seg, scroll)); --exc-html-right-pane, (exclude right pane/column, affects
+html (seg, scroll)); --exc-html-top-band, (exclude top band, affects html (seg,
+scroll), concordance (minitoc forced on to provide seg navigation));
+--exc-segsubtoc (exclude sub table of contents, affects html (seg), epub) ; see
+also --inc-*
+
+*-F [--webserv=webrick]*
+see --sample-search-form
+
+*-f [optional string part of filename]*
+see --find
+
+*--fictionbook [filename/wildcard/url]*
+fictionbook smart text (sisu v5)
+
+*--find [optional string part of filename]*
+without match string, glob all .sst .ssm files in directory (including language
+subdirectories). With match string, find files that match given string in
+directory (including language subdirectories). Alias -f, --glob, -G
+
+*-G [optional string part of filename]*
+see --find
+
+*-g [filename/wildcard]*
+see --git
+
+*--git [filename/wildcard]*
+produces or updates markup source file structure in a git repo (experimental
+and subject to change). Alias -g
+
+*--glob [optional string part of filename]*
+see --find
+
+*-h [filename/wildcard]*
+see --html
+
+*--harvest *.ss[tm]*
+makes two lists of sisu output based on the sisu markup documents in a
+directory: list of author and authors works (year and titles), and; list by
+topic with titles and author. Makes use of header metadata fields (author,
+title, date, topic_register). Can be used with maintenance (-M) and remote
+placement (-R) flags.
+
+*--help [topic]*
+provides help on the selected topic, where topics (keywords) include: list,
+(com)mands, short(cuts), (mod)ifiers, (env)ironment, markup, syntax, headers,
+headings, endnotes, tables, example, customise, skin, (dir)ectories, path,
+(lang)uage, db, install, setup, (conf)igure, convert, termsheet, search, sql,
+features, license.
+
+*--html [filename/wildcard]*
+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).
+Alias -h
+
+*--html-scroll [filename/wildcard]*
+produces html output, the document in a single file (scroll.html) only. Compare
+--html-seg and --html
+
+*--html-seg [filename/wildcard]*
+produces html output, segmented text with table of contents (toc.html and
+index.html). Compare --html-scroll and --html
+
+*--html-strict [filename/wildcard]*
+produces html with --strict option. see --strict
+
+*-I [filename/wildcard]*
+see --texinfo
+
+*-i [filename/wildcard]*
+see --manpage
+
+*--i18n-**
+these flags affect output by filetype and filename): --i18n-mono
+(--monolingual) output filenames without language code for default language
+('en' or as set); --i18n-multi (--multilingual) language code provided as part
+of the output filename, this is the default. Where output is in one language
+only the language code may not be desired. see also --output-by-*
+
+*--inc-**
+include output feature, overrides configuration settings, (usually the default
+if none set), has precedence over --exc-* (exclude output feature). Some detail
+provided under --exc-*, see --exc-*
+
+*-j [filename/wildcard]*
+copies images associated with a file for use by html, xhtml & xml outputs
+(automatically invoked by --dump & redirect).
+
+*-k*
+see --color-off
+
+*--keep-processing-files [filename/wildcard/url]*
+see --maintenance
+
+*-M [filename/wildcard/url]*
+see --maintenance
+
+*-m [filename/wildcard/url]*
+see --dal (document abstraction level/layer)
+
+*--machine [filename/wildcard/url]*
+see --dal (document abstraction level/layer)
+
+*--maintenance [filename/wildcard/url]*
+maintenance mode, interim processing files are preserved and their locations
+indicated. (also see -V). Aliases -M and --keep-processing-files.
+
+*--markdown [filename/wildcard/url]*
+markdown smart text (sisu v5)
+
+*--manpage [filename/wildcard]*
+produces man page of file, not suitable for all outputs. Alias -i
+
+*--monolingual*
+see --i18n-*
+
+*--multilingual*
+see --i18n-*
+
+*-N [filename/wildcard/url]*
+document digest or document content certificate ( DCC ) as md5 digest tree of
+the document: the digest for the document, and digests for each object
+contained within the document (together with information on software versions
+that produced it) (digest.txt). -NV for verbose digest output to screen.
+
+*-n [filename/wildcard/url]*
+skip the creation of intermediate processing files (document abstraction) if
+they already exist, this skips the equivalent of -m which is otherwise assumed
+by most processing flags.
+
+*--no-**
+see --exc-*
+
+*-o [filename/wildcard/url]*
+see --odt
+
+*--ocn*
+see --inc-ocn and --exc-ocn
+
+*--odf [filename/wildcard/url]*
+see --odt
+
+*--odt [filename/wildcard/url]*
+output basic document in opendocument file format (opendocument.odt). Alias -o
+
+*--output-by-**
+select output directory structure from 3 alternatives: --output-by-language,
+(language directory (based on language code) with filetype (html, epub, pdf
+etc.) subdirectories); --output-by-filetype, (filetype directories with
+language code as part of filename); --output-by-filename, (filename directories
+with language code as part of filename). This is configurable. Alias --by-*
+
+*-P [language_directory/filename language_directory]*
+see --po4a
+
+*-p [filename/wildcard]*
+see --pdf
+
+*--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=*
+
+*--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-*
+
+*--pdf [filename/wildcard]*
+produces /LaTeX/ pdf (portrait.pdf & landscape.pdf). Orientation and papersize
+may be set on the command-line. Default paper size is set in config file, or
+document header, or provided with additional command line parameter, e.g.
+--papersize-a4 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book
+sizes 'A5' and 'B5' (system defaults to A4), and; --landscape or --portrait,
+so: e.g. "sisu --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]"
+or "sisu --pdf --landscape --a4 --letter --verbose [filename/wildcard]". --pdf
+defaults to both landscape & portrait output, and a4 if no other papersizes are
+configured. Related options --pdf-landscape --pdf-portrait --pdf-papersize-*
+--pdf-papersize=[list]. Alias -p
+
+*--pdf-l [filename/wildcard]*
+See --pdf-landscape
+
+*--pdf-landscape [filename/wildcard]*
+sets orientation, produces /LaTeX/ pdf landscape.pdf. Default paper size is set
+in config file, or document header, or provided with additional command line
+parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and
+'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related options
+--pdf --pdf-portrait. See also --papersize-* or --papersize=[list]. Alias
+--pdf-l or in conjunction with --pdf --landscape
+
+*--pdf-p [filename/wildcard]*
+See --pdf-portrait
+
+*--pdf-portrait [filename/wildcard]*
+sets orientation, produces /LaTeX/ pdf portrait.pdf.pdf. Default paper size is
+set in config file, or document header, or provided with additional command
+line parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter'
+and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related
+options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list].
+Alias --pdf-p or in conjunction with --pdf --portrait
+
+*--pg [instruction] [filename]*
+database /PostgreSQL/ ( --pgsql may be used instead) possible instructions,
+include: --createdb; --create; --dropall; --import [filename]; --update
+[filename]; --remove [filename]; see database section below. Alias -D
+
+*--po [language_directory/filename language_directory]*
+see --po4a
+
+*--po4a [language_directory/filename language_directory]*
+produces .pot and po files for the file in the languages specified by the
+language directory. *SiSU* markup is placed in subdirectories named with the
+language code, e.g. en/ fr/ es/. The sisu config file must set the output
+directory structure to multilingual. v3, experimental
+
+*-Q [filename/wildcard]*
+see --qrcode
+
+*-q [filename/wildcard]*
+see --quiet
+
+*--qrcode [filename/wildcard]*
+generate QR code image of metadata (used in manifest). v3 only.
+
+*--quiet [filename/wildcard]*
+quiet less output to screen.
+
+*-R [filename/wildcard]*
+see --rsync
+
+*-r [filename/wildcard]*
+see --scp
+
+*--redirect[=directory_path] [filename/wildcard]*
+places output in subdirectory under specified directory, subdirectory uses the
+filename (without the suffix). If no output directory is specified places the
+subdirectory under the current directory (pwd). Unlike using default settings
+/HTML/ files have embedded css. Compare --dump
+
+*--rst [filename/wildcard/url]*
+ReST (rST restructured text) smart text (sisu v5)
+
+*--rsync [filename/wildcard]*
+copies sisu output files to remote host using rsync. This requires that
+sisurc.yml has been provided with information on hostname and username, and
+that you have your "keys" and ssh agent in place. Note the behavior of rsync
+different if -R is used with other flags from if used alone. Alone the rsync
+--delete parameter is sent, useful for cleaning the remote directory (when -R
+is used together with other flags, it is not). Also see --scp. Alias -R
+
+*-S*
+see --sisupod
+
+*-S [filename/wildcard]*
+see --sisupod
+
+*-s [filename/wildcard]*
+see --source
+
+*--sample-search-form [--db=(pgsql|sqlite)] [--webserv=webrick]*
+generate examples of (naive) cgi search form for /SQLite/ or PgSQL depends on
+your already having used sisu to populate an /SQLite/ or PgSQL database, (the
+/SQLite/ version scans the output directories for existing sisu_sqlite
+databases, so it is first necessary to create them, before generating the
+search form) see --sqlite & --pg and the database section below. Optional
+additional parameters include: url location of webserver search form and db:
+--webserv-search='[url]'; location of webserver output:
+--webserv-output='[url]'; cgi search form link name:
+--cgi-search-form-name='[name.cgi]'; for pgsql, database user:
+--db-user='[username]'. If the optional parameter --webserv=webrick is passed,
+the cgi examples created will be set up to use the default port set for use by
+the webrick server, (otherwise the port is left blank and the system setting
+used, usually 80). The samples are dumped in the present work directory which
+must be writable, (with screen instructions given that they be copied to the
+cgi-bin directory). Alias -F
+
+*--scp [filename/wildcard]*
+copies sisu output files to remote host using scp. This requires that
+sisurc.yml has been provided with information on hostname and username, and
+that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r
+
+*--sqlite --[instruction] [filename]*
+database type set to /SQLite/, this produces one of two possible databases,
+without additional database related instructions it produces a discreet
+/SQLite/ file for the document processed; with additional instructions it
+produces a common /SQLite/ database of all processed documents that (come from
+the same document preparation directory and as a result) share the same output
+directory base path (possible instructions include: --createdb; --create;
+--dropall; --import [filename]; --update [filename]; --remove [filename]); see
+database section below. Alias -d
+
+*--sisupod*
+produces a sisupod a zipped sisu directory of markup files including sisu
+markup source files and the directories local configuration file, images and
+skins. Note: this only includes the configuration files or skins contained in
+./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option
+is tested only with zsh). Alias -S
+
+*--sisupod [filename/wildcard]*
+produces a zipped file of the prepared document specified along with associated
+images, by default named sisupod.zip they may alternatively be named with the
+filename extension .ssp This provides a quick way of gathering the relevant
+parts of a sisu document which can then for example be emailed. A sisupod
+includes sisu markup source file, (along with associated documents if a master
+file, or available in multilingual versions), together with related images and
+skin. *SiSU* commands can be run directly against a sisupod contained in a
+local directory, or provided as a url on a remote site. As there is a security
+issue with skins provided by other users, they are not applied unless the flag
+--trust or --trusted is added to the command instruction, it is recommended
+that file that are not your own are treated as untrusted. The directory
+structure of the unzipped file is understood by sisu, and sisu commands can be
+run within it. Note: if you wish to send multiple files, it quickly becomes
+more space efficient to zip the sisu markup directory, rather than the
+individual files for sending). See the -S option without [filename/wildcard].
+Alias -S
+
+*--source [filename/wildcard]*
+copies sisu markup file to output directory. Alias -s
+
+*--strict*
+together with --html, produces more w3c compliant html, for example not having
+purely numeric identifiers for text, the location object url#33 becomes url#o33
+
+*-T [filename/wildcard (*.termsheet.rb)]*
+standard form document builder, preprocessing feature
+
+*-t [filename/wildcard]*
+see --txt
+
+*--texinfo [filename/wildcard]*
+produces texinfo and info file, (view with pinfo). Alias -I
+
+*--textile [filename/wildcard/url]*
+textile smart text (sisu v5)
+
+*--txt [filename/wildcard]*
+produces /plaintext/ with Unix linefeeds and without markup, (object numbers
+are omitted), has footnotes at end of each paragraph that contains them [ -A
+for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options
+include: --endnotes for endnotes --footnotes for footnotes at the end of each
+paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias
+-t
+
+*--txt-asciitext [filename/wildcard]*
+see --asciitext
+
+*--txt-markdown [filename/wildcard]*
+see --markdown
+
+*--txt-rst [filename/wildcard]*
+see --rst
+
+*--txt-textile [filename/wildcard]*
+see --textile
+
+*-U [filename/wildcard]*
+see --urls
+
+*-u [filename/wildcard]*
+provides url mapping of output files for the flags requested for processing,
+also see -U
+
+*--urls [filename/wildcard]*
+prints url output list/map for the available processing flags options and
+resulting files that could be requested, (can be used to get a list of
+processing options in relation to a file, together with information on the
+output that would be produced), -u provides url output mapping for those flags
+requested for processing. The default assumes sisu_webrick is running and
+provides webrick url mappings where appropriate, but these can be switched to
+file system paths in sisurc.yml. Alias -U
+
+*-V*
+on its own, provides *SiSU* version and environment information (sisu --help
+env)
+
+*-V [filename/wildcard]*
+even more verbose than the -v flag.
+
+*-v*
+on its own, provides *SiSU* version information
+
+*-v [filename/wildcard]*
+see --verbose
+
+*--v3 [filename/wildcard]*
+invokes the sisu v3 document parser/generator. You may run sisu3 instead.
+
+*--v4 [filename/wildcard]*
+invokes the sisu v4 document parser/generator. This is the default and is
+normally omitted.
+
+*--verbose [filename/wildcard]*
+provides verbose output of what is being generated, where output is placed (and
+error messages if any), as with -u flag provides a url mapping of files created
+for each of the processing flag requests. Alias -v
+
+*-W*
+see --webrick
+
+*-w [filename/wildcard]*
+see --concordance
+
+*--webrick*
+starts ruby' s webrick webserver points at sisu output directories, the default
+port is set to 8081 and can be changed in the resource configuration files.
+[tip: the webrick server requires link suffixes, so html output should be
+created using the -h option rather than -H ; also, note -F webrick ]. Alias -W
+
+*--wordmap [filename/wildcard]*
+see --concordance
+
+*--xhtml [filename/wildcard]*
+produces xhtml//XML/ output for browser viewing (sax parsing). Alias -b
+
+*--xml-dom [filename/wildcard]*
+produces /XML/ output with deep document structure, in the nature of dom. Alias
+-X
+
+*--xml-sax [filename/wildcard]*
+produces /XML/ output shallow structure (sax parsing). Alias -x
+
+*-X [filename/wildcard]*
+see --xml-dom
+
+*-x [filename/wildcard]*
+see --xml-sax
+
+*-Y [filename/wildcard]*
+produces a short sitemap entry for the document, based on html output and the
+sisu_manifest. --sitemaps generates/updates the sitemap index of existing
+sitemaps. (Experimental, [g,y,m announcement this week])
+
+*-y [filename/wildcard]*
+produces an html summary of output generated (hyperlinked to content) and
+document specific metadata (sisu_manifest.html). This step is assumed for most
+processing flags.
+
+*-Z [filename/wildcard]*
+see --zap
+
+*--zap [filename/wildcard]*
+Zap, if used with other processing flags deletes output files of the type about
+to be processed, prior to processing. If -Z is used as the lone processing
+related flag (or in conjunction with a combination of -[mMvVq]), will remove
+the related document output directory. Alias -Z
+
+COMMAND LINE MODIFIERS
+----------------------
+
+*--no-ocn*
+[with --html --pdf or --epub] switches off /object citation numbering/. Produce
+output without identifying numbers in margins of html or /LaTeX//pdf output.
+
+*--no-annotate*
+strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus
+sign
+
+*--no-asterisk*
+strips output text of editor endnotes[^*2] denoted by asterisk sign
+
+*--no-dagger*
+strips output text of editor endnotes[^+1] denoted by dagger/plus sign
+
+DATABASE COMMANDS
+-----------------
+
+*dbi - database interface*
+
+*-D or --pgsql* set for /PostgreSQL/ *-d or --sqlite* default set for /SQLite/
+-d is modifiable with --db=[database type (PgSQL or /SQLite/) ]
+
+*--pg -v --createall*
+initial step, creates required relations (tables, indexes) in existing
+/PostgreSQL/ database (a database should be created manually and given the same
+name as working directory, as requested) (rb.dbi) [ -dv --createall /SQLite/
+equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at
+the present time for /PostgreSQL/ it may be necessary to manually create the
+database. The command would be 'createdb [database name]' where database name
+would be SiSU_[present working directory name (without path)]. Please use only
+alphanumerics and underscores.
+
+*--pg -v --import*
+[filename/wildcard] imports data specified to /PostgreSQL/ db (rb.dbi) [ -dv
+--import /SQLite/ equivalent]
+
+*--pg -v --update*
+[filename/wildcard] updates/imports specified data to /PostgreSQL/ db (rb.dbi)
+[ -dv --update /SQLite/ equivalent]
+
+*--pg --remove*
+[filename/wildcard] removes specified data to /PostgreSQL/ db (rb.dbi) [ -d
+--remove /SQLite/ equivalent]
+
+*--pg --dropall*
+kills data" and drops (/PostgreSQL/ or /SQLite/) db, tables & indexes [ -d
+--dropall /SQLite/ equivalent]
+
+The -v is for verbose output.
+
+SHORTCUTS, SHORTHAND FOR MULTIPLE FLAGS
+---------------------------------------
+
+*--update [filename/wildcard]*
+Checks existing file output and runs the flags required to update this output.
+This means that if only html and pdf output was requested on previous runs,
+only the -hp files will be applied, and only these will be generated this time,
+together with the summary. This can be very convenient, if you offer different
+outputs of different files, and just want to do the same again.
+
+*-0 to -5 [filename or wildcard]*
+Default shorthand mappings (for v3, note that the defaults can be
+changed/configured in the sisurc.yml file):
+
+*-0*
+-NQhewpotbxXyYv [this is the default action run when no options are give, i.e.
+on 'sisu [filename]']
+
+*-1*
+-Qhewpoty
+
+*-2*
+-NQhewpotbxXy
+
+*-3*
+-NQhewpotbxXyY
+
+*-4*
+-NQhewpotbxXDyY --update
+
+*-5*
+-NQhewpotbxXDyYv --update
+
+add -v for verbose mode and -c to toggle color state, e.g. sisu -2vc [filename
+or wildcard]
+
+consider -u for appended url info or -v for verbose output
+
+COMMAND LINE WITH FLAGS - BATCH PROCESSING
+..........................................
+
+In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst"
+or "sisu -h *.{sst,ssm}" to produce html version of all documents.
+
+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.
+
+INTRODUCTION TO SISU MARKUP[^3]
+-------------------------------
+
+SUMMARY
+.......
+
+*SiSU* source documents are /plaintext/ (/UTF-8/)[^4] files
+
+All paragraphs are separated by an empty line.
+
+Markup is comprised of:
+
+* at the top of a document, the document header made up of semantic meta-data
+about the document and if desired additional processing instructions (such an
+instruction to automatically number headings from a particular level down)
+
+* followed by the prepared substantive text of which the most important single
+characteristic is the markup of different heading levels, which define the
+primary outline of the document structure. Markup of substantive text includes:
+
+ * heading levels defines document structure
+
+ * text basic attributes, italics, bold etc.
+
+ * grouped text (objects), which are to be treated differently, such as code
+ blocks or poems.
+
+ * footnotes/endnotes
+
+ * linked text and images
+
+ * paragraph actions, such as indent, bulleted, numbered-lists, etc.
+
+Some interactive help on markup is available, by typing sisu and selecting
+markup or sisu --help markup
+
+To check the markup in a file:
+
+ sisu --identify [filename].sst
+
+For brief descriptive summary of markup history
+
+ sisu --query-history
+
+or if for a particular version:
+
+ sisu --query-0.38
+
+MARKUP EXAMPLES
+...............
+
+
+----------------------------------------
+
+ONLINE
+......
+
+Online markup examples are available together with the respective outputs
+produced from <http://www.jus.uio.no/sisu/SiSU/examples.html> or from
+<http://www.jus.uio.no/sisu/sisu_examples/>
+
+There is of course this document, which provides a cursory overview of sisu
+markup and the respective output produced:
+<http://www.jus.uio.no/sisu/sisu_markup/>
+
+an alternative presentation of markup syntax:
+/usr/share/doc/sisu/on_markup.txt.gz
+
+
+----------------------------------------
+
+INSTALLED
+.........
+
+With *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
+
+MARKUP OF HEADERS
+-----------------
+
+Headers contain either: semantic meta-data about a document, which can be used
+by any output module of the program, or; processing instructions.
+
+Note: the first line of a document may include information on the markup
+version used in the form of a comment. Comments are a percentage mark at the
+start of a paragraph (and as the first character in a line of text) followed by
+a space and the comment:
+
+% this would be a comment
+
+
+SAMPLE HEADER
+.............
+
+This current document is loaded by a master document that has a header similar
+to this one:
+
+% 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]
+ . sisu --v4 [operations]
+ . sisu --v3 [operations]
+
+@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/?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
+
+
+AVAILABLE HEADERS
+.................
+
+Header tags appear at the beginning of a document and provide meta information
+on the document (such as the /Dublin Core/) , or information as to how the
+document as a whole is to be processed. All header instructions take the form
+@headername: or on the next line and indented by once space :subheadername: All
+/Dublin Core/ meta tags are available
+
+*@identifier:* information or instructions
+
+where the "identifier" is a tag recognised by the program, and the
+"information" or "instructions" belong to the tag/identifier specified
+
+Note: a header where used should only be used once; all headers apart from
+@title: are optional; the @structure: header is used to describe document
+structure, and can be useful to know.
+
+This is a sample header
+
+% SiSU 2.0 [declared file-type identifier with markup version]
+
+
+@title: [title text] [this header is the only one that is mandatory]
+ :subtitle: [subtitle if any]
+ :language: English
+
+
+@creator:
+ :author: [Lastname, First names]
+ :illustrator: [Lastname, First names]
+ :translator: [Lastname, First names]
+ :prepared_by: [Lastname, First names]
+
+
+@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]
+
+
+@rights:
+ :copyright: Copyright (C) [Year and Holder]
+ :license: [Use License granted]
+ :text: [Year and Holder]
+ :translation: [Name, Year]
+ :illustrations: [Name, Year]
+
+
+@classify:
+ :topic_register: SiSU:markup sample:book;book:novel:fantasy
+ :type:
+ :subject:
+ :description:
+ :keywords:
+ :abstract:
+ :loc: [Library of Congress classification]
+ :dewey: [Dewey classification
+
+
+@identify:
+ :isbn: [ISBN]
+ :oclc:
+
+
+@links: { SiSU }http://www.sisudoc.org
+ { FSF }http://www.fsf.org
+
+
+@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
+
+
+@original:
+ :language: [language]
+
+
+@notes:
+ :comment:
+ :prefix: [prefix is placed just after table of contents]
+
+
+MARKUP OF SUBSTANTIVE TEXT
+--------------------------
+
+HEADING LEVELS
+..............
+
+Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
+headings, followed by other heading levels, and 1 -6 being headings followed by
+substantive text or sub-headings. :A~ usually the title :A~? conditional level
+1 heading (used where a stand-alone document may be imported into another)
+
+*:A~ [heading text]* Top level heading [this usually has similar content to the
+title @title: ] NOTE: the heading levels described here are in 0.38 notation,
+see heading
+
+*:B~ [heading text]* Second level heading [this is a heading level divider]
+
+*:C~ [heading text]* Third level heading [this is a heading level divider]
+
+*1~ [heading text]* Top level heading preceding substantive text of document or
+sub-heading 2, the heading level that would normally be marked 1. or 2. or 3.
+etc. in a document, and the level on which sisu by default would break html
+output into named segments, names are provided automatically if none are given
+(a number), otherwise takes the form 1~my_filename_for_this_segment
+
+*2~ [heading text]* Second level heading preceding substantive text of document
+or sub-heading 3 , the heading level that would normally be marked 1.1 or 1.2
+or 1.3 or 2.1 etc. in a document.
+
+*3~ [heading text]* Third level heading preceding substantive text of document,
+that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a
+document
+
+1~filename level 1 heading,
+
+% the primary division such as Chapter that is followed by substantive text, and may be further subdivided (this is the level on which by default html segments are made)
+
+
+FONT ATTRIBUTES
+...............
+
+*markup example:*
+
+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}#
+
+
+*resulting output:*
+
+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#
+
+INDENTATION AND BULLETS
+.......................
+
+*markup example:*
+
+ordinary paragraph
+
+_1 indent paragraph one step
+
+_2 indent paragraph two steps
-%% to use setup.rb
----------------
-this is a three step process,
-in the root directory of the unpacked SiSU as root type:
+_9 indent paragraph nine steps
- ruby setup.rb config
- ruby setup.rb setup
- #[as root:]
- ruby setup.rb install
- further information:
- <http://i.loveruby.net/en/projects/setup/>
- <http://i.loveruby.net/en/projects/setup/doc/usage.html>
+*resulting output:*
-%% to use install (prapared with "Rake")
----------------
-Rake must be installed on your system:
- <http://rake.rubyforge.org/>
- <http://rubyforge.org/frs/?group_id=50>
+ordinary paragraph
-in the root directory of the unpacked SiSU as root type:
- rake
+ indent paragraph one step
+
+ indent paragraph two steps
+
+ indent paragraph nine steps
+
+*markup example:*
+
+_* bullet text
+
+_1* bullet text, first indent
+
+_2* bullet text, two step indent
+
+
+*resulting output:*
+
+* bullet text
+
+ * bullet text, first indent
+
+ * bullet text, two step indent
+
+Numbered List (not to be confused with headings/titles, (document structure))
+
+*markup example:*
+
+# numbered list numbered list 1., 2., 3, etc.
+
+_# numbered list numbered list indented a., b., c., d., etc.
+
+
+HANGING INDENTS
+...............
+
+*markup example:*
+
+_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
+
+
+*resulting output:*
+
+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;
+
+A regular paragraph.
+
+ 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
+
+in each case level may be 0-9
+
+*live-build* A collection of scripts used to build customized *Debian*
+ Livesystems. /live-build/ was formerly known as live-helper, and even earlier
+ known as live-package.
+
+*live-build*
+ A collection of scripts used to build customized *Debian* Livesystems.
+ /live-build/ was formerly known as live-helper, and even earlier known as
+ live-package.
+
+FOOTNOTES / ENDNOTES
+....................
+
+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
+
+*markup example:*
+
+~{ a footnote or endnote }~
+
+
+*resulting output:*
+
+[^5]
+
+*markup example:*
+
+normal text~{ self contained endnote marker & endnote in one }~ continues
+
+
+*resulting output:*
+
+normal text[^6] continues
+
+*markup example:*
+
+normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks if required }~ continues
+
+normal text ~{** another unnumbered asterisk footnote/endnote }~ continues
+
+
+*resulting output:*
+
+normal text [^*] continues
+
+normal text [^**] continues
+
+*markup example:*
+
+normal text ~[* editors notes, numbered asterisk footnote/endnote series ]~ continues
+
+normal text ~[+ editors notes, numbered plus symbol footnote/endnote series ]~ continues
+
+
+*resulting output:*
+
+normal text [^*3] continues
+
+normal text [^+2] continues
+
+*Alternative endnote pair notation for footnotes/endnotes:*
+
+% note the endnote marker "~^"
+
+normal text~^ continues
+
+^~ endnote text following the paragraph in which the marker occurs
+
+
+the standard and pair notation cannot be mixed in the same document
+
+LINKS
+.....
+
+
+----------------------------------------
+
+NAKED URLS WITHIN TEXT, DEALING WITH URLS
+.........................................
+
+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).
+
+*markup example:*
+
+normal text http://www.sisudoc.org/ continues
+
+
+*resulting output:*
+
+normal text <http://www.sisudoc.org/> continues
+
+An escaped url without decoration
+
+*markup example:*
+
+normal text _http://www.sisudoc.org/ continues
+
+deb _http://www.jus.uio.no/sisu/archive unstable main non-free
+
+
+*resulting output:*
+
+normal text http://www.sisudoc.org/ continues
+
+deb http://www.jus.uio.no/sisu/archive unstable main non-free
+
+where a code block is used there is neither decoration nor hyperlinking, code
+blocks are discussed later in this document
+
+*resulting output:*
+
+deb http://www.jus.uio.no/sisu/archive unstable main non-free
+deb-src http://www.jus.uio.no/sisu/archive unstable main non-free
+
+
+
+----------------------------------------
+
+LINKING TEXT
+............
+
+To link text or an image to a url the markup is as follows
+
+*markup example:*
+
+about { SiSU }http://url.org markup
+
+
+*resulting output:*
+
+about SiSU [link: <http://www.sisudoc.org/>] markup
+
+A shortcut notation is available so the url link may also be provided
+automatically as a footnote
+
+*markup example:*
+
+about {~^ SiSU }http://url.org markup
+
+
+*resulting output:*
+
+about SiSU [link: <http://www.sisudoc.org/>] [^7] markup
+
+Internal document links to a tagged location, including an ocn
+
+*markup example:*
+
+about { text links }#link_text
+
+
+*resulting output:*
+
+about text links
+
+Shared document collection link
+
+*markup example:*
+
+about { SiSU book markup examples }:SiSU/examples.html
+
+
+*resulting output:*
+
+about *SiSU* book markup examples
+
+
+----------------------------------------
+
+LINKING IMAGES
+..............
+
+*markup example:*
+
+{ tux.png 64x80 }image
+
+% various url linked images
+[image: "a better way"]
+ [image: "Way Better - with Gnu/Linux, Debian and Ruby"]
+
+{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/
+
+
+*resulting output:*
+
+tux.png 64x80 [link: local image]
+
+tux.png 64x80 "Gnu/Linux - a better way" [link: <http://www.sisudoc.org/>]
+
+GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
+and Ruby" [link: <http://www.sisudoc.org/>]
+
+ruby_logo.png 70x90 "Ruby" [link: <http://www.ruby-lang.org/en/>] [^8]
+
+*linked url footnote shortcut*
+
+{~^ [text to link] }http://url.org
+
+% maps to: { [text to link] }http://url.org ~{ http://url.org }~
+
+% which produces hyper-linked text within a document/paragraph, with an endnote providing the url for the text location used in the hyperlink
+
+
+text marker *~name
+
+
+note at a heading level the same is automatically achieved by providing names
+to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of
+auto-heading numbering, without further intervention.
+
+
+----------------------------------------
+
+LINK SHORTCUT FOR MULTIPLE VERSIONS OF A SISU DOCUMENT IN THE SAME DIRECTORY
+TREE
+..............................................................................
+
+*markup example:*
+
+!_ /{"Viral Spiral"}/, David Bollier
+
+{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst
+
+
+*/"Viral Spiral"/, David Bollier*
+
+"Viral Spiral", David Bollier [link: <http://niu/manual/en/manifest/viral_spiral.david_bollier.html>]
+ document manifest [link: <http://niu/manual/en/manifest/viral_spiral.david_bollier.html>]
+ html, segmented text [link: <http://niu/manual/en/html/viral_spiral.david_bollier/toc.html>]
+ html, scroll, document in one [link: <http://niu/manual/en/html/viral_spiral.david_bollier.html>]
+ epub [link: <http://niu/manual/en/epub/viral_spiral.david_bollier.epub>]
+ pdf, landscape [link: <http://niu/manual/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
+ pdf, portrait [link: <http://niu/manual/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
+ odf: odt, open document text [link: <http://niu/manual/en/odt/viral_spiral.david_bollier.odt>]
+ xhtml scroll [link: <http://niu/manual/en/xhtml/viral_spiral.david_bollier.xhtml>]
+ xml, sax [link: <http://niu/manual/en/xml_sax/viral_spiral.david_bollier.sax.xml>]
+ xml, dom [link: <http://niu/manual/en/xml_dom/viral_spiral.david_bollier.dom.xml>]
+ concordance [link: <http://niu/manual/en/html/viral_spiral.david_bollier/concordance.html>]
+ dcc, document content certificate (digests) [link: <http://niu/manual/en/digest/viral_spiral.david_bollier.hash_digest.txt>]
+ markup source text [link: <http://niu/manual/en/src/viral_spiral.david_bollier.sst>]
+ markup source (zipped) pod [link: <http://niu/manual/en/src/viral_spiral.david_bollier.sst.zip>]
+
+GROUPED TEXT
+............
+
+
+----------------------------------------
+
+TABLES
+......
+
+Tables may be prepared in two either of two forms
+
+*markup example:*
+
+table{ c3; 40; 30; 30;
+
+This is a table
+this would become column two of row one
+column three of row one is here
+
+And here begins another row
+column two of row two
+column three of row two, and so on
+
+}table
+
+
+*resulting output:*
+
+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』
+
+a second form may be easier to work with in cases where there is not much
+information in each column
+
+*markup example:*[^10]
+
+!_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
+
+{table~h 24; 12; 12; 12; 12; 12; 12;}
+ |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
+Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
+Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
+Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
+No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
+No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
+
+* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
+
+
+*resulting output:*
+
+*Table 3.1: Contributors to Wikipedia, January 2001 - June 2005*
+
+┆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.
+
+
+----------------------------------------
+
+POEM
+....
+
+*basic markup:*
+
+poem{
+
+ Your poem here
+
+}poem
+
+Each verse in a poem is given an object number.
+
+
+*markup example:*
+
+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
+
+
+*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."'
+
+
+----------------------------------------
+
+GROUP
+.....
+
+*basic markup:*
+
+group{
+
+ Your grouped text here
+
+}group
+
+A group is treated as an object and given a single object number.
+
+
+*markup example:*
+
+group{
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "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
+
+
+*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."'
+
+
+----------------------------------------
+
+CODE
+....
+
+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 *SiSU* markup. You cannot however use code
+tags to escape code tags. They are however used in the same way as group or
+poem tags.
+
+A code-block is treated as an object and given a single object number. [an
+option to number each line of code may be considered at some later time]
+
+*use of code tags instead of poem compared, resulting output:*
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "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."'
+
+
+From *SiSU* 2.7.7 on you can number codeblocks by placing a hash after the
+opening code tag # code{# # as demonstrated here:
+
+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."'
+
+ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
+.....................................................................
+
+
+----------------------------------------
+
+LINE-BREAKS
+...........
+
+To break a line within a "paragraph object", two backslashes \\
+with a space before and a space or newline after them
+may be used.
+
+To break a line within a "paragraph object",
+two backslashes \\ with a space before
+and a space or newline after them \\
+may be used.
+
+
+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).
+
+To draw a dividing line dividing paragraphs, see the section on page breaks.
+
+
+----------------------------------------
+
+PAGE BREAKS
+...........
+
+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:
+
+page new =\= or ╋ breaks the page, starts a new page.
+
+page break -\- or ┼ breaks a column, starts a new column, if using columns,
+else breaks the page, starts a new page.
+
+page break line across page -..- draws a dividing line, dividing paragraphs
+
+page break:
+
+-\\-
or
- rake base
-This makes use of Rake (by Jim Weirich) and the provided Rakefile
+<:pb>
-For a list of alternative actions you may type:
- rake help
- rake -T
-%% to use install (prapared with "Rant")
----------------
-(you may use the instructions above for rake substituting rant if rant is
-installed on your system, or you may use an independent installer created using
-rant as follows:)
+page (break) new:
-in the root directory of the unpacked SiSU as root type:
- ruby ./sisu-install
+=\\=
or
- ruby ./sisu-install base
-This makes use of Rant (by Stefan Lang) and the provided Rantfile. It has been
-configured to do post installation setup setup configuration and generation of
-first test file. Note however, that additional external package dependencies,
-such as tetex-extra are not taken care of for you.
+<:pn>
- further information:
- <http://make.rubyforge.org/>
- <http://rubyforge.org/frs/?group_id=615>
-Dependencies
---------------
-Once installed see 'man 8 sisu' for some information on additional programs
-that sisu makes use of, and that you may need or wish to install. (this will
-depend on such factors as whether you want to generate pdf, whether you will be
-using SiSU with or without a database, ...) 'man sisu_markup-samples' may also be of
-interest if the sisu-markup-samples package has also been installed.
-
-The information in man 8 may not be most up to date, and it is possible that
-more useful information can be gleaned from the following notes taken from the
-Debian control file (end edited), gives an idea of additional packages that
-SiSU can make use of if available, (the use/requirement of some of which are
-interdependent for specific actions by SiSU):
+page (break) line across page (dividing paragraphs):
-Package: sisu
-Architecture: all
-Depends: ruby (>= 1.8.2), libwebrick-ruby, unzip, zip
-Conflicts: vim-sisu, sisu-vim, sisu-remote
-Replaces: vim-sisu, sisu-vim
-Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, librmagick-ruby, trang,
-tidy, librexml-ruby, openssl, rsync, openssh-client | lsh-client, keychain,
-hyperestraier, kdissert, vim-addon-manager
-Suggests: rcs | cvs, lv, texinfo, pinfo
+-..-
-Package: sisu-complete
-Depends: ruby (>= 1.8.4), sisu, sisu-pdf, sisu-postgresql, sisu-sqlite
-Recommends: hyperestraier
-Package: sisu-pdf
-Architecture: all
-Depends: sisu, texlive-latex-base, texlive-fonts-recommended,
-texlive-latex-recommended, texlive-latex-extra
-Suggests: evince, xpdf
+BOOK INDEX
+..........
-Package: sisu-postgresql
-Depends: sisu, postgresql-8.1, libdbi-ruby, libdbm-ruby, libdbd-pg-ruby
-Suggests: pgaccess, libdbd-pgsql, postgresql-contrib-8.1
+To make an index append to paragraph the book index term relates to it, using
+an equal sign and curly braces.
-Package: sisu-sqlite
-Depends: sisu, sqlite, libdbi-ruby, libdbm-ruby, libdbd-sqlite-ruby
-Suggests: libdbd-sqlite
+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.
-Package: sisu-markup-samples
-Depends: sisu
+ Paragraph containing main term and sub-term.
+ ={Main term:sub-term}
-%% Quick start
----------------
-Most of the installation should be taken care of by the aptitude or rant
-install. (The rant install if run in full will also test run the generation of
-the first document).
-After installation of sisu-complete, move to the document samples directory
+The index syntax starts on a new line, but there should not be an empty line
+between paragraph and index markup.
- cd /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg
+The structure of the resulting index would be:
-and run
+ Main term, 1
+ sub-term, 1
- sisu -3 free_as_in_freedom.rms_and_free_software.sam_williams.sst
-[or the same:
- sisu -NhwpoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst
-]
+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.
-look at output results, see the "sisu_manifest" page created for the document
+ Paragraph containing main term, second term and sub-term.
+ ={first term; second term: sub-term}
-or to generate an online document move to a writable directory, as the file
-will be downloaded there and e.g.
-sisu -3 http://www.jus.uio.no/sisu/free_culture.lawrence_lessig/free_culture.lawrence_lessig.sst
+The structure of the resulting index would be:
-the database stuff is extra perhaps, the latex stuff could be considered extra
-perhaps but neither needs to be installed for most of sisu output to work
+ First term, 1,
+ Second term, 1,
+ sub-term, 1
-examine source document, vim has syntax support
-gvim free_as_in_freedom.rms_and_free_software.sam_williams.sst
+If multiple sub-terms appear under one paragraph, they are separated under the
+main term heading from each other by a pipe symbol.
-additional markup samples in
-<http://www.jus.uio.no/sisu/SiSU/2.html>
+ Paragraph containing main term, second term and sub-term.
+ ={Main term:
+ sub-term+2|second sub-term;
+ Another term
+ }
-For help
- man sisu
+ A paragraph that continues discussion of the first sub-term
-%% Configuration files
----------------
-The default configuration/setup is contained within the program and is altered
-by configuration settings in /etc/[sisu version]/sisurc.yml
-or in ~/.sisu/sisurc.yml
+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:
-* configuration file - a yaml file
- /etc/sisu/[sisu version]/sisurc.yml
- ~/.sisu/sisurc.yml
+ Main term, 1,
+ sub-term, 1-3,
+ second sub-term, 1,
+ Another term, 1
-* directory structure - setting up of output and working directory.
-* skins - changing the appearance of a project, directory or individual
-documents within ~/.sisu/skin
- ~/.sisu/skin/doc contains individual skins, with symbolic links from
- ~/.sisu/skin/dir if the contents of a directory are to take a particular
- document skin.
+COMPOSITE DOCUMENTS MARKUP
+--------------------------
-* additional software - eg. Tex and LaTeX (tetex, tetex-base, tetex-extra on
-Debian), Postgresql, [sqlite], trang, tidy, makeinfo, ... none of which are
-required for basic html or XML processing.
+It is possible to build a document by creating a master document that requires
+other documents. The documents required may be complete documents that could be
+generated independently, or they could be markup snippets, prepared so as to be
+easily available to be placed within another text. If the calling document is a
+master document (built from other documents), it should be named with the
+suffix *.ssm* Within this document you would provide information on the other
+documents that should be included within the text. These may be other documents
+that would be processed in a regular way, or markup bits prepared only for
+inclusion within a master document *.sst* regular markup file, or *.ssi*
+(insert/information) A secondary file of the composite document is built prior
+to processing with the same prefix and the suffix *._sst*
-* if you use Vim as editor there is a syntax highlighter and fold resource
-config file for SiSU. I hope more syntax highlighters follow.
+basic markup for importing a document into a master document
-There are post installation steps (which are really part of the overall
-installation)
+<< filename1.sst
-sisu -C in your marked up document directory, should do some auto-configuring
-provided you have the right permissions for the output directories. (and
-provided the output directories have already been specified if you are not
-using the defaults).
+<< filename2.ssi
-%% Use General Overview
----------------
-Documents are marked up in SiSU syntax and kept in an ordinary text editable
-file, named with the suffix .sst, or .ssm
-Marked up SiSU documents are usually kept in a sub-directory of your choosing
+The form described above should be relied on. Within the /Vim/ editor it
+results in the text thus linked becoming hyperlinked to the document it is
+calling in which is convenient for editing.
-%% Help
----------------
+SUBSTITUTIONS
+-------------
-interactive help described below, or man page:
+*markup example:*
- man sisu
+The current Debian is ${debian_stable} the next debian will be ${debian_testing}
- man 8 sisu
- 'man sisu_markup-samples' [if the sisu-markup-samples package is also installed]
+Configure substitution in _sisu/sisu_document_make
-%% Directory Structure
----------------
-Once installed, type:
- sisu -V
+@make:
+:substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*'
-%% Configuration File
----------------
-The defaults can be changed via SiSU's configure file sisurc.yml which the
-program expects to find in ./_sisu ~/.sisu or /etc/sisu (searched in that
-order, stopping on the first one found)
+*resulting output:*
-%% Markup
----------------
+The current *Debian* is *Wheezy* the next debian will be *Jessie*
-See man pages.
- man sisu
+Configure substitution in _sisu/sisu_document_make
- man 8 sisu
-Sample marked up document are provided with the download tarball in the
-directory:
- ./data/doc/sisu/v2/sisu_markup_samples/dfsg
+----------------------------------------
-These are installed on the system usually at:
- /usr/share/doc/sisu/v2/sisu_markup_samples/dfsg
-More markup samples are available in the package sisu-markup-samples
- <http://www.jus.uio.no/sisu/SiSU/download.html#sisu-markup-samples>
+----------------------------------------
-Many more are available online off:
- <http://www.jus.uio.no/sisu/SiSU/2.html>
-%% Additional Things
----------------
+ [1]: <http://packages.qa.debian.org/s/sisu.html>
-There is syntax support for some editors provided (together with a README file) in
+ [2]: from the *Debian* control file
- ./data/sisu/v2/conf/editor-syntax-etc
+ [*1]: square brackets
-usually installed to:
+ [*2]: square brackets
- /usr/share/sisu/v2/conf/editor-syntax-etc
+ [+1]: square brackets
-v1, v2 Changes
----------------
+ [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.
-See changelogs
+ [4]: files should be prepared using /UTF-8/ character encoding
-From a developer's perspective the substantive change between the two versions
-is to the middle layer, (the document abstraction, the intermediate document
-representation used in processing). Version 1 uses strings and relies on
-regular expressions to identify document objects, while Version 2 uses ruby
-objects. The version 1 approach whilst programming language neutral offers less
-control, and leads to complicated code; version 2 approach takes advantage of
-features within the ruby language suited to what the application does.
-Development is curently on version 2, version 1 is likely to remain for some
-time as a reference implementation.
+ [5]: a footnote or endnote
-%% Versions
+ [6]: self contained endnote marker & endnote in one
-* v1 sisu pretty mature in operation and syntax
-* v2 introduces new processing middle layer (document abstraction);
- markup same except for minor changes to document headers;
- epub output introduced
-* v3 introduces alternative (configurable) output structures
-* v4 retires what were referred to as sisu skins
+ [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required
-%% License
----------------
+ [**]: another unnumbered asterisk footnote/endnote
-License: GPL 3 or later see the copyright file in
+ [*3]: editors notes, numbered asterisk footnote/endnote series
- ./data/doc/sisu
+ [+2]: editors notes, numbered plus symbol footnote/endnote series
-usually installed to:
+ [7]: <http://www.sisudoc.org/>
- /usr/share/doc/sisu
+ [8]: <http://www.ruby-lang.org/en/>
-%% SiSU Standard
------------------
+ [10]: Table from the Wealth of Networks by Yochai Benkler
+
+ <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler>
+
+==============================================================================
+
+ Title: SiSU - README
+
+ Creator: Ralph Amissah
+
+ Rights: Copyright (C) Ralph Amissah 2014;\\ License: GPL 3 (part of SiSU
+ documentation)
+
+ Subject: ebook, epublishing, electronic book, electronic publishing,
+ electronic document, electronic citation, data structure,
+ citation systems, search
+
+ Publisher: SiSU http://www.jus.uio.no/sisu (this copy)
+
+ Date created: 2014-02-02
+
+ Date available: 2014-02-02
+
+ Date modified: 2014-02-02
+
+ Date: 2014-02-02
+
+ Sourcefile: README.ssm.sst
+
+ Filetype: SiSU text insert 5.0,
+
+ Source digest: SHA256(README.ssm.sst)=
+ 5927789066d1eb9cf0321946d46e3ce2a66414557038d5c745bb009233611dd8
+
+ Generated by: Generated by: SiSU 6.0.1 of 2014w05/2 (2014-02-04)
+
+ Ruby version: ruby 2.0.0p353 (2013-11-22) [i386-linux-gnu]
+
+ Document (ao) last generated: 2014-02-04 23:45:41 -0500
+
+==============================================================================
+
+
+plaintext (plain text):
+ http://niu/manual/en/txt/README.txt
+
+Other versions of this document:
-SiSU uses:
+manifest:
+ http://niu/manual/en/manifest/README.html
-* Standard SiSU markup syntax,
-* Standard SiSU meta-markup syntax, and the
-* Standard SiSU object citation numbering and system
+at:
+ http://niu/manual
-© Ralph Amissah 1997, current 2006.
-All Rights Reserved.
-* however note the License section
-CHANGELOG
- ./CHANGELOG
-and see
- <http://www.jus.uio.no/sisu/SiSU/changelog.html>
- <http://www.jus.uio.no/sisu/SiSU/changelog_markup_samples.html>
+* Generated by: SiSU 6.0.1 of 2014w05/2 (2014-02-04)
+* Ruby version: ruby 2.0.0p353 (2013-11-22) [i386-linux-gnu]
+* Last Generated on: 2014-02-04 23:45:43 -0500
+* SiSU http://www.sisudoc.org/
diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5
index e79f97ca..15e4ce0d 100644
--- a/data/doc/sisu/CHANGELOG_v5
+++ b/data/doc/sisu/CHANGELOG_v5
@@ -65,6 +65,7 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_5.3.1.orig.tar.xz
* documentation, manpage README etc.
* sisu manual directory moved
* sisu manual updated
+ * README & sisu.1 (manpage) updated
* removed html man pages (man2html)
%% 5.3.0.orig.tar.xz (2014-01-26:03/7)
diff --git a/data/doc/sisu/CHANGELOG_v6 b/data/doc/sisu/CHANGELOG_v6
index 23925664..4454c3e1 100644
--- a/data/doc/sisu/CHANGELOG_v6
+++ b/data/doc/sisu/CHANGELOG_v6
@@ -55,6 +55,7 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_6.0.1.orig.tar.xz
* documentation, manpage README etc.
* sisu manual directory moved
* sisu manual updated
+ * README & sisu.1 (manpage) updated
* removed html man pages (man2html)
%% 6.0.0.orig.tar.xz (2014-01-26:03/7)
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index a692a9f4..f6bb6b5b 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -1,4 +1,4 @@
-.TH "sisu" "1" "2013-11-27" "5.1.0" "SiSU"
+.TH "sisu" "1" "2014-02-05" "6.0.1" "SiSU"
.br
.SH NAME
.br
@@ -37,197 +37,68 @@ RALPH AMISSAH
.BR
-.B SiSU
-is a framework for document structuring, publishing (in multiple open standard
-formats) and search, comprising of: (a) a lightweight document structure and
-presentation markup syntax; and (b) an accompanying engine for generating
-standard document format outputs from documents prepared in sisu markup syntax,
-which is able to produce multiple standard outputs (including the population of
-sql databases) that (can) share a common numbering system for the citation of
-text within a document.
-
-.BR
-.B SiSU
-is developed under an open source, software libre license (
-.I GPLv3
-). Its use case for development is work with medium to large document sets and
-cope with evolving document formats/ representation technologies. Documents are
-prepared once, and generated as need be to update the technical presentation or
-add additional output formats. Various output formats (including search related
-output) share a common mechanism for cross-output-format citation.
-.BR
.B SiSU
-both defines a markup syntax and provides an engine that produces open
-standards format outputs from documents prepared with
+is a lightweight markup based document creation and publishing framework that
+is controlled from the command line. Prepare documents for
.B SiSU
-markup. From a single lightly prepared document sisu custom builds several
-standard output formats which share a common (text object) numbering system for
-citation of content within a document (that also has implications for search).
-The sisu engine works with an abstraction of the document's structure and
-content from which it is possible to generate different forms of representation
-of the document. Significantly
+using your text editor of choice, then use
.B SiSU
-markup is more sparse than html and outputs which include
-.I HTML,
-.I EPUB,
-.I ODT
-(Open Document Format text),
-.I LaTeX,
-landscape and portrait
-.I PDF,
-all of which can be added to and updated.
-.B SiSU
-is also able to populate
-.I SQL
-type databases at an object level, which means that searches can be made with
-that degree of granularity.
+to generate various output document formats.
.BR
-Source document preparation and output generation is a two step process: (i)
-document source is prepared, that is, marked up in sisu markup syntax and (ii)
-the desired output subsequently generated by running the sisu engine against
-document source. Output representations if updated (in the sisu engine) can be
-generated by re-running the engine against the prepared source. Using
-.B SiSU
-markup applied to a document,
+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
-custom builds (to take advantage of the strengths of different ways of
-representing documents) various standard open output formats including plain
-text,
+produces: plain-text,
.I HTML,
.I XHTML,
.I XML,
.I EPUB,
-.I ODT,
-.I LaTeX
-or
-.I PDF
-files, and populate an
+.I ODF:
+.I ODT
+(Opendocument),
+.I LaTeX,
+.I PDF,
+and populates an
.I SQL
-database with objects[^1] (equating generally to paragraph-sized chunks) so
-searches may be performed and matches returned with that degree of granularity
-( e.g. your search criteria is met by these documents and at these locations
-within each document). Document output formats share a common object numbering
-system for locating content. This is particularly suitable for "published"
-works (finalized texts as opposed to works that are frequently changed or
-updated) for which it provides a fixed means of reference of content.
+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
-In preparing a
-.B SiSU
-document you optionally provide semantic information related to the document in
-a document header, and in marking up the substantive text provide information
-on the structure of the document, primarily indicating heading levels and
-footnotes. You also provide information on basic text attributes where used.
-The rest is automatic, sisu from this information custom builds[^2] the
-different forms of output requested.
+Outputs share a common citation numbering system, associated with text objects
+and any semantic meta-data provided about the document.
.BR
-.B SiSU
-works with an abstraction of the document based on its structure which is
-comprised of its headings[^3] and objects[^4], which enables
-.B SiSU
-to represent the document in many different ways, and to take advantage of the
-strengths of different ways of presenting documents. The objects are numbered,
-and these numbers can be used to provide a common basis for citing material
-within a document across the different output format types. This is significant
-as page numbers are not well suited to the digital age, in web publishing,
-changing a browser's default font or using a different browser can mean that
-text will appear on a different page; and publishing in different formats,
-html, landscape and portrait pdf etc. again page numbers are not useful to cite
-text. Dealing with documents at an object level together with object numbering
-also has implications for search that
-.B SiSU
-is able to take advantage of.
-.BR
-One of the challenges of maintaining documents is to keep them in a format that
-allows use of them independently of proprietary platforms. Consider issues
-related to dealing with legacy proprietary formats today and what guarantee you
-have that old proprietary formats will remain (or can be read without
-proprietary software/equipment) in 15 years time, or the way the way in which
-html has evolved over its relatively short span of existence.
-.B SiSU
-provides the flexibility of producing documents in multiple non-proprietary
-open formats including
-.I HTML,
-.I EPUB,
-[^5]
-.I ODT,
-[^6]
-.I PDF
-[^7]
-.I ODF,
-[^8]. Whilst
.B SiSU
-relies on software, the markup is uncomplicated and minimalistic which
-guarantees that future engines can be written to run against it. It is also
-easily converted to other formats, which means documents prepared in
-.B SiSU
-can be migrated to other document formats. Further security is provided by the
-fact that the software itself,
-.B SiSU
-is available under
-.I GPLv3
-a licence that guarantees that the source code will always be open, and free as
-in libre, which means that that code base can be used, updated and further
-developed as required under the terms of its license. Another challenge is to
-keep up with a moving target.
-.B SiSU
-permits new forms of output to be added as they become important, (Open
-Document Format text was added in 2006 when it became an ISO standard for
-office applications and the archival of documents),
-.I EPUB
-was introduced in 2009; and allows the technical representations existing
-output to be updated (
-.I HTML
-has evolved and the related module has been updated repeatedly over the years,
-presumably when the World Wide Web Consortium (w3c) finalises
-.I HTML
-5 which is currently under development, the
-.I HTML
-module will again be updated allowing all existing documents to be regenerated
-as
-.I HTML
-5).
+also provides concordance files, document content certificates and manifests of
+generated output. Book indexes may be made.
.BR
-The document formats are written to the file-system and available for indexing
-by independent indexing tools, whether off the web like Google and Yahoo or on
-the site like Lucene and Hyperestraier.
+Some document markup samples are provided in the package sisu -markup-samples.
+Homepages:
-.BR
-.B SiSU
-also provides other features such as concordance files and document content
-certificates, and the working against an abstraction of document structure has
-further possibilities for the research and development of other document
-representations, the availability of objects is useful for example for topic
-maps and thesauri, together with the flexibility of
-.B SiSU
-offers great possibilities.
+* <http://www.sisudoc.org/>
-.BR
-.B SiSU
-is primarily for published works, which can take advantage of the citation
-system to reliably reference its documents.
-.B SiSU
-works well in a complementary manner with such collaborative technologies as
-Wikis, which can take advantage of and be used to discuss the substance of
-content prepared in
-.B SiSU.
-
-.BR
-<http://www.sisudoc.org/>
+* <http://www.jus.uio.no/sisu>
-.BR
-<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:
@@ -428,6 +299,9 @@ produces html output, the document in a single file (scroll.html) only. Compare
produces html output, segmented text with table of contents (toc.html and
index.html). Compare --html-scroll and --html
.TP
+.B --html-strict [filename/wildcard]
+produces html with --strict option. see --strict
+.TP
.B -I [filename/wildcard]
see --texinfo
.TP
@@ -498,6 +372,9 @@ see --exc-*
.B -o [filename/wildcard/url]
see --odt
.TP
+.B --ocn
+see --inc-ocn and --exc-ocn
+.TP
.B --odf [filename/wildcard/url]
see --odt
.TP
@@ -702,6 +579,10 @@ for sending). See the -S option without [filename/wildcard]. Alias -S
.B --source [filename/wildcard]
copies sisu markup file to output directory. Alias -s
.TP
+.B --strict
+together with --html, produces more w3c compliant html, for example not having
+purely numeric identifiers for text, the location object url#33 becomes url#o33
+.TP
.B -T [filename/wildcard (*.termsheet.rb)]
standard form document builder, preprocessing feature
.TP
@@ -2279,6 +2160,8 @@ 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